typesafe-mcp

The Jev decision adapter for coding agents: a portable MCP tool that turns agent state plus typed questions into Jev decisions — probabilities, choices, scores — that code can branch on. Jev is a decision primitive, not another coding agent; hosts keep reasoning, editing, and execution.

Language

System One: TypeSafe's class of decision models: state plus typed questions in, structured answers and probabilities out. Jev is the first. Avoid: LLM, chatbot, agent

Jev: The TypeSafe System One decision model the evaluate tool calls; returns typed judgments with probabilities, not text. Avoid: the model, LLM

State: The evidence a request judges — a string, JSON object, or array of text. Facts live here; judgments live in questions. Avoid: prompt, document, context window

Instructions: The question text (string, object, or array) sent to Jev. Question IDs are not. Avoid: prompt

Criteria: The answer space: choice option map, score level array, or optional noul {true, false}. Avoid: enum, labels, rubric (unless talking about score levels)

Confidence: A 0–1 summary of how peaked a choice or score distribution is. Noul has none; its value is already a probability. Avoid: probability (different), certainty

Jev semantics: What the evaluate tool means — question types, criteria shapes, the 0-indexed score legend, defaults, and the prose describing them. One canonical owner in the MCP layer; adapters translate representation but never author descriptions, defaults, or behavioral meaning. Avoid: tool config, prompt, plugin settings

Canonical surface: The MCP tool contract that agents program against; the single definition of the tool's schema, descriptions, and defaults. Avoid: API, plugin interface

Adapter: A host integration (Claude Code, Codex, Claude Desktop, pi, OMP, PyThinker, any MCP-capable CLI or agent) that renders or registers the canonical surface. Adapters own transport and registration only. A registration adapter owns the full transaction for its host — detection, CLI protocol, rollback, legacy cleanup — while the setup driver owns orchestration and reporting. Automated setup covers Claude Code, Codex, Claude Desktop, and stock pi; OMP, PyThinker, and other MCP clients register the same evaluate mcp stdio binary by hand. Product-owned semantics are generated into adapters; adapter-owned protocol mechanics stay local and are pinned by cross-boundary integration tests — the ownership split is ADR-002 (docs/ADR-002-adapter-owned-protocol-mechanics.md). Avoid: client (overloaded), connector

Route: Which endpoint serves Jev for a given run: the TypeSafe API directly, or OpenRouter's Decisions endpoint. TypeSafe wins when both keys are set. A config concept, not a code seam: route selection lives inside newClientFromEnv, and every production caller gets a fully constructed Client or the canonical configuration error. Avoid: provider, backend

Evals

Rep: One repetition of one scenario: the actions the model took, keyed by scenario and rep index. The unit of observation. Avoid: trial, sample, attempt

Run record: The durable artifact of one selection run under evals/results/ — run metadata, every rep, and the cases, metrics, and gate derived from them. One format owner (evals/internal/runrecord); regradable from its reps alone (ADR-003). Avoid: result file, report, log

Host policy: The pure, versioned function that turns typed answers into a branch — allow, reject, ask user, escalate, route, execute. Owned by the host or, in a benchmark, by the harness as a pre-registered rule. Its output is derived from persisted answers, never stored as truth, and it never lives in the MCP server (ADR-004 §3). Avoid: decide(), threshold (a policy may use several), guardrail (that is a recipe)

Recipe: A documented use of evaluate: state contract, questions, interpretation, host policy. The questions are the file under examples/. A recipe is never a tool. Avoid: example (the JSON only), template, workflow

Frozen run: A completed agent run captured once by the judge capture harness — task, trace, final answer, evidence — redacted, content-hashed, and never edited; every judge arm sees the same one (ADR-001 A2.2). Avoid: transcript, replay

Trace: The ordered tool events inside a frozen run: tool, arguments, output, exit status. Nothing else in this repo is called a trace. Avoid: log, spans

Projection: The deterministic, versioned reduction of a frozen run to a state that fits the budget. Code, not Jev. Avoid: summary, compaction (that is a Jev keep/drop use case)

Oracle: Ground truth for a benchmark — a task's deterministic check, or a label two people reached independently and then adjudicated. Committed before any judged output exists; the runner refuses uncommitted labels. Avoid: expected output, gold (unqualified)

Question types

Noul: A yes/no proposition; returns a probability, not prose. Avoid: boolean question

Choice: One option from a defined map; returns a distribution over options.

Score: A position on an ordered scale of levels; 0-indexed, with a legend and per-level probabilities. Avoid: rating, ranking