akanjs 3.0.0-beta.9 → 3.0.0

package/vendor/use-agentic/Compaction.ts

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

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[] {

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,5 +1,6 @@
-"use client";
 export * from "./AgentAbort";
+export * from "./AgentActivity";
+export * from "./AgentGate";
 export * from "./Agentic";
 export * from "./AgenticSurface";
 export * from "./AgentProgress";

package/vendor/use-agentic/surfaceContext.ts

@@ -1,10 +1,13 @@
 "use client";
 import { useContext } from "react";
+import type { AgentGate } from "./AgentGate";
 import { AgenticSurface } from "./AgenticSurface";
 import { sharedContext } from "./sharedContext";
 
 export const SurfaceContext = sharedContext<AgenticSurface | null>("surface", null);
 export const ScopeContext = sharedContext<string[]>("scope", []);
+export const GateContext = sharedContext<AgentGate | null>("gate", null);
 
 export const useSurface = () => useContext(SurfaceContext) ?? AgenticSurface.shared;
 export const useScopePath = () => useContext(ScopeContext);
+export const useAgentGate = () => useContext(GateContext);

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. */
@@ -125,6 +174,23 @@ export interface ToolCallResult {
  */
 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.
@@ -205,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. */
@@ -216,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[];