akanjs 3.1.0-rc.13 → 3.1.0-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.0-rc.13",
+  "version": "3.1.0-rc.14",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/agent.service.ts

@@ -3,6 +3,7 @@ import type {
   AgentWireAttachment,
   AgentWireMessage,
   AgentWireReference,
+  AgentWireToolResult,
   LlmAccepts,
   LlmTurnRequest,
 } from "./predefinedAdaptor/llm.adaptor";
@@ -104,12 +105,21 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
   /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
   static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest {
-    if (!request.messages.some((message) => message.attachments?.length)) return request;
+    if (!request.messages.some(AgentService.carriesFiles)) return request;
     const messages = request.messages.map((message) => AgentService.readableMessage(message, accepts ?? {}));
     return { ...request, messages };
   }
 
+  private static carriesFiles(message: AgentWireMessage): boolean {
+    return !!message.attachments?.length || !!message.toolResults?.some((result) => result.attachments?.length);
+  }
+
   private static readableMessage(message: AgentWireMessage, accepts: LlmAccepts): AgentWireMessage {
+    if (message.role === "tool")
+      return {
+        ...message,
+        toolResults: (message.toolResults ?? []).map((result) => AgentService.readableResult(result, accepts)),
+      };
     const { attachments = [], ...rest } = message;
     if (!attachments.length) return message;
     const kept = attachments.filter((attachment) => AgentService.isReadable(attachment, accepts));
@@ -122,6 +132,16 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     };
   }
 
+  private static readableResult(result: AgentWireToolResult, accepts: LlmAccepts): AgentWireToolResult {
+    if (!result.attachments?.length) return result;
+    const attachments = result.attachments.map((attachment) =>
+      AgentService.isReadable(attachment, accepts)
+        ? attachment
+        : { name: attachment.name, mimeType: attachment.mimeType, text: AgentService.note(attachment) },
+    );
+    return { ...result, attachments };
+  }
+
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -2,6 +2,7 @@ import { adapt } from "../adapt";
 import type {
   AgentWireAttachment,
   AgentWireMessage,
+  AgentWireToolResult,
   LlmAccepts,
   LlmAdaptor,
   LlmLimits,
@@ -14,12 +15,14 @@ import { LlmOverflow } from "./llmOverflow";
 import { eachSseData } from "./sseData";
 
 type AnthropicSource = { type: "base64"; media_type: string; data: string } | { type: "url"; url: string };
-type AnthropicBlock =
+type AnthropicContentBlock =
   | { type: "text"; text: string }
   | { type: "image"; source: AnthropicSource }
-  | { type: "document"; source: AnthropicSource }
+  | { type: "document"; source: AnthropicSource };
+type AnthropicBlock =
+  | AnthropicContentBlock
   | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
-  | { type: "tool_result"; tool_use_id: string; content: string };
+  | { type: "tool_result"; tool_use_id: string; content: string | AnthropicContentBlock[] };
 interface AnthropicMessage {
   role: "user" | "assistant";
   content: AnthropicBlock[];
@@ -221,15 +224,7 @@ export class AnthropicLlm
     if (message.role === "tool")
       return {
         role: "user",
-        content: (message.toolResults ?? []).map((result) => ({
-          type: "tool_result" as const,
-          tool_use_id: result.id,
-          content: JSON.stringify({
-            ...(result.result !== undefined ? { result: result.result } : {}),
-            ...(result.changes?.length ? { changes: result.changes } : {}),
-            ...(result.error ? { error: result.error } : {}),
-          }),
-        })),
+        content: (message.toolResults ?? []).map((result) => AnthropicLlm.toolResult(result, accepts)),
       };
     if (message.role === "assistant")
       return {
@@ -248,9 +243,36 @@ export class AnthropicLlm
   }
 
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[] {
-    const attachments = message.attachments ?? [];
     const notes: string[] = [];
-    const blocks = attachments.flatMap((attachment): AnthropicBlock[] => {
+    const blocks = AnthropicLlm.attachmentBlocks(message.attachments ?? [], accepts, notes);
+    const text = [message.text, ...notes].filter(Boolean).join("\n\n");
+    return [...(text ? [{ type: "text" as const, text }] : []), ...blocks];
+  }
+
+  /** A string while the call returned no file, so a transcript without one posts what it always did. */
+  static toolResult(result: AgentWireToolResult, accepts?: LlmAccepts): AnthropicBlock {
+    const payload = JSON.stringify({
+      ...(result.result !== undefined ? { result: result.result } : {}),
+      ...(result.changes?.length ? { changes: result.changes } : {}),
+      ...(result.error ? { error: result.error } : {}),
+    });
+    if (!result.attachments?.length) return { type: "tool_result", tool_use_id: result.id, content: payload };
+    const notes: string[] = [];
+    const blocks = AnthropicLlm.attachmentBlocks(result.attachments, accepts, notes);
+    return {
+      type: "tool_result",
+      tool_use_id: result.id,
+      content: [{ type: "text", text: [payload, ...notes].join("\n\n") }, ...blocks],
+    };
+  }
+
+  /** Pushes a note for each file no block can carry, for the caller to fold into the text beside them. */
+  static attachmentBlocks(
+    attachments: AgentWireAttachment[],
+    accepts: LlmAccepts | undefined,
+    notes: string[],
+  ): AnthropicContentBlock[] {
+    return attachments.flatMap((attachment): AnthropicContentBlock[] => {
       if (attachment.text)
         return [
           {
@@ -271,8 +293,6 @@ export class AnthropicLlm
       notes.push(`[Attachment not read: ${attachment.name} (${attachment.mimeType}) — this API has no block for it.]`);
       return [];
     });
-    const text = [message.text, ...notes].filter(Boolean).join("\n\n");
-    return [...(text ? [{ type: "text" as const, text }] : []), ...blocks];
   }
 
   static typed(source: AnthropicSource, mimeType: string): AnthropicSource {

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -10,6 +10,8 @@ export interface AgentWireToolResult {
   result?: unknown;
   changes?: unknown[];
   error?: string;
+  /** Files the call handed the model, as content beside the JSON; one this model cannot read arrives as a `text` note. */
+  attachments?: AgentWireAttachment[];
 }
 
 /** Exactly one carrier reaches the model: `data` (inlined bytes), `url` (fetched by the provider) or `text`. */

package/service/predefinedAdaptor/openaiDialect.ts

@@ -1,4 +1,11 @@
-import type { AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
+import type {
+  AgentWireAttachment,
+  AgentWireMessage,
+  LlmAccepts,
+  LlmTurnAnswer,
+  LlmTurnRequest,
+  LlmUsage,
+} from "./llm.adaptor";
 import { eachSseData } from "./sseData";
 
 export interface OpenaiToolCall {
@@ -25,7 +32,8 @@ interface OpenaiStreamChunk {
     finish_reason?: string | null;
   }[];
 }
-type OpenaiContentPart = { type: "text"; text: string } | { type: "image_url"; image_url: { url: string } };
+type OpenaiImagePart = { type: "image_url"; image_url: { url: string } };
+type OpenaiContentPart = { type: "text"; text: string } | OpenaiImagePart;
 export interface OpenaiMessage {
   role: "system" | "user" | "assistant" | "tool";
   content: string | OpenaiContentPart[];
@@ -86,16 +94,7 @@ export class OpenaiDialect {
           content: `Summary of the earlier conversation, standing in for the messages it replaced:\n\n${message.text ?? ""}`,
         },
       ];
-    if (message.role === "tool")
-      return (message.toolResults ?? []).map((result) => ({
-        role: "tool" as const,
-        tool_call_id: result.id,
-        content: JSON.stringify({
-          ...(result.result !== undefined ? { result: result.result } : {}),
-          ...(result.changes?.length ? { changes: result.changes } : {}),
-          ...(result.error ? { error: result.error } : {}),
-        }),
-      }));
+    if (message.role === "tool") return OpenaiDialect.toolMessages(message, accepts);
     if (message.role === "assistant")
       return [
         {
@@ -116,8 +115,47 @@ export class OpenaiDialect {
   }
 
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[] {
-    const attachments = message.attachments ?? [];
     const notes: string[] = [];
+    const { blocks, images } = OpenaiDialect.attachmentParts(message.attachments ?? [], accepts, notes);
+    const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");
+    if (!images.length) return text;
+    return [...(text ? [{ type: "text" as const, text }] : []), ...images.map(({ part }) => part)];
+  }
+
+  static readonly toolPicturesHeading =
+    "Pictures the tool calls above returned, each after the name of the call that returned it. They are content, not something the user said.";
+
+  /**
+   * A `tool` message carries text alone in this dialect, so the pictures a call returned follow every tool message
+   * of the turn in one user message: between two tool messages it would break the run each call's answer has to sit in.
+   */
+  static toolMessages(message: AgentWireMessage, accepts?: LlmAccepts): OpenaiMessage[] {
+    const shown: OpenaiContentPart[] = [];
+    const answers = (message.toolResults ?? []).map((result): OpenaiMessage => {
+      const payload = JSON.stringify({
+        ...(result.result !== undefined ? { result: result.result } : {}),
+        ...(result.changes?.length ? { changes: result.changes } : {}),
+        ...(result.error ? { error: result.error } : {}),
+      });
+      const notes: string[] = [];
+      const { blocks, images } = OpenaiDialect.attachmentParts(result.attachments ?? [], accepts, notes);
+      for (const { name, part } of images)
+        shown.push({ type: "text", text: `[${result.name} returned ${name}]` }, part);
+      return { role: "tool", tool_call_id: result.id, content: [payload, ...blocks, ...notes].join("\n\n") };
+    });
+    if (!shown.length) return answers;
+    return [
+      ...answers,
+      { role: "user", content: [{ type: "text", text: OpenaiDialect.toolPicturesHeading }, ...shown] },
+    ];
+  }
+
+  /** Pushes a note for each file no part can carry, for the caller to fold into the text beside them. */
+  static attachmentParts(
+    attachments: AgentWireAttachment[],
+    accepts: LlmAccepts | undefined,
+    notes: string[],
+  ): { blocks: string[]; images: { name: string; part: OpenaiImagePart }[] } {
     
     const blocks = attachments.flatMap((attachment) =>
       attachment.text ? [`--- attachment: ${attachment.name} (${attachment.mimeType}) ---\n${attachment.text}`] : [],
@@ -138,11 +176,9 @@ export class OpenaiDialect {
           }
           
           const url = attachment.data ? `data:${mimeType};base64,${attachment.data}` : (attachment.url ?? "");
-          return url ? [{ type: "image_url" as const, image_url: { url } }] : [];
+          return url ? [{ name: attachment.name, part: { type: "image_url" as const, image_url: { url } } }] : [];
         });
-    const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");
-    if (!images.length) return text;
-    return [...(text ? [{ type: "text" as const, text }] : []), ...images];
+    return { blocks, images };
   }
 
   static async consumeStream(

package/store/agent/ScreenImage.ts

@@ -0,0 +1,166 @@
+import { Binary } from "akanjs/base";
+import { type MessageAttachment, ToolOutput } from "../../vendor/use-agentic";
+import { ScreenTarget } from "./ScreenTarget";
+
+export interface ScreenImageView {
+  attachment: MessageAttachment;
+  /** The picture's size and how it was sent, for a model asked about its proportions or resolution. */
+  size: string;
+}
+
+/**
+ * A picture on the screen, handed to the model as the browser drew it: redrawn into a JPEG no longer than
+ * `maxEdge`, inlined as bytes. Redrawing turns HEIC, AVIF and SVG into a type every provider reads, bounds what one
+ * picture costs, and leaves the provider nothing to download — a storage path or a `blob:` address it cannot reach,
+ * or a signed URL that expires while the conversation still carries it.
+ */
+export class ScreenImage {
+  /** The long edge Anthropic downscales past; a bigger picture spends upload and latency on pixels nobody reads. */
+  static readonly maxEdge = 1568;
+  static readonly quality = 0.85;
+  static readonly loadMs = 10_000;
+
+  static readonly #typeByExtension = new Map([
+    ["jpg", "image/jpeg"],
+    ["jpeg", "image/jpeg"],
+    ["png", "image/png"],
+    ["gif", "image/gif"],
+    ["webp", "image/webp"],
+  ]);
+
+  /** The `<img>` showing `src` in `root`, matched on what readScreen prints, its absolute form, or the attribute. */
+  static find(src: string, root?: HTMLElement): HTMLImageElement | null {
+    const scope = root ?? (typeof document === "undefined" ? null : document.body);
+    if (!scope) return null;
+    for (const image of scope.querySelectorAll("img"))
+      if (
+        (image.currentSrc === src || image.src === src || image.getAttribute("src") === src) &&
+        ScreenTarget.visible(image)
+      )
+        return image;
+    return null;
+  }
+
+  static async view(image: HTMLImageElement): Promise<ScreenImageView> {
+    const src = image.currentSrc || image.src;
+    const name = ScreenImage.#nameOf(image, src);
+    
+    const loaded = image.complete && image.naturalWidth > 0 ? image : await ScreenImage.#load(src, false);
+    const drawn =
+      (loaded ? await ScreenImage.#draw(loaded, name) : null) ??
+      (await ScreenImage.#drawFrom(await ScreenImage.#load(src, true), name));
+    if (drawn) return drawn;
+    const mimeType = ScreenImage.#typeOf(src);
+    if (mimeType && ScreenImage.publiclyFetchable(src))
+      return {
+        attachment: { name, mimeType, url: src },
+        size: `${ScreenImage.#sizeOf(image)}, sent by address because this page may not read its pixels`,
+      };
+    throw new Error(
+      `${name} cannot be viewed: its host does not let this page read the picture, and the model's provider cannot download it from ${src}. Tell the user you cannot see it.`,
+    );
+  }
+
+  /**
+   * Whether a provider could download `url` itself — an http(s) address off loopback, private, link-local and CGNAT
+   * ranges. It decides between an address and no picture at all; it is not an SSRF guard and must not become one.
+   */
+  static publiclyFetchable(url: string): boolean {
+    if (!/^https?:\/\//i.test(url)) return false;
+    let hostname: string;
+    try {
+      hostname = new URL(url).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname.endsWith(".local")) return false;
+    if (hostname === "internal" || hostname.endsWith(".internal")) return false;
+    if (hostname.startsWith("[")) return !ScreenImage.#privateV6(hostname.slice(1, -1));
+    return !/^(?:0\.|10\.|127\.|169\.254\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(
+      hostname,
+    );
+  }
+
+  static #privateV6(address: string): boolean {
+    if (address === "::" || address === "::1" || address.startsWith("::ffff:")) return true;
+    const first = Number.parseInt(address.split(":")[0] || "0", 16);
+    return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80;
+  }
+
+  static async #drawFrom(image: HTMLImageElement | null, name: string): Promise<ScreenImageView | null> {
+    return image ? await ScreenImage.#draw(image, name) : null;
+  }
+
+  static async #draw(image: HTMLImageElement, name: string): Promise<ScreenImageView | null> {
+    const width = image.naturalWidth || image.width;
+    const height = image.naturalHeight || image.height;
+    if (!width || !height) return null;
+    const scale = Math.min(1, ScreenImage.maxEdge / Math.max(width, height));
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(width * scale));
+    canvas.height = Math.max(1, Math.round(height * scale));
+    const context = canvas.getContext("2d");
+    if (!context) return null;
+    
+    context.fillStyle = "#ffffff";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    let blob: Blob | null;
+    try {
+      blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/jpeg", ScreenImage.quality));
+    } catch {
+      
+      return null;
+    }
+    if (!blob) return null;
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    if (bytes.length > ToolOutput.attachmentBytes)
+      throw new Error(`${name} is ${bytes.length} bytes even as a JPEG, past what one tool result may carry.`);
+    return {
+      attachment: { name, mimeType: "image/jpeg", data: Binary.toBase64(bytes) },
+      size: `${width}×${height}, sent as ${canvas.width}×${canvas.height} JPEG`,
+    };
+  }
+
+  static #load(src: string, cors: boolean): Promise<HTMLImageElement | null> {
+    return new Promise((resolve) => {
+      const image = new Image();
+      if (cors) image.crossOrigin = "anonymous";
+      const timer = setTimeout(() => resolve(null), ScreenImage.loadMs);
+      image.onload = () => {
+        clearTimeout(timer);
+        resolve(image);
+      };
+      image.onerror = () => {
+        clearTimeout(timer);
+        resolve(null);
+      };
+      image.src = src;
+    });
+  }
+
+  static #nameOf(image: HTMLImageElement, src: string): string {
+    const alt = image.getAttribute("alt")?.trim();
+    if (alt) return alt;
+    if (!/^https?:/i.test(src)) return "image";
+    try {
+      return decodeURIComponent(new URL(src).pathname.split("/").pop() ?? "") || "image";
+    } catch {
+      return "image";
+    }
+  }
+
+  static #typeOf(src: string): string | null {
+    let pathname: string;
+    try {
+      pathname = new URL(src).pathname;
+    } catch {
+      return null;
+    }
+    return ScreenImage.#typeByExtension.get(pathname.split(".").pop()?.toLowerCase() ?? "") ?? null;
+  }
+
+  static #sizeOf(image: HTMLImageElement): string {
+    return image.naturalWidth ? `${image.naturalWidth}×${image.naturalHeight}` : "size unknown";
+  }
+}

package/store/agent/StoreSurfaceSource.ts

@@ -1,7 +1,8 @@
 import { router } from "akanjs/client";
-import { AgenticSurface, type SurfaceSource, type ToolEntry } from "../../vendor/use-agentic";
+import { AgenticSurface, type SurfaceSource, type ToolEntry, ToolReturn } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
 import { ScreenFlash } from "./ScreenFlash";
+import { ScreenImage } from "./ScreenImage";
 import { ScreenReader } from "./ScreenReader";
 import { ScreenSettle } from "./ScreenSettle";
 import { ScreenTarget } from "./ScreenTarget";
@@ -9,7 +10,7 @@ import { ScreenTarget } from "./ScreenTarget";
 /** Every screen's built-in tools. A same-named hook tool shadows one at root scope only; a zone uses `builtins`. */
 export class StoreSurfaceSource implements SurfaceSource {
   /** What a session's `builtins` option selects from, in build order. */
-  static readonly builtins = ["navigate", "goBack", "readScreen", "readState", "highlight"] as const;
+  static readonly builtins = ["navigate", "goBack", "readScreen", "readState", "highlight", "viewImage"] as const;
 
   #bridge: AgentBridge | null;
   readonly #builtins = new Map<string, ToolEntry[]>();
@@ -29,6 +30,7 @@ export class StoreSurfaceSource implements SurfaceSource {
         StoreSurfaceSource.#readScreen(viewKey),
         this.#readState(viewKey),
         StoreSurfaceSource.#highlight(viewKey),
+        StoreSurfaceSource.#viewImage(viewKey),
       ];
       this.#builtins.set(viewKey, builtins);
     }
@@ -158,6 +160,38 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
+  static #viewImage(viewKey: string): ToolEntry {
+    const absent = (src: string) =>
+      `No picture at ${src} is on screen now. Call readScreen with images: true and pass an address exactly as it prints one; a picture that has left the screen cannot be viewed.`;
+    return {
+      name: "viewImage",
+      description:
+        "Look at one picture on screen, to answer from what it shows rather than from its caption. Pass an [image] address readScreen printed with `images: true`. Each picture costs this turn over a thousand tokens, so view only the ones the answer needs.",
+      parameters: {
+        type: "object",
+        properties: { src: { type: "string", description: "The image address exactly as readScreen printed it." } },
+        required: ["src"],
+        additionalProperties: false,
+      },
+      settle: false,
+      
+      guard: (args) => {
+        const src = typeof args.src === "string" ? args.src.trim() : "";
+        if (!src) return "viewImage needs a src.";
+        if (src.startsWith("data:"))
+          return "A data: address is the picture's bytes, not an address readScreen prints. Pass one readScreen printed.";
+        return ScreenImage.find(src, StoreSurfaceSource.#zoneRoot(viewKey)) ? true : absent(src);
+      },
+      run: async (args) => {
+        const src = String(args.src).trim();
+        const image = ScreenImage.find(src, StoreSurfaceSource.#zoneRoot(viewKey));
+        if (!image) throw new Error(absent(src));
+        const { attachment, size } = await ScreenImage.view(image);
+        return ToolReturn.attach(`Attached ${attachment.name}: ${size}.`, [attachment]);
+      },
+    };
+  }
+
   #readState(viewKey: string): ToolEntry {
     return {
       name: "readState",

package/store/agent/index.ts

@@ -1,11 +1,12 @@
 
-export { AgentAbort, AgentProgress, type AgentProgressStep } from "../../vendor/use-agentic";
+export { AgentAbort, AgentProgress, type AgentProgressStep, ToolReturn } from "../../vendor/use-agentic";
 export * from "./AgentBridge";
 export * from "./AgentContext";
 export * from "./AgentCursor";
 export * from "./AgentPrompts";
 export * from "./AgentVisual";
 export * from "./ScreenFlash";
+export * from "./ScreenImage";
 export * from "./ScreenReader";
 export * from "./ScreenSettle";
 export * from "./ScreenTarget";

package/types/service/agent.service.d.ts

@@ -31,7 +31,9 @@ export declare class AgentService extends AgentService_base {
     private static fenced;
     /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
     static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest;
+    private static carriesFiles;
     private static readableMessage;
+    private static readableResult;
     private static isReadable;
     private static note;
 }

package/types/service/predefinedAdaptor/anthropicLlm.d.ts

@@ -1,4 +1,4 @@
-import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
+import type { AgentWireAttachment, AgentWireMessage, AgentWireToolResult, LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
 type AnthropicSource = {
     type: "base64";
     media_type: string;
@@ -7,7 +7,7 @@ type AnthropicSource = {
     type: "url";
     url: string;
 };
-type AnthropicBlock = {
+type AnthropicContentBlock = {
     type: "text";
     text: string;
 } | {
@@ -16,7 +16,8 @@ type AnthropicBlock = {
 } | {
     type: "document";
     source: AnthropicSource;
-} | {
+};
+type AnthropicBlock = AnthropicContentBlock | {
     type: "tool_use";
     id: string;
     name: string;
@@ -24,7 +25,7 @@ type AnthropicBlock = {
 } | {
     type: "tool_result";
     tool_use_id: string;
-    content: string;
+    content: string | AnthropicContentBlock[];
 };
 interface AnthropicMessage {
     role: "user" | "assistant";
@@ -90,6 +91,10 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     static providerMessages(messages: AgentWireMessage[], accepts?: LlmAccepts): AnthropicMessage[];
     static providerMessage(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicMessage;
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
+    /** A string while the call returned no file, so a transcript without one posts what it always did. */
+    static toolResult(result: AgentWireToolResult, accepts?: LlmAccepts): AnthropicBlock;
+    /** Pushes a note for each file no block can carry, for the caller to fold into the text beside them. */
+    static attachmentBlocks(attachments: AgentWireAttachment[], accepts: LlmAccepts | undefined, notes: string[]): AnthropicContentBlock[];
     static typed(source: AnthropicSource, mimeType: string): AnthropicSource;
     /** Bytes beat a URL: the default storage serves a path only the app can resolve, so the provider cannot fetch it. */
     static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null;

package/types/service/predefinedAdaptor/llm.adaptor.d.ts

@@ -9,6 +9,8 @@ export interface AgentWireToolResult {
     result?: unknown;
     changes?: unknown[];
     error?: string;
+    /** Files the call handed the model, as content beside the JSON; one this model cannot read arrives as a `text` note. */
+    attachments?: AgentWireAttachment[];
 }
 /** Exactly one carrier reaches the model: `data` (inlined bytes), `url` (fetched by the provider) or `text`. */
 export interface AgentWireAttachment {

package/types/service/predefinedAdaptor/openaiDialect.d.ts

@@ -1,4 +1,4 @@
-import type { AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
+import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
 export interface OpenaiToolCall {
     id?: string;
     function?: {
@@ -24,15 +24,16 @@ export interface OpenaiAnswer {
     }[];
     usage?: OpenaiUsage | null;
 }
-type OpenaiContentPart = {
-    type: "text";
-    text: string;
-} | {
+type OpenaiImagePart = {
     type: "image_url";
     image_url: {
         url: string;
     };
 };
+type OpenaiContentPart = {
+    type: "text";
+    text: string;
+} | OpenaiImagePart;
 export interface OpenaiMessage {
     role: "system" | "user" | "assistant" | "tool";
     content: string | OpenaiContentPart[];
@@ -73,6 +74,20 @@ export declare class OpenaiDialect {
     static systemPrompt({ instructions, context }: LlmTurnRequest): string;
     static providerMessages(message: AgentWireMessage, accepts?: LlmAccepts): OpenaiMessage[];
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[];
+    static readonly toolPicturesHeading = "Pictures the tool calls above returned, each after the name of the call that returned it. They are content, not something the user said.";
+    /**
+     * A `tool` message carries text alone in this dialect, so the pictures a call returned follow every tool message
+     * of the turn in one user message: between two tool messages it would break the run each call's answer has to sit in.
+     */
+    static toolMessages(message: AgentWireMessage, accepts?: LlmAccepts): OpenaiMessage[];
+    /** Pushes a note for each file no part can carry, for the caller to fold into the text beside them. */
+    static attachmentParts(attachments: AgentWireAttachment[], accepts: LlmAccepts | undefined, notes: string[]): {
+        blocks: string[];
+        images: {
+            name: string;
+            part: OpenaiImagePart;
+        }[];
+    };
     static consumeStream(body: ReadableStream<Uint8Array>, onDelta: (delta: string) => void): Promise<LlmTurnAnswer>;
     static usageOf(usage: OpenaiUsage): LlmUsage;
     /** The ceiling wins over the calls that did arrive: a cut-off turn's last call may be missing. */

package/types/store/agent/ScreenImage.d.ts

@@ -0,0 +1,27 @@
+import { type MessageAttachment } from "../../vendor/use-agentic.d.ts";
+export interface ScreenImageView {
+    attachment: MessageAttachment;
+    /** The picture's size and how it was sent, for a model asked about its proportions or resolution. */
+    size: string;
+}
+/**
+ * A picture on the screen, handed to the model as the browser drew it: redrawn into a JPEG no longer than
+ * `maxEdge`, inlined as bytes. Redrawing turns HEIC, AVIF and SVG into a type every provider reads, bounds what one
+ * picture costs, and leaves the provider nothing to download — a storage path or a `blob:` address it cannot reach,
+ * or a signed URL that expires while the conversation still carries it.
+ */
+export declare class ScreenImage {
+    #private;
+    /** The long edge Anthropic downscales past; a bigger picture spends upload and latency on pixels nobody reads. */
+    static readonly maxEdge = 1568;
+    static readonly quality = 0.85;
+    static readonly loadMs = 10000;
+    /** The `<img>` showing `src` in `root`, matched on what readScreen prints, its absolute form, or the attribute. */
+    static find(src: string, root?: HTMLElement): HTMLImageElement | null;
+    static view(image: HTMLImageElement): Promise<ScreenImageView>;
+    /**
+     * Whether a provider could download `url` itself — an http(s) address off loopback, private, link-local and CGNAT
+     * ranges. It decides between an address and no picture at all; it is not an SSRF guard and must not become one.
+     */
+    static publiclyFetchable(url: string): boolean;
+}

package/types/store/agent/StoreSurfaceSource.d.ts

@@ -4,7 +4,7 @@ import { AgentBridge } from "./AgentBridge.d.ts";
 export declare class StoreSurfaceSource implements SurfaceSource {
     #private;
     /** What a session's `builtins` option selects from, in build order. */
-    static readonly builtins: readonly ["navigate", "goBack", "readScreen", "readState", "highlight"];
+    static readonly builtins: readonly ["navigate", "goBack", "readScreen", "readState", "highlight", "viewImage"];
     /** Without a bridge, `AgentBridge.of()` runs at the first `readState` call. */
     constructor(bridge?: AgentBridge);
     tools: (view?: string[]) => ToolEntry[];

package/types/store/agent/index.d.ts

@@ -1,10 +1,11 @@
-export { AgentAbort, AgentProgress, type AgentProgressStep } from "../../vendor/use-agentic.d.ts";
+export { AgentAbort, AgentProgress, type AgentProgressStep, ToolReturn } from "../../vendor/use-agentic.d.ts";
 export * from "./AgentBridge.d.ts";
 export * from "./AgentContext.d.ts";
 export * from "./AgentCursor.d.ts";
 export * from "./AgentPrompts.d.ts";
 export * from "./AgentVisual.d.ts";
 export * from "./ScreenFlash.d.ts";
+export * from "./ScreenImage.d.ts";
 export * from "./ScreenReader.d.ts";
 export * from "./ScreenSettle.d.ts";
 export * from "./ScreenTarget.d.ts";

package/types/vendor/use-agentic/Compaction.d.ts

@@ -1,4 +1,4 @@
-import type { ChatMessage, TurnLimits } from "./types.d.ts";
+import type { ChatMessage, ToolCallResult, TurnLimits } from "./types.d.ts";
 export interface CompactOptions {
     /**
      * Estimated transcript tokens above which a turn summarizes its own history first — a ceiling on what each turn
@@ -50,6 +50,8 @@ export declare class Compaction {
      * more than the slack the estimate leaves.
      */
     static tokensOf(messages: readonly ChatMessage[]): number;
+    /** One tool result as it rides the wire, by the same rule. */
+    static resultTokensOf(result: ToolCallResult): number;
     /**
      * What the next request is estimated to cost, prompt and all: the provider's own count for the last turn that
      * reported one, plus four characters a token for what the transcript gained since. The provider's number is the

package/types/vendor/use-agentic/ToolOutput.d.ts

@@ -10,12 +10,17 @@ import type { ToolCallResult } from "./types.d.ts";
  *
  * Clipped rather than dropped, and the note says what happened: a model handed a value it cannot see the end of
  * asks a narrower question, where one handed nothing answers from the field names.
+ *
+ * A file the call attached is bounded apart: a picture is billed by its pixels, not by the length of its base64, so
+ * counting it as characters would clip every one. It meets the per-file ceiling a user's attachment meets instead.
  */
 export declare class ToolOutput {
     #private;
     /** Characters, ~5k tokens: comfortably above `ScreenReader.limit` and far below any provider's window. */
     static readonly limit = 20000;
-    /** Four characters per token, over the JSON the result rides as — the same estimate `Compaction` places. */
+    /** Bytes of one attached file, as `maxAttachmentBytes` bounds a user's: a provider refuses a turn past it. */
+    static readonly attachmentBytes: number;
+    /** The estimate `Compaction` places: four characters per token over the JSON, and a flat rate per picture. */
     static tokensOf(result: ToolCallResult): number;
     static clipped(result: ToolCallResult): ToolCallResult;
     /**

package/types/vendor/use-agentic/ToolReturn.d.ts

@@ -0,0 +1,18 @@
+import type { MessageAttachment } from "./types.d.ts";
+/**
+ * What a tool's `run` returns when its answer includes files beside the value: `ToolReturn.attach(result, files)`.
+ * `ToolRunner` lifts the files into `ToolCallResult.attachments`, which a backend hands the model as content.
+ */
+export declare class ToolReturn {
+    #private;
+    /** Interned, not an `instanceof`: one page can hold several bundled copies of this package. */
+    static readonly brand: unique symbol;
+    readonly result: unknown;
+    readonly attachments: MessageAttachment[];
+    constructor(result: unknown, attachments: MessageAttachment[]);
+    static attach(result: unknown, attachments: MessageAttachment[]): ToolReturn;
+    static split(value: unknown): {
+        result: unknown;
+        attachments: MessageAttachment[];
+    };
+}

package/types/vendor/use-agentic/Transcript.d.ts

@@ -10,9 +10,16 @@ import type { ChatMessage } from "./types.d.ts";
  * transcript is assembled rather than where each hole is made.
  */
 export declare class Transcript {
+    #private;
     static readonly unanswered = "The turn was stopped before this call ran.";
     /** What one turn posts: no host-only message, no unanswered call, no result answering a call nobody sees. */
     static wire(messages: readonly ChatMessage[]): ChatMessage[];
+    /**
+     * A file a tool returned before the user's latest message, as a note in its place. A picture costs a turn over a
+     * thousand tokens and would ride every turn after the one that asked for it; a later question about it calls the
+     * tool again, which is why the note says to — and to do it while the picture is on screen, where a tool can reach it.
+     */
+    static seen(messages: readonly ChatMessage[]): ChatMessage[];
     /** A message without the provider's count for its turn — what the wire carries and what a compaction keeps. */
     static unmeasured(message: ChatMessage): ChatMessage;
     static sanitize(messages: readonly ChatMessage[]): ChatMessage[];

package/types/vendor/use-agentic/index.d.ts

@@ -13,6 +13,7 @@ export * from "./Reference.d.ts";
 export * from "./sharedContext.d.ts";
 export * from "./surfaceContext.d.ts";
 export * from "./ToolOutput.d.ts";
+export * from "./ToolReturn.d.ts";
 export * from "./ToolRunner.d.ts";
 export * from "./Transcript.d.ts";
 export * from "./types.d.ts";

package/types/vendor/use-agentic/types.d.ts

@@ -144,6 +144,12 @@ export interface ToolCallResult {
     /** What the call changed on the surface — the whole report for a tool that returns nothing. */
     changes?: ResourceDiff[];
     error?: string;
+    /**
+     * Files the call handed the model — a picture it looked at — in the shape a user's attachment takes. A `result`
+     * cannot carry one: it reaches the model as JSON text, so a URL is read as letters and base64 as a wall of them.
+     * Outside the `ToolOutput` ceiling, and only the latest turn's ride the wire as bytes (`Transcript.wire`).
+     */
+    attachments?: MessageAttachment[];
 }
 /**
  * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn

package/ui/Agent/agentSessionOf.ts

@@ -14,6 +14,7 @@ import {
   type AgentSessionOptions,
   type ChatMessage,
   type CompactOptions,
+  type MessageAttachment,
   type SessionHistory,
   type SurfaceView,
   Transcript,
@@ -100,18 +101,24 @@ export const sessionView = (surface: AgenticSurface, path: string[], builtins?:
 const restoredValue =
   "the conversation was restored from storage, which keeps what the user pointed at but not the value it held";
 
+const pointerOf = ({ name, mimeType, url, ref }: MessageAttachment): MessageAttachment => ({
+  name,
+  mimeType,
+  ...(url ? { url } : {}),
+  ...(ref ? { ref } : {}),
+});
+
 const withoutContent = (message: ChatMessage): ChatMessage => {
-  if (!message.attachments?.length && !message.references?.length) return message;
+  const toolFiles = message.toolResults?.some((result) => result.attachments?.length);
+  if (!message.attachments?.length && !message.references?.length && !toolFiles) return message;
   return {
     ...message,
-    ...(message.attachments?.length
+    ...(message.attachments?.length ? { attachments: message.attachments.map(pointerOf) } : {}),
+    ...(toolFiles
       ? {
-          attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
-            name,
-            mimeType,
-            ...(url ? { url } : {}),
-            ...(ref ? { ref } : {}),
-          })),
+          toolResults: message.toolResults?.map((result) =>
+            result.attachments?.length ? { ...result, attachments: result.attachments.map(pointerOf) } : result,
+          ),
         }
       : {}),
     ...(message.references?.length

package/vendor/use-agentic/Compaction.ts

@@ -1,4 +1,5 @@
-import type { ChatMessage, MessageAttachment, TurnLimits } from "./types";
+import { Transcript } from "./Transcript";
+import type { ChatMessage, MessageAttachment, ToolCallResult, TurnLimits } from "./types";
 
 export interface CompactOptions {
   /**
@@ -58,10 +59,17 @@ export class Compaction {
    */
   static tokensOf(messages: readonly ChatMessage[]): number {
     let chars = 0;
-    for (const message of messages) if (!message.local) chars += Compaction.#charsOf(message);
+    for (const message of Transcript.seen(messages)) if (!message.local) chars += Compaction.#charsOf(message);
     return Math.ceil(chars / 4);
   }
 
+  /** One tool result as it rides the wire, by the same rule. */
+  static resultTokensOf(result: ToolCallResult): number {
+    const { attachments, images } = Compaction.#blanked(result.attachments);
+    const chars = JSON.stringify(images ? { ...result, attachments } : result).length;
+    return Math.ceil(chars / 4) + images * Compaction.imageTokens;
+  }
+
   /**
    * What the next request is estimated to cost, prompt and all: the provider's own count for the last turn that
    * reported one, plus four characters a token for what the transcript gained since. The provider's number is the
@@ -88,12 +96,32 @@ export class Compaction {
 
   static #charsOf(message: ChatMessage): number {
     const posted = message.usage ? { ...message, usage: undefined } : message;
-    const images = message.attachments?.filter(Compaction.#isInlinedImage).length ?? 0;
+    const own = Compaction.#blanked(message.attachments);
+    let images = own.images;
+    const toolResults = message.toolResults?.map((result) => {
+      const blanked = Compaction.#blanked(result.attachments);
+      images += blanked.images;
+      return blanked.images ? { ...result, attachments: blanked.attachments } : result;
+    });
     if (!images) return JSON.stringify(posted).length;
-    const attachments = message.attachments?.map((attachment) =>
-      Compaction.#isInlinedImage(attachment) ? { ...attachment, data: "" } : attachment,
+    return (
+      JSON.stringify({ ...posted, attachments: own.attachments, toolResults }).length +
+      images * Compaction.imageTokens * 4
     );
-    return JSON.stringify({ ...posted, attachments }).length + images * Compaction.imageTokens * 4;
+  }
+
+  static #blanked(attachments: MessageAttachment[] | undefined): {
+    attachments: MessageAttachment[] | undefined;
+    images: number;
+  } {
+    const images = attachments?.filter(Compaction.#isInlinedImage).length ?? 0;
+    if (!images) return { attachments, images };
+    return {
+      attachments: attachments?.map((attachment) =>
+        Compaction.#isInlinedImage(attachment) ? { ...attachment, data: "" } : attachment,
+      ),
+      images,
+    };
   }
 
   static #isInlinedImage(attachment: MessageAttachment): boolean {
@@ -185,13 +213,16 @@ export class Compaction {
       );
     for (const call of message.toolCalls ?? [])
       parts.push(`[called ${call.name} ${Compaction.#clip(JSON.stringify(call.args), 200)}]`);
-    for (const result of message.toolResults ?? [])
+    for (const result of message.toolResults ?? []) {
       parts.push(
         `[${result.error ? "failed" : "result"} ${result.name}: ${Compaction.#clip(
           result.error ?? JSON.stringify(result.result ?? null),
           400,
         )}]`,
       );
+      for (const attachment of result.attachments ?? [])
+        parts.push(`[${result.name} returned ${attachment.name}, content not carried into this summary]`);
+    }
     if (message.error) parts.push(`[turn failed: ${message.error}]`);
     return `${message.role}: ${parts.join(" ")}`.trimEnd();
   }

package/vendor/use-agentic/ToolOutput.ts

@@ -1,4 +1,5 @@
-import type { ResourceDiff, ToolCallResult } from "./types";
+import { Compaction } from "./Compaction";
+import type { MessageAttachment, ResourceDiff, ToolCallResult } from "./types";
 
 /**
  * The ceiling on what one tool call may add to the transcript.
@@ -11,14 +12,20 @@ import type { ResourceDiff, ToolCallResult } from "./types";
  *
  * Clipped rather than dropped, and the note says what happened: a model handed a value it cannot see the end of
  * asks a narrower question, where one handed nothing answers from the field names.
+ *
+ * A file the call attached is bounded apart: a picture is billed by its pixels, not by the length of its base64, so
+ * counting it as characters would clip every one. It meets the per-file ceiling a user's attachment meets instead.
  */
 export class ToolOutput {
   /** Characters, ~5k tokens: comfortably above `ScreenReader.limit` and far below any provider's window. */
   static readonly limit = 20_000;
 
-  /** Four characters per token, over the JSON the result rides as — the same estimate `Compaction` places. */
+  /** Bytes of one attached file, as `maxAttachmentBytes` bounds a user's: a provider refuses a turn past it. */
+  static readonly attachmentBytes = 4 * 1024 * 1024;
+
+  /** The estimate `Compaction` places: four characters per token over the JSON, and a flat rate per picture. */
   static tokensOf(result: ToolCallResult): number {
-    return Math.ceil(JSON.stringify(result).length / 4);
+    return Compaction.resultTokensOf(result);
   }
 
   static clipped(result: ToolCallResult): ToolCallResult {
@@ -27,6 +34,21 @@ export class ToolOutput {
       ...(result.result !== undefined ? { result: ToolOutput.#within(result.result) } : {}),
       ...(result.changes?.length ? { changes: result.changes.map((change) => ToolOutput.#change(change)) } : {}),
       ...(result.error ? { error: ToolOutput.#text(result.error) } : {}),
+      ...(result.attachments?.length
+        ? { attachments: result.attachments.map((attachment) => ToolOutput.#attachment(attachment)) }
+        : {}),
+    };
+  }
+
+  static #attachment(attachment: MessageAttachment): MessageAttachment {
+    if (attachment.text) return { ...attachment, text: ToolOutput.#text(attachment.text) };
+    
+    const bytes = Math.floor(((attachment.data?.length ?? 0) * 3) / 4);
+    if (bytes <= ToolOutput.attachmentBytes) return attachment;
+    return {
+      name: attachment.name,
+      mimeType: attachment.mimeType,
+      text: `[Not attached: ${bytes} bytes, past the ${ToolOutput.attachmentBytes}-byte ceiling on one file a tool may return. Tell the user it was too large to look at.]`,
     };
   }
 

package/vendor/use-agentic/ToolReturn.ts

@@ -0,0 +1,32 @@
+import type { MessageAttachment } from "./types";
+
+/**
+ * What a tool's `run` returns when its answer includes files beside the value: `ToolReturn.attach(result, files)`.
+ * `ToolRunner` lifts the files into `ToolCallResult.attachments`, which a backend hands the model as content.
+ */
+export class ToolReturn {
+  /** Interned, not an `instanceof`: one page can hold several bundled copies of this package. */
+  static readonly brand = Symbol.for("use-agentic.ToolReturn");
+
+  readonly result: unknown;
+  readonly attachments: MessageAttachment[];
+
+  constructor(result: unknown, attachments: MessageAttachment[]) {
+    this.result = result;
+    this.attachments = attachments;
+    Object.defineProperty(this, ToolReturn.brand, { value: true });
+  }
+
+  static attach(result: unknown, attachments: MessageAttachment[]): ToolReturn {
+    return new ToolReturn(result, attachments);
+  }
+
+  static split(value: unknown): { result: unknown; attachments: MessageAttachment[] } {
+    if (!ToolReturn.#is(value)) return { result: value, attachments: [] };
+    return { result: value.result, attachments: value.attachments };
+  }
+
+  static #is(value: unknown): value is ToolReturn {
+    return typeof value === "object" && value !== null && ToolReturn.brand in value;
+  }
+}

package/vendor/use-agentic/ToolRunner.ts

@@ -1,7 +1,9 @@
 import { AgentAbort } from "./AgentAbort";
 import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
 import { ToolOutput } from "./ToolOutput";
+import { ToolReturn } from "./ToolReturn";
 import type {
+  ResourceDiff,
   SurfaceView,
   ToolActivity,
   ToolCallRequest,
@@ -155,12 +157,7 @@ export class ToolRunner {
     const answered = await ask({ callId: call.id, name: call.name, args: call.args, render: entry.card }, signal);
     if ("error" in answered) return { ...base, error: answered.error };
     if (entry.settle !== false) await this.#host.settle?.();
-    const changes = this.#surface.diffSince(before);
-    return {
-      ...base,
-      ...(answered.result !== undefined ? { result: answered.result } : {}),
-      ...(changes.length ? { changes } : {}),
-    };
+    return ToolRunner.#answered(base, answered.result, this.#surface.diffSince(before));
   }
 
   async #execute(
@@ -180,7 +177,7 @@ export class ToolRunner {
     try {
       
       if (!this.#stillDecided(call, entry, message)) throw new Error(ToolRunner.#movedError(call.name));
-      const result = await AgentAbort.run(signal, () =>
+      const returned = await AgentAbort.run(signal, () =>
         AgentProgress.run(
           (report) => this.#host.progress?.({ callId: call.id, report }),
           () => ToolRunner.raced(this.#surface.call(call.name, call.args), signal),
@@ -188,12 +185,7 @@ export class ToolRunner {
       );
 
       if (entry.settle !== false) await this.#host.settle?.();
-      const changes = this.#surface.diffSince(before);
-      return {
-        ...base,
-        ...(result !== undefined ? { result } : {}),
-        ...(changes.length ? { changes } : {}),
-      };
+      return ToolRunner.#answered(base, returned, this.#surface.diffSince(before));
     } catch (error) {
       failed = error instanceof Error ? error.message : String(error);
       return { ...base, error: failed };
@@ -224,6 +216,16 @@ export class ToolRunner {
     );
   }
 
+  static #answered(base: { id: string; name: string }, returned: unknown, changes: ResourceDiff[]): ToolCallResult {
+    const { result, attachments } = ToolReturn.split(returned);
+    return {
+      ...base,
+      ...(result !== undefined ? { result } : {}),
+      ...(changes.length ? { changes } : {}),
+      ...(attachments.length ? { attachments } : {}),
+    };
+  }
+
   static #movedError(name: string) {
     return `${name} changed on screen before it ran, so it did not run.`;
   }

package/vendor/use-agentic/Transcript.ts

@@ -1,4 +1,4 @@
-import type { ChatMessage } from "./types";
+import type { ChatMessage, MessageAttachment, ToolCallResult } from "./types";
 
 /**
  * The transcript's own invariant, in one place because three paths break it: a turn stopped between a tool call
@@ -15,7 +15,43 @@ export class Transcript {
 
   /** What one turn posts: no host-only message, no unanswered call, no result answering a call nobody sees. */
   static wire(messages: readonly ChatMessage[]): ChatMessage[] {
-    return Transcript.sanitize(messages.filter((message) => !message.local).map(Transcript.unmeasured));
+    return Transcript.sanitize(
+      Transcript.seen(messages.filter((message) => !message.local)).map(Transcript.unmeasured),
+    );
+  }
+
+  /**
+   * A file a tool returned before the user's latest message, as a note in its place. A picture costs a turn over a
+   * thousand tokens and would ride every turn after the one that asked for it; a later question about it calls the
+   * tool again, which is why the note says to — and to do it while the picture is on screen, where a tool can reach it.
+   */
+  static seen(messages: readonly ChatMessage[]): ChatMessage[] {
+    const latest = messages.findLastIndex((message) => message.role === "user" && !message.summary && !message.local);
+    if (latest <= 0) return [...messages];
+    return messages.map((message, at) =>
+      at < latest && message.toolResults?.some(Transcript.#carriesFile)
+        ? { ...message, toolResults: message.toolResults.map(Transcript.#noted) }
+        : message,
+    );
+  }
+
+  static #carriesFile(result: ToolCallResult): boolean {
+    return !!result.attachments?.some((attachment) => !attachment.text);
+  }
+
+  static #noted(result: ToolCallResult): ToolCallResult {
+    if (!Transcript.#carriesFile(result)) return result;
+    const attachments = result.attachments?.map(
+      (attachment): MessageAttachment =>
+        attachment.text
+          ? attachment
+          : {
+              name: attachment.name,
+              mimeType: attachment.mimeType,
+              text: `[Seen earlier and no longer attached. To look at it again, call ${result.name} again while it is on screen.]`,
+            },
+    );
+    return { ...result, attachments };
   }
 
   /** A message without the provider's count for its turn — what the wire carries and what a compaction keeps. */

package/vendor/use-agentic/WIRE.md

@@ -64,6 +64,26 @@ of one export.
 
 Nothing here is stored: the wire carries the bytes for exactly one turn's request.
 
+### A tool result's files
+
+A `toolResults` entry may carry `attachments` of the same shape — a picture the call looked at, which its `result`
+cannot hold: that reaches the model as JSON text, so a URL in it is read as letters and base64 as a wall of them.
+
+```jsonc
+{ "role": "tool", "toolResults": [{ "id": "c3", "name": "viewImage", "result": "Attached card.jpg: 782×962, sent as 782×962 JPEG.",
+  "attachments": [{ "name": "card.jpg", "mimeType": "image/jpeg", "data": "/9j/4AAQ…" }] }] }
+```
+
+The same rules apply, and a provider format with no place for a file inside a tool result is still no reason to
+drop one. Hand it to the model in the nearest place it reads — a chat-completions `tool` message carries text alone,
+so the pictures follow the turn's tool messages in one user message, each named after the call that returned it —
+and replace what it cannot read with a note **in the attachment's place**, as a `text` attachment of the same name:
+a tool message has no text of its own for a note to join.
+
+The client sends a tool's file as bytes only in the latest turn. One returned before the user's last message arrives
+as such a note, telling the model to call the tool again, since a picture costs a thousand tokens or more on every
+turn it rides.
+
 ## Response
 
 `200` with a single JSON object:

package/vendor/use-agentic/index.ts

@@ -13,6 +13,7 @@ export * from "./Reference";
 export * from "./sharedContext";
 export * from "./surfaceContext";
 export * from "./ToolOutput";
+export * from "./ToolReturn";
 export * from "./ToolRunner";
 export * from "./Transcript";
 export * from "./types";

package/vendor/use-agentic/types.ts

@@ -167,6 +167,12 @@ export interface ToolCallResult {
   /** What the call changed on the surface — the whole report for a tool that returns nothing. */
   changes?: ResourceDiff[];
   error?: string;
+  /**
+   * Files the call handed the model — a picture it looked at — in the shape a user's attachment takes. A `result`
+   * cannot carry one: it reaches the model as JSON text, so a URL is read as letters and base64 as a wall of them.
+   * Outside the `ToolOutput` ceiling, and only the latest turn's ride the wire as bytes (`Transcript.wire`).
+   */
+  attachments?: MessageAttachment[];
 }
 
 /**

package/webkit/McpAppAgent.ts

@@ -4,6 +4,7 @@ import { Logger } from "akanjs/common";
 import { AgentContext, AgentVisual, ensureStoreSurface, ScreenSettle, StoreRegistry } from "akanjs/store";
 import {
   type AgenticSurface,
+  type MessageAttachment,
   type ToolApprovalRequest,
   type ToolCallResult,
   ToolOutput,
@@ -146,7 +147,7 @@ export class McpAppAgent {
     return JSON.stringify(tools);
   }
 
-  static #resultOf({ result, changes, error }: ToolCallResult): McpToolResult {
+  static #resultOf({ result, changes, error, attachments = [] }: ToolCallResult): McpToolResult {
     if (error !== undefined) return { content: [{ type: "text", text: error }], isError: true };
     const text = changes?.length
       ? JSON.stringify({ ...(result !== undefined ? { result } : {}), changes })
@@ -155,6 +156,15 @@ export class McpAppAgent {
         : typeof result === "string"
           ? result
           : JSON.stringify(result);
-    return { content: [{ type: "text", text }] };
+    return { content: [{ type: "text", text }, ...attachments.map(McpAppAgent.#contentOf)] };
+  }
+
+  static #contentOf({ name, mimeType, data, url, text }: MessageAttachment): McpToolResult["content"][number] {
+    if (data !== undefined && mimeType.startsWith("image/")) return { type: "image", data, mimeType };
+    if (text !== undefined) return { type: "text", text: `--- attachment: ${name} (${mimeType}) ---\n${text}` };
+    return {
+      type: "text",
+      text: `[${name} (${mimeType}) was not attached${url ? `; it is at ${url}` : ""}: an MCP tool result carries only pictures, as bytes.]`,
+    };
   }
 }