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

package/types/vendor/@akanjs/native/plugins/window/src/index.d.ts

@@ -0,0 +1,185 @@
+import { type FileRef, type VetoHandler } from "../../../packages/core/src/index.ts";
+/** The app window (desktop). Sizes and positions are logical pixels (CSS px). */
+export interface WindowState {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    maximized: boolean;
+    minimized: boolean;
+    fullscreen: boolean;
+    focused: boolean;
+    visible: boolean;
+    title: string;
+}
+/** A window and its id (SH-6: 1 is the window the app opened; others come from createWindow). */
+export interface WindowInfo extends WindowState {
+    id: number;
+}
+/** Where a new window opens. Sizes and positions are logical pixels; x and y are the frame's top-left corner. */
+export interface CreateWindowOptions {
+    /** App path the window loads, e.g. "/settings" (the SPA router sees it). Default "/". */
+    path?: string;
+    /** Default: the app name. */
+    title?: string;
+    width?: number;
+    height?: number;
+    /** Default: offset from the focused window, like new documents on macOS. */
+    x?: number;
+    y?: number;
+}
+/** `window`: which window an op acts on. Default: the window of the page that calls. */
+type On = {
+    window?: number;
+};
+export interface WindowApi {
+    getState(args?: On): Promise<WindowState>;
+    setTitle(args: {
+        title: string;
+    } & On): Promise<WindowState>;
+    setSize(args: {
+        width: number;
+        height: number;
+    } & On): Promise<WindowState>;
+    setPosition(args: {
+        x: number;
+        y: number;
+    } & On): Promise<WindowState>;
+    center(args?: On): Promise<WindowState>;
+    minimize(args?: On): Promise<WindowState>;
+    maximize(args?: On): Promise<WindowState>;
+    unmaximize(args?: On): Promise<WindowState>;
+    /** Un-minimize, un-maximize and focus. */
+    restore(args?: On): Promise<WindowState>;
+    setFullscreen(args: {
+        value: boolean;
+    } & On): Promise<WindowState>;
+    setAlwaysOnTop(args: {
+        value: boolean;
+    } & On): Promise<WindowState>;
+    show(args?: On): Promise<WindowState>;
+    hide(args?: On): Promise<WindowState>;
+    focus(args?: On): Promise<WindowState>;
+    /**
+     * Closes the window without asking onCloseRequested handlers. While another window exists it
+     * is destroyed; the last window makes the app quit (asking app.onBeforeQuit handlers), or only
+     * hides if desktop.quitOnLastWindowClosed is false.
+     */
+    close(args?: On): Promise<void>;
+    /** Moves the window with the mouse; call it from a mousedown on a custom title bar. */
+    startDragging(args?: On): Promise<void>;
+    toggleMaximize(args?: On): Promise<WindowState>;
+    /** Opens another window (desktop). Use createWindow(). */
+    create(args?: CreateWindowOptions): Promise<WindowInfo>;
+    /** Every window, hidden ones included, by id. Use getAllWindows(). */
+    list(): Promise<WindowInfo[]>;
+    /** Internal: the page's answer to a closeRequested event. Use onCloseRequested(). */
+    answerCloseRequested(args: {
+        id: number;
+        allow?: boolean;
+    }): Promise<void>;
+}
+export interface WindowEvents {
+    /** This window's inner size changed. */
+    resize: {
+        width: number;
+        height: number;
+    };
+    /** This window moved. */
+    move: {
+        x: number;
+        y: number;
+    };
+    /** This window gained or lost focus. */
+    focus: {
+        focused: boolean;
+    };
+    /** Internal: the close button or Cmd+W on this window. Use onCloseRequested(). */
+    closeRequested: {
+        id: number;
+    };
+    /** A window was opened (any window). */
+    created: {
+        id: number;
+    };
+    /** A window was destroyed (any window). */
+    destroyed: {
+        id: number;
+    };
+    /** Files dragged over this window from Finder or another app (desktop, plugins.md D9). Use onDragDrop(). */
+    dragDrop: DragDropEvent;
+}
+/**
+ * A file drag over the window (desktop). Only drags that carry files are reported. The page's own
+ * HTML5 drop events keep working next to it (dataTransfer.files, without paths).
+ */
+export interface DragDropEvent {
+    type: "enter" | "over" | "drop" | "leave";
+    /** Absolute paths of the dragged files and folders (enter and drop). */
+    paths?: string[];
+    /** Pointer position in CSS px from the page's top-left corner (not on leave). */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** On drop: every regular file, served by the host for this session so the page can fetch() it. */
+    files?: (FileRef & {
+        path: string;
+        name: string;
+    })[];
+}
+/** The window plugin. Its ops act on this page's window unless `window` says otherwise. */
+export declare const appWindow: import("../../../packages/core/src/plugin.ts").Plugin<WindowApi, WindowEvents>;
+/** One window, by id. Its methods act on that window from any page. */
+export interface WindowHandle {
+    readonly id: number;
+    /** True for the window this page runs in. */
+    readonly isCurrent: boolean;
+    getState(): Promise<WindowState>;
+    setTitle(title: string): Promise<WindowState>;
+    setSize(width: number, height: number): Promise<WindowState>;
+    setPosition(x: number, y: number): Promise<WindowState>;
+    center(): Promise<WindowState>;
+    minimize(): Promise<WindowState>;
+    maximize(): Promise<WindowState>;
+    unmaximize(): Promise<WindowState>;
+    restore(): Promise<WindowState>;
+    toggleMaximize(): Promise<WindowState>;
+    setFullscreen(value: boolean): Promise<WindowState>;
+    setAlwaysOnTop(value: boolean): Promise<WindowState>;
+    show(): Promise<WindowState>;
+    hide(): Promise<WindowState>;
+    focus(): Promise<WindowState>;
+    /** Closes it without asking its onCloseRequested handlers (see appWindow.close). */
+    close(): Promise<void>;
+    /** Calls `fn` once the window is destroyed. Returns an unregister function. */
+    onDestroyed(fn: () => void): () => void;
+}
+/** This page's window id: 1 for the window the app opened. 1 where there is only one window. */
+export declare const currentWindowId: number;
+export declare function windowHandle(id: number): WindowHandle;
+/** The window this page runs in. */
+export declare function getCurrentWindow(): WindowHandle;
+/**
+ * Opens another window that loads `path` of this app (desktop). It stays hidden until its page
+ * has loaded, like the first window. UNSUPPORTED on web, iOS and Android. Pages of different
+ * windows share storage (localStorage, IndexedDB) and can talk through BroadcastChannel.
+ */
+export declare function createWindow(options?: CreateWindowOptions): Promise<WindowHandle>;
+/** Every window of the app, hidden ones included, by id. Only the current one where there is one window. */
+export declare function getAllWindows(): Promise<WindowHandle[]>;
+export declare function isDragRegion(path: EventTarget[]): boolean;
+/** The window state, kept up to date from resize/move/focus events. null until known or where unsupported. */
+export declare function useWindowState(): WindowState | null;
+/**
+ * Runs `handler` when the user asks to close this page's window (close button, Cmd+W). Call
+ * `event.preventDefault()` to keep it open, e.g. after asking to save. Without handlers, or if
+ * none prevents it, the window closes as usual. Desktop only: elsewhere it never fires
+ * (`appWindow.eventImplementation("closeRequested")` tells). Returns an unregister function.
+ */
+export declare const onCloseRequested: (handler: VetoHandler<{}>) => () => void;
+/** onCloseRequested while mounted; always calls the latest handler. */
+export declare function useCloseRequested(handler: VetoHandler<{}>): void;
+/** Files dragged over this window (desktop). Returns an unsubscribe function; never fires on web or mobile. */
+export declare function onDragDrop(handler: (event: DragDropEvent) => void): () => void;
+export {};

package/types/vendor/@akanjs/native/plugins/window/src/web.d.ts

@@ -0,0 +1,2 @@
+import type { WindowApi, WindowEvents } from "./index.ts";
+export declare const web: import("../../../packages/core/src/plugin.ts").WebPlugin<WindowApi, WindowEvents>;

package/types/vendor/@akanjs/native/plugins/window/src.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.d.ts";

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

@@ -0,0 +1,7 @@
+import type { WindowStateApi } from "./index.ts";
+export declare const STATE_FILE = "window-state.json";
+export declare function createDesktopWindowState(options?: {
+    delay?: number;
+}): import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<WindowStateApi, {}>;
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<WindowStateApi, {}>;
+export default _default;

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

@@ -0,0 +1,33 @@
+/**
+ * Remembers the desktop window's position, size and maximized state across launches.
+ * Adding the plugin to akan-native.config.ts is all it takes: bounds are saved while the user moves
+ * or resizes the window and restored before the window is first shown (no visible jump).
+ *
+ * - Bounds are logical points of the normal (not maximized, not minimized, not full-screen)
+ *   window, like Tauri's window-state; `maximized` is kept separately so un-maximizing after a
+ *   restart returns to the last normal bounds.
+ * - A saved position whose title bar would be off every connected display is dropped, and the
+ *   window opens at the default place (a display was unplugged).
+ * - Full screen is not restored: on macOS it would open a new Space at launch.
+ * - Web, iOS and Android: UNSUPPORTED (the OS owns the window there).
+ */
+export interface SavedWindowState {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    maximized: boolean;
+}
+export interface WindowStateApi {
+    /** What the next launch will restore, or null when nothing is saved yet. */
+    getSaved(): Promise<{
+        state: SavedWindowState | null;
+    }>;
+    /** Saves the current bounds now instead of after the next move or resize settles. */
+    save(): Promise<{
+        state: SavedWindowState | null;
+    }>;
+    /** Forgets the saved state: the next launch uses the configured size again. */
+    clear(): Promise<void>;
+}
+export declare const windowState: import("../../../packages/core/src/plugin.ts").Plugin<WindowStateApi, {}>;

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

@@ -0,0 +1,39 @@
+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;
+}
+/** The saved file's contents, or null when it is missing, corrupt or from another format version. */
+export declare function parseSaved(text: string | null): SavedWindowState | null;
+export declare function serialize(state: SavedWindowState): string;
+/**
+ * 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 declare function nextState(prev: SavedWindowState | null, snap: WindowSnapshot): SavedWindowState | null;
+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 declare 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;

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

@@ -0,0 +1 @@
+export * from "./src/index.d.ts";

package/types/vendor/use-agentic/AgentProgress.d.ts

@@ -1,8 +1,19 @@
+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[];
 }
 /**
  * The progress channel for the tool call running now.
@@ -20,6 +31,7 @@ export declare class AgentProgress {
     static report(message: string, amount?: {
         done?: number;
         total?: number;
+        steps?: AgentProgressStep[];
     }): void;
     /** True while someone is rendering the reports, for a message that costs something to assemble. */
     static get watching(): boolean;

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -1,6 +1,6 @@
 import type { AgentProgressReport } from "./AgentProgress.d.ts";
 import { type CompactOptions } from "./Compaction.d.ts";
-import type { AgentRunner, ChatMessage, ContextBlock, PublishedTool, SurfaceView } from "./types.d.ts";
+import type { AgentRunner, ChatMessage, ContextBlock, MessageReference, PublishedTool, SurfaceView, ToolActivity, ToolCard } from "./types.d.ts";
 export interface PendingApproval {
     callId: string;
     name: string;
@@ -21,6 +21,19 @@ export interface PendingQuestion {
     answer: (value: string | string[]) => void;
     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
@@ -76,6 +89,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;
 }
 /**
  * The client-side conversation loop: send → model turn → tool calls → approval gate → execute → report diffs → next
@@ -111,6 +139,60 @@ export declare class AgentSession {
     get isCompacting(): boolean;
     get pendingApproval(): PendingApproval | null;
     get pendingQuestion(): PendingQuestion | null;
+    get pendingCard(): PendingCard | null;
+    /**
+     * 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[];
+    /**
+     * 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) => void;
+    /**
+     * 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) => void;
+    /**
+     * 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[];
+    /** Idempotent by key: the second chat to apply the same insert is acknowledging one that is already gone. */
+    insertApplied: (key: string) => void;
+    /**
+     * 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[]) => void;
+    /**
+     * 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: () => () => void;
+    /** By key, never by index: what orders the references of a message is its text, and that is not this list. */
+    unstage: (key: string) => void;
+    clearStaged: () => void;
     /** What the tool running now last said about its own progress, for the row that is still spinning. */
     get progress(): (AgentProgressReport & {
         callId: string;
@@ -154,8 +236,18 @@ export declare class AgentSession {
     compact: ({ keep }?: {
         keep?: number;
     }) => Promise<boolean>;
-    /** 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(): number;
+    /**
+     * 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;
+    };
     /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
     report: (error: string) => void;
     /** A line the host wrote — a command's own output. Rendered in the transcript, withheld from the model. */

package/types/vendor/use-agentic/Compaction.d.ts

@@ -1,9 +1,19 @@
-import type { ChatMessage } from "./types.d.ts";
+import type { ChatMessage, TurnLimits } from "./types.d.ts";
 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>;
 }
@@ -15,14 +25,24 @@ export interface CompactOptions {
 export declare class Compaction {
     #private;
     /**
-     * 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: number;
         keep: number;
+        buffer: number;
     };
+    /** The answer ceiling assumed when the backend did not report one — the one most relays request when they do. */
+    static readonly answerTokens = 8192;
+    /**
+     * 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 imageTokens = 1600;
     static readonly instruction: string;
     /**
      * Four characters per token, counted over the JSON the turn actually posts. A rough estimate on purpose: this
@@ -30,6 +50,19 @@ export declare class Compaction {
      * more than the slack the estimate leaves.
      */
     static tokensOf(messages: readonly ChatMessage[]): number;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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
@@ -42,6 +75,10 @@ export declare 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?: number): string;
     static message(summary: string): ChatMessage;

package/types/vendor/use-agentic/Reference.d.ts

@@ -0,0 +1,56 @@
+import type { MessageReference } from "./types.d.ts";
+/**
+ * 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 declare class Reference {
+    #private;
+    /**
+     * 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 = 20000;
+    /**
+     * 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;
+    static same(one: MessageReference, other: MessageReference): boolean;
+    /**
+     * 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;
+    /** Greedy on the label alone: a label may hold anything but `]`, and every other part is a name or an id. */
+    static readonly pattern: RegExp;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /** 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";
+}

package/types/vendor/use-agentic/ToolRunner.d.ts

@@ -1,5 +1,5 @@
 import { type AgentProgressReport } from "./AgentProgress.d.ts";
-import type { SurfaceView, ToolCallRequest, ToolCallResult, ToolEntry } from "./types.d.ts";
+import type { SurfaceView, ToolActivity, ToolCallRequest, ToolCallResult, ToolCard, ToolEntry } from "./types.d.ts";
 export interface ToolApprovalRequest {
     callId: string;
     name: string;
@@ -7,6 +7,19 @@ export interface ToolApprovalRequest {
     /** What the user is asked, already resolved from the entry's `confirm`. */
     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;
@@ -25,6 +38,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
@@ -32,6 +52,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.

package/types/vendor/use-agentic/Transcript.d.ts

@@ -10,9 +10,12 @@ import type { ChatMessage } from "./types.d.ts";
  * transcript is assembled rather than where each hole is made.
  */
 export declare class Transcript {
-    #private;
     static readonly unanswered = "The turn was stopped before this call ran.";
     /** What one turn posts: no host-only message, no unanswered call, no result answering a call nobody sees. */
     static wire(messages: readonly ChatMessage[]): ChatMessage[];
+    /** A message without the provider's count for its turn — what the wire carries and what a compaction keeps. */
+    static unmeasured(message: ChatMessage): ChatMessage;
     static sanitize(messages: readonly ChatMessage[]): ChatMessage[];
+    /** An empty assistant message is a draft a reload or an abort caught before it said anything. */
+    static carries(message: ChatMessage): boolean;
 }

package/types/vendor/use-agentic/index.d.ts

@@ -7,6 +7,7 @@ export * from "./AgentScope.d.ts";
 export * from "./AgentSession.d.ts";
 export * from "./Compaction.d.ts";
 export * from "./httpRunner.d.ts";
+export * from "./Reference.d.ts";
 export * from "./sharedContext.d.ts";
 export * from "./surfaceContext.d.ts";
 export * from "./ToolOutput.d.ts";