akanjs 3.0.0-beta.8 → 3.0.0

package/ui/Agent/Refer.tsx

@@ -5,17 +5,13 @@ import { type MessageReference, Reference } from "../../vendor/use-agentic";
 
 export interface ReferenceChipsProps {
   className?: string;
-
+  
   references: readonly MessageReference[];
   /** Omitted for a sent message: what is already on the wire cannot be taken back. */
   onRemove?: (key: string) => void;
   removeLabel?: string;
 }
 
-/**
- * What the user pointed at, beside what they are typing. Keyed on the pointer rather than on the row's position:
- * the order a message's references appear in is its text's, and removing one is removing its token.
- */
 export const ReferenceChips = ({ className, references, onRemove, removeLabel }: ReferenceChipsProps) => (
   <div className={cn("flex flex-wrap gap-1", className)}>
     {references.map((reference) => {

package/ui/Agent/RichInput.tsx

@@ -0,0 +1,146 @@
+"use client";
+import { registerPlainText } from "@lexical/plain-text";
+import { cn } from "akanjs/client";
+import {
+  COMMAND_PRIORITY_HIGH,
+  createEditor,
+  KEY_ARROW_DOWN_COMMAND,
+  KEY_ARROW_UP_COMMAND,
+  KEY_ENTER_COMMAND,
+  KEY_ESCAPE_COMMAND,
+  KEY_TAB_COMMAND,
+  type LexicalCommand,
+  PASTE_COMMAND,
+} from "lexical";
+import { type KeyboardEvent as ReactKeyboardEvent, type RefObject, useEffect, useRef, useState } from "react";
+import type { ComposerHandle } from "./Composer";
+import { MentionNode } from "./MentionNode";
+import { MentionDraft } from "./mentionDraft";
+
+interface RichInputProps {
+  className?: string;
+  draft: string;
+  placeholder: string;
+  onDraft: (text: string) => void;
+  /** The textarea's own handler, fed a synthetic event: the chat reads keys off the draft and caret, not the DOM. */
+  onKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+  onFiles: (files: File[]) => void;
+  handleRef?: RefObject<ComposerHandle | null>;
+}
+
+export const RichInput = ({
+  className,
+  draft,
+  placeholder,
+  onDraft,
+  onKeyDown,
+  onFiles,
+  handleRef,
+}: RichInputProps) => {
+  const [editor] = useState(() =>
+    createEditor({
+      namespace: "akanAgentComposer",
+      nodes: [MentionNode],
+      onError: (error: Error) => console.error(error),
+    }),
+  );
+  const rootRef = useRef<HTMLDivElement>(null);
+  const live = useRef({ draft, onDraft, onKeyDown, onFiles });
+  live.current = { draft, onDraft, onKeyDown, onFiles };
+  
+  const settled = useRef(draft);
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    editor.setRootElement(root);
+    const forward = (key: string, event: KeyboardEvent | null) => {
+      const value = MentionDraft.read();
+      const caret = MentionDraft.caret() ?? value.length;
+      let prevented = false;
+      live.current.onKeyDown({
+        key,
+        shiftKey: !!event?.shiftKey,
+        nativeEvent: { isComposing: !!event?.isComposing },
+        currentTarget: { value, selectionStart: caret, selectionEnd: caret },
+        preventDefault: () => {
+          prevented = true;
+          event?.preventDefault();
+        },
+      } as unknown as ReactKeyboardEvent<HTMLTextAreaElement>);
+      return prevented;
+    };
+    
+    const onKey = <T extends KeyboardEvent | null>(command: LexicalCommand<T>, key: string) =>
+      editor.registerCommand<T>(command, (event) => forward(key, event), COMMAND_PRIORITY_HIGH);
+    const teardowns = [
+      registerPlainText(editor),
+      editor.registerUpdateListener(({ editorState }) => {
+        const text = editorState.read(() => MentionDraft.read());
+        if (text === settled.current) return;
+        
+        settled.current = text;
+        live.current.onDraft(text);
+      }),
+      onKey(KEY_ENTER_COMMAND, "Enter"),
+      onKey(KEY_TAB_COMMAND, "Tab"),
+      onKey(KEY_ARROW_UP_COMMAND, "ArrowUp"),
+      onKey(KEY_ARROW_DOWN_COMMAND, "ArrowDown"),
+      onKey(KEY_ESCAPE_COMMAND, "Escape"),
+      editor.registerCommand(
+        PASTE_COMMAND,
+        (event) => {
+          const files = [...(("clipboardData" in event ? event.clipboardData?.files : null) ?? [])];
+          if (!files.length) return false;
+          event.preventDefault();
+          live.current.onFiles(files);
+          return true;
+        },
+        COMMAND_PRIORITY_HIGH,
+      ),
+    ];
+    if (live.current.draft) editor.update(() => MentionDraft.write(live.current.draft), { discrete: true });
+    return () => {
+      for (const teardown of teardowns) teardown();
+      editor.setRootElement(null);
+    };
+  }, [editor]);
+  useEffect(() => {
+    if (draft === settled.current) return;
+    settled.current = draft;
+    editor.update(() => MentionDraft.write(draft), { discrete: true });
+  }, [draft, editor]);
+  useEffect(() => {
+    if (!handleRef) return;
+    handleRef.current = {
+      focus: () => editor.focus(),
+      caret: () => editor.getEditorState().read(() => MentionDraft.caret()),
+      setCaret: (at) => {
+        editor.update(() => MentionDraft.place(at), { discrete: true });
+        editor.focus();
+      },
+    };
+    return () => {
+      handleRef.current = null;
+    };
+  }, [editor, handleRef]);
+  return (
+    <div className="relative flex-1">
+      <div
+        aria-label={placeholder}
+        aria-multiline
+        className={cn("max-h-32 overflow-y-auto whitespace-pre-wrap break-words outline-none", className)}
+        contentEditable
+        ref={rootRef}
+        role="textbox"
+        suppressContentEditableWarning
+      />
+      {draft ? null : (
+        <span className="pointer-events-none absolute inset-0 select-none px-3 py-1.5 text-foreground/40 text-sm">
+          {placeholder}
+        </span>
+      )}
+    </div>
+  );
+};
+
+export default RichInput;

package/ui/Agent/Skip.tsx

@@ -2,25 +2,13 @@ import type { ReactNode } from "react";
 
 export interface SkipProps {
   className?: string;
-  /**
-   * What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. Required
-   * because the marker is the whole point: an unnamed one tells the agent a region exists and nothing about it.
-   */
+  /** What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. */
   label: string;
   children: ReactNode;
 }
 
-/**
- * A region the default `readScreen` leaves out, for chrome that costs the agent tokens and answers nothing — a
- * footer, a cookie banner, a repeated nav. What stands in its place is `[skipped: <label>]`, so an agent asked
- * about the footer says it did not read one instead of reporting that the page has none, and `section: "<label>"`
- * reads it on request.
- *
- * **This hides text, not behaviour.** Tools and state keys are declarations, not markup: an `st.tool` inside here
- * is published exactly as before, and `highlight` still reaches a control in here. It renders a wrapper element,
- * so where a div between a flex container and its children would move the layout, put the attribute on the element
- * the page already renders — `<footer data-agent-skip="site footer">`.
- */
+/** Hides text from `readScreen`, not tools or state. Where a wrapper div would move the layout, put
+ *  `data-agent-skip="<label>"` on an element the page already renders. */
 export const Skip = ({ className, label, children }: SkipProps) => {
   return (
     <div className={className} data-agent-skip={label}>

package/ui/Agent/Steps.tsx

@@ -0,0 +1,33 @@
+"use client";
+import type { AgentProgressReport, ChatMessage, ToolCallResult } from "../../vendor/use-agentic";
+import { createOverridable } from "../UiOverride";
+import Bubble from "./Bubble";
+
+export interface StepsProps {
+  /** One agent turn as rendered: tool messages keep only the results no call row claims. */
+  messages: readonly ChatMessage[];
+  /** True only for the last turn while the session is still working on it. */
+  isRunning: boolean;
+  /** What the running call last reported about itself. */
+  progress?: (AgentProgressReport & { callId: string }) | null;
+  /** Results by call id across the transcript, so a call's own row resolves in place. */
+  results?: ReadonlyMap<string, ToolCallResult>;
+}
+
+/** Draws the turn's messages flat into a Fragment: no element, no `className`. */
+export const DefaultSteps = ({ messages, progress, results }: StepsProps) => {
+  return (
+    <>
+      {messages.map((message, idx) =>
+        
+        message.role === "tool" ? (
+          <Bubble key={idx} message={message} />
+        ) : (
+          <Bubble key={idx} message={message} progress={progress} results={results} />
+        ),
+      )}
+    </>
+  );
+};
+
+export default createOverridable("AgentSteps", DefaultSteps);

package/ui/Agent/ToolCard.tsx

@@ -0,0 +1,32 @@
+"use client";
+import { cn, usePage } from "akanjs/client";
+import type { PendingCard } from "../../vendor/use-agentic";
+import { createOverridable } from "../UiOverride";
+
+export interface ToolCardProps {
+  className?: string;
+  card: PendingCard;
+}
+
+/** Always draws a skip, so a card rendering no cancel of its own cannot park the turn for good. */
+export const DefaultToolCard = ({ className, card }: ToolCardProps) => {
+  const { l } = usePage();
+  return (
+    <div
+      aria-label={l("base.agentToolCard")}
+      className={cn("flex flex-col gap-2 border-primary/30 border-t bg-primary/5 px-4 py-3", className)}
+      role="group"
+    >
+      {card.render({ args: card.args, submit: card.submit, cancel: card.dismiss })}
+      <button
+        className="self-end text-foreground/50 text-xs hover:text-foreground"
+        onClick={() => card.dismiss()}
+        type="button"
+      >
+        {l("base.skip")}
+      </button>
+    </div>
+  );
+};
+
+export default createOverridable("AgentToolCard", DefaultToolCard);

package/ui/Agent/Zone.tsx

@@ -1,5 +1,6 @@
 "use client";
 import { usePage } from "akanjs/client";
+import type { AgentVisualOption } from "akanjs/store";
 import { type ReactNode, useEffect, useMemo, useRef } from "react";
 import {
   AgenticSurface,
@@ -12,55 +13,36 @@ import {
   type SessionHistory,
   useScopePath,
 } from "../../vendor/use-agentic";
-import { agentSessionOf } from "./agentSessionOf";
+import { agentSessionOf, type BuiltinOption, type PersistOption } from "./agentSessionOf";
 import { Guide } from "./Guide";
-import type { PersistOption } from "./sessionHistory";
-import type { BuiltinOption } from "./sessionView";
 
 export interface ZoneProps {
   className?: string;
   /** Names the zone; the scope id and the `data-agent-zone` container both derive from it. */
   id: string;
   label?: string;
-  /** Zone-scoped guidance — a mounted Guide, so the root agent reads it too (ancestor rule), a sibling zone never does. */
+  /** A mounted Guide: the root agent reads it too, a sibling zone never does. */
   instructions?: string;
   runner?: AgentRunner;
   maxTurns?: number;
-  /** When this zone's conversation summarizes itself — same contract as the chat's own `compact`. */
+  /** Same contract as the chat's own `compact`. */
   compact?: CompactOptions;
-  /**
-   * Which of the runtime's own tools this zone's agent gets — all of them by default, `false` none, an array
-   * exactly the ones it names. `builtins={["readScreen", "readState"]}` is how a zone that must not leave the
-   * screen stops being able to: the tools are withheld, not discouraged, so a prompt cannot talk the model past it.
-   */
+  /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
   builtins?: BuiltinOption;
-  /**
-   * Keeps this zone's transcript across reloads, keyed by the zone's scope path — web storage by default, or a
-   * `SessionHistory` of the app's own to keep it anywhere else, a server included.
-   */
+  /** Keyed by the zone's scope path; web storage by default, or an app `SessionHistory`. */
   persist?: PersistOption | SessionHistory;
-  /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+  /** Called after a compaction replaced messages with one summary. */
   onCompact?: AgentSessionOptions["onCompact"];
-  /**
-   * Runs this zone on a session the app built instead of one of its own, and the app then owns it: unmounting the
-   * zone leaves it running. Read once at mount, like every other session option here.
-   */
+  /** On by default; `false` draws nothing, `{ cursor: false }` / `{ reveal: false }` turn one effect off. */
+  visual?: boolean | AgentVisualOption;
+  /** An app-built session the app keeps owning: unmounting leaves it running. Read once at mount. */
   session?: AgentSession;
-  /** Hands the session out once it exists, for a page or store that wants to send into it or watch it. */
+  /** Called once the session exists. */
   onSession?: (session: AgentSession) => void;
   children: ReactNode;
 }
 
-/**
- * A zone agent: one subtree with its own conversation over a scoped view of the same surface. Everything mounted
- * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
- * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
- * on one screen run two conversations in parallel, each seeing only its own subtree.
- *
- * **Everything a zone publishes is named `<id>.<name>`.** Instructions that name a tool must carry the prefix —
- * a bare name is a tool that does not exist, and the model calling it spends a turn on `Unknown tool`. Build the
- * name from the id rather than writing it twice, and read `Agent.Context`'s Assemble to see the published list.
- */
+/** Everything a zone publishes is named `<id>.<name>`, so instructions naming a tool must carry the prefix. */
 export const Zone = ({
   className,
   id,
@@ -72,6 +54,7 @@ export const Zone = ({
   builtins,
   persist,
   onCompact,
+  visual = true,
   session: provided,
   onSession,
   children,
@@ -93,10 +76,11 @@ export const Zone = ({
       builtins,
       persist,
       onCompact,
+      visual,
     });
   const session = held.current;
   useEffect(
-
+    
     () => (provided ? undefined : () => session.abort()),
     [],
   );

package/ui/Agent/agentSessionOf.ts

@@ -1,39 +1,52 @@
-import { AgentContext, ensureStoreSurface, ScreenSettle } from "akanjs/store";
+import { getEnv } from "akanjs/base";
 import {
+  AgentContext,
+  AgentVisual,
+  type AgentVisualOption,
+  ensureStoreSurface,
+  ScreenSettle,
+  StoreSurfaceSource,
+} from "akanjs/store";
+import {
+  type AgenticSurface,
   type AgentRunner,
   AgentSession,
   type AgentSessionOptions,
+  type ChatMessage,
   type CompactOptions,
   type SessionHistory,
+  type SurfaceView,
+  Transcript,
 } from "../../vendor/use-agentic";
 import { fetchRunner } from "./fetchRunner";
-import { type PersistOption, sessionHistoryOf } from "./sessionHistory";
-import { type BuiltinOption, sessionView } from "./sessionView";
+
+/** A tool the akan runtime contributes to every screen, whatever that screen declares. */
+export type AgentBuiltin = (typeof StoreSurfaceSource.builtins)[number];
+
+/** `true` (the default) takes all of them, `false` none, an array exactly the ones it names. */
+export type BuiltinOption = boolean | AgentBuiltin[];
+
+export type PersistOption = boolean | { storage?: "session" | "local"; key?: string };
 
 export interface AgentSessionSetup {
-  /** Read per call rather than captured, so text the session builds follows a language switched mid-conversation. */
+  /** Read per call, so the session's own text follows a language switched mid-conversation. */
   l: (key: string) => string;
-  /** The zone's scope path, empty for the root agent — it picks both the surface view and the persistence key. */
+  /** The zone's scope path, empty for the root agent; it picks both the surface view and the persistence key. */
   view?: string[];
   runner?: AgentRunner;
   instructions?: string;
   maxTurns?: number;
   compact?: CompactOptions;
-  /**
-   * Which of the runtime's own tools this session gets: all of them by default, none with `false`, exactly the
-   * ones an array names. A zone whose conversation must stay on one screen takes `navigate` and `goBack` off it.
-   */
+  /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
   builtins?: BuiltinOption;
-  /** Web storage by default; a `SessionHistory` puts the transcript wherever the app keeps it, including a server. */
+  /** Web storage by default, or an app `SessionHistory`. */
   persist?: PersistOption | SessionHistory;
-  /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+  /** Called after a compaction replaced messages with one summary. */
   onCompact?: AgentSessionOptions["onCompact"];
+  /** `false` draws nothing while this session drives the page. */
+  visual?: boolean | AgentVisualOption;
 }
 
-/**
- * The one place a chat session is wired to the akan runtime. Chat and Zone both build one, and building it twice
- * is how a zone came to be the only surface with no `compact` option — an option added on one side of a copy.
- */
 export const agentSessionOf = ({
   l,
   view = [],
@@ -44,9 +57,11 @@ export const agentSessionOf = ({
   builtins,
   persist,
   onCompact,
+  visual,
 }: AgentSessionSetup): AgentSession => {
   const { surface } = ensureStoreSurface();
   const history = sessionHistoryOf(persist, view.join("."));
+  const drawing = AgentVisual.sink(visual);
   return new AgentSession(sessionView(surface, view, builtins), runner ?? fetchRunner(), {
     buildContext: (scoped) => AgentContext.of().blocks(scoped, view),
     settle: () => ScreenSettle.wait(),
@@ -56,5 +71,90 @@ export const agentSessionOf = ({
     ...(compact ? { compact } : {}),
     ...(history ? { history } : {}),
     ...(onCompact ? { onCompact } : {}),
+    ...(drawing ?? {}),
   });
 };
+
+export const sessionView = (surface: AgenticSurface, path: string[], builtins?: BuiltinOption): SurfaceView => {
+  const scoped = path.length ? surface.view(path) : surface;
+  if (builtins === undefined || builtins === true) return scoped;
+  const kept = new Set<string>(builtins === false ? [] : builtins);
+  const names = StoreSurfaceSource.builtins as readonly string[];
+  const shown = (name: string) => kept.has(name) || !names.includes(name) || surface.declares(name, path);
+  return {
+    snapshot: () => {
+      const snapshot = scoped.snapshot();
+      return { ...snapshot, tools: snapshot.tools.filter((tool) => shown(tool.name)) };
+    },
+    tool: (name) => (shown(name) ? scoped.tool(name) : null),
+    call: async (name, args) => {
+      if (!shown(name)) throw new Error(`Unknown tool: ${name}`);
+      return await scoped.call(name, args);
+    },
+    read: (name) => scoped.read(name),
+    diffSince: (before) => scoped.diffSince(before),
+    subscribe: (listener) => scoped.subscribe(listener),
+  };
+};
+
+const restoredValue =
+  "the conversation was restored from storage, which keeps what the user pointed at but not the value it held";
+
+const withoutContent = (message: ChatMessage): ChatMessage => {
+  if (!message.attachments?.length && !message.references?.length) return message;
+  return {
+    ...message,
+    ...(message.attachments?.length
+      ? {
+          attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
+            name,
+            mimeType,
+            ...(url ? { url } : {}),
+            ...(ref ? { ref } : {}),
+          })),
+        }
+      : {}),
+    ...(message.references?.length
+      ? {
+          references: message.references.map(({ refName, refId, label, path }) => ({
+            refName,
+            refId,
+            label,
+            ...(path ? { path } : {}),
+            note: restoredValue,
+          })),
+        }
+      : {}),
+  };
+};
+
+export const sessionHistoryOf = (
+  persist: PersistOption | SessionHistory | undefined,
+  pathKey = "",
+): SessionHistory | undefined => {
+  if (!persist) return undefined;
+  if (typeof persist === "object" && typeof (persist as SessionHistory).load === "function")
+    return persist as SessionHistory;
+  if (typeof window === "undefined") return undefined;
+  const option = persist === true ? {} : (persist as Exclude<PersistOption, boolean>);
+  const storage = option.storage === "local" ? window.localStorage : window.sessionStorage;
+  const key = option.key ?? `akan.agent.${getEnv().appName}${pathKey ? `.${pathKey}` : ""}`;
+  const version = 1;
+  const cap = 50;
+  return {
+    load: () => {
+      const raw = storage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw) as { v?: number; messages?: ChatMessage[] };
+      return parsed.v === version && Array.isArray(parsed.messages) ? parsed.messages : null;
+    },
+    save: (messages) => {
+      
+      const kept = Transcript.sanitize(messages.slice(-cap)).map(withoutContent);
+      storage.setItem(key, JSON.stringify({ v: version, messages: kept }));
+    },
+    clear: () => {
+      storage.removeItem(key);
+    },
+  };
+};

package/ui/Agent/attachment.ts

@@ -1,34 +1,19 @@
 import type { MessageAttachment } from "../../vendor/use-agentic";
 
-/** Turns one picked file into an attachment, or `null` to say this reader does not handle that file. */
+/** `null` leaves the file to the built-in reader. */
 export type AttachReader = (file: File) => Promise<MessageAttachment | null>;
 
-/**
- * Per-file ceiling for the composer. The bytes ride inside one turn's JSON request, so a file past this is not a
- * slow attachment — it is a request the relay and the provider both refuse, and refusing it here is the only place
- * the user learns which file it was.
- */
+/** The bytes ride inside one turn's JSON request, which the relay and the provider both refuse past this. */
 export const maxAttachmentBytes = 4 * 1024 * 1024;
 
-/**
- * Ceilings for one message rather than one file. The bytes ride inside a single turn's JSON, so what a provider
- * refuses is the sum — and a count cap keeps a whole folder dropped onto the panel from becoming one request that
- * cannot be sent and cannot be edited down without starting over.
- */
+/** A provider refuses the sum of one turn's attachments, not each file. */
 export const maxMessageAttachmentBytes = 8 * 1024 * 1024;
 export const maxMessageAttachments = 5;
 
-/**
- * What the three ceilings above are for an app that knows better. They are a property of the provider the relay is
- * configured with — a larger request limit, or a reader that attaches by `url` and pays none of it — so the
- * defaults are the conservative answer rather than the only one.
- */
 export interface AttachLimits {
-  /** What one attachment may cost the request, measured on what the reader produced. */
+  /** Measured on what the reader produced, not on the source file. */
   perFileBytes?: number;
-  /** What every attachment on one message may cost together. */
   perMessageBytes?: number;
-  /** How many attachments one message may carry. */
   perMessageCount?: number;
 }
 
@@ -37,18 +22,7 @@ export type AttachFailure = "tooLarge" | "unsupported";
 const textMimes = new Set(["application/json", "application/xml", "application/x-yaml", "application/yaml"]);
 
 export class Attachment {
-  /**
-   * Reads what a browser can read on its own — an image as bytes, a text-ish file as text — and hands everything
-   * else to the app's own reader. That split is the layer boundary: a PDF needs a parser, so extracting one is the
-   * app's business (`attach`), while carrying the result is the framework's.
-   *
-   * The app's reader runs first so it can also replace the built-in handling, which is what downscaling an image
-   * before it costs a megabyte of prompt looks like — and it runs before the ceiling too, because the ceiling is
-   * what the attachment costs the request, which is what the reader decides. A reader that answers a `url` has
-   * already paid it; refusing its file on the source size would refuse it for a cost it does not incur. The
-   * built-in carriers are the file itself, so there the source size *is* the cost, and checking it up front is
-   * also what keeps a huge `arrayBuffer` from being read in order to be refused.
-   */
+  
   static async read(
     file: File,
     attach?: AttachReader,
@@ -70,34 +44,23 @@ export class Attachment {
     return typeof value === "string";
   }
 
-  /** What this attachment costs the request: base64 carries three bytes per four characters, less its padding. */
   static bytesOf(attachment: MessageAttachment): number {
     const data = attachment.data ?? "";
     const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
     return Math.max(0, Math.floor((data.length * 3) / 4) - padding) + (attachment.text?.length ?? 0);
   }
 
-  /** Which message ceiling these would pass together, or null when one message can carry them all. */
   static overflow(attachments: readonly MessageAttachment[], limits: AttachLimits = {}): "tooMany" | "tooMuch" | null {
     if (attachments.length > (limits.perMessageCount ?? maxMessageAttachments)) return "tooMany";
     const bytes = attachments.reduce((sum, one) => sum + Attachment.bytesOf(one), 0);
     return bytes > (limits.perMessageBytes ?? maxMessageAttachmentBytes) ? "tooMuch" : null;
   }
 
-  /**
-   * Same name and same size is the same file picked twice — the shape a re-drop or a double paste produces. A
-   * host that can name a file says so with `ref`, and then that is the answer: name and size collide for two
-   * crops of one export, which is a wrong `true` the heuristic cannot avoid and an id never reaches.
-   */
   static same(one: MessageAttachment, other: MessageAttachment): boolean {
     if (one.ref || other.ref) return one.ref === other.ref;
     return one.name === other.name && Attachment.bytesOf(one) === Attachment.bytesOf(other);
   }
 
-  /**
-   * Chunked because `String.fromCharCode(...bytes)` spreads one argument per byte, and a megabyte of them is a
-   * RangeError rather than a slow call.
-   */
   static async #base64(file: File): Promise<string> {
     const bytes = new Uint8Array(await file.arrayBuffer());
     const chunk = 0x8000;

package/ui/Agent/fetchRunner.ts

@@ -2,28 +2,16 @@ import { getEnv } from "akanjs/base";
 import { fetch, Translator } from "akanjs/client";
 import { type AgentRunner, httpRunner, type RunnerEvent } from "../../vendor/use-agentic";
 
-/** `<refName>.error.<key>` — the shape a domain `Err` puts on the wire, its dictionary text being the message. */
 const errorKey = /^[a-zA-Z][A-Za-z0-9]*\.error\.[A-Za-z0-9_]+$/;
 
-/**
- * A server `Err` travels as its key, because the endpoint has no language to resolve it in — the chat does, so
- * the resolving happens here, one step before the transcript. Anything else is already a sentence somebody wrote,
- * and a key with no entry stays as it is rather than becoming a worse sentence.
- */
 const readable = (event: RunnerEvent): RunnerEvent => {
   if (event.type !== "error" || !errorKey.test(event.message)) return event;
   const text = Translator.translateByLocale(Translator.getActiveLocale() ?? "en", event.message, event.data);
-  return text === event.message ? event : { type: "error", message: text };
+  if (text === event.message) return event;
+  return { type: "error", message: text, ...(event.overflow ? { overflow: event.overflow } : {}) };
 };
 
-/**
- * Runs each assistant turn against the app's own `runAgentTurn` route — service signals mount unprefixed, so the
- * URL is `<serverHttpUri>/runAgentTurn` — through the shared `httpRunner`, which negotiates streaming via
- * `accept`: a server that streams answers SSE and the text arrives as it is generated; one that does not answers
- * the same JSON turn. The client runtime's fetch proxy is only probed for whether the endpoint exists (the util
- * lib ships one) and for the signed-in JWT; cookies ride the same-origin request on their own. The endpoint is a
- * stateless relay; the loop and every tool execution stay in this browser session.
- */
+/** Runs each turn against `<serverHttpUri>/runAgentTurn` (service signals mount unprefixed) through `httpRunner`. */
 export const fetchRunner = (options: { fetcher?: typeof globalThis.fetch } = {}): AgentRunner => ({
   async *run(request) {
     const client = fetch as { runAgentTurn?: unknown; instance?: { jwt?: string | null } };

package/ui/Agent/index.ts

@@ -1,14 +1,9 @@
 import { AgentScope } from "../../vendor/use-agentic";
-import Context from "./Context";
-import { Dock } from "./Dock";
+import { Context, Dock, Section, StateKey, Tool, Transcript } from "./Dock";
 import { Guide } from "./Guide";
 import { History } from "./History";
 import { Chat } from "./index_";
-import Section from "./Section";
 import { Skip } from "./Skip";
-import StateKey from "./StateKey";
-import Tool from "./Tool";
-import Transcript from "./Transcript";
 import { Zone } from "./Zone";
 
 export const Agent = {