toolnexus 0.20.0 → 0.22.0

package/dist/models.js

@@ -0,0 +1,46 @@
+/**
+ * listModels (SPEC §4C): the models a provider offers, for model switching. One GET per page,
+ * no retries. Same key rules as the client (apiKey, apiKeyEnv, or the host's own env var).
+ */
+import { resolveKey } from "./client.js";
+async function getJson(f, url, headers, signal) {
+    const res = await f(url, { method: "GET", headers, signal });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`list models: HTTP ${res.status}: ${text.slice(0, 300)}`);
+    return JSON.parse(text);
+}
+/**
+ * List the models at `opts.baseUrl` in `opts.style`: openai `GET {base}/models`; anthropic
+ * `GET {base}/v1/models`, following `has_more`/`last_id`. Sorted by id.
+ */
+export async function listModels(opts, ctx) {
+    const key = resolveKey(opts);
+    const f = opts.fetch ?? fetch;
+    const base = opts.baseUrl.replace(/\/+$/, "");
+    const out = [];
+    if (opts.style === "anthropic") {
+        const endpoint = base.endsWith("/v1") ? `${base}/models` : `${base}/v1/models`;
+        let after = "";
+        for (let page = 0; page < 100; page++) {
+            const url = `${endpoint}?limit=1000${after ? `&after_id=${encodeURIComponent(after)}` : ""}`;
+            const body = await getJson(f, url, { "x-api-key": key, "anthropic-version": "2023-06-01", ...opts.headers }, ctx?.signal);
+            for (const m of body?.data ?? [])
+                out.push({ id: m.id, ...(m.display_name ? { name: m.display_name } : {}) });
+            if (!body?.has_more || !body?.last_id)
+                break;
+            after = body.last_id;
+        }
+    }
+    else {
+        const body = await getJson(f, `${base}/models`, { Authorization: `Bearer ${key}`, ...opts.headers }, ctx?.signal);
+        for (const m of body?.data ?? []) {
+            out.push({
+                id: m.id,
+                ...(m.name ? { name: m.name } : {}),
+                ...(typeof m.context_length === "number" && m.context_length > 0 ? { contextLength: m.context_length } : {}),
+            });
+        }
+    }
+    return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/dist/promptcache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Prompt caching (SPEC §8 "Prompt caching", change add-prompt-cache). The engine keeps the
+ * request prefix stable and marks it for the provider's cache.
+ */
+/** `ClientOptions.promptCache`. */
+export interface PromptCacheOptions {
+    /** Groups requests that share a prefix (one per session). Sent as openai `prompt_cache_key`.
+     * Ignored by anthropic, which caches by prefix. */
+    key?: string;
+    /** Ask for the provider's longer cache lifetime where one exists (anthropic `ttl: "1h"`). */
+    longTTL?: boolean;
+}
+/**
+ * Mark the cacheable prefix in an assembled body, in place. The transcript's own objects are
+ * never mutated: every touched entry is copied.
+ *  - anthropic: `cache_control` on the last tool, the system prompt (a string becomes one text
+ *    block) and the last content block of the latest message (3 of the 4 allowed breakpoints).
+ *  - openai: `prompt_cache_key = key` when set; the prefix is cached automatically.
+ *  - gemini: nothing yet (explicit cachedContent is deferred).
+ */
+export declare function applyPromptCache(body: Record<string, any>, style: string, o: PromptCacheOptions): void;

package/dist/promptcache.js

@@ -0,0 +1,59 @@
+/**
+ * Prompt caching (SPEC §8 "Prompt caching", change add-prompt-cache). The engine keeps the
+ * request prefix stable and marks it for the provider's cache.
+ */
+function withCacheControl(v, mark) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return v;
+    return { ...v, cache_control: mark };
+}
+/**
+ * Mark the cacheable prefix in an assembled body, in place. The transcript's own objects are
+ * never mutated: every touched entry is copied.
+ *  - anthropic: `cache_control` on the last tool, the system prompt (a string becomes one text
+ *    block) and the last content block of the latest message (3 of the 4 allowed breakpoints).
+ *  - openai: `prompt_cache_key = key` when set; the prefix is cached automatically.
+ *  - gemini: nothing yet (explicit cachedContent is deferred).
+ */
+export function applyPromptCache(body, style, o) {
+    if (style === "anthropic") {
+        const mark = { type: "ephemeral" };
+        if (o.longTTL)
+            mark.ttl = "1h";
+        if (Array.isArray(body.tools) && body.tools.length > 0) {
+            const out = [...body.tools];
+            out[out.length - 1] = withCacheControl(out[out.length - 1], mark);
+            body.tools = out;
+        }
+        if (typeof body.system === "string") {
+            if (body.system !== "")
+                body.system = [{ type: "text", text: body.system, cache_control: mark }];
+        }
+        else if (Array.isArray(body.system) && body.system.length > 0) {
+            const out = [...body.system];
+            out[out.length - 1] = withCacheControl(out[out.length - 1], mark);
+            body.system = out;
+        }
+        if (Array.isArray(body.messages) && body.messages.length > 0) {
+            const out = [...body.messages];
+            const last = out[out.length - 1];
+            if (last && typeof last === "object" && !Array.isArray(last)) {
+                const m = { ...last };
+                if (typeof m.content === "string") {
+                    m.content = [{ type: "text", text: m.content, cache_control: mark }];
+                }
+                else if (Array.isArray(m.content) && m.content.length > 0) {
+                    const blocks = [...m.content];
+                    blocks[blocks.length - 1] = withCacheControl(blocks[blocks.length - 1], mark);
+                    m.content = blocks;
+                }
+                out[out.length - 1] = m;
+            }
+            body.messages = out;
+        }
+    }
+    else if (style === "openai") {
+        if (o.key)
+            body.prompt_cache_key = o.key;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,32 @@
+import { type ConversationEntry, type ConversationStore } from "./client.js";
+/**
+ * Durable {@link ConversationStore}: one file `<root>/<id>.json` per conversation holding
+ * `{"version":1,"messages":[...]}`. `save` writes a temp file (0600), fsyncs and renames it over
+ * the old one, so a reader sees the old or the new transcript, never a torn one (power-loss
+ * durability of the rename is best-effort). Same-id saves are serialized in-process; across
+ * processes the last rename wins.
+ */
+/**
+ * Durability mode (SPEC §8 "Durability mode"): `full` (default) flushes the file then fsyncs the
+ * directory best-effort; `fsync` flushes the file only; `none` skips every flush. Temp-then-rename
+ * holds in every mode. (On macOS Node's `fh.sync()` is libuv's fsync, which already issues
+ * `F_FULLFSYNC`; Node exposes no plainer flush, so `fsync` differs from `full` only by the dir fsync.)
+ */
+export type FileStoreSync = "full" | "fsync" | "none";
+export interface FileStoreOptions {
+    sync?: FileStoreSync;
+}
+export declare class FileConversationStore implements ConversationStore {
+    readonly root: string;
+    readonly sync: FileStoreSync;
+    private readonly chains;
+    constructor(root: string, opts?: FileStoreOptions);
+    private file;
+    get(id: string): Promise<any[] | undefined>;
+    save(id: string, messages: any[]): Promise<void>;
+    private write;
+    /** Every stored conversation, newest first (mtime; ties by id ascending). Bodies are not parsed. */
+    list(): Promise<ConversationEntry[]>;
+    /** Remove a conversation; absent ids are not an error. */
+    delete(id: string): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,131 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { sortEntries } from "./client.js";
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const VERSION = 1;
+function checkId(id) {
+    if (typeof id !== "string" || !ID_RE.test(id) || id === "." || id === "..") {
+        throw new Error(`invalid conversation id: ${JSON.stringify(id)}`);
+    }
+}
+export class FileConversationStore {
+    root;
+    sync;
+    chains = new Map();
+    constructor(root, opts = {}) {
+        if (typeof root !== "string" || root === "")
+            throw new Error("FileConversationStore: root is required");
+        const mode = opts.sync ?? "full";
+        if (mode !== "full" && mode !== "fsync" && mode !== "none") {
+            throw new Error(`FileConversationStore: unknown sync mode ${JSON.stringify(opts.sync)}`);
+        }
+        this.root = root;
+        this.sync = mode;
+    }
+    file(id) {
+        return path.join(this.root, id + ".json");
+    }
+    async get(id) {
+        checkId(id);
+        let text;
+        try {
+            text = await fsp.readFile(this.file(id), "utf8");
+        }
+        catch (e) {
+            if (e?.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error(`conversation "${id}": corrupt file: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (body === null || typeof body !== "object" || body.version !== VERSION) {
+            throw new Error(`conversation "${id}": unsupported version ${JSON.stringify(body?.version)}`);
+        }
+        if (!Array.isArray(body.messages))
+            throw new Error(`conversation "${id}": corrupt file: messages is not an array`);
+        return body.messages;
+    }
+    async save(id, messages) {
+        checkId(id);
+        const prev = this.chains.get(id) ?? Promise.resolve();
+        const next = prev.catch(() => { }).then(() => this.write(id, messages));
+        this.chains.set(id, next);
+        try {
+            await next;
+        }
+        finally {
+            if (this.chains.get(id) === next)
+                this.chains.delete(id);
+        }
+    }
+    async write(id, messages) {
+        await fsp.mkdir(this.root, { recursive: true, mode: 0o700 });
+        const tmp = path.join(this.root, `.${id}.${randomBytes(6).toString("hex")}.tmp`);
+        const data = JSON.stringify({ version: VERSION, messages });
+        let fh;
+        try {
+            fh = await fsp.open(tmp, "w", 0o600);
+            await fh.writeFile(data, "utf8");
+            if (this.sync !== "none")
+                await fh.sync();
+            await fh.close();
+            fh = undefined;
+            await fsp.rename(tmp, this.file(id));
+        }
+        catch (e) {
+            await fh?.close().catch(() => { });
+            await fsp.rm(tmp, { force: true }).catch(() => { });
+            throw e;
+        }
+        // Best-effort parent-dir fsync so the rename itself survives power loss where supported.
+        if (this.sync !== "full")
+            return;
+        try {
+            const dir = await fsp.open(this.root, "r");
+            await dir.sync().catch(() => { });
+            await dir.close();
+        }
+        catch { }
+    }
+    /** Every stored conversation, newest first (mtime; ties by id ascending). Bodies are not parsed. */
+    async list() {
+        let names;
+        try {
+            names = await fsp.readdir(this.root);
+        }
+        catch (e) {
+            if (e?.code === "ENOENT")
+                return [];
+            throw e;
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const id = name.slice(0, -5);
+            if (!ID_RE.test(id) || id === "." || id === "..")
+                continue;
+            try {
+                const st = await fsp.stat(path.join(this.root, name));
+                if (st.isFile())
+                    out.push({ id, updatedAt: st.mtime });
+            }
+            catch (e) {
+                if (e?.code !== "ENOENT")
+                    throw e;
+            }
+        }
+        return sortEntries(out);
+    }
+    /** Remove a conversation; absent ids are not an error. */
+    async delete(id) {
+        checkId(id);
+        await fsp.rm(this.file(id), { force: true });
+    }
+}

package/dist/tooltiers.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tool tiers (SPEC §8 "Prompt caching" → Tool tiers, change add-prompt-cache phase 2). With
+ * `ClientOptions.toolTiers` set, only CORE tools are sent with full schemas. LISTED tools appear
+ * as "name — one line" and DEFERRED tools by name only, both inside the description of a
+ * `tool_search` tool that returns full schemas on demand, as a tool result: the tools array
+ * never changes mid-session, so the cached prefix survives. A loaded tool is called by name, or
+ * through `call_tool {name, arguments}`, which the loop unwraps BEFORE hooks.
+ */
+import type { Tool, ToolResult } from "./types.js";
+/** `ClientOptions.toolTiers`. */
+export interface ToolTierOptions {
+    /** Always sent with their full schema. */
+    core?: string[];
+    /** Named only. Every other tool is listed (name + one line). A tool registered after the
+     * plan froze is deferred and found by search. */
+    deferred?: string[];
+    /** Caps the tokens sent up front (core schemas + tool_search + call_tool). Absent/0 ⇒ 5% of
+     * `contextWindow`; both absent ⇒ no budget. Over budget, the least-used core tools move to
+     * listed, then the least-used listed tools to deferred. */
+    budgetTokens?: number;
+    contextWindow?: number;
+    /** Host per-tool usage stat (higher = more used), read only when the plan is built. */
+    usageCount?: (name: string) => number;
+    /** Token estimate of a JSON-encodable value; default ceil(bytes/4). */
+    countTokens?: (v: unknown) => number;
+}
+export type ToolTier = "core" | "listed" | "deferred";
+/** The frozen tier assignment for one toolkit. */
+export interface ToolPlan {
+    tier: Map<string, ToolTier>;
+    core: string[];
+    listed: string[];
+    deferred: string[];
+    search: Tool;
+    call: Tool;
+}
+export declare function defaultCountTokens(v: unknown): number;
+export declare function toolDef(t: Tool): Record<string, unknown>;
+/** Build a tier plan over `tools` (exported for tests and host UIs). */
+export declare function buildToolPlan(o: ToolTierOptions, tools: Tool[]): ToolPlan;
+/** `call_tool {name, arguments}` → the real call; `undefined` when `name` is not call_tool. */
+export declare function unwrapCallTool(name: string, args: Record<string, unknown>): {
+    name: string;
+    args: Record<string, unknown>;
+} | undefined;
+/** Go's json escapes `<`, `>`, `&`, U+2028 and U+2029 inside strings; they never occur outside one. */
+export declare function goHtmlEscape(json: string): string;
+/** Run `tool_search` over every tool (any tier). */
+export declare function toolSearch(all: Tool[], get: (name: string) => Tool | undefined, args: Record<string, unknown>): ToolResult;

package/dist/tooltiers.js

@@ -0,0 +1,197 @@
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export function defaultCountTokens(v) {
+    return Math.ceil(Buffer.byteLength(JSON.stringify(v) ?? "", "utf8") / 4);
+}
+export function toolDef(t) {
+    return { name: t.name, description: t.description, inputSchema: t.inputSchema };
+}
+function firstLine(s) {
+    const i = s.indexOf("\n");
+    if (i >= 0)
+        s = s.slice(0, i);
+    // Go cuts at 120 BYTES; cut at 120 UTF-8 bytes too, without splitting a character.
+    if (Buffer.byteLength(s, "utf8") > 120) {
+        let out = "";
+        for (const ch of s) {
+            if (Buffer.byteLength(out + ch, "utf8") > 120)
+                break;
+            out += ch;
+        }
+        s = out + "…";
+    }
+    return s;
+}
+const notRun = async () => ({ output: "engine-internal tool: run by the client loop", isError: true });
+function rebuild(p, byName) {
+    p.core = [];
+    p.listed = [];
+    p.deferred = [];
+    for (const [n, t] of p.tier)
+        (t === "core" ? p.core : t === "listed" ? p.listed : p.deferred).push(n);
+    p.core.sort(cmp);
+    p.listed.sort(cmp);
+    p.deferred.sort(cmp);
+    let d = 'Load the full schema of tools that are not shown in full, then call them by name (or with call_tool). Query by keywords, or "select:a,b" for exact names.';
+    if (p.listed.length) {
+        d += "\n\nAvailable tools:";
+        for (const n of p.listed) {
+            d += "\n- " + n;
+            const line = firstLine(byName.get(n)?.description ?? "");
+            if (line)
+                d += " — " + line;
+        }
+    }
+    if (p.deferred.length)
+        d += "\n\nMore tools (name only): " + p.deferred.join(", ");
+    p.search = {
+        name: "tool_search",
+        description: d,
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Keywords, or select:name1,name2" },
+                limit: { type: "number", description: "Maximum results for a keyword query (default 5)" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        source: "builtin",
+        hints: { readOnly: true, destructive: false, openWorld: false },
+        execute: notRun,
+    };
+    p.call = {
+        name: "call_tool",
+        description: "Call a tool loaded with tool_search, by name, with its arguments.",
+        inputSchema: {
+            type: "object",
+            properties: { name: { type: "string" }, arguments: { type: "object" } },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        source: "builtin",
+        execute: notRun,
+    };
+}
+/** Build a tier plan over `tools` (exported for tests and host UIs). */
+export function buildToolPlan(o, tools) {
+    const count = o.countTokens ?? defaultCountTokens;
+    const usage = (n) => (o.usageCount ? o.usageCount(n) : 0);
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const tier = new Map();
+    for (const t of tools)
+        tier.set(t.name, "listed");
+    for (const n of o.deferred ?? [])
+        if (tier.has(n))
+            tier.set(n, "deferred");
+    for (const n of o.core ?? [])
+        if (tier.has(n))
+            tier.set(n, "core");
+    const p = { tier };
+    rebuild(p, byName);
+    let budget = o.budgetTokens ?? 0;
+    if (!budget && o.contextWindow && o.contextWindow > 0)
+        budget = Math.floor(o.contextWindow / 20);
+    if (budget > 0) {
+        const cost = () => {
+            let n = count(toolDef(p.search)) + count(toolDef(p.call));
+            for (const name of p.core)
+                n += count(toolDef(byName.get(name)));
+            return n;
+        };
+        // least used first; ties: bigger schema first, then name
+        const order = (names) => [...names].sort((a, b) => {
+            const ua = usage(a), ub = usage(b);
+            if (ua !== ub)
+                return ua - ub;
+            const sa = count(toolDef(byName.get(a))), sb = count(toolDef(byName.get(b)));
+            if (sa !== sb)
+                return sb - sa;
+            return cmp(a, b);
+        });
+        for (const n of order(p.core)) {
+            if (cost() <= budget)
+                break;
+            tier.set(n, "listed");
+            rebuild(p, byName);
+        }
+        for (const n of order(p.listed)) {
+            if (cost() <= budget)
+                break;
+            tier.set(n, "deferred");
+            rebuild(p, byName);
+        }
+    }
+    return p;
+}
+/** `call_tool {name, arguments}` → the real call; `undefined` when `name` is not call_tool. */
+export function unwrapCallTool(name, args) {
+    if (name !== "call_tool")
+        return undefined;
+    const real = typeof args?.name === "string" ? args.name : "";
+    const inner = args?.arguments && typeof args.arguments === "object" && !Array.isArray(args.arguments) ? args.arguments : {};
+    return { name: real, args: inner };
+}
+/** Keys sorted at every level, so the loaded definitions print the same bytes as the Go port. */
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort(cmp))
+            out[k] = sortKeys(v[k]);
+        return out;
+    }
+    return v;
+}
+/** Go's json escapes `<`, `>`, `&`, U+2028 and U+2029 inside strings; they never occur outside one. */
+export function goHtmlEscape(json) {
+    return json.replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/** Run `tool_search` over every tool (any tier). */
+export function toolSearch(all, get, args) {
+    const q = (typeof args.query === "string" ? args.query : "").trim();
+    if (!q)
+        return { output: "tool_search: query is required", isError: true };
+    let picked = [];
+    if (q.startsWith("select:")) {
+        const missing = [];
+        for (const raw of q.slice("select:".length).split(",")) {
+            const n = raw.trim();
+            if (!n)
+                continue;
+            const t = get(n);
+            if (t)
+                picked.push(t);
+            else
+                missing.push(n);
+        }
+        if (missing.length && !picked.length)
+            return { output: "tool_search: no such tool: " + missing.join(", "), isError: true };
+    }
+    else {
+        const limit = typeof args.limit === "number" && args.limit >= 1 ? Math.trunc(args.limit) : 5;
+        const terms = q.toLowerCase().split(/\s+/).filter(Boolean);
+        const hits = [];
+        for (const t of all) {
+            const name = t.name.toLowerCase(), desc = t.description.toLowerCase();
+            let s = 0;
+            for (const term of terms) {
+                if (name.includes(term))
+                    s += 3;
+                if (desc.includes(term))
+                    s += 1;
+            }
+            if (s > 0)
+                hits.push({ t, score: s });
+        }
+        hits.sort((a, b) => b.score - a.score || cmp(a.t.name, b.t.name));
+        picked = hits.slice(0, limit).map((h) => h.t);
+    }
+    if (!picked.length)
+        return { output: "No matching tools.", isError: false, metadata: { count: 0 } };
+    return {
+        output: "Loaded tools (call by name, or with call_tool):\n" + goHtmlEscape(JSON.stringify(sortKeys(picked.map(toolDef)), null, 2)),
+        isError: false,
+        metadata: { count: picked.length, tools: picked.map((t) => t.name) },
+    };
+}

package/dist/types.d.ts

@@ -27,6 +27,22 @@ export interface ToolContext {
     timeout?: number;
     /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
     answer?: Answer;
+    /** The model's id for this tool call, set by the client loop (§4C). A message's calls run
+     * concurrently, so this is how a tool tells its sibling calls apart. Absent outside the loop. */
+    callId?: string;
+}
+/**
+ * Advisory behavior hints (named after MCP tool annotations, §4C), for host permission gates
+ * built on `hooks.beforeTool`. Absent on a tool = unknown; treat it as mutating. Never sent to
+ * the model: no adapter or wire output carries them.
+ */
+export interface ToolHints {
+    /** The tool does not change its environment. */
+    readOnly: boolean;
+    /** The tool may overwrite or delete things (meaningful when not readOnly). */
+    destructive: boolean;
+    /** The tool reaches outside the host (network, external systems). */
+    openWorld: boolean;
 }
 /**
  * §10 Suspension. A tool that needs an out-of-band, async resolution (login, approval,
@@ -77,6 +93,9 @@ export interface Tool {
     inputSchema: JSONSchema;
     source: ToolSource;
     execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
+    /** What the tool may do (§4C). Builtins always carry hints; MCP tools carry them when the
+     * server sends annotations. Advisory: a server can mislabel its tools. */
+    hints?: ToolHints;
 }
 export type McpStatus = "connected" | "disabled" | "failed";
 /** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts test/host-boundary.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts"

package/src/agents/agent.ts

@@ -10,7 +10,7 @@
 import type { PromptInput } from "../content.js"
 import fs from "node:fs"
 import { defineTool } from "../native.js"
-import type { Answer, Request, Tool } from "../types.js"
+import type { Answer, Request, Tool, ToolContext } from "../types.js"
 import { AgentRuntime, isVerbError, S, type AgentDef, type Budget, type Handle, type RuntimeOptions, type TaskResult } from "./runtime.js"
 import { Loop, guardedHooks, type Completion, type Guardrail } from "./loop.js"
 import type { ClientOptions } from "../client.js"
@@ -141,6 +141,27 @@ export class Agent {
     return { ...r, runtime }
   }
 
+  /** `run` that interrupts the child when `signal` aborts. */
+  private async runSignal(prompt: string, opts: AgentRunOptions, signal?: AbortSignal): Promise<{ text: string; isError: boolean; turns: number; totalTokens: number; cancelled?: boolean }> {
+    if (!signal) return this.run(prompt, opts)
+    const reason = () => (signal.reason instanceof Error ? signal.reason.message : String(signal.reason ?? "aborted"))
+    if (signal.aborted) return { text: reason(), isError: true, turns: 0, totalTokens: 0, cancelled: true }
+    const runtime = this.createRuntime(opts)
+    const h = runtime.spawn(runtime.root, this.name)
+    if (isVerbError(h)) return { text: h.error, isError: true, turns: 0, totalTokens: 0 }
+    const onAbort = () => void runtime.close(runtime.root, { force: true }).catch(() => {})
+    signal.addEventListener("abort", onAbort, { once: true })
+    try {
+      const woke = runtime.wake(h, prompt)
+      const r = await runtime.wait(h as Handle)
+      if (signal.aborted) return { text: reason(), isError: true, turns: r.turns, totalTokens: r.totalTokens, cancelled: true }
+      if (woke.ok && r.status !== "pending") await runtime.close(runtime.root)
+      return r
+    } finally {
+      signal.removeEventListener("abort", onAbort)
+    }
+  }
+
   /**
    * The bridge: an Agent IS a Tool. Drop the result into the classic API's
    * `extraTools`; the agent's own loop runs in isolation and the classic run
@@ -148,6 +169,18 @@ export class Agent {
    * `{agent, turns, totalTokens}`.
    */
   asTool(opts: AgentRunOptions = {}): Tool {
+    return this.asToolWith(() => opts)
+  }
+
+  /**
+   * `asTool` with options built per call from the calling tool's context (SPEC §4C), so the
+   * child runs under the parent turn's gates: set `hooks` (the same beforeTool permission gate —
+   * it also sees the child's tool calls), `waitFor` (the same ask bridge) and `onMetric`. A
+   * `hooks` on the agent's own spec replaces `opts.hooks` for that agent, so leave it unset when
+   * the gate must hold. When the calling turn is cancelled (`ctx.signal`), the child is
+   * interrupted and the tool returns a `cancelled:` error result.
+   */
+  asToolWith(per: (ctx?: ToolContext) => AgentRunOptions): Tool {
     return defineTool({
       name: this.name,
       description: this.spec.does,
@@ -156,13 +189,11 @@ export class Agent {
         properties: { prompt: { type: "string", description: "The task for this agent" } },
         required: ["prompt"],
       },
-      run: async (args: Record<string, unknown>) => {
-        const r = await this.run(String(args.prompt), opts)
-        return {
-          output: r.text,
-          isError: r.isError,
-          metadata: { agent: this.name, turns: r.turns, totalTokens: r.totalTokens },
-        }
+      run: async (args: Record<string, unknown>, ctx?: ToolContext) => {
+        const r = await this.runSignal(String(args.prompt), per(ctx), ctx?.signal)
+        const metadata = { agent: this.name, turns: r.turns, totalTokens: r.totalTokens }
+        if (r.cancelled) return { output: `cancelled: ${r.text}`, isError: true, metadata }
+        return { output: r.text, isError: r.isError, metadata }
       },
     })
   }