akanjs 3.1.0-rc.13 → 3.1.0-rc.15

package/client/makePageProto.tsx

@@ -28,11 +28,12 @@ const getPageInfo = (): { locale: string; path: string } => {
   const activePath = Translator.getActivePath();
   if (activePath) return { locale: activeLocale ?? defaultLocale, path: activePath };
   if (getEnv().side !== "server") {
-    const [, firstSegment = "", ...rest] = csrLocation.pathname.split("/");
+    const pathname = Translator.getRenderPath() ?? csrLocation.pathname;
+    const [, firstSegment = "", ...rest] = pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
     
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
-    return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : csrLocation.pathname) };
+    return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : pathname };
   }
   const h = untrackedHeaders();
   

package/client/translator.ts

@@ -18,6 +18,8 @@ interface TranslatorState {
   activeLocale?: string;
   
   activePath?: string;
+  
+  renderPath?: string;
 }
 
 const TRANSLATOR_STATE_KEY = "__AKAN_TRANSLATOR_STATE__";
@@ -57,6 +59,20 @@ export class Translator {
   static getActivePath(): string | undefined {
     return getTranslatorState().activePath;
   }
+  static renderAt<T>(path: string | undefined, render: () => T): T {
+    if (!path) return render();
+    const state = getTranslatorState();
+    const outer = state.renderPath;
+    state.renderPath = path;
+    try {
+      return render();
+    } finally {
+      state.renderPath = outer;
+    }
+  }
+  static getRenderPath(): string | undefined {
+    return getTranslatorState().renderPath;
+  }
   static markHydrated() {
     delete getTranslatorState().activePath;
   }

package/client/viewportMeta.ts

@@ -7,6 +7,9 @@ export interface ThemeColorTag {
 
 /** Turns a root layout's `.viewport()` into the `viewport` and `theme-color` meta tags every document shell writes. */
 export class ViewportMeta {
+  static readonly #offMedia = "not all";
+  static readonly #ownAttr = "data-akan-theme-color";
+
   static content(viewport: RouteViewport | undefined, { native = false }: { native?: boolean } = {}): string {
     const parts = ["width=device-width", "initial-scale=1"];
     if (viewport?.fitCover ?? native) parts.push("viewport-fit=cover");
@@ -39,18 +42,30 @@ export class ViewportMeta {
     const tags = ViewportMeta.themeColors(viewport, theme);
     if (!tags.length) return;
     const existing = [...document.head.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]')];
-
-    for (const meta of existing.slice(tags.length)) meta.setAttribute("media", "not all");
-    tags.forEach((tag, idx) => {
-      const meta = existing[idx] ?? ViewportMeta.#ensureMeta("theme-color", true);
+    const live = existing.filter((meta) => meta.getAttribute("media") !== ViewportMeta.#offMedia);
+    const isCurrent =
+      live.length === tags.length &&
+      tags.every(
+        (tag, idx) => live[idx]?.content === tag.content && live[idx]?.getAttribute("media") === (tag.media ?? null),
+      );
+    if (isCurrent) return;
+    
+    for (const meta of existing) {
+      if (meta.hasAttribute(ViewportMeta.#ownAttr)) meta.remove();
+      else meta.setAttribute("media", ViewportMeta.#offMedia);
+    }
+    for (const tag of tags) {
+      const meta = document.createElement("meta");
+      meta.name = "theme-color";
       meta.content = tag.content;
       if (tag.media) meta.setAttribute("media", tag.media);
-      else meta.removeAttribute("media");
-    });
+      meta.setAttribute(ViewportMeta.#ownAttr, "");
+      document.head.appendChild(meta);
+    }
   }
 
-  static #ensureMeta(name: string, fresh = false): HTMLMetaElement {
-    const found = fresh ? null : document.head.querySelector<HTMLMetaElement>(`meta[name="${name}"]`);
+  static #ensureMeta(name: string): HTMLMetaElement {
+    const found = document.head.querySelector<HTMLMetaElement>(`meta[name="${name}"]`);
     if (found) return found;
     const meta = document.createElement("meta");
     meta.name = name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.0-rc.13",
+  "version": "3.1.0-rc.15",
   "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,43 @@ 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 the <address> of an [image: <alt>](<address>) it prints; 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. readScreen with `images: true` prints each picture as `[image: <alt>](<address>)`, or `[image](<address>)` when it has no alt; pass that address. 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 <address> of an [image: <alt>](<address>) readScreen printed, without the parentheses.",
+          },
+        },
+        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/client/translator.d.ts

@@ -14,6 +14,8 @@ export declare class Translator {
     static getActiveLocale(): string | undefined;
     static setActivePath(path: string | undefined): void;
     static getActivePath(): string | undefined;
+    static renderAt<T>(path: string | undefined, render: () => T): T;
+    static getRenderPath(): string | undefined;
     static markHydrated(): void;
     static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string;
     static withDefaultLocale(allDictionary: AllDictionary, lang: string): Dictionary | undefined;

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;
 }