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

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
+    );
   }
 }

package/vendor/use-agentic/WIRE.md

@@ -72,20 +72,34 @@ Nothing here is stored: the wire carries the bytes for exactly one turn's reques
 {
   "text": "Trimmed. Anything else?",                                  // optional
   "toolCalls": [{ "id": "c2", "name": "renderProject", "args": {} }], // optional
-  "stop": "end"                                                       // "end" | "toolUse"; defaults from toolCalls
+  "stop": "end",                                                      // "end" | "toolUse"; defaults from toolCalls
+  "usage": { "input": 18230, "output": 41 },                          // optional
+  "limits": { "window": 128000, "output": 8192 }                      // optional
 }
 ```
 
+`usage` is what the provider counted for this turn — `input` the whole prompt, cached part included. `limits` is
+what the backend knows about its model: `window` the context window, `output` the answer ceiling it requests. Send
+each only when it is known; a guessed window is worse than none. With them the session compacts before the prompt
+outgrows the window, measured by the provider's own count rather than by a character estimate; without them it
+falls back to its transcript ceiling alone.
+
 Any non-2xx status is surfaced to the session as one error event and ends the turn; a string `message` or
 `error` field in a JSON body becomes that event's message verbatim, and any other body is not interpreted. A
 message that is a code rather than a sentence may be accompanied by a flat `data` object of strings and numbers —
 the values whoever resolves the code interpolates into its text; a host that does not know the code shows the
 message as it stands.
 
+**A refusal because the prompt no longer fits the window carries `"overflow": { "limit": 128000 }`** (`limit` only
+when the provider named it). It is the one refusal a session can answer by itself: it summarizes the transcript and
+asks again, once, and remembers the window for the rest of the conversation. Flag nothing else with it — a rate
+limit flagged as overflow compacts a conversation that fit.
+
 ## Streaming
 
 The same endpoint may answer `text/event-stream` instead when the request's `accept` names it: one `RunnerEvent`
 (`types.ts`) JSON object per SSE `data:` line, ending with the `done` event. A failure after the stream opened
-travels as one `error` event — the status line is already gone by then. `httpRunner` sends
+travels as one `error` event — the status line is already gone by then. `usage` and `limits` ride the `done` event
+and `overflow` the `error` event, in the same shapes as above. `httpRunner` sends
 `accept: text/event-stream, application/json` and branches on the response's content type, so a server that never
 streams keeps answering the single JSON object above unchanged.

package/vendor/use-agentic/httpRunner.ts

@@ -1,4 +1,4 @@
-import type { AgentRunner, RunnerEvent, ToolCallRequest } from "./types";
+import type { AgentRunner, RunnerEvent, ToolCallRequest, TurnLimits, TurnUsage } from "./types";
 
 export interface HttpRunnerOptions {
   url: string;
@@ -11,6 +11,8 @@ interface TurnAnswer {
   text?: string;
   toolCalls?: ToolCallRequest[];
   stop?: "end" | "toolUse" | "length";
+  usage?: TurnUsage;
+  limits?: TurnLimits;
 }
 
 const eventTypes = new Set(["text", "toolCall", "done", "error"]);
@@ -73,6 +75,13 @@ const interpolations = (value: unknown): Record<string, string | number> | undef
   return entries.length ? Object.fromEntries(entries) : undefined;
 };
 
+const overflowOf = (value: unknown): { limit?: number } | undefined => {
+  if (!value) return undefined;
+  if (typeof value !== "object") return {};
+  const { limit } = value as { limit?: unknown };
+  return typeof limit === "number" ? { limit } : {};
+};
+
 /**
  * The server's own message travels verbatim — it was written for whoever is reading the chat, and a prefix in
  * front of it both reads as two sentences and hides a coded message from the host that would have resolved it.
@@ -81,11 +90,12 @@ const interpolations = (value: unknown): Record<string, string | number> | undef
 const turnError = async (response: Response): Promise<RunnerEvent> => {
   const fallback = { type: "error", message: `Agent turn failed: ${response.status}` } as const;
   try {
-    const body = (await response.json()) as { message?: unknown; error?: unknown; data?: unknown };
+    const body = (await response.json()) as { message?: unknown; error?: unknown; data?: unknown; overflow?: unknown };
     const message = typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : "";
     if (!message) return fallback;
     const data = interpolations(body.data);
-    return { type: "error", message, ...(data ? { data } : {}) };
+    const overflow = overflowOf(body.overflow);
+    return { type: "error", message, ...(data ? { data } : {}), ...(overflow ? { overflow } : {}) };
   } catch {
     return fallback;
   }
@@ -126,6 +136,11 @@ export const httpRunner = ({ url, headers, fetcher }: HttpRunnerOptions): AgentR
     const turn = (await response.json()) as TurnAnswer;
     if (turn.text) yield { type: "text", delta: turn.text };
     for (const call of turn.toolCalls ?? []) yield { type: "toolCall", id: call.id, name: call.name, args: call.args };
-    yield { type: "done", stop: turn.stop ?? (turn.toolCalls?.length ? "toolUse" : "end") };
+    yield {
+      type: "done",
+      stop: turn.stop ?? (turn.toolCalls?.length ? "toolUse" : "end"),
+      ...(turn.usage ? { usage: turn.usage } : {}),
+      ...(turn.limits ? { limits: turn.limits } : {}),
+    };
   },
 });

package/vendor/use-agentic/index.ts

@@ -1,4 +1,3 @@
-"use client";
 export * from "./AgentAbort";
 export * from "./Agentic";
 export * from "./AgenticSurface";
@@ -8,6 +7,7 @@ export * from "./AgentScope";
 export * from "./AgentSession";
 export * from "./Compaction";
 export * from "./httpRunner";
+export * from "./Reference";
 export * from "./sharedContext";
 export * from "./surfaceContext";
 export * from "./ToolOutput";

package/vendor/use-agentic/types.ts

@@ -1,3 +1,5 @@
+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. */
@@ -6,7 +8,24 @@ export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) =>
 /** 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;
@@ -17,7 +36,37 @@ 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. */
@@ -118,6 +167,30 @@ export interface ToolCallResult {
   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.
@@ -131,13 +204,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;
@@ -154,11 +220,42 @@ 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. */
@@ -174,6 +271,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. */
@@ -185,12 +288,20 @@ export interface ContextBlock {
 export type RunnerEvent =
   | { type: "text"; delta: string }
   | { type: "toolCall"; id: string; name: string; args: Record<string, unknown> }
-  | { type: "done"; stop: TurnStop }
+  | { 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> };
+  | {
+      type: "error";
+      message: string;
+      data?: Record<string, string | number>;
+      overflow?: { limit?: number };
+    };
 
 export interface RunnerRequest {
   messages: ChatMessage[];

package/webkit/RenderLayer.tsx

@@ -0,0 +1,45 @@
+"use client";
+import type { RouteRender } from "akanjs/client";
+import { createElement, memo, type ReactNode, useRef } from "react";
+import { useFetch } from "./useFetch";
+
+interface RenderLayerProps {
+  renders: RouteRender[];
+  index: number;
+  params: Record<string, string>;
+  searchParams: Record<string, string | string[]>;
+  leaf?: ReactNode;
+}
+export const RenderLayer = memo(({ renders, index, params, searchParams, leaf = null }: RenderLayerProps) => {
+  const isLast = index >= renders.length - 1;
+  const children = isLast ? (
+    leaf
+  ) : (
+    <RenderLayer renders={renders} index={index + 1} params={params} searchParams={searchParams} leaf={leaf} />
+  );
+  const routeRender = renders[index];
+  const isAsyncRender = isAsyncRouteRender(routeRender);
+  const resultRef = useRef<ReactNode | Promise<ReactNode> | null>(null);
+  if (isAsyncRender && resultRef.current === null) {
+    resultRef.current = routeRender?.render({ children, params, searchParams } as never) ?? null;
+  }
+  const { fulfilled, value } = useFetch(resultRef.current);
+  if (!routeRender) return null;
+  if (!isAsyncRender) return createElement(routeRender.render as never, { children, params, searchParams } as never);
+  if (!fulfilled || !value) return <>{composeLoadingFallback(renders.slice(index), params)}</>;
+  return value;
+});
+
+function isAsyncRouteRender(routeRender?: RouteRender): boolean {
+  return Boolean(routeRender?.isAsync || routeRender?.render.constructor.name === "AsyncFunction");
+}
+
+function composeLoadingFallback(renders: RouteRender[], params: Record<string, string>): ReactNode {
+  let element: ReactNode = null;
+  for (let i = renders.length - 1; i >= 0; i--) {
+    const Loading = renders[i]?.Loading;
+    if (!Loading) continue;
+    element = Loading({ params, children: element } as never) as ReactNode;
+  }
+  return element;
+}