akanjs 3.0.0-beta.2 → 3.0.0-beta.20

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();

package/ui/Agent/useDraftRecall.ts

@@ -2,19 +2,11 @@
 import { useRef, useState } from "react";
 import type { ChatMessage } from "../../vendor/use-agentic";
 
-/** What a restored transcript can still offer the arrows: the asks themselves, newest last. */
 const asked = (messages: readonly ChatMessage[], cap: number) =>
   messages
     .flatMap((message) => (message.role === "user" && !message.summary && message.text ? [message.text] : []))
     .slice(-cap);
 
-/**
- * ↑ walks back through what was sent, ↓ forward, and 0 is the draft it was walked away from. A single-line input
- * does nothing of its own with the vertical arrows, so recall is free to take them.
- *
- * Seeded from the transcript rather than starting empty, because a persisted chat restores the conversation and
- * losing only "what I just typed" across a reload is the one gap a user notices.
- */
 export const useDraftRecall = (messages: readonly ChatMessage[]) => {
   const cap = 30;
   const sent = useRef<string[] | null>(null);
@@ -29,7 +21,6 @@ export const useDraftRecall = (messages: readonly ChatMessage[]) => {
       if (history[history.length - 1] !== text) sent.current = [...history, text].slice(-cap);
       setAt(0);
     },
-    /** Answers the draft to show, or null when the walk cannot go that way. */
     step: (delta: number, draft: string): string | null => {
       const history = sent.current ?? [];
       const next = Math.max(0, Math.min(at + delta, history.length));

package/ui/Agent/useKeyboardInset.ts

@@ -1,13 +1,6 @@
 "use client";
 import { useEffect, useState } from "react";
 
-/**
- * How much of the layout viewport the on-screen keyboard is covering.
- *
- * `visualViewport` is the only thing that reports it — `dvh` tracks the browser's own chrome and not the
- * keyboard — and a full-screen chat whose composer sits under the keyboard is one nobody can type into. Answers
- * 0 wherever the API is absent, which is every desktop case and the server.
- */
 export const useKeyboardInset = () => {
   const [inset, setInset] = useState(0);
   useEffect(() => {

package/ui/Agent/useReferenceMenu.ts

@@ -0,0 +1,93 @@
+"use client";
+import { type AgentFieldType, AgentValue } from "akanjs/store";
+import { useEffect, useRef, useState } from "react";
+import { type AgentSession, Reference } from "../../vendor/use-agentic";
+import type { MenuRow } from "./Menu";
+
+export interface ReferenceCandidate {
+  refId: string;
+  label: string;
+  description?: string;
+}
+
+export interface ReferenceSource<T extends AgentFieldType = AgentFieldType> {
+  refName: string;
+  /** What this group of rows is called in the menu. */
+  label: string;
+  /** Masks what leaves the browser: name the class carrying the pointed-at fields, which a `Light<Model>` rarely is. */
+  type: T;
+  /** The signal aborts when the query moves on. */
+  search: (query: string, signal: AbortSignal) => Promise<ReferenceCandidate[]>;
+  /** Called once, when a row is picked. */
+  resolve: (refId: string) => Promise<unknown>;
+}
+
+interface ReferenceMenuSetup {
+  draft: string;
+  sources: readonly ReferenceSource[];
+  session: AgentSession;
+  l: (key: string, param?: Record<string, string | number>) => string;
+  onWrite: (text: string) => void;
+}
+
+const atQuery = /(^|\s)@([^\s@[\]()]*)$/;
+
+const searchDelay = 150;
+
+export const useReferenceMenu = ({ draft, sources, session, l, onWrite }: ReferenceMenuSetup) => {
+  const [rows, setRows] = useState<MenuRow[]>([]);
+  const [cursor, setCursor] = useState(0);
+  const [hidden, setHidden] = useState(false);
+  
+  const held = useRef(sources);
+  held.current = sources;
+  const match = hidden ? null : atQuery.exec(draft);
+
+  const query = match ? match[2] : null;
+  const write = (candidate: ReferenceCandidate, source: ReferenceSource) => {
+    const reference = { refName: source.refName, refId: candidate.refId, label: candidate.label };
+    onWrite(`${draft.slice(0, match?.index ?? 0)}${match?.[1] ?? ""}${Reference.token(reference)} `);
+    void source
+      .resolve(candidate.refId)
+      .then((value) => session.stage({ ...reference, value: AgentValue.serialize(source.type, value) }))
+      .catch(() => session.note(l("base.agentReferenceFailed", { label: candidate.label })));
+  };
+  useEffect(() => {
+    if (query === null || !held.current.length) {
+      setRows([]);
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      const current = held.current;
+      void Promise.all(
+        current.map((source) => source.search(query, controller.signal).catch(() => [] as ReferenceCandidate[])),
+      ).then((found) => {
+        if (controller.signal.aborted) return;
+        setCursor(0);
+        setRows(
+          found.flatMap((candidates, at) =>
+            candidates.map((candidate) => ({
+              name: candidate.label,
+              description: candidate.description ?? current[at].label,
+              pick: () => write(candidate, current[at]),
+            })),
+          ),
+        );
+      });
+    }, searchDelay);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [query, draft]);
+  const selected = Math.min(cursor, Math.max(rows.length - 1, 0));
+  return {
+    rows: query === null ? [] : rows,
+    selected,
+    reopen: () => setHidden(false),
+    hide: () => setHidden(true),
+    move: (delta: number) => setCursor(Math.max(0, Math.min(selected + delta, rows.length - 1))),
+    at: () => (query === null ? undefined : rows[selected]),
+  };
+};

package/ui/Agent/useSlashMenu.ts

@@ -9,10 +9,8 @@ interface SlashMenuSetup {
   onCommand: (command: ChatCommand) => void;
 }
 
-/** Only a bare `/name` opens the menu: once an argument is being typed, the list has nothing left to offer. */
 const slashQuery = /^\/[A-Za-z0-9_-]*$/;
 
-/** The `/` menu's rows — this chat's own commands — and which one the keys are on. */
 export const useSlashMenu = ({ draft, l, onCommand }: SlashMenuSetup) => {
   const [cursor, setCursor] = useState(0);
   const [hidden, setHidden] = useState(false);
@@ -30,7 +28,6 @@ export const useSlashMenu = ({ draft, l, onCommand }: SlashMenuSetup) => {
   return {
     rows,
     selected,
-    /** Reset when the draft is written to: a new query has a new first row, and Escape only hides the old one. */
     reopen: () => {
       setHidden(false);
       setCursor(0);