toolnexus 0.18.0 → 0.19.0

package/src/agents/loop.ts

@@ -177,6 +177,33 @@ export async function runGated(
   }
 }
 
+/**
+ * The spec fields a Loop drive CANNOT honour, named rather than dropped silently.
+ *
+ * A `Loop` is one client run: it has no runtime, so it has no handle tree to spawn a `team`
+ * into, no §10 suspension ledger for `waitFor`, and no per-agent metric sink routing. Those
+ * fields are honoured by `Agent.run` / `AgentRuntime` only. `uses.tools` is not honoured either
+ * — a Loop is handed its toolkit by the caller.
+ *
+ * Returns a FIXED CANONICAL vocabulary — `"tools"`, `"team"`, `"waitFor"`, `"onMetric"` —
+ * identical in all seven ports, exactly as the `limit` strings are, and NOT this language's own
+ * spelling of the field. Empty ⇒ nothing is lost.
+ * Additive and advisory: a Loop never refuses to run because of it (that would be breaking).
+ */
+export function loopUnsupported(spec: {
+  uses?: { tools?: unknown[] }
+  team?: unknown[]
+  waitFor?: unknown
+  onMetric?: unknown
+}): string[] {
+  const out: string[] = []
+  if (spec.uses?.tools && spec.uses.tools.length > 0) out.push("tools")
+  if (spec.team && spec.team.length > 0) out.push("team")
+  if (spec.waitFor) out.push("waitFor")
+  if (spec.onMetric) out.push("onMetric")
+  return out
+}
+
 /** A live execution of an Agent. Its only verbs are `run` and reading state. */
 export class Loop {
   #status: Outcome["status"] | "idle" | "running" = "idle"
@@ -234,10 +261,21 @@ export class Loop {
   /** Applies a per-call model override via `requestParams` (`model` is not in the
    *  forbidden set — the client forbids only messages/tools/stream). */
   #clientOptions(opts: LoopRunOptions): ClientOptions {
+    const spec = this.agent.spec
     const base: ClientOptions = {
       ...this.options,
-      systemPrompt: this.agent.spec.soul ?? this.options.systemPrompt,
-      hooks: guardedHooks(this.agent.spec.guardrails, this.agent.spec.hooks ?? this.options.hooks),
+      // CALLER-WINS (ADR 0024 / issue #87). A `systemPrompt` the caller put on the client
+      // options is an explicit instruction for THIS drive; the soul is the agent's default.
+      // js used to let the soul override it, which python and csharp never did.
+      systemPrompt: this.options.systemPrompt ?? spec.soul,
+      // The spec's model and turn ceiling become Loop DEFAULTS — the same spec drives both
+      // doors. `ClientOptions.model` is REQUIRED in js, so "the caller did not choose" is
+      // spelled the way the runtime already spells it: absent, or the `"inherit"` sentinel.
+      model: !this.options.model || this.options.model === "inherit"
+        ? (spec.model && spec.model !== "inherit" ? spec.model : this.options.model)
+        : this.options.model,
+      maxTurns: this.options.maxTurns ?? spec.budget?.maxTurns,
+      hooks: guardedHooks(spec.guardrails, spec.hooks ?? this.options.hooks),
     }
     if (!opts.model) return base
     return { ...base, requestParams: { ...(base.requestParams ?? {}), model: opts.model } }

package/src/agents/runtime.ts

@@ -15,7 +15,17 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import type { PromptInput } from "../content.js"
-import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js"
+import {
+  createClient,
+  createInProcessFetch,
+  InMemoryConversationStore,
+  type ClientStyle,
+  type ConversationStore,
+  type Hooks,
+  type InProcessRequest,
+  type InProcessResponse,
+  type MetricEvent,
+} from "../client.js"
 import { runGated, type Completion } from "./loop.js"
 import { createToolkit, type Toolkit } from "../toolkit.js"
 import { defineTool } from "../native.js"
@@ -118,6 +128,63 @@ export interface InboxItem {
 
 export type HandleState = "idle" | "running" | "suspended" | "closed"
 
+/**
+ * The §7D AGENT status vocabulary, as a value. It is a DIFFERENT, larger closed set than the
+ * §8 CLIENT vocabulary (`RUN_STATUSES` = done/pending/incomplete): only this one contains
+ * `"timeout"`, and `"timeout"` here means a `wait()` DEADLINE expired while the child keeps
+ * running — never that an LLM call timed out. Two fields are called `status`; they are not
+ * interchangeable (ADR 0027 D2.1).
+ */
+export const TASK_STATUSES = [
+  "done", "pending", "incomplete", "interrupted", "closed", "timeout", "error",
+] as const
+
+/**
+ * The CLOSED `limit` vocabulary (addendum A14). A value NAMES THE BUDGET FIELD that stopped the
+ * run, spelled exactly as `Budget` spells it, plus the two non-budget stops `completion` and
+ * `timeout`. Identical in all seven ports, like the `loopUnsupported` strings — "which limit
+ * stopped me" is only answerable if the answer is the same word everywhere.
+ *
+ * A port's INTERNAL pool/dimension name is an implementation detail and must never leak into
+ * the field; `canonicalLimit` is the boundary that enforces that here.
+ */
+export const TASK_LIMITS = [
+  "maxTurns", "maxTokens", "maxToolCalls", "maxWallMs", "maxChildren", "maxConcurrent", "maxDepth",
+  "completion", "timeout",
+] as const
+
+export type TaskLimit = (typeof TASK_LIMITS)[number]
+
+/** Map anything the internals produce onto the closed vocabulary; unknown ⇒ undefined, never a
+ *  leaked internal name. */
+export function canonicalLimit(limit: string | undefined): TaskLimit | undefined {
+  return limit && (TASK_LIMITS as readonly string[]).includes(limit) ? (limit as TaskLimit) : undefined
+}
+
+/**
+ * NAMED CONSTANTS for the two closed vocabularies. Every `TaskResult` construction site in this
+ * file spells its status and limit through these, never as a string literal, so a rename cannot
+ * silently desync the two fields — which is exactly how `status:"timeout"` came to ship with an
+ * empty `limit` in three of the seven ports (addendum A18).
+ */
+export const S: Readonly<Record<TaskStatus, TaskStatus>> = Object.freeze({
+  done: "done", pending: "pending", incomplete: "incomplete", interrupted: "interrupted",
+  closed: "closed", timeout: "timeout", error: "error",
+})
+
+export const L: Readonly<Record<TaskLimit, TaskLimit>> = Object.freeze({
+  maxTurns: "maxTurns", maxTokens: "maxTokens", maxToolCalls: "maxToolCalls", maxWallMs: "maxWallMs",
+  maxChildren: "maxChildren", maxConcurrent: "maxConcurrent", maxDepth: "maxDepth",
+  completion: "completion", timeout: "timeout",
+})
+
+/**
+ * THE INVARIANT `S`/`L` exist to protect (addendum A18): a LIMIT stop (`incomplete`, `timeout`)
+ * names its limit; every other status carries none. It is asserted by the suite, not exported —
+ * a predicate that exists so our own tests can state a rule is not public API (A19b, ADR 0019).
+ * Ports copy the PREDICATE, not an export.
+ */
+
 export type TaskStatus =
   | "done"
   | "pending"      // §10 durable suspension — resume via runtime.resume(answer)
@@ -135,8 +202,23 @@ export interface TaskResult {
   /** Present iff status === "pending". `data.path` carries the suspended handle's
    * id path (§10 agent-escalation addendum) — never a field grafted on Request. */
   pending?: Request
+  /** Cumulative LLM round trips for this handle's SUBTREE — never per-run, never reset. */
   turns: number
+  /**
+   * Cumulative TREE total: this handle's own spend plus every descendant's, on EVERY status
+   * (ADR 0025 D1). It was already the tree total on four of the seven status branches; this
+   * gives the field one meaning. `parent.totalTokens >= child.totalTokens` always holds.
+   */
   totalTokens: number
+  /** This handle's OWN accumulated spend, excluding children. */
+  ownTokens: number
+  /**
+   * WHICH limit stopped the run, as a value to branch on rather than prose to match. Drawn from
+   * the CLOSED, cross-port `TASK_LIMITS` vocabulary (addendum A14) — it names the `Budget` field,
+   * or `completion` / `timeout`. Absent otherwise. A stop you cannot explain to a user is a bug,
+   * not a state.
+   */
+  limit?: TaskLimit
 }
 
 /** Uniform verb failure — returned, never thrown (only the root throws to the host). */
@@ -206,6 +288,8 @@ export class Handle {
   readonly deadline?: number
   /** Total tokens attributed to this handle (own turns + descendant roll-up). */
   usageTotal = 0
+  /** Tokens spent by THIS handle's own turns, excluding descendants (ADR 0025 D1). */
+  ownTokens = 0
   /** Total tool calls attributed to this handle (own + descendant roll-up). */
   toolCallsTotal = 0
   /** LLM round trips run by this handle itself (never reset — resume grows it). */
@@ -270,8 +354,16 @@ export interface RuntimeOptions {
   registry: Record<string, AgentDef>
   /** LLM endpoint. Omit for hermetic runs against an injected `fetch` mock. */
   llm?: { baseUrl?: string; style?: ClientStyle; apiKey?: string; model?: string }
-  /** HTTP transport for LLM requests (§8 Gap 2) — the hermetic-test seam. */
+  /** HTTP transport for LLM requests (§8 Gap 2) — the hermetic-test seam.
+   * Mutually exclusive with `inProcess` — `new AgentRuntime(...)` throws if both are set. */
   fetch?: typeof fetch
+  /** A model running IN THIS PROCESS (ADR 0030): the semantic counterpart to
+   * `fetch`, so a host whose model is a plain function never has to build its own
+   * `fetch`-shaped adapter. Internally this is turned into a `createInProcessFetch`
+   * adapter and wrapped by the SAME global turn gate as `fetch` — there is no second
+   * code path. Mutually exclusive with `fetch` and with `llm` — `new AgentRuntime(...)`
+   * throws if more than one of `fetch`/`inProcess` is set. */
+  inProcess?: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>
   /** Time source for every timer/timeout/deadline. Default: the system clock. */
   clock?: Clock
   /** The ONE ConversationStore for all handles (conversation id = handle id).
@@ -324,6 +416,20 @@ export class AgentRuntime {
   private readonly turnQueue: GateWaiter[] = []
 
   constructor(opts: RuntimeOptions) {
+    if (opts.fetch && opts.inProcess) {
+      throw new Error("toolnexus/agents: RuntimeOptions.fetch and RuntimeOptions.inProcess are mutually exclusive — set one, not both")
+    }
+    if (opts.llm && opts.inProcess) {
+      throw new Error(
+        "toolnexus/agents: RuntimeOptions.llm and RuntimeOptions.inProcess are mutually exclusive — an in-process model has no wire endpoint to point llm at",
+      )
+    }
+    if (opts.inProcess) {
+      // Reuse the SAME adapter createInProcessClient builds on (ADR 0030) — the
+      // runtime's in-process wiring is a CALLER of that export, not a second copy
+      // of the request/response assembly.
+      opts = { ...opts, fetch: createInProcessFetch(opts.inProcess) }
+    }
     this.opts = opts
     this.registry = opts.registry
     this.clock = opts.clock ?? systemClock
@@ -418,11 +524,11 @@ export class AgentRuntime {
     if (opts?.by && h.parent !== opts.by) {
       return Promise.resolve({
         text: `wait refused: only the spawner may wait on ${h.id}`,
-        isError: true, status: "error", turns: h.turnsTotal, totalTokens: h.usageTotal,
+        isError: true, status: S.error, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
       })
     }
     if (h.state === "closed") {
-      return Promise.resolve(h.lastResult ?? { text: "closed", isError: true, status: "closed", turns: h.turnsTotal, totalTokens: h.usageTotal })
+      return Promise.resolve(h.lastResult ?? { text: "closed", isError: true, status: S.closed, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens })
     }
     if (h.state === "suspended") return Promise.resolve(this.pendingResult(h))
     if (h.state === "idle" && h.lastResult && !this.isQueued(h)) return Promise.resolve(h.lastResult)
@@ -440,7 +546,7 @@ export class AgentRuntime {
         cancel = this.clock.setTimeout(() => {
           const i = h.waiters.indexOf(finish)
           if (i >= 0) h.waiters.splice(i, 1)
-          finish({ text: `wait timeout after ${opts.timeoutMs}ms (child still ${h.state})`, isError: true, status: "timeout", turns: h.turnsTotal, totalTokens: h.usageTotal })
+          finish({ text: `wait timeout after ${opts.timeoutMs}ms (child still ${h.state})`, isError: true, status: S.timeout, limit: L.timeout, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens })
         }, opts.timeoutMs)
       }
     })
@@ -496,7 +602,7 @@ export class AgentRuntime {
     await h.def.onClose?.(h, reason)
     const prev = h.state
     h.state = "closed"
-    const final: TaskResult = { text: "closed", isError: true, status: "closed", turns: h.turnsTotal, totalTokens: h.usageTotal }
+    const final: TaskResult = { text: "closed", isError: true, status: S.closed, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
     for (const w of h.waiters.splice(0)) w(final)
     this.t(`${h.id}: ${prev}→closed (${reason})`)
   }
@@ -527,16 +633,19 @@ export class AgentRuntime {
    * REATTACHES to the existing child by task key — never spawns a duplicate.
    * The root alone may throw to the host.
    */
-  async resume(answer: Answer): Promise<void> {
+  async resume(answer: Answer): Promise<TaskResult> {
     const leaf = this.deepestSuspended(this.root)
     if (!leaf) throw new Error("no suspended handle to resume")
     this.t(`${leaf.id}: resume with Answer(ok=${answer.ok}) at checkpoint (turns so far: ${leaf.turnsTotal})`)
-    await this.resumeSuspended(leaf, answer, { inline: false })
+    // The value is the settled result of the TOPMOST handle the cascade re-ran — what the host
+    // would have got from `Agent.run` had the suspension never happened (ADR 0025 D3).
+    let topmost = await this.resumeSuspended(leaf, answer, { inline: false })
     for (let p = leaf.parent; p && p !== this.root; p = p.parent) {
       if (p.state !== "suspended") break
       this.t(`${p.id}: cascade resume (reattaching delegated work)`)
-      await this.resumeSuspended(p, undefined, { inline: false })
+      topmost = await this.resumeSuspended(p, undefined, { inline: false })
     }
+    return topmost
   }
 
   private deepestSuspended(h: Handle): Handle | null {
@@ -580,25 +689,28 @@ export class AgentRuntime {
   // ---- budgets (live ancestor-chain enforcement + roll-up ledger) --------
 
   /** Walk the LIVE ancestor chain; name the first exhausted pool, if any. */
-  private poolLimit(h: Handle): string | undefined {
+  private poolLimit(h: Handle): TaskLimit | undefined {
     const now = this.clock.now()
     for (let a: Handle | null = h; a; a = a.parent) {
-      if (a.pool.tokens <= 0) return "maxTokens"
-      if (a.pool.toolCalls <= 0) return "maxToolCalls"
-      if (a.deadline !== undefined && now >= a.deadline) return "maxWallMs"
+      if (a.pool.tokens <= 0) return L.maxTokens
+      if (a.pool.toolCalls <= 0) return L.maxToolCalls
+      if (a.deadline !== undefined && now >= a.deadline) return L.maxWallMs
     }
     return undefined
   }
 
   /** Lifetime turn cap on the handle itself (turns never reset across resumes). */
-  private turnCap(h: Handle): string | undefined {
-    return h.turnsTotal >= h.eff.maxTurns ? "maxTurns" : undefined
+  private turnCap(h: Handle): TaskLimit | undefined {
+    return h.turnsTotal >= h.eff.maxTurns ? L.maxTurns : undefined
   }
 
   /** A limit stop is LOUD: settle an incomplete result (never silent, never a throw). */
-  private settleRefused(h: Handle, limit: string): string {
+  private settleRefused(h: Handle, limit: TaskLimit): string {
+    // `limit` here is already a Budget field name (`poolLimit`/`turnCap` return them verbatim);
+    // `canonicalLimit` below is the guard that keeps it that way if either ever changes.
     const text = `budget exhausted (${limit}); partial work preserved`
-    const r: TaskResult = { text, isError: true, status: "incomplete", turns: h.turnsTotal, totalTokens: h.usageTotal }
+    // The exhausted pool is COMPUTED here and used to be discarded into prose. `limit` carries it.
+    const r: TaskResult = { text, isError: true, status: S.incomplete, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens, limit }
     h.lastResult = r
     for (const w of h.waiters.splice(0)) w(r)
     return text
@@ -606,6 +718,7 @@ export class AgentRuntime {
 
   /** Usage roll-up IS the budget ledger: every ancestor's pool drains live. */
   private rollUp(h: Handle, tokens: number, toolCalls: number): void {
+    h.ownTokens += tokens // own figure: outside the ancestor walk, by construction
     for (let a: Handle | null = h; a; a = a.parent) {
       a.usageTotal += tokens
       a.toolCallsTotal += toolCalls
@@ -728,7 +841,7 @@ export class AgentRuntime {
 
   private pendingResult(h: Handle): TaskResult {
     const req = h.pendingRequest
-    return { text: req?.prompt ?? "", isError: false, status: "pending", pending: req, turns: h.turnsTotal, totalTokens: h.usageTotal }
+    return { text: req?.prompt ?? "", isError: false, status: S.pending, pending: req, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
   }
 
   /** The escalation seam: this handle's §10 interpreter authority, with the
@@ -801,7 +914,7 @@ export class AgentRuntime {
         h.checkpoint = { input }
         h.drained = [] // drained items ride the checkpointed input, not the inbox
         this.t(`${h.id}: running→suspended (pending "${stamped.kind}")`)
-        result = { text: r.text, isError: false, status: "pending", pending: stamped, turns: r.turns, totalTokens: r.usage.totalTokens }
+        result = { text: r.text, isError: false, status: S.pending, pending: stamped, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
       } else if (r.status === "incomplete") {
         h.state = "idle"
         h.drained = []
@@ -810,13 +923,17 @@ export class AgentRuntime {
         // generic sentence. Reading `limit` is how the runtime tells them apart.
         result = {
           text: r.limit === "completion" ? r.text : "hit maxTurns without a final answer",
-          isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens,
+          isError: true, status: S.incomplete, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
+          // The LATENT instance golang found: forwarding the client's `limit` straight through
+          // would hand a host `incomplete` with an empty limit whenever the client omits it.
+          // The `?? L.maxTurns` is what makes the invariant hold by construction, not by luck.
+          limit: canonicalLimit(r.limit) ?? L.maxTurns,
         }
       } else {
         h.state = "idle"
         h.drained = []
         this.t(`${h.id}: running→idle (done, turns=${r.turns}, tokens=${r.usage.totalTokens})`)
-        result = { text: r.text, isError: false, status: "done", turns: r.turns, totalTokens: r.usage.totalTokens }
+        result = { text: r.text, isError: false, status: S.done, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
       }
     } catch (e) {
       const aborted = h.abort?.signal.aborted ?? false
@@ -828,8 +945,9 @@ export class AgentRuntime {
       this.t(`${h.id}: running→idle (${aborted ? "interrupted; inbox intact" : `error: ${msg}`})`)
       result = {
         text: msg, isError: true,
-        status: closing ? "closed" : aborted ? "interrupted" : "error",
-        turns: h.turnsTotal, totalTokens: h.usageTotal,
+        // None of these three is a limit stop, so none carries a `limit` (A18).
+        status: closing ? S.closed : aborted ? S.interrupted : S.error,
+        turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
       }
     } finally {
       this.releaseChildSlot(h)
@@ -904,7 +1022,7 @@ export class AgentRuntime {
           } else if (existing.state === "running") {
             r = await rt.wait(existing, { by: parent })
           } else {
-            r = existing.lastResult ?? { text: `no recorded result for ${existing.id}`, isError: true, status: "error", turns: existing.turnsTotal, totalTokens: existing.usageTotal }
+            r = existing.lastResult ?? { text: `no recorded result for ${existing.id}`, isError: true, status: S.error, turns: existing.turnsTotal, totalTokens: existing.usageTotal, ownTokens: existing.ownTokens }
           }
         } else {
           const spawned = rt.spawn(parent, name)

package/src/builtin.ts

@@ -10,6 +10,7 @@
 import { spawn } from "node:child_process"
 import fs from "node:fs/promises"
 import { existsSync, readdirSync } from "node:fs"
+import { compareCodePoints, sortEntriesByName, toPosixPath } from "./order.js"
 import path from "node:path"
 import type { JSONSchema, Tool, ToolContext, ToolResult } from "./types.js"
 import { pending } from "./types.js"
@@ -115,7 +116,9 @@ function walkFiles(root: string): string[] {
     const dir = stack.pop()!
     let entries
     try {
-      entries = readdirSync(dir, { withFileTypes: true })
+      // EXPLICIT (A24). `glob` breaks at its cap, so an unsorted read changes WHICH files the
+      // model is shown, not merely their order — the same content bug as <skill_files> had.
+      entries = sortEntriesByName(readdirSync(dir, { withFileTypes: true }))
     } catch {
       continue
     }
@@ -332,10 +335,13 @@ function grepTool(): Tool {
       const root = args.path ? String(args.path) : process.cwd()
       const include = args.include ? String(args.include) : undefined
       const limit = typeof args.limit === "number" ? args.limit : 100
-      const matches: string[] = []
+      // Was the worse of the two builtins: capped MID-WALK and never sorted at all, so both the
+      // CONTENT and the order of the results were whatever the walk happened to reach first.
+      // Now: collect every match, order by relative path (code point) then line number ascending,
+      // and truncate last. The emitted path and the sort key are the same string (A28).
+      const hits: Array<{ rel: string; line: number; text: string }> = []
       for (const file of walkFiles(root)) {
-        if (matches.length >= limit) break
-        const rel = path.relative(root, file)
+        const rel = toPosixPath(path.relative(root, file), path.sep)
         if (include && !matchGlob(rel, include)) continue
         let text: string
         try {
@@ -345,10 +351,11 @@ function grepTool(): Tool {
         }
         const lines = text.split("\n")
         for (let i = 0; i < lines.length; i++) {
-          if (matches.length >= limit) break
-          if (re.test(lines[i])) matches.push(`${file}:${i + 1}:${lines[i]}`)
+          if (re.test(lines[i])) hits.push({ rel, line: i + 1, text: lines[i] })
         }
       }
+      hits.sort((a, b) => compareCodePoints(a.rel, b.rel) || a.line - b.line)
+      const matches = hits.slice(0, limit).map((h) => `${h.rel}:${h.line}:${h.text}`)
       return ok(matches.join("\n"), { count: matches.length })
     },
   )
@@ -373,13 +380,15 @@ function globTool(): Tool {
       if (!pattern) return err("glob: pattern is required")
       const root = args.path ? String(args.path) : process.cwd()
       const limit = typeof args.limit === "number" ? args.limit : 100
+      // Collect ALL matches, order them, THEN cap (A24/A25): breaking the walk at the cap let
+      // the filesystem decide WHICH files the model sees, not merely their order. The emitted
+      // string and the sort key are the SAME `/`-separated relative path (A28).
       const found: string[] = []
       for (const file of walkFiles(root)) {
-        if (found.length >= limit) break
-        const rel = path.relative(root, file)
+        const rel = toPosixPath(path.relative(root, file), path.sep)
         if (matchGlob(rel, pattern)) found.push(rel)
       }
-      found.sort()
+      found.sort(compareCodePoints)
       return ok(found.slice(0, limit).join("\n"), { count: Math.min(found.length, limit) })
     },
   )

package/src/classifier.ts

@@ -10,9 +10,8 @@
  * here is a security control.
  */
 import type { Client } from "./client.js"
-import { type ErrorInfo, type ErrorTier, type MetricEvent } from "./client.js"
+import { type ErrorInfo, type ErrorTier, type MetricEvent, redactErrorBody, capErrorBody } from "./client.js"
 import { retryAfterMs, isRetryableStatus } from "./retry.js"
-import type { Toolkit } from "./toolkit.js"
 
 // ---------------------------------------------------------------- constants
 
@@ -25,6 +24,19 @@ export const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY"
 /** Bounds ONE request; a classifier has no loop to bound. */
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10_000
 
+/**
+ * A named BACKEND: `baseUrl`, `model` and `apiKeyEnv` are only jointly valid, so they travel as
+ * a UNIT (ADR 0027 D1). `jev-latest` is TypeSafe's spelling; the gateway spells the same model
+ * `typesafe/jev-1.13`, and mixing the two is issue #91.
+ */
+export type ClassifierBackend = "typesafe" | "openrouter"
+
+/** The two servable pairings, as configurations rather than six independently-choosable cells. */
+export const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, { baseUrl: string; model: string; apiKeyEnv: string }>> = {
+  typesafe: { baseUrl: DEFAULT_CLASSIFIER_BASE_URL, model: DEFAULT_CLASSIFIER_MODEL, apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV },
+  openrouter: { baseUrl: "https://openrouter.ai/api/v1", model: "typesafe/jev-1.13", apiKeyEnv: "OPENROUTER_API_KEY" },
+}
+
 /** Client-side cap on a choice's named options (§8B). */
 export const MAX_CHOICE_OPTIONS = 255
 /** Bounds of a score rubric (§8B). */
@@ -392,6 +404,11 @@ export type EvaluateFn = (
 export interface ClassifierOptions {
   /** Default `"systemone"`. */
   style?: ClassifierStyle
+  /** A named `baseUrl` + `model` + `apiKeyEnv` pairing (`"typesafe"` | `"openrouter"`), set as a
+   * UNIT. Default `"typesafe"`. The three individual options still win where given, for a
+   * self-hosted origin — but a known-bad mixture is refused at construction, not 700 ms later
+   * as an "Unknown model" 400. */
+  backend?: ClassifierBackend
   /** Default `https://api.typesafe.ai/v1`. OpenRouter serves this wire today. */
   baseUrl?: string
   /** Default `"jev-latest"`. Pin it once thresholds are tuned. */
@@ -456,9 +473,12 @@ export class Classifier {
 
   constructor(private readonly opts: ClassifierOptions) {
     this.style = opts.style ?? "systemone"
-    this.baseUrl = opts.baseUrl ?? DEFAULT_CLASSIFIER_BASE_URL
-    this.model = opts.model ?? DEFAULT_CLASSIFIER_MODEL
-    this.apiKeyEnv = opts.apiKeyEnv ?? DEFAULT_CLASSIFIER_API_KEY_ENV
+    const preset = CLASSIFIER_BACKENDS[opts.backend ?? "typesafe"]
+    this.baseUrl = opts.baseUrl ?? preset.baseUrl
+    this.model = opts.model ?? preset.model
+    this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv
+    const mismatch = backendMismatch(this.baseUrl, this.model)
+    if (mismatch) throw new Error(mismatch)
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS
     switch (this.style) {
       case "systemone":
@@ -706,7 +726,8 @@ export class Classifier {
       '{"type":"choice","choice":"<one offered option id>","probabilities":{"<every offered option id>":<0..1>},"confidence":<0..1>}. ' +
       'A "score" answer is {"type":"score","score":<a number within the rubric bounds, fractional allowed>,' +
       '"legend":{"0":"<level 0>",…},"probabilities":{"0":<0..1>,…},"confidence":<0..1>}.'
-    const run = await this.opts.client!.run(prompt, { toolkit: EMPTY_TOOLKIT, signal })
+    // No toolkit at all: a classifier has no loop and executes nothing (SPEC §0.10, ADR 0023).
+    const run = await this.opts.client!.run(prompt, { signal })
     const payload = firstJsonObject(run.text)
     let parsed: unknown
     try {
@@ -778,9 +799,21 @@ export function degenerateCriteria(criteria: Record<string, string>): string {
  */
 function cause(status: number, body: string): string {
   if (status === 401 || status === 403) return ""
-  const s = body.trim()
-  if (!s) return ""
-  return ": " + (s.length > 200 ? s.slice(0, 200) + "…" : s)
+  // ONE policy, now shared with the §8 client path: redact account identifiers, then cap.
+  const s = capErrorBody(redactErrorBody(body))
+  return s ? ": " + s : ""
+}
+
+/**
+ * The one mixture known to fail, caught before the wire: TypeSafe's unqualified `jev-*` model id
+ * pointed at the OpenRouter gateway, which has never heard of it. Returns the message to fail
+ * with, or `""` when the pairing is fine.
+ */
+export function backendMismatch(baseUrl: string, model: string): string {
+  const host = baseUrl.replace(/^[a-z]+:\/\//i, "").split("/")[0].split(":")[0].toLowerCase()
+  if (host !== "openrouter.ai" && !host.endsWith(".openrouter.ai")) return ""
+  if (!/^jev-/.test(model)) return ""
+  return `classifier: model "${model}" is TypeSafe's spelling; on openrouter.ai use "${CLASSIFIER_BACKENDS.openrouter.model}"`
 }
 
 /** `${ENV_VAR}` expands at call time; an unset var expands to the empty string, as §2. */
@@ -813,20 +846,3 @@ function sleep(ms: number): Promise<void> {
   })
 }
 
-/**
- * The `llm` style declares no tools — a classifier has no loop and executes nothing. The §8
- * `run` takes a Toolkit, so this is the empty one; the cast is the price of not exposing a
- * public "no tools" Toolkit constructor just for this path.
- */
-const EMPTY_TOOLKIT = {
-  skillsPrompt: () => "",
-  toOpenAI: () => [],
-  toAnthropic: () => [],
-  toGemini: () => [],
-  get: () => undefined,
-  list: () => [],
-  execute: async () => {
-    throw new Error("classifier: the llm style declares no tools")
-  },
-  close: async () => {},
-} as unknown as Toolkit