pi-jar 0.2.2 → 0.2.4

package/src/compact-tools.ts

@@ -1,14 +1,19 @@
+import { stat } from "node:fs/promises";
 import {
   createBashToolDefinition,
   createEditToolDefinition,
   createReadToolDefinition,
   createWriteToolDefinition,
+  formatSize,
   getAgentDir,
   SettingsManager,
   type ExtensionAPI,
-  type ExtensionContext
+  type ExtensionContext,
+  type ReadToolDetails
 } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { isReadStub, readRangeKey, resolveToolPath, type ReadStubDetails } from "./context-diet.ts";
 
 type ToolResult = { content: Array<{ type: string; text?: string }>; details?: unknown };
 
@@ -152,11 +157,83 @@ function bashFor(ctx: ExtensionContext) {
   return tool;
 }
 
+/** Over Pi's 50 KB read cap, a read without offset/limit gets this many lines and a note saying so. */
+const AUTO_LIMIT_BYTES = 50 * 1024;
+const AUTO_LIMIT_LINES = 400;
+/** Pi sends these as image attachments and ignores offset/limit for them. */
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|webp|bmp)$/i;
+/** Pi's trailing `[… Use offset=N to continue.]` notice, which is not file text. */
+const READ_NOTICE = /\n\n\[[^\n]*\]$/;
+
+/** A read whose output is in context: the file revision it saw, its session ordinal and its line count. */
+interface ReadMark { revision: string; ordinal: number; lines: number }
+
+/**
+ * Per-session record of what `read` put in context, behind the opt-in repeated-read stub. A mark answers
+ * only for its exact path, line window and file revision. Anything that may change the file or drop that
+ * output from context forgets marks: an edit/write of the path (even a failed edit: the model evidently
+ * misremembers the file), a session start or switch, compaction and tree navigation.
+ */
+class ReadMemory {
+  #files = new Map<string, Map<string, ReadMark>>();
+  #reads = 0;
+  /** Invalidation clock: a read that straddles an invalidation of its file is never remembered. */
+  #clock = 0;
+  #cleared = 0;
+  #forgotten = new Map<string, number>();
+
+  /** The session ordinal of a new read and the clock it starts at. */
+  begin(): { ordinal: number; since: number } {
+    return { ordinal: ++this.#reads, since: this.#clock };
+  }
+  find(file: string, range: string, revision: string): ReadMark | undefined {
+    const mark = this.#files.get(file)?.get(range);
+    return mark?.revision === revision ? mark : undefined;
+  }
+  remember(file: string, range: string, mark: ReadMark, since: number): void {
+    if (this.#cleared > since || (this.#forgotten.get(file) ?? 0) > since) return;
+    let ranges = this.#files.get(file);
+    if (!ranges) this.#files.set(file, ranges = new Map());
+    ranges.set(range, mark);
+  }
+  forget(file: string): void {
+    this.#forgotten.set(file, ++this.#clock);
+    this.#files.delete(file);
+  }
+  /** A new session also restarts read numbering. */
+  clear(newSession = false): void {
+    this.#cleared = ++this.#clock;
+    this.#files.clear();
+    this.#forgotten.clear();
+    if (newSession) this.#reads = 0;
+  }
+}
+
+/** A regular file's resolved path, size and revision (Pi's own dev:ino:size:mtime:ctime file key). */
+async function inspectFile(path: string, cwd: string): Promise<{ file: string; size: number; revision: string } | undefined> {
+  const file = resolveToolPath(path, cwd);
+  if (!file) return undefined;
+  try {
+    const stats = await stat(file, { bigint: true });
+    if (!stats.isFile()) return undefined;
+    return { file, size: Number(stats.size), revision: `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}` };
+  } catch {
+    // Missing or unreadable: Pi's read reports the error itself (or resolves a macOS name variant), uncached.
+    return undefined;
+  }
+}
+
+export interface CompactToolOptions {
+  /** Opt-in repeated-read stub; consulted per call, so a settings toggle applies to the next read. */
+  readCache?: () => boolean;
+}
+
 /**
- * Keep Pi's execution/schema/prompt metadata intact and replace only the collapsed
- * presentation. Expanded cards delegate back to Pi's native renderers.
+ * Keep Pi's execution and schema, replace only the collapsed presentation and keep the per-call prompt
+ * rules short (detail lives in tool and parameter descriptions). Expanded cards delegate back to Pi's
+ * native renderers. `read` also caps whole reads of large files and can stub unchanged repeats.
  */
-export function installCompactBuiltinTools(pi: ExtensionAPI): void {
+export function installCompactBuiltinTools(pi: ExtensionAPI, { readCache }: CompactToolOptions = {}): void {
   if (typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool !== "function") return;
 
   const cwd = process.cwd();
@@ -165,8 +242,58 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
   const edit = createEditToolDefinition(cwd);
   const write = createWriteToolDefinition(cwd);
 
-  pi.registerTool({
+  // Without session events a mark could outlive a compaction, so the read cache requires them.
+  const memory = typeof (pi as Partial<ExtensionAPI>).on === "function" ? new ReadMemory() : undefined;
+  if (memory) {
+    pi.on("session_start", () => memory.clear(true));
+    pi.on("session_compact", () => memory.clear());
+    pi.on("session_tree", () => memory.clear());
+  }
+  const forget = (path: string, ctx: ExtensionContext) => {
+    const file = resolveToolPath(path, ctx.cwd);
+    if (file) memory?.forget(file);
+  };
+
+  const readParameters = Type.Object({
+    ...read.parameters.properties,
+    force: Type.Optional(Type.Boolean({ description: "Re-read even if unchanged since an earlier read." }))
+  });
+  pi.registerTool<typeof readParameters, ReadToolDetails | ReadStubDetails | undefined>({
     ...read,
+    description: `${read.description} Without offset/limit, files over ${formatSize(AUTO_LIMIT_BYTES)} stop at ${AUTO_LIMIT_LINES} lines.`,
+    promptGuidelines: ["Use read, not cat/sed, to view files.", "Keep plans in jar_todo or the plan tool, not /tmp/*.md files you re-read."],
+    parameters: readParameters,
+    async execute(id, { force, ...request }, signal, onUpdate, ctx) {
+      const cache = readCache?.() === true ? memory : undefined;
+      // Taken before the stat: an invalidation from here on keeps this read from being remembered.
+      const started = cache?.begin();
+      const whole = request.offset === undefined && request.limit === undefined;
+      const target = cache || whole ? await inspectFile(request.path, ctx.cwd) : undefined;
+      const limited = whole && target !== undefined && target.size > AUTO_LIMIT_BYTES && !IMAGE_FILE.test(target.file);
+      const effective = limited ? { ...request, limit: AUTO_LIMIT_LINES } : request;
+      const range = readRangeKey(effective.offset, effective.limit);
+      const slot = cache && started && target && range !== undefined
+        ? { cache, ...started, file: target.file, range, revision: target.revision } : undefined;
+      if (slot && !force) {
+        const mark = slot.cache.find(slot.file, slot.range, slot.revision);
+        if (mark) return {
+          content: [{ type: "text", text: `[unchanged since read #${mark.ordinal} (${mark.lines} line${mark.lines === 1 ? "" : "s"}); pass force: true to re-read]` }],
+          details: { unchangedSinceRead: mark.ordinal }
+        };
+      }
+      const result = await read.execute(id, effective, signal, onUpdate, ctx);
+      let text = "";
+      for (const part of result.content) {
+        // Images ignore offset/limit and are never remembered.
+        if (part.type !== "text") return result;
+        text += part.text;
+      }
+      slot?.cache.remember(slot.file, slot.range, { revision: slot.revision, ordinal: slot.ordinal, lines: lineCount(text.replace(READ_NOTICE, "")) }, slot.since);
+      if (!limited) return result;
+      const note = `\n\n[${formatSize(target.size)} file: a read without offset/limit returns its first ${AUTO_LIMIT_LINES} lines. Use offset/limit to read more.]`;
+      const last = result.content.length - 1;
+      return { ...result, content: result.content.map((part, index) => index === last && part.type === "text" ? { ...part, text: part.text + note } : part) };
+    },
     renderCall(args, theme, context) {
       if (context.expanded && read.renderCall) return read.renderCall(args, theme, context);
       const range = args?.offset || args?.limit
@@ -175,8 +302,9 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
       return new Text(theme.fg("toolTitle", theme.bold("read ")) + theme.fg("accent", str(args?.path)) + range, 0, 0);
     },
     renderResult(result, options, theme, context) {
-      if (options.expanded && read.renderResult) return read.renderResult(result, options, theme, context);
+      if (options.expanded && read.renderResult) return read.renderResult(result as Parameters<NonNullable<typeof read.renderResult>>[0], options, theme, context);
       if (options.isPartial) return new Text(theme.fg("warning", "reading…"), 0, 0);
+      if (isReadStub(result.details)) return new Text(theme.fg("muted", `unchanged since read #${result.details.unchangedSinceRead}${expandHint}`), 0, 0);
       const summary = summarizeResult(result);
       const count = `${summary.lines}${summary.truncated ? "+" : ""}`;
       return new Text(theme.fg("muted", `${count} line${summary.lines === 1 && !summary.truncated ? "" : "s"}${expandHint}`), 0, 0);
@@ -185,6 +313,8 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
 
   pi.registerTool({
     ...bash,
+    description: `${bash.description} PI_* env vars describe the current model and session.`,
+    promptGuidelines: [],
     async execute(id, params, signal, onUpdate, ctx) {
       return bashFor(ctx).execute(id, params, signal, onUpdate, ctx);
     },
@@ -209,19 +339,29 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
 
   pi.registerTool({
     ...edit,
+    promptSnippet: "Precise exact-text file edits",
+    promptGuidelines: ["Batch all changes to one file into one edit call (several edits[] entries); keep each oldText minimal but unique."],
+    execute(id, params, signal, onUpdate, ctx) {
+      return edit.execute(id, params, signal, onUpdate, ctx).finally(() => forget(params.path, ctx));
+    },
     renderCall(args, theme, context) {
       if (context.expanded && edit.renderCall) return edit.renderCall(args, theme, context);
       const path = str(args?.path) || str((args as { file_path?: unknown } | undefined)?.file_path);
       return compactCard(theme, context, new Text(theme.fg("toolTitle", theme.bold("edit ")) + theme.fg("accent", path), 0, 0));
     },
     renderResult(result, options, theme, context) {
-      if (options.expanded && edit.renderResult) return edit.renderResult(result, options, theme, context);
+      if (options.expanded && edit.renderResult) return edit.renderResult(result as Parameters<NonNullable<typeof edit.renderResult>>[0], options, theme, context);
       return intoCard(context, editSummary(result, options.isPartial, theme));
     }
   });
 
   pi.registerTool({
     ...write,
+    promptSnippet: "Create new files or complete rewrites; use edit for partial changes",
+    promptGuidelines: [],
+    execute(id, params, signal, onUpdate, ctx) {
+      return write.execute(id, params, signal, onUpdate, ctx).finally(() => forget(params.path, ctx));
+    },
     renderCall(args, theme, context) {
       if (context.expanded && write.renderCall) return write.renderCall(args, theme, context);
       const content = str(args?.content);
@@ -234,7 +374,7 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
         + theme.fg("dim", ` · ${count.lines}${count.truncated ? "+" : ""} line${count.lines === 1 && !count.truncated ? "" : "s"}`), 0, 0);
     },
     renderResult(result, options, theme, context) {
-      if (options.expanded && write.renderResult) return write.renderResult(result, options, theme, context);
+      if (options.expanded && write.renderResult) return write.renderResult(result as Parameters<NonNullable<typeof write.renderResult>>[0], options, theme, context);
       if (options.isPartial) return new Text(theme.fg("warning", "writing…"), 0, 0);
       const summary = summarizeResult(result);
       const text = summary.sample;

package/src/context-budget.ts

@@ -0,0 +1,226 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ContextBudget } from "./settings.ts";
+import { cleanText } from "./status.ts";
+
+/**
+ * Context-budget guard. Pi compacts only near the window limit, so a long session re-sends a large,
+ * growing prompt on every call. Past `softTokens` the guard either suggests /compact or /new once per
+ * crossing, or compacts once at the next safe point:
+ * - the end of a turn in which a jar_todo item completed while work remains. Every tool result of that
+ *   turn is in, so the run stops there (Pi's compact() aborts an active run; it must never cut a tool
+ *   chain), compacts once settled, then resumes with a hidden continuation;
+ * - otherwise the run's own settlement, when nothing is in flight.
+ * Decisions here are pure; extensions/index.ts feeds Pi events in and makes the Pi calls.
+ */
+
+/** Calls covered by the footer's average cost per call. */
+export const RECENT_CALLS = 10;
+/** Provider prompt caches (Anthropic's default TTL, OpenAI's inactivity window) lapse after about this long. */
+export const CACHE_IDLE_MS = 5 * 60_000;
+/** Below this, re-sending the context uncached is not worth a notice. */
+export const CACHE_NOTICE_TOKENS = 100_000;
+/** Hidden prompt that resumes a run stopped at a safe point once compaction finished. */
+export const CONTEXT_CONTINUATION = "pi-jar.context-continuation";
+
+/** One provider request: its prompt size, its cost and when it was sent. */
+export interface ProviderCall { tokens: number; cost: number; at: number }
+export interface BudgetSettle { compact: boolean; resume: boolean }
+export interface BudgetCompaction { resume: boolean; tokens: number | undefined; softTokens: number; open: readonly string[] }
+
+interface UsageLike { input?: unknown; cacheRead?: unknown; cacheWrite?: unknown; cost?: { total?: unknown } }
+const amount = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+
+/** Prompt size of one call: fresh input plus cache reads and writes (its output is only re-sent by the next call). */
+export function contextTokens(usage: UsageLike | undefined): number {
+  return amount(usage?.input) + amount(usage?.cacheRead) + amount(usage?.cacheWrite);
+}
+
+/** The provider call behind an assistant message; none when nothing reached the provider (early abort, no usage). */
+export function providerCall(message: unknown, now: number): ProviderCall | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const { role, usage, timestamp } = message as { role?: unknown; usage?: UsageLike; timestamp?: unknown };
+  if (role !== "assistant") return undefined;
+  const tokens = contextTokens(usage);
+  if (!tokens) return undefined;
+  // The message timestamp is the request time, which is what a provider cache's lifetime counts from.
+  return { tokens, cost: amount(usage?.cost?.total), at: typeof timestamp === "number" && Number.isFinite(timestamp) && timestamp > 0 ? timestamp : now };
+}
+
+/**
+ * Seed for a started, navigated or resumed branch: the latest call costs (oldest first) and the newest call,
+ * unless a later compaction made its size stale. Walks back only as far as the window needs.
+ */
+export function branchCalls(branch: readonly unknown[], now: number): { costs: number[]; last?: ProviderCall } {
+  const costs: number[] = [];
+  let last: ProviderCall | undefined;
+  let compacted = false;
+  for (let index = branch.length - 1; index >= 0 && costs.length < RECENT_CALLS; index--) {
+    const entry = branch[index];
+    if (!entry || typeof entry !== "object") continue;
+    const { type, message } = entry as { type?: unknown; message?: unknown };
+    if (type === "compaction" && !costs.length) compacted = true;
+    if (type !== "message") continue;
+    const call = providerCall(message, now);
+    if (!call) continue;
+    if (!costs.length && !compacted) last = call;
+    costs.push(call.cost);
+  }
+  return { costs: costs.reverse(), ...(last ? { last } : {}) };
+}
+
+/** `950`, `130k`, `1.2M`. */
+export function formatTokens(tokens: number): string {
+  if (tokens < 1000) return String(Math.round(tokens));
+  if (tokens < 999_500) return `${Math.round(tokens / 1000)}k`;
+  return `${(tokens / 1_000_000).toFixed(1)}M`;
+}
+
+function elapsed(ms: number): string {
+  const minutes = Math.floor(ms / 60_000);
+  return minutes < 120 ? `${minutes}m` : minutes < 2880 ? `${Math.floor(minutes / 60)}h` : `${Math.floor(minutes / 1440)}d`;
+}
+
+export class ContextBudgetGuard {
+  private readonly budget: () => ContextBudget;
+  /** Costs of the last RECENT_CALLS calls, oldest first. */
+  private costs: number[] = [];
+  /** Prompt size of the newest call; unknown before the first call and after a compaction. */
+  private tokens: number | undefined;
+  /** When the provider cache was last surely warm: the newest call, or a Pi cache refresh since. */
+  private warmAt: number | undefined;
+  /** A crossing may still notify or compact; re-armed once a call fits the budget again. */
+  private armed = true;
+  /** Compact mode: this crossing's compaction waits for a safe point. */
+  private pending = false;
+  /** This guard stopped the run at a safe point, so the settled run resumes after compacting. */
+  private stopped = false;
+  /** A jar_todo call completed an item during the current turn. */
+  private completed = false;
+  /** The topic-switch hint was shown for the current finished task list. */
+  private topicShown = false;
+
+  constructor(budget: () => ContextBudget) { this.budget = budget; }
+
+  /** Footer chip: the newest call's prompt is past the budget. */
+  get over(): boolean {
+    const { action, softTokens } = this.budget();
+    return action !== "off" && this.tokens !== undefined && this.tokens > softTokens;
+  }
+  /** Average provider cost over the last RECENT_CALLS calls: at most ten additions, no session walk. */
+  get perCall(): number | undefined {
+    return this.costs.length ? this.costs.reduce((sum, cost) => sum + cost, 0) / this.costs.length : undefined;
+  }
+  get lastTokens(): number | undefined { return this.tokens; }
+  /** Settlement has work: a compaction waits, or a stopped run must resume. */
+  get busy(): boolean { return this.pending || this.stopped; }
+
+  /** A new or re-rooted branch: everything starts over from its seed. */
+  reset(seed: { costs?: readonly number[]; last?: ProviderCall } = {}): void {
+    this.costs = (seed.costs ?? []).slice(-RECENT_CALLS);
+    this.tokens = seed.last?.tokens;
+    this.warmAt = seed.last?.at;
+    this.armed = true;
+    this.pending = this.stopped = this.completed = this.topicShown = false;
+  }
+
+  /** One provider call ended; returns the suggest-mode notice for a fresh crossing. */
+  call(call: ProviderCall | undefined): string | undefined {
+    if (!call) return undefined;
+    this.costs.push(call.cost);
+    if (this.costs.length > RECENT_CALLS) this.costs.shift();
+    this.tokens = call.tokens;
+    this.warmAt = Math.max(this.warmAt ?? call.at, call.at);
+    const { action, softTokens } = this.budget();
+    if (call.tokens <= softTokens) { this.armed = true; return undefined; }
+    if (!this.armed || action === "off") return undefined;
+    this.armed = false;
+    if (action === "compact") { this.pending = true; return undefined; }
+    return `Context ${formatTokens(call.tokens)} is past the ${formatTokens(softTokens)} budget — /compact, or /new for the next task`;
+  }
+
+  /** A jar_todo call raised the completed count: a safe point at this turn's end, and a new list for the topic hint. */
+  todoCompleted(): void { this.completed = true; this.topicShown = false; }
+
+  /** Turn end: true when the run should stop here, to compact once settled and then resume. */
+  turnEnd(turn: { open: () => number; interrupted: boolean; blocked: boolean }): boolean {
+    const completed = this.completed;
+    this.completed = false;
+    if (this.stopped || !completed || !this.pending || this.budget().action !== "compact"
+      || turn.interrupted || turn.blocked || turn.open() <= 0) return false;
+    this.stopped = true;
+    return true;
+  }
+
+  /**
+   * Run settled. Compacts when due and nothing else holds the session (another compaction, plan mode); a
+   * pending compaction otherwise waits for the next settlement. A stopped run resumes unless the session is
+   * held, which means the user took over (their own /compact, plan mode).
+   */
+  settle(state: { idle: boolean; blocked: boolean }): BudgetSettle | undefined {
+    const resume = this.stopped;
+    this.stopped = false;
+    if (!state.idle || state.blocked) return undefined;
+    // A request made under another action (the setting changed since) is dropped here.
+    const compact = this.pending && this.budget().action === "compact";
+    this.pending = false;
+    return compact || resume ? { compact, resume } : undefined;
+  }
+
+  /** Any compaction (this guard's, Pi's threshold, /compact): the size is unknown until the next call. */
+  compacted(): void { this.tokens = undefined; this.pending = false; }
+
+  /** Pi refreshed the prompt cache while idle (cache warming), which restarts its lifetime. */
+  warmed(at: number): void { if (this.warmAt !== undefined) this.warmAt = Math.max(this.warmAt, at); }
+
+  /** An interactive prompt to an idle agent: hint /new after a finished task list, and flag a cold cache. */
+  prompt(now: number, todos: { done: number; total: number }): string | undefined {
+    const { action, softTokens } = this.budget();
+    const tokens = this.tokens;
+    if (action === "off" || tokens === undefined) return undefined;
+    const idle = this.warmAt === undefined ? 0 : now - this.warmAt;
+    const cold = idle > CACHE_IDLE_MS && tokens > CACHE_NOTICE_TOKENS;
+    const topic = !this.topicShown && todos.total > 0 && todos.done === todos.total && tokens > softTokens / 2;
+    if (topic) this.topicShown = true;
+    const size = formatTokens(tokens);
+    if (topic && cold) return `All tasks are done and the ${size} context is likely uncached (last call ${elapsed(idle)} ago). For a new task, /new starts fresh; /compact carries a summary over instead.`;
+    if (topic) return `All tasks are done (context ${size}). For an unrelated task, /new starts fresh; /compact carries a summary over instead.`;
+    if (cold) return `Last model call was ${elapsed(idle)} ago: the provider cache has likely expired, so this prompt re-sends ${size} uncached. After a break, /compact first.`;
+    return undefined;
+  }
+}
+
+/** At most six titles of 80 characters: compaction instructions and the continuation stay small. */
+const titles = (open: readonly string[]) => open.slice(0, 6).map((title) => cleanText(title, 80)).join("; ")
+  + (open.length > 6 ? `; +${open.length - 6} more` : "");
+
+/** Continue a run stopped at a safe point; the message is hidden, so the transcript shows only the work. */
+export function resumeAfterBudget(pi: Pick<ExtensionAPI, "sendMessage">, ctx: Pick<ExtensionContext, "ui">, open: readonly string[]): void {
+  const content = "[pi-jar] Context was compacted at a safe point after a task completed; the request is not finished. "
+    + `Continue the open jar_todo tasks${open.length ? ": " + titles(open) : ""}. Use jar_todo to check or update them.`;
+  try { pi.sendMessage({ customType: CONTEXT_CONTINUATION, content, display: false }, { triggerTurn: true }); }
+  catch (error) { ctx.ui.notify(`Could not resume after compaction: ${(error as Error).message}. Send a message to continue.`, "error"); }
+}
+
+/**
+ * Compact once, then resume a run this guard stopped unless the user cancelled. Await it from agent_settled:
+ * Pi defers the resumed turn until settlement handlers return, so print/json runs wait for it and no other
+ * wake-up starts a run mid-compaction. `current` turns false when the session was replaced meanwhile.
+ */
+export async function compactForBudget(pi: Pick<ExtensionAPI, "sendMessage">, ctx: Pick<ExtensionContext, "compact" | "ui">,
+  job: BudgetCompaction, current: () => boolean): Promise<void> {
+  const size = job.tokens === undefined ? "" : " " + formatTokens(job.tokens);
+  ctx.ui.notify(`Context${size} is past the ${formatTokens(job.softTokens)} budget: compacting at a safe point…`, "info");
+  const keep = "Preserve completed work, verification results, key decisions, file paths and open questions.";
+  // Executor form: the project's TS lib target predates Promise.withResolvers.
+  const error = await new Promise<Error | undefined>((resolve) => {
+    try {
+      ctx.compact({ customInstructions: job.open.length ? `${keep} Work continues on these open jar_todo tasks: ${titles(job.open)}.` : keep,
+        onComplete: () => resolve(undefined), onError: resolve });
+    } catch (thrown) { resolve(thrown instanceof Error ? thrown : new Error(String(thrown))); }
+  });
+  if (!current()) return;
+  // Only the user interrupts a compaction (Esc); Pi's other refusals and failures leave the context usable.
+  const userCancelled = error !== undefined && (error.name === "AbortError" || /\b(cancel|abort)/i.test(error.message));
+  if (error && !userCancelled) ctx.ui.notify(`Context compaction failed: ${error.message}${job.resume ? " · continuing without it" : ""}`, "warning");
+  if (job.resume && !userCancelled) resumeAfterBudget(pi, ctx, job.open);
+}