akanjs 3.0.0-beta.3 → 3.0.0-beta.30

package/vendor/use-agentic/AgenticSurface.ts

@@ -1,3 +1,4 @@
+import { AgentGate } from "./AgentGate";
 import type {
   AgentCall,
   PublishedResource,
@@ -13,6 +14,11 @@ import type {
 
 const SHARED_KEY = Symbol.for("useAgentic.sharedSurface");
 
+interface Registration<E> {
+  entry: E;
+  gate: AgentGate | null;
+}
+
 /**
  * The live registry of what the mounted screen offers an agent: tools, readable resources, and scopes.
  *
@@ -41,10 +47,10 @@ export class AgenticSurface {
     return [...scope.map((part) => AgenticSurface.sanitize(part)), AgenticSurface.sanitize(name)].join(".");
   }
 
-  #tools = new Map<string, ToolEntry[]>();
-  #resources = new Map<string, ResourceEntry[]>();
-  #scopes = new Map<string, ScopeEntry[]>();
-  #guides: { scope: string; text: string }[] = [];
+  #tools = new Map<string, Registration<ToolEntry>[]>();
+  #resources = new Map<string, Registration<ResourceEntry>[]>();
+  #scopes = new Map<string, Registration<ScopeEntry>[]>();
+  #guides: { scope: string; text: string; gate: AgentGate | null }[] = [];
   readonly #calls: AgentCall[] = [];
   #sources = new Set<SurfaceSource>();
   #listeners = new Set<() => void>();
@@ -62,34 +68,37 @@ export class AgenticSurface {
    * argument rather than closing over it: every registration is then interchangeable and last-wins picks an
    * equivalent one. The description is what says so — two registrations that describe the same action to a model
    * are the same declaration twice, and fifty rows are one entry rather than fifty collisions. Two that describe
-   * different actions under one name are a real clash whichever of them mounted last, and warn.
+   * different actions under one name are a real clash whichever of them mounted last, and warn. A clash needs both
+   * published at once, so a registration behind a parked gate, or over only parked ones, never warns.
    */
-  registerTool(scope: string[], entry: ToolEntry) {
+  registerTool(scope: string[], entry: ToolEntry, gate: AgentGate | null = null) {
     const key = AgenticSurface.fullName(scope, entry.name);
-    const stack = this.#tools.get(key);
-    const interchangeable = !stack?.length || stack[stack.length - 1].description === entry.description;
+    const shown = AgenticSurface.#shown(this.#tools.get(key));
+    const clashes = !!shown && AgenticSurface.#isActive(gate) && shown.description !== entry.description;
     return this.#stack(
       this.#tools,
       key,
-      entry,
-      interchangeable ? null : "is registered by two declarations that describe it differently",
+      { entry, gate },
+      clashes ? "is registered by two declarations that describe it differently" : null,
     );
   }
 
-  registerResource(scope: string[], entry: ResourceEntry) {
-    return this.#stack(this.#resources, AgenticSurface.fullName(scope, entry.name), entry);
+  registerResource(scope: string[], entry: ResourceEntry, gate: AgentGate | null = null) {
+    const key = AgenticSurface.fullName(scope, entry.name);
+    return this.#stack(this.#resources, key, { entry, gate }, this.#duplicate(this.#resources, key, gate));
   }
 
-  openScope(parent: string[], scope: ScopeEntry) {
-    return this.#stack(this.#scopes, AgenticSurface.childPath(parent, scope.id).join("."), scope);
+  openScope(parent: string[], scope: ScopeEntry, gate: AgentGate | null = null) {
+    const key = AgenticSurface.childPath(parent, scope.id).join(".");
+    return this.#stack(this.#scopes, key, { entry: scope, gate }, this.#duplicate(this.#scopes, key, gate));
   }
 
   /**
    * Standing guidance for the agent while the registrant is mounted — instructions, not context data. Kept in
    * registration order rather than sorted: guides are prose, and each one must stay a coherent block.
    */
-  registerGuide(scope: string[], text: string) {
-    const entry = { scope: scope.join("."), text };
+  registerGuide(scope: string[], text: string, gate: AgentGate | null = null) {
+    const entry = { scope: scope.join("."), text, gate };
     this.#guides.push(entry);
     this.#notify();
     return () => {
@@ -110,6 +119,36 @@ export class AgenticSurface {
     };
   }
 
+  /** A gate whose every flip re-publishes this surface. Under `parent`, it is active only while the parent is. */
+  gate(active: boolean, parent: AgentGate | null = null) {
+    return new AgentGate(active, () => this.#notify(), parent);
+  }
+
+  /**
+   * This surface for a subtree behind `gate`: what registers through it is published only while the gate is active,
+   * and every other call reaches this surface untouched. A proxy rather than a wrapper class, so a method added to the
+   * surface later is forwarded instead of missing.
+   */
+  gated(gate: AgentGate): AgenticSurface {
+    const registrations: Partial<Record<PropertyKey, unknown>> = {
+      registerTool: (scope: string[], entry: ToolEntry) => this.registerTool(scope, entry, gate),
+      registerResource: (scope: string[], entry: ResourceEntry) => this.registerResource(scope, entry, gate),
+      openScope: (parent: string[], scope: ScopeEntry) => this.openScope(parent, scope, gate),
+      registerGuide: (scope: string[], text: string) => this.registerGuide(scope, text, gate),
+    };
+    
+    const bound = new Map<PropertyKey, unknown>();
+    return new Proxy(this, {
+      get: (target, key) => {
+        if (Object.hasOwn(registrations, key)) return registrations[key];
+        const value = Reflect.get(target, key, target);
+        if (typeof value !== "function") return value;
+        if (!bound.has(key)) bound.set(key, value.bind(target));
+        return bound.get(key);
+      },
+    });
+  }
+
   snapshot(view: string[] = []): SurfaceSnapshot {
     const viewKey = view.join(".");
     const tools = [...this.#activeTools(view)].map(([name, entry]) => AgenticSurface.#publishTool(name, entry));
@@ -118,16 +157,19 @@ export class AgenticSurface {
     );
     const scopes = [...this.#scopes.entries()]
       .filter(([path]) => AgenticSurface.#within(viewKey, path))
-      .map(([path, stack]) => {
-        const scope = stack[stack.length - 1];
-        return { path, ...(scope.label ? { label: scope.label } : {}), ...(scope.kind ? { kind: scope.kind } : {}) };
+      .flatMap(([path, stack]) => {
+        const scope = AgenticSurface.#shown(stack);
+        if (!scope) return [];
+        return [{ path, ...(scope.label ? { label: scope.label } : {}), ...(scope.kind ? { kind: scope.kind } : {}) }];
       });
     
     return {
       tools: tools.sort((a, b) => (a.name < b.name ? -1 : 1)),
       resources: resources.sort((a, b) => (a.name < b.name ? -1 : 1)),
       scopes: scopes.sort((a, b) => (a.path < b.path ? -1 : 1)),
-      guides: this.#guides.filter((guide) => AgenticSurface.#guideApplies(viewKey, guide.scope)).map((g) => g.text),
+      guides: this.#guides
+        .filter((guide) => AgenticSurface.#isActive(guide.gate) && AgenticSurface.#guideApplies(viewKey, guide.scope))
+        .map((g) => g.text),
     };
   }
 
@@ -150,8 +192,8 @@ export class AgenticSurface {
 
   tool(name: string, view: string[] = []): ToolEntry | null {
     const viewKey = view.join(".");
-    const stack = this.#tools.get(name);
-    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    const shown = AgenticSurface.#shown(this.#tools.get(name));
+    if (shown && AgenticSurface.#within(viewKey, name)) return shown;
     for (const source of this.#sources) {
       const found = source.tools?.(view).find((candidate) => candidate.name === name);
       if (found) return found;
@@ -164,8 +206,7 @@ export class AgenticSurface {
    * what lets a host drop the built-in tools without dropping a screen's own tool that deliberately shadows one.
    */
   declares(name: string, view: string[] = []): boolean {
-    const stack = this.#tools.get(name);
-    return !!stack?.length && AgenticSurface.#within(view.join("."), name);
+    return !!AgenticSurface.#shown(this.#tools.get(name)) && AgenticSurface.#within(view.join("."), name);
   }
 
   /** Every call made through this surface, oldest first. What the dock shows the user to check against the screen. */
@@ -183,6 +224,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);
@@ -231,9 +274,10 @@ export class AgenticSurface {
     const viewKey = view.join(".");
     const seen = new Set<string>();
     for (const [name, stack] of this.#tools) {
-      if (!AgenticSurface.#within(viewKey, name)) continue;
+      const shown = AgenticSurface.#shown(stack);
+      if (!shown || !AgenticSurface.#within(viewKey, name)) continue;
       seen.add(name);
-      yield [name, stack[stack.length - 1]];
+      yield [name, shown];
     }
     for (const source of this.#sources) {
       for (const entry of source.tools?.(view) ?? []) {
@@ -248,9 +292,10 @@ export class AgenticSurface {
     const viewKey = view.join(".");
     const seen = new Set<string>();
     for (const [name, stack] of this.#resources) {
-      if (!AgenticSurface.#within(viewKey, name)) continue;
+      const shown = AgenticSurface.#shown(stack);
+      if (!shown || !AgenticSurface.#within(viewKey, name)) continue;
       seen.add(name);
-      yield [name, stack[stack.length - 1]];
+      yield [name, shown];
     }
     for (const source of this.#sources) {
       for (const entry of source.resources?.(view) ?? []) {
@@ -263,8 +308,8 @@ export class AgenticSurface {
 
   #resource(name: string, view: string[] = []): ResourceEntry | null {
     const viewKey = view.join(".");
-    const stack = this.#resources.get(name);
-    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    const shown = AgenticSurface.#shown(this.#resources.get(name));
+    if (shown && AgenticSurface.#within(viewKey, name)) return shown;
     for (const source of this.#sources) {
       const found = source.resources?.(view).find((candidate) => candidate.name === name);
       if (found) return found;
@@ -283,23 +328,38 @@ export class AgenticSurface {
     return viewKey.startsWith(`${scopeKey}.`) || scopeKey.startsWith(`${viewKey}.`);
   }
 
-  #stack<E>(map: Map<string, E[]>, key: string, entry: E, clash: string | null = "is registered more than once") {
+  #duplicate<E>(map: Map<string, Registration<E>[]>, key: string, gate: AgentGate | null) {
+    return AgenticSurface.#shown(map.get(key)) && AgenticSurface.#isActive(gate)
+      ? "is registered more than once"
+      : null;
+  }
+
+  #stack<E>(map: Map<string, Registration<E>[]>, key: string, registration: Registration<E>, clash: string | null) {
     const stack = map.get(key) ?? [];
-    if (stack.length && clash && !this.#warned.has(key)) {
+    if (clash && !this.#warned.has(key)) {
       this.#warned.add(key);
       console.warn(`[use-agentic] "${key}" ${clash}; the newest registration wins.`);
     }
-    stack.push(entry);
+    stack.push(registration);
     map.set(key, stack);
     this.#notify();
     return () => {
-      const idx = stack.indexOf(entry);
+      const idx = stack.indexOf(registration);
       if (idx >= 0) stack.splice(idx, 1);
       if (!stack.length) map.delete(key);
       this.#notify();
     };
   }
 
+  /** The newest registration whose gate is active: a parked subtree keeps its place without shadowing anything. */
+  static #shown<E>(stack: Registration<E>[] | undefined): E | undefined {
+    return stack?.findLast((registration) => AgenticSurface.#isActive(registration.gate))?.entry;
+  }
+
+  static #isActive(gate: AgentGate | null) {
+    return gate?.active ?? true;
+  }
+
   #notify() {
     for (const listener of this.#listeners) listener();
   }

package/vendor/use-agentic/Compaction.ts

@@ -1,10 +1,20 @@
-import type { ChatMessage } from "./types";
+import type { ChatMessage, MessageAttachment, TurnLimits } from "./types";
 
 export interface CompactOptions {
-  /** Estimated transcript tokens above which a turn summarizes its own history first. `0` never compacts. */
+  /**
+   * Estimated transcript tokens above which a turn summarizes its own history first — a ceiling on what each turn
+   * costs, apart from the window guard. `Infinity` leaves only the guard; `0` turns automatic compaction off
+   * altogether, the guard and the recovery from a refusal included.
+   */
   at?: number;
   /** Messages left verbatim below the summary. The cut slides down to the first message that can safely open one. */
   keep?: number;
+  /**
+   * Tokens held free below the model's window on top of its answer ceiling, once the backend has reported the
+   * window. It covers what the estimate cannot see: what arrived after the provider last counted, and a screen
+   * that changed since.
+   */
+  buffer?: number;
   /** Produces the summary from the digest. Default: one tool-less turn through the session's own runner. */
   summarize?: (digest: string, signal: AbortSignal) => Promise<string>;
 }
@@ -16,14 +26,27 @@ export interface CompactOptions {
  */
 export class Compaction {
   /**
-   * Deliberately well under the smallest window a provider is likely to have: what a conversation loses to an
-   * early summary is detail, and what it loses to a late one is the conversation. The tools, the screen context
-   * and the system prompt ride on top of the transcript on every turn, and none of them is compactable.
+   * `at` is a ceiling on cost rather than on the window. The relay holds no session, so every turn resends the
+   * whole transcript and the app pays for each one — a chat left to fill a million-token window prefills most of
+   * a million tokens per answer. The window is guarded on its own once the backend reports it, and `buffer` is the
+   * margin that guard holds back: 13k, the one Claude Code leaves below its own threshold.
+   */
+  static readonly defaults = { at: 24_000, keep: 6, buffer: 13_000 };
+
+  /** The answer ceiling assumed when the backend did not report one — the one most relays request when they do. */
+  static readonly answerTokens = 8_192;
+
+  /**
+   * What one inlined picture costs a turn. A provider bills a picture by its pixels after its own downscale, not by
+   * its bytes — Anthropic lands near 1,600 tokens and OpenAI's high-detail tiles under that — so counted as base64
+   * a 300KB screenshot reads as 100k tokens and compacts itself out of the very task it was attached to.
    */
-  static readonly defaults = { at: 24_000, keep: 6 };
+  static readonly imageTokens = 1_600;
 
   static readonly instruction =
     "Summarize the conversation below so you can carry it on with the summary in place of the messages themselves. " +
+    "If it opens with a previous summary, carry forward everything in it that still matters: nothing else remembers " +
+    "what came before it. " +
     "Keep what the user is trying to do, the decisions taken, the facts and tool results that still matter, and " +
     "anything left unfinished. Drop pleasantries and anything already superseded. Write compact notes, not prose, " +
     "and write nothing but the summary itself.";
@@ -35,10 +58,49 @@ export class Compaction {
    */
   static tokensOf(messages: readonly ChatMessage[]): number {
     let chars = 0;
-    for (const message of messages) if (!message.local) chars += JSON.stringify(message).length;
+    for (const message of messages) if (!message.local) chars += Compaction.#charsOf(message);
     return Math.ceil(chars / 4);
   }
 
+  /**
+   * What the next request is estimated to cost, prompt and all: the provider's own count for the last turn that
+   * reported one, plus four characters a token for what the transcript gained since. The provider's number is the
+   * one that knows its tokenizer — Hangul sits nearer one character a token than four — so the rule only has to
+   * cover the tail. With no count to start from, `overhead` stands in for what rides every turn beside the
+   * transcript: the tools, the screen context and the instructions.
+   */
+  static promptTokensOf(messages: readonly ChatMessage[], overhead: () => number): number {
+    for (let at = messages.length - 1; at >= 0; at -= 1) {
+      const { usage } = messages[at];
+      if (usage) return usage.input + usage.output + Compaction.tokensOf(messages.slice(at + 1));
+    }
+    return Compaction.tokensOf(messages) + overhead();
+  }
+
+  /**
+   * The prompt size past which a turn compacts first, or `Infinity` while the window is unknown. The answer shares
+   * the window with the prompt, so its ceiling is held back along with `buffer`.
+   */
+  static thresholdOf(limits: TurnLimits, buffer: number): number {
+    if (!limits.window) return Number.POSITIVE_INFINITY;
+    return limits.window - (limits.output ?? Compaction.answerTokens) - buffer;
+  }
+
+  static #charsOf(message: ChatMessage): number {
+    const posted = message.usage ? { ...message, usage: undefined } : message;
+    const images = message.attachments?.filter(Compaction.#isInlinedImage).length ?? 0;
+    if (!images) return JSON.stringify(posted).length;
+    const attachments = message.attachments?.map((attachment) =>
+      Compaction.#isInlinedImage(attachment) ? { ...attachment, data: "" } : attachment,
+    );
+    return JSON.stringify({ ...posted, attachments }).length + images * Compaction.imageTokens * 4;
+  }
+
+  static #isInlinedImage(attachment: MessageAttachment): boolean {
+    
+    return !!attachment.data && !!attachment.mimeType?.startsWith("image/");
+  }
+
   /**
    * Where the kept half starts, or `-1` when nothing can be cut. A user message is the boundary to prefer —
    * everything above it is settled — but one assistant turn that ran ten tools leaves no user message anywhere
@@ -66,9 +128,21 @@ export class Compaction {
   /**
    * The messages as one bounded block of text. Bounded is the point: the transcript being summarized is the one
    * that no longer fits, so feeding it back verbatim would fail exactly where compaction is needed most.
+   *
+   * A previous summary is the exception: carried whole, outside the bound and under its own label. It is the only
+   * record of everything compacted before it, so whatever is clipped from it here the next summary loses for good —
+   * and it wears the user's role on the wire without being anything the user said.
    */
   static digest(messages: readonly ChatMessage[], budget = 12_000): string {
-    const lines = messages.filter((message) => !message.local).map((message) => Compaction.#line(message));
+    const sent = messages.filter((message) => !message.local);
+    const previous = sent
+      .filter((message) => message.summary)
+      .map((message) => `previous summary:\n${message.text ?? ""}`);
+    const lines = sent.filter((message) => !message.summary).map((message) => Compaction.#line(message));
+    return [...previous, Compaction.#fit(lines, budget)].filter(Boolean).join("\n");
+  }
+
+  static #fit(lines: readonly string[], budget: number): string {
     if (lines.reduce((sum, line) => sum + line.length + 1, 0) <= budget) return lines.join("\n");
 
     const head: string[] = [];
@@ -100,7 +174,15 @@ export class Compaction {
   static #line(message: ChatMessage): string {
     const parts: string[] = [];
     if (message.text) parts.push(Compaction.#clip(message.text, 1200));
-    for (const attachment of message.attachments ?? []) parts.push(`[attached ${attachment.name}]`);
+
+    for (const attachment of message.attachments ?? [])
+      parts.push(`[attached ${attachment.name}, content not carried into this summary]`);
+
+    for (const reference of message.references ?? [])
+      parts.push(
+        `[referenced ${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}` +
+          ` (${reference.label}), value not carried into this summary]`,
+      );
     for (const call of message.toolCalls ?? [])
       parts.push(`[called ${call.name} ${Compaction.#clip(JSON.stringify(call.args), 200)}]`);
     for (const result of message.toolResults ?? [])

package/vendor/use-agentic/Reference.ts

@@ -0,0 +1,99 @@
+import type { MessageReference } from "./types";
+
+/**
+ * The ceiling on what one reference may add to the transcript, and the identity two of them are the same by.
+ *
+ * A reference is bulkier than it looks and lasts longer than a tool result. The host hands over whatever the
+ * screen was already holding — a document with an array of rows in it is tens of kilobytes — and unlike a tool
+ * result, which answers one turn's question, a reference is part of a *user* message: it rides the wire on this
+ * turn and on every turn after it, and it is the last thing compaction folds, because folding the thing the user
+ * pointed at is folding the question.
+ *
+ * So the value is bounded where it is staged, before it ever enters a message. Clipped rather than dropped, and
+ * the note says which: a model shown a value it cannot see the end of asks a narrower question, where one shown
+ * nothing answers from the field names.
+ */
+export class Reference {
+  /**
+   * Characters. The same number as `ToolOutput.limit` and for the same reason — far below any provider's window,
+   * comfortably above what one record needs — but its own constant, because the two bound different things and a
+   * host that finds one too generous has no reason to have found the other so.
+   */
+  static readonly limit = 20_000;
+
+  /**
+   * What the token in the message text spells, so the text is the index into the values and neither can drift
+   * from the other. A path is part of the identity: two fields of one document are two references.
+   */
+  static keyOf({ refName, refId, path }: MessageReference): string {
+    return `${refName}/${refId}${path ? `#${path}` : ""}`;
+  }
+
+  static same(one: MessageReference, other: MessageReference): boolean {
+    return Reference.keyOf(one) === Reference.keyOf(other);
+  }
+
+  /**
+   * The token a reference reads as in the message the user is writing: `@[label](mention:refName/id#path)`.
+   *
+   * The text is the source of truth for which references a message carries — deleting the token is how somebody
+   * takes one back — so the token has to say everything the pointer does. The value is looked up beside it by key.
+   */
+  static token(reference: MessageReference): string {
+    return `@[${reference.label}](mention:${Reference.keyOf(reference)})`;
+  }
+
+  /** Greedy on the label alone: a label may hold anything but `]`, and every other part is a name or an id. */
+  static readonly pattern = /@\[([^\]]*)\]\(mention:([^/)]+)\/([^#)]+)(?:#([^)]*))?\)/g;
+
+  /**
+   * The pointers a draft names, in the order it names them. Pointers only — the value lives in `staged` and is
+   * joined on by key, so reading the text can never resurrect a value somebody deleted the token for.
+   */
+  static parse(text: string): MessageReference[] {
+    return [...text.matchAll(Reference.pattern)].map(([, label, refName, refId, path]) => ({
+      refName,
+      refId,
+      label,
+      ...(path ? { path } : {}),
+    }));
+  }
+
+  /**
+   * A value past the ceiling becomes the JSON text up to it. That leaves `value` a string holding a fragment of a
+   * structure, which is exactly what it is — and a reader renders a string value as itself, so the model sees the
+   * fragment rather than an escaped quotation of one.
+   */
+  static clipped(reference: MessageReference): MessageReference {
+    if (reference.value === undefined) return reference;
+    const json = JSON.stringify(reference.value) ?? "";
+    if (json.length <= Reference.limit) return reference;
+    return { ...reference, value: `${json.slice(0, Reference.limit)}…`, note: Reference.#note(json.length) };
+  }
+
+  /**
+   * The text with every token naming `key` taken out, and the gap it leaves closed up. Deleting the chip and
+   * deleting the token have to be the same act, because the text is what decides which references a turn carries.
+   */
+  static without(text: string, key: string): string {
+    return text
+      .replace(new RegExp(Reference.pattern.source, "g"), (match, label, refName, refId, path) =>
+        Reference.keyOf({ refName, refId, label, path }) === key ? "" : match,
+      )
+      .replace(/[^\S\n]{2,}/g, " ")
+      .replace(/[^\S\n]+$/gm, "");
+  }
+
+  /** What a pasted token resolves to: the pointer is in the text, and no value was ever staged beside it. */
+  static readonly unstagedNote =
+    "the value was not captured with this reference, so read it again with a tool before answering about it";
+
+  static #note(chars: number): string {
+    return (
+      `The value is ${chars} characters (~${Math.ceil(chars / 4)} tokens), past the ${Reference.limit}-character ` +
+      `ceiling one reference may add to this conversation, so only the first ${Reference.limit} are shown and the ` +
+      `JSON is cut mid-structure. Read a narrower part of it with a tool — one row, one field — rather than asking ` +
+      `for the whole value, and tell the user if you cannot answer from what you can see.`
+    );
+  }
+}

package/vendor/use-agentic/ToolRunner.ts

@@ -1,7 +1,15 @@
 import { AgentAbort } from "./AgentAbort";
 import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
 import { ToolOutput } from "./ToolOutput";
-import type { SurfaceView, ToolCallRequest, ToolCallResult, ToolEntry } from "./types";
+import type {
+  SurfaceView,
+  ToolActivity,
+  ToolCallRequest,
+  ToolCallResult,
+  ToolCard,
+  ToolCardEntry,
+  ToolEntry,
+} from "./types";
 
 export interface ToolApprovalRequest {
   callId: string;
@@ -11,6 +19,17 @@ export interface ToolApprovalRequest {
   message: string;
 }
 
+/** A call whose answer the user writes, handed to the host with the component its declaration named. */
+export interface ToolCardRequest {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  render: ToolCard;
+}
+
+/** What the card settled on: the value the model reads back, or why there is none. */
+export type ToolCardAnswer = { result: unknown } | { error: string };
+
 /** `report` is `null` once the call is over, carrying the id so a host can ignore a clear that is not its own. */
 export interface ToolProgress {
   callId: string;
@@ -30,6 +49,13 @@ export interface ToolRunnerHost {
    * a host that may not perform the action, and the refusal says so rather than silently downgrading the gate.
    */
   approve?: (request: ToolApprovalRequest, signal: AbortSignal) => Promise<true | string>;
+  /**
+   * Parks the call until the user fills in the card its declaration named, and answers with what they submitted.
+   *
+   * Omitting it refuses those calls rather than running something in their place: a card tool has no function to
+   * fall back to — the user *is* the implementation — so a host with nowhere to render one may not answer it.
+   */
+  card?: (request: ToolCardRequest, signal: AbortSignal) => Promise<ToolCardAnswer>;
   /**
    * Awaited after a tool that changed something and before its change report is taken. A surface is read
    * synchronously and a screen does not settle synchronously, so without this the report describes the moment
@@ -37,6 +63,16 @@ export interface ToolRunnerHost {
    */
   settle?: () => Promise<void> | void;
   progress?: (progress: ToolProgress) => void;
+  /**
+   * That a call is running, for a host drawing it on the page rather than in a transcript. Separate from
+   * `progress`, which only ever fires for a tool that chose to report: a call the user has to be told about is
+   * every call, and one that says nothing about itself is exactly the one whose effect arrives unexplained.
+   *
+   * **The `start` is awaited**, so a host may draw something that has to land before the call does — a pointer
+   * pressing the link a `navigate` is about to follow is drawing on an element the router would otherwise have
+   * replaced first. The host owns the deadline: a decoration that takes its time makes the agent take its time.
+   */
+  activity?: (event: ToolActivity) => void | Promise<void>;
   /**
    * Answers a name the surface does not carry — where a consumer puts a built-in of its own. Reached only after
    * the surface came up empty, so a registered tool of the same name shadows it.
@@ -88,6 +124,7 @@ export class ToolRunner {
       const fallback = this.#host.fallback;
       return fallback ? await fallback(call, signal) : { ...base, error: `Unknown tool: ${call.name}` };
     }
+    if (entry.card) return await this.#carded(call, entry, signal);
     const message = ToolRunner.confirmMessage(call.name, entry, call.args);
     if (message) {
       const approve = this.#host.approve;
@@ -99,9 +136,39 @@ export class ToolRunner {
     return await ToolRunner.#serialized(() => this.#execute(call, entry, signal));
   }
 
+  /**
+   * A call the user answers. It waits **outside** the serialization queue, for the reason an approval does: a card
+   * parked in front of somebody is not work, and holding the lock across it would let one agent's unanswered form
+   * freeze every other agent on the page.
+   *
+   * The screen is still snapshotted around the wait, because a card that writes what it collected into a store is
+   * the ordinary case and the model has to be told what moved. Nothing is drawn through `activity` — that draws a
+   * call landing *on* the page, and this one lands in the chat.
+   */
+  async #carded(call: ToolCallRequest, entry: ToolCardEntry, signal: AbortSignal): Promise<ToolCallResult> {
+    const base = { id: call.id, name: call.name };
+    const verdict = entry.guard?.(call.args) ?? true;
+    if (verdict !== true) return { ...base, error: verdict };
+    const ask = this.#host.card;
+    if (!ask) return { ...base, error: `${call.name} is answered by the user, and nothing here can ask them.` };
+    const before = this.#surface.snapshot();
+    const answered = await ask({ callId: call.id, name: call.name, args: call.args, render: entry.card }, signal);
+    if ("error" in answered) return { ...base, error: answered.error };
+    if (entry.settle !== false) await this.#host.settle?.();
+    const changes = this.#surface.diffSince(before);
+    return {
+      ...base,
+      ...(answered.result !== undefined ? { result: answered.result } : {}),
+      ...(changes.length ? { changes } : {}),
+    };
+  }
+
   async #execute(call: ToolCallRequest, entry: ToolEntry, signal: AbortSignal): Promise<ToolCallResult> {
     const base = { id: call.id, name: call.name };
     const before = this.#surface.snapshot();
+    
+    await this.#host.activity?.({ callId: call.id, name: call.name, args: call.args, phase: "start" });
+    let failed: string | undefined;
     try {
       const result = await AgentAbort.run(signal, () =>
         AgentProgress.run(
@@ -118,9 +185,17 @@ export class ToolRunner {
         ...(changes.length ? { changes } : {}),
       };
     } catch (error) {
-      return { ...base, error: error instanceof Error ? error.message : String(error) };
+      failed = error instanceof Error ? error.message : String(error);
+      return { ...base, error: failed };
     } finally {
       this.#host.progress?.({ callId: call.id, report: null });
+      this.#host.activity?.({
+        callId: call.id,
+        name: call.name,
+        args: call.args,
+        phase: "end",
+        ...(failed ? { error: failed } : {}),
+      });
     }
   }
 

package/vendor/use-agentic/Transcript.ts

@@ -15,7 +15,12 @@ export class Transcript {
 
   /** What one turn posts: no host-only message, no unanswered call, no result answering a call nobody sees. */
   static wire(messages: readonly ChatMessage[]): ChatMessage[] {
-    return Transcript.sanitize(messages.filter((message) => !message.local));
+    return Transcript.sanitize(messages.filter((message) => !message.local).map(Transcript.unmeasured));
+  }
+
+  /** A message without the provider's count for its turn — what the wire carries and what a compaction keeps. */
+  static unmeasured(message: ChatMessage): ChatMessage {
+    return message.usage ? { ...message, usage: undefined } : message;
   }
 
   static sanitize(messages: readonly ChatMessage[]): ChatMessage[] {
@@ -28,7 +33,7 @@ export class Transcript {
         if (results.length) kept.push({ ...message, toolResults: results });
         continue;
       }
-      if (message.role === "assistant" && !Transcript.#carries(message)) continue;
+      if (message.role === "assistant" && !Transcript.carries(message)) continue;
       kept.push(message);
       const calls = message.toolCalls ?? [];
       for (const call of calls) called.add(call.id);
@@ -44,7 +49,13 @@ export class Transcript {
   }
 
   /** An empty assistant message is a draft a reload or an abort caught before it said anything. */
-  static #carries(message: ChatMessage) {
-    return !!message.text || !!message.error || !!message.toolCalls?.length || !!message.attachments?.length;
+  static carries(message: ChatMessage) {
+    return (
+      !!message.text ||
+      !!message.error ||
+      !!message.toolCalls?.length ||
+      !!message.attachments?.length ||
+      !!message.references?.length
+    );
   }
 }