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

package/ui/Agent/Question.tsx

@@ -10,12 +10,7 @@ export interface QuestionProps {
   question: PendingQuestion;
 }
 
-/**
- * The agent's question, parked above the composer while the loop waits on it. Only the picks live here — the
- * composer below is the free-text answer, so the panel never grows a second input meaning the same thing. There is
- * always that way out of the options: the model wrote them, and only the user knows whether the answer is among
- * them. Mounted keyed by call id, so a second ask starts with nothing picked.
- */
+/** Only the picks: the composer below is the free-text answer. */
 export const DefaultQuestion = ({ className, question }: QuestionProps) => {
   const { l } = usePage();
   const [picked, setPicked] = useState<string[]>([]);

package/ui/Agent/Queued.tsx

@@ -3,21 +3,17 @@ 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 {
   className?: string;
   message: QueuedMessage;
-  /** Hands the message back to the composer to be changed — the only way to edit what is already out of it. */
+  /** Hands the message back to the composer. */
   onEdit: () => void;
   onCancel: () => void;
 }
 
-/**
- * The message waiting for the running turn to end, parked above the composer where the question card sits. It is
- * shown rather than silently held because a send that vanished from the composer and has not appeared in the
- * transcript reads as lost, and because taking it back or dropping it needs somewhere to click.
- */
 export const DefaultQueued = ({ className, message, onEdit, onCancel }: QueuedProps) => {
   const { l } = usePage();
   return (
@@ -29,6 +25,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,40 @@
+"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;
+}
+
+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/RichInput.tsx

@@ -0,0 +1,146 @@
+"use client";
+import { registerPlainText } from "@lexical/plain-text";
+import { cn } from "akanjs/client";
+import {
+  COMMAND_PRIORITY_HIGH,
+  createEditor,
+  KEY_ARROW_DOWN_COMMAND,
+  KEY_ARROW_UP_COMMAND,
+  KEY_ENTER_COMMAND,
+  KEY_ESCAPE_COMMAND,
+  KEY_TAB_COMMAND,
+  type LexicalCommand,
+  PASTE_COMMAND,
+} from "lexical";
+import { type KeyboardEvent as ReactKeyboardEvent, type RefObject, useEffect, useRef, useState } from "react";
+import type { ComposerHandle } from "./Composer";
+import { MentionNode } from "./MentionNode";
+import { MentionDraft } from "./mentionDraft";
+
+interface RichInputProps {
+  className?: string;
+  draft: string;
+  placeholder: string;
+  onDraft: (text: string) => void;
+  /** The textarea's own handler, fed a synthetic event: the chat reads keys off the draft and caret, not the DOM. */
+  onKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+  onFiles: (files: File[]) => void;
+  handleRef?: RefObject<ComposerHandle | null>;
+}
+
+export const RichInput = ({
+  className,
+  draft,
+  placeholder,
+  onDraft,
+  onKeyDown,
+  onFiles,
+  handleRef,
+}: RichInputProps) => {
+  const [editor] = useState(() =>
+    createEditor({
+      namespace: "akanAgentComposer",
+      nodes: [MentionNode],
+      onError: (error: Error) => console.error(error),
+    }),
+  );
+  const rootRef = useRef<HTMLDivElement>(null);
+  const live = useRef({ draft, onDraft, onKeyDown, onFiles });
+  live.current = { draft, onDraft, onKeyDown, onFiles };
+  
+  const settled = useRef(draft);
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    editor.setRootElement(root);
+    const forward = (key: string, event: KeyboardEvent | null) => {
+      const value = MentionDraft.read();
+      const caret = MentionDraft.caret() ?? value.length;
+      let prevented = false;
+      live.current.onKeyDown({
+        key,
+        shiftKey: !!event?.shiftKey,
+        nativeEvent: { isComposing: !!event?.isComposing },
+        currentTarget: { value, selectionStart: caret, selectionEnd: caret },
+        preventDefault: () => {
+          prevented = true;
+          event?.preventDefault();
+        },
+      } as unknown as ReactKeyboardEvent<HTMLTextAreaElement>);
+      return prevented;
+    };
+    
+    const onKey = <T extends KeyboardEvent | null>(command: LexicalCommand<T>, key: string) =>
+      editor.registerCommand<T>(command, (event) => forward(key, event), COMMAND_PRIORITY_HIGH);
+    const teardowns = [
+      registerPlainText(editor),
+      editor.registerUpdateListener(({ editorState }) => {
+        const text = editorState.read(() => MentionDraft.read());
+        if (text === settled.current) return;
+        
+        settled.current = text;
+        live.current.onDraft(text);
+      }),
+      onKey(KEY_ENTER_COMMAND, "Enter"),
+      onKey(KEY_TAB_COMMAND, "Tab"),
+      onKey(KEY_ARROW_UP_COMMAND, "ArrowUp"),
+      onKey(KEY_ARROW_DOWN_COMMAND, "ArrowDown"),
+      onKey(KEY_ESCAPE_COMMAND, "Escape"),
+      editor.registerCommand(
+        PASTE_COMMAND,
+        (event) => {
+          const files = [...(("clipboardData" in event ? event.clipboardData?.files : null) ?? [])];
+          if (!files.length) return false;
+          event.preventDefault();
+          live.current.onFiles(files);
+          return true;
+        },
+        COMMAND_PRIORITY_HIGH,
+      ),
+    ];
+    if (live.current.draft) editor.update(() => MentionDraft.write(live.current.draft), { discrete: true });
+    return () => {
+      for (const teardown of teardowns) teardown();
+      editor.setRootElement(null);
+    };
+  }, [editor]);
+  useEffect(() => {
+    if (draft === settled.current) return;
+    settled.current = draft;
+    editor.update(() => MentionDraft.write(draft), { discrete: true });
+  }, [draft, editor]);
+  useEffect(() => {
+    if (!handleRef) return;
+    handleRef.current = {
+      focus: () => editor.focus(),
+      caret: () => editor.getEditorState().read(() => MentionDraft.caret()),
+      setCaret: (at) => {
+        editor.update(() => MentionDraft.place(at), { discrete: true });
+        editor.focus();
+      },
+    };
+    return () => {
+      handleRef.current = null;
+    };
+  }, [editor, handleRef]);
+  return (
+    <div className="relative flex-1">
+      <div
+        aria-label={placeholder}
+        aria-multiline
+        className={cn("max-h-32 overflow-y-auto whitespace-pre-wrap break-words outline-none", className)}
+        contentEditable
+        ref={rootRef}
+        role="textbox"
+        suppressContentEditableWarning
+      />
+      {draft ? null : (
+        <span className="pointer-events-none absolute inset-0 select-none px-3 py-1.5 text-foreground/40 text-sm">
+          {placeholder}
+        </span>
+      )}
+    </div>
+  );
+};
+
+export default RichInput;

package/ui/Agent/Skip.tsx

@@ -2,25 +2,13 @@ import type { ReactNode } from "react";
 
 export interface SkipProps {
   className?: string;
-  /**
-   * What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. Required
-   * because the marker is the whole point: an unnamed one tells the agent a region exists and nothing about it.
-   */
+  /** What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. */
   label: string;
   children: ReactNode;
 }
 
-/**
- * A region the default `readScreen` leaves out, for chrome that costs the agent tokens and answers nothing — a
- * footer, a cookie banner, a repeated nav. What stands in its place is `[skipped: <label>]`, so an agent asked
- * about the footer says it did not read one instead of reporting that the page has none, and `section: "<label>"`
- * reads it on request.
- *
- * **This hides text, not behaviour.** Tools and state keys are declarations, not markup: an `st.tool` inside here
- * is published exactly as before, and `highlight` still reaches a control in here. It renders a wrapper element,
- * so where a div between a flex container and its children would move the layout, put the attribute on the element
- * the page already renders — `<footer data-agent-skip="site footer">`.
- */
+/** Hides text from `readScreen`, not tools or state. Where a wrapper div would move the layout, put
+ *  `data-agent-skip="<label>"` on an element the page already renders. */
 export const Skip = ({ className, label, children }: SkipProps) => {
   return (
     <div className={className} data-agent-skip={label}>

package/ui/Agent/Steps.tsx

@@ -0,0 +1,33 @@
+"use client";
+import type { AgentProgressReport, ChatMessage, ToolCallResult } from "../../vendor/use-agentic";
+import { createOverridable } from "../UiOverride";
+import Bubble from "./Bubble";
+
+export interface StepsProps {
+  /** One agent turn as rendered: tool messages keep only the results no call row claims. */
+  messages: readonly ChatMessage[];
+  /** True only for the last turn while the session is still working on it. */
+  isRunning: boolean;
+  /** What the running call last reported about itself. */
+  progress?: (AgentProgressReport & { callId: string }) | null;
+  /** Results by call id across the transcript, so a call's own row resolves in place. */
+  results?: ReadonlyMap<string, ToolCallResult>;
+}
+
+/** Draws the turn's messages flat into a Fragment: no element, no `className`. */
+export const DefaultSteps = ({ messages, progress, results }: StepsProps) => {
+  return (
+    <>
+      {messages.map((message, idx) =>
+        
+        message.role === "tool" ? (
+          <Bubble key={idx} message={message} />
+        ) : (
+          <Bubble key={idx} message={message} progress={progress} results={results} />
+        ),
+      )}
+    </>
+  );
+};
+
+export default createOverridable("AgentSteps", DefaultSteps);

package/ui/Agent/ToolCard.tsx

@@ -0,0 +1,32 @@
+"use client";
+import { cn, usePage } from "akanjs/client";
+import type { PendingCard } from "../../vendor/use-agentic";
+import { createOverridable } from "../UiOverride";
+
+export interface ToolCardProps {
+  className?: string;
+  card: PendingCard;
+}
+
+/** Always draws a skip, so a card rendering no cancel of its own cannot park the turn for good. */
+export const DefaultToolCard = ({ className, card }: ToolCardProps) => {
+  const { l } = usePage();
+  return (
+    <div
+      aria-label={l("base.agentToolCard")}
+      className={cn("flex flex-col gap-2 border-primary/30 border-t bg-primary/5 px-4 py-3", className)}
+      role="group"
+    >
+      {card.render({ args: card.args, submit: card.submit, cancel: card.dismiss })}
+      <button
+        className="self-end text-foreground/50 text-xs hover:text-foreground"
+        onClick={() => card.dismiss()}
+        type="button"
+      >
+        {l("base.skip")}
+      </button>
+    </div>
+  );
+};
+
+export default createOverridable("AgentToolCard", DefaultToolCard);

package/ui/Agent/Zone.tsx

@@ -1,5 +1,6 @@
 "use client";
 import { usePage } from "akanjs/client";
+import type { AgentVisualOption } from "akanjs/store";
 import { type ReactNode, useEffect, useMemo, useRef } from "react";
 import {
   AgenticSurface,
@@ -12,55 +13,36 @@ import {
   type SessionHistory,
   useScopePath,
 } from "../../vendor/use-agentic";
-import { agentSessionOf } from "./agentSessionOf";
+import { agentSessionOf, type BuiltinOption, type PersistOption } from "./agentSessionOf";
 import { Guide } from "./Guide";
-import type { PersistOption } from "./sessionHistory";
-import type { BuiltinOption } from "./sessionView";
 
 export interface ZoneProps {
   className?: string;
   /** Names the zone; the scope id and the `data-agent-zone` container both derive from it. */
   id: string;
   label?: string;
-  /** Zone-scoped guidance — a mounted Guide, so the root agent reads it too (ancestor rule), a sibling zone never does. */
+  /** A mounted Guide: the root agent reads it too, a sibling zone never does. */
   instructions?: string;
   runner?: AgentRunner;
   maxTurns?: number;
-  /** When this zone's conversation summarizes itself — same contract as the chat's own `compact`. */
+  /** Same contract as the chat's own `compact`. */
   compact?: CompactOptions;
-  /**
-   * Which of the runtime's own tools this zone's agent gets — all of them by default, `false` none, an array
-   * exactly the ones it names. `builtins={["readScreen", "readState"]}` is how a zone that must not leave the
-   * screen stops being able to: the tools are withheld, not discouraged, so a prompt cannot talk the model past it.
-   */
+  /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
   builtins?: BuiltinOption;
-  /**
-   * Keeps this zone's transcript across reloads, keyed by the zone's scope path — web storage by default, or a
-   * `SessionHistory` of the app's own to keep it anywhere else, a server included.
-   */
+  /** Keyed by the zone's scope path; web storage by default, or an app `SessionHistory`. */
   persist?: PersistOption | SessionHistory;
-  /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+  /** Called after a compaction replaced messages with one summary. */
   onCompact?: AgentSessionOptions["onCompact"];
-  /**
-   * Runs this zone on a session the app built instead of one of its own, and the app then owns it: unmounting the
-   * zone leaves it running. Read once at mount, like every other session option here.
-   */
+  /** On by default; `false` draws nothing, `{ cursor: false }` / `{ reveal: false }` turn one effect off. */
+  visual?: boolean | AgentVisualOption;
+  /** An app-built session the app keeps owning: unmounting leaves it running. Read once at mount. */
   session?: AgentSession;
-  /** Hands the session out once it exists, for a page or store that wants to send into it or watch it. */
+  /** Called once the session exists. */
   onSession?: (session: AgentSession) => void;
   children: ReactNode;
 }
 
-/**
- * A zone agent: one subtree with its own conversation over a scoped view of the same surface. Everything mounted
- * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
- * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
- * on one screen run two conversations in parallel, each seeing only its own subtree.
- *
- * **Everything a zone publishes is named `<id>.<name>`.** Instructions that name a tool must carry the prefix —
- * a bare name is a tool that does not exist, and the model calling it spends a turn on `Unknown tool`. Build the
- * name from the id rather than writing it twice, and read `Agent.Context`'s Assemble to see the published list.
- */
+/** Everything a zone publishes is named `<id>.<name>`, so instructions naming a tool must carry the prefix. */
 export const Zone = ({
   className,
   id,
@@ -72,6 +54,7 @@ export const Zone = ({
   builtins,
   persist,
   onCompact,
+  visual = true,
   session: provided,
   onSession,
   children,
@@ -93,10 +76,11 @@ export const Zone = ({
       builtins,
       persist,
       onCompact,
+      visual,
     });
   const session = held.current;
   useEffect(
-
+    
     () => (provided ? undefined : () => session.abort()),
     [],
   );

package/ui/Agent/agentSessionOf.ts

@@ -1,39 +1,52 @@
-import { AgentContext, ensureStoreSurface, ScreenSettle } from "akanjs/store";
+import { getEnv } from "akanjs/base";
 import {
+  AgentContext,
+  AgentVisual,
+  type AgentVisualOption,
+  ensureStoreSurface,
+  ScreenSettle,
+  StoreSurfaceSource,
+} from "akanjs/store";
+import {
+  type AgenticSurface,
   type AgentRunner,
   AgentSession,
   type AgentSessionOptions,
+  type ChatMessage,
   type CompactOptions,
   type SessionHistory,
+  type SurfaceView,
+  Transcript,
 } from "../../vendor/use-agentic";
 import { fetchRunner } from "./fetchRunner";
-import { type PersistOption, sessionHistoryOf } from "./sessionHistory";
-import { type BuiltinOption, sessionView } from "./sessionView";
+
+/** A tool the akan runtime contributes to every screen, whatever that screen declares. */
+export type AgentBuiltin = (typeof StoreSurfaceSource.builtins)[number];
+
+/** `true` (the default) takes all of them, `false` none, an array exactly the ones it names. */
+export type BuiltinOption = boolean | AgentBuiltin[];
+
+export type PersistOption = boolean | { storage?: "session" | "local"; key?: string };
 
 export interface AgentSessionSetup {
-  /** Read per call rather than captured, so text the session builds follows a language switched mid-conversation. */
+  /** Read per call, so the session's own text follows a language switched mid-conversation. */
   l: (key: string) => string;
-  /** The zone's scope path, empty for the root agent — it picks both the surface view and the persistence key. */
+  /** The zone's scope path, empty for the root agent; it picks both the surface view and the persistence key. */
   view?: string[];
   runner?: AgentRunner;
   instructions?: string;
   maxTurns?: number;
   compact?: CompactOptions;
-  /**
-   * Which of the runtime's own tools this session gets: all of them by default, none with `false`, exactly the
-   * ones an array names. A zone whose conversation must stay on one screen takes `navigate` and `goBack` off it.
-   */
+  /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
   builtins?: BuiltinOption;
-  /** Web storage by default; a `SessionHistory` puts the transcript wherever the app keeps it, including a server. */
+  /** Web storage by default, or an app `SessionHistory`. */
   persist?: PersistOption | SessionHistory;
-  /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+  /** Called after a compaction replaced messages with one summary. */
   onCompact?: AgentSessionOptions["onCompact"];
+  /** `false` draws nothing while this session drives the page. */
+  visual?: boolean | AgentVisualOption;
 }
 
-/**
- * The one place a chat session is wired to the akan runtime. Chat and Zone both build one, and building it twice
- * is how a zone came to be the only surface with no `compact` option — an option added on one side of a copy.
- */
 export const agentSessionOf = ({
   l,
   view = [],
@@ -44,9 +57,11 @@ export const agentSessionOf = ({
   builtins,
   persist,
   onCompact,
+  visual,
 }: AgentSessionSetup): AgentSession => {
   const { surface } = ensureStoreSurface();
   const history = sessionHistoryOf(persist, view.join("."));
+  const drawing = AgentVisual.sink(visual);
   return new AgentSession(sessionView(surface, view, builtins), runner ?? fetchRunner(), {
     buildContext: (scoped) => AgentContext.of().blocks(scoped, view),
     settle: () => ScreenSettle.wait(),
@@ -56,5 +71,90 @@ export const agentSessionOf = ({
     ...(compact ? { compact } : {}),
     ...(history ? { history } : {}),
     ...(onCompact ? { onCompact } : {}),
+    ...(drawing ?? {}),
   });
 };
+
+export const sessionView = (surface: AgenticSurface, path: string[], builtins?: BuiltinOption): SurfaceView => {
+  const scoped = path.length ? surface.view(path) : surface;
+  if (builtins === undefined || builtins === true) return scoped;
+  const kept = new Set<string>(builtins === false ? [] : builtins);
+  const names = StoreSurfaceSource.builtins as readonly string[];
+  const shown = (name: string) => kept.has(name) || !names.includes(name) || surface.declares(name, path);
+  return {
+    snapshot: () => {
+      const snapshot = scoped.snapshot();
+      return { ...snapshot, tools: snapshot.tools.filter((tool) => shown(tool.name)) };
+    },
+    tool: (name) => (shown(name) ? scoped.tool(name) : null),
+    call: async (name, args) => {
+      if (!shown(name)) throw new Error(`Unknown tool: ${name}`);
+      return await scoped.call(name, args);
+    },
+    read: (name) => scoped.read(name),
+    diffSince: (before) => scoped.diffSince(before),
+    subscribe: (listener) => scoped.subscribe(listener),
+  };
+};
+
+const restoredValue =
+  "the conversation was restored from storage, which keeps what the user pointed at but not the value it held";
+
+const withoutContent = (message: ChatMessage): ChatMessage => {
+  if (!message.attachments?.length && !message.references?.length) return message;
+  return {
+    ...message,
+    ...(message.attachments?.length
+      ? {
+          attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
+            name,
+            mimeType,
+            ...(url ? { url } : {}),
+            ...(ref ? { ref } : {}),
+          })),
+        }
+      : {}),
+    ...(message.references?.length
+      ? {
+          references: message.references.map(({ refName, refId, label, path }) => ({
+            refName,
+            refId,
+            label,
+            ...(path ? { path } : {}),
+            note: restoredValue,
+          })),
+        }
+      : {}),
+  };
+};
+
+export const sessionHistoryOf = (
+  persist: PersistOption | SessionHistory | undefined,
+  pathKey = "",
+): SessionHistory | undefined => {
+  if (!persist) return undefined;
+  if (typeof persist === "object" && typeof (persist as SessionHistory).load === "function")
+    return persist as SessionHistory;
+  if (typeof window === "undefined") return undefined;
+  const option = persist === true ? {} : (persist as Exclude<PersistOption, boolean>);
+  const storage = option.storage === "local" ? window.localStorage : window.sessionStorage;
+  const key = option.key ?? `akan.agent.${getEnv().appName}${pathKey ? `.${pathKey}` : ""}`;
+  const version = 1;
+  const cap = 50;
+  return {
+    load: () => {
+      const raw = storage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw) as { v?: number; messages?: ChatMessage[] };
+      return parsed.v === version && Array.isArray(parsed.messages) ? parsed.messages : null;
+    },
+    save: (messages) => {
+      
+      const kept = Transcript.sanitize(messages.slice(-cap)).map(withoutContent);
+      storage.setItem(key, JSON.stringify({ v: version, messages: kept }));
+    },
+    clear: () => {
+      storage.removeItem(key);
+    },
+  };
+};