pi-jar 0.2.9 → 0.3.0

package/src/context-budget.ts

@@ -1,226 +0,0 @@
-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);
-}

package/src/context-diet.ts

@@ -1,235 +0,0 @@
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/** Character counts are diagnostics, NOT token estimates: signatures can be opaque ciphertext. */
-export interface ThinkingDietStats {
-  removedThinkingParts: number;
-  removedVisibleChars: number;
-  removedSignatureChars: number;
-}
-/** Superseded `read` results replaced by a stub, and the characters of file text they carried. */
-export interface ReadDietStats {
-  stubbedReads: number;
-  stubbedReadChars: number;
-}
-export type ContextDietStats = ThinkingDietStats & ReadDietStats;
-
-export interface DietMessage {
-  role: string;
-  content?: unknown;
-  toolCallId?: string;
-}
-
-const emptyStats = (): ContextDietStats => ({ removedThinkingParts: 0, removedVisibleChars: 0, removedSignatureChars: 0, stubbedReads: 0, stubbedReadChars: 0 });
-const record = (value: unknown): Record<string, unknown> | undefined =>
-  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-
-/**
- * `details` of a read-cache stub (src/compact-tools.ts). Such a result points at an earlier read
- * instead of carrying file text, so it never supersedes that read.
- */
-export interface ReadStubDetails { unchangedSinceRead: number }
-export const isReadStub = (details: unknown): details is ReadStubDetails => typeof record(details)?.unchangedSinceRead === "number";
-
-const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
-/**
- * Pi's read/edit/write path resolution (odd spaces, `@path`, `~`, file URLs) without probing the
- * filesystem. Undefined for a file URL Pi itself rejects; callers then just don't match the path.
- */
-export function resolveToolPath(path: string, cwd: string): string | undefined {
-  let value = path.replace(UNICODE_SPACES, " ");
-  if (value.startsWith("@")) value = value.slice(1);
-  if (value === "~" || value.startsWith("~/")) value = join(homedir(), value.slice(2));
-  else if (value.startsWith("file://")) {
-    try { value = fileURLToPath(value); } catch { return undefined; }
-  }
-  return resolve(cwd, value);
-}
-
-/**
- * The line window a read returns; Pi treats a missing offset and offsets ≤ 1 alike. Undefined when the
- * arguments are not plain numbers, so an unvalidated request never matches another.
- */
-export function readRangeKey(offset: unknown, limit: unknown): string | undefined {
-  const start = offset === undefined ? 1 : typeof offset === "number" ? Math.max(offset, 1) : undefined;
-  if (start === undefined || (limit !== undefined && typeof limit !== "number")) return undefined;
-  return `${start}:${limit ?? ""}`;
-}
-
-/** Completed prior user turns span [firstUser, boundary); every call there has its result there. */
-interface History { firstUser: number; boundary: number; results: Map<string, number> }
-
-/**
- * The completed prior-user-turn span a projection may rewrite; the complete current reasoning/tool
- * chain is never eligible. Ambiguous, unresolved or boundary-crossing historical tool calls make it
- * undefined, so every projection is a no-op: reducing context is less important than preserving
- * provider sequencing constraints.
- */
-function completedHistory(messages: readonly DietMessage[]): History | undefined {
-  let boundary = -1;
-  for (let index = messages.length - 1; index >= 0; index--) {
-    if (messages[index]!.role === "user") { boundary = index; break; }
-  }
-  const firstUser = messages.findIndex(message => message.role === "user");
-  if (boundary <= 0 || firstUser === boundary) return undefined;
-
-  const calls = new Map<string, number>();
-  const results = new Map<string, number>();
-  for (let index = 0; index < messages.length; index++) {
-    const message = messages[index]!;
-    if (message.role === "toolResult") {
-      const id = message.toolCallId;
-      if (typeof id !== "string" || !id || results.has(id)) return undefined;
-      results.set(id, index);
-    }
-    if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
-    for (const value of message.content) {
-      const part = record(value);
-      if (part?.type !== "toolCall") continue;
-      const id = part.id;
-      if (typeof id !== "string" || !id || calls.has(id)) return undefined;
-      calls.set(id, index);
-    }
-  }
-  for (const [id, index] of calls) {
-    if (index >= boundary) continue;
-    const result = results.get(id);
-    if (result === undefined || result <= index || result >= boundary) return undefined;
-  }
-  // A detached historical result means the original reasoning sequence is not fully known.
-  for (const [id, index] of results) {
-    if (index < boundary && !calls.has(id)) return undefined;
-  }
-  return { firstUser, boundary, results };
-}
-
-/**
- * Opt-in provider-context projection; never edits the session or mutates its messages.
- * Only prior user turns are eligible (see completedHistory).
- */
-export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { messages: T[]; stats: ThinkingDietStats } {
-  const stats: ThinkingDietStats = { removedThinkingParts: 0, removedVisibleChars: 0, removedSignatureChars: 0 };
-  const history = completedHistory(messages);
-  if (!history) return { messages, stats };
-  const { firstUser, boundary } = history;
-
-  let changed = false;
-  const projected = messages.map((message, index) => {
-    if (index < firstUser || index >= boundary || message.role !== "assistant" || !Array.isArray(message.content)) return message;
-    const kept = message.content.filter(value => record(value)?.type !== "thinking");
-    // Retain thinking-only rows unchanged rather than manufacturing empty assistant messages.
-    if (!kept.length || kept.length === message.content.length) return message;
-    for (const value of message.content) {
-      const part = record(value);
-      if (part?.type !== "thinking") continue;
-      stats.removedThinkingParts++;
-      if (typeof part.thinking === "string") stats.removedVisibleChars += part.thinking.length;
-      if (typeof part.thinkingSignature === "string") stats.removedSignatureChars += part.thinkingSignature.length;
-    }
-    changed = true;
-    return { ...message, content: kept } as T;
-  });
-  return { messages: changed ? projected : messages, stats };
-}
-
-/** Total text of an all-text result; undefined when it holds images or unknown parts. */
-function textLength(content: unknown): number | undefined {
-  if (!Array.isArray(content) || !content.length) return undefined;
-  let chars = 0;
-  for (const value of content) {
-    const part = record(value);
-    if (part?.type !== "text" || typeof part.text !== "string") return undefined;
-    chars += part.text.length;
-  }
-  return chars;
-}
-
-interface OpenRead { result: number; path: string; chars: number }
-
-/**
- * Opt-in projection, under the same eligibility as trimCompletedThinking: a `read` result that a later
- * read of the same file and line window, or a successful edit/write of the file, superseded becomes a
- * one-line stub; the toolResult keeps its id, name and position. Only operations inside the read's own
- * completed user turn count. A result's projection is therefore fixed when its turn completes and
- * changes together with the thinking trim, never later: re-projecting an older message after newer
- * ones arrive would re-bill the whole prefix after it (src/workflow-context.ts). Operations issued in
- * the read's own assistant message may have run in parallel with it, so they never supersede it.
- * Read-cache stubs, errors, images and results answered outside their turn are left alone.
- */
-export function stubSupersededReads<T extends DietMessage>(messages: T[], cwd: string): { messages: T[]; stats: ReadDietStats } {
-  const stats: ReadDietStats = { stubbedReads: 0, stubbedReadChars: 0 };
-  const history = completedHistory(messages);
-  if (!history) return { messages, stats };
-  const { firstUser, boundary, results } = history;
-
-  const stubs = new Map<number, string>();
-  const supersede = (read: OpenRead, by: string) => {
-    const stub = `[superseded by a later ${by} of ${read.path}]`;
-    if (stubs.has(read.result) || stub.length >= read.chars) return;
-    stubs.set(read.result, stub);
-    stats.stubbedReads++;
-    stats.stubbedReadChars += read.chars;
-  };
-  for (let start = firstUser; start < boundary;) {
-    // The boundary is a user message, so every completed turn ends at one.
-    let end = start + 1;
-    while (messages[end]!.role !== "user") end++;
-    /** File → line window → newest read of this turn not yet superseded. */
-    const open = new Map<string, Map<string, OpenRead>>();
-    for (let index = start + 1; index < end; index++) {
-      const message = messages[index]!;
-      if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
-      const added: Array<{ file: string; range: string; read: OpenRead }> = [];
-      for (const value of message.content) {
-        const part = record(value);
-        const args = record(part?.arguments);
-        const name = part?.name;
-        if (part?.type !== "toolCall" || (name !== "read" && name !== "edit" && name !== "write") || typeof args?.path !== "string") continue;
-        const result = results.get(part.id as string)!;
-        const outcome = record(messages[result]);
-        const file = resolveToolPath(args.path, cwd);
-        if (result >= end || !file || outcome?.isError === true) continue;
-        if (name !== "read") {
-          for (const read of open.get(file)?.values() ?? []) supersede(read, name);
-          open.delete(file);
-          continue;
-        }
-        const range = readRangeKey(args.offset, args.limit);
-        const chars = range === undefined || isReadStub(outcome?.details) ? undefined : textLength(outcome?.content);
-        if (range === undefined || chars === undefined) continue;
-        const prior = open.get(file)?.get(range);
-        if (prior) supersede(prior, "read");
-        added.push({ file, range, read: { result, path: args.path, chars } });
-      }
-      for (const { file, range, read } of added) {
-        let ranges = open.get(file);
-        if (!ranges) open.set(file, ranges = new Map());
-        ranges.set(range, read);
-      }
-    }
-    start = end;
-  }
-  if (!stubs.size) return { messages, stats };
-  const projected = messages.map((message, index) => {
-    const stub = stubs.get(index);
-    return stub === undefined ? message : { ...message, content: [{ type: "text", text: stub }] } as T;
-  });
-  return { messages: projected, stats };
-}
-
-/** Register a runtime-toggleable diet; caller owns its persisted, opt-in setting. */
-export function registerContextDiet(pi: ExtensionAPI, enabled: () => boolean): { stats: () => ContextDietStats } {
-  let latest = emptyStats();
-  pi.on("context", (event, ctx) => {
-    latest = emptyStats();
-    if (!enabled()) return;
-    const thinking = trimCompletedThinking(event.messages);
-    const reads = stubSupersededReads(thinking.messages, ctx.cwd);
-    latest = { ...thinking.stats, ...reads.stats };
-    if (reads.messages !== event.messages) return { messages: reads.messages };
-  });
-  pi.on("session_start", () => { latest = emptyStats(); });
-  return { stats: () => ({ ...latest }) };
-}