toolnexus 0.18.0 → 0.19.0

package/dist/agents/runtime.js

@@ -1,4 +1,4 @@
-import { createClient, InMemoryConversationStore } from "../client.js";
+import { createClient, createInProcessFetch, InMemoryConversationStore, } from "../client.js";
 import { runGated } from "./loop.js";
 import { createToolkit } from "../toolkit.js";
 import { defineTool } from "../native.js";
@@ -11,6 +11,49 @@ export const systemClock = {
         return () => clearTimeout(t);
     },
 };
+/**
+ * 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",
+];
+/**
+ * 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",
+];
+/** Map anything the internals produce onto the closed vocabulary; unknown ⇒ undefined, never a
+ *  leaked internal name. */
+export function canonicalLimit(limit) {
+    return limit && TASK_LIMITS.includes(limit) ? limit : 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 = Object.freeze({
+    done: "done", pending: "pending", incomplete: "incomplete", interrupted: "interrupted",
+    closed: "closed", timeout: "timeout", error: "error",
+});
+export const L = Object.freeze({
+    maxTurns: "maxTurns", maxTokens: "maxTokens", maxToolCalls: "maxToolCalls", maxWallMs: "maxWallMs",
+    maxChildren: "maxChildren", maxConcurrent: "maxConcurrent", maxDepth: "maxDepth",
+    completion: "completion", timeout: "timeout",
+});
 /** Type guard for the `spawn` return union. */
 export function isVerbError(x) {
     return typeof x === "object" && x !== null && "error" in x && typeof x.error === "string";
@@ -36,6 +79,8 @@ export class Handle {
     deadline;
     /** 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). */
@@ -112,6 +157,18 @@ export class AgentRuntime {
     turnSlots;
     turnQueue = [];
     constructor(opts) {
+        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;
@@ -207,11 +264,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));
@@ -233,7 +290,7 @@ export class AgentRuntime {
                     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);
             }
         });
@@ -290,7 +347,7 @@ export class AgentRuntime {
         await h.def.onClose?.(h, reason);
         const prev = h.state;
         h.state = "closed";
-        const final = { text: "closed", isError: true, status: "closed", turns: h.turnsTotal, totalTokens: h.usageTotal };
+        const final = { 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})`);
@@ -324,13 +381,16 @@ export class AgentRuntime {
         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;
     }
     deepestSuspended(h) {
         for (const c of h.children) {
@@ -377,22 +437,25 @@ export class AgentRuntime {
         const now = this.clock.now();
         for (let a = h; a; a = a.parent) {
             if (a.pool.tokens <= 0)
-                return "maxTokens";
+                return L.maxTokens;
             if (a.pool.toolCalls <= 0)
-                return "maxToolCalls";
+                return L.maxToolCalls;
             if (a.deadline !== undefined && now >= a.deadline)
-                return "maxWallMs";
+                return L.maxWallMs;
         }
         return undefined;
     }
     /** Lifetime turn cap on the handle itself (turns never reset across resumes). */
     turnCap(h) {
-        return h.turnsTotal >= h.eff.maxTurns ? "maxTurns" : undefined;
+        return h.turnsTotal >= h.eff.maxTurns ? L.maxTurns : undefined;
     }
     /** A limit stop is LOUD: settle an incomplete result (never silent, never a throw). */
     settleRefused(h, limit) {
+        // `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 = { 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 = { 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);
@@ -400,6 +463,7 @@ export class AgentRuntime {
     }
     /** Usage roll-up IS the budget ledger: every ancestor's pool drains live. */
     rollUp(h, tokens, toolCalls) {
+        h.ownTokens += tokens; // own figure: outside the ancestor walk, by construction
         for (let a = h; a; a = a.parent) {
             a.usageTotal += tokens;
             a.toolCallsTotal += toolCalls;
@@ -524,7 +588,7 @@ export class AgentRuntime {
     }
     pendingResult(h) {
         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
      * escalation traced (nearest interpreter wins; the Request's `data.path` names
@@ -592,7 +656,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";
@@ -602,14 +666,18 @@ 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) {
@@ -624,8 +692,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 {
@@ -703,7 +772,7 @@ export class AgentRuntime {
                         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 {

package/dist/builtin.js

@@ -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 { pending } from "./types.js";
 import { mediaTypeFor } from "./content.js";
@@ -108,7 +109,9 @@ function walkFiles(root) {
         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;
@@ -311,11 +314,13 @@ function grepTool() {
         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 = [];
+        // 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 = [];
         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;
@@ -327,12 +332,12 @@ function grepTool() {
             }
             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]}`);
+                    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 });
     });
 }
@@ -352,15 +357,16 @@ function globTool() {
             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 = [];
         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/dist/classifier.d.ts

@@ -19,6 +19,18 @@ export declare const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 export declare const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Bounds ONE request; a classifier has no loop to bound. */
 export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10000;
+/**
+ * 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 declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, {
+    baseUrl: string;
+    model: string;
+    apiKeyEnv: string;
+}>>;
 /** Client-side cap on a choice's named options (§8B). */
 export declare const MAX_CHOICE_OPTIONS = 255;
 /** Bounds of a score rubric (§8B). */
@@ -217,6 +229,11 @@ export type EvaluateFn = (state: unknown, questions: Record<string, Question>, s
 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. */
@@ -332,3 +349,9 @@ export declare function createClassifier(opts?: ClassifierOptions): Classifier;
  * the reason, or "" when the criteria are fine.
  */
 export declare function degenerateCriteria(criteria: Record<string, string>): string;
+/**
+ * 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 declare function backendMismatch(baseUrl: string, model: string): string;

package/dist/classifier.js

@@ -1,3 +1,4 @@
+import { redactErrorBody, capErrorBody } from "./client.js";
 import { retryAfterMs, isRetryableStatus } from "./retry.js";
 // ---------------------------------------------------------------- constants
 /** The System One endpoint base. */
@@ -8,6 +9,11 @@ export const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 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;
+/** The two servable pairings, as configurations rather than six independently-choosable cells. */
+export const CLASSIFIER_BACKENDS = {
+    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). */
@@ -261,9 +267,13 @@ export class Classifier {
     constructor(opts) {
         this.opts = opts;
         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":
@@ -512,7 +522,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;
         try {
@@ -579,10 +590,22 @@ export function degenerateCriteria(criteria) {
 function cause(status, body) {
     if (status === 401 || status === 403)
         return "";
-    const s = body.trim();
-    if (!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, model) {
+    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 ": " + (s.length > 200 ? s.slice(0, 200) + "…" : s);
+    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. */
 function expandEnv(value) {
@@ -611,20 +634,3 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
-/**
- * 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 () => { },
-};

package/dist/client.d.ts

@@ -41,7 +41,18 @@ export interface ClientOptions {
     /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
      * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
      * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
-     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later.
+     *
+     * IDEMPOTENCY CONTRACT (SPEC §7D rewind-to-checkpoint). A durable resume REPLAYS the suspended
+     * turn from its PRE-TURN checkpoint: "continues from its checkpoint" means the transcript is
+     * REWOUND, not carried. EVERY tool that ran in that turn RUNS AGAIN, and the suspended tool
+     * itself is always re-executed (with `ctx.answer`) — that is §10's resolution mechanism, not a
+     * bug. Reattachment by task key makes a re-run `task` call idempotent; a leaf agent's own
+     * side-effecting tools (`git push`, a charge, a delete) have NO equivalent and are the host's
+     * responsibility. Any tool reachable in a suspendable turn must be idempotent.
+     * Replaying the leaf's stored transcript instead is DEFERRED to its own change; it would not
+     * remove this requirement anyway.
+     */
     waitFor?: (request: Request) => Promise<Answer>;
     /** §8 Gap 1. Extra top-level keys shallow-merged into EVERY LLM body after the client builds
      * its own — a requestParams key WINS on collision (e.g. max_tokens overrides the anthropic
@@ -68,6 +79,60 @@ export interface ClientOptions {
      * text placeholder. Unset ⇒ attached parts error, derived parts degrade. */
     onUnsupportedPart?: UnsupportedPartMode;
 }
+/**
+ * The §8 CLIENT status vocabulary, as a value. It is a DIFFERENT, smaller closed set than the
+ * §7D AGENT vocabulary (`agents.TASK_STATUSES`), which also contains `"timeout"`, `"closed"`,
+ * `"interrupted"` and `"error"`. Two fields are called `status`; they are not interchangeable.
+ * A run that fails at a deadline THROWS here — it never comes back as a `RunResult`.
+ */
+export declare const RUN_STATUSES: readonly ["done", "pending", "incomplete"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+/** Account-identifier keys blanked out of a provider error body before it reaches a message,
+ *  a log or a metric. The shape survives; the value does not (ADR 0027 D3.2). */
+export declare const REDACTED_BODY_KEYS: readonly ["user_id", "account_id", "org_id", "organization"];
+/** What a redacted value is replaced with — identical in all seven ports. */
+export declare const REDACTION_PLACEHOLDER = "\u00ABredacted\u00BB";
+/** A redacted body is capped at this many characters IN THE MESSAGE ONLY. The typed `body`
+ *  field carries the full redacted body — a host that opted into a typed error asked for the
+ *  whole thing (ADR 0027 D3 / addendum A5). */
+export declare const ERROR_BODY_CAP = 200;
+/**
+ * Redact known account identifiers, then cap. A CAP IS NOT REDACTION: the body that leaked
+ * `user_2…` in issue #92 was 96 bytes, well inside the cap, so both steps are needed and
+ * redaction runs FIRST (capping first could split a key/value pair and hide it from the regex).
+ */
+export declare function redactErrorBody(body: string): string;
+/** Cap a already-redacted body for interpolation into a MESSAGE. Redaction is not a cap and a
+ *  cap is not redaction: they are independent and both are needed. */
+export declare function capErrorBody(body: string): string;
+/**
+ * A provider failure carried as a VALUE, not a sentence (ADR 0027 D3.1). A host that must
+ * decide what to log can read `status` / `retryAfter` instead of parsing a message.
+ *
+ * `body` is ALREADY redacted and capped, and is `""` on 401/403 — an auth body routinely
+ * reflects the credential or the header that was sent. `rawBody` is never populated by the
+ * library; the SPEC credentials guarantee now covers error messages too.
+ */
+export declare class LlmHttpError extends Error {
+    /** The HTTP status the provider answered with. */
+    readonly status: number;
+    /** The provider's FULL redacted body; `""` on 401/403 and when empty. Uncapped — the cap
+     *  applies to `message` only. */
+    readonly body: string;
+    /** The `Retry-After` header verbatim, when the provider sent one. */
+    readonly retryAfter?: string | undefined;
+    readonly name = "LlmHttpError";
+    constructor(
+    /** The HTTP status the provider answered with. */
+    status: number, 
+    /** The provider's FULL redacted body; `""` on 401/403 and when empty. Uncapped — the cap
+     *  applies to `message` only. */
+    body: string, 
+    /** The `Retry-After` header verbatim, when the provider sent one. */
+    retryAfter?: string | undefined);
+}
+/** Build the typed error from a non-2xx provider response (reads the body once). */
+export declare function llmHttpError(res: Response): Promise<LlmHttpError>;
 /** §8 Resilience. What to do with a failed LLM call. */
 export type ErrorTier = "retry" | "fail";
 /** §8 Resilience. Context passed to `onError` for each failed LLM attempt. */
@@ -284,8 +349,14 @@ export declare class Client {
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
-    run(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    /**
+     * Run the loop. `ctx` — and `ctx.toolkit` inside it — are OPTIONAL: an absent toolkit is a
+     * COMPLETION (SPEC §0.10). The system message is then the system prompt alone, and the
+     * request body carries no `tools` and no `tool_choice` key (not an empty array). An empty
+     * toolkit and no toolkit are observably identical on the wire.
+     */
+    run(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         signal?: AbortSignal;
         history?: any[];
     }): Promise<RunResult>;
@@ -317,15 +388,15 @@ export declare class Client {
      * the answer — so the next `ask` with the same `id` continues it. Without an
      * `id` it is a stateless one-shot (identical to `run`).
      */
-    ask(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    ask(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         id?: string;
         on_text?: (delta: string) => void;
         signal?: AbortSignal;
     }): Promise<RunResult>;
     /** A stateful multi-turn conversation that retains history across sends. */
-    conversation(ctx: {
-        toolkit: Toolkit;
+    conversation(ctx?: {
+        toolkit?: Toolkit;
         signal?: AbortSignal;
     }): Conversation;
     /**
@@ -333,11 +404,13 @@ export declare class Client {
      * With an `id`, it is stateful (like `ask`): the thread's transcript is loaded as history before
      * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
      */
-    stream(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    stream(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         id?: string;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, void, unknown>;
+    /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
+     *  the system message is the system prompt alone. This deref was issue #86 (ADR 0023). */
     private system;
     /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
     private makeSignal;
@@ -400,6 +473,17 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
     /** Your model. Receives the assembled request, returns one assistant message. */
     generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
 };
+/**
+ * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
+ * the reusable piece of {@link createInProcessClient} — assembles the wire request,
+ * calls `generate`, and re-encodes its answer as an OpenAI-shaped `Response`. Every
+ * caller that wants an in-process model behind a `fetch` slot (the top-level client,
+ * or the agent runtime's `inProcess` option) goes through this ONE function, so there
+ * is no second copy of the request/response assembly to drift.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export declare function createInProcessFetch(generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>): typeof fetch;
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -407,18 +491,20 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
  * This is a second constructor, not a second seam: it builds on the same injectable
  * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
  * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
+ * is just that adapter wired into a `Client`.
  *
- * Streaming is refused rather than faked — see the thrown error.
+ * Streaming is refused rather than faked — see {@link createInProcessFetch}.
  */
 export declare function createInProcessClient(opts: InProcessOptions): Client;
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export declare class Conversation {
     private readonly client;
-    private readonly toolkit;
+    private readonly toolkit?;
     private readonly signal?;
     /** Full running transcript (system + user + assistant + tool messages). */
     messages: any[];
-    constructor(client: Client, toolkit: Toolkit, signal?: AbortSignal | undefined);
+    constructor(client: Client, toolkit?: Toolkit | undefined, signal?: AbortSignal | undefined);
     /** Send the next user turn; prior history is retained automatically. */
     send(prompt: PromptInput): Promise<RunResult>;
     /** Reset the conversation memory. */