toolnexus 0.21.0 → 0.23.0

package/README.md

@@ -12,7 +12,7 @@ unified as one tool set, driving any LLM.
 > loop, hooks, streaming, retries, memory — and nothing it doesn't.
 
 The JS/TypeScript port of [toolnexus](https://github.com/muthuishere/toolnexus) — the same
-library, byte-identical, also in **Python, Go, Java, C#, Elixir and Clojure**. Built on
+library, byte-identical, also in **Python, Go, Java, C#, Elixir, Clojure and Rust**. Built on
 `@modelcontextprotocol/sdk` (the MCP SDK opencode uses).
 
 ## Install
@@ -28,11 +28,11 @@ Built-in tools are on by default, so an empty toolkit can already act:
 ```ts
 import { createToolkit, createClient } from "toolnexus"
 
-const tk = await createToolkit()                        // 10 built-in tools, on by default
+const tk = await createToolkit({})                      // 10 built-in tools, on by default
 const agent = createClient({
   baseUrl: "https://openrouter.ai/api/v1",              // any OpenAI- or Anthropic-style endpoint
   style: "openai",                                      // or "anthropic"
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-4o-mini",                          // key: OPENROUTER_API_KEY (matches the host)
 })
 
 const { text } = await agent.run("What files are in this folder?", { toolkit: tk })
@@ -49,6 +49,52 @@ const tk = await createToolkit({ mcp: "mcp.json", skills: ["skills"] })
 - `skills/` is a folder of `**/SKILL.md` files, loaded on demand through one `skill` tool.
 - Remote MCP `headers` values expand `${ENV_VAR}` at call time and are never logged.
 
+## API key by host (BREAKING in 0.22)
+
+A key is only ever sent to the host it belongs to. `apiKey` wins; else `apiKeyEnv` (the NAME of
+an env var); else only the env var of the `baseUrl` host, over https — `api.openai.com` →
+`OPENAI_API_KEY`, `api.anthropic.com` → `ANTHROPIC_API_KEY`, `openrouter.ai` →
+`OPENROUTER_API_KEY`. **A local server, a proxy or any other host needs `apiKey` or `apiKeyEnv`**
+(before 0.22 the first provider key in the environment was sent to any `baseUrl`):
+
+```ts
+createClient({ baseUrl: "http://localhost:11434/v1", style: "openai", model: "llama3", apiKey: "YOUR_KEY_HERE" })
+createClient({ baseUrl: "https://my-proxy.example/v1", style: "openai", model: "m", apiKeyEnv: "MY_PROXY_KEY" })
+```
+
+## Prompt cache and tool tiers
+
+```ts
+const agent = createClient({
+  baseUrl, style, model,
+  promptCache: { key: "session-42" },   // anthropic cache breakpoints / openai prompt_cache_key
+  toolTiers: { core: ["read", "grep"] }, // the rest load on demand via tool_search / call_tool
+})
+const res = await agent.run(prompt, { toolkit: tk })
+res.usage.cacheReadTokens               // cache hits; anthropic context = prompt + cacheRead + cacheWrite
+agent.toolTierPlan(tk)                  // { read: "core", bash: "listed", … }, frozen per toolkit
+agent.resetToolTiers(tk)                // rebuild at session start
+```
+
+`toolTiers` keeps the tools array identical on every request, so the cached prefix survives a
+large or growing toolkit. `call_tool` is unwrapped before hooks, so permission gates see the real
+tool. Runnable: `npm run example:prompt-cache` ([`examples/prompt_cache.ts`](examples/prompt_cache.ts)).
+
+## Host additions (0.22)
+
+- `loadMcp(cfg, { onServer })` — each MCP server reported the moment it connects or fails;
+  `mcpSource.resourceTools()` adds `list_mcp_resources` / `read_mcp_resource`.
+- `waitFor(request, { signal })` — a pending question ends with its turn.
+- Tool `hints` (`readOnly` / `destructive` / `openWorld`) on every builtin and MCP tool, passed to
+  `hooks.beforeTool` — allow, deny with an error result, or ask via `pending`.
+- Opt-in builtins: `builtins: { background: new BackgroundShells(), webSearch, notebookEdit: true }`
+  (`bash_output` / `kill_shell`, `websearch`, `notebook_edit`); `grep` takes `context` / `before` /
+  `after`; `read` / `grep` report truncation in metadata.
+- `agents.compactor({ onCompact })`, `agent.asToolWith(ctx => ({ hooks, waitFor }))`, runtime
+  `waitFor`, `ctx.callId` on tools, `listModels(opts)`.
+
+ACP host hooks (permission choice, update stream, cancel, streaming) are Go-only for now.
+
 ## Simple judgments
 
 A thin layer over any `Classifier` (SPEC.md §8B); the wire request is byte-identical to
@@ -102,4 +148,4 @@ Everything else — the full surface, with runnable examples — lives on the do
 | **API reference** | [JavaScript](https://muthuishere.github.io/toolnexus/api/javascript/) |
 | **Cookbook** | [Zero to agent](https://muthuishere.github.io/toolnexus/cookbook/zero-to-agent/) · [MCP servers](https://muthuishere.github.io/toolnexus/cookbook/mcp-servers/) · [Agent skills](https://muthuishere.github.io/toolnexus/cookbook/agent-skills/) · [Judge](https://muthuishere.github.io/toolnexus/cookbook/judge/) |
 
-Contract across all seven ports: [`SPEC.md`](https://github.com/muthuishere/toolnexus/blob/main/SPEC.md).
+Contract across all eight ports: [`SPEC.md`](https://github.com/muthuishere/toolnexus/blob/main/SPEC.md).

package/dist/agents/agent.d.ts

@@ -8,7 +8,7 @@
  * Everything compiles down to the six host verbs in runtime.ts.
  */
 import type { PromptInput } from "../content.js";
-import type { Answer, Request, Tool } from "../types.js";
+import type { Answer, Request, Tool, ToolContext } from "../types.js";
 import { AgentRuntime, type AgentDef, type Budget, type RuntimeOptions, type TaskResult } from "./runtime.js";
 import { Loop, type Completion, type Guardrail } from "./loop.js";
 import type { ClientOptions } from "../client.js";
@@ -93,6 +93,8 @@ export declare class Agent {
      * case the tree stays parked and `result.runtime.resume(answer)` continues it.
      */
     run(prompt: PromptInput, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /** `run` that interrupts the child when `signal` aborts. */
+    private runSignal;
     /**
      * 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
@@ -100,6 +102,15 @@ export declare class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts?: AgentRunOptions): Tool;
+    /**
+     * `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;
 }
 /** The one new noun: define an agent. */
 export declare function agent(name: string, spec: AgentSpec): Agent;

package/dist/agents/agent.js

@@ -73,6 +73,32 @@ export class Agent {
             await runtime.close(runtime.root);
         return { ...r, runtime };
     }
+    /** `run` that interrupts the child when `signal` aborts. */
+    async runSignal(prompt, opts, signal) {
+        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);
+            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
@@ -80,6 +106,17 @@ export class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts = {}) {
+        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) {
         return defineTool({
             name: this.name,
             description: this.spec.does,
@@ -88,13 +125,12 @@ export class Agent {
                 properties: { prompt: { type: "string", description: "The task for this agent" } },
                 required: ["prompt"],
             },
-            run: async (args) => {
-                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, ctx) => {
+                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/dist/agents/compaction.d.ts

@@ -32,6 +32,25 @@ 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). */
 export interface BeforeLLMEvent {

package/dist/agents/compaction.js

@@ -89,7 +89,8 @@ export function compactor(opts) {
     const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2);
     return async (ev) => {
         const msgs = ev.messages;
-        if (count(msgs) <= opts.maxTokens)
+        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;
@@ -97,16 +98,37 @@ export function compactor(opts) {
         const split = findTailStart(msgs, headEnd, keepTail, count);
         if (split <= headEnd)
             return undefined; // nothing safely compactible
-        const older = msgs.slice(headEnd, split);
+        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 = [];
+        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 tail = msgs.slice(split);
         const flushNote = opts.flushToMemory
             ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
             : [];
         const summary = await opts.summarize(older);
         const summaryMsg = { 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/dist/agents/runtime.d.ts

@@ -293,6 +293,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>;
 }
 /**
  * The §7D agent runtime: six host verbs over a tree of Handles, three loud

package/dist/agents/runtime.js

@@ -595,12 +595,23 @@ export class AgentRuntime {
      * escalation traced (nearest interpreter wins; the Request's `data.path` names
      * the suspended subtree that is asking). */
     wrapWaitFor(h) {
-        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 = 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) => {
             const path = Array.isArray(req.data?.path) ? req.data.path.join("/") : h.id;
-            this.t(`${path}: escalate → ${h.id} answers ("nearest interpreter")`);
+            this.t(`${path}: escalate → ${answerer} answers ("nearest interpreter")`);
             return waitFor(req);
         };
     }

package/dist/builtin.d.ts

@@ -1,4 +1,5 @@
 import type { Tool } from "./types.js";
+import { BackgroundShells, type WebSearchFunc } from "./builtin_extras.js";
 /**
  * Config for the single global builtin toggle (mirrors MCP isEnabled precedence),
  * plus the host boundary: which interpreter `bash` runs, what a relative path
@@ -28,6 +29,21 @@ export type BuiltinsConfig = boolean | {
      * builtins, NOT a sandbox — `bash` still reaches the whole filesystem.
      */
     confineToBaseDir?: boolean;
+    /**
+     * POSIX wait in ms between SIGTERM and SIGKILL of a timed-out or cancelled
+     * `bash` job's process group. Absent or 0 ⇒ 2000. No effect on Windows,
+     * which has no graceful stop for a console process (SPEC §4A).
+     */
+    killGraceMs?: number;
+    /**
+     * Opt-in (SPEC §4C): `bash` takes `run_in_background` and the `bash_output` / `kill_shell`
+     * tools exist. The host owns the registry: call `closeAll()` on shutdown.
+     */
+    background?: BackgroundShells;
+    /** Opt-in (SPEC §4C): adds a `websearch` tool backed by this provider. The library ships none. */
+    webSearch?: WebSearchFunc;
+    /** Opt-in (SPEC §4C): adds the `notebook_edit` tool for .ipynb cells. */
+    notebookEdit?: boolean;
 };
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP: