akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/window-state/src/state.ts

@@ -0,0 +1,146 @@
+
+import type { SavedWindowState } from "./index.ts";
+
+/** The part of window.getState this plugin reads. */
+export interface WindowSnapshot {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  maximized: boolean;
+  minimized: boolean;
+  fullscreen: boolean;
+  visible: boolean;
+}
+
+const FORMAT = 1;
+/** Anything outside these bounds is a corrupt file, not a window. */
+const LIMIT = 1_000_000;
+
+const finite = (v: unknown, min: number): v is number =>
+  typeof v === "number" && Number.isFinite(v) && v >= min && v <= LIMIT;
+
+/** The saved file's contents, or null when it is missing, corrupt or from another format version. */
+export function parseSaved(text: string | null): SavedWindowState | null {
+  if (!text) return null;
+  let v: Record<string, unknown>;
+  try {
+    v = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!v || typeof v !== "object" || v.format !== FORMAT) return null;
+  const { x, y, width, height, maximized } = v;
+  if (
+    !finite(x, -LIMIT) ||
+    !finite(y, -LIMIT) ||
+    !finite(width, 1) ||
+    !finite(height, 1) ||
+    typeof maximized !== "boolean"
+  )
+    return null;
+  return { x, y, width, height, maximized };
+}
+
+export function serialize(state: SavedWindowState): string {
+  const { x, y, width, height, maximized } = state;
+  return `${JSON.stringify({ format: FORMAT, x, y, width, height, maximized })}\n`;
+}
+
+/**
+ * The state to save after `snap`. Only a normal window says where it is; a maximized one only
+ * flips the flag, so un-maximizing after a restart returns to the last normal bounds (Tauri
+ * window-state keeps prev_x/prev_y for the same reason). Minimized, hidden or full-screen
+ * windows change nothing.
+ */
+export function nextState(prev: SavedWindowState | null, snap: WindowSnapshot): SavedWindowState | null {
+  if (snap.minimized || !snap.visible || snap.fullscreen) return prev;
+  if (!(snap.width >= 1 && snap.height >= 1)) return prev;
+  if (snap.maximized) {
+    
+    return prev
+      ? { ...prev, maximized: true }
+      : { x: snap.x, y: snap.y, width: snap.width, height: snap.height, maximized: true };
+  }
+  return { x: snap.x, y: snap.y, width: snap.width, height: snap.height, maximized: false };
+}
+
+const same = (a: SavedWindowState | null, b: SavedWindowState | null) =>
+  a === b ||
+  (!!a &&
+    !!b &&
+    a.x === b.x &&
+    a.y === b.y &&
+    a.width === b.width &&
+    a.height === b.height &&
+    a.maximized === b.maximized);
+
+export interface Tracker {
+  readonly saved: SavedWindowState | null;
+  /** A move or resize happened: capture once things settle. */
+  changed(): void;
+  /** Captures now (and waits for a capture in flight). */
+  flush(): Promise<SavedWindowState | null>;
+  /** Forgets the saved state; the next capture starts over. */
+  clear(): void;
+  stop(): void;
+}
+
+export function createTracker(options: {
+  initial: SavedWindowState | null;
+  read(): Promise<WindowSnapshot>;
+  write(state: SavedWindowState): void;
+  /** Debounce for move/resize bursts, ms. Also lets the maximize animation finish. */
+  delay?: number;
+}): Tracker {
+  const delay = options.delay ?? 400;
+  let saved = options.initial;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let chain: Promise<SavedWindowState | null> = Promise.resolve(saved);
+
+  const capture = async (): Promise<SavedWindowState | null> => {
+    let snap: WindowSnapshot;
+    try {
+      snap = await options.read();
+    } catch {
+      return saved; 
+    }
+    const next = nextState(saved, snap);
+    if (next && !same(next, saved)) {
+      saved = next;
+      try {
+        options.write(next);
+      } catch (error) {
+        console.error("[akan-native] window-state: saving failed", error);
+      }
+    }
+    return saved;
+  };
+  const enqueue = () => (chain = chain.then(capture, capture));
+  const cancel = () => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  return {
+    get saved() {
+      return saved;
+    },
+    changed() {
+      cancel();
+      timer = setTimeout(() => {
+        timer = undefined;
+        void enqueue();
+      }, delay);
+    },
+    flush() {
+      cancel();
+      return enqueue();
+    },
+    clear() {
+      cancel();
+      saved = null;
+    },
+    stop: cancel,
+  };
+}

package/vendor/use-agentic/AgentProgress.ts

@@ -1,8 +1,20 @@
+export interface AgentProgressStep {
+  id: string;
+  label: string;
+  status: "pending" | "running" | "done" | "error";
+  detail?: string;
+}
+
 export interface AgentProgressReport {
   /** One short line about the step in flight. Read by the user, not the model — keep it prose. */
   message: string;
   done?: number;
   total?: number;
+  /**
+   * The activity of work running somewhere else — a server job, a code worker — that this one call is waiting on.
+   * Each report replaces the list whole, so a relay forwards what it has and never merges.
+   */
+  steps?: AgentProgressStep[];
 }
 
 /**
@@ -19,7 +31,7 @@ export interface AgentProgressReport {
 export class AgentProgress {
   static #sink: ((report: AgentProgressReport) => void) | null = null;
 
-  static report(message: string, amount: { done?: number; total?: number } = {}) {
+  static report(message: string, amount: { done?: number; total?: number; steps?: AgentProgressStep[] } = {}) {
     AgentProgress.#sink?.({ message, ...amount });
   }
 

package/vendor/use-agentic/AgentSession.ts

@@ -1,18 +1,24 @@
 import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
+import { Reference } from "./Reference";
 import { ToolOutput } from "./ToolOutput";
-import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
+import { type ToolApprovalRequest, type ToolCardAnswer, type ToolCardRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
 import type {
   AgentRunner,
   ChatMessage,
   ContextBlock,
+  MessageReference,
   PublishedTool,
   RunnerRequest,
   SurfaceView,
+  ToolActivity,
   ToolCallRequest,
   ToolCallResult,
+  ToolCard,
+  TurnLimits,
   TurnStop,
+  TurnUsage,
 } from "./types";
 
 export interface PendingApproval {
@@ -37,6 +43,20 @@ export interface PendingQuestion {
   dismiss: (reason?: string) => void;
 }
 
+/**
+ * A call parked on a component the app declared with the tool — a form to fill in, a choice no list of strings
+ * could carry. The loop waits on it exactly as it waits on an approval, and `render` is the app's own, so the
+ * framework decides where the card sits and nothing about what it asks.
+ */
+export interface PendingCard {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  render: ToolCard;
+  submit: (value: unknown) => void;
+  dismiss: (reason?: string) => void;
+}
+
 /**
  * Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it, so a
  * server-side transcript is as legal as web storage — which is why every method may answer asynchronously. A
@@ -90,6 +110,21 @@ export interface AgentSessionOptions {
    * duplicate, no error, just messages that never reach the server. Reset the mark here.
    */
   onCompact?: (replaced: readonly ChatMessage[], summary: ChatMessage) => void;
+  /**
+   * Called as each tool call starts and ends — where a host draws what the agent is doing on the page itself.
+   * The session keeps none of it: nothing here is transcript, and holding it would mean a re-render per call for
+   * something no message renders.
+   */
+  onActivity?: (event: ToolActivity) => void | Promise<void>;
+  /**
+   * Called when a turn starts and when it settles — the boundary a host draws the agent's own presence in. The
+   * calls of one turn arrive with model turns between them, seconds long, so anything measured in the gap
+   * between *calls* keeps ending and restarting inside a turn that never stopped.
+   *
+   * Only the conversation loop reports here. `compact` runs under the same flag and drives nothing on screen, so
+   * a host drawing the agent at work would draw it for a summary nobody asked to watch.
+   */
+  onTurn?: (running: boolean) => void;
 }
 
 /**
@@ -132,6 +167,10 @@ export class AgentSession {
   #running = false;
   #pending: PendingApproval | null = null;
   #question: PendingQuestion | null = null;
+  #card: PendingCard | null = null;
+  #staged: MessageReference[] = [];
+  #inserts: MessageReference[] = [];
+  #chats = 0;
   #progress: (AgentProgressReport & { callId: string }) | null = null;
   #controller: AbortController | null = null;
   #active: Promise<void> | null = null;
@@ -144,8 +183,15 @@ export class AgentSession {
   #history: SessionHistory | undefined;
   #onCompact: AgentSessionOptions["onCompact"];
   #compacting = false;
-  /** Size below which auto-compaction stays out of the way, raised when a summary failed to shrink anything. */
-  #compactFloor = 0;
+  /**
+   * Sizes below which auto-compaction stays out of the way, raised when a summary failed to shrink anything — one
+   * per trigger, since the ceiling reads the transcript and the guard the whole prompt.
+   */
+  #compactFloor = { transcript: 0, prompt: 0 };
+  /** What the backend reported about its model, or what a refusal named — kept for the life of the session. */
+  #limits: TurnLimits = {};
+  /** What the tools, the screen context and the instructions cost the last request, for a host's gauge. */
+  #overhead = 0;
 
   constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
     this.#surface = surface;
@@ -153,7 +199,9 @@ export class AgentSession {
     this.#options = options;
     this.#tools = new ToolRunner(surface, {
       approve: (request, signal) => this.#awaitApproval(request, signal),
+      card: (request, signal) => this.#awaitCard(request, signal),
       settle: () => this.#options.settle?.(),
+      activity: (event) => this.#options.onActivity?.(event),
       progress: ({ callId, report }) => {
         if (report) this.#progress = { ...report, callId };
         else if (this.#progress?.callId === callId) this.#progress = null;
@@ -212,6 +260,121 @@ export class AgentSession {
     return this.#question;
   }
 
+  get pendingCard(): PendingCard | null {
+    return this.#card;
+  }
+
+  /**
+   * What the user has pointed at and not yet sent.
+   *
+   * Held by the session rather than by the composer, which is where staged *files* live — and the difference is
+   * not an inconsistency. A file only ever arrives from the composer's own picker or drop zone, so composer-local
+   * state can reach every producer of one. A reference arrives from whichever component drew the data: a card
+   * partway down the page, reaching the session it is already inside. Composer state is unreachable from there,
+   * and a chat that replaces its composer has no state to reach anyway.
+   *
+   * A staging slot, not a tray. `send` empties it, so what somebody pointed at belongs to the message they were
+   * writing and never leaks into the next one.
+   */
+  get staged(): readonly MessageReference[] {
+    return this.#staged;
+  }
+
+  /**
+   * Pointing at the same field twice replaces it: the newer value is the one they meant, and one chip is honest.
+   *
+   * Stages the value only. The caller is the composer's own `@` menu, which is already writing the token as the
+   * user picks — `refer` is the entry point for everything that is not the composer.
+   */
+  stage = (reference: MessageReference) => {
+    this.#stage(Reference.clipped(reference));
+    this.#announce();
+  };
+
+  /**
+   * Points at something from a component that is not the composer — a card the user clicked beside the data.
+   *
+   * Two halves, because the composer owns one of them: the value is staged here, and the token the message needs
+   * is left for whichever chat is rendering this session's draft to write. That is why nothing is queued when no
+   * chat is: the value would sit staged with no token anywhere naming it, and the message text is what decides
+   * which references a turn carries — so the user would press a button and watch nothing happen, which is the
+   * failure this warns about instead.
+   */
+  refer = (reference: MessageReference) => {
+    const clipped = Reference.clipped(reference);
+    this.#stage(clipped);
+    if (this.#chats) this.#inserts = [...this.#inserts.filter((one) => !Reference.same(one, clipped)), clipped];
+    else
+      console.warn(
+        `No chat is rendering this agent session, so "${clipped.label}" was staged with no token written for it. ` +
+          "The component calling this and an <Agent.Chat /> have to share one session — check which <Agent.Zone> " +
+          "each of them is inside.",
+      );
+    this.#announce();
+  };
+
+  /**
+   * Tokens a chat has not written into its draft yet. State rather than a queue somebody drains, for the reason
+   * `pendingApproval` is state: two chats may be mounted on one session — a responsive app renders a desktop and
+   * a mobile composer and hides one in CSS — and each holds its own draft, so each has to write the token. A
+   * destructive read would hand it to whichever rendered first and leave the other silently without it.
+   */
+  get pendingInserts(): readonly MessageReference[] {
+    return this.#inserts;
+  }
+
+  /** Idempotent by key: the second chat to apply the same insert is acknowledging one that is already gone. */
+  insertApplied = (key: string) => {
+    const next = this.#inserts.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#inserts.length) return;
+    this.#inserts = next;
+    this.#announce();
+  };
+
+  /**
+   * Stages references back from a message that was parked behind a running turn. What was pointed at since wins:
+   * the parked value is the older read of the same field, and letting it land would undo an edit made in between.
+   * No token is written — the parked text carries them already, and the composer is putting that text back.
+   */
+  restoreStaged = (references: readonly MessageReference[]) => {
+    const fresh = references.filter((one) => !this.#staged.some((held) => Reference.same(held, one)));
+    if (!fresh.length) return;
+    this.#staged = [...fresh.map((one) => Reference.clipped(one)), ...this.#staged];
+    this.#announce();
+  };
+
+  /**
+   * Registered by a chat for as long as it is rendering this session's draft, so `refer` can tell the difference
+   * between a token nobody has written yet and one nobody ever will.
+   */
+  attachChat = () => {
+    this.#chats += 1;
+    return () => {
+      this.#chats = Math.max(0, this.#chats - 1);
+    };
+  };
+
+  #stage(clipped: MessageReference) {
+    const at = this.#staged.findIndex((one) => Reference.same(one, clipped));
+    this.#staged =
+      at === -1 ? [...this.#staged, clipped] : this.#staged.map((one, idx) => (idx === at ? clipped : one));
+  }
+
+  /** By key, never by index: what orders the references of a message is its text, and that is not this list. */
+  unstage = (key: string) => {
+    const next = this.#staged.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#staged.length) return;
+    this.#staged = next;
+    this.#announce();
+  };
+
+  clearStaged = () => {
+    if (!this.#staged.length && !this.#inserts.length) return;
+    this.#staged = [];
+    this.#inserts = [];
+    this.#announce();
+  };
+
   /** What the tool running now last said about its own progress, for the row that is still spinning. */
   get progress(): (AgentProgressReport & { callId: string }) | null {
     return this.#progress;
@@ -241,11 +404,13 @@ export class AgentSession {
   async #turn(input: string | ChatMessage[]) {
     const controller = new AbortController();
     this.#controller = controller;
+    this.#options.onTurn?.(true);
     if (typeof input === "string") this.#append({ role: "user", text: input });
     else for (const message of input) this.#append(message);
     const maxTurns = this.#options.maxTurns ?? 12;
     try {
       let budget = maxTurns;
+      let recovered = false;
       for (let turn = 0; ; turn += 1) {
         if (controller.signal.aborted) return;
         if (turn >= budget) {
@@ -259,12 +424,20 @@ export class AgentSession {
           budget = turn + maxTurns;
         }
         await this.#autoCompact(controller.signal);
-        const { toolCalls, stop } = await this.#assistantTurn(controller.signal);
+        const { toolCalls, stop, overflow } = await this.#assistantTurn(controller.signal);
 
         if (controller.signal.aborted) {
           this.#unanswered(toolCalls);
           return;
         }
+        if (overflow) {
+          if (recovered || !(await this.#recover(overflow, controller.signal))) {
+            if (!controller.signal.aborted) this.#fail(overflow.message);
+            return;
+          }
+          recovered = true;
+          continue;
+        }
 
         if (stop === "length") {
 
@@ -292,7 +465,12 @@ export class AgentSession {
       this.#active = null;
       this.#pending = null;
       this.#question = null;
+      this.#card = null;
       this.#progress = null;
+
+      const draft = this.#messages[this.#messages.length - 1];
+      if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+      this.#options.onTurn?.(false);
       this.#notify();
     }
   }
@@ -312,7 +490,9 @@ export class AgentSession {
       await this.#active;
     }
     this.#messages = [];
-    this.#compactFloor = 0;
+    this.#staged = [];
+    this.#inserts = [];
+    this.#compactFloor = { transcript: 0, prompt: 0 };
     
     if (this.#saveTimer) {
       clearTimeout(this.#saveTimer);
@@ -411,11 +591,28 @@ export class AgentSession {
     }
   };
 
-  /** What the transcript is estimated to cost the next turn, in tokens — the number auto-compaction watches. */
+  /** What the transcript is estimated to cost the next turn, in tokens — the number the `at` ceiling watches. */
   get tokens() {
     return Compaction.tokensOf(this.#messages);
   }
 
+  /**
+   * How close the conversation is to summarizing itself, measured against whichever trigger is nearer: the `at`
+   * ceiling over the transcript, or the window guard over the whole prompt once the backend has reported its
+   * window. Each pair is in its own unit, which is why only the nearer one is answered. No `compactAt` means
+   * nothing will compact it.
+   */
+  get context(): { used: number; compactAt?: number } {
+    const { at, buffer } = this.#compactOptions;
+    const prompt = Compaction.promptTokensOf(this.#messages, () => this.#overhead);
+    if (!at) return { used: prompt };
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const ceiling = Number.isFinite(at) ? { used: Compaction.tokensOf(this.#messages), compactAt: at } : null;
+    const window = Number.isFinite(guard) ? { used: prompt, compactAt: guard } : null;
+    if (ceiling && window) return ceiling.used / ceiling.compactAt >= window.used / window.compactAt ? ceiling : window;
+    return ceiling ?? window ?? { used: prompt };
+  }
+
   /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
   report = (error: string) => {
     this.#append({ role: "assistant", error });
@@ -436,7 +633,7 @@ export class AgentSession {
       if (!summary || signal.aborted) return false;
       const replaced = this.#messages.slice(0, at);
       const message = Compaction.message(summary);
-      this.#messages = [message, ...this.#messages.slice(at)];
+      this.#messages = [message, ...this.#messages.slice(at).map(Transcript.unmeasured)];
       try {
         this.#onCompact?.(replaced, message);
       } catch {
@@ -450,13 +647,21 @@ export class AgentSession {
 
   /**
    * Runs before the turn that would have overflowed rather than after it fails: the provider answers a request
-   * that is too long with a refusal, not with a shorter answer, so there is nothing to recover from afterwards.
-   * Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes out as
-   * it would have, since it may well still fit.
+   * that is too long with a refusal, not with a shorter answer, so waiting for one costs a round trip that was
+   * refused. Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes
+   * out as it would have, since it may well still fit.
    */
   async #autoCompact(signal: AbortSignal) {
-    const { at = Compaction.defaults.at, keep = Compaction.defaults.keep } = this.#options.compact ?? {};
-    if (!at || Compaction.tokensOf(this.#messages) < Math.max(at, this.#compactFloor)) return;
+    const { at, keep, buffer } = this.#compactOptions;
+    if (!at) return;
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const measure = () => ({
+      transcript: Compaction.tokensOf(this.#messages),
+      prompt: Compaction.promptTokensOf(this.#messages, () => AgentSession.#tokensOfFrame(this.#frame())),
+    });
+    const before = measure();
+    const floor = this.#compactFloor;
+    if (before.transcript < Math.max(at, floor.transcript) && before.prompt <= Math.max(guard, floor.prompt)) return;
     let compacted = false;
     try {
       compacted = await this.#compact(keep, signal);
@@ -465,9 +670,57 @@ export class AgentSession {
       console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
       return;
     }
-    const after = Compaction.tokensOf(this.#messages);
+    const after = measure();
 
-    this.#compactFloor = compacted && after >= at ? after + at : 0;
+    this.#compactFloor = {
+      transcript: compacted && after.transcript >= at ? after.transcript + at : 0,
+      prompt: compacted && after.prompt > guard ? after.prompt + buffer : 0,
+    };
+  }
+
+  /**
+   * Answers a refusal for length the one way a session can: compact, and ask again. Once per send — a transcript
+   * refused again after its own summary is not one another summary will fit — and never where the host turned
+   * automatic compaction off, since that host keeps the window itself.
+   */
+  async #recover(overflow: { limit?: number }, signal: AbortSignal): Promise<boolean> {
+    if (overflow.limit) this.#limits = { ...this.#limits, window: overflow.limit };
+    const { at, keep } = this.#compactOptions;
+    if (!at) return false;
+    const draft = this.#messages[this.#messages.length - 1];
+    if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+    try {
+      return await this.#compact(keep, signal);
+    } catch (error) {
+      console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  get #compactOptions() {
+    const {
+      at = Compaction.defaults.at,
+      keep = Compaction.defaults.keep,
+      buffer = Compaction.defaults.buffer,
+    } = this.#options.compact ?? {};
+    return { at, keep, buffer };
+  }
+
+  /** What rides every turn beside the transcript. Read per turn, because the screen it describes moves. */
+  #frame(): Omit<RunnerRequest, "messages" | "signal"> {
+    const { tools, guides } = this.#surface.snapshot();
+    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
+    return {
+      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
+        ? tools
+        : [...tools, AgentSession.askUserTool],
+      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
+      ...(instructions ? { instructions } : {}),
+    };
+  }
+
+  static #tokensOfFrame(frame: Omit<RunnerRequest, "messages" | "signal">): number {
+    return Math.ceil(JSON.stringify(frame).length / 4);
   }
 
   /** No tools and no screen context: this turn summarizes the conversation, and must not act on it. */
@@ -488,32 +741,33 @@ export class AgentSession {
     return text;
   }
 
-  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop }> {
-    const { tools, guides } = this.#surface.snapshot();
-    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
-    const request: RunnerRequest = {
-      messages: Transcript.wire(this.#messages),
-      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
-        ? tools
-        : [...tools, AgentSession.askUserTool],
-      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
-      ...(instructions ? { instructions } : {}),
-      signal,
-    };
+  async #assistantTurn(
+    signal: AbortSignal,
+  ): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop; overflow?: { message: string; limit?: number } }> {
+    const frame = this.#frame();
+    this.#overhead = AgentSession.#tokensOfFrame(frame);
+    const request: RunnerRequest = { messages: Transcript.wire(this.#messages), ...frame, signal };
     this.#append({ role: "assistant" });
     let text = "";
     const toolCalls: ToolCallRequest[] = [];
     let stop: TurnStop = "end";
+    let usage: TurnUsage | undefined;
     for await (const event of this.#runner.run(request)) {
       if (signal.aborted) break;
       if (event.type === "text") {
         text += event.delta;
         this.#patchLast({ text });
       } else if (event.type === "toolCall") toolCalls.push({ id: event.id, name: event.name, args: event.args });
-      else if (event.type === "done") stop = event.stop;
+      else if (event.type === "done") {
+        stop = event.stop;
+        usage = event.usage;
+        if (event.limits) this.#limits = { ...this.#limits, ...event.limits };
+      } else if (event.overflow)
+        return { toolCalls: [], stop: "end", overflow: { message: event.message, limit: event.overflow.limit } };
       else throw new Error(event.message);
     }
-    if (toolCalls.length) this.#patchLast({ toolCalls });
+    if (toolCalls.length || usage)
+      this.#patchLast({ ...(toolCalls.length ? { toolCalls } : {}), ...(usage ? { usage } : {}) });
     return { toolCalls, stop };
   }
 
@@ -572,6 +826,28 @@ export class AgentSession {
     });
   }
 
+  #awaitCard(request: ToolCardRequest, signal: AbortSignal): Promise<ToolCardAnswer> {
+    return new Promise((resolve) => {
+      const settle = (answer: ToolCardAnswer) => {
+        this.#card = null;
+        signal.removeEventListener("abort", onAbort);
+        this.#notify();
+        resolve(answer);
+      };
+      const onAbort = () => settle({ error: "The user aborted the turn." });
+      signal.addEventListener("abort", onAbort);
+      this.#card = {
+        callId: request.callId,
+        name: request.name,
+        args: request.args,
+        render: request.render,
+        submit: (value) => settle({ result: value }),
+        dismiss: (reason) => settle({ error: reason ?? "The user closed the card without filling it in." }),
+      };
+      this.#notify();
+    });
+  }
+
   #awaitApproval(request: ToolApprovalRequest, signal: AbortSignal): Promise<true | string> {
     return new Promise((resolve) => {
       const settle = (value: true | string) => {
@@ -628,9 +904,17 @@ export class AgentSession {
   }
 
   #notify() {
+    this.#announce();
+    this.#schedulePersist();
+  }
+
+  /**
+   * A change that is not the transcript's. Staged references live beside the messages rather than in them, so
+   * announcing one has to redraw the composer without scheduling a save of messages nothing touched.
+   */
+  #announce() {
     this.#version += 1;
     for (const listener of this.#listeners) listener();
-    this.#schedulePersist();
   }
 
   /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */

package/vendor/use-agentic/AgenticSurface.ts

@@ -183,6 +183,8 @@ export class AgenticSurface {
     try {
       const verdict = entry.guard?.(args) ?? true;
       if (verdict !== true) throw new Error(verdict);
+      
+      if (!entry.run) throw new Error(`${name} is answered by the user, and this caller cannot ask them.`);
       return await entry.run(args);
     } catch (error) {
       record.error = error instanceof Error ? error.message : String(error);