@mono-agent/agent-runtime 0.3.0 → 0.4.1

package/src/ai/providers/codex-app.js

@@ -8,6 +8,7 @@ import { codexModelSupportsFastMode, normalizeFastMode } from "../runtime/fast-m
 import { readRuntimeBrand } from "../../agent/tools/shared/runtime-context.js";
 import { buildCapabilitiesUsed } from "../runtime/capabilities-used.js";
 import { createSessionRegistry } from "../runtime/sessions.js";
+import { createSessionLiveness } from "../runtime/session-liveness.js";
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_THREAD_START_ATTEMPTS = 2;
@@ -223,6 +224,9 @@ function codexCollaborationModePayload(nativeSubagents, { model, effort, systemP
   };
 }
 
+/**
+ * @param {{command?: string, args?: string[], cwd?: any, env?: any, onNotification?: (msg: any) => void}} [options]
+ */
 export function createCodexAppServerClient({
   command = "codex",
   // project_doc_max_bytes=0 keeps codex from injecting its own project docs;
@@ -440,6 +444,11 @@ const codexSessions = createSessionRegistry({
     try { entry.client.close(); } catch {}
   },
 });
+// Synchronous liveness primitives over the registry. Codex only needs the
+// await-free busy claim (its resume handling is simpler than pi's — no durable
+// reopen / create-on-miss reservation), so it consumes claim(); its keep-alive
+// register + deletes stay direct registry ops.
+const codexLiveness = createSessionLiveness(codexSessions);
 
 export async function generateCodexAppResponse(systemPrompt, options = {}) {
   const start = Date.now();
@@ -579,7 +588,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
   }
 
   async function initializeClient(nextClient) {
-    const brand = readRuntimeBrand();
+    const brand = options.toolContext?.runtimeBrand ?? readRuntimeBrand();
     await nextClient.request("initialize", {
       clientInfo: { name: brand.clientInfoName, title: brand.clientInfoTitle, version: "0" },
       capabilities: { experimentalApi: true },
@@ -654,7 +663,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
         ]);
         if (turnCompleted || !turnReadyResolved) break;
       }
-      const input = userTextInput(formatLiveInputGuidance(message.body));
+      const input = userTextInput(formatLiveInputGuidance(message.body, options.prompts));
       try {
         const response = await client.request("turn/steer", {
           threadId,
@@ -730,25 +739,27 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
   }
 
   if (resumeSessionId) {
-    const entry = codexSessions.get(resumeSessionId);
-    if (!entry) {
-      // The host sent no conversation history for a resume, so silently
-      // starting a fresh thread would lose context. Fail fast instead.
-      return sessionUnavailableResult(
-        "session_not_found",
-        `Codex session ${resumeSessionId} is not live; cannot resume`,
-        "codex_session_not_found",
-      );
+    // Await-free busy claim (get -> busy check -> set-busy in one span). A miss
+    // fails fast: the host sent no conversation history for a resume, so silently
+    // starting a fresh thread would lose context. A busy entry is executing a
+    // turn already.
+    const claimed = codexLiveness.claim(resumeSessionId);
+    if (!claimed.ok) {
+      // @ts-check does not narrow the ClaimResult union on `!claimed.ok`,
+      // though the loser branch always carries `reason`.
+      return /** @type {{reason: string}} */ (claimed).reason === "missing"
+        ? sessionUnavailableResult(
+          "session_not_found",
+          `Codex session ${resumeSessionId} is not live; cannot resume`,
+          "codex_session_not_found",
+        )
+        : sessionUnavailableResult(
+          "session_busy",
+          `Codex session ${resumeSessionId} is already executing a turn`,
+          "codex_session_busy",
+        );
     }
-    if (entry.busy) {
-      return sessionUnavailableResult(
-        "session_busy",
-        `Codex session ${resumeSessionId} is already executing a turn`,
-        "codex_session_busy",
-      );
-    }
-    entry.busy = true;
-    resumeEntry = entry;
+    resumeEntry = claimed.entry;
   }
 
   try {
@@ -786,11 +797,13 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
     const fastMode = codexModelSupportsFastMode(resolved.model) && normalizeFastMode(options.fastMode, true);
     if (!resumeEntry) {
       const mcpServers = codexMcpConfig(options.mcpServers);
-      const config = {
+      // Incrementally assembled config handed across the codex app-server
+      // boundary; the reasoning fields below are attached conditionally.
+      const config = /** @type {any} */ ({
         ...(fastMode ? { service_tier: "fast" } : {}),
         features: { fast_mode: fastMode },
         ...(Object.keys(mcpServers).length ? { mcp_servers: mcpServers } : {}),
-      };
+      });
       if (normalizedEffort) {
         config.model_reasoning_effort = normalizedEffort;
         if (normalizedEffort !== "none") config.model_reasoning_summary = "auto";
@@ -807,7 +820,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
         approvalPolicy: approvalPolicyForPermissionMode(options.permissionMode),
         sandbox: sandboxForPermissionMode(options.permissionMode),
         config,
-        serviceName: readRuntimeBrand().serviceName,
+        serviceName: (options.toolContext?.runtimeBrand ?? readRuntimeBrand()).serviceName,
         developerInstructions: systemPrompt,
         ephemeral: true,
         sessionStartSource: "startup",

package/src/ai/providers/opencode-app.js

@@ -164,10 +164,10 @@ async function generateOpencodeAppResponse(systemPrompt, options = {}) {
   };
 
   try {
-    const opencode = await createOpencode({
+    const opencode = await createOpencode(/** @type {any} */ ({
       ...(Object.keys(mcp).length ? { config: { mcp } } : { config: {} }),
       ...(options.abortSignal ? { signal: options.abortSignal } : {}),
-    });
+    }));
     client = opencode.client;
     server = opencode.server;
     options.abortSignal?.addEventListener?.("abort", abortHandler, { once: true });

package/src/ai/providers/opencode-discovery.js

@@ -15,10 +15,10 @@ export async function discoverOpencodeProviders({ createServer = createOpencode
     if (result?.error) {
       const message = typeof result.error === "string"
         ? result.error
-        : (result.error?.message || JSON.stringify(result.error));
+        : (/** @type {any} */ (result.error)?.message || JSON.stringify(result.error));
       throw new Error(message);
     }
-    const providers = result?.data?.providers || result?.providers || [];
+    const providers = result?.data?.providers || /** @type {any} */ (result)?.providers || [];
     return providers.map((provider) => ({
       providerID: provider.id,
       name: provider.name || provider.id,

package/src/ai/providers/pi-errors.js

@@ -0,0 +1,65 @@
+// Shared pi error-normalization helpers.
+//
+// Extracted so the pi-native bridge does not have to import from a sibling
+// provider module. Both the message-normalizer (unwrap nested provider error
+// envelopes) and the context-limit classifier are pure string helpers with no
+// runtime dependencies.
+
+function tryParseJson(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+export function normalizePiErrorMessage(message) {
+  const text = String(message || "").trim();
+  if (!text) return null;
+  const codexMatch = /^Codex error:\s*(\{[\s\S]*\})$/i.exec(text);
+  const parsed = tryParseJson(codexMatch ? codexMatch[1] : text);
+  const nested = parsed?.error || parsed;
+  if (typeof nested?.message === "string" && nested.message.trim()) return nested.message.trim();
+  if (typeof nested?.error?.message === "string" && nested.error.message.trim()) return nested.error.message.trim();
+  return text;
+}
+
+export function isContextLimitError(message) {
+  const text = String(message || "");
+  // Rate-limit wording takes precedence: it is a throttle, not a context overflow.
+  if (/rate limit|too many requests/i.test(text)) return false;
+  // Broadened to catch the many ways providers phrase a context/token overflow:
+  // "context length/window/budget", "max(imum) tokens", "token limit",
+  // "too many tokens", "prompt (is) too long", "exceeds the context/maximum/max",
+  // "input tokens/exceeds", "output token(s)", "token(s) exceed".
+  return /context[_ ](?:length|window|budget)|max(?:imum)?[_ ]?tokens?|token[_ ]limit|too[_ ]many[_ ]tokens?|prompt[_ ](?:is[_ ])?too[_ ]long|exceeds?[_ ](?:the context|maximum|max)|input[_ ](?:tokens?|exceeds)|output[_ ]tokens?|tokens?[_ ]exceed/i.test(text);
+}
+
+// Best-effort extraction of the model's real context-window ceiling from an
+// overflow error. Providers usually state the limit ("maximum context length is
+// 200000 tokens", "context window of 128000", "this model supports at most
+// 32768 tokens"). We use the discovered value to lower the proactive compaction
+// trigger on the running model so a wrong/default contextWindow self-corrects.
+// Returns the smallest plausible token count found, or null.
+export function parseContextLimitFromError(message) {
+  const text = String(message || "");
+  if (!text) return null;
+  // Capture a number that sits next to context/window/token wording, tolerating
+  // separators in large numbers (e.g. "128,000" or "128 000"). Phrases like
+  // "however you requested 210000 tokens" would over-count the limit, so we
+  // anchor on max/limit/context/window wording and take the smallest match.
+  const patterns = [
+    /(?:maximum|max(?:imum)?)\s+context\s+(?:length|window)\s*(?:is|of|=|:)?\s*([\d][\d,_ ]*)/ig,
+    /context\s+(?:length|window|budget)\s*(?:is|of|=|:)?\s*([\d][\d,_ ]*)/ig,
+    /(?:maximum|max(?:imum)?|at most|supports?(?:\s+up\s+to)?)\s+([\d][\d,_ ]*)\s*(?:input\s+)?tokens?/ig,
+    /(?:token|context)\s+limit\s*(?:is|of|=|:)?\s*([\d][\d,_ ]*)/ig,
+  ];
+  const found = [];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const n = Number(String(m[1]).replace(/[,_ ]/g, ""));
+      // Guard against matching small token counts (e.g. "8 tokens") that are not
+      // a real window; a context window is at least a few thousand tokens.
+      if (Number.isFinite(n) && n >= 1000) found.push(n);
+    }
+  }
+  if (found.length === 0) return null;
+  return Math.min(...found);
+}

package/src/ai/providers/pi-events.js

@@ -51,6 +51,11 @@ export function compactToolRawResult(result, resultContent) {
   };
 }
 
+/**
+ * @param {any} toolName
+ * @param {any} args
+ * @param {{cwd?: any, toolLimits?: any}} [options]
+ */
 export function eventToolArgs(toolName, args, { cwd, toolLimits } = {}) {
   return normalizePiBuiltinToolParams(toolName, args || {}, { cwd, toolLimits });
 }

package/src/ai/providers/pi-models.js

@@ -1,4 +1,8 @@
-import { getModel as getPiModel } from "@earendil-works/pi-ai";
+// pi 0.80 moved the static catalog reads off the pi-ai root: `getModel` is now
+// deprecated/compat-only. `getBuiltinModel(provider, id)` from `providers/all`
+// is the non-deprecated replacement — same 2-arg signature, and it returns
+// `undefined` on an unknown provider/model exactly like the old `getModel`.
+import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/all";
 import { readRuntimeBrand } from "../../agent/tools/shared/runtime-context.js";
 
 export const EMPTY_USAGE = {
@@ -20,8 +24,8 @@ function openAiCompatBaseUrl(provider) {
   return /\/v\d+$/.test(baseUrl) ? baseUrl : `${baseUrl}/v1`;
 }
 
-function customProviderName(provider) {
-  return `${readRuntimeBrand().providerModelPrefix}-${provider.id}`;
+function customProviderName(provider, brand) {
+  return `${(brand ?? readRuntimeBrand()).providerModelPrefix}-${provider.id}`;
 }
 
 function customProviderKey(provider, isPrivate) {
@@ -64,7 +68,7 @@ function resolveCustomPiModel(resolved, options) {
   const isPrivate = typeof options.isPrivateProvider === "boolean"
     ? options.isPrivateProvider
     : false;
-  const providerName = customProviderName(provider);
+  const providerName = customProviderName(provider, options.toolContext?.runtimeBrand);
   const pricing = modelRow?.pricing || {};
   return {
     model: {
@@ -90,11 +94,24 @@ function resolveCustomPiModel(resolved, options) {
   };
 }
 
+// `options.customProvider`, when present, takes UNCONDITIONAL precedence for
+// ANY pi model ref resolved in this run — it is not scoped to the specific
+// model reference passed in. A fallback-router chain that mixes a custom-pi
+// entry with a builtin-pi entry therefore routes ALL pi entries in that chain
+// through the same custom provider once options.customProvider is set for the
+// run (the router does not re-derive customProvider per chain entry).
 export function resolvePiRuntimeModel(resolved, options) {
   if (options.customProvider) return resolveCustomPiModel(resolved, options);
   if (resolved.sdk !== "pi") throw new Error(`unsupported pi sdk: ${resolved.sdk}`);
   const provider = resolved.provider;
   const model = getPiModel(provider, resolved.model);
+  if (!model) {
+    // Phrasing matters: this must match ai/failure.js's NON_RETRYABLE_PROVIDER_RE
+    // `model[_ ]not[_ ]found` alternation so the router classifies a catalog miss
+    // as non-retryable and bails cleanly instead of retrying/misclassifying it as
+    // a transient provider_unavailable failure.
+    throw new Error(`pi model not found: ${provider}:${resolved.model}`);
+  }
   return {
     model,
     capabilities: {

package/src/ai/providers/pi-native/compaction-driver.js

@@ -0,0 +1,394 @@
+// @ts-check
+// Context auto-compaction for the pi-native bridge.
+//
+// AUTO-COMPACTION. pi-agent-core performs NO automatic in-loop compaction
+// (shouldCompact/compact are exported helpers its loop never calls), so this
+// bridge DRIVES it: proactively before a turn when the running model's context
+// is near the window, and reactively (compact + single re-prompt) if a turn
+// still overflows. The window auto-tracks the model actually serving the request
+// and self-corrects from any real ceiling stated in an overflow error.
+//
+// DELEGATED to pi where pi provides the primitive: the proactive trigger
+// DECISION runs through pi's shouldCompact() (via piCompactionSettings) and the
+// context-size ESTIMATE runs through pi's estimateContextTokens(). Only the
+// pieces pi does not model stay hand-rolled here: the DRIVING (pi never invokes
+// compaction itself), the discovered-window ceiling learning, and the fixed
+// per-request overhead (system prompt + tool schemas) that estimateContextTokens
+// omits.
+//
+// Pure moves out of pi-native.js: the discovered-window cache (kept at MODULE
+// scope, matching its bridge-level scope before the split), context estimation,
+// the guarded tryCompact, the reactive candidate test, the live compaction
+// policy resolution, and the proactive+reactive hooks. Per-run compaction state
+// (applied / reactiveAttempted / compactedThisRun / policy / diagnostics) lives
+// on the caller-owned runState.compaction.
+
+import {
+  calculateContextTokens,
+  estimateContextTokens,
+  getLastAssistantUsage,
+  shouldCompact,
+} from "@earendil-works/pi-agent-core";
+import {
+  estimateFixedOverheadTokens,
+  isLikelyContextTermination,
+  resolveAgentCompactionPolicy,
+} from "../../../agent/compaction.js";
+import {
+  isContextLimitError,
+  normalizePiErrorMessage,
+  parseContextLimitFromError,
+} from "../pi-errors.js";
+import { appendStructuredOutputInstruction } from "./structured-output.js";
+import { runHarnessPrompt } from "./turn-runner.js";
+
+// Per-process cache of real context-window ceilings discovered from overflow
+// errors, keyed by model reference/id. The long-running host re-learns quickly
+// after a restart; this just spares repeated first-overflow round-trips.
+const discoveredContextWindows = new Map();
+
+function modelWindowKey(harness, runtime, resolved) {
+  const live = typeof harness?.getModel === "function" ? harness.getModel() : null;
+  return resolved?.reference || runtime?.model?.id || live?.id || "unknown";
+}
+
+// The window of the model that ACTUALLY serves this request: prefer the harness's
+// live model (authoritative for native pi models), fall back to the resolved
+// runtime model. Returns 0 when unknown so callers can skip the proactive trigger.
+function liveModelContextWindow(harness, runtime) {
+  const live = typeof harness?.getModel === "function" ? harness.getModel() : null;
+  const win = Number(live?.contextWindow) || Number(runtime?.model?.contextWindow) || 0;
+  return win > 0 ? win : 0;
+}
+
+function effectiveContextWindow(harness, runtime, resolved) {
+  const declared = liveModelContextWindow(harness, runtime);
+  const discovered = discoveredContextWindows.get(modelWindowKey(harness, runtime, resolved));
+  if (Number.isFinite(discovered) && discovered > 0) {
+    return declared > 0 ? Math.min(declared, discovered) : discovered;
+  }
+  return declared;
+}
+
+function recordDiscoveredContextWindow(harness, runtime, resolved, limit) {
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n <= 0) return;
+  const key = modelWindowKey(harness, runtime, resolved);
+  const existing = discoveredContextWindows.get(key);
+  discoveredContextWindows.set(key, Number.isFinite(existing) && existing > 0 ? Math.min(existing, n) : n);
+}
+
+// Best-effort estimate of the current session's context size. The last assistant
+// usage is authoritative (it reflects what the provider actually counted,
+// including cache reads), but it can be stale/zero (e.g. seeded history), so we
+// take the MAX of the usage-based count and pi's estimateContextTokens() over the
+// transcript. Either being large is a reason to compact; overcounting only
+// compacts slightly early.
+//
+// The transcript branch is DELEGATED to pi's estimateContextTokens(): it sums
+// pi's own per-message estimateTokens across session.buildContext().messages,
+// and when a message carries a VALID last-assistant usage it uses usage +
+// trailing-message estimate instead of re-summing the whole transcript. Seeded /
+// faux histories carry no valid usage (faux usage totals 0 tokens, which pi
+// rejects), so it reduces to the pure per-message sum the bridge summed by hand
+// before — a behaviour-neutral swap there, and a more provider-accurate estimate
+// once real usage is present.
+//
+// `fixedOverheadTokens` is the system-prompt + tool-schema + per-turn user
+// message overhead the provider meters but the transcript estimate (which covers
+// only session.buildContext().messages) excludes. It is added to the ESTIMATE
+// branch ONLY: the usage-based count already includes that overhead (it is what
+// the provider actually counted), so adding it there would double-count. With a
+// stale/0 usage and a seeded session the estimate branch wins, and without this
+// the trigger under-counts and the real request overflows.
+export async function estimateCurrentContextTokens(session, fixedOverheadTokens = 0) {
+  let usageTokens = 0;
+  let rawTokens = 0;
+  try {
+    const usage = getLastAssistantUsage(await session.getEntries());
+    if (usage) usageTokens = Number(calculateContextTokens(usage)) || 0;
+  } catch { /* ignore — fall back to the transcript estimate */ }
+  try {
+    const context = await session.buildContext();
+    rawTokens = Number(estimateContextTokens(context?.messages || []).tokens) || 0;
+  } catch { /* ignore — usage-based estimate stands */ }
+  // Apply the fixed overhead to the transcript estimate only (see note above).
+  rawTokens += Number(fixedOverheadTokens) || 0;
+  if (usageTokens === 0 && rawTokens === 0) return { tokens: 0, source: "unavailable" };
+  return usageTokens >= rawTokens
+    ? { tokens: usageTokens, source: "usage" }
+    : { tokens: rawTokens, source: "estimate" };
+}
+
+// Run a single guarded compaction. Requires the harness idle (callers
+// waitForIdle first). Never throws — classifies AgentHarnessError into a warning
+// and reports back whether anything was compacted. Fires onCompactionRecorded on
+// success so a host can persist the compaction row.
+export async function tryCompact(harness, { trigger, onEvent, runtimeWarnings, onCompactionRecorded, runId, model }) {
+  try {
+    const result = await harness.compact();
+    const tokensBefore = Number(result?.tokensBefore) || null;
+    onEvent?.({
+      type: "runtime_warning",
+      warning_kind: "context_compaction_applied",
+      source: "pi",
+      trigger,
+      tokens_before: tokensBefore,
+    });
+    if (typeof onCompactionRecorded === "function") {
+      try {
+        onCompactionRecorded({
+          task_run_id: runId || null,
+          trigger,
+          provider_kind: "pi",
+          model: model || null,
+          tokens_before: tokensBefore,
+          summary: result?.summary || "",
+          first_kept_entry_id: result?.firstKeptEntryId || null,
+          status: "succeeded",
+          created_at: Date.now(),
+        });
+      } catch (err) {
+        runtimeWarnings.push({
+          warning_kind: "context_compaction_record_failed",
+          source: "pi",
+          message: err?.message || String(err),
+        });
+      }
+    }
+    return { applied: true, tokensBefore, nothingToCompact: false };
+  } catch (err) {
+    const message = err?.message || String(err);
+    const code = err?.code;
+    const nothingToCompact = code === "compaction" && /nothing to compact/i.test(message);
+    const warningKind = nothingToCompact
+      ? "context_compaction_nothing_to_compact"
+      : code === "auth"
+        ? "context_compaction_auth_failed"
+        : code === "busy"
+          ? "context_compaction_busy"
+          : "context_compaction_failed";
+    runtimeWarnings.push({ warning_kind: warningKind, source: "pi", trigger, message });
+    return { applied: false, tokensBefore: null, nothingToCompact };
+  }
+}
+
+function isReactiveCompactionCandidate(errorMessage, diagnostics) {
+  if (!errorMessage) return false;
+  return isContextLimitError(errorMessage) || isLikelyContextTermination(errorMessage, diagnostics);
+}
+
+/**
+ * Express the kernel's compaction policy as a pi `CompactionSettings` so the
+ * proactive trigger runs through pi's own `shouldCompact()`.
+ *
+ * EQUIVALENCE (exact, proven by pi-native-compaction-parity.test.js): pi fires
+ * when `contextTokens > contextWindow - reserveTokens` (STRICT `>`), while the
+ * kernel policy fires when `estimate >= triggerTokens` (`>=`). Both `estimate`
+ * and `triggerTokens` are non-negative INTEGERS — pi's `estimateTokens` /
+ * `calculateContextTokens` return `Math.ceil(...)`/summed provider counts, and
+ * `resolveAgentCompactionPolicy` builds `triggerTokens` with `Math.floor` — so
+ * for integers `x >= t` iff `x > t - 1`. Setting
+ *   `reserveTokens = contextWindow - triggerTokens + 1`
+ * gives `contextWindow - reserveTokens = triggerTokens - 1`, hence
+ *   `shouldCompact(x, window, s)` == `x > triggerTokens - 1` == `x >= triggerTokens`.
+ * `triggerTokens < contextWindow` always (it is `min(floor(window*ratio),
+ * window - reserve)` with `ratio <= 0.95`), so `reserveTokens >= 2` — never
+ * degenerate. `keepRecentTokens` is carried through for a faithful settings
+ * object even though `shouldCompact` ignores it.
+ * @param {{enabled: boolean, contextWindow: number, triggerTokens: number, keepRecentTokens: number}} policy
+ * @returns {{enabled: boolean, reserveTokens: number, keepRecentTokens: number}}
+ */
+export function piCompactionSettings(policy) {
+  return {
+    enabled: !!policy.enabled,
+    reserveTokens: policy.contextWindow - policy.triggerTokens + 1,
+    keepRecentTokens: policy.keepRecentTokens,
+  };
+}
+
+/**
+ * Resolve the compaction policy against the LIVE model's context window
+ * (auto-recognized from the model actually serving the request, lowered by any
+ * ceiling learned from a prior overflow). A positive `contextWindowOverride`
+ * (from the typed `compaction` policy object) replaces the auto-recognized
+ * window — it is not a legacy `settings` key, so it is applied here directly
+ * rather than through the settings shim. Drives the proactive trigger +
+ * reactive recovery.
+ * @param {{harness: any, runtime: any, resolved: any, settings: any, contextWindowOverride?: number}} params
+ */
+export function resolveLiveCompactionPolicy({ harness, runtime, resolved, settings, contextWindowOverride }) {
+  const overrideWindow = Number(contextWindowOverride);
+  const contextWindow = Number.isFinite(overrideWindow) && overrideWindow > 0
+    ? overrideWindow
+    : effectiveContextWindow(harness, runtime, resolved);
+  return resolveAgentCompactionPolicy(settings || {}, { contextWindow });
+}
+
+/**
+ * Proactive compaction: if the session is already near the window, compact
+ * BEFORE issuing the request so a long-lived session never overflows. Mutates
+ * runState.compaction (applied / compactedThisRun / diagnostics) and re-anchors
+ * runState.sessionBaselineCount when it fires.
+ * @param {any} runState
+ * @param {any} params
+ */
+export async function runProactiveCompaction(runState, {
+  harness,
+  systemPrompt,
+  options,
+  tools,
+  promptText,
+  promptImages,
+  reference,
+  onEvent,
+  runtimeWarnings,
+}) {
+  const policy = runState.compaction.policy;
+  if (!(policy.enabled && policy.contextWindow > 0 && !options.abortSignal?.aborted)) return;
+  // Fixed per-request overhead the provider meters but the raw transcript
+  // estimate excludes (system prompt + tool/MCP schemas + per-turn user
+  // message + memory). Computed ONCE here from the same inputs the harness
+  // sends to the provider, then folded into the raw estimate so the trigger
+  // reflects the real request size. ON by default (this corrects a real
+  // undercount that lets seeded sessions overflow); set
+  // compaction.fixedOverheadEnabled:false (or the deprecated
+  // agent_compaction_fixed_overhead_enabled:false) restores the prior
+  // transcript-only trigger (overhead = 0). The flag is already resolved onto
+  // policy.fixedOverheadEnabled, so read it there rather than re-sniffing the
+  // raw settings bag. See estimateFixedOverheadTokens.
+  //
+  // Only the TRAILING per-turn user message is passed here, NOT
+  // options.messages. The prior transcript is already summed by the raw
+  // branch via session.buildContext().messages (priorMessages were seeded
+  // into the session above), so passing the whole history would double-count
+  // it. promptText/promptImages (from splitPromptMessages at the run head)
+  // ARE the per-turn turn, so reconstruct that single message for the
+  // estimate — matching estimateFixedOverheadTokens' "per-turn user
+  // message(s)" contract.
+  const perTurnContent = Array.isArray(promptImages) && promptImages.length > 0
+    ? [{ type: "text", text: promptText }, ...promptImages]
+    : promptText;
+  const fixedOverhead = policy.fixedOverheadEnabled !== false
+    ? estimateFixedOverheadTokens({
+      systemPrompt: appendStructuredOutputInstruction(systemPrompt, options.outputSchema, options.prompts),
+      tools,
+      messages: [{ role: "user", content: perTurnContent }],
+    })
+    : { systemPromptTokens: 0, toolSchemaTokens: 0, userMessageTokens: 0, fixedOverheadTokens: 0 };
+  const est = await estimateCurrentContextTokens(runState.session, fixedOverhead.fixedOverheadTokens);
+  // DELEGATED trigger decision: pi's shouldCompact() with the policy mapped to
+  // pi CompactionSettings (see piCompactionSettings — exact `>=`-preserving
+  // mapping). Equivalent to the prior `est.tokens >= policy.triggerTokens`.
+  if (shouldCompact(est.tokens, policy.contextWindow, piCompactionSettings(policy))) {
+    await harness.waitForIdle();
+    if (!options.abortSignal?.aborted) {
+      const res = await tryCompact(harness, {
+        trigger: "proactive",
+        onEvent,
+        runtimeWarnings,
+        onCompactionRecorded: options.onCompactionRecorded,
+        runId: options.runId,
+        model: reference,
+      });
+      if (res.applied) {
+        runState.compaction.applied = true;
+        runState.compaction.compactedThisRun = true;
+        Object.assign(runState.compaction.diagnostics, {
+          context_compaction_proactive: true,
+          context_compaction_tokens_before: res.tokensBefore,
+          context_compaction_estimate_source: est.source,
+          context_window: policy.contextWindow,
+          // Additive observability (A4): the overhead components folded into
+          // the trigger comparison, the trigger itself (read back by
+          // isLikelyContextTermination but otherwise never set), and the
+          // transcript-plus-overhead estimate that fired this compaction.
+          context_fixed_overhead_tokens: fixedOverhead.fixedOverheadTokens,
+          context_system_prompt_tokens: fixedOverhead.systemPromptTokens,
+          context_tool_schema_tokens: fixedOverhead.toolSchemaTokens,
+          context_compaction_trigger_tokens: policy.triggerTokens,
+          context_transcript_estimate: est.tokens,
+        });
+        // Compaction collapses the transcript prefix, so the pre-run baseline
+        // no longer aligns. Re-anchor it to the compacted length so the run's
+        // own turns (issued next) slice out correctly in captureState.
+        runState.sessionBaselineCount = (await runState.session.buildContext()).messages.length;
+      }
+    }
+  }
+}
+
+/**
+ * Reactive recovery: if the turn ended in a context overflow and we have not
+ * already compacted-and-retried this run, compact once and re-prompt once.
+ * Learns the real ceiling from the overflow error. Returns the (possibly
+ * re-captured) state + runError.
+ * @param {any} runState
+ * @param {any} params
+ * @returns {Promise<{state: any, runError: any}>}
+ */
+export async function runReactiveCompaction(runState, {
+  harness,
+  runtime,
+  resolved,
+  options,
+  promptText,
+  promptImages,
+  reference,
+  onEvent,
+  runtimeWarnings,
+  state,
+  runError,
+  captureState,
+}) {
+  const c = runState.compaction;
+  if (!(
+    c.policy?.enabled
+    && !c.reactiveAttempted
+    && !runState.externalAbort
+    && !runState.maxTurnsHit
+    && !options.abortSignal?.aborted
+  )) {
+    return { state, runError };
+  }
+  const provisionalRaw = state.stopReason === "error" || state.stopReason === "aborted"
+    ? state.lastAssistant?.errorMessage || runError?.message || null
+    : (runError ? runError.message || String(runError) : null);
+  const provisionalError = normalizePiErrorMessage(provisionalRaw);
+  if (provisionalError && isReactiveCompactionCandidate(provisionalError, c.diagnostics)) {
+    c.reactiveAttempted = true;
+    // Learn the real ceiling from the error so future runs trigger
+    // proactively at it even when the configured contextWindow was wrong.
+    recordDiscoveredContextWindow(harness, runtime, resolved, parseContextLimitFromError(provisionalError));
+    // A second compaction immediately after a fresh proactive one is almost
+    // always "nothing to compact"; skip it and surface the original error.
+    if (!c.compactedThisRun) {
+      await harness.waitForIdle();
+      const res = await tryCompact(harness, {
+        trigger: "reactive_overflow",
+        onEvent,
+        runtimeWarnings,
+        onCompactionRecorded: options.onCompactionRecorded,
+        runId: options.runId,
+        model: reference,
+      });
+      if (res.applied) {
+        c.applied = true;
+        c.compactedThisRun = true;
+        Object.assign(c.diagnostics, {
+          context_compaction_reactive: true,
+          context_compaction_tokens_before: res.tokensBefore,
+        });
+        // Re-anchor the transcript baseline to the compacted length so the
+        // re-prompt's turn (and its stopReason/usage) slices out correctly.
+        runState.sessionBaselineCount = (await runState.session.buildContext()).messages.length;
+        // Re-prompt ONCE in the now-compacted session. The trailing user turn
+        // is already persisted, so a fresh prompt continues against it.
+        const rerun = await runHarnessPrompt(harness, promptText, promptImages);
+        runError = rerun.runError;
+        state = await captureState();
+      }
+    }
+  }
+  return { state, runError };
+}