toolnexus 0.18.1 → 0.20.0

package/dist/agents/runtime.js

@@ -1,16 +1,60 @@
-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";
-/** 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 const systemClock = {
     now: () => Date.now(),
-    setTimeout(fn, ms) {
+    setTimeout(fn, ms, opts) {
         const t = setTimeout(fn, ms);
-        t.unref?.();
+        if (opts?.keepAlive === false)
+            t.unref?.();
         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 +80,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 +158,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 +265,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 +291,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 +348,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 +382,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 +438,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 +464,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 +589,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 +657,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 +667,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 +693,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 +773,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.d.ts

@@ -1,9 +1,33 @@
 import type { Tool } from "./types.js";
-/** Config for the single global builtin toggle (mirrors MCP isEnabled precedence). */
+/**
+ * Config for the single global builtin toggle (mirrors MCP isEnabled precedence),
+ * plus the host boundary: which interpreter `bash` runs, what a relative path
+ * resolves against, and whether paths leaving it are refused (SPEC §4A, ADR 0034).
+ */
 export type BuiltinsConfig = boolean | {
     enabled?: boolean;
     disabled?: boolean;
     tools?: Record<string, boolean>;
+    /**
+     * The argv prefix `bash` runs a command with — `["sh","-c"]`,
+     * `["cmd","/d","/s","/c"]`, `["powershell","-NoProfile","-Command"]`. Set,
+     * it is used verbatim. Absent, an interpreter is DETECTED at toolkit
+     * construction (POSIX `sh -c`; Windows %COMSPEC% → pwsh → powershell → bash).
+     */
+    shell?: string[];
+    /**
+     * What a RELATIVE path means, for every builtin that touches the
+     * filesystem — including the paths inside apply_patch's patch text, and as
+     * bash's default workdir. Empty ⇒ the process cwd, i.e. today's behaviour.
+     */
+    baseDir?: string;
+    /**
+     * Refuse any path whose CANONICAL form leaves baseDir (symlinks, Windows
+     * junctions and short names resolved on both sides), and Windows reserved
+     * device names. Default off. A guarantee about path resolution in the file
+     * builtins, NOT a sandbox — `bash` still reaches the whole filesystem.
+     */
+    confineToBaseDir?: boolean;
 };
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
@@ -22,4 +46,10 @@ export declare function selectBuiltins(cfg: BuiltinsConfig | undefined): Tool[];
  * for parity: bash, read, write, edit, grep, glob, webfetch, question,
  * apply_patch, todowrite.
  */
-export declare function createBuiltinTools(): Tool[];
+export declare function createBuiltinTools(cfg?: BuiltinsConfig): Tool[];
+/**
+ * The interpreter the builtins resolved for `bash` — what a host prints, and
+ * what `metadata.shell` carries on every bash result. Throws the same error
+ * `selectBuiltins` fails construction with when nothing resolves.
+ */
+export declare function builtinShell(cfg?: BuiltinsConfig): string[];