jev-gateway 0.1.0

package/dist/decide.js

@@ -0,0 +1,149 @@
+import { argKey, buildQuestions, buildShortlistQuestions, MAX_TOOLS, NEEDS_TOOL_KEY, NO_TOOL, NONE_OF_THESE, shardKey, SHORTLIST_PER_SHARD, statedKey, TOOL_KEY, } from "./questions.js";
+import { buildState } from "./state.js";
+/** Why a request is not Jev's to decide, or undefined when it is. */
+function skipReason(input) {
+    if (input.turns.length === 0)
+        return "no_messages";
+    if (input.tools.length === 0)
+        return "no_tools";
+    if (input.tools.length > MAX_TOOLS * 255)
+        return "too_many_tools";
+    if (new Set(input.tools.map((tool) => tool.name)).size !== input.tools.length)
+        return "duplicate_tool_names";
+    if (input.tools.some((tool) => tool.name === NO_TOOL))
+        return "reserved_tool_name";
+    if (input.toolChoice === "decided")
+        return "tool_choice_already_decided";
+    return undefined;
+}
+/** Fill every argument from Jev's answers; the weakest judgement bounds the whole call. */
+function resolveArgs(plan, toolIndex, answers, minCertainty) {
+    const args = {};
+    let certainty = 1;
+    for (const param of plan.closedParams ?? []) {
+        if (param.kind === "const") {
+            if (param.required)
+                args[param.name] = param.value;
+            continue;
+        }
+        if (!param.required) {
+            const stated = answers[statedKey(toolIndex, param.name)];
+            if (stated?.type !== "noul")
+                return undefined;
+            certainty = Math.min(certainty, Math.max(stated.noul, 1 - stated.noul));
+            if (stated.noul < 0.5)
+                continue;
+        }
+        const answer = answers[argKey(toolIndex, param.name)];
+        if (param.kind === "boolean" && answer?.type === "noul") {
+            args[param.name] = answer.noul >= 0.5;
+            certainty = Math.min(certainty, Math.max(answer.noul, 1 - answer.noul));
+        }
+        else if (param.kind === "enum" && answer?.type === "choice" && param.values.has(answer.choice)) {
+            args[param.name] = param.values.get(answer.choice);
+            certainty = Math.min(certainty, answer.confidence);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return certainty >= minCertainty ? { args, certainty } : undefined;
+}
+/** The strongest few tools of every shard, ranked in a single Jev call. */
+async function shortlist(tools, state, config, askJev) {
+    const { questions, shards } = buildShortlistQuestions(tools);
+    const result = await askJev({ state, questions, model: config.jevModel });
+    const kept = shards.flatMap((shard, index) => {
+        const answer = result.answers[shardKey(index)];
+        if (answer?.type !== "choice")
+            return [];
+        const ranked = Object.entries(answer.probabilities)
+            .filter(([name]) => name !== NONE_OF_THESE)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, SHORTLIST_PER_SHARD)
+            .map(([name]) => name);
+        return shard.filter((tool) => ranked.includes(tool.name));
+    });
+    return { tools: kept, inputTokens: result.usage.input_tokens };
+}
+export async function decide(input, config, askJev) {
+    const skip = skipReason(input);
+    if (skip)
+        return { mode: "passthrough", reason: skip };
+    const startedAt = performance.now();
+    const state = buildState(input, config);
+    let tools = input.tools;
+    let shortlistTokens = 0;
+    let result;
+    let plans;
+    try {
+        if (tools.length > MAX_TOOLS) {
+            ({ tools, inputTokens: shortlistTokens } = await shortlist(tools, state, config, askJev));
+            if (tools.length === 0)
+                return { mode: "passthrough", reason: "jev_unexpected_answer" };
+        }
+        const built = buildQuestions(tools, {
+            allowNone: input.toolChoice !== "required",
+            withArgs: config.directCalls,
+        });
+        plans = built.plans;
+        result = await askJev({ state, questions: built.questions, model: config.jevModel });
+    }
+    catch (error) {
+        // Fail open: a Jev outage must never take the gateway down with it.
+        return { mode: "passthrough", reason: `jev_error: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const picked = result.answers[TOOL_KEY];
+    const needs = result.answers[NEEDS_TOOL_KEY];
+    if (picked?.type !== "choice" || needs?.type !== "noul") {
+        return { mode: "passthrough", reason: "jev_unexpected_answer" };
+    }
+    const jev = {
+        choice: picked.choice,
+        confidence: picked.confidence,
+        needsTool: needs.noul,
+        topProbabilities: Object.fromEntries(Object.entries(picked.probabilities)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 3)),
+        inputTokens: result.usage.input_tokens + shortlistTokens,
+        latencyMs: Math.round(performance.now() - startedAt),
+        ...(tools === input.tools ? {} : { shortlist: tools.map((tool) => tool.name) }),
+    };
+    if (picked.confidence < config.minConfidence)
+        return { mode: "passthrough", reason: "low_confidence", jev };
+    // Two independent questions must agree before the router overrides the LLM.
+    const wantsTool = picked.choice !== NO_TOOL;
+    if (wantsTool ? needs.noul < 0.3 : needs.noul > 0.7) {
+        return { mode: "passthrough", reason: "jev_answers_disagree", jev };
+    }
+    if (!wantsTool) {
+        // A hint can suggest a tool; suggesting silence would only risk ending an agent's turn early.
+        return config.onNone === "force_none" && input.steer !== "hint"
+            ? { mode: "none", confidence: picked.confidence, jev }
+            : { mode: "passthrough", reason: "no_tool_needed", jev };
+    }
+    const toolIndex = plans.findIndex((plan) => plan.name === picked.choice);
+    const plan = plans[toolIndex];
+    const tool = tools[toolIndex];
+    if (!plan || !tool)
+        return { mode: "passthrough", reason: "jev_unknown_tool", jev };
+    // Provider-run tools can't be forced by name; knowing Jev wants one is still worth logging.
+    if (tool.kind === "hosted")
+        return { mode: "passthrough", reason: "hosted_tool_selected", jev };
+    // Neither can namespaced ones: backends reject both `tool_choice.namespace` and the bare name.
+    if (tool.namespace)
+        return { mode: "passthrough", reason: "namespaced_tool_selected", jev };
+    const resolved = plan.closedParams && resolveArgs(plan, toolIndex, result.answers, config.argMinCertainty);
+    if (resolved) {
+        return {
+            mode: "direct",
+            tool: plan.name,
+            args: resolved.args,
+            confidence: Math.min(picked.confidence, resolved.certainty),
+            jev,
+        };
+    }
+    if (input.steer === "hint")
+        return { mode: "hint", tool: plan.name, confidence: picked.confidence, jev };
+    return { mode: "forced", tool: plan.name, kind: tool.kind, confidence: picked.confidence, jev };
+}

package/dist/index.js

@@ -0,0 +1,21 @@
+import { serve } from "@hono/node-server";
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { createApp } from "./app.js";
+import { loadConfig } from "./config.js";
+import { createDump } from "./debug.js";
+const config = loadConfig();
+// Reads TYPESAFE_API_KEY. One fast retry only: past that, failing open to the LLM is quicker.
+const jev = new TypeSafeClient({
+    defaultModel: config.jevModel,
+    timeout: config.jevTimeoutMs,
+    retry: { maxRetries: 1, backoffInitialMs: 100 },
+});
+const app = createApp({
+    config,
+    askJev: (request) => jev.systemOne(request),
+    dump: createDump(config.debugDumpDir),
+    log: (entry) => console.log(JSON.stringify({ time: new Date().toISOString(), ...entry })),
+});
+serve({ fetch: app.fetch, port: config.port }, ({ port }) => {
+    console.log(`jev-gateway listening on http://localhost:${port} → ${config.upstreamBaseUrl} (jev: ${config.jevModel})`);
+});

package/dist/questions.js

@@ -0,0 +1,147 @@
+import { truncate } from "./state.js";
+/** Choice label meaning "reply in text, call nothing". */
+export const NO_TOOL = "no_tool_needed";
+/** Choice label a shard uses to say "the right tool is not in this group". */
+export const NONE_OF_THESE = "none_of_these";
+/**
+ * Most tools one tool question may offer. A Choice accepts 255 options, but state plus the longest
+ * question must also fit Jev's 32k-token window, and below ~400 characters a description stops
+ * telling similar tools apart — so big rosters (Claude Code sends ~280) are shortlisted first.
+ */
+export const MAX_TOOLS = 120;
+export const SHORTLIST_PER_SHARD = 3;
+/** Cap on speculative argument questions fanned out in the same Jev call. */
+const MAX_ARG_QUESTIONS = 96;
+const MAX_DESCRIPTION_CHARS = 1024;
+/** Characters one tool question may spend on descriptions (~12k tokens). */
+const QUESTION_CHAR_BUDGET = 48_000;
+export const TOOL_KEY = "tool";
+export const NEEDS_TOOL_KEY = "needs_tool";
+function closedParam(name, schema, required) {
+    if ("const" in schema)
+        return { name, required, kind: "const", value: schema.const };
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        if (schema.enum.length === 1)
+            return { name, required, kind: "const", value: schema.enum[0] };
+        const values = new Map();
+        for (const value of schema.enum) {
+            if (value !== null && typeof value === "object")
+                return undefined;
+            values.set(String(value), value);
+        }
+        // Labels are what Jev sees; colliding labels ("1" vs 1) can't be mapped back.
+        if (values.size !== schema.enum.length || values.size > 255)
+            return undefined;
+        return { name, required, kind: "enum", description: schema.description, values };
+    }
+    if (schema.type === "boolean")
+        return { name, required, kind: "boolean", description: schema.description };
+    return undefined;
+}
+export function planTool(tool) {
+    const schema = tool.parameters;
+    // Only function tools take JSON arguments, and without a recognizable object schema
+    // there is nothing safe to infer about them.
+    if (tool.kind !== "function")
+        return { name: tool.name };
+    if (schema && schema.type !== undefined && schema.type !== "object")
+        return { name: tool.name };
+    const required = new Set(schema?.required ?? []);
+    const closedParams = [];
+    for (const [name, property] of Object.entries(schema?.properties ?? {})) {
+        const param = closedParam(name, property, required.has(name));
+        if (!param)
+            return { name: tool.name };
+        closedParams.push(param);
+    }
+    return { name: tool.name, closedParams };
+}
+export const argKey = (toolIndex, param) => `arg:${toolIndex}:${param}`;
+export const statedKey = (toolIndex, param) => `stated:${toolIndex}:${param}`;
+function toolCriteria(tools) {
+    const limit = Math.min(MAX_DESCRIPTION_CHARS, Math.floor(QUESTION_CHAR_BUDGET / tools.length));
+    const criteria = {};
+    for (const tool of tools) {
+        const params = Object.keys(tool.parameters?.properties ?? {});
+        // Descriptions lead with what the tool is for; the tail is usage detail Jev doesn't need.
+        const description = tool.description?.trim().slice(0, limit);
+        criteria[tool.name] = description || (params.length ? `Parameters: ${params.join(", ")}` : null);
+    }
+    return criteria;
+}
+export const shardKey = (index) => `shard:${index}`;
+/**
+ * First pass over a roster too big for one question: every shard is ranked in the same Jev call,
+ * and the best few of each go on to the real decision — ranking wide, then judging a shortlist.
+ */
+export function buildShortlistQuestions(tools) {
+    const shardCount = Math.ceil(tools.length / MAX_TOOLS);
+    const size = Math.ceil(tools.length / shardCount);
+    const shards = Array.from({ length: shardCount }, (_, index) => tools.slice(index * size, (index + 1) * size));
+    const questions = {};
+    shards.forEach((shard, index) => {
+        questions[shardKey(index)] = {
+            type: "choice",
+            instructions: "Given the conversation, which of these tools would best advance the user's latest request " +
+                "if the assistant called it next?",
+            criteria: { ...toolCriteria(shard), [NONE_OF_THESE]: "None of the tools in this list fits the next step." },
+        };
+    });
+    return { questions, shards };
+}
+/**
+ * One Jev request decides everything: which tool (if any), whether a tool is needed at all,
+ * and — speculatively, for every tool Jev could fully answer — each closed-set argument.
+ * Extra questions barely change latency, so code picks the relevant answers afterwards.
+ */
+export function buildQuestions(tools, options) {
+    const plans = tools.map(planTool);
+    const criteria = toolCriteria(tools);
+    if (options.allowNone) {
+        criteria[NO_TOOL] =
+            "No tool call is needed right now: the assistant should reply to the user in plain text " +
+                "(answer directly, ask a clarifying question, or report results that tools already returned).";
+    }
+    const questions = {
+        [TOOL_KEY]: {
+            type: "choice",
+            instructions: "Given the conversation, what should the assistant do next? " +
+                "Pick the single tool whose call best advances the user's latest request.",
+            criteria,
+        },
+        [NEEDS_TOOL_KEY]: {
+            type: "noul",
+            instructions: "Does the assistant need to call one of its tools now, rather than reply to the user in plain text?",
+        },
+    };
+    if (!options.withArgs)
+        return { questions, plans };
+    let argQuestions = 0;
+    plans.forEach((plan, toolIndex) => {
+        const asked = plan.closedParams?.filter((param) => param.kind !== "const") ?? [];
+        const cost = asked.reduce((sum, param) => sum + (param.required ? 1 : 2), 0);
+        if (!plan.closedParams || argQuestions + cost > MAX_ARG_QUESTIONS) {
+            delete plan.closedParams;
+            return;
+        }
+        argQuestions += cost;
+        for (const param of asked) {
+            const about = `the "${param.name}" argument of the tool "${plan.name}"${param.description ? ` (${truncate(param.description, MAX_DESCRIPTION_CHARS)})` : ""}`;
+            questions[argKey(toolIndex, param.name)] =
+                param.kind === "boolean"
+                    ? { type: "noul", instructions: `If the assistant calls "${plan.name}" now, should ${about} be true?` }
+                    : {
+                        type: "choice",
+                        instructions: `If the assistant calls "${plan.name}" now, what value should ${about} have?`,
+                        criteria: Object.fromEntries([...param.values.keys()].map((label) => [label, null])),
+                    };
+            if (!param.required) {
+                questions[statedKey(toolIndex, param.name)] = {
+                    type: "noul",
+                    instructions: `Does the conversation state or clearly imply a value for ${about}?`,
+                };
+            }
+        }
+    });
+    return { questions, plans };
+}

package/dist/state.js

@@ -0,0 +1,43 @@
+/** Keep the head and tail of long text; the middle is what matters least for routing. */
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    const marker = " …[truncated]… ";
+    const keep = Math.max(0, max - marker.length);
+    const head = Math.ceil(keep * 0.6);
+    return text.slice(0, head) + marker + text.slice(text.length - (keep - head));
+}
+/** Jev is text-only: flatten content parts and leave a placeholder for anything else. */
+export function textOf(content) {
+    if (content == null)
+        return "";
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return JSON.stringify(content);
+    return content
+        .map((part) => typeof part?.text === "string" ? part.text : `[${part?.type ?? "attachment"}]`)
+        .join("\n");
+}
+/**
+ * Jev state: the content the questions are asked about.
+ * The newest turns are kept when the conversation exceeds the state budget.
+ */
+export function buildState(input, limits) {
+    const systemText = truncate(input.system, limits.maxMessageChars);
+    let budget = limits.maxStateChars - systemText.length;
+    const conversation = [];
+    for (let i = input.turns.length - 1; i >= 0; i--) {
+        const turn = input.turns[i];
+        budget -= JSON.stringify(turn).length;
+        if (budget < 0 && conversation.length > 0)
+            break;
+        conversation.unshift(turn);
+    }
+    const omitted = input.turns.length - conversation.length;
+    return {
+        ...(systemText ? { assistant_instructions: systemText } : {}),
+        ...(omitted ? { earlier_turns_omitted: omitted } : {}),
+        conversation,
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** The subset of the OpenAI Chat Completions shapes the router needs to understand. */
+export {};

package/dist/upstream.js

@@ -0,0 +1,71 @@
+// Hop-by-hop and length/encoding headers must not cross the proxy: fetch re-frames
+// (and transparently decompresses) bodies, so the originals would be wrong.
+const DROPPED_REQUEST_HEADERS = new Set(["host", "connection", "content-length", "accept-encoding", "transfer-encoding"]);
+const DROPPED_RESPONSE_HEADERS = new Set(["connection", "content-length", "content-encoding", "transfer-encoding"]);
+/**
+ * A client that hangs up mid-stream aborts the upstream read, which surfaces as a stream error
+ * and gets logged as one by the HTTP server. It isn't: Codex closes every SSE stream as soon as
+ * it has `response.completed`. End the body quietly instead; real upstream errors still propagate.
+ */
+function quietOnClientAbort(body, signal) {
+    if (!body)
+        return body;
+    const reader = body.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    controller.close();
+                else
+                    controller.error(error);
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+}
+/** Proxy a gateway request (`/v1/...`) to the upstream API, streaming the response back. */
+export async function forward(incoming, config, fetchImpl, options = {}) {
+    const url = new URL(incoming.url);
+    const target = config.upstreamBaseUrl + url.pathname.replace(/^\/v1/, "") + url.search;
+    const headers = new Headers();
+    incoming.headers.forEach((value, name) => {
+        if (!DROPPED_REQUEST_HEADERS.has(name) && !name.startsWith("x-jev-"))
+            headers.set(name, value);
+    });
+    if (config.upstreamApiKey)
+        headers.set("authorization", `Bearer ${config.upstreamApiKey}`);
+    if (typeof options.body === "string")
+        headers.delete("content-encoding");
+    const hasBody = incoming.method !== "GET" && incoming.method !== "HEAD";
+    const init = { method: incoming.method, headers, signal: incoming.signal };
+    if (options.body !== undefined) {
+        init.body = options.body;
+    }
+    else if (hasBody && incoming.body) {
+        init.body = incoming.body;
+        init.duplex = "half";
+    }
+    let upstream;
+    try {
+        upstream = await fetchImpl(target, init);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return Response.json({ error: { message: `jev-gateway could not reach upstream: ${message}`, type: "upstream_unreachable" } }, { status: 502, headers: options.responseHeaders });
+    }
+    const responseHeaders = new Headers();
+    upstream.headers.forEach((value, name) => {
+        if (!DROPPED_RESPONSE_HEADERS.has(name))
+            responseHeaders.set(name, value);
+    });
+    for (const [name, value] of Object.entries(options.responseHeaders ?? {}))
+        responseHeaders.set(name, value);
+    return new Response(quietOnClientAbort(upstream.body, incoming.signal), { status: upstream.status, headers: responseHeaders });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "jev-gateway",
+  "version": "0.1.0",
+  "description": "LLM gateway that hands tool-selection decisions to TypeSafe's Jev model \u2014 with launchers for Codex and Claude Code",
+  "keywords": [
+    "llm",
+    "gateway",
+    "proxy",
+    "jev",
+    "typesafe",
+    "tool-calling",
+    "codex",
+    "claude-code",
+    "openai",
+    "anthropic"
+  ],
+  "license": "MIT",
+  "author": "Vinicius Lana",
+  "type": "module",
+  "engines": {
+    "node": ">=22.9"
+  },
+  "bin": {
+    "jev-codex": "bin/jev-codex.mjs",
+    "jev-claude": "bin/jev-claude.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "scripts/mock-jev.mjs",
+    ".env.example"
+  ],
+  "scripts": {
+    "dev": "tsx watch --env-file-if-exists=.env src/index.ts",
+    "start": "node --env-file-if-exists=.env dist/index.js",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "codex": "node bin/jev-codex.mjs",
+    "claude": "node bin/jev-claude.mjs",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "hono": "^4.13.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1",
+    "tsx": "^4.23.13"
+  }
+}

package/scripts/mock-jev.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// mock-jev: a local stand-in for TypeSafe's `POST /v1/systemone`, for driving the router
+// end to end (real client, real upstream) without a TypeSafe key. The SDK honours
+// TYPESAFE_BASE_URL, so:
+//
+//   MOCK_JEV_SCRIPT=exec_command,no_tool_needed node scripts/mock-jev.mjs &
+//   TYPESAFE_BASE_URL=http://127.0.0.1:8799 TYPESAFE_API_KEY=mock jev-codex exec "…"
+//
+// It answers whatever question keys it is sent (see src/questions.ts): scripted for `tool`,
+// consistent for `needs_tool`, deliberately unsure for arguments.
+import { createServer } from "node:http";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PORT = Number(process.env.MOCK_JEV_PORT ?? 8799);
+const NO_TOOL = "no_tool_needed";
+// One `tool` answer per request, in order; the last one repeats. An agent loop needs this:
+// "always pick the shell" never lets the turn end.
+const SCRIPT = (process.env.MOCK_JEV_SCRIPT ?? NO_TOOL).split(",").map((name) => name.trim()).filter(Boolean);
+const CONFIDENCE = Number(process.env.MOCK_JEV_CONFIDENCE ?? 0.95);
+// Argument answers below the router's JEV_ARG_MIN_CERTAINTY keep it out of `direct` mode;
+// raise this to exercise direct calls.
+const ARG_CERTAINTY = Number(process.env.MOCK_JEV_ARG_CERTAINTY ?? 0.5);
+const DUMP_DIR = process.env.MOCK_JEV_DUMP_DIR;
+
+let served = 0;
+
+function answer(key, question, wanted) {
+  if (key === "tool") {
+    const options = Object.keys(question.criteria ?? {});
+    // A scripted name the client doesn't offer would be a mock bug, not a routing result.
+    const choice = options.includes(wanted) ? wanted : options.includes(NO_TOOL) ? NO_TOOL : options[0];
+    const rest = (1 - CONFIDENCE) / Math.max(1, options.length - 1);
+    const probabilities = Object.fromEntries(options.map((name) => [name, name === choice ? CONFIDENCE : rest]));
+    return { type: "choice", choice, confidence: CONFIDENCE, probabilities };
+  }
+  if (key.startsWith("shard:")) {
+    // First pass over a big roster: the wanted tool lives in exactly one shard.
+    const options = Object.keys(question.criteria ?? {});
+    const choice = options.includes(wanted) ? wanted : "none_of_these";
+    const rest = (1 - CONFIDENCE) / Math.max(1, options.length - 1);
+    return { type: "choice", choice, confidence: CONFIDENCE, probabilities: Object.fromEntries(options.map((name) => [name, name === choice ? CONFIDENCE : rest])) };
+  }
+  if (key === "needs_tool") return { type: "noul", noul: wanted === NO_TOOL ? 0.1 : 0.9 };
+  if (question.type === "noul") return { type: "noul", noul: ARG_CERTAINTY };
+  if (question.type === "score") return { type: "score", score: 0.5 };
+  const options = Object.keys(question.criteria ?? {});
+  return {
+    type: "choice",
+    choice: options[0],
+    confidence: ARG_CERTAINTY,
+    probabilities: Object.fromEntries(options.map((name, i) => [name, i === 0 ? ARG_CERTAINTY : 0])),
+  };
+}
+
+createServer(async (req, res) => {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const send = (status, body) => {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  };
+  if (req.method !== "POST" || !req.url?.startsWith("/v1/systemone")) return send(404, { error: "mock-jev only serves POST /v1/systemone" });
+
+  let request;
+  try {
+    request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return send(400, { error: "invalid JSON" });
+  }
+  const questions = request.questions ?? {};
+  const wanted = SCRIPT[Math.min(served, SCRIPT.length - 1)];
+  // A shortlist pass and the decision that follows it belong to the same turn of the script.
+  if ("tool" in questions) served++;
+  const answers = Object.fromEntries(Object.entries(questions).map(([key, q]) => [key, answer(key, q, wanted)]));
+  const state = JSON.stringify(request.state ?? null);
+
+  if (DUMP_DIR) {
+    mkdirSync(DUMP_DIR, { recursive: true });
+    writeFileSync(join(DUMP_DIR, `jev-${String(served).padStart(4, "0")}.json`), JSON.stringify({ request, answers }, null, 2));
+  }
+  console.log(
+    JSON.stringify({
+      n: served,
+      scripted: wanted,
+      answered: answers.tool?.choice,
+      options: Object.keys(questions.tool?.criteria ?? {}),
+      questions: Object.keys(questions).length,
+      stateChars: state.length,
+    }),
+  );
+  send(200, { model: request.model ?? "mock-jev", answers, usage: { input_tokens: Math.ceil(state.length / 4), output_tokens: 0 } });
+}).listen(PORT, "127.0.0.1", () => console.log(`mock-jev on http://127.0.0.1:${PORT} — script: ${SCRIPT.join(" → ")}`));