toolnexus 0.22.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/client.d.ts

@@ -493,6 +493,9 @@ export declare class Client {
     private runToolDirect;
     /** ToolTiers `call_tool {name, arguments}` -> the real call; undefined when tiers are off. */
     private unwrapCall;
+    /** The RunResult.toolCalls entry: a `call_tool` call is recorded as the real tool with its
+     *  inner arguments, the name hooks and stream events see (the transcript keeps the wrapper). */
+    private toolCallRecord;
     /** The stream's tool_call event, naming the real tool for a `call_tool` call. */
     private callEvent;
     private resultEvent;

package/dist/client.js

@@ -722,6 +722,12 @@ export class Client {
     unwrapCall(name, args) {
         return this.opts.toolTiers ? unwrapCallTool(name, args) : undefined;
     }
+    /** The RunResult.toolCalls entry: a `call_tool` call is recorded as the real tool with its
+     *  inner arguments, the name hooks and stream events see (the transcript keeps the wrapper). */
+    toolCallRecord(name, args, result) {
+        const inner = this.unwrapCall(name, args);
+        return { name: inner ? inner.name : name, args: inner ? inner.args : args, output: result.output, isError: result.isError, metadata: result.metadata };
+    }
     /** The stream's tool_call event, naming the real tool for a `call_tool` call. */
     callEvent(id, name, args) {
         const inner = this.unwrapCall(name, args);
@@ -897,7 +903,7 @@ export class Client {
                 // and the later suspensions' placeholder results never enter the transcript (they re-suspend
                 // on resume). Mirrors the streaming path.
                 for (const s of settled) {
-                    toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    toolCalls.push(this.toolCallRecord(s.call.function.name, s.args, s.result));
                     messages.push(toolMessage(s.call.id, s.call.function.name, s.result));
                     if (s.halted)
                         return this.pendingRun(runStart, lastModel, s.halted, messages, toolCalls, turns, usage);
@@ -1021,7 +1027,7 @@ export class Client {
                 const content = [];
                 let halted;
                 for (const s of settled) {
-                    toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    toolCalls.push(this.toolCallRecord(s.use.name, s.args, s.result));
                     content.push(toolResultBlock(s.use.id, s.result));
                     if (s.halted) {
                         halted = s.halted;
@@ -1145,13 +1151,13 @@ export class Client {
                         const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn, signal);
                         result = r.result;
                         if (r.halted) {
-                            toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            toolCalls.push(this.toolCallRecord(c.name, args, result));
                             messages.push(toolMessage(c.id, c.name, result));
                             yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
-                    toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                    toolCalls.push(this.toolCallRecord(c.name, args, result));
                     messages.push(toolMessage(c.id, c.name, result));
                     yield this.resultEvent(c.id, c.name, safeJson(c.args), result);
                 }
@@ -1266,14 +1272,14 @@ export class Client {
                         const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn, signal);
                         result = r.result;
                         if (r.halted) {
-                            toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            toolCalls.push(this.toolCallRecord(u.name, args, result));
                             results.push(toolResultBlock(u.id, result));
                             messages.push({ role: "user", content: results });
                             yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
-                    toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                    toolCalls.push(this.toolCallRecord(u.name, args, result));
                     results.push(toolResultBlock(u.id, result));
                     yield this.resultEvent(u.id, u.name, u.input, result);
                 }

package/dist/toolkit.d.ts

@@ -52,7 +52,7 @@ export declare class Toolkit {
     private readonly mcpServerConfig;
     private byName;
     private constructor();
-    static create(opts: ToolkitOptions): Promise<Toolkit>;
+    static create(opts?: ToolkitOptions): Promise<Toolkit>;
     tools(): Tool[];
     get(name: string): Tool | undefined;
     /** Add a tool at runtime (native, http, or any custom Tool). First name wins. */
@@ -104,4 +104,4 @@ export declare class Toolkit {
     }[];
     close(): Promise<void>;
 }
-export declare function createToolkit(opts: ToolkitOptions): Promise<Toolkit>;
+export declare function createToolkit(opts?: ToolkitOptions): Promise<Toolkit>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.22.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/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.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/client.ts

@@ -995,6 +995,13 @@ export class Client {
     return this.opts.toolTiers ? unwrapCallTool(name, args) : undefined
   }
 
+  /** The RunResult.toolCalls entry: a `call_tool` call is recorded as the real tool with its
+   *  inner arguments, the name hooks and stream events see (the transcript keeps the wrapper). */
+  private toolCallRecord(name: string, args: Record<string, unknown>, result: ToolResult): ToolCallRecord {
+    const inner = this.unwrapCall(name, args)
+    return { name: inner ? inner.name : name, args: inner ? inner.args : args, output: result.output, isError: result.isError, metadata: result.metadata }
+  }
+
   /** The stream's tool_call event, naming the real tool for a `call_tool` call. */
   private callEvent(id: string, name: string, args: Record<string, unknown>): StreamEvent {
     const inner = this.unwrapCall(name, args)
@@ -1168,7 +1175,7 @@ export class Client {
         // and the later suspensions' placeholder results never enter the transcript (they re-suspend
         // on resume). Mirrors the streaming path.
         for (const s of settled) {
-          toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
+          toolCalls.push(this.toolCallRecord(s.call.function.name, s.args, s.result))
           messages.push(toolMessage(s.call.id, s.call.function.name, s.result))
           if (s.halted) return this.pendingRun(runStart, lastModel, s.halted, messages, toolCalls, turns, usage)
         }
@@ -1288,7 +1295,7 @@ export class Client {
         const content: any[] = []
         let halted: Request | undefined
         for (const s of settled) {
-          toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
+          toolCalls.push(this.toolCallRecord(s.use.name, s.args, s.result))
           content.push(toolResultBlock(s.use.id, s.result))
           if (s.halted) { halted = s.halted; break }
         }
@@ -1392,13 +1399,13 @@ export class Client {
             const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn, signal)
             result = r.result
             if (r.halted) {
-              toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              toolCalls.push(this.toolCallRecord(c.name, args, result))
               messages.push(toolMessage(c.id, c.name, result))
               yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
-          toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+          toolCalls.push(this.toolCallRecord(c.name, args, result))
           messages.push(toolMessage(c.id, c.name, result))
           yield this.resultEvent(c.id, c.name, safeJson(c.args), result)
         }
@@ -1495,14 +1502,14 @@ export class Client {
             const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn, signal)
             result = r.result
             if (r.halted) {
-              toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              toolCalls.push(this.toolCallRecord(u.name, args, result))
               results.push(toolResultBlock(u.id, result))
               messages.push({ role: "user", content: results })
               yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
-          toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+          toolCalls.push(this.toolCallRecord(u.name, args, result))
           results.push(toolResultBlock(u.id, result))
           yield this.resultEvent(u.id, u.name, u.input, result)
         }

package/src/toolkit.ts

@@ -79,7 +79,7 @@ export class Toolkit {
     }
   }
 
-  static async create(opts: ToolkitOptions): Promise<Toolkit> {
+  static async create(opts: ToolkitOptions = {}): Promise<Toolkit> {
     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
@@ -250,6 +250,6 @@ export class Toolkit {
   }
 }
 
-export function createToolkit(opts: ToolkitOptions): Promise<Toolkit> {
+export function createToolkit(opts: ToolkitOptions = {}): Promise<Toolkit> {
   return Toolkit.create(opts)
 }