toolnexus 0.22.0 → 0.24.0

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type JSONSchema = {
     [k: string]: unknown;
 };
 import type { ContentPart } from "./content.js";
-export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom";
+export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "media" | "custom";
 export interface ToolResult {
     output: string;
     isError: boolean;
@@ -96,6 +96,9 @@ export interface Tool {
     /** 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;
+    /** Decides per call whether this tool may run alongside other safe calls of the same model
+     * response (SPEC §8 "Tool scheduling"). Absent ⇒ safe only when `hints.readOnly`. */
+    concurrencySafe?: (args: Record<string, unknown>) => boolean;
 }
 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.22.0",
+  "version": "0.24.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,10 +17,12 @@
   ],
   "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/tool-concurrency.test.ts test/media.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:media": "node --experimental-strip-types examples/media.ts",
+    "example:prompt-cache": "node --experimental-strip-types examples/prompt_cache.ts"
   },
   "keywords": [
     "mcp",

package/src/agents/loop.ts

@@ -141,6 +141,7 @@ export async function runGated(
   }
 
   let accumulated: RunResult["toolCalls"] = []
+  let accFiles: RunResult["files"] = []
   let last: RunResult | undefined
   let reason = ""
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -149,7 +150,9 @@ export async function runGated(
     // The gate judges the ACCUMULATED work, so an agent cannot escape it by
     // declining to re-declare its plan on a retry.
     accumulated = [...accumulated, ...r.toolCalls]
-    const judged: RunResult = { ...r, toolCalls: accumulated }
+    // RunResult.files is derived from toolCalls, so it accumulates with them (§8).
+    accFiles = [...accFiles, ...(r.files ?? [])]
+    const judged: RunResult = { ...r, toolCalls: accumulated, files: accFiles }
     last = judged
 
     if (r.status && r.status !== "done") {

package/src/agents/runtime.ts

@@ -1012,7 +1012,7 @@ export class AgentRuntime {
     const team = [...(parent.def.team ?? [])].sort()
     const advertised = team.map((n) => (this.registry[n] ? `${n}: ${this.registry[n].does}` : n)).join("; ")
     const rt = this
-    return defineTool({
+    const tool = defineTool({
       name: "task",
       description: `Delegate a subtask to an isolated subagent (it runs on a fresh transcript and returns only its final answer). Available agents — ${advertised}`,
       inputSchema: {
@@ -1068,5 +1068,8 @@ export class AgentRuntime {
         }
       },
     })
+    // Each subagent is isolated and the runtime's own gate schedules the children,
+    // so a fan-out of task calls runs concurrently (SPEC §8 "Tool scheduling").
+    return { ...tool, concurrencySafe: () => true }
   }
 }

package/src/client.ts

@@ -10,6 +10,7 @@ import { toOpenAI, toAnthropic } from "./adapters.js"
 import { applyPromptCache, type PromptCacheOptions } from "./promptcache.js"
 import { buildToolPlan, toolSearch, unwrapCallTool, type ToolPlan, type ToolTier, type ToolTierOptions } from "./tooltiers.js"
 import { isRetryableStatus, retryAfterMs } from "./retry.js"
+import { isConcurrencySafe, resolveMaxToolConcurrency, scheduleCalls } from "./toolconcurrency.js"
 import type { ContentPart, PromptInput, UnsupportedPartMode } from "./content.js"
 import { toOpenAIWire, toAnthropicWire, checkPromptParts, type WireOptions } from "./wire.js"
 import type { TranslateRequest, TranslateResult, TranslatedToolCall } from "./translate.js"
@@ -41,6 +42,10 @@ export interface ClientOptions {
   headers?: Record<string, string>
   systemPrompt?: string
   maxTurns?: number
+  /** Cap on concurrency-safe tool calls of one response running at once (SPEC §8 "Tool
+   * scheduling"). Absent ⇒ env `TOOLNEXUS_MAX_TOOL_CONCURRENCY` when a positive integer, else 10.
+   * Unsafe calls (anything not read-only) always run alone. */
+  maxToolConcurrency?: number
   hooks?: Hooks
   /** Retries on transient LLM errors (`429`/`500`/`502`/`503`/`504`/`529` + network). Default 2.
    * Widen the status set with `retryableStatuses`. */
@@ -318,6 +323,26 @@ export interface ToolCallRecord {
   output: string
   isError: boolean
   metadata?: Record<string, unknown>
+  /** §8: the ToolResult's parts — present iff the result had parts. */
+  parts?: ContentPart[]
+}
+
+/** §8 RunResult.files entry: a non-text part a tool call produced this run. */
+export type RunFile = { type: "image" | "file" | "audio"; mimeType: string; url?: string; data?: string; name?: string; from: string; callId: string }
+
+/** Model tool-call id of each record, kept off the record itself (§8 shape has no id). */
+const callIds = new WeakMap<ToolCallRecord, string>()
+
+/** RunResult.files: every non-text part of every tool call, in call order (§8). */
+function runFiles(toolCalls: ToolCallRecord[]): RunFile[] {
+  const out: RunFile[] = []
+  for (const r of toolCalls) {
+    for (const p of r.parts ?? []) {
+      if (p.type === "text") continue
+      out.push({ ...p, from: r.name, callId: callIds.get(r) ?? "" })
+    }
+  }
+  return out
 }
 
 /** Token usage, summed across every LLM round trip in the run. */
@@ -340,6 +365,8 @@ export interface RunResult {
   messages: any[]
   /** Every tool call made, with its output, error flag, and metadata. */
   toolCalls: ToolCallRecord[]
+  /** Every non-text part produced by tool calls this run, in call order (§8). Always present. */
+  files: RunFile[]
   /** Total number of tool calls (= toolCalls.length). */
   toolCallCount: number
   /** Number of LLM round trips. */
@@ -990,11 +1017,42 @@ export class Client {
     return { args: a, result }
   }
 
+  /** Runs one response's calls under the tool schedule (SPEC §8 "Tool scheduling"). */
+  private schedule<T, R>(
+    toolkit: Toolkit | undefined,
+    items: T[],
+    key: (item: T) => [string, Record<string, unknown>],
+    fn: (item: T) => Promise<R>,
+  ): Promise<R[]> {
+    return scheduleCalls(items, (item) => {
+      const [name, args] = key(item)
+      return this.callSafe(toolkit, name, args)
+    }, resolveMaxToolConcurrency(this.opts.maxToolConcurrency), fn)
+  }
+
+  /** One call's safety; looks through `call_tool` to the tool it names. Unknown ⇒ unsafe. */
+  private callSafe(toolkit: Toolkit | undefined, name: string, args: Record<string, unknown>): boolean {
+    if (this.opts.toolTiers && name === "tool_search") return true
+    const inner = this.unwrapCall(name, args ?? {})
+    const tool = toolkit?.get(inner ? inner.name : name)
+    return tool ? isConcurrencySafe(tool, inner ? inner.args : (args ?? {})) : false
+  }
+
   /** ToolTiers `call_tool {name, arguments}` -> the real call; undefined when tiers are off. */
   private unwrapCall(name: string, args: Record<string, unknown>): { name: string; args: Record<string, unknown> } | undefined {
     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, callId?: string): ToolCallRecord {
+    const inner = this.unwrapCall(name, args)
+    const rec: ToolCallRecord = { name: inner ? inner.name : name, args: inner ? inner.args : args, output: result.output, isError: result.isError, metadata: result.metadata }
+    if (result.parts?.length) rec.parts = result.parts
+    callIds.set(rec, callId ?? "")
+    return rec
+  }
+
   /** 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)
@@ -1150,8 +1208,8 @@ export class Client {
         if (calls.length === 0) return this.endRun(runStart, lastModel, msg.content ?? "", messages, toolCalls, turns, usage)
         // execute all tool calls in this turn concurrently (true parallel tool calling)
         done.clear()
-        const settled = await untilAborted(signal, Promise.all(
-          calls.map(async (call: any) => {
+        const settled = await untilAborted(signal, this.schedule(toolkit,
+          calls, (call: any) => [call.function.name, safeJson(call.function.arguments)], async (call: any) => {
             let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn, signal)
             let halted: Request | undefined
             const req = pendingOf(result)
@@ -1162,13 +1220,13 @@ export class Client {
             }
             if (!halted && call.id) done.set(call.id, result)
             return { call, args, result, halted }
-          }),
+          },
         ))
         // Record in tool-call order; on the FIRST durable halt, surface it and stop — deterministic,
         // 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, s.call.id))
           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)
         }
@@ -1183,7 +1241,7 @@ export class Client {
 
   private result(model: string, text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage, exhausted = false): RunResult {
     const incomplete = exhausted && text === ""
-    const r: RunResult = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model, status: incomplete ? "incomplete" : "done" }
+    const r: RunResult = { text, messages, toolCalls, files: runFiles(toolCalls), toolCallCount: toolCalls.length, turns, usage, model, status: incomplete ? "incomplete" : "done" }
     if (incomplete) r.limit = "maxTurns"
     return r
   }
@@ -1191,7 +1249,7 @@ export class Client {
   /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
   private pendingRun(runStart: number, model: string, request: Request, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
     this.emit({ event: "run", model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart })
-    return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model, status: "pending", pending: request }
+    return { text: request.prompt, messages, toolCalls, files: runFiles(toolCalls), toolCallCount: toolCalls.length, turns, usage, model, status: "pending", pending: request }
   }
 
   /**
@@ -1268,8 +1326,8 @@ export class Client {
         }
         // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
         done.clear()
-        const settled = await untilAborted(signal, Promise.all(
-          uses.map(async (use: any) => {
+        const settled = await untilAborted(signal, this.schedule(toolkit,
+          uses, (use: any) => [use.name, use.input ?? {}], async (use: any) => {
             let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn, signal)
             let halted: Request | undefined
             const req = pendingOf(result)
@@ -1280,7 +1338,7 @@ export class Client {
             }
             if (!halted && use.id) done.set(use.id, result)
             return { use, args, result, halted }
-          }),
+          },
         ))
         // Record in tool-call order; on the FIRST durable halt, include that tool_result block, stop
         // building the content, and surface it — deterministic (G3), later suspensions re-suspend on
@@ -1288,7 +1346,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, s.use.id))
           content.push(toolResultBlock(s.use.id, s.result))
           if (s.halted) { halted = s.halted; break }
         }
@@ -1378,11 +1436,11 @@ export class Client {
         messages.push({ role: "assistant", content: content || null, tool_calls: calls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) })
         for (const c of calls) yield this.callEvent(c.id, c.name, safeJson(c.args))
         done.clear()
-        const settled = await untilAborted(signal, Promise.all(calls.map(async (c) => {
+        const settled = await untilAborted(signal, this.schedule(toolkit, calls, (c) => [c.name, safeJson(c.args)], async (c) => {
           const r = await this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn, signal)
-          if (!pendingOf(r.result) && c.id) done.set(c.id, r.result)
+                    if (!pendingOf(r.result) && c.id) done.set(c.id, r.result)
           return r
-        })))
+        }))
         for (let i = 0; i < calls.length; i++) {
           const c = calls[i]
           let { args, result } = settled[i]
@@ -1392,13 +1450,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, c.id))
               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, c.id))
           messages.push(toolMessage(c.id, c.name, result))
           yield this.resultEvent(c.id, c.name, safeJson(c.args), result)
         }
@@ -1480,11 +1538,11 @@ export class Client {
         }
         for (const u of uses as any[]) yield this.callEvent(u.id, u.name, u.input)
         done.clear()
-        const settled = await untilAborted(signal, Promise.all((uses as any[]).map(async (u) => {
+        const settled = await untilAborted(signal, this.schedule(toolkit, uses as any[], (u: any) => [u.name, u.input ?? {}], async (u: any) => {
           const r = await this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn, signal)
           if (!pendingOf(r.result) && u.id) done.set(u.id, r.result)
           return r
-        })))
+        }))
         const results: any[] = []
         for (let i = 0; i < uses.length; i++) {
           const u = uses[i] as any
@@ -1495,14 +1553,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, u.id))
               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, u.id))
           results.push(toolResultBlock(u.id, result))
           yield this.resultEvent(u.id, u.name, u.input, result)
         }

package/src/index.ts

@@ -45,5 +45,7 @@ export {
 } from "./judge.js"
 export * from "./promptcache.js"
 export * from "./tooltiers.js"
+export * from "./toolconcurrency.js"
 export * from "./models.js"
 export * from "./builtin_extras.js"
+export * from "./media.js"