@hicaru/pi-rlm 0.3.6 → 0.3.9

package/src/commands/rlm-llm.ts

@@ -0,0 +1,59 @@
+/** `/rlm-llm` — pin the leaf-LLM model (llm_query / llm_batch / map_files). */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { modelRef } from "../config/settings.ts";
+import { cheapestModel } from "../mode/llm-model.ts";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { pickableModels, selectModel } from "../ui/model-picker.ts";
+import { setRlmModeStatus } from "../ui/status.ts";
+import { applyLlmSelection } from "./pins.ts";
+
+/** Newer Pi hosts expose session-scoped models; 0.79 peers do not — duck-type safely. */
+function sessionScopedModels(
+  ctx: ExtensionContext,
+): readonly { readonly model: Model<Api> }[] | undefined {
+  const scoped: unknown = Reflect.get(ctx, "scopedModels");
+  return Array.isArray(scoped) ? scoped as readonly { readonly model: Model<Api> }[] : undefined;
+}
+
+async function runRlmLlm(controller: RlmController, ctx: ExtensionContext): Promise<void> {
+  try {
+    await ctx.modelRegistry.refresh();
+  } catch {
+    // Fail-soft: show the cached available snapshot rather than aborting config.
+  }
+  const models = pickableModels(ctx.modelRegistry, sessionScopedModels(ctx));
+  const llm = await selectModel(
+    ctx,
+    "llm",
+    models,
+    controller.llmModel,
+    controller.config.subSampling.reasoning,
+    controller.savedLlmRef,
+  );
+  applyLlmSelection(controller, llm);
+  const persisted = await controller.persist();
+  if (!persisted) ctx.ui.notify("RLM: failed to save settings to ~/.pi/agent/rlm.json", "error");
+  setRlmModeStatus(ctx, controller, ctx.getContextUsage());
+
+  // Name the model that actually resolved, not "(cheapest)" — otherwise there is no way to
+  // tell whether the free model in the catalog was the one picked.
+  const pinned = controller.llmModel;
+  const effective = pinned ?? cheapestModel(ctx.modelRegistry);
+  const reasoning = controller.config.subSampling.reasoning;
+  ctx.ui.notify(
+    `RLM: llm=${modelRef(effective) ?? "(none available)"}`
+    + `${pinned ? "" : " (cheapest, auto)"}${reasoning ? `/${reasoning}` : ""}`,
+    "info",
+  );
+}
+
+export function registerRlmLlmCommand(pi: ExtensionAPI, controller: RlmController): void {
+  pi.registerCommand("rlm-llm", {
+    description: "Pin the LLM model used by llm_query / llm_batch / map_files sub-calls.",
+    handler: async (_args, ctx) => {
+      await runRlmLlm(controller, ctx);
+    },
+  });
+}

package/src/commands/rlm-rlm.ts

@@ -0,0 +1,58 @@
+/** `/rlm-rlm` — pin the root/worker model for rlm_query / rlm_batch child engines.
+ *
+ * Unpinned (default), child engines follow pi's active session model — exactly
+ * the pre-pin behavior, now an explicit picker row.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { modelRef } from "../config/settings.ts";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { pickableModels, selectModel } from "../ui/model-picker.ts";
+import { setRlmModeStatus } from "../ui/status.ts";
+import { applyRlmSelection } from "./pins.ts";
+
+function sessionScopedModels(
+  ctx: ExtensionContext,
+): readonly { readonly model: Model<Api> }[] | undefined {
+  const scoped: unknown = Reflect.get(ctx, "scopedModels");
+  return Array.isArray(scoped) ? scoped as readonly { readonly model: Model<Api> }[] : undefined;
+}
+
+async function runRlmRlm(controller: RlmController, ctx: ExtensionContext): Promise<void> {
+  try {
+    await ctx.modelRegistry.refresh();
+  } catch {
+    // Fail-soft: show the cached available snapshot rather than aborting config.
+  }
+  const models = pickableModels(ctx.modelRegistry, sessionScopedModels(ctx));
+  const rlm = await selectModel(
+    ctx,
+    "rlm",
+    models,
+    controller.rlmModel,
+    controller.config.rootSampling?.reasoning,
+    controller.savedRlmRef,
+  );
+  applyRlmSelection(controller, rlm);
+  const persisted = await controller.persist();
+  if (!persisted) ctx.ui.notify("RLM: failed to save settings to ~/.pi/agent/rlm.json", "error");
+  setRlmModeStatus(ctx, controller, ctx.getContextUsage());
+
+  const reasoning = controller.config.rootSampling?.reasoning;
+  ctx.ui.notify(
+    controller.rlmModel
+      ? `RLM: rlm=${modelRef(controller.rlmModel) ?? "(none)"}${reasoning ? `/${reasoning}` : ""}`
+      : "RLM: rlm follows session model",
+    "info",
+  );
+}
+
+export function registerRlmRlmCommand(pi: ExtensionAPI, controller: RlmController): void {
+  pi.registerCommand("rlm-rlm", {
+    description: "Pin the model used by rlm_query / rlm_batch child engines (default: session model).",
+    handler: async (_args, ctx) => {
+      await runRlmRlm(controller, ctx);
+    },
+  });
+}

package/src/commands/rlm.ts

@@ -9,7 +9,7 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     description: "Toggle persistent RLM mode (route plain prompts through the RLM engine).",
     handler: async (_args, ctx) => {
       const enabled = controller.toggle();
-      setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+      setRlmModeStatus(ctx, controller, ctx.getContextUsage());
       ctx.ui.notify(`RLM mode ${enabled ? "ON" : "OFF"}`, "info");
     },
   });
@@ -30,7 +30,7 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     description: "Toggle RLM mode (off also stops a running query)",
     handler: async (ctx) => {
       const enabled = controller.toggle();
-      setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+      setRlmModeStatus(ctx, controller, ctx.getContextUsage());
       ctx.ui.notify(`RLM mode ${enabled ? "ON" : "OFF"}`, "info");
     },
   });

package/src/config/defaults.ts

@@ -31,4 +31,21 @@ export const DEFAULT_CONFIG: Readonly<RlmConfig> = Object.freeze({
   rootSampling: Object.freeze({ maxTokens: 16_384 }),
   subSystemPrompt: DEFAULT_SUB_SYSTEM_PROMPT,
   subSampling: Object.freeze({ maxTokens: 8192 }),
+  // v5 token budget cascade — the primary run-length control (wall-clock stays a hang backstop).
+  enableTokenBudget: true,
+  budgetShare: 0.25,
+  budgetSoftFrac: 0.8,
+  budgetTaskCap: 400_000,
+  budgetMaxContinuations: 2,
+  budgetHandoffChars: 4_000,
+  // v5 TaskLedger blackboard
+  enableLedger: true,
+  rlmBudget: 8,
+  // v5 durable memory
+  enableMemory: true,
+  injectNoteTokens: 2_000,
+  evolveEvery: 8,
+  memoryDir: null,
+  // v5 role separation: children delegate (llm + memory/ledger); "legacy" = full child surface.
+  childSurface: "delegation",
 });

package/src/config/settings.ts

@@ -12,6 +12,9 @@ export interface PersistedSettings {
   /** "provider/id" of the pinned sub-LLM, or undefined for "cheapest (auto)".
    *  `null` = explicit "cheapest" clear (omit key on disk). */
   readonly llm?: string | null;
+  /** "provider/id" of the pinned rlm root/worker model, or undefined for "follow session".
+   *  `null` = explicit "follow session model" clear (omit key on disk). */
+  readonly rlm?: string | null;
 }
 
 type MutablePartialRlmConfig = { -readonly [K in keyof RlmConfig]?: RlmConfig[K] };
@@ -45,7 +48,9 @@ function validateThinkingLevel(v: unknown): ThinkingLevel | undefined {
   return typeof v === "string" && Object.hasOwn(THINKING_LEVELS, v) ? (v as ThinkingLevel) : undefined;
 }
 
-function validateConfig(raw: unknown): Partial<RlmConfig> {
+/** Validate an unknown (e.g. hand-edited rlm.json) config blob into a partial — the single
+ *  validation seam; exported for tests. */
+export function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (typeof raw !== "object" || raw === null) return {};
   const r = raw as Record<string, unknown>;
   const out: MutablePartialRlmConfig = {};
@@ -90,6 +95,47 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (contextLoader !== undefined) out.contextLoader = contextLoader;
   const autoSeedCwd = validateBoolean(r.autoSeedCwd);
   if (autoSeedCwd !== undefined) out.autoSeedCwd = autoSeedCwd;
+  // v5 token budget cascade
+  const enableTokenBudget = validateBoolean(r.enableTokenBudget);
+  if (enableTokenBudget !== undefined) out.enableTokenBudget = enableTokenBudget;
+  const budgetShare = validateNumber(r.budgetShare, 0.01);
+  if (budgetShare !== undefined && budgetShare <= 1) out.budgetShare = budgetShare;
+  const budgetSoftFrac = validateNumber(r.budgetSoftFrac, 0.5);
+  if (budgetSoftFrac !== undefined && budgetSoftFrac < 1) out.budgetSoftFrac = budgetSoftFrac;
+  const budgetTaskCap = validateNumber(r.budgetTaskCap, 0);
+  if (budgetTaskCap !== undefined) out.budgetTaskCap = budgetTaskCap;
+  const budgetMaxContinuations = validateNumber(r.budgetMaxContinuations, 0);
+  if (budgetMaxContinuations !== undefined) out.budgetMaxContinuations = budgetMaxContinuations;
+  const budgetHandoffChars = validateNumber(r.budgetHandoffChars, 500);
+  if (budgetHandoffChars !== undefined) out.budgetHandoffChars = budgetHandoffChars;
+  // v5 TaskLedger blackboard
+  const enableLedger = validateBoolean(r.enableLedger);
+  if (enableLedger !== undefined) out.enableLedger = enableLedger;
+  const rlmBudget = validateNumber(r.rlmBudget, 0);
+  if (rlmBudget !== undefined) out.rlmBudget = rlmBudget;
+  // v5 durable memory
+  const enableMemory = validateBoolean(r.enableMemory);
+  if (enableMemory !== undefined) out.enableMemory = enableMemory;
+  const injectNoteTokens = validateNumber(r.injectNoteTokens, 100);
+  if (injectNoteTokens !== undefined) out.injectNoteTokens = injectNoteTokens;
+  const evolveEvery = validateNumber(r.evolveEvery, 0);
+  if (evolveEvery !== undefined) out.evolveEvery = evolveEvery;
+  if (r.memoryDir === null) out.memoryDir = null;
+  else {
+    const memoryDir = validateString(r.memoryDir);
+    if (memoryDir !== undefined) out.memoryDir = memoryDir;
+  }
+  // v5 provider concurrency caps: { provider: minConcurrent }
+  if (typeof r.providerMaxConcurrent === "object" && r.providerMaxConcurrent !== null) {
+    const caps: Record<string, number> = {};
+    for (const [provider, cap] of Object.entries(r.providerMaxConcurrent as Record<string, unknown>)) {
+      const n = validateNumber(cap, 1);
+      if (n !== undefined) caps[provider] = n;
+    }
+    if (Object.keys(caps).length > 0) out.providerMaxConcurrent = Object.freeze(caps);
+  }
+  // v5 child surface doctrine
+  if (r.childSurface === "delegation" || r.childSurface === "legacy") out.childSurface = r.childSurface;
   if (typeof r.subSampling === "object" && r.subSampling !== null) {
     const ss = r.subSampling as Record<string, unknown>;
     const sampling: { maxTokens?: number; temperature?: number; reasoning?: ThinkingLevel } = {};
@@ -99,7 +145,7 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
     if (temperature !== undefined) sampling.temperature = temperature;
     const ssReasoning = validateThinkingLevel(ss.reasoning);
     if (ssReasoning !== undefined) sampling.reasoning = ssReasoning;
-    out.subSampling = sampling;
+    out.subSampling = Object.freeze(sampling);
   }
   if (typeof r.rootSampling === "object" && r.rootSampling !== null) {
     const rs = r.rootSampling as Record<string, unknown>;
@@ -124,6 +170,7 @@ export async function loadSettings(): Promise<PersistedSettings> {
       config: validateConfig(r.config),
       // `worker` is the pre-rename key — still read so an existing pin survives the upgrade.
       llm: validateString(r.llm) ?? validateString(r.worker),
+      rlm: validateString(r.rlm),
     };
   } catch {
     return { config: {} };
@@ -135,13 +182,19 @@ export async function saveSettings(s: PersistedSettings): Promise<boolean> {
     const p = settingsPath();
     await mkdir(dirname(p), { recursive: true });
     const body: Record<string, unknown> = { config: s.config };
+    const mergeDisk = s.llm === undefined || s.rlm === undefined;
+    const existing = mergeDisk ? await loadSettings() : undefined;
     if (s.llm !== undefined) {
       // Explicit: string → write pin, null → omit key (cheapest).
       if (s.llm !== null) body.llm = s.llm;
-    } else {
+    } else if (existing?.llm) {
       // Merge: preserve existing disk pin so config-only saves never strip it.
-      const existing = await loadSettings();
-      if (existing.llm) body.llm = existing.llm;
+      body.llm = existing.llm;
+    }
+    if (s.rlm !== undefined) {
+      if (s.rlm !== null) body.rlm = s.rlm;
+    } else if (existing?.rlm) {
+      body.rlm = existing.rlm;
     }
     await writeFile(p, `${JSON.stringify(body, null, 2)}\n`);
     return true;

package/src/core/answer.ts

@@ -1,7 +1,7 @@
 /** Helpers for detecting and formatting the RLM final answer from a turn's REPL results. */
 
 import type { ReplResult } from "../sandbox/protocol.ts";
-import { truncateOutput } from "../text/parsing.ts";
+import { formatReplStderr } from "../text/repl-output.ts";
 
 /** First non-null final answer across a turn's executed blocks, or null. */
 export function finalAnswerOf(results: readonly ReplResult[]): string | null {
@@ -29,9 +29,10 @@ export function turnHadError(results: readonly ReplResult[]): boolean {
 const SMALL_STDOUT_LIMIT = 800;
 const STDOUT_PREVIEW_LIMIT = 200;
 const STDOUT_TAIL_LIMIT = 200;
-const STDERR_LIMIT = 8_000;
 
-/** The REPL output fed back to the model as the next user message. */
+/** The REPL output fed back to the model as the next user message. Prefixed `REPL stdout:`
+ *  (v5 parity, audit C4): `distillTrajectory` keys on this needle to harvest the working
+ *  set for a budget-capped continuation — without it a hard-cap chain starts blind. */
 export function formatReplOutputs(results: readonly ReplResult[], skippedBlocks = 0): string {
   if (results.length === 0) {
     return "No ```repl``` block found in your response. Write one to interact with the REPL.";
@@ -44,21 +45,21 @@ export function formatReplOutputs(results: readonly ReplResult[], skippedBlocks
     const head = multi ? `[block ${i + 1}]\n` : "";
     const { text, elided } = formatStdout(r);
     hadElision ||= elided;
-    parts[i] = `${head}${text}${formatStderr(r)}`;
+    parts[i] = `${head}${text}${formatReplStderr(r.stderr)}`;
   }
   const body = parts.join("\n\n");
   const skipNote = skippedBlocks > 0
     ? `\n\n[${skippedBlocks} later \`\`\`repl\`\`\` block(s) skipped because an earlier block raised — fix and re-run them]`
     : "";
   // Orientation hint only when the model lost output to elision — otherwise it sees everything.
-  if (!hadElision) return `${body}${skipNote}`;
+  if (!hadElision) return `REPL stdout:\n${body}${skipNote}`;
   // The REPL namespace is persistent across blocks in a turn, so the last block's varNames reflect
   // every variable created in any earlier block too.
   const varNames = results.at(-1)?.varNames ?? [];
   const hint = varNames.length > 0
     ? `REPL vars: ${varNames.join(", ")}`
     : `No REPL vars yet — assign results to variables before printing large outputs.`;
-  return `${body}${skipNote}\n\n${hint}`;
+  return `REPL stdout:\n${body}${skipNote}\n\n${hint}`;
 }
 
 /** Stdout ≤ SMALL_STDOUT_LIMIT flows through verbatim; larger output keeps a short head + a note
@@ -78,7 +79,3 @@ function formatStdout(r: ReplResult): { text: string; elided: boolean } {
   };
 }
 
-function formatStderr(r: ReplResult): string {
-  const err = r.stderr.trim();
-  return err ? `\n[stderr]\n${truncateOutput(err, STDERR_LIMIT)}` : "";
-}

package/src/core/budget.ts

@@ -0,0 +1,182 @@
+/**
+ * Token budget cascade (port of rlm_test v4/v5 `budget.py`).
+ *
+ * The budget is the PRIMARY run-length control: cap = budgetShare × model context window,
+ * one soft wrap-up turn at `softFrac` of the cap, and at the hard cap a deterministic
+ * handoff (`distillTrajectory`) is handed to a fresh continuation run — chain-capped at
+ * `maxContinuations`. Wall-clock timeouts stay only as hang backstops.
+ *
+ * v5 counts the whole tree (root turns + sub-LLM usage) against the cap; the engine feeds
+ * the run's LimitGuard totals in via `observeTotal` after every turn. Each continuation
+ * starts a fresh spend window (v5's offset-anchoring) — the chain total is bounded by
+ * `cap × (1 + maxContinuations)`, never by re-charging prior work.
+ */
+
+import type { ChatMsg } from "../bridge/model.ts";
+import type { RlmConfig } from "./types.ts";
+
+export interface TokenBudgetOptions {
+  readonly softFrac?: number;
+  readonly continuations?: number;
+  readonly maxContinuations?: number;
+}
+
+export type BudgetState = "" | "soft" | "hard";
+
+/** v5 verbatim: the soft wrap-up note prepended to the single turn after crossing soft. */
+export const WRAP_UP_BUDGET: string = Object.freeze(
+  "[budget] ~80% of your token cap — ONE turn left. If the task is answerable NOW, finalize " +
+    '(set answer["ready"] = True). Otherwise print a compact findings dump: what is confirmed, ' +
+    "current file/line or search position, and the exact next step — a fresh continuation picks " +
+    "it up. Do not start new exploration.",
+);
+
+export const DEFAULT_NEXT_STEP: string =
+  Object.freeze("continue the probing that was in flight, then finalize");
+
+/** v5 verbatim template (adapting the finalize spelling to this plugin's REPL). */
+const HANDOFF_TEMPLATE: string = Object.freeze(
+  "A prior RLM run hit its token cap mid-task.\n" +
+    "You are its continuation — pick up EXACTLY where it stopped.\n\n" +
+    "ORIGINAL TASK:\n{query}\n\n" +
+    "CONFIRMED FINDINGS SO FAR:\n{findings}\n\n" +
+    "CURRENT STATE / LAST ACTIONS:\n{state}\n\n" +
+    "NEXT STEP: {next}\n" +
+    "Do not re-do confirmed work; continue from the NEXT STEP and finalize as\n" +
+    'soon as the task is answerable (answer["ready"] = True).',
+);
+
+/** v5's elision marker, used whenever a handoff section is trimmed. */
+const ELISION_MARK = "\n…(+N chars elided [v5 handoff])…\n";
+
+export class TokenBudget {
+  readonly cap: number;
+  readonly softFrac: number;
+  readonly continuations: number;
+  readonly maxContinuations: number;
+  private spent = 0;
+
+  constructor(cap: number, opts: TokenBudgetOptions = {}) {
+    this.cap = Math.max(1, Math.floor(cap));
+    this.softFrac = opts.softFrac ?? 0.8;
+    this.continuations = opts.continuations ?? 0;
+    this.maxContinuations = opts.maxContinuations ?? 2;
+  }
+
+  get soft(): number {
+    return Math.floor(this.cap * this.softFrac);
+  }
+
+  get hard(): number {
+    return this.cap;
+  }
+
+  /** Tokens charged to this run so far (root + sub-LLM, whole tree). */
+  get tokensSpent(): number {
+    return this.spent;
+  }
+
+  /**
+   * Feed the run's cumulative token totals (LimitGuard::usage()) after each turn.
+   * Absolute, not incremental: one budget instance observes exactly one run, which is
+   * what makes a continuation's fresh instance start from zero (v5 offset anchoring).
+   */
+  observeTotal(inputTokens: number, outputTokens: number): void {
+    this.spent = Math.max(0, inputTokens) + Math.max(0, outputTokens);
+  }
+
+  state(): BudgetState {
+    if (this.cap <= 0) return "";
+    if (this.spent >= this.hard) return "hard";
+    if (this.spent >= this.soft) return "soft";
+    return "";
+  }
+
+  canContinue(): boolean {
+    return this.continuations < this.maxContinuations;
+  }
+
+  /** Fresh spend window, one step deeper in the chain. */
+  nextContinuation(): TokenBudget {
+    return new TokenBudget(this.cap, {
+      softFrac: this.softFrac,
+      continuations: this.continuations + 1,
+      maxContinuations: this.maxContinuations,
+    });
+  }
+}
+
+/** Cap derivation (v5 `resolve_budget`): share × context window, clamped by the task cap. */
+export function resolveBudget(contextWindow: number | undefined, config: RlmConfig): TokenBudget {
+  const ctx = contextWindow !== undefined && contextWindow > 0 ? contextWindow : 32_000;
+  const shareCap = Math.floor(ctx * config.budgetShare);
+  const cap = config.budgetTaskCap > 0 ? Math.min(shareCap, config.budgetTaskCap) : shareCap;
+  return new TokenBudget(Math.max(cap, 1), {
+    softFrac: config.budgetSoftFrac,
+    maxContinuations: config.budgetMaxContinuations,
+  });
+}
+
+/**
+ * Truncate at the midpoint so both the head and the tail of the content survive
+ * (v5 semantics: keep the opening context and the most recent actions).
+ */
+export function truncateMid(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const half = Math.max(0, maxChars - ELISION_MARK.length) >> 1;
+  const elided = text.length - (half * 2);
+  return text.slice(0, half) + ELISION_MARK.replace("N", String(elided)) + text.slice(text.length - half);
+}
+
+const QUERY_CHARS = 800;
+const FINDINGS_MAX = 6;
+const FINDINGS_MIN_CHARS = 20;
+const STATE_MAX = 8;
+const STATE_NEEDLE = "REPL stdout";
+const NEXT_STEP_RE = /next|then|will |todo/i;
+
+/**
+ * Deterministic trajectory → handoff (v5 `distill_trajectory`). No LLM call: the model was
+ * just told (soft wrap-up) to print a findings dump, and this harvests it — query, the last
+ * substantive assistant findings, the last REPL states, and the next step.
+ */
+export function distillTrajectory(
+  history: readonly ChatMsg[],
+  query: string,
+  handoffChars = 4_000,
+): string {
+  const findings: string[] = [];
+  for (let i = history.length - 1; i >= 0 && findings.length < FINDINGS_MAX; i--) {
+    const m = history[i];
+    if (m.role === "assistant" && m.content.trim().length > FINDINGS_MIN_CHARS) {
+      findings.push(m.content.trim());
+    }
+  }
+  // v5 parity (audit C4): the next-step hint scans NEWEST-first; the join below is chronological.
+  const next = findings.find((f) => NEXT_STEP_RE.test(f)) ?? DEFAULT_NEXT_STEP;
+  findings.reverse();
+  const states: string[] = [];
+  for (let i = history.length - 1; i >= 0 && states.length < STATE_MAX; i--) {
+    const m = history[i];
+    if (m.role === "user" && m.content.includes(STATE_NEEDLE)) {
+      states.push(m.content.trim());
+    }
+  }
+  states.reverse();
+
+  const querySlice = query.slice(0, QUERY_CHARS);
+  const queryBlock = truncateMid(querySlice, Math.floor(handoffChars * 0.3));
+  const findingsBlock = truncateMid(findings.join("\n\n"), Math.floor(handoffChars * 0.35));
+  const stateBlock = truncateMid(states.join("\n\n"), Math.floor(handoffChars * 0.35));
+
+  return HANDOFF_TEMPLATE
+    .replace("{query}", queryBlock)
+    .replace("{findings}", findingsBlock)
+    .replace("{state}", stateBlock)
+    .replace("{next}", next);
+}
+
+/** The full continuation prompt: `[continuation n]` header + distilled handoff. */
+export function continuationPrompt(n: number, handoff: string): string {
+  return `[continuation ${n}]\n${handoff}`;
+}

package/src/core/compaction.ts

@@ -33,6 +33,52 @@ export function shouldCompact(history: ChatMsg[], deps: CompactionDeps): boolean
   return estimateMessageTokens(history) >= threshold;
 }
 
+/**
+ * v5 G1: elide old tool/repl payload bodies, keep the head (system) and the working-set tail
+ * intact. Runs BEFORE `shouldCompact` — v3 measured −97% tokens on coding tasks with this
+ * alone, often avoiding the summarizer entirely. Head-ONLY elision was a measured v3 bug
+ * (turns grew 3→8): the tail carries the current working set, so the last `keepTurns` turns
+ * are never touched.
+ */
+export function elideOldToolPayloads(
+  history: ChatMsg[],
+  keepTurns = 2,
+  toolChars = 1_500,
+): ChatMsg[] {
+  if (history.length === 0) return history;
+  // Find the assistant message that starts the keepTurns-th-from-last turn; everything from
+  // there on is the protected tail.
+  let tailStart = 0;
+  let seen = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].role === "assistant") {
+      seen++;
+      if (seen >= keepTurns) {
+        tailStart = i;
+        break;
+      }
+    }
+  }
+  if (tailStart === 0) return history; // fewer turns than keepTurns — nothing to elide
+  let changed = false;
+  const marker = "\n…[elided v5-G1]…";
+  const out: ChatMsg[] = new Array<ChatMsg>(history.length); // pre-allocated
+  for (let i = 0; i < history.length; i++) {
+    const m = history[i];
+    if (
+      i < tailStart &&
+      m.role === "user" &&
+      m.content.length > toolChars
+    ) {
+      out[i] = { role: "user", content: m.content.slice(0, toolChars) + marker };
+      changed = true;
+    } else {
+      out[i] = m;
+    }
+  }
+  return changed ? out : history;
+}
+
 /**
  * Summarize the trajectory and return a compacted history: [system, summary(assistant),
  * continue(user)]. The caller continues appending turns from there.