toolnexus 0.18.1 → 0.20.0

package/dist/acp.d.ts

@@ -0,0 +1,42 @@
+import type { InProcessRequest, InProcessResponse } from "./client.js";
+/** Options for {@link loadACP}. `command`/`args` spawn the ACP agent as a child
+ *  process; everything else tunes the session handshake. */
+export interface ACPOptions {
+    /** The ACP agent binary, e.g. `"devin"`. */
+    command: string;
+    /** Arguments to the agent, e.g. `["acp"]`. */
+    args?: string[];
+    /** Working directory for `session/new`. Real ACP agents (e.g. `devin acp`)
+     *  reject a relative `cwd` with `-32602 Invalid params` — this is always
+     *  resolved to an absolute path before it is sent. Default: `process.cwd()`. */
+    cwd?: string;
+    /** Extra environment variables for the child, merged over the current
+     *  process environment. */
+    env?: Record<string, string>;
+    /** ACP `initialize` protocolVersion. Default `1`. */
+    protocolVersion?: number;
+    /** Safety-net timeout (ms) for one `session/prompt` turn — NOT specifically
+     *  for the permission handshake, which this client always answers instantly.
+     *  It exists only so a broken/unresponsive agent cannot hang a caller
+     *  forever. Default 30000. */
+    permissionTimeoutMs?: number;
+    /** Optional `session/set_mode` sent once, right after `session/new`. */
+    mode?: string;
+}
+/** One warm ACP connection: one child process, one session, alive across many
+ *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
+ *  wants, so it plugs straight into {@link createInProcessClient}. */
+export interface ACPClient {
+    generate: (request: InProcessRequest) => Promise<InProcessResponse>;
+    /** Terminates the agent process. Idempotent — a second call is a no-op. */
+    close: () => Promise<void>;
+}
+/**
+ * Opens one ACP connection: spawns `command`, performs `initialize` →
+ * `session/new` (with an absolute `cwd` and an `mcpServers` array — the exact
+ * trap real `devin acp` enforces with `-32602` otherwise) → an optional
+ * `session/set_mode`, then returns a client whose `.generate` sends exactly
+ * one `session/prompt` per call, accumulating only `agent_message_chunk`
+ * text.
+ */
+export declare function loadACP(opts: ACPOptions): Promise<ACPClient>;

package/dist/acp.js

@@ -0,0 +1,246 @@
+/**
+ * ACP (Agent Client Protocol) model source — issue #96, ADR 0031
+ * ("ACP: the warm session is the feature, and it breaks the stateless request"),
+ * openspec/changes/add-acp-model-source.
+ *
+ * ACP is to *agents* what MCP is to *tools*: JSON-RPC 2.0, one object per line,
+ * over a child process's stdin/stdout (`devin acp`, Gemini CLI, Zed's agents all
+ * speak it). This file ships ACP as nothing more than a `generate` function —
+ * the exact shape {@link InProcessOptions.generate} already defines — so the
+ * tool-calling loop, skills, MCP tools, adapters and sub-agents are entirely
+ * untouched. `loadACP` opens the connection once (`initialize` → `session/new` →
+ * optional `session/set_mode`) and hands back an {@link ACPClient} whose
+ * `.generate` can be passed straight to {@link createInProcessClient}.
+ *
+ * The hard part is not the JSON-RPC plumbing — it is that an ACP session is
+ * *stateful* while every other toolnexus model source is stateless-by-default.
+ * toolnexus assembles a complete request every turn; sending the whole thing
+ * into a session that already remembers the transcript makes some agents answer
+ * a near-duplicate prompt from stale history (reproduced in `spikes/acp/`).
+ * The mitigation (kept as the default, not left to the caller) is an explicit
+ * "this supersedes everything earlier" marker appended to every rendered
+ * prompt — see {@link renderPrompt}.
+ *
+ * Three more traps this client exists to close, all proven in the spike:
+ *  - `session/update` notifications interleave with JSON-RPC replies on the
+ *    same stdout stream, so everything arriving is demultiplexed by id.
+ *  - Only `agent_message_chunk` text may be accumulated into the reply —
+ *    `agent_thought_chunk` and tool-call narration wrap prose around
+ *    structured output and corrupt it if mixed in.
+ *  - An unanswered `session/request_permission` hangs the turn FOREVER, even
+ *    in an agent's bypass mode. The client answers with the first `allow`-kind
+ *    option the instant the request arrives; `permissionTimeoutMs` is only a
+ *    safety net for a broken agent that never asks and never replies at all.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import path from "node:path";
+/** The literal marker every rendered prompt ends with, naming the current
+ *  turn as the one to answer. Kept as a named constant (not just inlined)
+ *  because the exact wording is shared, by convention, with the other
+ *  language ports and the spike that proved it fixes the stale-answer bug. */
+const SUPERSEDES_MARKER = "SUPERSEDES-ALL-PRIOR:";
+function renderContentPart(part) {
+    if (typeof part === "string")
+        return part;
+    if (part == null)
+        return "";
+    if (typeof part === "object" && "text" in part && typeof part.text === "string")
+        return part.text;
+    return JSON.stringify(part);
+}
+/** Flattens `content` (a string, or an array of content parts) to plain text. */
+function renderContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content.map(renderContentPart).join(" ");
+    return renderContentPart(content);
+}
+/** Renders the FULL assembled request as one prompt string — role + content
+ *  per message — then appends the supersedes marker naming the latest user
+ *  turn, per ADR 0031's proposed (and spike-confirmed) default: full request
+ *  every turn, not a delta, so this stays stateless like every other
+ *  toolnexus model source and never risks a shadow transcript drifting from
+ *  the caller's own conversation state. */
+function renderPrompt(request) {
+    const messages = request.messages ?? [];
+    const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content)}`);
+    let latest = "";
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === "user") {
+            latest = renderContent(messages[i].content);
+            break;
+        }
+    }
+    if (!latest && messages.length > 0)
+        latest = renderContent(messages[messages.length - 1]?.content);
+    lines.push(`${SUPERSEDES_MARKER} ${latest}`);
+    return lines.join("\n");
+}
+/**
+ * Opens one ACP connection: spawns `command`, performs `initialize` →
+ * `session/new` (with an absolute `cwd` and an `mcpServers` array — the exact
+ * trap real `devin acp` enforces with `-32602` otherwise) → an optional
+ * `session/set_mode`, then returns a client whose `.generate` sends exactly
+ * one `session/prompt` per call, accumulating only `agent_message_chunk`
+ * text.
+ */
+export async function loadACP(opts) {
+    const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+    const permissionTimeoutMs = opts.permissionTimeoutMs ?? 30000;
+    const child = spawn(opts.command, opts.args ?? [], {
+        cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        stdio: ["pipe", "pipe", "ignore"],
+    });
+    let closed = false;
+    let nextId = 0;
+    const pending = new Map();
+    let updateSink = null;
+    const rl = createInterface({ input: child.stdout });
+    rl.on("line", (raw) => {
+        const line = raw.trim();
+        if (!line)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        handleLine(msg);
+    });
+    function write(msg) {
+        child.stdin.write(JSON.stringify(msg) + "\n");
+    }
+    function reply(id, result) {
+        write({ jsonrpc: "2.0", id, result });
+    }
+    function call(method, params) {
+        const id = `c-${++nextId}`;
+        return new Promise((resolve, reject) => {
+            pending.set(id, (msg) => {
+                if (msg.error)
+                    reject(new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`));
+                else
+                    resolve(msg.result);
+            });
+            write({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    /** Demultiplexes EVERYTHING arriving on stdout: replies to our requests
+     *  (matched by JSON-RPC id), `session/update` notifications (interleaved
+     *  with replies, routed to whichever turn is in flight), and
+     *  server-initiated requests like `session/request_permission`. */
+    function handleLine(msg) {
+        if (msg.method === undefined && msg.id !== undefined) {
+            const cb = pending.get(String(msg.id));
+            if (cb) {
+                pending.delete(String(msg.id));
+                cb(msg);
+            }
+            return;
+        }
+        if (msg.method === "session/update") {
+            updateSink?.(msg.params);
+            return;
+        }
+        if (msg.method === "session/request_permission" && msg.id !== undefined) {
+            answerPermission(msg);
+            return;
+        }
+        // An unhandled server->client request still needs a reply or a
+        // strict agent may itself hang waiting on one.
+        if (msg.id !== undefined)
+            reply(msg.id, {});
+    }
+    /** Answers with the FIRST option whose `kind` starts with `allow` — an
+     *  unanswered permission request hangs the turn forever (proven in
+     *  spikes/acp). This runs the instant the request arrives, never waiting
+     *  for anything else. */
+    function answerPermission(req) {
+        const options = req.params?.options ?? [];
+        const chosen = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"));
+        const result = chosen
+            ? { outcome: { outcome: "selected", optionId: chosen.optionId } }
+            : { outcome: { outcome: "cancelled" } };
+        reply(req.id, result);
+    }
+    await call("initialize", {
+        protocolVersion: opts.protocolVersion ?? 1,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+    });
+    const sessionResult = await call("session/new", { cwd, mcpServers: [] });
+    const sessionId = sessionResult?.sessionId;
+    if (opts.mode) {
+        await call("session/set_mode", { sessionId, modeId: opts.mode });
+    }
+    // Serialises turns: one ACP session is one conversation, so concurrent
+    // prompts must not interleave into it. Idiomatic promise-chaining queue —
+    // each generate() call attaches after whatever is already queued, and the
+    // queue itself never rejects (a failed turn does not poison later ones).
+    let turnQueue = Promise.resolve();
+    async function promptOnce(request) {
+        const text = renderPrompt(request);
+        const id = `c-${++nextId}`;
+        let content = "";
+        updateSink = (params) => {
+            const update = params?.update;
+            if (update?.sessionUpdate === "agent_message_chunk") {
+                content += update?.content?.text ?? "";
+            }
+            // agent_thought_chunk and tool_call/tool_call_update narration are
+            // deliberately dropped — mixing them into the reply corrupts
+            // structured output a caller expects to parse.
+        };
+        const replyPromise = new Promise((resolve) => pending.set(id, resolve));
+        write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } });
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)), permissionTimeoutMs);
+        });
+        try {
+            const msg = await Promise.race([replyPromise, timeout]);
+            if (msg.error)
+                throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`);
+            return { content };
+        }
+        finally {
+            clearTimeout(timer);
+            pending.delete(id);
+            updateSink = null;
+        }
+    }
+    const generate = (request) => {
+        if (closed)
+            return Promise.reject(new Error("toolnexus: ACP client is closed"));
+        const turn = turnQueue.then(() => promptOnce(request));
+        turnQueue = turn.then(() => undefined, () => undefined);
+        return turn;
+    };
+    const close = () => {
+        if (closed)
+            return Promise.resolve();
+        closed = true;
+        rl.close();
+        return new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                resolve();
+                return;
+            }
+            const done = () => resolve();
+            child.once("exit", done);
+            child.kill();
+            // Belt-and-braces: resolve even if the child never emits `exit` (e.g.
+            // already reaped), so close() itself never hangs.
+            setTimeout(done, 1000);
+        });
+    };
+    const client = { generate, close };
+    // Non-enumerable, undocumented — internal test hook only, so the public
+    // ACPClient surface stays exactly {generate, close}.
+    Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false });
+    return client;
+}

package/dist/agents/agent.d.ts

@@ -31,7 +31,18 @@ export interface AgentSpec {
     budget?: Budget;
     /** Model id; default "inherit" (the runtime's `llm.model`). */
     model?: string;
-    /** §10 interpreter authority for this agent's subtree. */
+    /** §10 interpreter authority for this agent's subtree.
+     *
+     * 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>;
     onSpawn?: AgentDef["onSpawn"];
     onClose?: AgentDef["onClose"];

package/dist/agents/agent.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import { defineTool } from "../native.js";
-import { AgentRuntime, isVerbError } from "./runtime.js";
+import { AgentRuntime, isVerbError, S } from "./runtime.js";
 import { Loop, guardedHooks } from "./loop.js";
 export class Agent {
     name;
@@ -61,7 +61,8 @@ export class Agent {
         const runtime = this.createRuntime(opts);
         const h = runtime.spawn(runtime.root, this.name);
         if (isVerbError(h)) {
-            return { text: h.error, isError: true, status: "error", turns: 0, totalTokens: 0, runtime };
+            // A spawn refusal is an ERROR, not a limit stop: it names no `limit` (A18).
+            return { text: h.error, isError: true, status: S.error, turns: 0, totalTokens: 0, ownTokens: 0, runtime };
         }
         const woke = runtime.wake(h, prompt);
         if (!woke.ok) {

package/dist/agents/home.js

@@ -188,9 +188,11 @@ export function startAgent(a, run, hb) {
                 });
             }
         }
-        cancel = runtime.clock.setTimeout(beat, hb.everyMs); // self-reschedule → one live timer
+        // keepAlive:false — a heartbeat is housekeeping and must never be the reason
+        // a host process stays up.
+        cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false }); // self-reschedule → one live timer
     };
-    cancel = runtime.clock.setTimeout(beat, hb.everyMs);
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false });
     return {
         runtime,
         beats,

package/dist/agents/loop.d.ts

@@ -79,6 +79,27 @@ export declare function allTodosDone(result: RunResult): Verdict;
  * it owes an Answer or a fix.
  */
 export declare function runGated(ask: (prompt: PromptInput) => Promise<RunResult>, prompt: PromptInput, completion: Completion | undefined): Promise<RunResult>;
+/**
+ * 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 declare function loopUnsupported(spec: {
+    uses?: {
+        tools?: unknown[];
+    };
+    team?: unknown[];
+    waitFor?: unknown;
+    onMetric?: unknown;
+}): string[];
 /** A live execution of an Agent. Its only verbs are `run` and reading state. */
 export declare class Loop {
     #private;

package/dist/agents/loop.js

@@ -109,6 +109,31 @@ export async function runGated(ask, prompt, completion) {
         text: `completion.verify failed ${maxAttempts}×: ${reason}`,
     };
 }
+/**
+ * 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) {
+    const out = [];
+    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 {
     agent;
@@ -163,10 +188,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) {
+        const spec = this.agent.spec;
         const base = {
             ...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;

package/dist/agents/runtime.d.ts

@@ -15,17 +15,26 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import type { PromptInput } from "../content.js";
-import { type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js";
+import { type ClientStyle, type ConversationStore, type Hooks, type InProcessRequest, type InProcessResponse, type MetricEvent } from "../client.js";
 import { type Completion } from "./loop.js";
 import type { Answer, Request, Tool } from "../types.js";
 /** Injectable time source. All runtime timers, timeouts, and deadlines use it. */
 export interface Clock {
     /** Current time in ms (epoch or virtual). */
     now(): number;
-    /** Schedule `fn` after `ms`; returns a cancel function. */
-    setTimeout(fn: () => void, ms: number): () => void;
+    /** Schedule `fn` after `ms`; returns a cancel function.
+     *
+     * `keepAlive` defaults to TRUE, and the default is the important half: a timer
+     * that cannot hold the event loop open never fires when it is the only thing
+     * left to do — which is precisely a deadline whose promise nothing else will
+     * settle. Background housekeeping that should never hold a process open (a
+     * heartbeat) passes `false` explicitly. A host's own Clock may ignore the
+     * option; it then behaves as that host's timers always have. */
+    setTimeout(fn: () => void, ms: number, opts?: {
+        keepAlive?: boolean;
+    }): () => void;
 }
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export declare const systemClock: Clock;
 /** §7D hierarchical budget. Carved at spawn (`min(own, parent remaining)`) and
  * live-enforced against the whole ancestor chain before each turn and spawn.
@@ -93,6 +102,42 @@ export interface InboxItem {
     text: string;
 }
 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 declare const TASK_STATUSES: readonly ["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 declare const TASK_LIMITS: readonly ["maxTurns", "maxTokens", "maxToolCalls", "maxWallMs", "maxChildren", "maxConcurrent", "maxDepth", "completion", "timeout"];
+export type TaskLimit = (typeof TASK_LIMITS)[number];
+/** Map anything the internals produce onto the closed vocabulary; unknown ⇒ undefined, never a
+ *  leaked internal name. */
+export declare function canonicalLimit(limit: string | undefined): 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 declare const S: Readonly<Record<TaskStatus, TaskStatus>>;
+export declare const L: Readonly<Record<TaskLimit, TaskLimit>>;
+/**
+ * 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" | "incomplete" | "interrupted" | "closed" | "timeout" | "error";
 /** The result of one completed (or halted) turn, as seen by waiters and `task`. */
 export interface TaskResult {
@@ -102,8 +147,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). */
 export interface VerbError {
@@ -164,6 +224,8 @@ export declare class Handle {
     readonly deadline?: number;
     /** Total tokens attributed to this handle (own turns + descendant roll-up). */
     usageTotal: number;
+    /** Tokens spent by THIS handle's own turns, excluding descendants (ADR 0025 D1). */
+    ownTokens: number;
     /** Total tool calls attributed to this handle (own + descendant roll-up). */
     toolCallsTotal: number;
     /** LLM round trips run by this handle itself (never reset — resume grows it). */
@@ -202,8 +264,16 @@ export interface RuntimeOptions {
         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).
@@ -315,7 +385,7 @@ export declare class AgentRuntime {
      * REATTACHES to the existing child by task key — never spawns a duplicate.
      * The root alone may throw to the host.
      */
-    resume(answer: Answer): Promise<void>;
+    resume(answer: Answer): Promise<TaskResult>;
     private deepestSuspended;
     /**
      * Resume a suspended handle by REPLAYING its halted turn from the checkpoint: