akanjs 3.0.0-beta.7 → 3.0.0-beta.8

package/ui/Agent/Chat.tsx

@@ -37,9 +37,11 @@ import type { BuiltinOption } from "./sessionView";
 import { tokenCount } from "./tokenCount";
 import { useChatAttachments } from "./useChatAttachments";
 import { type QueuedMessage, useChatQueue } from "./useChatQueue";
+import { useChatReferences } from "./useChatReferences";
 import { useChatVoice } from "./useChatVoice";
 import { useDraftRecall } from "./useDraftRecall";
 import { useKeyboardInset } from "./useKeyboardInset";
+import { type ReferenceSource, useReferenceMenu } from "./useReferenceMenu";
 import { useSlashMenu } from "./useSlashMenu";
 import type { VoiceEngine } from "./voice";
 
@@ -117,6 +119,15 @@ export interface ChatProps {
    * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
    */
   attach?: AttachReader;
+  /**
+   * What the composer's `@` menu can point at — one entry per kind of document a user may name while asking.
+   *
+   * Which documents those are is the app's answer, so the source carries its own `search`; the framework carries
+   * the token, the masking and the snapshot. Whole documents only: a field inside one is pointed at from the
+   * component that draws it, with `useAgentReference`, because that component is the thing that knows a rich-text
+   * field reads as a paragraph rather than as the editor document it is stored as.
+   */
+  reference?: readonly ReferenceSource[];
   /**
    * Raises or lowers what the composer accepts — per file, per message, and how many. The defaults are what one
    * turn's JSON safely carries to a conservative provider; an app pointed at a larger request limit, or one whose
@@ -176,6 +187,7 @@ export const DefaultChat = ({
   defaultDraft,
   attach,
   attachLimits,
+  reference,
   voice,
 }: ChatProps) => {
   const { l } = usePage();
@@ -225,6 +237,7 @@ export const DefaultChat = ({
   const listRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const launcherRef = useRef<HTMLButtonElement>(null);
+  const refs = useChatReferences({ session, draft, version, inputRef, onDraft: setDraft });
   
   const sticky = useRef(true);
   const returning = useRef(false);
@@ -274,6 +287,7 @@ export const DefaultChat = ({
   const write = (text: string) => {
     setDraft(text);
     menu.reopen();
+    mentions.reopen();
   };
 
   const closable = openProp === undefined || !!onOpenChange;
@@ -287,6 +301,7 @@ export const DefaultChat = ({
 
     if (command.name === "new") {
       files.clear();
+      session.clearStaged();
       queue.take();
     }
     void ChatCommands.run(command, { session, l });
@@ -299,10 +314,15 @@ export const DefaultChat = ({
     if (session.isRunning) return queue.push(message);
     sticky.current = true;
     speech.take(message.byVoice);
-    if (!message.attachments.length) void session.send(message.text);
+    if (!message.attachments.length && !message.references.length) void session.send(message.text);
     else
       void session.send([
-        { role: "user", ...(message.text ? { text: message.text } : {}), attachments: message.attachments },
+        {
+          role: "user",
+          ...(message.text ? { text: message.text } : {}),
+          ...(message.attachments.length ? { attachments: message.attachments } : {}),
+          ...(message.references.length ? { references: message.references } : {}),
+        },
       ]);
     return true;
   };
@@ -311,10 +331,15 @@ export const DefaultChat = ({
     const message = queue.queued;
     if (!message || !files.restore(message.attachments)) return;
     queue.take();
+    
+    session.restoreStaged(message.references);
     write([message.text, draft].filter(Boolean).join("\n"));
     speech.hold(message.byVoice);
   };
   const menu = useSlashMenu({ draft, l, onCommand: runCommand });
+  const mentions = useReferenceMenu({ draft, sources: reference ?? [], session, l, onWrite: write });
+
+  const list = menu.at() ? menu : mentions;
   const send = () => {
     const text = draft.trim();
     if (!text && !files.attached.length) return;
@@ -338,12 +363,13 @@ export const DefaultChat = ({
       return;
     }
     const byVoice = speech.lift();
-    if (!dispatch({ text, attachments: files.attached, byVoice })) {
+    if (!dispatch({ text, attachments: files.attached, references: refs.references, byVoice })) {
       speech.hold(byVoice);
       return;
     }
     write("");
     files.clear();
+    session.clearStaged();
     if (text) recall.remember(text);
   };
   const onKeyDown = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => {
@@ -352,22 +378,24 @@ export const DefaultChat = ({
     const onEdgeLine = (up: boolean) =>
       area.selectionStart === area.selectionEnd &&
       !(up ? area.value.slice(0, area.selectionStart) : area.value.slice(area.selectionEnd)).includes("\n");
-    const row = menu.at();
+    const row = list.at();
     if (row) {
       
       if (event.key === "ArrowDown" || event.key === "ArrowUp") {
         event.preventDefault();
-        menu.move(event.key === "ArrowDown" ? 1 : -1);
+        list.move(event.key === "ArrowDown" ? 1 : -1);
         return;
       }
       if (event.key === "Tab") {
         event.preventDefault();
-        write(`/${row.name} `);
+        
+        if (list === menu) write(`/${row.name} `);
+        else row.pick();
         return;
       }
       if (event.key === "Escape") {
         event.preventDefault();
-        menu.hide();
+        list.hide();
         return;
       }
       if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing) {
@@ -501,7 +529,7 @@ export const DefaultChat = ({
         <Question key={session.pendingQuestion.callId} question={session.pendingQuestion} />
       ) : null}
       {queue.queued ? <Queued message={queue.queued} onCancel={() => queue.take()} onEdit={unpark} /> : null}
-      <Menu onPick={(row) => row.pick()} rows={menu.rows} selected={menu.selected} />
+      <Menu onPick={(row) => row.pick()} prefix={list === menu ? "/" : "@"} rows={list.rows} selected={list.selected} />
       <Composer
         attached={files.attached}
         pending={files.pending}
@@ -512,7 +540,9 @@ export const DefaultChat = ({
         onFiles={(picked) => void files.add(picked)}
         onKeyDown={onKeyDown}
         onRemoveFile={files.remove}
+        onRemoveReference={refs.remove}
         onSend={send}
+        references={refs.references}
         onStop={() => {
           speech.silence();
           

package/ui/Agent/Composer.tsx

@@ -1,18 +1,24 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
 import { type KeyboardEvent, type RefObject, useEffect } from "react";
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic";
+import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic";
 import { Button } from "../Button";
 import { inputRecipe } from "../recipe";
 import { createOverridable, useUiRecipe } from "../UiOverride";
 import { Attach, Chips } from "./Attach";
 import { Mic } from "./Mic";
+import { ReferenceChips } from "./Refer";
 
 export interface ComposerProps {
   className?: string;
   session: AgentSession;
   draft: string;
   attached: readonly MessageAttachment[];
+  /**
+   * What the draft's `@[…](mention:…)` tokens point at. The text is what carries them, so a composer that draws no
+   * chip still sends them — the chip is how somebody sees and removes one, not how it travels.
+   */
+  references?: readonly MessageReference[];
   /** Files still being read. An `attach` that uploads takes seconds, and a panel that shows nothing looks broken. */
   pending?: number;
   /** Absent when the screen cannot listen — the same rule as publishing no tool for a control that is not drawn. */
@@ -21,6 +27,8 @@ export interface ComposerProps {
   onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
   onFiles: (files: File[]) => void;
   onRemoveFile: (idx: number) => void;
+  /** Keyed on `refName/refId#path`, not on a row index: the order is the draft's, and the draft is the truth. */
+  onRemoveReference?: (key: string) => void;
   onSend: () => void;
   onStop: () => void;
   inputRef?: RefObject<HTMLTextAreaElement | null>;
@@ -35,12 +43,14 @@ export const DefaultComposer = ({
   session,
   draft,
   attached,
+  references = [],
   pending = 0,
   mic,
   onDraft,
   onKeyDown,
   onFiles,
   onRemoveFile,
+  onRemoveReference,
   onSend,
   onStop,
   inputRef,
@@ -56,6 +66,13 @@ export const DefaultComposer = ({
   }, [draft, inputRef]);
   return (
     <div className={cn("flex flex-col gap-2 border-foreground/5 border-t p-3", className)}>
+      {references.length ? (
+        <ReferenceChips
+          onRemove={onRemoveReference}
+          references={references}
+          removeLabel={l("base.agentReferenceRemove")}
+        />
+      ) : null}
       {attached.length || pending ? (
         <Chips
           attachments={attached}

package/ui/Agent/Menu.tsx

@@ -15,11 +15,13 @@ export interface MenuProps {
   rows: MenuRow[];
   /** Index the arrows are on. Enter picks it and Tab completes its name, so it has to be visible. */
   selected: number;
+  /** What the rows are being typed after, so a name reads as the thing the user is completing. */
+  prefix?: string;
   onPick: (row: MenuRow) => void;
 }
 
-/** The `/` menu: this chat's own commands first, then the app's `prompt()` endpoints. */
-export const DefaultAgentMenu = ({ className, rows, selected, onPick }: MenuProps) => {
+/** The composer's completion list: `/` commands and `prompt()` endpoints, or the `@` menu's reference rows. */
+export const DefaultAgentMenu = ({ className, rows, selected, prefix = "/", onPick }: MenuProps) => {
   if (!rows.length) return null;
   return (
     <div
@@ -41,7 +43,10 @@ export const DefaultAgentMenu = ({ className, rows, selected, onPick }: MenuProp
           role="option"
           type="button"
         >
-          <span className="shrink-0 font-mono text-xs">/{row.name}</span>
+          <span className="shrink-0 font-mono text-xs">
+            {prefix}
+            {row.name}
+          </span>
           {row.hint ? <span className="shrink-0 font-mono text-[10px] text-foreground/40">{row.hint}</span> : null}
           {row.description ? (
             <span className="ml-auto truncate text-[10px] text-foreground/50">{row.description}</span>

package/ui/Agent/Queued.tsx

@@ -3,6 +3,7 @@ import { cn, usePage } from "akanjs/client";
 import { AiOutlineClose, AiOutlineEdit } from "react-icons/ai";
 import { createOverridable } from "../UiOverride";
 import { Chips } from "./Attach";
+import { ReferenceChips } from "./Refer";
 import type { QueuedMessage } from "./useChatQueue";
 
 export interface QueuedProps {
@@ -29,6 +30,7 @@ export const DefaultQueued = ({ className, message, onEdit, onCancel }: QueuedPr
       <div className="flex min-w-0 flex-1 flex-col gap-1">
         <span className="text-[10px] text-foreground/40">{l("base.agentQueued")}</span>
         {message.attachments.length ? <Chips attachments={message.attachments} /> : null}
+        {message.references.length ? <ReferenceChips references={message.references} /> : null}
         {message.text ? (
           <p className="line-clamp-2 whitespace-pre-wrap text-foreground/70 text-sm">{message.text}</p>
         ) : null}

package/ui/Agent/Refer.tsx

@@ -0,0 +1,44 @@
+"use client";
+import { cn } from "akanjs/client";
+import { AiOutlineClose } from "react-icons/ai";
+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) => {
+      const key = Reference.keyOf(reference);
+      return (
+        <span
+          className="flex items-center gap-1 rounded-field bg-primary/10 px-2 py-0.5 text-primary text-xs"
+          key={key}
+          title={key}
+        >
+          <span className="max-w-32 truncate">{reference.label || key}</span>
+          {onRemove ? (
+            <button
+              aria-label={removeLabel}
+              className="text-primary/50 hover:text-primary"
+              onClick={() => onRemove(key)}
+              type="button"
+            >
+              <AiOutlineClose />
+            </button>
+          ) : null}
+        </span>
+      );
+    })}
+  </div>
+);

package/ui/Agent/sessionHistory.ts

@@ -11,19 +11,42 @@ export type PersistOption = boolean | { storage?: "session" | "local"; key?: str
  * letting it answer from the filename. A `ref` stays for the same reason and matters more: it is the host's own
  * handle on the file, so dropping it leaves a restored conversation with nothing but a name and size to guess
  * from — the guess `ref` exists to retire.
+ *
+ * A reference's `value` goes the same way and for the same reason — it is capped at 20,000 characters each, and a
+ * transcript of 50 messages would not fit beside it. What is left behind is better than what an attachment leaves,
+ * though, and the note says so rather than leaving the model to notice: `refName`/`refId`/`path` is a live pointer,
+ * so the answer to a restored reference is to read it again with a tool, not to guess from the label.
  */
-const withoutContent = (message: ChatMessage): ChatMessage =>
-  message.attachments?.length
-    ? {
-        ...message,
-        attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
-          name,
-          mimeType,
-          ...(url ? { url } : {}),
-          ...(ref ? { ref } : {}),
-        })),
-      }
-    : message;
+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,
+          })),
+        }
+      : {}),
+  };
+};
 
 /**
  * Maps the `persist` prop onto a `SessionHistory` over web storage. Session storage is the default on purpose:

package/ui/Agent/useChatQueue.ts

@@ -1,12 +1,15 @@
 "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[];
+  /** What the parked text's tokens pointed at. Carried so a turn that opens later still knows what they held. */
+  references: MessageReference[];
   /** The ask came from the microphone, so the reply it gets is read aloud — carried until the send that opens it. */
   byVoice: boolean;
 }
@@ -56,6 +59,13 @@ 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;

package/ui/Agent/useChatReferences.ts

@@ -0,0 +1,67 @@
+"use client";
+import { type RefObject, useEffect, useMemo, useRef } from "react";
+import { type AgentSession, type MessageReference, Reference } from "../../vendor/use-agentic";
+
+interface ChatReferencesSetup {
+  session: AgentSession;
+  draft: string;
+  /** The chat's own version snapshot — a `refer` from anywhere on the page is one of the changes it counts. */
+  version: number;
+  inputRef: RefObject<HTMLTextAreaElement | null>;
+  onDraft: (text: string) => void;
+}
+
+/**
+ * The composer's half of a reference: writing the token for one somebody pointed at elsewhere, and reading back
+ * which references the draft now carries.
+ *
+ * **The text is the source of truth, and the staged values are looked up beside it.** A reference is on the
+ * message because its token is in the message — so deleting the token by hand drops it, exactly as deleting the
+ * chip does, and neither can leave the other behind. The draft is never scanned to re-derive a value; a token
+ * whose value was never staged (pasted out of an earlier message) travels as a pointer with a note saying to read
+ * it again, which is the same shape a restored conversation produces.
+ */
+export const useChatReferences = ({ session, draft, version, inputRef, onDraft }: ChatReferencesSetup) => {
+  const caret = useRef<number | null>(null);
+
+  useEffect(() => session.attachChat(), [session]);
+  useEffect(() => {
+    const pending = session.pendingInserts;
+    if (!pending.length) return;
+    const area = inputRef.current;
+
+    const at = area ? area.selectionStart : 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;
+    const area = inputRef.current;
+    if (!area) return;
+    
+    area.focus();
+    area.setSelectionRange(at, 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,
+    /** Removing the chip removes the token, because the token is what puts the reference on the message. */
+    remove: (key: string) => {
+      onDraft(Reference.without(draft, key));
+      session.unstage(key);
+    },
+  };
+};

package/ui/Agent/useReferenceMenu.ts

@@ -0,0 +1,108 @@
+"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";
+
+/** One row the `@` menu offers: a document of its source's model, named the way the screen names it. */
+export interface ReferenceCandidate {
+  refId: string;
+  label: string;
+  description?: string;
+}
+
+/**
+ * A kind of document the `@` menu can point at.
+ *
+ * `type` is the whole decision about what leaves the browser, in `st.expose`'s vocabulary — a model class masks by
+ * that model. **Name the class that actually carries the fields somebody is pointing at**: a `Light<Model>` is
+ * usually not it, and a reference masked by one arrives without the field that was the reason for pointing.
+ *
+ * `search` is the app's own query, because which documents a person may point at is the app's answer and not the
+ * framework's; the signal is aborted when the query moves on. `resolve` is called once, when a row is picked.
+ */
+export interface ReferenceSource<T extends AgentFieldType = AgentFieldType> {
+  refName: string;
+  /** What this group of rows is called in the menu. */
+  label: string;
+  type: T;
+  search: (query: string, signal: AbortSignal) => Promise<ReferenceCandidate[]>;
+  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;
+}
+
+/**
+ * Only a word being typed at the end of the draft opens the menu. A `@` mid-sentence is left alone because the
+ * draft is the only thing this can read — a textarea's caret is not in React state — and a completed token always
+ * ends in a space, so the menu never reopens onto one it just wrote.
+ */
+const atQuery = /(^|\s)@([^\s@[\]()]*)$/;
+
+/** Long enough that typing a name is one query rather than one per letter, short enough to feel like a menu. */
+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]),
+  };
+};