toolnexus 0.16.0 → 0.17.0

package/README.md

@@ -235,6 +235,52 @@ For `httpTool`: URL `{placeholders}` are filled from args; `query` arg names go
 querystring (all args on GET); the rest become the JSON body (`body: "json" | "form" | "raw"`).
 Non-2xx → `{ isError: true, output: "HTTP <status>: <body>" }`.
 
+## Images, PDFs and audio (content parts)
+
+Parts go in the **first** argument, next to your text, because the order of text and image is
+semantic to a model:
+
+```ts
+import { attach, text } from "toolnexus"
+
+const { text: answer } = await agent.run(
+  ["What is broken in this screenshot?", await attach("./shot.png")],
+  { toolkit: tk },
+)
+```
+
+`attach(source, opts?)` takes what you already hold: a filesystem path, a `data:` URL, an
+`https:` URL, native bytes (`Uint8Array`, `Buffer`, `ArrayBuffer`, any `ArrayBufferView` —
+`mimeType` required, bytes carry no extension), or a `Blob`/`File` straight off an upload.
+`fromPath`, `fromBytes`, `fromBlob`, `fromDataUrl`, `fromUrl` are the same thing spelled
+explicitly. Mime types come from a fixed extension table (`png jpg jpeg gif webp pdf mp3 wav`) —
+never sniffed, never read from the machine's mime database, so every port agrees. A plain string
+prompt is untouched and byte-identical to before.
+
+A tool can answer with media too — `parts` alongside the still-required `output`, which is what
+the transcript, compaction and any text-only provider keep seeing:
+
+```ts
+defineTool({
+  name: "screenshot",
+  description: "Grab the screen",
+  inputSchema: { type: "object", properties: {} },
+  run: async () => ({
+    output: "screenshot, 1280x720 png",
+    parts: [await attach("./shot.png")],
+  }),
+})
+```
+
+**MCP tools' images now survive.** Non-text content from an MCP server — image, audio, embedded
+resource, `resource_link` — used to be filtered out silently; it is preserved as `parts` and
+emitted per provider style (Anthropic inside `tool_result`; OpenAI, whose `tool` message rejects
+an image, in a synthetic user message that never enters your transcript).
+
+Whatever you pass in, a part stores **bytes plus a `mimeType`** — never a handle, never a path —
+so a persisted transcript replays without the original file. A `Blob` is read **eagerly** at
+construction, and a handle you supply is read, not closed.
+
 ## Built-in tools
 
 A fifth source ships **10 built-in tools** — `bash`, `read`, `write`, `edit`, `grep`, `glob`,

package/dist/agents/agent.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Level-1 subagent surface — SPEC.md §7D.
+ *
+ * One new noun: `agent(name, spec)`. An Agent is (identity/system prompt × a
+ * filtered toolkit view × the shipped client loop), and — the §7A/§7B axiom
+ * completed locally — an Agent IS a Tool: `asTool()` bridges it into the classic
+ * 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 type { Answer, Request, Tool } 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";
@@ -71,7 +81,7 @@ export declare 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.
      */
-    run(prompt: string, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    run(prompt: PromptInput, opts?: AgentRunOptions): Promise<AgentRunResult>;
     /**
      * 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

package/dist/agents/agent.js

@@ -1,12 +1,3 @@
-/**
- * Level-1 subagent surface — SPEC.md §7D.
- *
- * One new noun: `agent(name, spec)`. An Agent is (identity/system prompt × a
- * filtered toolkit view × the shipped client loop), and — the §7A/§7B axiom
- * completed locally — an Agent IS a Tool: `asTool()` bridges it into the classic
- * API's `extraTools`; `run()` executes one-shot against a private runtime.
- * Everything compiles down to the six host verbs in runtime.ts.
- */
 import fs from "node:fs";
 import { defineTool } from "../native.js";
 import { AgentRuntime, isVerbError } from "./runtime.js";

package/dist/agents/compaction.d.ts

@@ -1,28 +1,3 @@
-/**
- * Context compaction (SPEC.md §7F) — keep a long-lived agent under budget.
- *
- * A long-running agent grows its transcript until it overflows the model's window.
- * `compactor(opts)` returns a **`beforeLLM` hook** (§8) that summarizes the older
- * transcript and keeps a recent tail. It rides the existing seam: the client loop
- * applies a `beforeLLM` message rewrite by *replacing* the working transcript, and
- * that array flows on into `RunResult.messages` and the `ConversationStore`. So
- * compaction is a pure `messages → messages` helper and adds **no loop behavior** —
- * it is the canonical use of the §8 `beforeLLM` hook.
- *
- * Invariants (SPEC §7F):
- *   1. At/below `maxTokens` the hook is a **no-op** — it returns nothing and the run
- *      is byte-identical to a run with no compactor.
- *   2. **Tool-pair safety** — the retained tail always begins at a `user` turn, so no
- *      `tool` message is ever orphaned from the `assistant` carrying its `tool_call_id`.
- *   3. The **leading system prompt** (identity / soul / skills) is preserved verbatim;
- *      only the body between it and the tail is summarized.
- *
- *   import { agents } from "toolnexus"
- *   const client = createClient({
- *     …,
- *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
- *   })
- */
 /**
  * A chat message in the working transcript. Structural and provider-neutral — only the
  * fields compaction reasons about are named; anything else on the message is carried

package/dist/agents/compaction.js

@@ -23,6 +23,7 @@
  *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
  *   })
  */
+import { partTokens } from "../content.js";
 /**
  * Cheap, deterministic token estimate: `ceil(chars/4)` over each message's JSON
  * serialization, summed. This is an *estimator*, not a tokenizer — exactness is the
@@ -30,10 +31,48 @@
  */
 export function estimateTokens(messages) {
     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) {
+    const partBytes = [];
+    const walk = (v, key) => {
+        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 = {};
+            for (const [k, val] of Object.entries(v))
+                out[k] = walk(val, k);
+            return out;
+        }
+        return v;
+    };
+    return { text: JSON.stringify(walk(m)) ?? "", partBytes };
+}
 /** The system reminder injected when `flushToMemory` is set. */
 const FLUSH_TO_MEMORY_REMINDER = "Before continuing: if anything from earlier is worth keeping, save it with the memory tool now — the earlier transcript is about to be summarized.";
 /** Prefix on the summary system message; hosts/tests key off this to detect a compaction. */

package/dist/agents/loop.d.ts

@@ -12,6 +12,7 @@
  *
  * So Loop takes no options: it is read, not configured.
  */
+import type { PromptInput } from "../content.js";
 import { type ClientOptions, type Hooks, type RunResult } from "../client.js";
 import type { Toolkit } from "../toolkit.js";
 import type { Agent } from "./agent.js";
@@ -77,7 +78,7 @@ export declare function allTodosDone(result: RunResult): Verdict;
  * keeps `pending` and `incomplete` distinct — the caller can always tell whether
  * it owes an Answer or a fix.
  */
-export declare function runGated(ask: (prompt: string) => Promise<RunResult>, prompt: string, completion: Completion | undefined): Promise<RunResult>;
+export declare function runGated(ask: (prompt: PromptInput) => Promise<RunResult>, prompt: PromptInput, completion: Completion | undefined): Promise<RunResult>;
 /** A live execution of an Agent. Its only verbs are `run` and reading state. */
 export declare class Loop {
     #private;
@@ -94,5 +95,5 @@ export declare class Loop {
     get status(): string;
     /** Model round trips this loop has spent. */
     get turns(): number;
-    run(prompt: string, opts?: LoopRunOptions): Promise<Outcome>;
+    run(prompt: PromptInput, opts?: LoopRunOptions): Promise<Outcome>;
 }

package/dist/agents/loop.js

@@ -1,17 +1,3 @@
-/**
- * Loop — a live execution of an Agent, and the completion gate that stops it
- * claiming `done` too early. A layer over the shipped §8 client: nothing here
- * changes existing behaviour.
- *
- * The placement law this encodes:
- *
- *   AgentSpec (the harness) answers "MAY it?"    — capability, ceilings. Per problem.
- *   RunOptions             answers "with WHAT?"  — model for this call.  Per call.
- *   Loop                   answers "DID it?"     — status, turns.        Observed.
- *   none of them           answers "is it RIGHT?"— a tool, skill or agent.
- *
- * So Loop takes no options: it is read, not configured.
- */
 import { createClient } from "../client.js";
 /**
  * Compiles a spec's guardrails into one `beforeTool` with FIRST-DENY-WINS,

package/dist/agents/runtime.d.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 { type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js";
 import { type Completion } from "./loop.js";
 import type { Answer, Request, Tool } from "../types.js";
@@ -132,11 +133,11 @@ 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;
 }
 /**
  * A live agent. Public surface is the observable state (§7D pins transitions, not
@@ -266,7 +267,7 @@ export declare 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): {
+    wake(h: Handle, prompt?: PromptInput): {
         ok: true;
     } | ({
         ok: false;

package/dist/agents/runtime.js

@@ -1,19 +1,3 @@
-/**
- * Agent runtime substrate — SPEC.md §7D.
- *
- * A Handle is a live agent: state machine (`idle → running → idle|suspended|closed`,
- * `suspended → running` only via the Answer to its pending Request), an inbox held as
- * agent state, hierarchical budgets, and a deterministic parent-scoped id
- * (`root/coordinator.1/explore.2`). The runtime exposes exactly six host verbs
- * (spawn/post/wake/wait/interrupt/close) plus read-only list/inspect views, and owns
- * the cross-cutting infrastructure: ONE ConversationStore for all handles
- * (conversation id = handle id, so transcripts genuinely survive turns), an
- * injectable clock (fixtures run virtual), and the handle table.
- *
- * Everything rides shipped machinery: the §8 client loop, §10 pending/waitFor, and
- * the ConversationStore. SPEC pins transitions, never scheduling — conformance is
- * identical per-handle transition traces against `examples/subagent-*` fixtures.
- */
 import { createClient, InMemoryConversationStore } from "../client.js";
 import { runGated } from "./loop.js";
 import { createToolkit } from "../toolkit.js";
@@ -563,7 +547,14 @@ export class AgentRuntime {
      * snapshot and the input is checkpointed — resume replays the whole turn.
      */
     async executeTurn(h, prompt, oneShotWaitFor) {
-        const input = (prompt ?? "") + this.drainInbox(h);
+        // 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 = typeof prompt === "string" || prompt === undefined
+            ? (prompt ?? "") + drained
+            : drained
+                ? [...prompt, { type: "text", text: drained }]
+                : prompt;
         let result;
         try {
             await h.ready;

package/dist/builtin.js

@@ -12,6 +12,7 @@ import fs from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { pending } from "./types.js";
+import { mediaTypeFor } from "./content.js";
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
  * `disabled:true` wins, else `enabled:false` disables, otherwise enabled.
@@ -171,7 +172,7 @@ function bashTool() {
     }));
 }
 function readTool() {
-    return builtin("read", "Read a UTF-8 text file. With offset/limit, return only that line window.", {
+    return builtin("read", "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: {
             path: { type: "string", description: "Path to the file to read" },
@@ -184,13 +185,33 @@ function readTool() {
         const p = String(args.path ?? "");
         if (!p)
             return err("read: path is required");
-        let content;
+        let bytes;
         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) } : {}) }],
+            };
+        }
+        let content;
+        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");

package/dist/client.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Toolkit } from "./toolkit.js";
 import type { ToolResult, Request, Answer } from "./types.js";
+import type { PromptInput, UnsupportedPartMode } from "./content.js";
 import type { TranslateRequest, TranslateResult } from "./translate.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
@@ -50,6 +51,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. */
 export type ErrorTier = "retry" | "fail";
@@ -243,6 +251,8 @@ export declare class Client {
     private openaiBody;
     /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
     private anthropicBody;
+    /** The §8A/§1B shaping options every wire build shares. */
+    private wireOpts;
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
@@ -252,7 +262,7 @@ export declare class Client {
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
-    run(prompt: string, ctx: {
+    run(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         signal?: AbortSignal;
         history?: any[];
@@ -285,7 +295,7 @@ export declare 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`).
      */
-    ask(prompt: string, ctx: {
+    ask(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         id?: string;
         on_text?: (delta: string) => void;
@@ -301,7 +311,7 @@ export declare 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.
      */
-    stream(prompt: string, ctx: {
+    stream(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         id?: string;
         signal?: AbortSignal;
@@ -387,7 +397,7 @@ export declare class Conversation {
     messages: any[];
     constructor(client: Client, toolkit: Toolkit, signal?: AbortSignal | undefined);
     /** Send the next user turn; prior history is retained automatically. */
-    send(prompt: string): Promise<RunResult>;
+    send(prompt: PromptInput): Promise<RunResult>;
     /** Reset the conversation memory. */
     reset(): void;
 }

package/dist/client.js

@@ -1,4 +1,5 @@
 import { pendingOf } from "./types.js";
+import { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
@@ -207,7 +208,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. */
     openaiBody(messages, tools, stream) {
-        const b = { model: this.opts.model, messages };
+        const b = { model: this.opts.model, messages: toOpenAIWire(messages, this.wireOpts()) };
         if (tools.length) {
             b.tools = tools;
             b.tool_choice = "auto";
@@ -220,13 +221,17 @@ export class Client {
     }
     /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
     anthropicBody(system, messages, tools, stream) {
-        const b = { model: this.opts.model, max_tokens: 4096, system, messages };
+        const b = { 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. */
+    wireOpts() {
+        return { onUnsupportedPart: this.opts.onUnsupportedPart, maxPartBytes: this.opts.maxPartBytes };
+    }
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics() {
         return this.registry.render();
@@ -247,6 +252,7 @@ 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, ctx) {
+        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);
@@ -433,6 +439,7 @@ export class Client {
      * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
      */
     async *stream(prompt, ctx) {
+        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)
@@ -602,7 +609,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);
                 }
@@ -710,7 +717,7 @@ export class Client {
                 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 });
-                    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;
@@ -820,13 +827,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 };
                 }
             }
@@ -927,14 +934,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 });
@@ -1086,6 +1093,26 @@ function safeJson(s) {
         return {};
     }
 }
+/**
+ * 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, name, result) {
+    const m = { 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, result) {
+    const b = { 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) {
     for (let i = messages.length - 1; i >= 0; i--) {
         if (messages[i].role === "assistant" && typeof messages[i].content === "string")