jev-gateway 0.1.0

package/.env.example

@@ -0,0 +1,33 @@
+# --- Required -------------------------------------------------------------
+# TypeSafe API key (https://docs.typesafe.ai). Jev makes the tool-selection call.
+TYPESAFE_API_KEY=
+
+# --- Upstream LLM (any OpenAI-compatible API) -------------------------------
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+# If set, replaces the client's Authorization header on upstream requests.
+# If unset, the client's own Authorization header is forwarded as-is.
+UPSTREAM_API_KEY=
+# If set, clients must send "Authorization: Bearer <ROUTER_API_KEY>" (requires UPSTREAM_API_KEY).
+ROUTER_API_KEY=
+# Optional cheaper model used only to fill arguments once Jev has picked the tool.
+ARGS_MODEL=
+
+# --- Routing ----------------------------------------------------------------
+PORT=8787
+JEV_MODEL=jev-latest
+JEV_TIMEOUT_MS=4000
+# Below this confidence the request is forwarded untouched (the LLM decides).
+JEV_MIN_CONFIDENCE=0.7
+# Minimum certainty per closed-set argument before answering without the LLM.
+JEV_ARG_MIN_CERTAINTY=0.8
+# When Jev says "no tool needed": force_none (tool_choice=none) | passthrough
+JEV_ON_NONE=force_none
+# Answer directly (no LLM call) when every argument is an enum/boolean.
+JEV_DIRECT_CALLS=true
+JEV_MAX_STATE_CHARS=60000
+JEV_MAX_MESSAGE_CHARS=4000
+
+# --- Debugging --------------------------------------------------------------
+# Opt-in wire dumps: every routed request (decoded JSON body, credentials redacted), what the
+# router changed, and the reply's usage / error body. Dumps contain the whole conversation.
+JEV_DEBUG_DUMP_DIR=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Lana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# jev-gateway
+
+> Independent project — not affiliated with or endorsed by TypeSafe. "Jev" is TypeSafe's model; this
+> gateway is a client of its public API.
+
+An LLM gateway that speaks Chat Completions, the Responses API and the Anthropic Messages API.
+Point your client — or Codex, or Claude Code — at it instead of your LLM provider; whenever a
+request is really asking **"which tool should I call?"**, the router hands that decision to
+[Jev](https://docs.typesafe.ai/introduction) — TypeSafe's System One model — instead of paying a
+reasoning LLM to make it.
+
+Jev doesn't generate text. It answers typed questions (Choice / Score / Noul) about a piece of
+state and returns calibrated probabilities plus a confidence, in one fast call. Tool selection is
+exactly that kind of question, so the split is:
+
+| Decision | Who makes it |
+| --- | --- |
+| Which tool, or no tool at all | **Jev** (Choice over the tool list + a Noul cross-check) |
+| Arguments that are enums / booleans / consts | **Jev** (fanned out in the same call) |
+| Open-ended arguments (free text, numbers, dates) | Upstream LLM, with `tool_choice` forced to Jev's pick |
+| Plain text replies, everything without `tools` | Upstream LLM, untouched |
+
+## How a request is routed
+
+`POST /v1/chat/completions` with `tools` and `tool_choice` of `auto`/`required` triggers **one**
+Jev call. The conversation becomes the state; the questions are:
+
+- `tool` — Choice: every tool name → its description, plus `no_tool_needed` (omitted for `required`)
+- `needs_tool` — Noul: an independent "does the assistant need a tool now?" check
+- `arg:*` / `stated:*` — for each tool whose parameters are *all* closed-set, one question per
+  argument (and "was it stated?" for optional ones), asked speculatively since extra questions are
+  nearly free
+
+The answer picks one of five modes, reported in the `x-jev-gateway-mode` response header:
+
+| Mode | When | What happens |
+| --- | --- | --- |
+| `direct` | Tool is confident and every argument is closed-set and certain | The router synthesizes the `tool_calls` response itself (streaming included). **No LLM call.** |
+| `forced` | Tool is confident, arguments need an LLM | Forwarded with `tool_choice` set to that function — and to `ARGS_MODEL` if configured, since the hard part is already done |
+| `hint` | Tool is confident, but `tool_choice` can't be rewritten (Anthropic: extended thinking on, or the conversation is prompt-cached) | Forwarded with a one-line suggestion appended *after* the client's last block, so cached prefixes stay intact. The LLM may disagree |
+| `none` | Jev is confident no tool is needed | Forwarded with `tool_choice: "none"` (or untouched with `JEV_ON_NONE=passthrough`) |
+| `passthrough` | Low confidence, the two questions disagree, Jev errored/timed out, no tools, caller already chose | Forwarded byte-for-byte; `x-jev-gateway-reason` says why |
+
+Rosters over 120 tools (Claude Code sends ~280) don't fit one good question, so they take two Jev
+calls: every shard of the roster is ranked in one call, and the top 3 of each go on to the decision
+above with full-length descriptions.
+
+The router always **fails open**: any Jev problem means the LLM decides, as if the gateway weren't
+there. All other `/v1/*` routes (models, embeddings, …) are proxied unchanged.
+
+## Install
+
+```bash
+npm install -g jev-gateway
+mkdir -p ~/.jev-gateway && echo "TYPESAFE_API_KEY=…" > ~/.jev-gateway/.env
+jev-codex        # or: jev-claude
+```
+
+That is all the two launchers need (details below). To run the gateway as a standalone server for
+your own clients, work from a checkout:
+
+## Run it
+
+```bash
+pnpm install
+cp .env.example .env    # set TYPESAFE_API_KEY, and UPSTREAM_BASE_URL if not OpenAI
+pnpm dev
+```
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8787/v1")  # your usual provider key still works
+```
+
+By default the client's own `Authorization` header is forwarded upstream. Set `UPSTREAM_API_KEY`
+to have the gateway hold the provider key, and `ROUTER_API_KEY` to require a gateway key from
+clients. Any OpenAI-compatible upstream works (OpenAI, OpenRouter, vLLM, Ollama, LiteLLM, …).
+
+### Try a decision without an upstream
+
+`POST /router/decide` takes a chat.completions body, calls Jev, and returns the decision — mode,
+tool, arguments, Jev's confidence, top probabilities, tokens and latency — without calling the LLM:
+
+```bash
+curl -s localhost:8787/router/decide -H 'content-type: application/json' -d '{
+  "model": "gpt-5",
+  "messages": [{"role": "user", "content": "turn the kitchen lights on"}],
+  "tools": [{"type": "function", "function": {
+    "name": "set_lights", "description": "Turn the lights in a room on or off.",
+    "parameters": {"type": "object", "required": ["room", "on"], "properties": {
+      "room": {"type": "string", "enum": ["kitchen", "bedroom", "office"]},
+      "on": {"type": "boolean"}}}}}]
+}'
+```
+
+Send `x-jev-gateway: off` on any request to bypass Jev for that call.
+
+## Use it with Codex (local)
+
+Codex only speaks the Responses API, so the router handles `POST /v1/responses` the same way as
+chat completions — including Codex's free-form tools (`apply_patch`), provider-run tools
+(`web_search`, offered to Jev but never forced) and zstd-compressed request bodies.
+
+```bash
+jev-codex                # instead of `codex`; every codex argument still works
+jev-codex exec "fix the failing test"
+jev-codex --jev-logs     # second terminal: watch each routing decision live
+```
+
+`jev-codex` starts a background router on `127.0.0.1:8790` if one isn't running, then launches
+`codex` with a `-c model_providers.jev-gateway…` override. **Nothing in `~/.codex` is modified**, and
+plain `codex` keeps working as before. It reuses your existing Codex login
+(`requires_openai_auth = true`): with a ChatGPT subscription the router forwards to
+`https://chatgpt.com/backend-api/codex`, with an API key to `https://api.openai.com/v1`
+(override with `JEV_CODEX_UPSTREAM_BASE_URL`). `TYPESAFE_API_KEY` is read from the environment,
+`~/.jev-gateway/.env`, or a checkout's own `.env`. `jev-codex --jev-help` lists the rest (`--jev-status`, `--jev-stop`,
+`--jev-config` for a permanent `codex --profile jev`).
+
+If the upstream rejects a rewritten request (HTTP 400/422 — some backends only accept
+`tool_choice: "auto"`), the router replays the original, so Codex never sees a router-caused error.
+
+## Use it with Claude Code (local)
+
+```bash
+jev-claude               # instead of `claude`; every claude argument still works
+jev-claude -p "summarise this repo"
+jev-claude --jev-logs    # second terminal: watch each routing decision live
+```
+
+`jev-claude` starts a background router on `127.0.0.1:8789` forwarding to `https://api.anthropic.com/v1`
+and runs `claude` with only `ANTHROPIC_BASE_URL` set. With no gateway credential alongside it, Claude
+Code keeps using its saved login, so a **claude.ai subscription keeps working** and its limits apply
+as usual; **nothing in `~/.claude` is modified**. The same `--jev-*` flags as `jev-codex` apply.
+
+What Jev can do here is narrower than with Codex, by design of the API rather than the router:
+Claude Code runs with adaptive thinking (a forced `tool_choice` is rejected) and re-reads a cached
+conversation every turn (any `tool_choice` change would invalidate it). So Claude Code requests are
+steered with `hint` mode, `none` is never applied, and `direct` still answers without the LLM when
+a tool's arguments are all closed-set. API callers without thinking or message caching get `forced`.
+
+## Configuration
+
+See [.env.example](.env.example). The ones worth tuning:
+
+- `JEV_MIN_CONFIDENCE` (0.7) — below this the LLM decides. Raise it to be more conservative.
+- `JEV_ARG_MIN_CERTAINTY` (0.8) — the weakest argument must clear this for a `direct` answer;
+  otherwise the request degrades to `forced`.
+- `ARGS_MODEL` — a cheap model for argument filling in `forced` mode.
+- `JEV_DIRECT_CALLS=false` — never answer without the LLM; Jev only picks the tool.
+
+Each routed request logs one JSON line (mode, reason, Jev's choice/confidence/latency) to stdout.
+
+## Known trade-offs
+
+- Jev picks **one** tool per turn. In `forced` mode the LLM can still call that tool several times
+  in parallel, but not mix different tools in one turn; `direct` mode emits exactly one call.
+- Jev is text-only with a 32k-token state budget: images become `[image_url]` placeholders and long
+  conversations keep their newest turns (`JEV_MAX_STATE_CHARS`). It is most accurate in English.
+- A hint is a suggestion, not a decision: in `hint` mode the LLM still spends its own reasoning on
+  the choice, so the gain is accuracy on large rosters, not latency or cost.
+- Validated end to end on subscriptions (Codex 0.154 on ChatGPT, Claude Code 2.1 on claude.ai) with
+  `scripts/mock-jev.mjs` standing in for Jev: `forced`/`none` are accepted by the ChatGPT Codex
+  backend, `hint` by Anthropic. Jev's real accuracy on these rosters, and the confidence thresholds,
+  still need tuning against a real `TYPESAFE_API_KEY`.
+
+## Layout
+
+```
+src/adapters/      wire formats ↔ neutral shapes: chat.ts, responses.ts (Codex), messages.ts (Claude Code)
+src/state.ts       conversation → Jev state (truncation, newest-turns budget)
+src/questions.ts   tools → Jev questions; detects closed-set parameters
+src/decide.ts      the Jev call and the mode decision
+src/upstream.ts    streaming reverse proxy
+src/app.ts         Hono app: routes, auth, headers, fail-open replay
+bin/                jev-codex / jev-claude launchers (shared logic in launcher.mjs)
+scripts/mock-jev.mjs  local stand-in for Jev, for end-to-end runs without a TypeSafe key
+```
+
+`pnpm test` runs the suite against fake Jev and upstream transports; no keys needed.

package/bin/jev-claude.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// jev-claude: run Claude Code through a local jev-gateway — nothing in ~/.claude is modified.
+import { runLauncher } from "./launcher.mjs";
+
+await runLauncher({
+  name: "jev-claude",
+  client: "claude",
+  portEnv: "JEV_CLAUDE_PORT",
+  defaultPort: 8789,
+  upstream: () => process.env.JEV_CLAUDE_UPSTREAM_BASE_URL ?? "https://api.anthropic.com/v1",
+  upstreamHelp: "JEV_CLAUDE_UPSTREAM_BASE_URL   where Claude traffic goes (default https://api.anthropic.com/v1)",
+  // Only the base URL is set. With no gateway credential alongside it, Claude Code keeps using its
+  // saved claude.ai login, so a Pro/Max subscription (or an existing API key) keeps working as is.
+  env: (origin) => ({ ANTHROPIC_BASE_URL: origin }),
+  configHelp: (origin) =>
+    `# Keep the router running (jev-claude --jev-start), then either:\n` +
+    `#   ANTHROPIC_BASE_URL=${origin} claude\n` +
+    `# or add to ~/.claude/settings.json:\n` +
+    JSON.stringify({ env: { ANTHROPIC_BASE_URL: origin } }, null, 2),
+});

package/bin/jev-codex.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// jev-codex: run Codex through a local jev-gateway — nothing in ~/.codex is modified.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runLauncher } from "./launcher.mjs";
+
+/** Codex talks to a different backend depending on how the user logged in. */
+function detectUpstream() {
+  if (process.env.JEV_CODEX_UPSTREAM_BASE_URL) return process.env.JEV_CODEX_UPSTREAM_BASE_URL;
+  try {
+    const codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+    const auth = JSON.parse(readFileSync(join(codexHome, "auth.json"), "utf8"));
+    if (auth.auth_mode === "chatgpt" || (auth.tokens && !auth.OPENAI_API_KEY)) {
+      return "https://chatgpt.com/backend-api/codex";
+    }
+  } catch {
+    // No readable login: assume API-key usage.
+  }
+  return "https://api.openai.com/v1";
+}
+
+const provider = (origin) => ({
+  name: `"jev-gateway"`,
+  base_url: `"${origin}/v1"`,
+  wire_api: `"responses"`,
+  // Reuse whatever login Codex already has; the router forwards it upstream untouched.
+  requires_openai_auth: "true",
+});
+
+await runLauncher({
+  name: "jev-codex",
+  client: "codex",
+  portEnv: "JEV_CODEX_PORT",
+  defaultPort: 8790,
+  upstream: detectUpstream,
+  upstreamHelp:
+    "JEV_CODEX_UPSTREAM_BASE_URL   where Codex traffic goes; default follows your Codex login:\n" +
+    "                                ChatGPT login → https://chatgpt.com/backend-api/codex\n" +
+    "                                API key       → https://api.openai.com/v1",
+  args: (origin) => [
+    "-c",
+    `model_provider="jev-gateway"`,
+    ...Object.entries(provider(origin)).flatMap(([key, value]) => ["-c", `model_providers.jev-gateway.${key}=${value}`]),
+  ],
+  configHelp: (origin) =>
+    `# Save as ~/.codex/jev.config.toml, keep the router running (jev-codex --jev-start),\n` +
+    `# then use: codex --profile jev\n` +
+    `model_provider = "jev-gateway"\n\n[model_providers.jev-gateway]\n` +
+    Object.entries(provider(origin))
+      .map(([key, value]) => `${key} = ${value}`)
+      .join("\n"),
+});

package/bin/launcher.mjs

@@ -0,0 +1,148 @@
+// Shared by the jev-<client> launchers: keep one background router per client alive, then run
+// the client pointed at it. Nothing in the client's own config directory is ever modified.
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const STATE_DIR = join(homedir(), ".jev-gateway");
+// A git checkout runs the TypeScript sources directly; an installed package only ships dist/.
+const FROM_SOURCE = existsSync(join(ROOT, "src/index.ts"));
+const ROUTER_ARGS = FROM_SOURCE ? ["--import", "tsx", join(ROOT, "src/index.ts")] : [join(ROOT, "dist/index.js")];
+/** Where TYPESAFE_API_KEY and tuning knobs may live; the first file to set a variable wins. */
+const ENV_FILES = [...(FROM_SOURCE ? [join(ROOT, ".env")] : []), join(STATE_DIR, ".env")];
+
+/**
+ * @param {object} spec
+ * @param {string} spec.name         launcher name, e.g. "jev-claude"
+ * @param {string} spec.client       binary to run, e.g. "claude"; also names the log/pid files
+ * @param {string} spec.portEnv      env var overriding the router port
+ * @param {number} spec.defaultPort
+ * @param {() => string} spec.upstream        where this client's traffic is forwarded
+ * @param {string} spec.upstreamHelp          help text describing the upstream default
+ * @param {(origin: string) => string[]} [spec.args]   extra leading arguments for the client
+ * @param {(origin: string) => Record<string, string>} [spec.env]  extra environment for the client
+ * @param {(origin: string) => string} spec.configHelp  how to wire the client up permanently
+ */
+export async function runLauncher(spec) {
+  // Real environment variables win over both files.
+  for (const file of ENV_FILES) if (existsSync(file)) process.loadEnvFile(file);
+
+  const port = Number(process.env[spec.portEnv] ?? spec.defaultPort);
+  const origin = `http://127.0.0.1:${port}`;
+  const logFile = join(STATE_DIR, `${spec.client}.log`);
+  const pidFile = join(STATE_DIR, `${spec.client}.pid`);
+
+  const help = `${spec.name} — ${spec.client} with tool selection routed through Jev
+
+  ${spec.name} [${spec.client} args…]   start the router if needed, then run ${spec.client} through it
+  ${spec.name} --jev-start     only start the background router
+  ${spec.name} --jev-status    is the router up, and where does it forward to?
+  ${spec.name} --jev-logs      follow the router's decisions (run in a second terminal)
+  ${spec.name} --jev-stop      stop the background router
+  ${spec.name} --jev-config    how to point plain \`${spec.client}\` at the router permanently
+
+Environment (or ${ENV_FILES.at(-1)}):
+  TYPESAFE_API_KEY   required — Jev makes the tool-selection call
+  ${spec.portEnv}   router port for ${spec.client} (default ${spec.defaultPort})
+  ${spec.upstreamHelp}
+`;
+
+  const health = async () => {
+    try {
+      const response = await fetch(`${origin}/health`, { signal: AbortSignal.timeout(1000) });
+      return response.ok ? await response.json() : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  const tailLog = (lines = 15) =>
+    existsSync(logFile) ? readFileSync(logFile, "utf8").trimEnd().split("\n").slice(-lines).join("\n") : "";
+
+  const ensureRouter = async () => {
+    const upstream = spec.upstream().replace(/\/+$/, "");
+    const running = await health();
+    if (running) {
+      if (running.upstream === upstream) return;
+      console.error(`${spec.name}: router on :${port} forwards to ${running.upstream}, expected ${upstream}.`);
+      console.error(`${" ".repeat(spec.name.length)}  Run \`${spec.name} --jev-stop\` and try again.`);
+      process.exit(1);
+    }
+    if (!process.env.TYPESAFE_API_KEY) {
+      console.error(`${spec.name}: TYPESAFE_API_KEY is not set. Export it, or put it in ${ENV_FILES.at(-1)}`);
+      process.exit(1);
+    }
+
+    mkdirSync(STATE_DIR, { recursive: true });
+    const log = openSync(logFile, "a");
+    // The client authenticates itself (subscription login or its own key); the gateway must not swap that out.
+    const { UPSTREAM_API_KEY: _key, ROUTER_API_KEY: _routerKey, ...env } = process.env;
+    const child = spawn(process.execPath, ROUTER_ARGS, {
+      cwd: ROOT,
+      env: { ...env, PORT: String(port), UPSTREAM_BASE_URL: upstream },
+      detached: true,
+      stdio: ["ignore", log, log],
+    });
+    closeSync(log);
+    child.unref();
+    writeFileSync(pidFile, String(child.pid));
+
+    let exited = false;
+    child.once("exit", () => (exited = true));
+    for (let attempt = 0; attempt < 50 && !exited; attempt++) {
+      if (await health()) return;
+      await new Promise((done) => setTimeout(done, 100));
+    }
+    console.error(`${spec.name}: the router did not start. Last log lines (${logFile}):\n${tailLog()}`);
+    process.exit(1);
+  };
+
+  const stopRouter = () => {
+    if (!existsSync(pidFile)) return console.log(`${spec.name}: no background router recorded.`);
+    const pid = Number(readFileSync(pidFile, "utf8"));
+    try {
+      process.kill(pid);
+      console.log(`${spec.name}: stopped router (pid ${pid}).`);
+    } catch {
+      console.log(`${spec.name}: router was not running.`);
+    }
+    rmSync(pidFile, { force: true });
+  };
+
+  const [flag] = process.argv.slice(2);
+  if (flag === "--jev-help") return console.log(help);
+  if (flag === "--jev-stop") return stopRouter();
+  if (flag === "--jev-config") return console.log(spec.configHelp(origin));
+  if (flag === "--jev-start") {
+    await ensureRouter();
+    return console.log(`${spec.name}: router up on ${origin} → ${spec.upstream()} (logs: ${logFile})`);
+  }
+  if (flag === "--jev-status") {
+    const running = await health();
+    console.log(running ? `${spec.name}: router up on ${origin} → ${running.upstream}` : `${spec.name}: router is not running`);
+    return console.log(`logs: ${logFile}`);
+  }
+  if (flag === "--jev-logs") {
+    mkdirSync(STATE_DIR, { recursive: true });
+    closeSync(openSync(logFile, "a"));
+    return spawn("tail", ["-n", "30", "-f", logFile], { stdio: "inherit" });
+  }
+
+  await ensureRouter();
+  const child = spawn(spec.client, [...(spec.args?.(origin) ?? []), ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: { ...process.env, ...spec.env?.(origin) },
+  });
+  child.on("error", (error) => {
+    console.error(`${spec.name}: could not run ${spec.client}: ${error.message}`);
+    process.exit(127);
+  });
+  // The router is left running for the next session; `--jev-stop` ends it.
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+  // Ctrl-C reaches the client directly (same foreground process group); it decides what that means.
+  process.on("SIGINT", () => {});
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+}

package/dist/adapters/adapter.js

@@ -0,0 +1 @@
+export const sse = (events) => events.map(({ event, data }) => `${event ? `event: ${event}\n` : ""}data: ${data}\n\n`).join("");

package/dist/adapters/chat.js

@@ -0,0 +1,128 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { textOf, truncate } from "../state.js";
+import { sse } from "./adapter.js";
+/** OpenAI Chat Completions (`POST /v1/chat/completions`). */
+function toInput(req, maxMessageChars) {
+    if (!Array.isArray(req.messages))
+        return { skip: "no_messages" };
+    const rawTools = Array.isArray(req.tools) ? req.tools : [];
+    if (rawTools.some((tool) => tool.type !== "function" || !tool.function?.name))
+        return { skip: "non_function_tools" };
+    const toolNameByCallId = new Map();
+    for (const message of req.messages) {
+        for (const call of message.tool_calls ?? [])
+            toolNameByCallId.set(call.id, call.function.name);
+    }
+    const system = [];
+    const turns = [];
+    for (const message of req.messages) {
+        const text = truncate(textOf(message.content), maxMessageChars);
+        if (message.role === "system" || message.role === "developer") {
+            if (text)
+                system.push(text);
+        }
+        else if (message.role === "tool") {
+            turns.push({
+                role: "tool_result",
+                tool: toolNameByCallId.get(message.tool_call_id ?? "") ?? "unknown",
+                content: text,
+            });
+        }
+        else if (message.tool_calls?.length) {
+            turns.push({
+                role: message.role,
+                ...(text ? { text } : {}),
+                tool_calls: message.tool_calls.map((call) => ({
+                    tool: call.function.name,
+                    arguments: truncate(call.function.arguments, maxMessageChars),
+                })),
+            });
+        }
+        else {
+            turns.push({ role: message.role, text });
+        }
+    }
+    const choice = req.tool_choice ?? "auto";
+    return {
+        system: system.join("\n\n"),
+        turns,
+        tools: rawTools.map((tool) => ({
+            kind: "function",
+            name: tool.function.name,
+            description: tool.function.description,
+            parameters: tool.function.parameters,
+        })),
+        toolChoice: choice === "auto" || choice === "required" ? choice : "decided",
+    };
+}
+function apply(req, decision, argsModel) {
+    if (decision.mode === "forced") {
+        return {
+            ...req,
+            model: argsModel ?? req.model,
+            tool_choice: { type: "function", function: { name: decision.tool } },
+        };
+    }
+    if (decision.mode === "none")
+        return { ...req, tool_choice: "none" };
+    return req;
+}
+const usageOf = (call) => ({
+    prompt_tokens: call.inputTokens,
+    completion_tokens: 0,
+    total_tokens: call.inputTokens,
+});
+const ids = () => ({
+    id: `chatcmpl-jev-${randomUUID()}`,
+    callId: `call_${randomBytes(12).toString("hex")}`,
+    created: Math.floor(Date.now() / 1000),
+});
+/** A chat.completion carrying the tool call Jev decided on, shaped like an LLM's. */
+function directJson(req, call) {
+    const { id, callId, created } = ids();
+    return {
+        id,
+        object: "chat.completion",
+        created,
+        model: req.model,
+        choices: [
+            {
+                index: 0,
+                message: {
+                    role: "assistant",
+                    content: null,
+                    refusal: null,
+                    tool_calls: [
+                        { id: callId, type: "function", function: { name: call.tool, arguments: JSON.stringify(call.args) } },
+                    ],
+                },
+                logprobs: null,
+                finish_reason: "tool_calls",
+            },
+        ],
+        usage: usageOf(call),
+        system_fingerprint: "jev-gateway",
+    };
+}
+/** The same tool call as a chat.completion.chunk stream, for `stream: true` clients. */
+function directStream(req, call) {
+    const { id, callId, created } = ids();
+    const base = { id, object: "chat.completion.chunk", created, model: req.model, system_fingerprint: "jev-gateway" };
+    const delta = (delta, finish_reason = null) => ({
+        ...base,
+        choices: [{ index: 0, delta, logprobs: null, finish_reason }],
+    });
+    const chunks = [
+        delta({
+            role: "assistant",
+            content: null,
+            tool_calls: [{ index: 0, id: callId, type: "function", function: { name: call.tool, arguments: "" } }],
+        }),
+        delta({ tool_calls: [{ index: 0, function: { arguments: JSON.stringify(call.args) } }] }),
+        delta({}, "tool_calls"),
+    ];
+    if (req.stream_options?.include_usage)
+        chunks.push({ ...base, choices: [], usage: usageOf(call) });
+    return sse([...chunks.map((chunk) => ({ data: JSON.stringify(chunk) })), { data: "[DONE]" }]);
+}
+export const chatAdapter = { toInput, apply, directJson, directStream };