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

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";

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

@@ -1,9 +1,25 @@
+import type { ReactNode } from "react";
 export type JsonSchema = Record<string, unknown>;
 /** `true` asks with a default message, a string is the message, a function decides from the arguments. */
 export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) => string | boolean);
 /** Re-checked at the moment of execution; a string is the refusal reason the agent reads. */
 export type ToolGuard = (args: Record<string, unknown>) => true | string;
-export interface ToolEntry {
+/**
+ * What a card tool renders while its call waits, and the two ways the user ends that wait. `submit` is the call's
+ * result, `cancel` is its refusal; whichever comes first settles the call and takes the card off the screen, so a
+ * second call of either does nothing.
+ */
+export interface ToolCardControl {
+    args: Record<string, unknown>;
+    submit: (value: unknown) => void;
+    cancel: (reason?: string) => void;
+}
+/**
+ * Called, not mounted — the host invokes it inside its own render, so the returned tree keeps no state of its
+ * own between renders. Put anything stateful in a component the function returns.
+ */
+export type ToolCard = (control: ToolCardControl) => ReactNode;
+interface ToolEntryBase {
     name: string;
     description?: string;
     parameters?: JsonSchema;
@@ -14,7 +30,33 @@ export interface ToolEntry {
     settle?: boolean;
     confirm?: ToolConfirm;
     guard?: ToolGuard;
+}
+export interface ToolActionEntry extends ToolEntryBase {
     run: (args: Record<string, unknown>) => unknown;
+    card?: never;
+}
+/**
+ * A call the **user** answers rather than the screen: the host parks the call, renders `card`, and what the card
+ * submits is what the model reads back. `confirm` is not read for one — the card in front of the user is already
+ * the asking, and a gate before it would ask them twice for one thing.
+ */
+export interface ToolCardEntry extends ToolEntryBase {
+    card: ToolCard;
+    run?: never;
+}
+export type ToolEntry = ToolActionEntry | ToolCardEntry;
+/**
+ * That a call is happening, for a host drawing it on the screen rather than in a transcript.
+ *
+ * Emitted around the execution alone — after the approval card settled, and never for a call a guard or an
+ * approval refused before it ran, so a host may treat `start` as "this is being done to the page right now".
+ */
+export interface ToolActivity {
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+    phase: "start" | "end";
+    error?: string;
 }
 /** One call an agent made through the surface, in the order it made them. */
 export interface AgentCall {
@@ -101,6 +143,27 @@ export interface ToolCallResult {
     changes?: ResourceDiff[];
     error?: string;
 }
+/**
+ * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
+ * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
+ * neither is distinguishable from `end` without it.
+ */
+export type TurnStop = "end" | "toolUse" | "length";
+/** What the provider counted for one turn. `input` is the whole prompt, cached part included — what the window held. */
+export interface TurnUsage {
+    input: number;
+    output: number;
+}
+/**
+ * What the backend knows about the model it relays to, each only when it was told: a window it guesses is worse
+ * than none, because a guard placed on a wrong number fires at the wrong time and nothing says so.
+ */
+export interface TurnLimits {
+    /** The model's context window, prompt and answer together. */
+    window?: number;
+    /** The answer ceiling the backend actually requests. */
+    output?: number;
+}
 /**
  * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
  * tool, the same reason `askUser` belongs to the session and not to the surface.
@@ -114,12 +177,6 @@ export interface ToolCallResult {
  * model cannot read and says so in the transcript, because a silently dropped file is one the model then
  * hallucinates about.
  */
-/**
- * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
- * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
- * neither is distinguishable from `end` without it.
- */
-export type TurnStop = "end" | "toolUse" | "length";
 export interface MessageAttachment {
     name: string;
     mimeType: string;
@@ -135,11 +192,41 @@ export interface MessageAttachment {
      */
     ref?: string;
 }
+/**
+ * Data the user pointed at while they were talking, rather than a file they handed over — a record, or one field
+ * of one, named in the message the way they named it. It rides a message for the same reason an attachment does:
+ * what somebody referred to while asking is part of the asking, and the turn context is rebuilt from the screen
+ * every turn, so a screen-shaped carrier forgets what was pointed at three turns ago.
+ *
+ * **`value` is a snapshot, deliberately.** It is what the data was when the user sent the message, and it is never
+ * re-read on a later turn. Re-reading would be wrong twice over: it rewrites what the person was looking at when
+ * they spoke, and the common case is an agent that then *edits* the very field it was pointed at, which would
+ * leave the reference showing the result and no record of what was being changed from. `refName`, `refId` and
+ * `path` are the way back to the current value — a tool re-reads it when the answer needs it.
+ *
+ * **`value` arrives masked, and nothing downstream can mask it again.** Masking needs the model class
+ * (`mask(model, value)`), which no wire carries, so whichever model the host names when it stages the reference is
+ * the whole of the decision about what leaves the browser.
+ */
+export interface MessageReference {
+    /** The host's own `refName`, unchanged — the vocabulary its published tools already speak. */
+    refName: string;
+    refId: string;
+    /** What the chip draws and what the token in the text spells, so the two can never disagree. */
+    label: string;
+    /** A dotted path into the document, in `pathSet`'s vocabulary. Absent means the whole of it. */
+    path?: string;
+    value?: unknown;
+    /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+    note?: string;
+}
 export interface ChatMessage {
     role: ChatRole;
     text?: string;
     /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
     attachments?: MessageAttachment[];
+    /** Data the message points at. Content, framed like attachments and for the same reason. */
+    references?: MessageReference[];
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolCallResult[];
     /** A failed or capped turn, recorded in the transcript rather than thrown past it. */
@@ -155,6 +242,12 @@ export interface ChatMessage {
      * a host renders it as one.
      */
     summary?: boolean;
+    /**
+     * What the provider counted for the turn that wrote this assistant message. Kept on the message so it moves,
+     * persists and is summarized away with it; never sent, and dropped from what a compaction keeps, since it
+     * measured a prompt that no longer exists.
+     */
+    usage?: TurnUsage;
 }
 /** One block of screen context the host assembles per turn. `kind` is the host's vocabulary; the wire forwards it verbatim. */
 export interface ContextBlock {
@@ -172,15 +265,23 @@ export type RunnerEvent = {
 } | {
     type: "done";
     stop: TurnStop;
+    usage?: TurnUsage;
+    limits?: TurnLimits;
 }
 /**
  * `data` accompanies a message that is a code rather than a sentence — the values whoever resolves the code
  * interpolates into its text. A host that does not know the code shows the message as it stands.
+ *
+ * `overflow` marks the provider refusing a prompt too long for its window — the one refusal a session can undo
+ * on its own, by compacting and asking again. `limit` is the window when the refusal named it.
  */
  | {
     type: "error";
     message: string;
     data?: Record<string, string | number>;
+    overflow?: {
+        limit?: number;
+    };
 };
 export interface RunnerRequest {
     messages: ChatMessage[];
@@ -193,3 +294,4 @@ export interface RunnerRequest {
 export interface AgentRunner {
     run: (request: RunnerRequest) => AsyncIterable<RunnerEvent>;
 }
+export {};

package/types/webkit/RenderLayer.d.ts

@@ -0,0 +1,11 @@
+import type { RouteRender } from "akanjs/client";
+import { type ReactNode } from "react";
+interface RenderLayerProps {
+    renders: RouteRender[];
+    index: number;
+    params: Record<string, string>;
+    searchParams: Record<string, string | string[]>;
+    leaf?: ReactNode;
+}
+export declare const RenderLayer: import("react").MemoExoticComponent<({ renders, index, params, searchParams, leaf }: RenderLayerProps) => string | number | bigint | true | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null>;
+export {};

package/types/webkit/index.d.ts

@@ -1,7 +1,6 @@
 export { bootCsr } from "./bootCsr.d.ts";
-export { createRobotPage } from "./createRobotPage.d.ts";
-export { createSitemapPage } from "./createSitemapPage.d.ts";
 export { lazy } from "./lazy.d.ts";
+export { createRobotPage, createSitemapPage } from "./seoPages.d.ts";
 export type * from "./types.d.ts";
 export { useBodyScrollLock } from "./useBodyScrollLock.d.ts";
 export { useCamera } from "./useCamera.d.ts";

package/types/webkit/lazy.d.ts

@@ -1,15 +1,6 @@
 import type { ReactNode } from "react";
-/**
- * `suspense` puts a Suspense boundary around the lazy component, so a chunk that resolves *after* the
- * page is painted — a modal body, a dropdown menu — suspends only itself. Without one the suspension
- * travels up to the nearest boundary, which is the route (`server/routeElementComposer.tsx`), and the
- * whole page repaints as its loading fallback on the first open.
- *
- * It is opt-in rather than the default because a boundary also changes server rendering: under the
- * default `renderMode: "stream"` the boundary's subtree leaves the shell as `loading` and arrives later
- * in the stream. That is fine for an interaction shell and wrong for a page body, which SEO snapshots,
- * prerendering and pre-hydration E2E read out of the shell.
- */
+/** `suspense`: a late chunk suspends only itself, not the route. Opt-in: under streaming the boundary's subtree
+ * leaves the shell, which SEO snapshots, prerendering and pre-hydration E2E read. */
 type LazyOption = {
     ssr?: boolean;
     suspense?: boolean;
@@ -18,6 +9,6 @@ type LazyOption = {
 type LoadedOf<Loaded> = Loaded extends {
     default: infer T;
 } ? T : Loaded;
-/** React lazy wrapper with Akan's `ssr: false` server stub and client mount gate. */
+/** `ssr: false` renders `loading` on the server and mounts the component only after hydration. */
 export declare const lazy: <Loaded>(loader: () => Promise<Loaded>, option?: LazyOption) => LoadedOf<Loaded>;
 export {};

package/types/webkit/{createRobotPage.d.ts → seoPages.d.ts}

@@ -13,3 +13,7 @@ export declare const createRobotPage: (clientHttpUri: string, config?: {
     };
     sitemap: string;
 };
+export declare const createSitemapPage: (clientHttpUri: string, paths: string[]) => {
+    url: string;
+    lastModified: Date;
+}[];

package/types/webkit/useBodyScrollLock.d.ts

@@ -1,2 +1 @@
-/** Hold `document.body` unscrollable while `active`. */
 export declare const useBodyScrollLock: (active: boolean) => void;

package/types/webkit/useCamera.d.ts

@@ -10,7 +10,7 @@ export interface CameraPromptLabels {
     picture?: string;
     cancel?: string;
 }
-/** Capacitor camera/photos hook with permission checks and app-settings fallback. */
+/** `checkPermission` opens the app settings when camera or photo access is denied. */
 export declare const useCamera: ({ promptLabels }?: {
     promptLabels?: CameraPromptLabels;
 }) => {

package/types/webkit/useContact.d.ts

@@ -2,7 +2,7 @@ import { type CapacitorPermissionState } from "akanjs/client/capacitor";
 type PermissionStatus = {
     contacts: CapacitorPermissionState;
 };
-/** Capacitor contacts hook with permission checks and contact loading helpers. */
+/** `checkPermission` opens the app settings when contacts access is denied. */
 export declare const useContact: () => {
     permissions: PermissionStatus;
     getContacts: () => Promise<unknown[]>;

package/types/webkit/useDebounce.d.ts

@@ -1,2 +1 @@
-/** Returns a callback that runs only after calls have stopped for the wait time. */
 export declare const useDebounce: <Args extends unknown[], Return>(callback: (...args: Args) => Return, states?: unknown[], wait?: number) => (...args: Args) => void;

package/types/webkit/useEscapeKey.d.ts

@@ -1,5 +1,2 @@
-/**
- * Close `onEscape` on Escape while `active`, but only while this surface is the topmost active one.
- * The callback is read through a ref, so a fresh closure per render does not reshuffle the stack.
- */
+/** Calls `onEscape` on Escape while `active` and this surface is the topmost active one. */
 export declare const useEscapeKey: (active: boolean, onEscape: () => void) => void;

package/types/webkit/useFetch.d.ts

@@ -1,15 +1,10 @@
-/** Tracks fulfillment state for a promise or immediate value inside a client component. */
 export declare const useFetch: <Return>(fnOrPromise: Promise<Return> | Return, { onError }?: {
     onError?: (err: string) => void;
 }) => {
     fulfilled: boolean;
     value: Return | null;
 };
-/**
- * Like `useFetch`, but takes a factory function that is only called once
- * (or when `deps` change). Prevents duplicate network requests caused by
- * React re-renders.
- */
+/** Calls `factory` once per `deps` change, so a re-render does not start another request. */
 export declare const useFetchFn: <Return>(factory: () => Promise<Return> | Return, deps?: unknown[], options?: {
     onError?: (err: string) => void;
 }) => {