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

package/ui/Agent/Chat.tsx

@@ -1,6 +1,6 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
-import { AgentPrompts } from "akanjs/store";
+import { AgentPrompts, type AgentVisualOption } from "akanjs/store";
 import {
   type KeyboardEvent as ReactKeyboardEvent,
   type ReactNode,
@@ -17,111 +17,87 @@ import {
   type AgentRunner,
   type AgentSession,
   type AgentSessionOptions,
+  type ChatMessage,
   type CompactOptions,
   SessionContext,
   type SessionHistory,
 } from "../../vendor/use-agentic";
 import { createOverridable } from "../UiOverride";
 import Approval from "./Approval";
-import { agentSessionOf } from "./agentSessionOf";
+import { agentSessionOf, type BuiltinOption, type PersistOption } from "./agentSessionOf";
 import type { AttachLimits, AttachReader } from "./attachment";
 import Bubble from "./Bubble";
 import { type ChatCommand, ChatCommands } from "./ChatCommands";
-import { Composer } from "./Composer";
+import { Composer, type ComposerHandle } from "./Composer";
 import { Launcher } from "./Launcher";
 import Menu from "./Menu";
 import Question from "./Question";
 import Queued from "./Queued";
-import type { PersistOption } from "./sessionHistory";
-import type { BuiltinOption } from "./sessionView";
+import Steps from "./Steps";
+import ToolCard from "./ToolCard";
 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";
 
 export interface ChatProps {
-  /** Reaches whichever surface is showing — the launcher while closed, the panel while open. */
+  /** Applied to the launcher while closed and to the panel while open. */
   className?: string;
   title?: string;
-  /** App-global framing. Route-scoped guidance layers on it through mounted `Agent.Guide`s. */
+  /** App-global framing; route-scoped `Agent.Guide`s layer on it. */
   instructions?: string;
-  /** Swap the transport; the default drives the app's `runAgentTurn` endpoint. */
+  /** Defaults to the app's `runAgentTurn` endpoint. */
   runner?: AgentRunner;
   maxTurns?: number;
-  /**
-   * When the conversation summarizes itself to stay inside the model's window — `at` estimated tokens, `keep`
-   * messages left verbatim below the summary. Tune it per provider; `{ at: 0 }` turns it off.
-   */
+  /** Summarizes past `at` estimated tokens or near the server's context window, keeping `keep` messages verbatim;
+   *  `{ at: Infinity }` leaves only the window guard, `{ at: 0 }` turns it all off. */
   compact?: CompactOptions;
-  /**
-   * Which of the runtime's own tools this chat's agent gets — all of them by default, `false` none, an array
-   * exactly the ones it names. A chat that must not leave the screen it is on drops `navigate` and `goBack`.
-   */
+  /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
   builtins?: BuiltinOption;
-  /** 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"];
   defaultOpen?: boolean;
-  /**
-   * Controlled open state. Pass it with `onOpenChange` to drive the panel from the app's own control — a header
-   * button, a menu item — instead of the built-in launcher. Left off, the panel owns the state as before.
-   */
+  /** Controlled open state, paired with `onOpenChange`; left off, the panel owns it. */
   open?: boolean;
-  /**
-   * Left off while `open` is controlled, the panel cannot close itself — so it draws **no close button** rather
-   * than an inert one. That is the shape of a fixed panel with nowhere to close to, and it is also what keeps a
-   * controlled chat assemblable by a server component, since this is the only prop here that is a function.
-   */
+  /** Left off while `open` is controlled, the panel draws no close button. */
   onOpenChange?: (open: boolean) => void;
-  /** `false` draws no launcher, for an app that opens the panel from a control of its own. */
+  /** On by default; `false` draws nothing, `{ cursor: false }` / `{ reveal: false }` turn one effect off. */
+  visual?: boolean | AgentVisualOption;
+  /** `false` draws no launcher. */
   launcher?: boolean;
-  /**
-   * Keeps the transcript across reloads — sessionStorage by default, `{ storage: "local" }` to outlive the tab, or
-   * a `SessionHistory` of the app's own to keep it anywhere else, a server included.
-   *
-   * Ignored, like every session option above it, when an enclosing `Agent.Zone` or `AgentProvider` already holds a
-   * session: this chat then binds to that one, and the options belong to whoever built it.
-   */
+  /** sessionStorage by default, `{ storage: "local" }` to outlive the tab, or an app `SessionHistory`. Ignored, like
+   *  every session option above, when an enclosing `Agent.Zone` or `AgentProvider` already holds a session. */
   persist?: PersistOption | SessionHistory;
-  /** Renders in the page flow instead of floating above it — a zone chat that lives inside its own section. */
+  /** Renders in the page flow instead of floating above it. */
   inline?: boolean;
-  /** `false` gives the browser its own Cmd/Ctrl+L back, for an app whose shell already spends that chord. */
+  /** `false` leaves Cmd/Ctrl+L to the browser. */
   shortcut?: boolean;
-  /** One surface each, where `className` reaches both. */
   launcherClassName?: string;
   panelClassName?: string;
-  /** Shown in place of the intro line while the transcript is empty — where starter questions go. */
+  /** Shown in place of the intro line while the transcript is empty. */
   intro?: ReactNode;
   /** Extra header controls, left of the built-in clear and close buttons. */
   header?: ReactNode;
-  /**
-   * `false` draws no header bar at all — for an `inline` chat inside a panel the app already titles. The extra
-   * `header` controls go with it, and the clear action stays reachable as the `/new` command.
-   */
+  /** `false` draws no header bar, `header` included; clearing stays reachable as `/new`. */
   chrome?: boolean;
-  /** The composer's opening text, read once at mount — where a `?prompt=` lands without sending it. */
+  /** The composer's opening text, read once at mount. */
   defaultDraft?: string;
-  /**
-   * Reads a file the user attached into an attachment, or answers `null` to leave it to the built-in reader
-   * (images as bytes, text as text). This is where an app puts what needs a parser — a PDF's text, a spreadsheet's
-   * cells — since the framework carries attachments but depends on nothing that can extract one. It runs before
-   * the built-in, so it can also replace how an image is prepared.
-   */
+  /** Runs before the built-in reader, which `null` falls back to. The provider fetches a `url` itself, so answer
+   *  `data` too when it cannot reach it — `data` is then what is sent and `url` only draws the chip. */
   attach?: AttachReader;
-  /**
-   * 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
-   * `attach` uploads and answers a `url`, has no reason to inherit them.
-   */
+  /** What the composer's `@` menu can point at, one entry per document kind. */
+  reference?: readonly ReferenceSource[];
+  /** Draws `@` pointers as names; on when `reference` is set, `false` keeps the plain textarea. */
+  mentions?: boolean;
+  /** Overrides the per-file, per-message and count ceilings on attachments. */
   attachLimits?: AttachLimits;
-  /**
-   * Speech in and out. The engine listens and speaks; this component decides when — a press-to-talk microphone
-   * whose transcript lands in the composer for the user to correct, and a reply read aloud **only when the ask
-   * itself came in by voice**, so a typed question never turns the speakers on.
-   */
+  /** Speech in and out; a reply is read aloud only when the ask came in by voice. */
   voice?: VoiceEngine;
 }
 
@@ -136,16 +112,8 @@ const panelLayer = "fixed inset-0 z-[150] sm:inset-auto sm:right-4 sm:bottom-4";
 const panelSize =
   "h-dvh w-screen rounded-none sm:h-[min(600px,calc(100dvh-2rem))] sm:w-[min(24rem,calc(100vw-2rem))] sm:rounded-box";
 
-/** Distance from the bottom within which the transcript keeps following new messages. */
 const stickyEdge = 80;
 
-/**
- * The user-facing half of the in-page agent: one floating chat wired to the same surface the dock inspects.
- * The conversation loop runs in this browser session — every tool call executes here, gated by the approval
- * card — and the session lives in a ref, so it survives reopening the panel and dies with the page unless
- * `persist` keeps it. An enclosing AgentProvider's session wins, which is how an app isolates a surface or swaps
- * the loop while keeping this UI.
- */
 export const DefaultChat = ({
   className,
   title,
@@ -159,6 +127,7 @@ export const DefaultChat = ({
   open: openProp,
   onOpenChange,
   launcher = true,
+  visual = true,
   persist,
   inline = false,
   shortcut = true,
@@ -170,6 +139,8 @@ export const DefaultChat = ({
   defaultDraft,
   attach,
   attachLimits,
+  reference,
+  mentions,
   voice,
 }: ChatProps) => {
   const { l } = usePage();
@@ -189,6 +160,7 @@ export const DefaultChat = ({
       builtins,
       persist,
       onCompact,
+      visual,
     });
   const session = held.current;
   const version = useSyncExternalStore(
@@ -197,7 +169,6 @@ export const DefaultChat = ({
     () => session.version,
   );
   const [ownOpen, setOwnOpen] = useState(defaultOpen);
-
   const open = openProp ?? ownOpen;
   const setOpen = (next: boolean) => {
     if (openProp === undefined) setOwnOpen(next);
@@ -219,7 +190,13 @@ export const DefaultChat = ({
   const listRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const launcherRef = useRef<HTMLButtonElement>(null);
+  const handleRef = useRef<ComposerHandle | null>(null);
   
+  const focusComposer = () => {
+    if (handleRef.current) handleRef.current.focus();
+    else inputRef.current?.focus();
+  };
+  const refs = useChatReferences({ session, draft, version, handleRef, onDraft: setDraft });
   const sticky = useRef(true);
   const returning = useRef(false);
   const read = useRef(session.messages.length);
@@ -243,7 +220,7 @@ export const DefaultChat = ({
       event.preventDefault();
       sticky.current = true;
       setOpen(true);
-      inputRef.current?.focus();
+      focusComposer();
     };
     
     window.addEventListener("keydown", onKeyDown, true);
@@ -251,16 +228,15 @@ export const DefaultChat = ({
   }, [shortcut]);
   useEffect(() => {
     if (!open) {
-      
       if (returning.current) launcherRef.current?.focus();
       returning.current = false;
       return;
     }
-    inputRef.current?.focus();
+    focusComposer();
   }, [open, session.pendingQuestion?.callId]);
   useEffect(
     () => () => {
-
+      
       if (!provided) session.abort();
     },
     [],
@@ -268,8 +244,8 @@ export const DefaultChat = ({
   const write = (text: string) => {
     setDraft(text);
     menu.reopen();
+    mentionMenu.reopen();
   };
-
   const closable = openProp === undefined || !!onOpenChange;
   const dismiss = () => {
     returning.current = true;
@@ -278,48 +254,52 @@ export const DefaultChat = ({
   const runCommand = (command: ChatCommand) => {
     write("");
     recall.remember(`/${command.name}`);
-
+    
     if (command.name === "new") {
       files.clear();
+      session.clearStaged();
       queue.take();
     }
     void ChatCommands.run(command, { session, l });
   };
-  /**
-   * Opens a turn with what the composer held, or parks it behind the turn that is running so it opens the next.
-   * False only when parking refused it — the files would not fit beside what is already waiting.
-   */
   const dispatch = (message: QueuedMessage): boolean => {
     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;
   };
-  /** Hands the parked message back to the composer, ahead of whatever was typed since it was parked. */
   const unpark = () => {
     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 mentionMenu = useReferenceMenu({ draft, sources: reference ?? [], session, l, onWrite: write });
+  
+  const list = menu.at() ? menu : mentionMenu;
   const send = () => {
     const text = draft.trim();
     if (!text && !files.attached.length) return;
     const command = AgentPrompts.parseCommand(text);
     const builtin = command ? ChatCommands.find(command.name, l) : null;
-
+    
     if (builtin) {
       runCommand(builtin);
       return;
     }
-
     const question = session.pendingQuestion;
     if (question) {
       if (!text) {
@@ -332,36 +312,36 @@ 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>) => {
     const area = event.currentTarget;
-
     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) {
@@ -390,15 +370,36 @@ export const DefaultChat = ({
   const bubbles = useMemo(() => {
     const resultOf = new Map(session.messages.flatMap((message) => message.toolResults ?? []).map((r) => [r.id, r]));
     const claimed = new Set(session.messages.flatMap((message) => message.toolCalls?.map((call) => call.id) ?? []));
-    return session.messages.flatMap((message, idx) => {
-      if (message.role !== "tool")
-        return [<Bubble key={idx} message={message} progress={session.progress} results={resultOf} />];
-      const orphans = (message.toolResults ?? []).filter((result) => !claimed.has(result.id));
-      return orphans.length ? [<Bubble key={idx} message={{ ...message, toolResults: orphans }} />] : [];
+    const blocks: ({ at: number; user: ChatMessage } | { at: number; turn: ChatMessage[] })[] = [];
+    session.messages.forEach((message, idx) => {
+      if (message.role === "user") {
+        blocks.push({ at: idx, user: message });
+        return;
+      }
+      const orphans = message.role === "tool" ? (message.toolResults ?? []).filter((r) => !claimed.has(r.id)) : null;
+      if (orphans && !orphans.length) return;
+      const shown = orphans ? { ...message, toolResults: orphans } : message;
+      const open = blocks.at(-1);
+      if (open && "turn" in open) open.turn.push(shown);
+      else blocks.push({ at: idx, turn: [shown] });
     });
+    const last = blocks.at(-1);
+    return blocks.map((block) =>
+      "user" in block ? (
+        <Bubble key={block.at} message={block.user} progress={session.progress} results={resultOf} />
+      ) : (
+        <Steps
+          isRunning={session.isRunning && block === last}
+          key={block.at}
+          messages={block.turn}
+          progress={session.progress}
+          results={resultOf}
+        />
+      ),
+    );
   }, [version]);
-
-  const tokens = useMemo(() => session.tokens, [version]);
+  
+  const context = useMemo(() => session.context, [version]);
   const unread = open ? 0 : Math.max(0, session.messages.length - read.current);
   const layer = (surface: ReactNode) => (inline ? surface : overlay ? createPortal(surface, overlay) : null);
   if (!open)
@@ -435,9 +436,16 @@ export const DefaultChat = ({
         <header className="flex items-center gap-2 border-foreground/5 border-b px-4 py-3">
           <span className="font-semibold text-sm">{title ?? l("base.agent")}</span>
           {session.isRunning ? <span className="size-2 animate-pulse rounded-full bg-primary" /> : null}
-          {tokens ? (
-            <span className="shrink-0 whitespace-nowrap text-[10px] text-foreground/40">
-              {l("base.agentTokens", { count: tokenCount(tokens) })}
+          {context.used ? (
+            <span
+              className="shrink-0 whitespace-nowrap text-[10px] text-foreground/40"
+              title={
+                context.compactAt ? l("base.agentCompactsAt", { limit: tokenCount(context.compactAt) }) : undefined
+              }
+            >
+              {context.compactAt
+                ? l("base.agentTokensOf", { count: tokenCount(context.used), limit: tokenCount(context.compactAt) })
+                : l("base.agentTokens", { count: tokenCount(context.used) })}
             </span>
           ) : null}
           <span className="ml-auto flex items-center gap-2">
@@ -491,25 +499,29 @@ export const DefaultChat = ({
         ) : null}
       </div>
       {session.pendingApproval ? <Approval approval={session.pendingApproval} /> : null}
+      {session.pendingCard ? <ToolCard card={session.pendingCard} key={session.pendingCard.callId} /> : null}
       {session.pendingQuestion ? (
         <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}
         draft={draft}
+        handleRef={handleRef}
         inputRef={inputRef}
+        mentions={mentions ?? !!reference?.length}
         {...(speech.canListen ? { mic: { listening: speech.listening, onToggle: speech.toggle } } : {})}
         onDraft={write}
         onFiles={(picked) => void files.add(picked)}
         onKeyDown={onKeyDown}
         onRemoveFile={files.remove}
+        onRemoveReference={refs.remove}
         onSend={send}
+        references={refs.references}
         onStop={() => {
           speech.silence();
-          
           unpark();
           session.abort();
         }}

package/ui/Agent/ChatCommands.ts

@@ -7,19 +7,13 @@ export interface ChatCommandContext {
 
 export interface ChatCommand {
   name: string;
-  /** Accepted but not listed: one row per command, so the menu names each thing once. */
+  /** Accepted but not listed in the menu. */
   aliases?: string[];
   description: string;
   run: (context: ChatCommandContext) => void | Promise<void>;
 }
 
-/**
- * The chat's own slash commands — the whole `/` menu, since an app's prompts are `page().prompt()` declarations
- * served over MCP and not listed by a browser chat.
- *
- * Output goes through `session.note`, never `send`: a command is answered by this browser, so its text belongs in
- * the transcript the user reads and nowhere in the history the model reads.
- */
+/** Output goes through `session.note`, never `send`: the user reads it, the model never does. */
 export class ChatCommands {
   static list(l: (key: string) => string): ChatCommand[] {
     return [
@@ -35,7 +29,6 @@ export class ChatCommands {
         name: "retry",
         description: l("base.agentCmdRetry"),
         run: async ({ session, l: t }) => {
-          
           if (session.isRunning) session.note(t("base.agentBusy"));
           else if (!(await session.retry())) session.note(t("base.agentNothingToRetry"));
         },
@@ -59,7 +52,7 @@ export class ChatCommands {
     return ChatCommands.list(l).find((command) => command.name === name || command.aliases?.includes(name)) ?? null;
   }
 
-  /** A command is user-typed, so a failure inside one lands in the transcript instead of at the page. */
+  /** A failure is reported into the transcript instead of thrown. */
   static async run(command: ChatCommand, context: ChatCommandContext) {
     try {
       await command.run(context);
@@ -68,16 +61,12 @@ export class ChatCommands {
     }
   }
 
-  /**
-   * The conversation as markdown. The relay is stateless and the transcript lives only in this browser, so an
-   * export is the only way a wrong answer can reach whoever could fix it — which is why the header carries where
-   * and when it happened. Local notes are left out: they are this chat talking to itself.
-   */
+  /** The conversation as markdown, local notes left out. */
   static transcriptOf(messages: readonly ChatMessage[], where = ""): string {
     const lines = [`# Agent conversation`, [where, new Date().toISOString()].filter(Boolean).join(" · "), ""];
     for (const message of messages) {
       if (message.local) continue;
-
+      
       lines.push(`**${message.summary ? "summary" : message.role}**`);
       if (message.text) lines.push(message.text);
       for (const attachment of message.attachments ?? [])
@@ -109,10 +98,6 @@ export class ChatCommands {
     session.note([l("base.agentHelpIntro"), ...rows, "", l("base.agentHelpNote")].join("\n"));
   }
 
-  /**
-   * What this screen published, read off the session's own surface — a zone chat therefore lists its zone's view.
-   * `askUser` is the session's rather than the surface's, so it is added here the same way the turn adds it.
-   */
   static #tools({ session, l }: ChatCommandContext) {
     const { tools, resources } = session.surface.snapshot();
     const published = tools.some((tool) => tool.name === AgentSession.askUserTool.name)
@@ -131,7 +116,6 @@ export class ChatCommands {
     );
   }
 
-  /** A tool description is written for a model and runs long; the menu row wants its first sentence. */
   static #sentence(text: string) {
     const first = text.split(/(?<=[.!?])\s/)[0].trim();
     return first.length > 120 ? `${first.slice(0, 117)}...` : first;