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

package/vendor/use-agentic/AgentSession.ts

@@ -1,18 +1,24 @@
 import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
+import { Reference } from "./Reference";
 import { ToolOutput } from "./ToolOutput";
-import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
+import { type ToolApprovalRequest, type ToolCardAnswer, type ToolCardRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
 import type {
   AgentRunner,
   ChatMessage,
   ContextBlock,
+  MessageReference,
   PublishedTool,
   RunnerRequest,
   SurfaceView,
+  ToolActivity,
   ToolCallRequest,
   ToolCallResult,
+  ToolCard,
+  TurnLimits,
   TurnStop,
+  TurnUsage,
 } from "./types";
 
 export interface PendingApproval {
@@ -37,6 +43,20 @@ export interface PendingQuestion {
   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
@@ -90,6 +110,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;
 }
 
 /**
@@ -132,6 +167,10 @@ export class AgentSession {
   #running = false;
   #pending: PendingApproval | null = null;
   #question: PendingQuestion | null = null;
+  #card: PendingCard | null = null;
+  #staged: MessageReference[] = [];
+  #inserts: MessageReference[] = [];
+  #chats = 0;
   #progress: (AgentProgressReport & { callId: string }) | null = null;
   #controller: AbortController | null = null;
   #active: Promise<void> | null = null;
@@ -144,8 +183,15 @@ export class AgentSession {
   #history: SessionHistory | undefined;
   #onCompact: AgentSessionOptions["onCompact"];
   #compacting = false;
-  /** Size below which auto-compaction stays out of the way, raised when a summary failed to shrink anything. */
-  #compactFloor = 0;
+  /**
+   * Sizes below which auto-compaction stays out of the way, raised when a summary failed to shrink anything — one
+   * per trigger, since the ceiling reads the transcript and the guard the whole prompt.
+   */
+  #compactFloor = { transcript: 0, prompt: 0 };
+  /** What the backend reported about its model, or what a refusal named — kept for the life of the session. */
+  #limits: TurnLimits = {};
+  /** What the tools, the screen context and the instructions cost the last request, for a host's gauge. */
+  #overhead = 0;
 
   constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
     this.#surface = surface;
@@ -153,7 +199,9 @@ export class AgentSession {
     this.#options = options;
     this.#tools = new ToolRunner(surface, {
       approve: (request, signal) => this.#awaitApproval(request, signal),
+      card: (request, signal) => this.#awaitCard(request, signal),
       settle: () => this.#options.settle?.(),
+      activity: (event) => this.#options.onActivity?.(event),
       progress: ({ callId, report }) => {
         if (report) this.#progress = { ...report, callId };
         else if (this.#progress?.callId === callId) this.#progress = null;
@@ -212,6 +260,121 @@ export class AgentSession {
     return this.#question;
   }
 
+  get pendingCard(): PendingCard | null {
+    return this.#card;
+  }
+
+  /**
+   * 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[] {
+    return this.#staged;
+  }
+
+  /**
+   * 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) => {
+    this.#stage(Reference.clipped(reference));
+    this.#announce();
+  };
+
+  /**
+   * 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) => {
+    const clipped = Reference.clipped(reference);
+    this.#stage(clipped);
+    if (this.#chats) this.#inserts = [...this.#inserts.filter((one) => !Reference.same(one, clipped)), clipped];
+    else
+      console.warn(
+        `No chat is rendering this agent session, so "${clipped.label}" was staged with no token written for it. ` +
+          "The component calling this and an <Agent.Chat /> have to share one session — check which <Agent.Zone> " +
+          "each of them is inside.",
+      );
+    this.#announce();
+  };
+
+  /**
+   * 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[] {
+    return this.#inserts;
+  }
+
+  /** Idempotent by key: the second chat to apply the same insert is acknowledging one that is already gone. */
+  insertApplied = (key: string) => {
+    const next = this.#inserts.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#inserts.length) return;
+    this.#inserts = next;
+    this.#announce();
+  };
+
+  /**
+   * 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[]) => {
+    const fresh = references.filter((one) => !this.#staged.some((held) => Reference.same(held, one)));
+    if (!fresh.length) return;
+    this.#staged = [...fresh.map((one) => Reference.clipped(one)), ...this.#staged];
+    this.#announce();
+  };
+
+  /**
+   * 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 = () => {
+    this.#chats += 1;
+    return () => {
+      this.#chats = Math.max(0, this.#chats - 1);
+    };
+  };
+
+  #stage(clipped: MessageReference) {
+    const at = this.#staged.findIndex((one) => Reference.same(one, clipped));
+    this.#staged =
+      at === -1 ? [...this.#staged, clipped] : this.#staged.map((one, idx) => (idx === at ? clipped : one));
+  }
+
+  /** By key, never by index: what orders the references of a message is its text, and that is not this list. */
+  unstage = (key: string) => {
+    const next = this.#staged.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#staged.length) return;
+    this.#staged = next;
+    this.#announce();
+  };
+
+  clearStaged = () => {
+    if (!this.#staged.length && !this.#inserts.length) return;
+    this.#staged = [];
+    this.#inserts = [];
+    this.#announce();
+  };
+
   /** What the tool running now last said about its own progress, for the row that is still spinning. */
   get progress(): (AgentProgressReport & { callId: string }) | null {
     return this.#progress;
@@ -241,11 +404,13 @@ export class AgentSession {
   async #turn(input: string | ChatMessage[]) {
     const controller = new AbortController();
     this.#controller = controller;
+    this.#options.onTurn?.(true);
     if (typeof input === "string") this.#append({ role: "user", text: input });
     else for (const message of input) this.#append(message);
     const maxTurns = this.#options.maxTurns ?? 12;
     try {
       let budget = maxTurns;
+      let recovered = false;
       for (let turn = 0; ; turn += 1) {
         if (controller.signal.aborted) return;
         if (turn >= budget) {
@@ -259,12 +424,20 @@ export class AgentSession {
           budget = turn + maxTurns;
         }
         await this.#autoCompact(controller.signal);
-        const { toolCalls, stop } = await this.#assistantTurn(controller.signal);
+        const { toolCalls, stop, overflow } = await this.#assistantTurn(controller.signal);
 
         if (controller.signal.aborted) {
           this.#unanswered(toolCalls);
           return;
         }
+        if (overflow) {
+          if (recovered || !(await this.#recover(overflow, controller.signal))) {
+            if (!controller.signal.aborted) this.#fail(overflow.message);
+            return;
+          }
+          recovered = true;
+          continue;
+        }
 
         if (stop === "length") {
 
@@ -292,7 +465,12 @@ export class AgentSession {
       this.#active = null;
       this.#pending = null;
       this.#question = null;
+      this.#card = null;
       this.#progress = null;
+
+      const draft = this.#messages[this.#messages.length - 1];
+      if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+      this.#options.onTurn?.(false);
       this.#notify();
     }
   }
@@ -312,7 +490,9 @@ export class AgentSession {
       await this.#active;
     }
     this.#messages = [];
-    this.#compactFloor = 0;
+    this.#staged = [];
+    this.#inserts = [];
+    this.#compactFloor = { transcript: 0, prompt: 0 };
     
     if (this.#saveTimer) {
       clearTimeout(this.#saveTimer);
@@ -411,11 +591,28 @@ export class AgentSession {
     }
   };
 
-  /** 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() {
     return Compaction.tokensOf(this.#messages);
   }
 
+  /**
+   * 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 } {
+    const { at, buffer } = this.#compactOptions;
+    const prompt = Compaction.promptTokensOf(this.#messages, () => this.#overhead);
+    if (!at) return { used: prompt };
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const ceiling = Number.isFinite(at) ? { used: Compaction.tokensOf(this.#messages), compactAt: at } : null;
+    const window = Number.isFinite(guard) ? { used: prompt, compactAt: guard } : null;
+    if (ceiling && window) return ceiling.used / ceiling.compactAt >= window.used / window.compactAt ? ceiling : window;
+    return ceiling ?? window ?? { used: prompt };
+  }
+
   /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
   report = (error: string) => {
     this.#append({ role: "assistant", error });
@@ -436,7 +633,7 @@ export class AgentSession {
       if (!summary || signal.aborted) return false;
       const replaced = this.#messages.slice(0, at);
       const message = Compaction.message(summary);
-      this.#messages = [message, ...this.#messages.slice(at)];
+      this.#messages = [message, ...this.#messages.slice(at).map(Transcript.unmeasured)];
       try {
         this.#onCompact?.(replaced, message);
       } catch {
@@ -450,13 +647,21 @@ export class AgentSession {
 
   /**
    * Runs before the turn that would have overflowed rather than after it fails: the provider answers a request
-   * that is too long with a refusal, not with a shorter answer, so there is nothing to recover from afterwards.
-   * Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes out as
-   * it would have, since it may well still fit.
+   * that is too long with a refusal, not with a shorter answer, so waiting for one costs a round trip that was
+   * refused. Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes
+   * out as it would have, since it may well still fit.
    */
   async #autoCompact(signal: AbortSignal) {
-    const { at = Compaction.defaults.at, keep = Compaction.defaults.keep } = this.#options.compact ?? {};
-    if (!at || Compaction.tokensOf(this.#messages) < Math.max(at, this.#compactFloor)) return;
+    const { at, keep, buffer } = this.#compactOptions;
+    if (!at) return;
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const measure = () => ({
+      transcript: Compaction.tokensOf(this.#messages),
+      prompt: Compaction.promptTokensOf(this.#messages, () => AgentSession.#tokensOfFrame(this.#frame())),
+    });
+    const before = measure();
+    const floor = this.#compactFloor;
+    if (before.transcript < Math.max(at, floor.transcript) && before.prompt <= Math.max(guard, floor.prompt)) return;
     let compacted = false;
     try {
       compacted = await this.#compact(keep, signal);
@@ -465,9 +670,57 @@ export class AgentSession {
       console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
       return;
     }
-    const after = Compaction.tokensOf(this.#messages);
+    const after = measure();
 
-    this.#compactFloor = compacted && after >= at ? after + at : 0;
+    this.#compactFloor = {
+      transcript: compacted && after.transcript >= at ? after.transcript + at : 0,
+      prompt: compacted && after.prompt > guard ? after.prompt + buffer : 0,
+    };
+  }
+
+  /**
+   * Answers a refusal for length the one way a session can: compact, and ask again. Once per send — a transcript
+   * refused again after its own summary is not one another summary will fit — and never where the host turned
+   * automatic compaction off, since that host keeps the window itself.
+   */
+  async #recover(overflow: { limit?: number }, signal: AbortSignal): Promise<boolean> {
+    if (overflow.limit) this.#limits = { ...this.#limits, window: overflow.limit };
+    const { at, keep } = this.#compactOptions;
+    if (!at) return false;
+    const draft = this.#messages[this.#messages.length - 1];
+    if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+    try {
+      return await this.#compact(keep, signal);
+    } catch (error) {
+      console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  get #compactOptions() {
+    const {
+      at = Compaction.defaults.at,
+      keep = Compaction.defaults.keep,
+      buffer = Compaction.defaults.buffer,
+    } = this.#options.compact ?? {};
+    return { at, keep, buffer };
+  }
+
+  /** What rides every turn beside the transcript. Read per turn, because the screen it describes moves. */
+  #frame(): Omit<RunnerRequest, "messages" | "signal"> {
+    const { tools, guides } = this.#surface.snapshot();
+    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
+    return {
+      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
+        ? tools
+        : [...tools, AgentSession.askUserTool],
+      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
+      ...(instructions ? { instructions } : {}),
+    };
+  }
+
+  static #tokensOfFrame(frame: Omit<RunnerRequest, "messages" | "signal">): number {
+    return Math.ceil(JSON.stringify(frame).length / 4);
   }
 
   /** No tools and no screen context: this turn summarizes the conversation, and must not act on it. */
@@ -488,32 +741,33 @@ export class AgentSession {
     return text;
   }
 
-  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop }> {
-    const { tools, guides } = this.#surface.snapshot();
-    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
-    const request: RunnerRequest = {
-      messages: Transcript.wire(this.#messages),
-      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
-        ? tools
-        : [...tools, AgentSession.askUserTool],
-      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
-      ...(instructions ? { instructions } : {}),
-      signal,
-    };
+  async #assistantTurn(
+    signal: AbortSignal,
+  ): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop; overflow?: { message: string; limit?: number } }> {
+    const frame = this.#frame();
+    this.#overhead = AgentSession.#tokensOfFrame(frame);
+    const request: RunnerRequest = { messages: Transcript.wire(this.#messages), ...frame, signal };
     this.#append({ role: "assistant" });
     let text = "";
     const toolCalls: ToolCallRequest[] = [];
     let stop: TurnStop = "end";
+    let usage: TurnUsage | undefined;
     for await (const event of this.#runner.run(request)) {
       if (signal.aborted) break;
       if (event.type === "text") {
         text += event.delta;
         this.#patchLast({ text });
       } else if (event.type === "toolCall") toolCalls.push({ id: event.id, name: event.name, args: event.args });
-      else if (event.type === "done") stop = event.stop;
+      else if (event.type === "done") {
+        stop = event.stop;
+        usage = event.usage;
+        if (event.limits) this.#limits = { ...this.#limits, ...event.limits };
+      } else if (event.overflow)
+        return { toolCalls: [], stop: "end", overflow: { message: event.message, limit: event.overflow.limit } };
       else throw new Error(event.message);
     }
-    if (toolCalls.length) this.#patchLast({ toolCalls });
+    if (toolCalls.length || usage)
+      this.#patchLast({ ...(toolCalls.length ? { toolCalls } : {}), ...(usage ? { usage } : {}) });
     return { toolCalls, stop };
   }
 
@@ -572,6 +826,28 @@ export class AgentSession {
     });
   }
 
+  #awaitCard(request: ToolCardRequest, signal: AbortSignal): Promise<ToolCardAnswer> {
+    return new Promise((resolve) => {
+      const settle = (answer: ToolCardAnswer) => {
+        this.#card = null;
+        signal.removeEventListener("abort", onAbort);
+        this.#notify();
+        resolve(answer);
+      };
+      const onAbort = () => settle({ error: "The user aborted the turn." });
+      signal.addEventListener("abort", onAbort);
+      this.#card = {
+        callId: request.callId,
+        name: request.name,
+        args: request.args,
+        render: request.render,
+        submit: (value) => settle({ result: value }),
+        dismiss: (reason) => settle({ error: reason ?? "The user closed the card without filling it in." }),
+      };
+      this.#notify();
+    });
+  }
+
   #awaitApproval(request: ToolApprovalRequest, signal: AbortSignal): Promise<true | string> {
     return new Promise((resolve) => {
       const settle = (value: true | string) => {
@@ -628,9 +904,17 @@ export class AgentSession {
   }
 
   #notify() {
+    this.#announce();
+    this.#schedulePersist();
+  }
+
+  /**
+   * A change that is not the transcript's. Staged references live beside the messages rather than in them, so
+   * announcing one has to redraw the composer without scheduling a save of messages nothing touched.
+   */
+  #announce() {
     this.#version += 1;
     for (const listener of this.#listeners) listener();
-    this.#schedulePersist();
   }
 
   /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */

package/vendor/use-agentic/AgenticSurface.ts

@@ -183,6 +183,8 @@ export class AgenticSurface {
     try {
       const verdict = entry.guard?.(args) ?? true;
       if (verdict !== true) throw new Error(verdict);
+      
+      if (!entry.run) throw new Error(`${name} is answered by the user, and this caller cannot ask them.`);
       return await entry.run(args);
     } catch (error) {
       record.error = error instanceof Error ? error.message : String(error);

package/vendor/use-agentic/Compaction.ts

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