jevcore

jevcore

TypeSafe Jev for DeepSeek Harness and any other MCP host.

Jev is not a chat model. It answers typed questions — noul (yes/no), choice, score — and returns calibrated probabilities. It does not write prose, and asking it to is a category error. This project gives an agent exactly that surface, and nothing more.

Offline by default. Egress disclosed. Nothing default-on.

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

Three packages, one decision layer

Package · What it is · Use it when jevcore · The decisions. Imports nothing from DeepSeek Harness or Cordis. · You want Jev in a plain script, a service, or your own harness jevcore-dsh · The DSH plugin: one service, three tools, two opt-in gates · You are running DeepSeek Harness jevcore-mcp · The same three tools over MCP, with a stdio binary · Your host speaks MCP but is not DSH

The adapters are thin on purpose. packages/dsh is four files: it declares tool schemas and translates hook payloads. Everything decision-shaped — the primitives, the providers, the egress contract, the policy, the gates — lives in core, so a new adapter cannot drift from the guarantees the others make. One runtime requirement differs across the three: jevcore-dsh tracks the harness and needs Node ^22.19.0 || >=24.0.0, while jevcore and jevcore-mcp need >=20.

Why this exists

Between 2026-09-17 and 09-20, nineteen plugins appeared that wire Jev into DSH. Auditing their source found a consistent pattern: the module labelled *guard*, *gate*, or *warden* was also the module shipping prompts, tool arguments, and file contents to a third party, and the README generally did not say so. Several were enabled by default. One gate could be reconfigured by the model it was guarding.

This project is the same idea with those failure modes designed out:

Property · How it is guaranteed here No network call unless you ask for one · Default provider is an offline mock; the live path needs both provider: live and a resolved credential Every transmission named before it happens · One startup log line per feature: off or SENDS { fields } Gates register nothing when disabled · Verified by test, not by policy — a disabled gate adds no event listener at all The model cannot widen its own constraints · No tool exposes gate configuration A judge that cannot answer never means "allow" · Undecided resolves through explicit config, defaulting to ask

The egress contract

This is the part worth reading before installing.

Transmission is decided per feature, and every feature defaults to off. The plugin prints its own contract at load:

[jevcore] provider=mock  endpoint=none  egress=OFF  (no network calls will be made; every answer is synthetic)
[jevcore] ready - provider=mock - gates: safety=off context=off

With provider: live and every feature enabled, the same report becomes explicit about what leaves:

[jevcore] provider=live  endpoint=https://api.typesafe.ai  egress=ON
[jevcore]   SENDS  tool:jev_ask  { state<=16000c questions<=4000c }
[jevcore]   SENDS  tool:jev_rank  { state<=16000c questions<=4000c }
[jevcore]   SENDS  tool:jev_check  { state<=16000c questions<=4000c }
[jevcore]   SENDS  gate:safety  { state<=8000c questions<=2000c }
[jevcore]   SENDS  gate:context  { state<=6000c questions<=2000c }
[jevcore]   redaction is best-effort; it removes named fields and known secret shapes, and cannot
             recognise an unrecognised secret in free text

Feature · Off by default? · What it sends tool:jev_ask · runs when the model calls it · the arguments the model passed, after redaction tool:jev_rank · runs when the model calls it · the query plus every candidate tool:jev_check · runs when the model calls it · the claim and its evidence gate:safety · yes — explicit opt-in · the tool name, its arguments, the workspace root gate:context · yes — explicit opt-in · a large tool result the agent just received

The tools transmit only when the model chooses to call them, which is visible in the transcript. The gates would run on every matching tool call, which is not, so they are opt-in.

Redaction, and its honest limit

Before anything is sent, src/redact.ts runs two passes: values under sensitive field names (password, token, apiKey, authorization, …) are replaced wholesale, and secret-shaped strings that survive into free text are pattern-matched (Bearer …, sk-…, ts_live_…, AWS/GitHub/Google key shapes, JWTs, private-key headers, credentials in connection strings).

This is a mitigation, not a permission. A secret that sits under an unrecognised key name *and* does not match a known shape will pass through. If that possibility is unacceptable for your workload, do not enable the live provider.

Install

As a DeepSeek Harness plugin

dsh plugin --profile <profile> add jevcore-dsh

Or from a checkout:

dsh plugin --profile <profile> add /absolute/path/to/jevcore/packages/dsh

packages/dsh imports jevcore by name, so a checkout also needs core resolvable from the profile (add /absolute/path/to/jevcore/packages/core).

Then confirm the row activated — the plugin list should show jev as active, not failed — and check the startup report in the log.

As an MCP server

For a host that speaks MCP, the same three tools are available over stdio:

npx -y jevcore-mcp

To wire it into DeepSeek Harness specifically, install a configuration-only bundle whose patch inserts the harness's own MCP client:

- insert:
    - id: jev-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: jev
        transport: stdio
        command: npx
        args: ['-y', 'jevcore-mcp']
        env:
          TYPESAFE_API_KEY: '<the key>'
        failOnStartupError: true

The env map is not optional: DSH strips every credential-shaped name — anything containing KEY, PASSWORD, SECRET or TOKEN, in any case — from the environment it hands a spawned server, then merges this map back in afterwards. A key exported in your shell never arrives, and the server stays on the offline mock without reporting an error.

The provider is chosen from the environment:

Variable · Effect TYPESAFE_API_KEY · Selects the TypeSafe route when present OPENROUTER_API_KEY · Selects the OpenRouter route when present and no TypeSafe key is set JEV_PROVIDER · mock, live, or openrouter — overrides the heuristic above TYPESAFE_MODEL / OPENROUTER_MODEL · Model id for the selected route TYPESAFE_BASE_URL / OPENROUTER_BASE_URL · API root for the selected route

With neither key it stays on the offline mock. Unlike the plugin, the MCP server resolves its credential once at startup, so a missing key with JEV_PROVIDER=live is a startup error rather than a per-call surprise.

Its egress report goes to stderr, never stdout — on a stdio transport stdout is the protocol channel, and a stray line there would corrupt the stream.

Going live

There are two routes to Jev. Both call the same models and both return the same typed answers; they differ in who holds your credential and whose servers see your state.

TypeSafe directly — use this if you have a key from console.typesafe.ai:

- insert:
    - id: jev
      name: 'jevcore-dsh'
      config:
        provider: live
        apiKeyRef: TYPESAFE_API_KEY   # a reference, never the key
        model: jev-latest

Through OpenRouter — use this if a TypeSafe key is impractical and you already have an OpenRouter key. OpenRouter serves the System One models at the same POST /v1/systemone path TypeSafe does, one level below its own API root, so this is the documented route to Jev rather than an approximation of it:

- insert:
    - id: jev
      name: 'jevcore-dsh'
      config:
        provider: openrouter
        openRouterApiKeyRef: OPENROUTER_API_KEY
        model: jev-latest              # a bare `jev-*` id, or `typesafe/jev-1.13`

The route is reached by pointing the official @typesafe-ai/sdk at https://openrouter.ai/api with your OpenRouter key — OpenRouter's own documented integration, so there is no second client to keep in step.

Two things to know about the OpenRouter route:

• Your state goes to OpenRouter, not to TypeSafe. A different third party

with different retention and logging. The startup report names the endpoint for exactly this reason — read it rather than inferring the destination from the provider's name.

• It returns a cost, which TypeSafe's own route does not, so usage.costUsd

is populated here and absent there.

The model id must be a System One one. jev-latest bare is the default and needs no prefix; typesafe/ is accepted on a versioned id such as typesafe/jev-1.13, but not on the moving tag — typesafe/jev-latest is not accepted by the route. Any other id would be routed to a chat model, which answers with prose this plugin cannot interpret as a decision, so it is refused before the call rather than misread after it.

Either way the credential is resolved through DSH's credential service first, then the environment variable of that name. It is read per call, so a key added while the process is running is picked up. It is never logged, never returned from a tool, and never written to configuration. Each route has its own reference (apiKeyRef and openRouterApiKeyRef) so the two cannot accidentally share a key.

@typesafe-ai/sdk is the only optional dependency; the plugin loads and runs offline without either, and only needs the one for the route you choose.

Configuration

Key · Default · Meaning provider · mock · mock (offline, deterministic, synthetic), live (TypeSafe), or openrouter apiKeyRef · TYPESAFE_API_KEY · Credential reference for the live route openRouterApiKeyRef · OPENROUTER_API_KEY · Credential reference for the openrouter route baseURL · https://api.typesafe.ai · API root for the live route. Non-HTTPS is refused except on loopback openRouterBaseURL · https://openrouter.ai/api · API root for the openrouter route. Same rule model · jev-latest · Sent with every request. On the OpenRouter route the bare default works; typesafe/ needs a versioned id such as typesafe/jev-1.13, and typesafe/jev-latest is not accepted logLevel · warn · silent \ · warn \ · info \ · debug minConfidence · 0.7 · Below this, an answer is not acted on minProbability · 0.6 · Below this, a decision is not acted on maxStateChars · per feature · Replaces the state cap for every feature. 0 means "keep the declared cap" gates.safety · false · Judge tool calls before dispatch gates.context · false · Withhold large, uninformative tool results

The declared state caps are 16,000 characters for the three tools and 8,000 / 6,000 for the safety and context gates. maxStateChars replaces all of them, and the startup report shows the effective value rather than the declared one, so what it prints is what is enforced.

Gates accept a bare boolean (safety: false) or an object with onUndecided: ask (default), allow, or deny.

ask is a question, so it needs something to ask. A deployment that composes no approval service cannot escalate to a human, and DeepSeek Harness then refuses the call instead of running it: every tool the safety gate matches is refused, which an operator experiences as the plugin having broken shell commands. docs/approval.md has the mechanism, and the plugin README covers the deployment view.

An unknown value is rejected at load with a message naming the key, rather than being silently ignored — a config typo should not quietly change the privacy posture.

Using it

From another plugin, with no model in the loop

The service is the primary surface. This is the point of a decision model: a routing or gating decision should not cost a model round-trip.

const jev = ctx.get('jev')
const result = await jev.ask({
  feature: 'tool:jev_ask',
  state: { ticket: 'I was charged twice.' },
  questions: {
    urgent: { type: 'noul', instructions: 'Does this convey urgency?' },
    team: {
      type: 'choice',
      instructions: 'Which team should handle this?',
      criteria: { billing: 'Payments, invoices, refunds', technical: 'Bugs, outages' },
    },
  },
})

result.answers carries probabilities and confidence. Deciding what to do with them is your code's job — see src/policy.ts for a worked example with an explicit confidence floor, where an unsure answer produces ask rather than allow.

From the model

Three tools, deliberately few and orthogonal:

• `jev_ask` — a batch of typed questions over one state.
• `jev_rank` — score and sort candidates against one criterion, one question per candidate in a

single round-trip. The probabilities are independent per-candidate judgments, not a distribution.

• `jev_check` — does this evidence support this claim? Returns supported, contradicted,

conflicted, insufficient, undecided, or unknown. Contradiction outranks support, because evidence that both supports and refutes is a conflict, not a weak yes.

A bundled skill

The plugin registers a skill, typesafe-ai-dsh, teaching an agent when a Jev judgment is the right tool and when it is a category error. It is registered through the skill registry rather than shipped as a directory for a provider to scan, so it needs no dependency on where a profile keeps its skills and it disappears cleanly when the plugin is removed.

The body lives in skills/typesafe-ai-dsh/SKILL.md and is read at load rather than embedded, so the file a human edits is the file that ships. A test asserts the two cannot drift.

The registry is declared as an optional dependency: a profile that does not compose the skill subsystem still gets the service and the three tools, with a warning that the skill was skipped.

The mock provider