toolnexus 0.21.0 → 0.23.0

package/dist/toolkit.js

@@ -38,7 +38,7 @@ export class Toolkit {
             this.byName.set(t.name, t);
         }
     }
-    static async create(opts) {
+    static async create(opts = {}) {
         const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined;
         // Skills come from directories, in-memory data, and/or a lazy provider (§3,
         // S1). The provider is resolved here (create() is async) and merged with the
@@ -184,6 +184,6 @@ export class Toolkit {
         await this.mcp?.close();
     }
 }
-export function createToolkit(opts) {
+export function createToolkit(opts = {}) {
     return Toolkit.create(opts);
 }

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.21.0",
+  "version": "0.23.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,10 +17,11 @@
   ],
   "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/judge.test.ts test/batteries.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 test/examples.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"
+    "example:multimodal": "node --experimental-strip-types examples/multimodal.ts",
+    "example:prompt-cache": "node --experimental-strip-types examples/prompt_cache.ts"
   },
   "keywords": [
     "mcp",

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 }
       },
     })
   }

package/src/agents/compaction.ts

@@ -102,6 +102,26 @@ export interface CompactorOptions {
    * default. Composes with the memory builtin.
    */
   flushToMemory?: boolean
+  /**
+   * Called after each compaction with what changed, so a host can tell its UI or log (SPEC §4C).
+   * Never called on a no-op. Awaited before the next model call.
+   */
+  onCompact?: (info: CompactInfo) => void | Promise<void>
+}
+
+/** One compaction, for {@link CompactorOptions.onCompact}. Token counts come from `countTokens`. */
+export interface CompactInfo {
+  tokensBefore: number
+  tokensAfter: number
+  messagesBefore: number
+  messagesAfter: number
+  /** How many messages were folded into the summary. */
+  summarized: number
+  /** The text `summarize` returned (without the header line). */
+  summary: string
+  /** The summarized messages, verbatim, so a host can persist them (the loop saves only the
+   * compacted transcript). */
+  folded: Message[]
 }
 
 /** The event a `beforeLLM` hook receives (§8). */
@@ -134,7 +154,8 @@ export function compactor(
 
   return async (ev: BeforeLLMEvent): Promise<{ messages: Message[] } | undefined> => {
     const msgs = ev.messages
-    if (count(msgs) <= opts.maxTokens) return undefined // under budget → no-op
+    const before = count(msgs)
+    if (before <= opts.maxTokens) return undefined // under budget → no-op
 
     // Preserve a leading system prompt verbatim (identity / soul / skills — never summarized).
     const headEnd = msgs[0]?.role === "system" ? 1 : 0
@@ -143,9 +164,17 @@ export function compactor(
     const split = findTailStart(msgs, headEnd, keepTail, count)
     if (split <= headEnd) return undefined // nothing safely compactible
 
-    const older = msgs.slice(headEnd, split)
-    if (older.length === 0) return undefined
+    let older = msgs.slice(headEnd, split)
     const tail = msgs.slice(split)
+    // The latest user prompt is never summarized away. When the only clean boundary is the first
+    // message after the system prompt (one prompt followed by a long agentic run), keep that
+    // prompt verbatim and summarize the work after it: [system, prompt, summary].
+    let pinned: Message[] = []
+    if (split === msgs.length && headEnd < msgs.length && isBoundary(msgs[headEnd])) {
+      pinned = msgs.slice(headEnd, headEnd + 1)
+      older = msgs.slice(headEnd + 1)
+    }
+    if (older.length === 0) return undefined
 
     const flushNote: Message[] = opts.flushToMemory
       ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
@@ -154,7 +183,19 @@ export function compactor(
     const summary = await opts.summarize(older)
     const summaryMsg: Message = { role: "system", content: `${SUMMARY_PREFIX}${summary}` }
 
-    return { messages: [...system, summaryMsg, ...flushNote, ...tail] }
+    const out = [...system, ...pinned, summaryMsg, ...flushNote, ...tail]
+    const after = count(out)
+    if (after >= before) return undefined // compaction would not shrink the transcript → no-op
+    await opts.onCompact?.({
+      tokensBefore: before,
+      tokensAfter: after,
+      messagesBefore: msgs.length,
+      messagesAfter: out.length,
+      summarized: older.length,
+      summary,
+      folded: older,
+    })
+    return { messages: out }
   }
 }
 

package/src/agents/runtime.ts

@@ -390,6 +390,11 @@ export interface RuntimeOptions {
   /** §8 observability sink applied to EVERY agent's client, unless that agent's def
    * sets its own `onMetric`. Resolves independently of `hooks`. Forwarded verbatim. */
   onMetric?: (ev: MetricEvent) => void
+  /** The runtime-level §10 interpreter (SPEC §4C): answers a suspension when no agent on the
+   * handle's chain has its own `waitFor`. Absent ⇒ unchanged (the suspension goes durable). A
+   * host running an agent as a tool (`asToolWith`) sets it so the child's asks reach the same
+   * bridge as the parent turn. */
+  waitFor?: (request: Request) => Promise<Answer>
 }
 
 interface GateWaiter {
@@ -855,11 +860,20 @@ export class AgentRuntime {
    * escalation traced (nearest interpreter wins; the Request's `data.path` names
    * the suspended subtree that is asking). */
   private wrapWaitFor(h: Handle): ((req: Request) => Promise<Answer>) | undefined {
-    const waitFor = h.def.waitFor
+    const own = h.def.waitFor
+    let waitFor = own
+    if (!waitFor && this.opts.waitFor) {
+      // The runtime-level bridge answers only when NO agent on the chain has its own waitFor;
+      // otherwise the ask escalates to that nearest interpreter, as before.
+      let a: Handle | null = h.parent
+      while (a && !a.def.waitFor) a = a.parent
+      if (!a) waitFor = this.opts.waitFor
+    }
     if (!waitFor) return undefined
+    const answerer = own ? h.id : this.root.id
     return async (req: Request): Promise<Answer> => {
       const path = Array.isArray(req.data?.path) ? (req.data!.path as string[]).join("/") : h.id
-      this.t(`${path}: escalate → ${h.id} answers ("nearest interpreter")`)
+      this.t(`${path}: escalate → ${answerer} answers ("nearest interpreter")`)
       return waitFor(req)
     }
   }