toolnexus 0.29.0 → 0.30.0

package/dist/acp.js

@@ -34,27 +34,79 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import path from "node:path";
+import { isContentPart, summarizePart } from "./content.js";
 /** The literal marker every rendered prompt ends with, naming the current
  *  turn as the one to answer. Kept as a named constant (not just inlined)
  *  because the exact wording is shared, by convention, with the other
  *  language ports and the spike that proved it fixes the stale-answer bug. */
 const SUPERSEDES_MARKER = "SUPERSEDES-ALL-PRIOR:";
-function renderContentPart(part) {
+function renderContentPart(part, media) {
     if (typeof part === "string")
         return part;
     if (part == null)
         return "";
     if (typeof part === "object" && "text" in part && typeof part.text === "string")
         return part.text;
+    // A media part (OpenAI chat wire shape) is named by its §1B one-liner, never its bytes;
+    // the part itself travels as a native ACP block (SPEC §8C "ACP content parts").
+    const p = acpWirePart(part);
+    if (p && p.type !== "text") {
+        media?.push(p);
+        return summarizePart(p);
+    }
     return JSON.stringify(part);
 }
-/** Flattens `content` (a string, or an array of content parts) to plain text. */
-function renderContent(content) {
+/** `data:<mime>;base64,<payload>` (non-empty mime) ⇒ {mimeType, data}; anything else ⇒ undefined (SPEC §8C). */
+function parseBase64DataUrl(u) {
+    if (!u.startsWith("data:"))
+        return undefined;
+    const comma = u.indexOf(",");
+    if (comma < 0)
+        return undefined;
+    const meta = u.slice(5, comma);
+    if (!meta.endsWith(";base64"))
+        return undefined;
+    const mimeType = meta.slice(0, -";base64".length);
+    return mimeType ? { mimeType, data: u.slice(comma + 1) } : undefined;
+}
+/** One OpenAI chat media block read back into a §1B part, as SPEC §8C pins it (Go acpWirePart). */
+function acpWirePart(part) {
+    switch (part?.type) {
+        case "image_url": {
+            const url = typeof part.image_url?.url === "string" ? part.image_url.url : "";
+            const d = parseBase64DataUrl(url);
+            if (d)
+                return { type: "image", ...d };
+            // A URL-only image part: EMPTY mimeType, never inferred from the URL.
+            return url ? { type: "image", mimeType: "", url } : undefined;
+        }
+        case "input_audio": {
+            let mimeType = "audio/" + String(part.input_audio?.format ?? "");
+            if (mimeType === "audio/mp3")
+                mimeType = "audio/mpeg";
+            return { type: "audio", mimeType, data: String(part.input_audio?.data ?? "") };
+        }
+        case "file": {
+            const d = parseBase64DataUrl(String(part.file?.file_data ?? ""));
+            if (!d)
+                return undefined;
+            const type = d.mimeType.startsWith("image/") ? "image" : d.mimeType.startsWith("audio/") ? "audio" : "file";
+            const p = { type, ...d };
+            if (part.file?.filename)
+                p.name = String(part.file.filename);
+            return p;
+        }
+    }
+    return isContentPart(part) && part.type !== "text" ? part : undefined;
+}
+/** Flattens `content` (a string, or an array of content parts) to plain text; media parts
+ *  found along the way are appended to `media`. */
+function renderContent(content, media) {
     if (typeof content === "string")
         return content;
     if (Array.isArray(content))
-        return content.map(renderContentPart).join(" ");
-    return renderContentPart(content);
+        return content.map((p) => renderContentPart(p, media)).join("\n");
+    return renderContentPart(content, media);
 }
 /** Renders the FULL assembled request as one prompt string — role + content
  *  per message — then appends the supersedes marker naming the latest user
@@ -64,7 +116,8 @@ function renderContent(content) {
  *  the caller's own conversation state. */
 function renderPrompt(request) {
     const messages = request.messages ?? [];
-    const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content)}`);
+    const parts = [];
+    const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content, parts)}`);
     let latest = "";
     for (let i = messages.length - 1; i >= 0; i--) {
         if (messages[i]?.role === "user") {
@@ -75,7 +128,25 @@ function renderPrompt(request) {
     if (!latest && messages.length > 0)
         latest = renderContent(messages[messages.length - 1]?.content);
     lines.push(`${SUPERSEDES_MARKER} ${latest}`);
-    return lines.join("\n");
+    return { text: lines.join("\n"), parts };
+}
+/** The session/prompt ContentBlock array: the text block, then one native block per media
+ *  part the agent advertised support for. A part it cannot take stays named only by its
+ *  description in the text; base64 never enters the text block. */
+function promptBlocks(text, parts, caps) {
+    const blocks = [{ type: "text", text }];
+    for (const p of parts) {
+        if (p.type === "text" || !p.data)
+            continue; // ACP media blocks require inline data
+        if (p.type === "image" && caps.image)
+            blocks.push({ type: "image", mimeType: p.mimeType, data: p.data });
+        else if (p.type === "audio" && caps.audio)
+            blocks.push({ type: "audio", mimeType: p.mimeType, data: p.data });
+        else if (p.type === "file" && caps.embeddedContext) {
+            blocks.push({ type: "resource", resource: { uri: `attachment:///${p.name || "attachment"}`, mimeType: p.mimeType, blob: p.data } });
+        }
+    }
+    return blocks;
 }
 /**
  * Opens one ACP connection: spawns `command`, performs `initialize` →
@@ -268,6 +339,8 @@ export async function loadACP(opts) {
         }
     };
     const initializeResult = await step("initialize", () => call("initialize", { protocolVersion: opts.protocolVersion ?? 1, clientCapabilities }));
+    const pc = initializeResult?.agentCapabilities?.promptCapabilities ?? {};
+    const promptCaps = { image: pc.image === true, audio: pc.audio === true, embeddedContext: pc.embeddedContext === true };
     const sessionParams = { cwd, mcpServers: opts.mcpServers ?? [] };
     if (opts.sessionMeta)
         sessionParams._meta = opts.sessionMeta;
@@ -302,9 +375,11 @@ export async function loadACP(opts) {
     async function promptOnce(request, emit, signal) {
         if (signal?.aborted)
             throw acpAbortError();
-        const text = renderPrompt(request);
+        const { text, parts } = renderPrompt(request);
         const id = `c-${++nextId}`;
         let content = "";
+        const files = []; // inbound media, in arrival order
+        const messageParts = []; // media the agent sent as message chunks
         const toolNames = new Map();
         const send = (ev) => {
             try {
@@ -320,6 +395,13 @@ export async function loadACP(opts) {
             const u = params?.update;
             switch (u?.sessionUpdate) {
                 case "agent_message_chunk": {
+                    const mp = acpBlockPart(u?.content);
+                    if (mp) {
+                        // An image/audio chunk is a part, never text (SPEC §8C ACP content parts).
+                        messageParts.push(mp);
+                        files.push(acpRunFile(mp, "acp", ""));
+                        break;
+                    }
                     const t = u?.content?.text ?? "";
                     content += t;
                     if (t)
@@ -352,11 +434,15 @@ export async function loadACP(opts) {
                     }
                     if (u.status !== "completed" && u.status !== "failed")
                         break;
+                    const { output, parts: toolParts } = acpToolContent(u.content);
+                    for (const p of toolParts)
+                        files.push(acpRunFile(p, name, callId));
                     send({
                         type: "tool_result",
                         id: callId,
                         name,
-                        output: acpToolContentText(u.content),
+                        output,
+                        ...(toolParts.length ? { parts: toolParts } : {}),
                         isError: u.status === "failed",
                         via: "acp",
                     });
@@ -367,7 +453,7 @@ export async function loadACP(opts) {
         if (exited)
             throw new Error(exitMessage("session/prompt"));
         const replyPromise = new Promise((resolve) => pending.set(id, { method: "session/prompt", cb: resolve }));
-        write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } });
+        write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: promptBlocks(text, parts, promptCaps) } });
         let timer;
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)), permissionTimeoutMs);
@@ -400,7 +486,9 @@ export async function loadACP(opts) {
                 throw new Error(msg.error.message);
             if (msg.error)
                 throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`);
-            return { content };
+            // With no message text but media chunks, the answer is their §1B description.
+            const answer = content === "" && messageParts.length ? messageParts.map(summarizePart).join("\n") : content;
+            return files.length ? { content: answer, files } : { content: answer };
         }
         finally {
             clearTimeout(timer);
@@ -478,9 +566,43 @@ function killGroup(pid, signal) {
         // already gone
     }
 }
-/** Joins the text of an ACP tool_call_update's `content` array ({content:{text}} parts). */
-function acpToolContentText(content) {
+/** Reads an ACP tool_call_update's `content` array ([{type:"content", content:ContentBlock}]):
+ *  text blocks join into the output; image/audio blocks become parts. With no text, the
+ *  output is the parts' §1B description (as for an image-only MCP result, §0.4). */
+function acpToolContent(content) {
     if (!Array.isArray(content))
-        return "";
-    return content.map((p) => (typeof p?.content?.text === "string" ? p.content.text : "")).join("");
+        return { output: "", parts: [] };
+    const parts = [];
+    let output = "";
+    for (const item of content) {
+        const p = acpBlockPart(item?.content);
+        if (p)
+            parts.push(p);
+        else if (typeof item?.content?.text === "string")
+            output += item.content.text;
+    }
+    if (output === "" && parts.length)
+        output = parts.map(summarizePart).join("\n");
+    return { output, parts };
+}
+/** An ACP image/audio ContentBlock ({type, mimeType, data, uri?}) as a §1B part: data wins,
+ *  a uri-only block is a URL part; any other block is not a part. */
+function acpBlockPart(blk) {
+    if (!blk || (blk.type !== "image" && blk.type !== "audio"))
+        return undefined;
+    const mimeType = blk.mimeType ?? "";
+    if (typeof blk.data === "string" && blk.data)
+        return { type: blk.type, mimeType, data: blk.data };
+    if (typeof blk.uri === "string" && blk.uri)
+        return { type: blk.type, mimeType, url: blk.uri };
+    return undefined;
+}
+/** One inbound part as a RunResult.files entry. */
+function acpRunFile(p, from, callId) {
+    const f = { type: p.type, mimeType: p.mimeType, from, callId };
+    if (p.url)
+        f.url = p.url;
+    if (p.data)
+        f.data = p.data;
+    return f;
 }

package/dist/client.d.ts

@@ -435,12 +435,15 @@ export type StreamEvent = {
     name: string;
     args: Record<string, unknown>;
     via: "acp";
-} | {
+}
+/** `parts`: the result's non-text output (§1B), e.g. an image an ACP agent's own tool returned. */
+ | {
     type: "tool_result";
     id: string;
     name: string;
     output: string;
     isError: boolean;
+    parts?: ContentPart[];
     metadata?: Record<string, unknown>;
     via?: "call_tool" | "acp";
 } | {
@@ -703,6 +706,9 @@ export interface InProcessResponse {
         completionTokens?: number;
         totalTokens?: number;
     };
+    /** Media the model's own agent-side tools or messages produced (e.g. an ACP agent's
+     *  images). Appended to RunResult.files after the loop's own tool files. */
+    files?: RunFile[];
 }
 /** A streaming in-process model: `emit` each event as it happens — `text` deltas become
  *  the streamed answer as they arrive; any other event (thought, an agent's own tool_call /

package/dist/client.js

@@ -3,6 +3,7 @@
  * ("openai" | "anthropic"), and it runs the tool-calling agent loop against a
  * Toolkit. See ../../SPEC.md §8.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { mediaPartPath } from "./media.js";
 import { pendingOf } from "./types.js";
 import { toOpenAI, toAnthropic } from "./adapters.js";
@@ -414,9 +415,14 @@ export class Client {
      */
     async run(prompt, ctx) {
         checkPromptParts(prompt, this.wireOpts());
-        return this.opts.style === "anthropic"
+        const agentFiles = [];
+        const r = await agentFilesSink.run(agentFiles, () => this.opts.style === "anthropic"
             ? this.runAnthropic(prompt, ctx?.toolkit, ctx?.signal, ctx?.history)
-            : this.runOpenAI(prompt, ctx?.toolkit, ctx?.signal, ctx?.history);
+            : this.runOpenAI(prompt, ctx?.toolkit, ctx?.signal, ctx?.history));
+        // Agent-side media (an in-process model's own tools) follow the loop's tool files.
+        if (agentFiles.length)
+            r.files = [...r.files, ...agentFiles];
+        return r;
     }
     /**
      * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
@@ -1336,6 +1342,9 @@ export class Client {
         messages.push({ role: "user", content: prompt });
         let tools = toOpenAI(this.requestTools(toolkit));
         const toolCalls = [];
+        // Agent-side media from an in-process answer (§8C ACP content parts), after the loop's own.
+        const agentFiles = [];
+        const withAgentFiles = (r) => (agentFiles.length ? { ...r, files: [...r.files, ...agentFiles] } : r);
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
         // The model of the last call this run made (a beforeLLM override when one applied) — §8.
@@ -1393,6 +1402,10 @@ export class Client {
                             yield j[IN_PROCESS_SIDE_KEY];
                             continue;
                         }
+                        if (j && j[IN_PROCESS_FILES_KEY] && this.opts.baseUrl === IN_PROCESS_BASE_URL) {
+                            agentFiles.push(...j[IN_PROCESS_FILES_KEY]);
+                            continue;
+                        }
                         if (j?.usage)
                             addUsage(usage, j.usage, "openai");
                         const choice = j?.choices?.[0];
@@ -1435,7 +1448,7 @@ export class Client {
                         continue;
                     }
                     yield { type: "usage", usage };
-                    yield { type: "done", result: this.endRun(runStart, lastModel, (rs?.carry ?? "") + content, messages, toolCalls, turns, usage) };
+                    yield { type: "done", result: withAgentFiles(this.endRun(runStart, lastModel, (rs?.carry ?? "") + content, messages, toolCalls, turns, usage)) };
                     return;
                 }
                 if (rs)
@@ -1460,7 +1473,7 @@ export class Client {
                         if (r.halted) {
                             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) };
+                            yield { type: "done", result: withAgentFiles(this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage)) };
                             return;
                         }
                     }
@@ -1470,7 +1483,7 @@ export class Client {
                 }
                 await this.roundEnd(messages, turn, false, "");
             }
-            yield { type: "done", result: this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true) };
+            yield { type: "done", result: withAgentFiles(this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true)) };
         }
         catch (e) {
             this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
@@ -1634,6 +1647,10 @@ const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
 /** The in-band SSE key that carries a non-text stream event from an in-process
  *  streaming generate to the consumer (honoured only on {@link IN_PROCESS_BASE_URL}). */
 const IN_PROCESS_SIDE_KEY = "toolnexus_event";
+/** The in-band SSE key carrying an in-process answer's `files` to `stream()` (same sentinel rule). */
+const IN_PROCESS_FILES_KEY = "toolnexus_files";
+/** Per-`run()` sink for an in-process answer's `files` — they are agent-side, not loop tool calls. */
+const agentFilesSink = new AsyncLocalStorage();
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
  * the reusable piece of {@link createInProcessClient} — assembles the wire request,
@@ -1663,6 +1680,8 @@ export function createInProcessFetch(generate, generateStream) {
                 "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.");
         }
         const answer = generate ? await generate(request) : await generateStream(request, () => { });
+        if (answer.files?.length)
+            agentFilesSink.getStore()?.push(...answer.files);
         const message = { role: "assistant" };
         if (answer.toolCalls && answer.toolCalls.length > 0) {
             message.tool_calls = wireToolCalls(answer.toolCalls, false);
@@ -1725,6 +1744,8 @@ function inProcessStream(generateStream, request) {
                         }
                         chunk({ [IN_PROCESS_SIDE_KEY]: ev });
                     });
+                    if (answer.files?.length)
+                        chunk({ [IN_PROCESS_FILES_KEY]: answer.files });
                     let finish = "stop";
                     if (answer.toolCalls && answer.toolCalls.length > 0) {
                         chunk({ choices: [{ index: 0, delta: { tool_calls: wireToolCalls(answer.toolCalls, true) } }] });

package/dist/media.d.ts

@@ -167,7 +167,7 @@ export declare const A2E_STYLE: MediaStyle & {
 };
 /**
  * Built-in CLI presets for {@link loadMediaStyle} (ADR 0042): media through a locally installed,
- * logged-in CLI on the user's own subscription, no API key. The `*Mock` twins behave the same
+ * logged-in CLI: the vendor's official CLI in its documented headless mode, signed in by the user; the provider's terms apply. The `*Mock` twins behave the same
  * (name, verbs, args, prompt folding, errors) but never start a process and return a fixed file.
  */
 export declare const MediaStyle: {

package/dist/media.js

@@ -361,7 +361,7 @@ export const A2E_STYLE = {
 };
 /**
  * Built-in CLI presets for {@link loadMediaStyle} (ADR 0042): media through a locally installed,
- * logged-in CLI on the user's own subscription, no API key. The `*Mock` twins behave the same
+ * logged-in CLI: the vendor's official CLI in its documented headless mode, signed in by the user; the provider's terms apply. The `*Mock` twins behave the same
  * (name, verbs, args, prompt folding, errors) but never start a process and return a fixed file.
  */
 export const MediaStyle = {
@@ -1780,7 +1780,7 @@ const GROK_SPEC = {
     command: "grok",
     templates: {
         image: "Generate exactly one image with your image generation tool: {prompt}. Do not write code. Reply only with the file path.",
-        video: "Generate exactly one short video with your video generation tool, shortest duration available: {prompt}. Do not write code. Reply only with the file path.",
+        video: "Generate exactly one video with your video generation tool: {prompt}. Do not write code. Reply only with the file path.",
     },
     argv: (prompt, cwd, model) => [
         "-p", prompt, "--cwd", cwd, "--output-format", "streaming-json", "--yolo", "--no-auto-update",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/acp.ts

@@ -34,7 +34,8 @@
 import { spawn } from "node:child_process"
 import { createInterface } from "node:readline"
 import path from "node:path"
-import type { InProcessRequest, InProcessResponse, StreamEvent } from "./client.js"
+import type { InProcessRequest, InProcessResponse, RunFile, StreamEvent } from "./client.js"
+import { isContentPart, summarizePart, type ContentPart } from "./content.js"
 
 /** Options for {@link loadACP}. `command`/`args` spawn the ACP agent as a child
  *  process; everything else tunes the session handshake. */
@@ -135,18 +136,64 @@ interface RpcMessage {
   error?: { code: number; message: string }
 }
 
-function renderContentPart(part: any): string {
+function renderContentPart(part: any, media?: ContentPart[]): string {
   if (typeof part === "string") return part
   if (part == null) return ""
   if (typeof part === "object" && "text" in part && typeof part.text === "string") return part.text
+  // A media part (OpenAI chat wire shape) is named by its §1B one-liner, never its bytes;
+  // the part itself travels as a native ACP block (SPEC §8C "ACP content parts").
+  const p = acpWirePart(part)
+  if (p && p.type !== "text") {
+    media?.push(p)
+    return summarizePart(p)
+  }
   return JSON.stringify(part)
 }
 
-/** Flattens `content` (a string, or an array of content parts) to plain text. */
-function renderContent(content: any): string {
+/** `data:<mime>;base64,<payload>` (non-empty mime) ⇒ {mimeType, data}; anything else ⇒ undefined (SPEC §8C). */
+function parseBase64DataUrl(u: string): { mimeType: string; data: string } | undefined {
+  if (!u.startsWith("data:")) return undefined
+  const comma = u.indexOf(",")
+  if (comma < 0) return undefined
+  const meta = u.slice(5, comma)
+  if (!meta.endsWith(";base64")) return undefined
+  const mimeType = meta.slice(0, -";base64".length)
+  return mimeType ? { mimeType, data: u.slice(comma + 1) } : undefined
+}
+
+/** One OpenAI chat media block read back into a §1B part, as SPEC §8C pins it (Go acpWirePart). */
+function acpWirePart(part: any): ContentPart | undefined {
+  switch (part?.type) {
+    case "image_url": {
+      const url = typeof part.image_url?.url === "string" ? part.image_url.url : ""
+      const d = parseBase64DataUrl(url)
+      if (d) return { type: "image", ...d } as ContentPart
+      // A URL-only image part: EMPTY mimeType, never inferred from the URL.
+      return url ? ({ type: "image", mimeType: "", url } as ContentPart) : undefined
+    }
+    case "input_audio": {
+      let mimeType = "audio/" + String(part.input_audio?.format ?? "")
+      if (mimeType === "audio/mp3") mimeType = "audio/mpeg"
+      return { type: "audio", mimeType, data: String(part.input_audio?.data ?? "") } as ContentPart
+    }
+    case "file": {
+      const d = parseBase64DataUrl(String(part.file?.file_data ?? ""))
+      if (!d) return undefined
+      const type = d.mimeType.startsWith("image/") ? "image" : d.mimeType.startsWith("audio/") ? "audio" : "file"
+      const p: any = { type, ...d }
+      if (part.file?.filename) p.name = String(part.file.filename)
+      return p as ContentPart
+    }
+  }
+  return isContentPart(part) && part.type !== "text" ? part : undefined
+}
+
+/** Flattens `content` (a string, or an array of content parts) to plain text; media parts
+ *  found along the way are appended to `media`. */
+function renderContent(content: any, media?: ContentPart[]): string {
   if (typeof content === "string") return content
-  if (Array.isArray(content)) return content.map(renderContentPart).join(" ")
-  return renderContentPart(content)
+  if (Array.isArray(content)) return content.map((p) => renderContentPart(p, media)).join("\n")
+  return renderContentPart(content, media)
 }
 
 /** Renders the FULL assembled request as one prompt string — role + content
@@ -155,9 +202,10 @@ function renderContent(content: any): string {
  *  every turn, not a delta, so this stays stateless like every other
  *  toolnexus model source and never risks a shadow transcript drifting from
  *  the caller's own conversation state. */
-function renderPrompt(request: InProcessRequest): string {
+function renderPrompt(request: InProcessRequest): { text: string; parts: ContentPart[] } {
   const messages = request.messages ?? []
-  const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content)}`)
+  const parts: ContentPart[] = []
+  const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content, parts)}`)
 
   let latest = ""
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -169,7 +217,30 @@ function renderPrompt(request: InProcessRequest): string {
   if (!latest && messages.length > 0) latest = renderContent(messages[messages.length - 1]?.content)
 
   lines.push(`${SUPERSEDES_MARKER} ${latest}`)
-  return lines.join("\n")
+  return { text: lines.join("\n"), parts }
+}
+
+/** The agent's `initialize` `agentCapabilities.promptCapabilities` (absent ⇒ false). */
+interface PromptCaps {
+  image: boolean
+  audio: boolean
+  embeddedContext: boolean
+}
+
+/** The session/prompt ContentBlock array: the text block, then one native block per media
+ *  part the agent advertised support for. A part it cannot take stays named only by its
+ *  description in the text; base64 never enters the text block. */
+function promptBlocks(text: string, parts: ContentPart[], caps: PromptCaps): Record<string, unknown>[] {
+  const blocks: Record<string, unknown>[] = [{ type: "text", text }]
+  for (const p of parts) {
+    if (p.type === "text" || !p.data) continue // ACP media blocks require inline data
+    if (p.type === "image" && caps.image) blocks.push({ type: "image", mimeType: p.mimeType, data: p.data })
+    else if (p.type === "audio" && caps.audio) blocks.push({ type: "audio", mimeType: p.mimeType, data: p.data })
+    else if (p.type === "file" && caps.embeddedContext) {
+      blocks.push({ type: "resource", resource: { uri: `attachment:///${p.name || "attachment"}`, mimeType: p.mimeType, blob: p.data } })
+    }
+  }
+  return blocks
 }
 
 /**
@@ -364,6 +435,8 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   const initializeResult = await step("initialize", () =>
     call("initialize", { protocolVersion: opts.protocolVersion ?? 1, clientCapabilities }),
   )
+  const pc = initializeResult?.agentCapabilities?.promptCapabilities ?? {}
+  const promptCaps: PromptCaps = { image: pc.image === true, audio: pc.audio === true, embeddedContext: pc.embeddedContext === true }
   const sessionParams: Record<string, unknown> = { cwd, mcpServers: opts.mcpServers ?? [] }
   if (opts.sessionMeta) sessionParams._meta = opts.sessionMeta
   const sessionResult = await step("session/new", () => call("session/new", sessionParams))
@@ -401,10 +474,12 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
     signal?: AbortSignal,
   ): Promise<InProcessResponse> {
     if (signal?.aborted) throw acpAbortError()
-    const text = renderPrompt(request)
+    const { text, parts } = renderPrompt(request)
     const id = `c-${++nextId}`
 
     let content = ""
+    const files: RunFile[] = [] // inbound media, in arrival order
+    const messageParts: ContentPart[] = [] // media the agent sent as message chunks
     const toolNames = new Map<string, string>()
     const send = (ev: StreamEvent) => {
       try {
@@ -419,6 +494,13 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
       const u = params?.update
       switch (u?.sessionUpdate) {
         case "agent_message_chunk": {
+          const mp = acpBlockPart(u?.content)
+          if (mp) {
+            // An image/audio chunk is a part, never text (SPEC §8C ACP content parts).
+            messageParts.push(mp)
+            files.push(acpRunFile(mp, "acp", ""))
+            break
+          }
           const t: string = u?.content?.text ?? ""
           content += t
           if (t) send({ type: "text", delta: t })
@@ -447,11 +529,14 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
             send({ type: "tool_call_args", id: callId, name, args: raw, via: "acp" })
           }
           if (u.status !== "completed" && u.status !== "failed") break
+          const { output, parts: toolParts } = acpToolContent(u.content)
+          for (const p of toolParts) files.push(acpRunFile(p, name, callId))
           send({
             type: "tool_result",
             id: callId,
             name,
-            output: acpToolContentText(u.content),
+            output,
+            ...(toolParts.length ? { parts: toolParts } : {}),
             isError: u.status === "failed",
             via: "acp",
           })
@@ -462,7 +547,7 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
 
     if (exited) throw new Error(exitMessage("session/prompt"))
     const replyPromise = new Promise<RpcMessage>((resolve) => pending.set(id, { method: "session/prompt", cb: resolve }))
-    write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } })
+    write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: promptBlocks(text, parts, promptCaps) } })
 
     let timer: NodeJS.Timeout | undefined
     const timeout = new Promise<never>((_, reject) => {
@@ -498,7 +583,9 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
       }
       if (msg.error && msg.error.code === 0) throw new Error(msg.error.message)
       if (msg.error) throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`)
-      return { content }
+      // With no message text but media chunks, the answer is their §1B description.
+      const answer = content === "" && messageParts.length ? messageParts.map(summarizePart).join("\n") : content
+      return files.length ? { content: answer, files } : { content: answer }
     } finally {
       clearTimeout(timer)
       if (onAbort) signal!.removeEventListener("abort", onAbort)
@@ -583,8 +670,36 @@ function killGroup(pid: number, signal: NodeJS.Signals): void {
   }
 }
 
-/** Joins the text of an ACP tool_call_update's `content` array ({content:{text}} parts). */
-function acpToolContentText(content: any): string {
-  if (!Array.isArray(content)) return ""
-  return content.map((p: any) => (typeof p?.content?.text === "string" ? p.content.text : "")).join("")
+/** Reads an ACP tool_call_update's `content` array ([{type:"content", content:ContentBlock}]):
+ *  text blocks join into the output; image/audio blocks become parts. With no text, the
+ *  output is the parts' §1B description (as for an image-only MCP result, §0.4). */
+function acpToolContent(content: any): { output: string; parts: ContentPart[] } {
+  if (!Array.isArray(content)) return { output: "", parts: [] }
+  const parts: ContentPart[] = []
+  let output = ""
+  for (const item of content) {
+    const p = acpBlockPart(item?.content)
+    if (p) parts.push(p)
+    else if (typeof item?.content?.text === "string") output += item.content.text
+  }
+  if (output === "" && parts.length) output = parts.map(summarizePart).join("\n")
+  return { output, parts }
+}
+
+/** An ACP image/audio ContentBlock ({type, mimeType, data, uri?}) as a §1B part: data wins,
+ *  a uri-only block is a URL part; any other block is not a part. */
+function acpBlockPart(blk: any): ContentPart | undefined {
+  if (!blk || (blk.type !== "image" && blk.type !== "audio")) return undefined
+  const mimeType: string = blk.mimeType ?? ""
+  if (typeof blk.data === "string" && blk.data) return { type: blk.type, mimeType, data: blk.data }
+  if (typeof blk.uri === "string" && blk.uri) return { type: blk.type, mimeType, url: blk.uri }
+  return undefined
+}
+
+/** One inbound part as a RunResult.files entry. */
+function acpRunFile(p: ContentPart, from: string, callId: string): RunFile {
+  const f: RunFile = { type: p.type as RunFile["type"], mimeType: (p as any).mimeType, from, callId }
+  if ((p as any).url) f.url = (p as any).url
+  if ((p as any).data) f.data = (p as any).data
+  return f
 }

package/src/client.ts

@@ -3,6 +3,7 @@
  * ("openai" | "anthropic"), and it runs the tool-calling agent loop against a
  * Toolkit. See ../../SPEC.md §8.
  */
+import { AsyncLocalStorage } from "node:async_hooks"
 import { mediaPartPath } from "./media.js"
 import type { Toolkit } from "./toolkit.js"
 import type { Tool, ToolHints, ToolResult, Request, Answer } from "./types.js"
@@ -465,7 +466,8 @@ export type StreamEvent =
   /** An ACP agent's `tool_call_update` carrying `rawInput`: the call's arguments, known after
    *  the initial `tool_call` (#188). Reported only; never executed by the loop. */
   | { type: "tool_call_args"; id: string; name: string; args: Record<string, unknown>; via: "acp" }
-  | { type: "tool_result"; id: string; name: string; output: string; isError: boolean; metadata?: Record<string, unknown>; via?: "call_tool" | "acp" }
+  /** `parts`: the result's non-text output (§1B), e.g. an image an ACP agent's own tool returned. */
+  | { type: "tool_result"; id: string; name: string; output: string; isError: boolean; parts?: ContentPart[]; metadata?: Record<string, unknown>; via?: "call_tool" | "acp" }
   | { type: "usage"; usage: Usage }
   /** Only with `fallbackModels`: switching from model `from` to `to` after overload (§8). */
   | { type: "fallback"; from: string; to: string }
@@ -744,9 +746,13 @@ export class Client {
    */
   async run(prompt: PromptInput, ctx?: { toolkit?: Toolkit; signal?: AbortSignal; history?: any[] }): Promise<RunResult> {
     checkPromptParts(prompt, this.wireOpts())
-    return this.opts.style === "anthropic"
+    const agentFiles: RunFile[] = []
+    const r = await agentFilesSink.run(agentFiles, () => this.opts.style === "anthropic"
       ? this.runAnthropic(prompt, ctx?.toolkit, ctx?.signal, ctx?.history)
-      : this.runOpenAI(prompt, ctx?.toolkit, ctx?.signal, ctx?.history)
+      : this.runOpenAI(prompt, ctx?.toolkit, ctx?.signal, ctx?.history))
+    // Agent-side media (an in-process model's own tools) follow the loop's tool files.
+    if (agentFiles.length) r.files = [...r.files, ...agentFiles]
+    return r
   }
 
   /**
@@ -1631,6 +1637,9 @@ export class Client {
     messages.push({ role: "user", content: prompt })
     let tools = toOpenAI(this.requestTools(toolkit))
     const toolCalls: ToolCallRecord[] = []
+    // Agent-side media from an in-process answer (§8C ACP content parts), after the loop's own.
+    const agentFiles: RunFile[] = []
+    const withAgentFiles = (r: RunResult): RunResult => (agentFiles.length ? { ...r, files: [...r.files, ...agentFiles] } : r)
     const usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
     let turns = 0
     // The model of the last call this run made (a beforeLLM override when one applied) — §8.
@@ -1682,6 +1691,10 @@ export class Client {
               yield j[IN_PROCESS_SIDE_KEY] as StreamEvent
               continue
             }
+            if (j && j[IN_PROCESS_FILES_KEY] && this.opts.baseUrl === IN_PROCESS_BASE_URL) {
+              agentFiles.push(...j[IN_PROCESS_FILES_KEY])
+              continue
+            }
             if (j?.usage) addUsage(usage, j.usage, "openai")
             const choice = j?.choices?.[0]
             const d = choice?.delta
@@ -1710,7 +1723,7 @@ export class Client {
         if (calls.length === 0) {
           if (await this.roundEnd(messages, turn, true, (rs?.carry ?? "") + content)) { if (rs) rs.carry = ""; continue }
           yield { type: "usage", usage }
-          yield { type: "done", result: this.endRun(runStart, lastModel, (rs?.carry ?? "") + content, messages, toolCalls, turns, usage) }
+          yield { type: "done", result: withAgentFiles(this.endRun(runStart, lastModel, (rs?.carry ?? "") + content, messages, toolCalls, turns, usage)) }
           return
         }
         if (rs) rs.carry = ""
@@ -1732,7 +1745,7 @@ export class Client {
             if (r.halted) {
               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) }
+              yield { type: "done", result: withAgentFiles(this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage)) }
               return
             }
           }
@@ -1742,7 +1755,7 @@ export class Client {
         }
         await this.roundEnd(messages, turn, false, "")
       }
-      yield { type: "done", result: this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true) }
+      yield { type: "done", result: withAgentFiles(this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true)) }
     } catch (e) {
       this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e)
       onInterrupt?.(interruptedTranscript(messages, this.opts.style === "anthropic", done))
@@ -1905,6 +1918,9 @@ export interface InProcessResponse {
   content?: string
   toolCalls?: InProcessToolCall[]
   usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number }
+  /** Media the model's own agent-side tools or messages produced (e.g. an ACP agent's
+   *  images). Appended to RunResult.files after the loop's own tool files. */
+  files?: RunFile[]
 }
 
 /** A streaming in-process model: `emit` each event as it happens — `text` deltas become
@@ -1940,6 +1956,12 @@ const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1"
  *  streaming generate to the consumer (honoured only on {@link IN_PROCESS_BASE_URL}). */
 const IN_PROCESS_SIDE_KEY = "toolnexus_event"
 
+/** The in-band SSE key carrying an in-process answer's `files` to `stream()` (same sentinel rule). */
+const IN_PROCESS_FILES_KEY = "toolnexus_files"
+
+/** Per-`run()` sink for an in-process answer's `files` — they are agent-side, not loop tool calls. */
+const agentFilesSink = new AsyncLocalStorage<RunFile[]>()
+
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
  * the reusable piece of {@link createInProcessClient} — assembles the wire request,
@@ -1974,6 +1996,7 @@ export function createInProcessFetch(generate?: InProcessGenerate, generateStrea
     }
 
     const answer = generate ? await generate(request) : await generateStream!(request, () => {})
+    if (answer.files?.length) agentFilesSink.getStore()?.push(...answer.files)
 
     const message: Record<string, any> = { role: "assistant" }
     if (answer.toolCalls && answer.toolCalls.length > 0) {
@@ -2041,6 +2064,7 @@ function inProcessStream(generateStream: InProcessGenerateStream, request: InPro
             }
             chunk({ [IN_PROCESS_SIDE_KEY]: ev })
           })
+          if (answer.files?.length) chunk({ [IN_PROCESS_FILES_KEY]: answer.files })
           let finish = "stop"
           if (answer.toolCalls && answer.toolCalls.length > 0) {
             chunk({ choices: [{ index: 0, delta: { tool_calls: wireToolCalls(answer.toolCalls, true) } }] })

package/src/media.ts

@@ -522,7 +522,7 @@ export const A2E_STYLE: MediaStyle & { _doc?: string } = {
 
 /**
  * Built-in CLI presets for {@link loadMediaStyle} (ADR 0042): media through a locally installed,
- * logged-in CLI on the user's own subscription, no API key. The `*Mock` twins behave the same
+ * logged-in CLI: the vendor's official CLI in its documented headless mode, signed in by the user; the provider's terms apply. The `*Mock` twins behave the same
  * (name, verbs, args, prompt folding, errors) but never start a process and return a fixed file.
  */
 export const MediaStyle = {
@@ -2009,7 +2009,7 @@ const GROK_SPEC: CliSpec = {
   command: "grok",
   templates: {
     image: "Generate exactly one image with your image generation tool: {prompt}. Do not write code. Reply only with the file path.",
-    video: "Generate exactly one short video with your video generation tool, shortest duration available: {prompt}. Do not write code. Reply only with the file path.",
+    video: "Generate exactly one video with your video generation tool: {prompt}. Do not write code. Reply only with the file path.",
   },
   argv: (prompt, cwd, model) => [
     "-p", prompt, "--cwd", cwd, "--output-format", "streaming-json", "--yolo", "--no-auto-update",