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

package/ui/Agent/Composer.tsx

@@ -1,61 +1,113 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
+import { lazy } from "akanjs/webkit";
 import { type KeyboardEvent, type RefObject, useEffect } from "react";
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic";
+import { AiOutlineAudio, AiOutlineAudioMuted } from "react-icons/ai";
+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";
+
+/** Every offset is into the draft string, tokens included. */
+export interface ComposerHandle {
+  focus: () => void;
+  caret: () => number | null;
+  setCaret: (at: number) => void;
+}
 
 export interface ComposerProps {
   className?: string;
   session: AgentSession;
   draft: string;
   attached: readonly MessageAttachment[];
-  /** Files still being read. An `attach` that uploads takes seconds, and a panel that shows nothing looks broken. */
+  /** What the draft's `@[…](mention:…)` tokens point at; the text carries them, chips only show them. */
+  references?: readonly MessageReference[];
+  /** Files still being read. */
   pending?: number;
-  /** Absent when the screen cannot listen — the same rule as publishing no tool for a control that is not drawn. */
+  /** Absent when the screen cannot listen. */
   mic?: { listening: boolean; onToggle: () => void };
   onDraft: (text: string) => void;
   onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
   onFiles: (files: File[]) => void;
   onRemoveFile: (idx: number) => void;
+  /** Keyed on `refName/refId#path`, not on a row index. */
+  onRemoveReference?: (key: string) => void;
   onSend: () => void;
   onStop: () => void;
   inputRef?: RefObject<HTMLTextAreaElement | null>;
+  /** Draws each `@` pointer as its name; set only when the chat has `reference` sources. */
+  mentions?: boolean;
+  /** Filled by whichever input is drawn. An override that draws its own textarea leaves it null and `inputRef` answers. */
+  handleRef?: RefObject<ComposerHandle | null>;
 }
 
-/** Where the box stops growing and starts scrolling: a chat composer is a paragraph at most. */
+const RichInput = lazy(() => import("./RichInput"), {
+  ssr: false,
+  suspense: true,
+  loading: () => <div className="flex-1" />,
+});
+
 const maxComposerHeight = 128;
 
-/** What the user writes with: the staged files above, and the controls that send or stop below them. */
 export const DefaultComposer = ({
   className,
   session,
   draft,
   attached,
+  references = [],
   pending = 0,
   mic,
   onDraft,
   onKeyDown,
   onFiles,
   onRemoveFile,
+  onRemoveReference,
   onSend,
   onStop,
   inputRef,
+  mentions = false,
+  handleRef,
 }: ComposerProps) => {
   const { l } = usePage();
   const surface = useUiRecipe("input") ?? inputRecipe;
+  const field = surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5");
+  const placeholder = session.pendingQuestion
+    ? l("base.agentAnswer")
+    : session.isRunning
+      ? l("base.agentQueuePlaceholder")
+      : l("base.agentPlaceholder");
+  useEffect(() => {
+    if (!handleRef || mentions) return;
+    handleRef.current = {
+      focus: () => inputRef?.current?.focus(),
+      caret: () => inputRef?.current?.selectionStart ?? null,
+      setCaret: (at) => {
+        inputRef?.current?.focus();
+        inputRef?.current?.setSelectionRange(at, at);
+      },
+    };
+    return () => {
+      handleRef.current = null;
+    };
+  }, [handleRef, inputRef, mentions]);
   useEffect(() => {
     const area = inputRef?.current;
     if (!area) return;
-
+    
     area.style.height = "auto";
     area.style.height = `${Math.min(area.scrollHeight, maxComposerHeight)}px`;
   }, [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}
@@ -70,27 +122,33 @@ export const DefaultComposer = ({
           <Mic className="pb-2" label={l("base.agentListen")} listening={mic.listening} onToggle={mic.onToggle} />
         ) : null}
         <Attach className="pb-2" label={l("base.agentAttach")} onPick={onFiles} />
-        <textarea
-          className={surface({ kind: "area", size: "sm" }, "max-h-32 flex-1 resize-none py-1.5")}
-          onChange={(event) => onDraft(event.target.value)}
-          onKeyDown={onKeyDown}
-          onPaste={(event) => {
-            const pasted = [...event.clipboardData.files];
-            if (!pasted.length) return;
-            event.preventDefault();
-            onFiles(pasted);
-          }}
-          placeholder={
-            session.pendingQuestion
-              ? l("base.agentAnswer")
-              : session.isRunning
-                ? l("base.agentQueuePlaceholder")
-                : l("base.agentPlaceholder")
-          }
-          ref={inputRef}
-          rows={1}
-          value={draft}
-        />
+        {mentions ? (
+          <RichInput
+            className={field}
+            draft={draft}
+            handleRef={handleRef}
+            onDraft={onDraft}
+            onFiles={onFiles}
+            onKeyDown={onKeyDown}
+            placeholder={placeholder}
+          />
+        ) : (
+          <textarea
+            className={field}
+            onChange={(event) => onDraft(event.target.value)}
+            onKeyDown={onKeyDown}
+            onPaste={(event) => {
+              const pasted = [...event.clipboardData.files];
+              if (!pasted.length) return;
+              event.preventDefault();
+              onFiles(pasted);
+            }}
+            placeholder={placeholder}
+            ref={inputRef}
+            rows={1}
+            value={draft}
+          />
+        )}
         {/* A parked question is not a turn to stop: the loop is waiting on the card, and the card has its own out. */}
         {session.isRunning && !session.pendingQuestion ? (
           <>
@@ -114,3 +172,27 @@ export const DefaultComposer = ({
 };
 
 export const Composer = createOverridable("AgentComposer", DefaultComposer);
+
+interface MicProps {
+  className?: string;
+  listening: boolean;
+  label: string;
+  onToggle: () => void;
+}
+
+const Mic = ({ className, listening, label, onToggle }: MicProps) => (
+  <button
+    aria-label={label}
+    aria-pressed={listening}
+    className={cn(
+      "shrink-0 hover:text-foreground",
+      listening ? "animate-pulse text-primary" : "text-foreground/50",
+      className,
+    )}
+    onClick={onToggle}
+    title={label}
+    type="button"
+  >
+    {listening ? <AiOutlineAudioMuted /> : <AiOutlineAudio />}
+  </button>
+);

package/ui/Agent/Dock.tsx

@@ -1,29 +1,25 @@
 "use client";
 import { cn } from "akanjs/client";
-import { type AgentBridge, ensureStoreSurface, StoreRegistry } from "akanjs/store";
-import { useRef, useState } from "react";
-import { AgenticSurface } from "../../vendor/use-agentic";
-import Context from "./Context";
-import Section from "./Section";
-import StateKey from "./StateKey";
-import Tool from "./Tool";
-import Transcript from "./Transcript";
+import {
+  type AgentBridge,
+  AgentContext,
+  ensureStoreSurface,
+  type SerializedStoreState,
+  StoreRegistry,
+} from "akanjs/store";
+import { type ReactNode, useRef, useState } from "react";
+import { type AgentCall, AgenticSurface, type PublishedTool, type SurfaceView } from "../../vendor/use-agentic";
+import { buttonRecipe } from "../recipe";
 
 export interface DockProps {
   className?: string;
-  /** The store keys and their masking. Defaults to the app's own. */
+  /** Defaults to the app's own. */
   bridge?: AgentBridge;
-  /** Where the declared tools live. Pass a zone's own to inspect it; defaults to the whole screen's. */
+  /** Defaults to the whole screen's; pass a zone's own to inspect it. */
   surface?: AgenticSurface;
   open?: boolean;
 }
 
-/**
- * The in-page surface of the agent: what this screen declared an agent may do, what it may read, and what it has
- * done. Tools come from the surface rather than from the store, because a tool exists only where a component
- * declared one — the dock is the way to see that this screen published what its author thought it did, which is
- * the one thing no amount of reading the source answers. Renders nothing on `AKAN_PUBLIC_ENV=main`.
- */
 export const Dock = ({ className, bridge, surface, open = false }: DockProps) => {
   const held = useRef<{ bridge: AgentBridge; surface: AgenticSurface } | null>(null);
   held.current ??= { bridge: bridge ?? ensureStoreSurface().bridge, surface: surface ?? AgenticSurface.shared };
@@ -75,3 +71,167 @@ export const Dock = ({ className, bridge, surface, open = false }: DockProps) =>
     </aside>
   );
 };
+
+interface SectionProps {
+  className?: string;
+  title: string;
+  count: number;
+  children: ReactNode;
+  open?: boolean;
+}
+
+export function Section({ className, title, count, children, open }: SectionProps) {
+  return (
+    <details className={cn("group rounded-box bg-muted", className)} open={open}>
+      <summary className="flex cursor-pointer list-none items-center gap-2 px-3 py-2 [&::-webkit-details-marker]:hidden">
+        <span className="font-semibold text-sm">{title}</span>
+        <span className="text-foreground/50 text-xs">{count}</span>
+        <span className="ml-auto text-foreground/40 transition-transform group-open:rotate-180">▾</span>
+      </summary>
+      <div className="flex flex-col gap-1 px-3 pb-3">{children}</div>
+    </details>
+  );
+}
+
+interface TranscriptProps {
+  className?: string;
+  calls: readonly AgentCall[];
+}
+
+export function Transcript({ className, calls }: TranscriptProps) {
+  return (
+    <div className={cn("flex flex-col gap-1", className)}>
+      {calls.map((call, idx) => (
+        <div className="flex flex-col rounded-field bg-background/60 px-2 py-1" key={idx}>
+          <div className="flex items-baseline gap-2">
+            <span className="truncate font-mono text-xs">{call.name}</span>
+            <span className="ml-auto shrink-0 text-[10px] text-foreground/40">
+              {call.at.toISOString().slice(11, 19)}
+            </span>
+          </div>
+          <span className="truncate font-mono text-[10px] text-foreground/50">{JSON.stringify(call.args)}</span>
+          {call.error ? <span className="text-[10px] text-destructive">{call.error}</span> : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+interface ToolProps {
+  className?: string;
+  surface: SurfaceView;
+  tool: PublishedTool;
+  onRun: () => void;
+}
+
+export function Tool({ className, surface, tool, onRun }: ToolProps) {
+  const [args, setArgs] = useState("{}");
+  const [error, setError] = useState("");
+  const properties = (tool.parameters as { properties?: unknown } | undefined)?.properties ?? {};
+  const run = async () => {
+    setError("");
+    try {
+      await surface.call(tool.name, JSON.parse(args) as Record<string, unknown>);
+    } catch (thrown) {
+      setError(thrown instanceof Error ? thrown.message : String(thrown));
+    }
+    onRun();
+  };
+  return (
+    <details className={cn("rounded-field bg-background/60 px-2 py-1", className)}>
+      <summary className="flex cursor-pointer list-none items-center gap-2 [&::-webkit-details-marker]:hidden">
+        <span className="truncate font-mono text-xs">{tool.name}</span>
+        {tool.needsConfirm ? <span className="shrink-0 text-[10px] text-foreground/40">confirm</span> : null}
+      </summary>
+      <div className="flex flex-col gap-2 py-2">
+        {tool.description ? <p className="text-foreground/70 text-xs">{tool.description}</p> : null}
+        <pre className="overflow-x-auto rounded-field bg-muted p-2 text-[10px] leading-tight">
+          {JSON.stringify(properties, null, 2)}
+        </pre>
+        <textarea
+          className="w-full rounded-field bg-muted p-2 font-mono text-xs"
+          rows={2}
+          value={args}
+          onChange={(event) => setArgs(event.target.value)}
+        />
+        {/* `buttonRecipe`, not `Button`: this developer surface does not read the app runtime through `usePage()`. */}
+        <button className={buttonRecipe({ size: "xs" })} onClick={run} type="button">
+          Run
+        </button>
+        {error ? <p className="text-destructive text-xs">{error}</p> : null}
+      </div>
+    </details>
+  );
+}
+
+interface StateKeyProps {
+  className?: string;
+  bridge: AgentBridge;
+  name: string;
+  entry: SerializedStoreState;
+  live?: boolean;
+}
+
+export function StateKey({ className, bridge, name, entry, live }: StateKeyProps) {
+  const [shown, setShown] = useState("");
+  const read = () => {
+    try {
+      setShown(JSON.stringify(bridge.read(name), null, 2));
+    } catch (thrown) {
+      setShown(thrown instanceof Error ? thrown.message : String(thrown));
+    }
+  };
+  return (
+    <div className={cn("flex flex-col gap-1", className)}>
+      <button className="flex items-center gap-2 text-left" type="button" onClick={read}>
+        <span className="truncate font-mono text-xs">{name}</span>
+        <span className="ml-auto shrink-0 text-[10px] text-foreground/40">
+          {live ? "live · " : ""}
+          {entry.refName ? `${entry.refName}.${entry.modelType ?? ""}` : entry.type}
+          {entry.derived ? " · derived" : ""}
+        </span>
+      </button>
+      {shown ? (
+        <pre className="scrollbar-thin max-h-40 overflow-auto rounded-field bg-muted p-2 text-[10px] leading-tight">
+          {shown}
+        </pre>
+      ) : null}
+    </div>
+  );
+}
+
+interface ContextProps {
+  className?: string;
+}
+
+export function Context({ className }: ContextProps) {
+  const [shown, setShown] = useState("");
+  
+  if (process.env.AKAN_PUBLIC_ENV === "main") return null;
+  const assemble = () => {
+    try {
+      const { guides, tools } = AgenticSurface.shared.snapshot();
+      const context = AgentContext.of().blocks(AgenticSurface.shared);
+      const assembled = {
+        tools: tools.map((tool) => tool.name),
+        ...(guides.length ? { guides } : {}),
+        context,
+      };
+      setShown(JSON.stringify(assembled, null, 2));
+    } catch (thrown) {
+      setShown(thrown instanceof Error ? thrown.message : String(thrown));
+    }
+  };
+  return (
+    <div className={className}>
+      <button className={buttonRecipe({ size: "xs" })} onClick={assemble} type="button">
+        Assemble
+      </button>
+      {shown ? (
+        <pre className="scrollbar-thin mt-2 max-h-60 overflow-auto rounded-field bg-background/60 p-2 text-[10px] leading-tight">
+          {shown}
+        </pre>
+      ) : null}
+    </div>
+  );
+}

package/ui/Agent/Guide.tsx

@@ -5,11 +5,7 @@ export interface GuideProps {
   instructions: string;
 }
 
-/**
- * Standing agent guidance scoped to a route subtree: render it from a `_layout.tsx` or a page and the text joins
- * the turn's instructions while that subtree is mounted. Nesting layers naturally — each mounted Guide contributes
- * its block, and navigating away withdraws it. Renders nothing.
- */
+/** Joins the turn's instructions while mounted; renders nothing. */
 export const Guide = ({ instructions }: GuideProps) => {
   useAgentGuide(instructions);
   return null;

package/ui/Agent/History.tsx

@@ -6,27 +6,10 @@ export interface HistoryProps {
   load: SessionHistory["load"];
   save: SessionHistory["save"];
   clear: SessionHistory["clear"];
-  /** Where a host with its own server-side summary moves its watermark — see `onCompact` on the session options. */
   onCompact?: AgentSessionOptions["onCompact"];
 }
 
-/**
- * Puts the enclosing zone's transcript wherever the app keeps it, as a mounted component rather than a prop.
- *
- * `persist` does the same thing and has to be passed to whoever builds the session, which makes every ancestor up
- * to that point a client component — a function cannot cross the server/client boundary as a prop. Mounted here
- * instead, the only client module an app needs is this leaf, and `Agent.Zone` and the chat inside it can be
- * assembled by a server component. Same shape as `Agent.Guide`, and it renders nothing.
- *
- * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
- * mounting with the zone restores and mounting later saves from there on.
- *
- * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
- * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
- * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
- * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
- * takes the slot, so a later unmount here leaves it alone.
- */
+/** Attaches the enclosing session's history while mounted; restoring lands only before the conversation started. */
 export const History = ({ load, save, clear, onCompact }: HistoryProps) => {
   const session = useContext(SessionContext);
   if (!session) throw new Error("Agent.History needs an enclosing Agent.Zone or AgentProvider to hold the session.");

package/ui/Agent/Launcher.tsx

@@ -6,9 +6,9 @@ import { createOverridable } from "../UiOverride";
 export interface LauncherProps {
   className?: string;
   label: string;
-  /** The chord that opens the chat, shown on hover. Null until the platform is known, which needs the client. */
+  /** Shown on hover; null until the client knows the platform. */
   hotkey?: { label: string; keys: string } | null;
-  /** Messages that arrived while the panel was closed, so a finished turn is not silent. */
+  /** Messages that arrived while the panel was closed. */
   unread: number;
   onOpen: () => void;
   buttonRef?: Ref<HTMLButtonElement>;

package/ui/Agent/Markdown.tsx

@@ -1,10 +1,44 @@
 "use client";
 import { cn } from "akanjs/client";
+import type { Align, MarkdownBlock, MarkdownItem, MarkdownSpan, TableBlock } from "akanjs/common";
+import { MarkdownBlocks, MarkdownSpans } from "akanjs/common";
 import type { ReactNode } from "react";
 import { createOverridable } from "../UiOverride";
-import { type MarkdownBlock, MarkdownBlocks, type MarkdownItem } from "./markdownBlocks";
-import { spans } from "./markdownSpans";
-import type { Align, TableBlock } from "./markdownTable";
+
+const spans = (text: string): ReactNode[] => MarkdownSpans.of(text).map((span, at) => node(span, at));
+
+const node = (span: MarkdownSpan, at: number): ReactNode => {
+  switch (span.kind) {
+    case "link":
+      return (
+        <a className="underline" href={span.href} key={at} rel="noreferrer" target="_blank">
+          {spans(span.text)}
+        </a>
+      );
+    case "code":
+      return (
+        <code className="rounded-field bg-muted px-1 font-mono text-[11px]" key={at}>
+          {span.text}
+        </code>
+      );
+    case "strong":
+      return (
+        <strong className="font-semibold" key={at}>
+          {spans(span.text)}
+        </strong>
+      );
+    case "em":
+      return <em key={at}>{spans(span.text)}</em>;
+    case "del":
+      return (
+        <del className="opacity-60" key={at}>
+          {span.text}
+        </del>
+      );
+    default:
+      return span.text;
+  }
+};
 
 const alignClass: { [key in Align]: string } = { left: "text-left", center: "text-center", right: "text-right" };
 
@@ -13,8 +47,6 @@ interface ListProps {
   items: MarkdownItem[];
 }
 
-/** Folds the scanner's flat depth-scored items back into real nested lists, so a nested run carries its own
- *  marker and leaves the outer numbering alone — a hidden `li` still advances an `ol`'s counter. */
 const List = ({ className, items }: ListProps) => {
   const rows: ReactNode[] = [];
   for (let at = 0; at < items.length; ) {
@@ -48,7 +80,6 @@ const Table = ({ block }: TableProps) => {
     return align ? alignClass[align] : "";
   });
   return (
-
     <div className="overflow-x-auto">
       <table className="min-w-full border-collapse">
         <thead>
@@ -78,7 +109,7 @@ const Table = ({ block }: TableProps) => {
 
 export interface CodeProps {
   className?: string;
-  /** The fence's info word, kept so a highlighter bound to this slot knows what it was handed. */
+  /** The fence's info word. */
   lang?: string;
   text: string;
 }
@@ -92,7 +123,6 @@ export const DefaultCode = ({ className, lang, text }: CodeProps) => (
   </pre>
 );
 
-/** The one place a fenced block is drawn, so an app binds its highlighter here instead of replacing the renderer. */
 const Code = createOverridable("AgentCode", DefaultCode);
 
 interface BlockProps {
@@ -103,7 +133,7 @@ const Block = ({ block }: BlockProps) => {
   switch (block.kind) {
     case "code":
       return <Code lang={block.lang} text={block.text} />;
-
+    
     case "heading":
       return <p className={cn("font-semibold", block.level <= 2 && "text-base")}>{spans(block.text)}</p>;
     case "list":
@@ -126,11 +156,7 @@ export interface MarkdownProps {
   children: string;
 }
 
-/**
- * The chat's own markdown renderer: React elements, never `dangerouslySetInnerHTML`, and no parser dependency.
- * `Bun.markdown` is the obvious candidate and cannot serve this — it is a runtime API the bundler passes through
- * verbatim, so it is undefined in the browser, and assistant text arrives here as SSE deltas the client accrues.
- */
+/** React elements, never `dangerouslySetInnerHTML`; not `Bun.markdown`, which is undefined in the browser. */
 export const DefaultMarkdown = ({ className, children }: MarkdownProps) => (
   <div className={cn("flex flex-col gap-2 break-words", className)}>
     {MarkdownBlocks.of(children).map((block, idx) => (

package/ui/Agent/MentionNode.ts

@@ -0,0 +1,54 @@
+"use client";
+import { $applyNodeReplacement, type LexicalNode, type NodeKey, type SerializedTextNode, TextNode } from "lexical";
+import { type MessageReference, Reference } from "../../vendor/use-agentic";
+
+export interface SerializedMentionNode extends SerializedTextNode {
+  reference: MessageReference;
+}
+
+export class MentionNode extends TextNode {
+  #reference: MessageReference;
+
+  static override getType() {
+    return "mention";
+  }
+
+  static override clone(node: MentionNode): MentionNode {
+    return new MentionNode(node.#reference, node.__key);
+  }
+
+  static override importJSON(json: Parameters<typeof TextNode.importJSON>[0]): MentionNode {
+    return new MentionNode((json as Partial<SerializedMentionNode>).reference);
+  }
+
+  constructor(reference: MessageReference = { refName: "", refId: "", label: "" }, key?: NodeKey) {
+    super(reference.label || Reference.keyOf(reference), key);
+    this.#reference = reference;
+    this.setMode("token");
+  }
+
+  get reference(): MessageReference {
+    return this.#reference;
+  }
+
+  override getTextContent(): string {
+    return Reference.token(this.#reference);
+  }
+
+  override createDOM(...args: Parameters<TextNode["createDOM"]>): HTMLElement {
+    const dom = super.createDOM(...args);
+    dom.className = "rounded-field bg-primary/10 px-1 text-primary";
+    dom.title = Reference.keyOf(this.#reference);
+    return dom;
+  }
+
+  override exportJSON(): SerializedMentionNode {
+    return { ...super.exportJSON(), reference: this.#reference };
+  }
+}
+
+export const $createMentionNode = (reference: MessageReference): MentionNode =>
+  $applyNodeReplacement(new MentionNode(reference));
+
+export const $isMentionNode = (node: LexicalNode | null | undefined): node is MentionNode =>
+  node instanceof MentionNode;

package/ui/Agent/Menu.tsx

@@ -5,7 +5,7 @@ import { createOverridable } from "../UiOverride";
 export interface MenuRow {
   name: string;
   description?: string;
-  /** The argument names a prompt takes, shown so a user knows what to type after the name. */
+  /** The argument names a row takes. */
   hint?: string;
   pick: () => void;
 }
@@ -13,13 +13,13 @@ export interface MenuRow {
 export interface MenuProps {
   className?: string;
   rows: MenuRow[];
-  /** Index the arrows are on. Enter picks it and Tab completes its name, so it has to be visible. */
   selected: number;
+  /** Drawn before each row name; `/` by default. */
+  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) => {
+export const DefaultAgentMenu = ({ className, rows, selected, prefix = "/", onPick }: MenuProps) => {
   if (!rows.length) return null;
   return (
     <div
@@ -41,7 +41,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>