toolnexus 0.15.0 → 0.17.0

package/dist/wire.js

@@ -0,0 +1,104 @@
+import { encodeParts, isContentPart, validatePart } from "./content.js";
+/** The text preceding each relocated part, so the model can attribute it to its call. */
+export const relocationHeader = (name, id) => `Output of tool ${name} (${id}):`;
+/** Split parts into the text ones (which ride along in place) and the rest. */
+function split(parts) {
+    const texts = [];
+    const others = [];
+    for (const p of parts)
+        (p.type === "text" ? texts : others).push(p);
+    return { texts, others };
+}
+function partsOf(m) {
+    const p = m?.parts;
+    return Array.isArray(p) && p.length ? p : undefined;
+}
+/** True when a message's `content` is a canonical `ContentPart[]` rather than a wire array. */
+function isPartArray(content) {
+    return Array.isArray(content) && content.length > 0 && content.every(isContentPart);
+}
+/**
+ * Build the OpenAI-style wire messages. Tool messages carry `output` plus text parts only;
+ * their non-text parts are collected and flushed as one synthetic user message the moment
+ * the run of tool messages ends.
+ */
+export function toOpenAIWire(messages, opts = {}) {
+    const out = [];
+    let relocated = [];
+    const flush = () => {
+        if (!relocated.length)
+            return;
+        const blocks = [];
+        for (const r of relocated) {
+            blocks.push({ type: "text", text: relocationHeader(r.name, r.id) });
+            blocks.push(...encodeParts(r.parts, { style: "openai", provenance: "derived", ...opts }));
+        }
+        relocated = [];
+        out.push({ role: "user", content: blocks });
+    };
+    for (const m of messages ?? []) {
+        if (m?.role === "tool") {
+            const parts = partsOf(m);
+            const { parts: _drop, ...rest } = m ?? {};
+            if (!parts) {
+                out.push(m);
+                continue;
+            }
+            const { texts, others } = split(parts);
+            const msg = { ...rest };
+            if (texts.length) {
+                msg.content = [{ type: "text", text: String(rest.content ?? "") }, ...encodeParts(texts, { style: "openai", provenance: "derived", ...opts })];
+            }
+            out.push(msg);
+            if (others.length)
+                relocated.push({ name: String(rest.name ?? ""), id: String(rest.tool_call_id ?? ""), parts: others });
+            continue;
+        }
+        flush();
+        if (isPartArray(m?.content)) {
+            out.push({ ...m, content: encodeParts(m.content, { style: "openai", provenance: "attached", ...opts }) });
+            continue;
+        }
+        out.push(m);
+    }
+    flush();
+    return out;
+}
+/**
+ * Build the Anthropic-style wire messages. Nothing is relocated: a `tool_result` block that
+ * carries parts gets them natively inside its own `content`, keyed to its `tool_use_id`.
+ */
+export function toAnthropicWire(messages, opts = {}) {
+    return (messages ?? []).map((m) => {
+        if (isPartArray(m?.content)) {
+            return { ...m, content: encodeParts(m.content, { style: "anthropic", provenance: "attached", ...opts }) };
+        }
+        if (!Array.isArray(m?.content))
+            return m;
+        let touched = false;
+        const content = m.content.map((block) => {
+            if (block?.type !== "tool_result")
+                return block;
+            const parts = partsOf(block);
+            if (!parts)
+                return block;
+            touched = true;
+            const { parts: _drop, ...rest } = block;
+            return {
+                ...rest,
+                content: [
+                    { type: "text", text: String(rest.content ?? "") },
+                    ...encodeParts(parts, { style: "anthropic", provenance: "derived", ...opts }),
+                ],
+            };
+        });
+        return touched ? { ...m, content } : m;
+    });
+}
+/** Validate every attached part before assembly, so `maxPartBytes` cannot be bypassed. */
+export function checkPromptParts(prompt, opts) {
+    if (!Array.isArray(prompt))
+        return;
+    for (const p of prompt)
+        validatePart(p, opts.maxPartBytes);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.15.0",
+  "version": "0.17.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/home.test.ts test/compaction.test.ts test/loop.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/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/agents/agent.ts

@@ -7,6 +7,7 @@
  * API's `extraTools`; `run()` executes one-shot against a private runtime.
  * Everything compiles down to the six host verbs in runtime.ts.
  */
+import type { PromptInput } from "../content.js"
 import fs from "node:fs"
 import { defineTool } from "../native.js"
 import type { Answer, Request, Tool } from "../types.js"
@@ -113,7 +114,7 @@ export class Agent {
    * the tree down — unless the run suspends durably (`status:"pending"`), in which
    * case the tree stays parked and `result.runtime.resume(answer)` continues it.
    */
-  async run(prompt: string, opts: AgentRunOptions = {}): Promise<AgentRunResult> {
+  async run(prompt: PromptInput, opts: AgentRunOptions = {}): Promise<AgentRunResult> {
     const runtime = this.createRuntime(opts)
     const h = runtime.spawn(runtime.root, this.name)
     if (isVerbError(h)) {

package/src/agents/compaction.ts

@@ -23,6 +23,7 @@
  *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
  *   })
  */
+import { partTokens } from "../content.js"
 
 /**
  * A chat message in the working transcript. Structural and provider-neutral — only the
@@ -44,10 +45,47 @@ export interface Message {
  */
 export function estimateTokens(messages: Message[]): number {
   let total = 0
-  for (const m of messages) total += Math.ceil(JSON.stringify(m).length / 4)
+  for (const m of messages) {
+    const { text, partBytes } = stripPartPayloads(m)
+    total += Math.ceil(text.length / 4)
+    // §1B: a media part is charged from its BYTE LENGTH. Scoring it by its `mimeType`
+    // string would price a 5 MB image at ~3 tokens, so the compactor would evict text and
+    // keep every image forever — the exact opposite of what a budget is for. Charging the
+    // base64 verbatim is the other failure: it prices an 82-byte PNG like 30 lines of prose.
+    for (const bytes of partBytes) total += partTokens(bytes)
+  }
   return total
 }
 
+/** Keys whose string value is a media payload rather than prose. */
+const PAYLOAD_KEYS = new Set(["data", "file_data", "blob"])
+
+/**
+ * Serialize a message for estimation with its media payloads replaced by "", returning the
+ * decoded byte length of each one so the caller can charge it properly. Recognises both the
+ * canonical `ContentPart` (`data`) and every provider block shape it encodes to
+ * (`image_url.url` as a data: URL, `file.file_data`, `input_audio.data`).
+ */
+function stripPartPayloads(m: Message): { text: string; partBytes: number[] } {
+  const partBytes: number[] = []
+  const walk = (v: unknown, key?: string): unknown => {
+    if (typeof v === "string") {
+      const b64 = PAYLOAD_KEYS.has(key ?? "") ? v : v.startsWith("data:") ? v.slice(v.indexOf(",") + 1) : undefined
+      if (b64 === undefined) return v
+      partBytes.push(Math.max(0, Math.floor((b64.length * 3) / 4)))
+      return ""
+    }
+    if (Array.isArray(v)) return v.map((x) => walk(x))
+    if (v && typeof v === "object") {
+      const out: Record<string, unknown> = {}
+      for (const [k, val] of Object.entries(v as Record<string, unknown>)) out[k] = walk(val, k)
+      return out
+    }
+    return v
+  }
+  return { text: JSON.stringify(walk(m)) ?? "", partBytes }
+}
+
 /** Options for {@link compactor}. */
 export interface CompactorOptions {
   /** Compact only when the transcript estimate exceeds this; at/below ⇒ no-op. */

package/src/agents/loop.ts

@@ -12,6 +12,7 @@
  *
  * So Loop takes no options: it is read, not configured.
  */
+import type { PromptInput } from "../content.js"
 import { createClient, type ClientOptions, type Hooks, type RunResult } from "../client.js"
 import type { Toolkit } from "../toolkit.js"
 import type { Agent } from "./agent.js"
@@ -114,8 +115,8 @@ export function allTodosDone(result: RunResult): Verdict {
  * it owes an Answer or a fix.
  */
 export async function runGated(
-  ask: (prompt: string) => Promise<RunResult>,
-  prompt: string,
+  ask: (prompt: PromptInput) => Promise<RunResult>,
+  prompt: PromptInput,
   completion: Completion | undefined,
 ): Promise<RunResult> {
   if (!completion) return ask(prompt)
@@ -187,14 +188,14 @@ export class Loop {
     return this.#turns
   }
 
-  async run(prompt: string, opts: LoopRunOptions = {}): Promise<Outcome> {
+  async run(prompt: PromptInput, opts: LoopRunOptions = {}): Promise<Outcome> {
     const completion = this.agent.spec.completion
     const client = createClient(this.#clientOptions(opts))
     this.#status = "running"
 
     let attempts = 0
     let history: any[] = []
-    const ask = async (p: string): Promise<RunResult> => {
+    const ask = async (p: PromptInput): Promise<RunResult> => {
       attempts++
       const r = await client.run(p, { toolkit: this.toolkit, history })
       this.#turns += r.turns

package/src/agents/runtime.ts

@@ -14,6 +14,7 @@
  * the ConversationStore. SPEC pins transitions, never scheduling — conformance is
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
+import type { PromptInput } from "../content.js"
 import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js"
 import { runGated, type Completion } from "./loop.js"
 import { createToolkit, type Toolkit } from "../toolkit.js"
@@ -176,12 +177,12 @@ interface Pools {
  */
 interface Checkpoint {
   /** The exact turn input (prompt + rendered inbox drain) to replay. */
-  input: string
+  input: PromptInput
 }
 
 interface QueuedWake {
   h: Handle
-  prompt?: string
+  prompt?: PromptInput
 }
 
 /**
@@ -387,7 +388,7 @@ export class AgentRuntime {
    * the wake queues FIFO and a completing sibling transfers its slot. Waking a
    * suspended handle is a no-op (items buffer; only the Answer wakes it).
    */
-  wake(h: Handle, prompt?: string): { ok: true } | ({ ok: false } & VerbError) {
+  wake(h: Handle, prompt?: PromptInput): { ok: true } | ({ ok: false } & VerbError) {
     if (h.state === "closed") return { ok: false, error: `closed: ${h.id}` }
     if (h.state === "suspended") return { ok: true } // buffers; suspended→running ONLY via the Answer
     if (h.state === "running") return { ok: true } // already awake; inbox drains next turn
@@ -750,8 +751,15 @@ export class AgentRuntime {
    * When the Run halts pending, the stored transcript is REWOUND to the pre-turn
    * snapshot and the input is checkpointed — resume replays the whole turn.
    */
-  private async executeTurn(h: Handle, prompt?: string, oneShotWaitFor?: (req: Request) => Promise<Answer>): Promise<TaskResult> {
-    const input = (prompt ?? "") + this.drainInbox(h)
+  private async executeTurn(h: Handle, prompt?: PromptInput, oneShotWaitFor?: (req: Request) => Promise<Answer>): Promise<TaskResult> {
+    // A parts prompt keeps its ordering; the drained inbox joins it as a trailing text part,
+    // which is the same append the string path does.
+    const drained = this.drainInbox(h)
+    const input: PromptInput = typeof prompt === "string" || prompt === undefined
+      ? (prompt ?? "") + drained
+      : drained
+        ? [...prompt, { type: "text" as const, text: drained }]
+        : prompt
     let result: TaskResult
     try {
       await h.ready

package/src/builtin.ts

@@ -13,6 +13,7 @@ import { existsSync, readdirSync } from "node:fs"
 import path from "node:path"
 import type { JSONSchema, Tool, ToolContext, ToolResult } from "./types.js"
 import { pending } from "./types.js"
+import { mediaTypeFor } from "./content.js"
 
 /** Config for the single global builtin toggle (mirrors MCP isEnabled precedence). */
 export type BuiltinsConfig =
@@ -184,7 +185,7 @@ function bashTool(): Tool {
 function readTool(): Tool {
   return builtin(
     "read",
-    "Read a UTF-8 text file. With offset/limit, return only that line window.",
+    "Read a file. Recognised media (png/jpg/jpeg/gif/webp/pdf/mp3/wav) comes back as a content part; anything else is read as UTF-8 text, with offset/limit returning that line window.",
     {
       type: "object",
       properties: {
@@ -198,12 +199,31 @@ function readTool(): Tool {
     async (args) => {
       const p = String(args.path ?? "")
       if (!p) return err("read: path is required")
-      let content: string
+      let bytes: Buffer
       try {
-        content = await fs.readFile(p, "utf8")
+        bytes = await fs.readFile(p)
       } catch (e) {
         return err(`read: ${e instanceof Error ? e.message : String(e)}`)
       }
+      // §6: a recognised media extension comes back as a part. The table is fixed — no magic-byte
+      // sniffing and no platform mime database, whose contents vary per machine.
+      const media = mediaTypeFor(p)
+      if (media) {
+        return {
+          output: `${p} (${media.mimeType}, ${bytes.length} bytes)`,
+          isError: false,
+          parts: [{ type: media.type, mimeType: media.mimeType, data: bytes.toString("base64"), ...(media.type === "file" ? { name: path.basename(p) } : {}) } as any],
+        }
+      }
+      let content: string
+      try {
+        // `fatal` so undecodable bytes are an isError RESULT, not U+FFFD soup — and never a
+        // raised exception escaping execute() into the loop. `ignoreBOM` keeps a leading BOM,
+        // as readFile(…, "utf8") does, so text reads stay byte-identical.
+        content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes)
+      } catch {
+        return err(`read: ${p} is not valid UTF-8 text and has no recognised media extension`)
+      }
       if (args.offset === undefined && args.limit === undefined) return ok(content)
       const lines = content.split("\n")
       const offset = typeof args.offset === "number" ? Math.max(1, Math.trunc(args.offset)) : 1

package/src/client.ts

@@ -6,6 +6,8 @@
 import type { Toolkit } from "./toolkit.js"
 import type { ToolResult, Request, Answer } from "./types.js"
 import { pendingOf } from "./types.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"
 import {
   finishReasonFor,
@@ -62,6 +64,13 @@ export interface ClientOptions {
    * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
    * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
   onError?: (info: ErrorInfo) => ErrorTier
+  /** §1B. Reject a content part carrying more than this many **decoded** bytes (never the
+   * +33% base64 string). Unset ⇒ no limit, as today. */
+  maxPartBytes?: number
+  /** §8A. Overrides the provenance rule uniformly: `"error"` fails on any part the style
+   * cannot represent (attached or tool-derived), `"text"` degrades every one of them to a
+   * text placeholder. Unset ⇒ attached parts error, derived parts degrade. */
+  onUnsupportedPart?: UnsupportedPartMode
 }
 
 /** §8 Resilience. What to do with a failed LLM call. */
@@ -384,7 +393,7 @@ export class Client {
   /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
    * matches the pre-change body so a no-options call is byte-identical. */
   private openaiBody(messages: any[], tools: any[], stream: boolean): Record<string, any> {
-    const b: Record<string, any> = { model: this.opts.model, messages }
+    const b: Record<string, any> = { model: this.opts.model, messages: toOpenAIWire(messages, this.wireOpts()) }
     if (tools.length) {
       b.tools = tools
       b.tool_choice = "auto"
@@ -398,12 +407,17 @@ export class Client {
 
   /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
   private anthropicBody(system: string, messages: any[], tools: any[], stream: boolean): Record<string, any> {
-    const b: Record<string, any> = { model: this.opts.model, max_tokens: 4096, system, messages }
+    const b: Record<string, any> = { model: this.opts.model, max_tokens: 4096, system, messages: toAnthropicWire(messages, this.wireOpts()) }
     if (tools.length) b.tools = tools
     if (stream) b.stream = true
     return this.finalizeBody(b)
   }
 
+  /** The §8A/§1B shaping options every wire build shares. */
+  private wireOpts(): WireOptions {
+    return { onUnsupportedPart: this.opts.onUnsupportedPart, maxPartBytes: this.opts.maxPartBytes }
+  }
+
   /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
   metrics(): string {
     return this.registry.render()
@@ -427,7 +441,8 @@ export class Client {
     this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) })
   }
 
-  async run(prompt: string, ctx: { toolkit: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
+  async run(prompt: PromptInput, ctx: { toolkit: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
+    checkPromptParts(prompt, this.wireOpts())
     return this.opts.style === "anthropic"
       ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
       : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history)
@@ -592,7 +607,7 @@ export class Client {
    * the answer — so the next `ask` with the same `id` continues it. Without an
    * `id` it is a stateless one-shot (identical to `run`).
    */
-  async ask(prompt: string, ctx: { toolkit: Toolkit; id?: string; on_text?: (delta: string) => void; signal?: AbortSignal }): Promise<RunResult> {
+  async ask(prompt: PromptInput, ctx: { toolkit: Toolkit; id?: string; on_text?: (delta: string) => void; signal?: AbortSignal }): Promise<RunResult> {
     // Block-style streaming: run the streaming loop, forward text deltas, still return the
     // final RunResult. Memory (id load/save) is handled by stream() itself, so no duplication.
     if (ctx.on_text) {
@@ -620,7 +635,8 @@ export class Client {
    * With an `id`, it is stateful (like `ask`): the thread's transcript is loaded as history before
    * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
    */
-  async *stream(prompt: string, ctx: { toolkit: Toolkit; id?: string; signal?: AbortSignal }): AsyncGenerator<StreamEvent, void, unknown> {
+  async *stream(prompt: PromptInput, ctx: { toolkit: Toolkit; id?: string; signal?: AbortSignal }): AsyncGenerator<StreamEvent, void, unknown> {
+    checkPromptParts(prompt, this.wireOpts())
     const history = ctx.id ? (await this.store.get(ctx.id)) ?? [] : undefined
     const gen = this.opts.style === "anthropic"
       ? this.streamAnthropic(prompt, ctx.toolkit, ctx.signal, history)
@@ -730,7 +746,7 @@ export class Client {
   }
 
   // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
-  private async runOpenAI(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
+  private async runOpenAI(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -783,7 +799,7 @@ export class Client {
         // 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 })
-          messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output })
+          messages.push(toolMessage(s.call.id, s.call.function.name, s.result))
           if (s.halted) return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage)
         }
       }
@@ -830,7 +846,7 @@ export class Client {
   }
 
   // ---- Anthropic-style: POST {baseUrl}/messages ----
-  private async runAnthropic(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
+  private async runAnthropic(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): Promise<RunResult> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const base = this.opts.baseUrl.replace(/\/$/, "")
@@ -890,7 +906,7 @@ export class Client {
         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 })
-          content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError })
+          content.push(toolResultBlock(s.use.id, s.result))
           if (s.halted) { halted = s.halted; break }
         }
         messages.push({ role: "user", content })
@@ -904,7 +920,7 @@ export class Client {
   }
 
   // ---- Streaming: OpenAI-style ----
-  private async *streamOpenAI(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
+  private async *streamOpenAI(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -982,13 +998,13 @@ export class Client {
             result = r.result
             if (r.halted) {
               toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-              messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+              messages.push(toolMessage(c.id, c.name, result))
               yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
           toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-          messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+          messages.push(toolMessage(c.id, c.name, result))
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
         }
       }
@@ -1000,7 +1016,7 @@ export class Client {
   }
 
   // ---- Streaming: Anthropic-style ----
-  private async *streamAnthropic(prompt: string, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
+  private async *streamAnthropic(prompt: PromptInput, toolkit: Toolkit, external?: AbortSignal, history?: any[]): AsyncGenerator<StreamEvent, void, unknown> {
     const key = resolveKey(this.opts)
     const signal = this.makeSignal(external)
     const runStart = Date.now()
@@ -1073,14 +1089,14 @@ export class Client {
             result = r.result
             if (r.halted) {
               toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-              results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+              results.push(toolResultBlock(u.id, result))
               messages.push({ role: "user", content: results })
               yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
               return
             }
           }
           toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-          results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+          results.push(toolResultBlock(u.id, result))
           yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError }
         }
         messages.push({ role: "user", content: results })
@@ -1097,6 +1113,135 @@ export function createClient(opts: ClientOptions): Client {
   return new Client(opts)
 }
 
+
+// --------------------------------------------------------------------------- //
+// In-process models (SPEC §8 Gap 2, semantic form).
+// --------------------------------------------------------------------------- //
+
+/** One tool call an in-process model asks for. Flat on purpose: the nested
+ *  `function: {}` wrapper is a wire detail, not something a model author should type.
+ *  `arguments` may be a structured value (encoded for you) or an encoded string. */
+export interface InProcessToolCall {
+  id?: string
+  name: string
+  arguments?: unknown
+}
+
+/** What an in-process model is handed: the assembled request for THIS call. */
+export interface InProcessRequest {
+  messages: any[]
+  tools?: any[]
+  model: string
+  /** Every other key the client assembled, for a model that wants them. */
+  body: Record<string, any>
+}
+
+/** What an in-process model returns: exactly one assistant message. Return `content`
+ *  to finish, or `toolCalls` to ask for tools — never both. `usage` is optional; when
+ *  omitted the run reports zero tokens rather than failing. */
+export interface InProcessResponse {
+  content?: string
+  toolCalls?: InProcessToolCall[]
+  usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number }
+}
+
+/** Options for {@link createInProcessClient}: every client option EXCEPT the three
+ *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate`. */
+export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style" | "fetch"> & {
+  /** Your model. Receives the assembled request, returns one assistant message. */
+  generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>
+}
+
+/** The sentinel base URL. Never dialled — the transport below answers every request
+ *  before the network is reached — but the client builds a URL string internally, so
+ *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
+ *  name can never resolve. */
+const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1"
+
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * This is a second constructor, not a second seam: it builds on the same injectable
+ * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
+ * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export function createInProcessClient(opts: InProcessOptions): Client {
+  const { generate, ...rest } = opts
+  if (typeof generate !== "function") {
+    throw new Error("toolnexus: createInProcessClient requires a `generate` function")
+  }
+
+  const inProcessFetch: typeof fetch = async (_url, init) => {
+    const body = JSON.parse(String((init as any)?.body ?? "{}"))
+
+    // A generate() returns a whole answer, so a stream would be one chunk pretending
+    // to be many. Content and delta-count assertions cannot tell that from a real
+    // stream, so refuse instead of degrading silently.
+    if (body.stream) {
+      throw new Error(
+        "toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
+          "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.",
+      )
+    }
+
+    const answer = await generate({
+      messages: body.messages ?? [],
+      tools: body.tools,
+      model: body.model,
+      body,
+    })
+
+    const message: Record<string, any> = { role: "assistant" }
+    if (answer.toolCalls && answer.toolCalls.length > 0) {
+      message.tool_calls = answer.toolCalls.map((c, i) => ({
+        id: c.id ?? `call_${i}`,
+        type: "function",
+        function: {
+          name: c.name,
+          // A string is already encoded; anything else is encoded here so a model
+          // author never has to think about the wire.
+          arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+        },
+      }))
+    } else {
+      message.content = answer.content ?? ""
+    }
+
+    const u = answer.usage ?? {}
+    const prompt = u.promptTokens ?? 0
+    const completion = u.completionTokens ?? 0
+    return new Response(
+      JSON.stringify({
+        choices: [{ index: 0, message, finish_reason: message.tool_calls ? "tool_calls" : "stop" }],
+        usage: {
+          prompt_tokens: prompt,
+          completion_tokens: completion,
+          total_tokens: u.totalTokens ?? prompt + completion,
+        },
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    )
+  }
+
+  return new Client({
+    // Retries default to ZERO here, unlike a network client. There is no wire, so
+    // there is no transient failure to ride out: whatever `generate` throws will
+    // throw again. Retrying it only buys backoff before the user sees their own bug —
+    // measured at 3.7s for the streaming refusal before this default. A host whose
+    // model really is flaky (a GPU that OOMs, say) can still set `retries`.
+    retries: 0,
+    ...(rest as ClientOptions),
+    baseUrl: IN_PROCESS_BASE_URL,
+    style: "openai",
+    // An in-process model has no endpoint to authenticate to, so the host must never need a key — but the client resolves one from the environment and fails when it finds none. A sentinel keeps that resolution from ever running. Caught by CI, which has no OPENROUTER_API_KEY; every local run passed because a developer shell has one.
+    apiKey: "in-process",
+    fetch: inProcessFetch,
+  })
+}
+
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export class Conversation {
   /** Full running transcript (system + user + assistant + tool messages). */
@@ -1104,7 +1249,7 @@ export class Conversation {
   constructor(private readonly client: Client, private readonly toolkit: Toolkit, private readonly signal?: AbortSignal) {}
 
   /** Send the next user turn; prior history is retained automatically. */
-  async send(prompt: string): Promise<RunResult> {
+  async send(prompt: PromptInput): Promise<RunResult> {
     const result = await this.client.run(prompt, { toolkit: this.toolkit, signal: this.signal, history: this.messages })
     this.messages = result.messages
     return result
@@ -1150,6 +1295,27 @@ function safeJson(s: string): Record<string, unknown> {
   }
 }
 
+/**
+ * A canonical `tool` turn. With no parts this is byte-identical to the pre-0.17 message;
+ * with parts it also carries them (and the tool `name` the §8A relocation header needs) —
+ * both consumed and stripped by the wire build, so neither reaches OpenAI.
+ */
+function toolMessage(id: string | undefined, name: string, result: ToolResult): any {
+  const m: any = { role: "tool", tool_call_id: id, content: result.output }
+  if (result.parts?.length) {
+    m.name = name
+    m.parts = result.parts
+  }
+  return m
+}
+
+/** A canonical Anthropic `tool_result` block; parts ride along and are emitted natively. */
+function toolResultBlock(id: string | undefined, result: ToolResult): any {
+  const b: any = { type: "tool_result", tool_use_id: id, content: result.output, is_error: result.isError }
+  if (result.parts?.length) b.parts = result.parts
+  return b
+}
+
 function lastText(messages: any[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {
     if (messages[i].role === "assistant" && typeof messages[i].content === "string") return messages[i].content