akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/vendor/@akanjs/native/packages/cli/src/platforms/android.ts

@@ -176,7 +176,7 @@ export function androidManifest(
     <uses-sdk android:minSdkVersion="${MIN_SDK}" android:targetSdkVersion="${TARGET_SDK}" />
     <uses-permission android:name="android.permission.INTERNET" />
 ${permissions.map((p) => `    <uses-permission android:name="${xml(p)}" />`).join("\n")}
-${manifestXml.map((x) => `    ${x.replaceAll("${applicationId}", appId)}`).join("\n")}
+${manifestXml.map((x) => `    ${x.replaceAll(`\${applicationId}`, appId)}`).join("\n")}
 
     <application
         android:name="com.akanjs.runtime.AkanNativeApplication"
@@ -221,7 +221,7 @@ ${config.deepLinks.domains
 ${pathPrefixes.map((prefix) => `                <data android:pathPrefix="${xml(prefix)}" />\n`).join("")}            </intent-filter>`,
   )
   .join("\n")}
-${activityXml.map((x) => `            ${x.replaceAll("${applicationId}", appId)}`).join("\n")}
+${activityXml.map((x) => `            ${x.replaceAll(`\${applicationId}`, appId)}`).join("\n")}
         </activity>
 
         <!-- Framework-only replacement for androidx FileProvider (camera EXTRA_OUTPUT, plugins.md C4) -->
@@ -230,7 +230,7 @@ ${activityXml.map((x) => `            ${x.replaceAll("${applicationId}", appId)}
             android:authorities="${appId}.akan-native.files"
             android:exported="false"
             android:grantUriPermissions="true" />
-${applicationXml.map((x) => `        ${x.replaceAll("${applicationId}", appId)}`).join("\n")}
+${applicationXml.map((x) => `        ${x.replaceAll(`\${applicationId}`, appId)}`).join("\n")}
     </application>
 </manifest>
 `;

package/vendor/@akanjs/native/packages/core/src/kernel.ts

@@ -453,9 +453,9 @@ export function updateReportOutcome(status: number): UpdateReportOutcome {
  * §10.2.3, digits only), else null. An HTTP date is not read; the batch goes at the next launch or return instead.
  */
 export function updateReportRetryAt(retryAfter: string | null, now: number): number | null {
-  const value = retryAfter?.replace(/^[ \t]+|[ \t]+$/g, "") ?? "";
-  if (!/^[0-9]+$/.test(value)) return null;
-  const seconds = Number(value);
+  const digits = /^[ \t]*([0-9]+)[ \t]*$/.exec(retryAfter ?? "")?.[1];
+  if (digits === undefined) return null;
+  const seconds = Number(digits);
   return Number.isFinite(seconds) ? now + seconds : null;
 }
 

package/vendor/@akanjs/native/packages/core/src/live.ts

@@ -12,6 +12,7 @@ export interface LiveValue<T> {
  */
 export function createLiveValue<T>(
   initial: T,
+  
   start?: (set: (value: T) => void) => (() => void) | void,
   equals: (a: T, b: T) => boolean = Object.is,
 ): LiveValue<T> {

package/vendor/@akanjs/native/packages/core/src/plugin.ts

@@ -82,16 +82,18 @@ type WithOptions<F> = F extends (...args: infer P) => infer R
  */
 export type PluginMethods<Api> = { [K in keyof Api]: Api[K] & WithOptions<Api[K]> };
 
-export type Plugin<Api, Events = {}> = PluginMethods<Api> & PluginHandle<Api, Events>;
+export type Plugin<Api, Events = Record<never, never>> = PluginMethods<Api> & PluginHandle<Api, Events>;
 
 const RESERVED = new Set([...RESERVED_MEMBERS, "$$typeof"]);
 
 /** Identity helper that gives web implementations their types. */
-export function defineWebPlugin<Api, Events = {}>(impl: WebPlugin<Api, Events>): WebPlugin<Api, Events> {
+export function defineWebPlugin<Api, Events = Record<never, never>>(
+  impl: WebPlugin<Api, Events>,
+): WebPlugin<Api, Events> {
   return impl;
 }
 
-export function definePlugin<Api extends object, Events extends object = {}>(
+export function definePlugin<Api extends object, Events extends object = Record<never, never>>(
   id: string,
   options: PluginOptions<Api, Events>,
 ): Plugin<Api, Events> {

package/vendor/@akanjs/native/packages/desktop/src/host.ts

@@ -244,7 +244,14 @@ export function startHost(plugins: DesktopPlugin[]): void {
           
           if (req.method === "hang" && boot.dev)
             return new Promise((resolve) =>
-              signal.addEventListener("abort", () => resolve((cancels++, undefined)), { once: true }),
+              signal.addEventListener(
+                "abort",
+                () => {
+                  cancels++;
+                  resolve(undefined);
+                },
+                { once: true },
+              ),
             );
           
           if (req.method === "info" && boot.dev) {
@@ -379,10 +386,11 @@ export function startHost(plugins: DesktopPlugin[]): void {
     const started = performance.now();
     for (let frames = 0; ; frames++) {
       if (frames >= DRAIN_FRAMES || performance.now() - started > DRAIN_MS) {
-        continuation ??= setTimeout(() => {
-          continuation = null;
-          drain();
-        }, 0);
+        if (continuation === null)
+          continuation = setTimeout(() => {
+            continuation = null;
+            drain();
+          }, 0);
         return;
       }
       const size = native.akan_native_poll(buffer, buffer.length);

package/vendor/@akanjs/native/packages/desktop/src/lifecycle.ts

@@ -3,6 +3,7 @@
 export type QuitReason = "user" | "session" | "lastWindowClosed";
 
 /** Return false (or resolve to false) to keep the app running / the window open. */
+
 export type Veto<E> = (event: E) => boolean | void | Promise<boolean | void>;
 
 export interface LifecycleOptions {

package/vendor/@akanjs/native/packages/desktop/src/page-veto.ts

@@ -28,7 +28,7 @@ interface Pending {
   resolve(allow: boolean): void;
 }
 
-export function createPageVeto<D extends object = {}>(ackTimeout = PAGE_ACK_TIMEOUT): PageVeto<D> {
+export function createPageVeto<D extends object = Record<never, never>>(ackTimeout = PAGE_ACK_TIMEOUT): PageVeto<D> {
   let emit: ((data: D & { id: number }, target?: EmitTarget) => number[] | unknown) | null = null;
   let seq = 0;
   const pending = new Map<number, Pending>();

package/vendor/@akanjs/native/packages/desktop/src/plugin.ts

@@ -216,6 +216,7 @@ export interface DesktopPlugin<Api = any, Events = any> {
    */
   events?: {
     [E in keyof Events]?: (
+      
       emit: (data: Events[E], target?: EmitTarget) => number[] | void,
       ctx: DesktopContext,
     ) => () => void;
@@ -272,6 +273,8 @@ export function limitExternalOpens(enabled: boolean): void {
   lastExternalOpen = -Infinity;
 }
 
-export function defineDesktopPlugin<Api, Events = {}>(plugin: DesktopPlugin<Api, Events>): DesktopPlugin<Api, Events> {
+export function defineDesktopPlugin<Api, Events = Record<never, never>>(
+  plugin: DesktopPlugin<Api, Events>,
+): DesktopPlugin<Api, Events> {
   return plugin;
 }

package/vendor/@akanjs/native/plugins/camera/src/web.ts

@@ -12,7 +12,7 @@ type Output = Pick<TakePhotoOptions, "quality" | "maxWidth" | "maxHeight">;
 const jpegQuality = (output: Output) => Math.min(100, Math.max(1, output.quality ?? 90)) / 100;
 
 /** The largest size within the limits, keeping the aspect ratio. */
-function fit(width: number, height: number, output: Output): { width: number; height: number } {
+function fitWithin(width: number, height: number, output: Output): { width: number; height: number } {
   const scale = Math.min(1, (output.maxWidth ?? width) / width, (output.maxHeight ?? height) / height);
   return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
 }
@@ -49,7 +49,7 @@ async function normalized(file: File, output: Output): Promise<Photo> {
     return { url: URL.createObjectURL(file), mime: file.type || "application/octet-stream", size: file.size }; 
   }
   try {
-    const size = fit(bitmap.width, bitmap.height, output);
+    const size = fitWithin(bitmap.width, bitmap.height, output);
     
     if (
       file.type === "image/jpeg" &&
@@ -203,7 +203,7 @@ async function captureWithPreview(options: TakePhotoOptions): Promise<Photo> {
       cancel.onclick = () => finish(() => reject(cancelled()));
       shutter.onclick = () => {
         if (!video.videoWidth || !video.videoHeight) return; 
-        const { width, height } = fit(video.videoWidth, video.videoHeight, options);
+        const { width, height } = fitWithin(video.videoWidth, video.videoHeight, options);
         const canvas = document.createElement("canvas");
         canvas.width = width;
         canvas.height = height;

package/vendor/@akanjs/native/plugins/file-picker/src/index.ts

@@ -198,7 +198,10 @@ export function useFilePicker(): UseFilePicker {
     setError(null);
     
     return start().then(
-      (value) => (setPending(false), value),
+      (value) => {
+        setPending(false);
+        return value;
+      },
       (e: unknown) => {
         setPending(false);
         setError(AkanNativeError.from(e));

package/vendor/@akanjs/native/plugins/local-notifications/src/web.ts

@@ -44,7 +44,7 @@ function dismiss(id: number): void {
 
 function show(n: ScheduledNotification): void {
   const N = api();
-  if (!N || N.permission !== "granted") return; 
+  if (N?.permission !== "granted") return; 
   dismiss(n.id);
   
   const notification = new N(n.title, { body: n.body, tag: `akan-native-${n.id}` });

package/vendor/@akanjs/native/plugins/secure-storage/src/desktop.ts

@@ -315,7 +315,7 @@ export function createDesktopSecureStorage(options: DesktopSecureStorageOptions
           store.entries = new Map(readable);
           save(store);
         }
-        return { keys: readable.map(([name]) => name).sort() };
+        return { keys: readable.map(([name]) => name).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)) };
       },
       clear(_args, ctx) {
         const store = storeFor(ctx);

package/vendor/@akanjs/native/plugins/share/src/options.ts

@@ -1,7 +1,7 @@
 import { AkanNativeError } from "../../../packages/core/src/index.ts";
 import type { ShareOptions } from "./index.ts";
 
-const NOT_LINKS = ["javascript:", "data:", "blob:", "file:"];
+const NOT_LINKS = ["javascript:", "vbscript:", "data:", "blob:", "file:"];
 
 const invalid = (message: string) => new AkanNativeError("INVALID_ARGS", message);
 

package/vendor/@akanjs/native/plugins/single-instance/src/desktop.ts

@@ -30,7 +30,7 @@ export function createDesktopSingleInstance(
     messages.emit(message, true);
   };
 
-  return defineDesktopPlugin<{}, SingleInstanceEvents>({
+  return defineDesktopPlugin<Record<never, never>, SingleInstanceEvents>({
     id: "single-instance",
     
     launchPhase: "gate",
@@ -56,7 +56,8 @@ export function createDesktopSingleInstance(
         const key = String(++listens);
         messages.listen(
           key,
-          (m) => ((emit as (m: SecondInstance, target?: EmitTarget) => number[] | void)(m, "focused")?.length ?? 1) > 0,
+          (m) =>
+            ((emit as (m: SecondInstance, target?: EmitTarget) => number[] | undefined)(m, "focused")?.length ?? 1) > 0,
         );
         return () => messages.unlisten(key);
       },

package/vendor/@akanjs/native/plugins/updates/src/desktop.ts

@@ -420,7 +420,10 @@ export function createDesktopUpdates(options: DesktopUpdatesOptions = {}): Deskt
     }
     const out = new Uint8Array(received);
     let at = 0;
-    for (const c of chunks) out.set(c, at), (at += c.length);
+    for (const c of chunks) {
+      out.set(c, at);
+      at += c.length;
+    }
     return out;
   };
 

package/vendor/@akanjs/native/plugins/window/src/index.ts

@@ -375,13 +375,13 @@ export function useWindowState(): WindowState | null {
  * none prevents it, the window closes as usual. Desktop only: elsewhere it never fires
  * (`appWindow.eventImplementation("closeRequested")` tells). Returns an unregister function.
  */
-export const onCloseRequested: (handler: VetoHandler<{}>) => () => void = vetoable(
+export const onCloseRequested: (handler: VetoHandler<Record<never, never>>) => () => void = vetoable(
   (listener) => appWindow.listen("closeRequested", listener),
   (args) => appWindow.answerCloseRequested(args),
 );
 
 /** onCloseRequested while mounted; always calls the latest handler. */
-export function useCloseRequested(handler: VetoHandler<{}>): void {
+export function useCloseRequested(handler: VetoHandler<Record<never, never>>): void {
   const latest = React.useRef(handler);
   latest.current = handler;
   React.useEffect(() => onCloseRequested((event) => latest.current(event)), []);

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/Reference.ts

@@ -38,25 +38,32 @@ export class Reference {
    *
    * The text is the source of truth for which references a message carries — deleting the token is how somebody
    * takes one back — so the token has to say everything the pointer does. The value is looked up beside it by key.
+   * A label's `\`, `[` and `]` are backslash-escaped, as in a markdown link: titles like "[Ops] Minutes" are common.
    */
   static token(reference: MessageReference): string {
-    return `@[${reference.label}](mention:${Reference.keyOf(reference)})`;
+    return `@[${reference.label.replace(/[\\[\]]/g, "\\$&")}](mention:${Reference.keyOf(reference)})`;
   }
 
-  /** Greedy on the label alone: a label may hold anything but `]`, and every other part is a name or an id. */
-  static readonly pattern = /@\[([^\]]*)\]\(mention:([^/)]+)\/([^#)]+)(?:#([^)]*))?\)/g;
+  /**
+   * Greedy on the label alone: a label may hold an escaped `\\`, `\[` or `\]`, a backslash escaping nothing (a token
+   * written before labels were escaped), and anything else but `]` or an `@[`, where a token starts over. No two
+   * alternatives match at the same place, so a long run cannot backtrack. Every other part is a name, an id or a
+   * dotted path, none of which holds a bracket.
+   */
+  static readonly pattern =
+    /@\[((?:\\[\\[\]]|\\(?![\\[\]])|(?!@\[)[^\]\\])*)\]\(mention:([^/)[\]]+)\/([^#)[\]]+)(?:#([^)[\]]*))?\)/g;
+
+  /** The pointer one match of `pattern` names, its label unescaped. */
+  static pointerOf([, label, refName, refId, path]: RegExpMatchArray): MessageReference {
+    return { refName, refId, label: label.replace(/\\([\\[\]])/g, "$1"), ...(path ? { path } : {}) };
+  }
 
   /**
    * The pointers a draft names, in the order it names them. Pointers only — the value lives in `staged` and is
    * joined on by key, so reading the text can never resurrect a value somebody deleted the token for.
    */
   static parse(text: string): MessageReference[] {
-    return [...text.matchAll(Reference.pattern)].map(([, label, refName, refId, path]) => ({
-      refName,
-      refId,
-      label,
-      ...(path ? { path } : {}),
-    }));
+    return [...text.matchAll(Reference.pattern)].map((match) => Reference.pointerOf(match));
   }
 
   /**

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[];
 }
 
 /**