akanjs 3.0.0-beta.2 → 3.0.0-beta.21

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 = {

package/ui/Agent/mentionDraft.ts

@@ -0,0 +1,91 @@
+"use client";
+import {
+  $createLineBreakNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getRoot,
+  $getSelection,
+  $isElementNode,
+  $isRangeSelection,
+  $isRootNode,
+  $isTextNode,
+  type LexicalNode,
+} from "lexical";
+import { Reference } from "../../vendor/use-agentic";
+import { $createMentionNode, $isMentionNode } from "./MentionNode";
+
+export class MentionDraft {
+  static read(): string {
+    return $getRoot().getTextContent();
+  }
+
+  static write(text: string, caretAt?: number) {
+    const paragraph = $createParagraphNode();
+    paragraph.append(...MentionDraft.nodesOf(text));
+    $getRoot().clear().append(paragraph);
+    MentionDraft.place(caretAt ?? text.length);
+  }
+
+  static nodesOf(text: string): LexicalNode[] {
+    const nodes: LexicalNode[] = [];
+    let at = 0;
+    
+    const pattern = new RegExp(Reference.pattern.source, "g");
+    for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+      const [token, label, refName, refId, path] = match;
+      if (match.index > at) nodes.push(...MentionDraft.#plain(text.slice(at, match.index)));
+      nodes.push($createMentionNode({ refName, refId, label, ...(path ? { path } : {}) }));
+      at = match.index + token.length;
+    }
+    if (at < text.length) nodes.push(...MentionDraft.#plain(text.slice(at)));
+    return nodes;
+  }
+
+  static caret(): number | null {
+    const selection = $getSelection();
+    if (!$isRangeSelection(selection)) return null;
+    const anchor = selection.anchor;
+    const node = anchor.getNode();
+    if ($isTextNode(node)) {
+      
+      const inner = $isMentionNode(node) ? (anchor.offset ? node.getTextContent().length : 0) : anchor.offset;
+      return MentionDraft.#before(node) + inner;
+    }
+    const children = $isElementNode(node) ? node.getChildren() : [];
+    const within = children.slice(0, anchor.offset).reduce((sum, child) => sum + child.getTextContent().length, 0);
+    return MentionDraft.#before(node) + within;
+  }
+
+  static place(at: number) {
+    const paragraph = $getRoot().getLastChild();
+    if (!$isElementNode(paragraph)) return;
+    let seen = 0;
+    for (const child of paragraph.getChildren()) {
+      const length = child.getTextContent().length;
+      if (at <= seen + length) {
+        
+        if ($isTextNode(child) && !$isMentionNode(child)) child.select(at - seen, at - seen);
+        else if (at > seen) child.selectNext(0, 0);
+        else if (child.getPreviousSibling()) child.selectPrevious();
+        else paragraph.select(0, 0);
+        return;
+      }
+      seen += length;
+    }
+    paragraph.selectEnd();
+  }
+
+  static #plain(text: string): LexicalNode[] {
+    return text
+      .split("\n")
+      .flatMap((line, idx) => [...(idx ? [$createLineBreakNode()] : []), ...(line ? [$createTextNode(line)] : [])]);
+  }
+
+  static #before(node: LexicalNode): number {
+    let sum = 0;
+    for (let cursor = node.getPreviousSibling(); cursor; cursor = cursor.getPreviousSibling())
+      sum += cursor.getTextContent().length;
+    const parent = node.getParent();
+    return parent && !$isRootNode(parent) ? sum + MentionDraft.#before(parent) : sum;
+  }
+}

package/ui/Agent/tokenCount.ts

@@ -1,8 +1,4 @@
-/**
- * An estimated token count as a chat-sized label. Rounded hard on purpose: the estimate itself is four characters
- * to a token, so a digit-exact figure would claim a precision it does not have — what a reader needs from it is
- * whether a tool result cost a hundred tokens or a million.
- */
+/** Rounded hard: the estimate is four characters to a token, so exact digits would claim false precision. */
 export const tokenCount = (count: number): string => {
   if (count < 1_000) return String(count);
   if (count < 1_000_000) return `${Math.round(count / 100) / 10}k`;

package/ui/Agent/useChatAttachments.ts

@@ -16,18 +16,13 @@ interface ChatAttachmentsSetup {
   l: (key: string, param?: Record<string, string | number>) => string;
 }
 
-/**
- * What the composer is holding, and the ceilings it holds it under. Staged files are mirrored in a ref because a
- * multi-file drop reads them one at a time: the cap has to see what the previous file of the same drop added, and
- * React state inside that loop is still the value the render started with.
- */
 export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAttachmentsSetup) => {
   const count = limits.perMessageCount ?? maxMessageAttachments;
   const messageBytes = limits.perMessageBytes ?? maxMessageAttachmentBytes;
   const [attached, setAttached] = useState<MessageAttachment[]>([]);
-
   const [pending, setPending] = useState(0);
   const [dragging, setDragging] = useState(false);
+  
   const staged = useRef<MessageAttachment[]>([]);
   
   const depth = useRef(0);
@@ -40,7 +35,6 @@ export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAtta
     depth.current = 0;
     setDragging(false);
   };
-  /** Staged one at a time so one unreadable file names itself instead of failing the whole drop silently. */
   const add = async (files: File[]) => {
     for (const file of files) {
       if (staged.current.length >= count) {
@@ -81,13 +75,12 @@ export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAtta
     onDrop: (event) => {
       const files = [...event.dataTransfer.files];
       rest();
-
+      
       if (!files.length) return;
       event.preventDefault();
       void add(files);
     },
   };
-  /** Stages files taken back from a parked message, ahead of what was picked since. False, noted, when they do not fit. */
   const restore = (list: MessageAttachment[]): boolean => {
     const next = [...list, ...staged.current];
     const overflow = Attachment.overflow(next, limits);

package/ui/Agent/useChatQueue.ts

@@ -1,36 +1,29 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic";
+import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic";
+import { Reference } from "../../vendor/use-agentic";
 import { type AttachLimits, Attachment, maxMessageAttachments } from "./attachment";
 
-/** What the composer held when it was sent: the shape a turn opens with, whether now or after the running one. */
 export interface QueuedMessage {
   text: string;
   attachments: MessageAttachment[];
-  /** The ask came from the microphone, so the reply it gets is read aloud — carried until the send that opens it. */
+  references: MessageReference[];
+  /** The ask came from the microphone, so its reply is read aloud. */
   byVoice: boolean;
 }
 
 interface ChatQueueSetup {
   session: AgentSession;
   limits?: AttachLimits;
-  /** The chat's own version snapshot — the turn ending is one of the changes it counts. */
   version: number;
   l: (key: string, param?: Record<string, string | number>) => string;
   onFlush: (message: QueuedMessage) => void;
 }
 
-/**
- * One message parked while a turn runs, sent the moment the turn ends. One slot rather than a list: a second send
- * joins the first, so what reaches the model is one user message and the user has one thing to take back or drop.
- *
- * Mirrored in a ref because the flush and the drop both race the turn's own wind-down: `/new` empties the slot
- * and then aborts, and the abort's notify would otherwise read the state the render started with and send what
- * was just dropped.
- */
 export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: ChatQueueSetup) => {
   const count = limits.perMessageCount ?? maxMessageAttachments;
   const [queued, setQueued] = useState<QueuedMessage | null>(null);
+  
   const held = useRef<QueuedMessage | null>(null);
   const put = (next: QueuedMessage | null) => {
     held.current = next;
@@ -44,7 +37,6 @@ export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: Chat
   }, [version]);
   return {
     queued,
-    /** Parks a message, joined onto one already waiting. False, with the reason noted, when the files would not fit. */
     push: (message: QueuedMessage): boolean => {
       const before = held.current;
       const attachments = [...(before?.attachments ?? []), ...message.attachments];
@@ -56,11 +48,17 @@ export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: Chat
       put({
         text: [before?.text, message.text].filter(Boolean).join("\n"),
         attachments,
+        
+        references: [
+          ...message.references,
+          ...(before?.references ?? []).filter(
+            (one) => !message.references.some((fresh) => Reference.keyOf(fresh) === Reference.keyOf(one)),
+          ),
+        ],
         byVoice: !!before?.byVoice || message.byVoice,
       });
       return true;
     },
-    /** Empties the slot and answers what was in it — the drop, and the first half of handing it back. */
     take: (): QueuedMessage | null => {
       const message = held.current;
       if (message) put(null);

package/ui/Agent/useChatReferences.ts

@@ -0,0 +1,51 @@
+"use client";
+import { type RefObject, useEffect, useMemo, useRef } from "react";
+import { type AgentSession, type MessageReference, Reference } from "../../vendor/use-agentic";
+import type { ComposerHandle } from "./Composer";
+
+interface ChatReferencesSetup {
+  session: AgentSession;
+  draft: string;
+  version: number;
+  handleRef: RefObject<ComposerHandle | null>;
+  onDraft: (text: string) => void;
+}
+
+export const useChatReferences = ({ session, draft, version, handleRef, onDraft }: ChatReferencesSetup) => {
+  const caret = useRef<number | null>(null);
+  
+  useEffect(() => session.attachChat(), [session]);
+  useEffect(() => {
+    const pending = session.pendingInserts;
+    if (!pending.length) return;
+    const at = handleRef.current?.caret() ?? draft.length;
+    const head = draft.slice(0, at);
+    const tail = draft.slice(at);
+    const tokens = pending.map((one) => Reference.token(one)).join(" ");
+    
+    const lead = head && !/\s$/.test(head) ? " " : "";
+    onDraft(`${head}${lead}${tokens} ${tail}`);
+    caret.current = head.length + lead.length + tokens.length + 1;
+    for (const one of pending) session.insertApplied(Reference.keyOf(one));
+  }, [version]);
+  useEffect(() => {
+    const at = caret.current;
+    if (at === null) return;
+    caret.current = null;
+    
+    handleRef.current?.setCaret(at);
+  }, [draft]);
+  const references = useMemo<MessageReference[]>(() => {
+    const staged = new Map(session.staged.map((one) => [Reference.keyOf(one), one]));
+    return Reference.parse(draft).map(
+      (pointer) => staged.get(Reference.keyOf(pointer)) ?? { ...pointer, note: Reference.unstagedNote },
+    );
+  }, [draft, version]);
+  return {
+    references,
+    remove: (key: string) => {
+      onDraft(Reference.without(draft, key));
+      session.unstage(key);
+    },
+  };
+};

package/ui/Agent/useChatVoice.ts

@@ -6,20 +6,11 @@ import { type VoiceEngine, type VoiceListener, VoiceReader } from "./voice";
 interface ChatVoiceSetup {
   session: AgentSession;
   engine?: VoiceEngine;
-  /** The chat's own version snapshot — every transcript change re-runs the reading policy. */
   version: number;
   onTranscript: (text: string) => void;
   onFailed: () => void;
 }
 
-/**
- * The chat's speech policy, which is the framework's and not the engine's: one utterance per press, the
- * transcript landing in the composer to be corrected, barge-in on the next press or on Stop, and a reply read
- * aloud **only when the ask arrived by voice** — a typed question never turns the speakers on.
- *
- * A question or an approval the loop parked on is read too, and only in that same case: the loop stops there,
- * and a voice user staring at a card they were never told about is a conversation that simply ends.
- */
 export const useChatVoice = ({ session, engine, version, onTranscript, onFailed }: ChatVoiceSetup) => {
   const [listening, setListening] = useState(false);
   
@@ -28,11 +19,9 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
   const listener = useRef<VoiceListener | null>(null);
   const reader = useRef<VoiceReader | null>(null);
   reader.current ??= new VoiceReader(() => held.current);
-  /** Set while the draft came from the microphone, consumed by the send that carries it. */
   const byVoice = useRef(false);
-  /** The assistant message being read aloud, and where its turn began. Null means this turn is not one to read. */
+  
   const spoken = useRef<{ at: number; from: number } | null>(null);
-  /** The parked card already announced, so a question is not re-read on every transcript change. */
   const announced = useRef<string | null>(null);
   const heard = useRef(0);
   useEffect(() => {
@@ -56,7 +45,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
       (message, idx) => idx >= reading.from && message.role === "assistant" && !message.local && !!message.text,
     );
     if (at < 0) return;
-    
     if (at !== reading.at) {
       speaker.reset();
       reading.at = at;
@@ -75,7 +63,7 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
     },
     [],
   );
-  /** One press is one utterance, so the engine is told to stop even when it reported a final result itself. */
+  
   const endListening = () => {
     const running = listener.current;
     listener.current = null;
@@ -86,10 +74,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
     reader.current?.cancel();
     spoken.current = null;
   };
-  /**
-   * Whether the draft came from the microphone, cleared as it is read: the send consuming the draft takes it, and
-   * an ask parked behind a running turn carries it to the send that finally opens with it.
-   */
   const lift = () => {
     const was = byVoice.current;
     byVoice.current = false;
@@ -97,15 +81,12 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
   };
   return {
     listening,
-    /** A screen that cannot listen renders no microphone — the rule that publishes no tool for a missing control. */
     canListen: !!engine && (engine.available?.() ?? true),
     silence,
     lift,
-    /** Puts a lifted flag back, for a parked ask that returned to the composer instead of opening a turn. */
     hold: (spokenAsk: boolean) => {
       byVoice.current ||= spokenAsk;
     },
-    /** Called by the send that opens a turn: only an ask that arrived by voice is answered out loud. */
     take: (spokenAsk = lift()) => {
       
       spoken.current = spokenAsk ? { at: -1, from: session.messages.length } : null;
@@ -117,7 +98,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
       }
       const voiceEngine = held.current;
       if (!voiceEngine) return;
-      
       silence();
       listener.current = voiceEngine.listen({
         onInterim: onTranscript,
@@ -127,7 +107,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
           endListening();
         },
         onError: (message) => {
-          
           console.warn(`[akan] voice input failed: ${message}`);
           onFailed();
           endListening();