@mono-agent/agent-runtime 0.3.0 → 0.4.1

package/src/agent/compaction.js

@@ -1,6 +1,38 @@
-import { randomUUID } from "node:crypto";
-
-export const COMPACTED_CONTEXT_MARKER = "Compacted prior agent context";
+// @ts-check
+
+// Context-compaction policy + heuristics for the pi-native bridge.
+//
+// The hand-rolled in-loop compaction manager (transformContext/afterToolCall)
+// was retired with the legacy pi-sdk Agent path — the sole pi bridge uses
+// pi-agent-core's AgentHarness, which owns compaction via harness.compact().
+// What remains here are two pure helpers the bridge still consumes:
+//   - resolveAgentCompactionPolicy: derives the context-window compaction
+//     trigger and the tool-output payload limits from settings + the running
+//     model. Pure (no Agent loop), so the bridge computes it directly.
+//   - isLikelyContextTermination: classifies a provider error/termination as a
+//     context-pressure event.
+
+/**
+ * @typedef {Object} AgentCompactionPolicy
+ * @property {boolean} enabled
+ * @property {number} contextWindow
+ * @property {number} triggerRatio
+ * @property {number} triggerTokens
+ * @property {number} keepRecentTokens
+ * @property {number} summaryMaxTokens
+ * @property {boolean} fixedOverheadEnabled
+ * @property {number} compactionMinSavingsTokens
+ * @property {number} toolPayloadCompactionTriggerChars
+ * @property {number} toolPruneTriggerTokens
+ * @property {number} toolTextLimitChars
+ * @property {number} bashOutputLimitChars
+ * @property {number} mcpTextLimitChars
+ * @property {number} searchResultLimit
+ * @property {number} imageInlineMaxBytes
+ * @property {number} toolPayloadMaxBytes
+ * @property {number} mcpCallTimeoutMs
+ * @property {number} mcpCallMaxTotalTimeoutMs
+ */
 
 const DEFAULT_CONTEXT_WINDOW = 128000;
 const DEFAULT_TRIGGER_RATIO = 0.85;
@@ -17,95 +49,49 @@ const DEFAULT_TOOL_TEXT_LIMIT_CHARS = 64000;
 const DEFAULT_BASH_OUTPUT_LIMIT_CHARS = 64000;
 const DEFAULT_MCP_TEXT_LIMIT_CHARS = 48000;
 const DEFAULT_SEARCH_RESULT_LIMIT = 100;
-const DEFAULT_IMAGE_INLINE_MAX_BYTES = 250000;
+// Images are returned to vision models whole (a Read of an image attachment, an
+// MCP screenshot). The byte size is large but token cost is driven by image
+// tokens, not base64 length, so allow multi-MB screenshots through instead of
+// clipping them to a "[truncated]" summary the model can't see. Clamp ceiling
+// (10MB) is enforced in resolveAgentCompactionPolicy.
+const DEFAULT_IMAGE_INLINE_MAX_BYTES = 5_000_000;
 const DEFAULT_TOOL_PAYLOAD_MAX_BYTES = 262144;
 const DEFAULT_MCP_CALL_TIMEOUT_MS = 120000;
-
+// Hard wall clock for a single MCP tool call. Progress notifications reset the
+// inactivity timeout above but must never extend a call past this cap (45 min) —
+// sized for legitimately long tools (audio transcription, ask-the-user waits).
+const DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS = 2_700_000;
+
+/**
+ * @param {*} value
+ * @param {number} fallback
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 function clampNumber(value, fallback, min, max) {
   const n = Number(value);
   if (!Number.isFinite(n)) return fallback;
   return Math.min(Math.max(n, min), max);
 }
 
+/**
+ * @param {*} value
+ * @param {number} fallback
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 function clampInteger(value, fallback, min, max) {
   return Math.floor(clampNumber(value, fallback, min, max));
 }
 
-function jsonString(value) {
-  try { return JSON.stringify(value); } catch { return String(value ?? ""); }
-}
-
-function base64Bytes(data) {
-  const text = String(data || "");
-  if (!text) return 0;
-  const clean = text.includes(",") ? text.slice(text.indexOf(",") + 1) : text;
-  return Math.floor(clean.length * 0.75);
-}
-
-function textPart(value) {
-  if (typeof value === "string") return value;
-  if (!value || typeof value !== "object") return String(value ?? "");
-  if (typeof value.text === "string") return value.text;
-  if (typeof value.thinking === "string") return value.thinking;
-  if (value.type === "image") return `[image ${base64Bytes(value.data)} bytes]`;
-  if (value.type === "toolCall") return `${value.name || "tool"} ${jsonString(value.arguments || value.input || {})}`;
-  return jsonString(value);
-}
-
-function contentText(content) {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) return content.map(textPart).join("\n");
-  return textPart(content);
-}
-
-function messageText(message) {
-  if (!message) return "";
-  const base = contentText(message.content);
-  if (message.role === "toolResult") {
-    return [
-      `Tool result: ${message.toolName || "unknown"}`,
-      message.isError ? "Status: error" : "",
-      base,
-      message.details ? jsonString(message.details) : "",
-    ].filter(Boolean).join("\n");
-  }
-  return base;
-}
-
-export function estimateAgentMessageTokens(message) {
-  const text = messageText(message);
-  let chars = text.length + 12;
-  let imageBytes = 0;
-  const parts = Array.isArray(message?.content) ? message.content : [];
-  for (const part of parts) {
-    if (part?.type === "image") imageBytes += base64Bytes(part.data);
-  }
-  const tokens = Math.ceil(chars / 4) + Math.ceil(imageBytes / 3);
-  return { tokens, chars, imageBytes };
-}
-
-export function estimateAgentMessages(messages = []) {
-  return messages.reduce((acc, message) => {
-    const next = estimateAgentMessageTokens(message);
-    acc.tokens += next.tokens;
-    acc.chars += next.chars;
-    acc.imageBytes += next.imageBytes;
-    return acc;
-  }, { tokens: 0, chars: 0, imageBytes: 0 });
-}
-
-export function estimateFirstTurnInput({ systemPrompt = "", messages = [] } = {}) {
-  const overheadChars = String(systemPrompt || "").length;
-  const overheadTokens = Math.ceil(overheadChars / 4);
-  const messageEstimate = estimateAgentMessages(messages);
-  return {
-    overheadTokens,
-    overheadChars,
-    inputTokens: overheadTokens + messageEstimate.tokens,
-    inputChars: overheadChars + messageEstimate.chars,
-  };
-}
-
+/**
+ * @param {Object<string, *>} [settings]
+ * @param {Object} [model]
+ * @param {number} [model.contextWindow]
+ * @returns {AgentCompactionPolicy}
+ */
 export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
   const contextWindow = clampInteger(model?.contextWindow, DEFAULT_CONTEXT_WINDOW, 32000, 10_000_000);
   const triggerRatio = clampNumber(
@@ -124,6 +110,11 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
     triggerTokens: Math.min(ratioTrigger, reserveTrigger),
     keepRecentTokens: clampInteger(settings.agent_compaction_keep_recent_tokens, DEFAULT_KEEP_RECENT_TOKENS, 4000, 200000),
     summaryMaxTokens: clampInteger(settings.agent_compaction_summary_max_tokens, DEFAULT_SUMMARY_MAX_TOKENS, 1000, 64000),
+    // ON by default; the proactive fixed-overhead correction (system prompt +
+    // tool schemas + per-turn message) is disabled only when explicitly false.
+    // Read by the compaction driver off the resolved policy so it never has to
+    // re-sniff the raw settings/policy inputs.
+    fixedOverheadEnabled: settings.agent_compaction_fixed_overhead_enabled !== false,
     compactionMinSavingsTokens: clampInteger(settings.agent_compaction_min_savings_tokens, DEFAULT_MIN_SAVINGS_TOKENS, 0, 500000),
     toolPayloadCompactionTriggerChars: clampInteger(
       settings.agent_tool_payload_compaction_trigger_chars,
@@ -139,318 +130,194 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
     imageInlineMaxBytes: clampInteger(settings.agent_image_inline_max_bytes, DEFAULT_IMAGE_INLINE_MAX_BYTES, 0, 10 * 1024 * 1024),
     toolPayloadMaxBytes: clampInteger(settings.agent_tool_payload_max_bytes, DEFAULT_TOOL_PAYLOAD_MAX_BYTES, 0, 16 * 1024 * 1024),
     mcpCallTimeoutMs: clampInteger(settings.agent_mcp_call_timeout_ms, DEFAULT_MCP_CALL_TIMEOUT_MS, 1000, Number.MAX_SAFE_INTEGER),
+    mcpCallMaxTotalTimeoutMs: clampInteger(
+      settings.agent_mcp_call_max_total_timeout_ms,
+      DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS,
+      1000,
+      Number.MAX_SAFE_INTEGER,
+    ),
   };
 }
 
-function assistantToolCalls(message) {
-  if (!message || message.role !== "assistant" || !Array.isArray(message.content)) return [];
-  return message.content.filter((part) => part?.type === "toolCall");
-}
-
-function hasToolCalls(message) {
-  return assistantToolCalls(message).length > 0;
-}
-
-function chooseFirstKeptIndex(messages, keepRecentTokens) {
-  if (!Array.isArray(messages) || messages.length <= 2) return -1;
-  let tokens = 0;
-  let start = messages.length;
-  for (let i = messages.length - 1; i >= 0; i -= 1) {
-    tokens += estimateAgentMessageTokens(messages[i]).tokens;
-    if (tokens >= keepRecentTokens) {
-      start = i;
-      break;
-    }
+// --- Typed policy objects <-> deprecated `settings` shim -------------------
+//
+// RuntimeRunOptions now carries typed `toolLimits` / `compaction` policy
+// objects. The DEPRECATED `settings` bag remains a per-group fallback: it is
+// consumed only when the corresponding typed object is ABSENT, and consuming it
+// surfaces one `deprecated_settings_option` runtime_warning per run.
+//
+// resolveAgentCompactionPolicy stays the canonical settings->policy clamp/mapper
+// (its signature is unchanged — worklab deep-imports it). The helpers below
+// project the typed objects back onto the same snake_case settings keys so the
+// resolution goes through that one clamp path unchanged, whether the values came
+// from a typed object or the legacy settings bag.
+
+// Typed toolLimits field -> settings key. `bashTimeoutMs` is intentionally
+// ABSENT: no `agent_bash_*_timeout` setting exists today and this phase does not
+// invent new timeout behavior, so the field is documented on the RuntimeToolLimits
+// typedef but not wired through the settings shim or any tool.
+const TOOL_LIMIT_SETTINGS_KEYS = /** @type {const} */ ({
+  toolTextLimitChars: "agent_tool_text_limit_chars",
+  bashOutputLimitChars: "agent_bash_output_limit_chars",
+  mcpTextLimitChars: "agent_mcp_text_limit_chars",
+  searchResultLimit: "agent_search_result_limit",
+  imageInlineMaxBytes: "agent_image_inline_max_bytes",
+  toolPayloadMaxBytes: "agent_tool_payload_max_bytes",
+  mcpCallTimeoutMs: "agent_mcp_call_timeout_ms",
+  mcpCallMaxTotalTimeoutMs: "agent_mcp_call_max_total_timeout_ms",
+});
+
+// Typed compaction field -> settings key. `contextWindowOverride` is ABSENT: it
+// has no legacy settings equivalent and is applied directly at the live-window
+// resolution site (resolveLiveCompactionPolicy), not through this shim.
+const COMPACTION_SETTINGS_KEYS = /** @type {const} */ ({
+  enabled: "agent_compaction_enabled",
+  triggerRatio: "agent_compaction_trigger_ratio",
+  keepRecentTokens: "agent_compaction_keep_recent_tokens",
+  summaryMaxTokens: "agent_compaction_summary_max_tokens",
+  minSavingsTokens: "agent_compaction_min_savings_tokens",
+  fixedOverheadEnabled: "agent_compaction_fixed_overhead_enabled",
+});
+
+export const DEPRECATED_SETTINGS_WARNING_KIND = "deprecated_settings_option";
+
+/**
+ * @param {Object<string, *>|null|undefined} group
+ * @param {Record<string, string>} keyMap
+ * @param {Object<string, *>} out
+ */
+function copyTypedGroup(group, keyMap, out) {
+  for (const [field, settingKey] of Object.entries(keyMap)) {
+    if (group && group[field] !== undefined) out[settingKey] = group[field];
   }
-  if (start <= 0 || start >= messages.length) return -1;
-
-  while (start > 0 && messages[start]?.role === "toolResult") start -= 1;
-  if (start > 0 && messages[start]?.role === "assistant" && !hasToolCalls(messages[start])) {
-    for (let i = start - 1; i >= 0; i -= 1) {
-      if (messages[i]?.role === "user") {
-        start = i;
-        break;
-      }
-      if (messages[i]?.role === "toolResult") break;
-    }
-  }
-  return start <= 0 ? -1 : start;
 }
 
-function oneLine(value, limit = 220) {
-  const text = String(value || "").replace(/\s+/g, " ").trim();
-  return text.length <= limit ? text : `${text.slice(0, limit - 3).trimEnd()}...`;
-}
-
-function extractPathish(value) {
-  if (!value || typeof value !== "object") return "";
-  return value.file_path || value.path || value.command || value.pattern || value.url || "";
-}
-
-function summarizeCompactedMessages(messages, { maxChars }) {
-  const previousSummaries = [];
-  const userNotes = [];
-  const assistantNotes = [];
-  const toolActions = [];
-  const toolErrors = [];
-  const changedFiles = new Set();
-
-  for (const message of messages) {
-    const text = messageText(message);
-    if (text.includes(COMPACTED_CONTEXT_MARKER)) {
-      previousSummaries.push(oneLine(text, 1000));
-      continue;
-    }
-    if (message.role === "user") {
-      userNotes.push(oneLine(text));
-      continue;
-    }
-    if (message.role === "assistant") {
-      const toolCalls = assistantToolCalls(message);
-      if (toolCalls.length) {
-        for (const call of toolCalls) {
-          const args = call.arguments || call.input || {};
-          const pathish = extractPathish(args);
-          toolActions.push(`${call.name || "tool"}${pathish ? `: ${oneLine(pathish, 180)}` : ""}`);
-          if (["Write", "Edit"].includes(call.name) && args.file_path) changedFiles.add(args.file_path);
-        }
-      } else {
-        assistantNotes.push(oneLine(text));
-      }
-      continue;
-    }
-    if (message.role === "toolResult") {
-      const details = message.details || {};
-      const params = details.params || details.input || {};
-      const pathish = extractPathish(params);
-      toolActions.push(`${message.toolName || details.tool || "tool"} result${pathish ? `: ${oneLine(pathish, 180)}` : ""}`);
-      const changes = details.changes || params.changes || [];
-      for (const change of Array.isArray(changes) ? changes : []) {
-        if (change?.path) changedFiles.add(change.path);
-      }
-      if (message.isError) toolErrors.push(oneLine(text, 300));
+/**
+ * @param {Object<string, *>|null|undefined} settings
+ * @param {Record<string, string>} keyMap
+ * @param {Object<string, *>} out
+ * @param {Array<string>} consumed
+ */
+function copySettingsGroup(settings, keyMap, out, consumed) {
+  if (!settings || typeof settings !== "object") return;
+  for (const settingKey of Object.values(keyMap)) {
+    if (settings[settingKey] !== undefined) {
+      out[settingKey] = settings[settingKey];
+      consumed.push(settingKey);
     }
   }
-
-  const sections = [
-    previousSummaries.length ? ["Historical context from previous compactions:", ...previousSummaries.slice(-6).map((item) => `- ${item}`)].join("\n") : "",
-    userNotes.length ? ["Recent user/task instructions from compacted prefix:", ...userNotes.slice(-8).map((item) => `- ${item}`)].join("\n") : "",
-    assistantNotes.length ? ["Agent progress from compacted prefix:", ...assistantNotes.slice(-8).map((item) => `- ${item}`)].join("\n") : "",
-    toolActions.length ? ["Tool activity from compacted prefix:", ...toolActions.slice(-20).map((item) => `- ${item}`)].join("\n") : "",
-    changedFiles.size ? ["Files likely touched before compaction:", ...[...changedFiles].slice(0, 20).map((item) => `- ${item}`)].join("\n") : "",
-    toolErrors.length ? ["Tool errors observed before compaction:", ...toolErrors.slice(-8).map((item) => `- ${item}`)].join("\n") : "",
-  ].filter(Boolean);
-
-  const summary = sections.join("\n\n") || "Prior context contained no compactable text.";
-  return summary.length <= maxChars
-    ? summary
-    : `${summary.slice(0, Math.max(0, maxChars - 40)).trimEnd()}\n[compaction summary truncated]`;
-}
-
-function buildCompactionMessage({ id, seq, metrics, firstKeptIndex, compactedCount, summary }) {
-  return {
-    role: "user",
-    timestamp: Date.now(),
-    content: [
-      `# ${COMPACTED_CONTEXT_MARKER}`,
-      "",
-      `Compaction id: ${id}`,
-      `Compaction sequence: ${seq}`,
-      `Compacted messages: ${compactedCount}`,
-      `First kept message index: ${firstKeptIndex}`,
-      `Estimated tokens before compaction: ${metrics.before.tokens}`,
-      `Estimated tokens after compaction: ${metrics.after.tokens}`,
-      "",
-      "The raw earlier transcript was compacted to keep this long autonomous session within the model context window. Continue from the current workspace state and the recent uncompressed messages below.",
-      "",
-      summary,
-    ].join("\n"),
-  };
 }
 
-function firstNonEmptyLine(text) {
-  for (const raw of String(text || "").split(/\r?\n/)) {
-    const line = raw.trim();
-    if (line) return line;
+/**
+ * Fold the typed `toolLimits` / `compaction` policy objects and the deprecated
+ * `settings` bag into ONE settings-like object resolveAgentCompactionPolicy
+ * consumes, honoring PER-GROUP precedence: when a typed object is present its
+ * fields win and the legacy settings keys for that group are ignored entirely;
+ * when the typed object is absent, that group's settings keys are consumed (and
+ * reported in `consumedSettingsKeys` so the caller can emit exactly one
+ * deprecation warning per run).
+ * @param {{toolLimits?: Object<string, *>, compaction?: Object<string, *>, settings?: Object<string, *>}} [options]
+ * @returns {{settingsLike: Object<string, *>, consumedSettingsKeys: Array<string>}}
+ */
+export function resolveRuntimePolicyInputs({ toolLimits, compaction, settings } = {}) {
+  /** @type {Object<string, *>} */
+  const settingsLike = {};
+  /** @type {Array<string>} */
+  const consumedSettingsKeys = [];
+
+  if (toolLimits && typeof toolLimits === "object") {
+    copyTypedGroup(toolLimits, TOOL_LIMIT_SETTINGS_KEYS, settingsLike);
+  } else {
+    copySettingsGroup(settings, TOOL_LIMIT_SETTINGS_KEYS, settingsLike, consumedSettingsKeys);
   }
-  return "";
-}
 
-function summarizeToolResultBody(message) {
-  const parts = Array.isArray(message?.content) ? message.content : [];
-  let textChars = 0;
-  let firstSnippet = "";
-  let imageCount = 0;
-  let imageBytes = 0;
-  for (const part of parts) {
-    if (part?.type === "text") {
-      const t = String(part.text || "");
-      textChars += t.length;
-      if (!firstSnippet) firstSnippet = firstNonEmptyLine(t);
-    } else if (part?.type === "image") {
-      imageCount += 1;
-      imageBytes += base64Bytes(part.data);
-    }
+  if (compaction && typeof compaction === "object") {
+    copyTypedGroup(compaction, COMPACTION_SETTINGS_KEYS, settingsLike);
+  } else {
+    copySettingsGroup(settings, COMPACTION_SETTINGS_KEYS, settingsLike, consumedSettingsKeys);
   }
-  const facts = [];
-  if (textChars > 0) facts.push(`${textChars} text chars`);
-  if (imageCount > 0) facts.push(`${imageCount} image${imageCount === 1 ? "" : "s"} (~${imageBytes} bytes)`);
-  if (message?.isError) facts.push("status: error");
-  if (firstSnippet) {
-    const snip = firstSnippet.length > 160 ? `${firstSnippet.slice(0, 160).trimEnd()}…` : firstSnippet;
-    facts.push(`first line: "${snip}"`);
-  }
-  return facts.join("; ");
-}
 
-// Replace older tool_result bodies with a 1–3 sentence lossy summary
-// instead of dropping them. Keeps the agent able to reason about prior
-// work (filename, byte count, error status, first-line excerpt) without
-// paying the original payload cost. The full payload remains on disk
-// under <runArtifactDir>/tool-output/ for explicit re-fetch via the
-// artifact path that tool-bloat.js records in details.
-function pruneToolResultContent(message, metrics) {
-  const details = {
-    ...(message.details || {}),
-    context_pruned: true,
-    pruned_tokens_estimate: metrics.tokens,
-    pruned_chars_estimate: metrics.chars,
-  };
-  const toolLabel = message.toolName || details.tool || "tool";
-  const artifact = details.artifact_path || details.full_output_path || details.path || null;
-  const summary = summarizeToolResultBody(message);
-  const lines = [
-    `[older ${toolLabel} result, summarized to free ~${metrics.tokens} tokens of context]`,
-  ];
-  if (summary) lines.push(summary);
-  if (artifact) lines.push(`Full output preserved at: ${artifact}`);
-  else lines.push("Re-issue a targeted tool call (narrower query / smaller range) if the raw payload is needed again.");
-  const content = [{ type: "text", text: lines.join("\n") }];
-  return { ...message, content, details };
+  return { settingsLike, consumedSettingsKeys };
 }
 
-function pruneOldToolResults(messages, policy) {
-  if (!Array.isArray(messages) || !policy?.toolPruneTriggerTokens) {
-    return { changed: false, messages, prunedCount: 0, tokensBefore: 0, tokensAfter: 0 };
-  }
-  const firstProtectedIndex = chooseFirstKeptIndex(messages, policy.keepRecentTokens);
-  if (firstProtectedIndex <= 0) {
-    return { changed: false, messages, prunedCount: 0, tokensBefore: 0, tokensAfter: 0 };
-  }
-
-  let prunableTokens = 0;
-  const metricsByIndex = new Map();
-  for (let i = 0; i < firstProtectedIndex; i += 1) {
-    if (messages[i]?.role !== "toolResult") continue;
-    if (messages[i]?.details?.context_pruned) continue;
-    const metrics = estimateAgentMessageTokens(messages[i]);
-    prunableTokens += metrics.tokens;
-    metricsByIndex.set(i, metrics);
-  }
-  if (prunableTokens < policy.toolPruneTriggerTokens) {
-    return { changed: false, messages, prunedCount: 0, tokensBefore: prunableTokens, tokensAfter: prunableTokens };
-  }
-
-  let prunedCount = 0;
-  const next = messages.map((message, index) => {
-    const metrics = metricsByIndex.get(index);
-    if (!metrics) return message;
-    prunedCount += 1;
-    return pruneToolResultContent(message, metrics);
-  });
-  const tokensAfter = [...metricsByIndex.keys()]
-    .reduce((sum, index) => sum + estimateAgentMessageTokens(next[index]).tokens, 0);
+/**
+ * Build the one-per-run deprecation warning fired when the legacy `settings`
+ * bag was consumed as a policy fallback. Shape matches the other pi/claude
+ * bridge runtime warnings ({warning_kind, source, message}).
+ * @param {ReadonlyArray<string>} consumedKeys
+ * @returns {{warning_kind: string, source: string, message: string, settings_keys: Array<string>}}
+ */
+export function deprecatedSettingsWarning(consumedKeys) {
+  const keys = Array.from(consumedKeys || []);
   return {
-    changed: prunedCount > 0,
-    messages: next,
-    prunedCount,
-    tokensBefore: prunableTokens,
-    tokensAfter,
+    warning_kind: DEPRECATED_SETTINGS_WARNING_KIND,
+    source: "runtime",
+    message:
+      "runOptions.settings is deprecated; pass the typed `toolLimits` / `compaction` policy objects instead "
+      + "(host migration helper: resolveRuntimePolicies in @mono-agent/runtime-adapter). Consumed settings keys: "
+      + `${keys.join(", ")}.`,
+    settings_keys: keys,
   };
 }
 
-function replaceMessagesInPlace(target, next) {
-  if (!Array.isArray(target) || target === next) return next;
-  target.splice(0, target.length, ...next);
-  return target;
-}
-
-function truncateText(text, limit, label) {
-  const value = String(text || "");
-  if (value.length <= limit) {
-    return { text: value, truncated: false, originalLength: value.length };
+// Estimate the FIXED per-request overhead the provider meters but the raw
+// transcript estimate excludes: the system prompt, the tool/MCP schemas, and the
+// per-turn user message(s). estimateCurrentContextTokens' raw branch sums ONLY
+// session.buildContext().messages (the transcript), so on a seeded session whose
+// last-assistant usage is stale/0 the proactive-compaction trigger under-counts
+// and under-fires, letting the real request overflow the window. Adding this
+// overhead to the raw estimate makes the trigger reflect what the provider counts.
+//
+// Uses Math.ceil(len/4) to mirror pi-ai's chars/4 heuristic — consistency with
+// the transcript estimate matters more than precision. Pure + dependency-free.
+/**
+ * @param {Object} [options]
+ * @param {string} [options.systemPrompt]
+ * @param {Array<Object>} [options.tools]
+ * @param {Array<Object>} [options.messages]
+ * @returns {{systemPromptTokens: number, toolSchemaTokens: number, userMessageTokens: number, fixedOverheadTokens: number}}
+ */
+export function estimateFixedOverheadTokens({ systemPrompt, tools, messages } = {}) {
+  const tokensForChars = (value) => Math.ceil(String(value ?? "").length / 4);
+
+  const systemPromptTokens = tokensForChars(systemPrompt);
+
+  let toolSchemaTokens = 0;
+  for (const tool of Array.isArray(tools) ? tools : []) {
+    try {
+      const serialized = JSON.stringify({
+        name: tool?.name,
+        description: tool?.description,
+        parameters: tool?.parameters ?? tool?.inputSchema ?? {},
+      });
+      toolSchemaTokens += tokensForChars(serialized);
+    } catch {
+      // Circular/unserializable tool schema — count it as 0 rather than throw.
+    }
   }
-  // First-class truncation marker: tells the model exactly what was cut and
-  // what it should do about it. The audit found agents failing tasks because
-  // they didn't notice silent ellipses — be loud and actionable.
-  const totalKb = Math.round(value.length / 1024);
-  const shownKb = Math.round(limit / 1024);
-  const marker = [
-    "",
-    `[!!! ${label || "tool"} OUTPUT TRUNCATED — ${shownKb}KB of ${totalKb}KB shown above. The tool returned ${value.length - limit} more characters that you cannot see.]`,
-    "If those characters matter for the task, narrow the query (smaller range, more specific pattern) or paginate. Don't assume the missing tail is empty.",
-  ].join("\n");
-  return {
-    text: `${value.slice(0, Math.max(0, limit - marker.length))}${marker}`,
-    truncated: true,
-    originalLength: value.length,
-  };
-}
 
-export function compactToolResultForContext(result, policy, { toolName = "tool" } = {}) {
-  if (!Array.isArray(result?.content) || !policy) return { changed: false, result };
-  const limit = toolName === "Bash" ? policy.bashOutputLimitChars : policy.toolTextLimitChars;
-  let changed = false;
-  let originalTextChars = 0;
-  let keptTextChars = 0;
-  let omittedImages = 0;
-  const content = result.content.map((part) => {
-    if (part?.type === "text") {
-      const truncated = truncateText(part.text || "", limit, toolName);
-      originalTextChars += truncated.originalLength;
-      keptTextChars += truncated.text.length;
-      if (truncated.truncated) changed = true;
-      return { ...part, text: truncated.text };
-    }
-    if (part?.type === "image") {
-      const bytes = base64Bytes(part.data);
-      if (policy.imageInlineMaxBytes >= 0 && bytes > policy.imageInlineMaxBytes) {
-        changed = true;
-        omittedImages += 1;
-        return {
-          type: "text",
-          text: `[omitted inline image from ${toolName}: ${bytes} bytes exceeds ${policy.imageInlineMaxBytes} byte context budget]`,
-        };
-      }
-      return part;
+  let userMessageTokens = 0;
+  for (const message of Array.isArray(messages) ? messages : []) {
+    try {
+      userMessageTokens += tokensForChars(JSON.stringify(message?.content ?? ""));
+    } catch {
+      // Unserializable content — count it as 0 rather than throw.
     }
-    const serialized = jsonString(part);
-    const truncated = truncateText(serialized, limit, toolName);
-    originalTextChars += truncated.originalLength;
-    keptTextChars += truncated.text.length;
-    if (truncated.truncated || truncated.text !== serialized) changed = true;
-    return { type: "text", text: truncated.text };
-  });
+  }
 
-  if (!changed) return { changed: false, result };
   return {
-    changed: true,
-    result: {
-      ...result,
-      content,
-      details: {
-        ...(result.details || {}),
-        context_compacted: true,
-        original_text_chars: originalTextChars || null,
-        kept_text_chars: keptTextChars || null,
-        omitted_images: omittedImages || null,
-        text_limit_chars: limit,
-        image_inline_max_bytes: policy.imageInlineMaxBytes,
-      },
-    },
+    systemPromptTokens,
+    toolSchemaTokens,
+    userMessageTokens,
+    fixedOverheadTokens: systemPromptTokens + toolSchemaTokens + userMessageTokens,
   };
 }
 
+/**
+ * @param {string} message
+ * @param {Object<string, *>} [diagnostics]
+ * @returns {boolean}
+ */
 export function isLikelyContextTermination(message, diagnostics = {}) {
   const text = String(message || "");
   if (!/terminated|aborted before final output|aborted before final|stream.*aborted|context window|context budget/i.test(text)) return false;
@@ -460,293 +327,3 @@ export function isLikelyContextTermination(message, diagnostics = {}) {
   const trigger = Number(diagnostics.context_compaction_trigger_tokens || 0);
   return Boolean(trigger > 0 && estimate >= trigger * 0.85);
 }
-
-export function createAgentCompactionManager({
-  runId,
-  providerKind,
-  modelReference,
-  model,
-  settings = {},
-  onEvent,
-  onCompactionRecorded,
-} = {}) {
-  const policy = resolveAgentCompactionPolicy(settings, model);
-  let compactionCount = 0;
-  let toolResultsCompacted = 0;
-  let toolResultsPruned = 0;
-  let toolPayloadCharsSinceCompaction = 0;
-  let maxToolPayloadCharsSinceCompaction = 0;
-  let forcedCompactionReason = null;
-  let maxContextTokensEstimate = 0;
-  let lastCompactionId = null;
-  let lastError = null;
-  let skippedLowSavings = 0;
-  let lastLowSavingsSkipTokens = 0;
-
-  function emit(event) {
-    onEvent?.(event);
-  }
-
-  // The host owns persistence: it receives the structured
-  // record below and writes it into `run_compactions`. The kernel emits a
-  // runtime_warning if the host's callback throws.
-  function record(row) {
-    if (!onCompactionRecorded || !runId) return;
-    const persisted = {
-      id: row.id,
-      task_run_id: runId,
-      seq: row.seq,
-      trigger: row.trigger,
-      provider_kind: providerKind || null,
-      model: modelReference || model?.id || null,
-      tokens_before: row.tokensBefore || null,
-      tokens_after: row.tokensAfter || null,
-      chars_before: row.charsBefore || null,
-      chars_after: row.charsAfter || null,
-      first_kept_index: row.firstKeptIndex ?? null,
-      summary: row.summary || "",
-      metadata_json: JSON.stringify(row.metadata || {}),
-      status: row.status || "succeeded",
-      error_text: row.errorText || null,
-      created_at: Date.now(),
-    };
-    try {
-      onCompactionRecorded(persisted);
-    } catch (err) {
-      lastError = err?.message || String(err);
-      emit({
-        type: "runtime_warning",
-        warning_kind: "context_compaction_record_failed",
-        message: lastError,
-      });
-    }
-  }
-
-  async function transformContext(messages = [], signal) {
-    const original = estimateAgentMessages(messages);
-    maxContextTokensEstimate = Math.max(maxContextTokensEstimate, original.tokens);
-    if (!policy.enabled || signal?.aborted) return messages;
-
-    let workingMessages = messages;
-    const pruned = pruneOldToolResults(workingMessages, policy);
-    if (pruned.changed) {
-      workingMessages = replaceMessagesInPlace(messages, pruned.messages);
-      toolResultsPruned += pruned.prunedCount;
-      toolPayloadCharsSinceCompaction = 0;
-      const afterPrune = estimateAgentMessages(workingMessages);
-      emit({
-        type: "tool_context_pruned",
-        run_id: runId || null,
-        pruned_tool_results: pruned.prunedCount,
-        tokens_before: original.tokens,
-        tokens_after: afterPrune.tokens,
-        tokens_saved: original.tokens - afterPrune.tokens,
-        pruned_tool_tokens_before: pruned.tokensBefore,
-        pruned_tool_tokens_after: pruned.tokensAfter,
-        pruned_tool_tokens_saved: pruned.tokensBefore - pruned.tokensAfter,
-      });
-    }
-
-    const before = estimateAgentMessages(workingMessages);
-    const trigger = forcedCompactionReason || (before.tokens >= policy.triggerTokens ? "token_budget" : null);
-    const lowSavingsBackoff = policy.compactionMinSavingsTokens > 0
-      && before.tokens <= lastLowSavingsSkipTokens + Math.max(1000, Math.floor(policy.compactionMinSavingsTokens / 2));
-    if (!trigger || lowSavingsBackoff) return workingMessages;
-
-    const firstKeptIndex = chooseFirstKeptIndex(workingMessages, policy.keepRecentTokens);
-    if (firstKeptIndex <= 0) return workingMessages;
-
-    const id = `cmp_${randomUUID()}`;
-    const seq = compactionCount + 1;
-    emit({
-      type: "context_compaction_started",
-      id,
-      run_id: runId || null,
-      seq,
-      trigger,
-      tokens_before: before.tokens,
-      trigger_tokens: policy.triggerTokens,
-      keep_recent_tokens: policy.keepRecentTokens,
-    });
-
-    try {
-      const compacted = workingMessages.slice(0, firstKeptIndex);
-      const recent = workingMessages.slice(firstKeptIndex);
-      const summaryMaxChars = Math.max(4000, policy.summaryMaxTokens * 4);
-      const summary = summarizeCompactedMessages(compacted, { maxChars: summaryMaxChars });
-      const provisional = [
-        {
-          role: "user",
-          content: summary,
-          timestamp: Date.now(),
-        },
-        ...recent,
-      ];
-      const after = estimateAgentMessages(provisional);
-      const summaryMessage = buildCompactionMessage({
-        id,
-        seq,
-        metrics: { before, after },
-        firstKeptIndex,
-        compactedCount: compacted.length,
-        summary,
-      });
-      const nextMessages = [summaryMessage, ...recent];
-      const finalAfter = estimateAgentMessages(nextMessages);
-      const savingsTokens = before.tokens - finalAfter.tokens;
-      const emergencyTriggerTokens = Math.floor(policy.contextWindow * 0.95);
-      if (
-        policy.compactionMinSavingsTokens > 0
-        && savingsTokens < policy.compactionMinSavingsTokens
-        && before.tokens < emergencyTriggerTokens
-      ) {
-        skippedLowSavings += 1;
-        lastLowSavingsSkipTokens = before.tokens;
-        forcedCompactionReason = null;
-        emit({
-          type: "runtime_warning",
-          warning_kind: "context_compaction_skipped_low_savings",
-          message: `Skipped context compaction because estimated savings were ${savingsTokens} tokens below the ${policy.compactionMinSavingsTokens} token minimum.`,
-          diagnostics: {
-            trigger,
-            tokens_before: before.tokens,
-            tokens_after: finalAfter.tokens,
-            savings_tokens: savingsTokens,
-            min_savings_tokens: policy.compactionMinSavingsTokens,
-          },
-        });
-        return workingMessages;
-      }
-      compactionCount += 1;
-      lastCompactionId = id;
-      record({
-        id,
-        seq,
-        trigger,
-        tokensBefore: before.tokens,
-        tokensAfter: finalAfter.tokens,
-        charsBefore: before.chars,
-        charsAfter: finalAfter.chars,
-        firstKeptIndex,
-        summary,
-        metadata: {
-          context_window: policy.contextWindow,
-          trigger_tokens: policy.triggerTokens,
-          keep_recent_tokens: policy.keepRecentTokens,
-          min_savings_tokens: policy.compactionMinSavingsTokens,
-          savings_tokens: savingsTokens,
-          tool_payload_chars_since_compaction: toolPayloadCharsSinceCompaction,
-          compacted_messages: compacted.length,
-          kept_messages: recent.length,
-        },
-      });
-      toolPayloadCharsSinceCompaction = 0;
-      forcedCompactionReason = null;
-      emit({
-        type: "context_compaction_completed",
-        id,
-        run_id: runId || null,
-        seq,
-        tokens_before: before.tokens,
-        tokens_after: finalAfter.tokens,
-        tokens_saved: savingsTokens,
-        chars_before: before.chars,
-        chars_after: finalAfter.chars,
-        compacted_messages: compacted.length,
-        kept_messages: recent.length,
-        first_kept_index: firstKeptIndex,
-      });
-      return replaceMessagesInPlace(messages, nextMessages);
-    } catch (err) {
-      lastError = err?.message || String(err);
-      record({
-        id,
-        seq,
-        trigger,
-        tokensBefore: before.tokens,
-        charsBefore: before.chars,
-        firstKeptIndex,
-        summary: "",
-        status: "failed",
-        errorText: lastError,
-      });
-      emit({
-        type: "runtime_warning",
-        warning_kind: "context_compaction_failed",
-        message: lastError,
-      });
-      return workingMessages;
-    }
-  }
-
-  async function afterToolCall({ toolCall, result }, signal) {
-    if (signal?.aborted) return undefined;
-    const compacted = compactToolResultForContext(result, policy, { toolName: toolCall?.name || "tool" });
-    const visibleResult = compacted.changed ? compacted.result : result;
-    const payloadChars = estimateAgentMessageTokens({
-      role: "toolResult",
-      toolName: toolCall?.name || "tool",
-      content: visibleResult?.content || [],
-      details: visibleResult?.details || null,
-    }).chars;
-    toolPayloadCharsSinceCompaction += payloadChars;
-    maxToolPayloadCharsSinceCompaction = Math.max(maxToolPayloadCharsSinceCompaction, toolPayloadCharsSinceCompaction);
-    if (
-      policy.enabled
-      && policy.toolPayloadCompactionTriggerChars > 0
-      && toolPayloadCharsSinceCompaction >= policy.toolPayloadCompactionTriggerChars
-    ) {
-      forcedCompactionReason = forcedCompactionReason || "tool_payload_budget";
-    }
-    if (!compacted.changed) return undefined;
-    toolResultsCompacted += 1;
-    emit({
-      type: "tool_result_compacted",
-      tool_use_id: toolCall?.id || null,
-      name: toolCall?.name || null,
-      text_limit_chars: compacted.result.details?.text_limit_chars || null,
-      original_text_chars: compacted.result.details?.original_text_chars || null,
-      kept_text_chars: compacted.result.details?.kept_text_chars || null,
-      omitted_images: compacted.result.details?.omitted_images || null,
-    });
-    return {
-      content: compacted.result.content,
-      details: compacted.result.details,
-    };
-  }
-
-  function diagnostics() {
-    return {
-      context_compaction_enabled: policy.enabled,
-      context_compactions: compactionCount,
-      context_compaction_last_id: lastCompactionId,
-      context_compaction_last_error: lastError,
-      context_compactions_skipped_low_savings: skippedLowSavings,
-      context_window_tokens: policy.contextWindow,
-      context_compaction_trigger_tokens: policy.triggerTokens,
-      context_keep_recent_tokens: policy.keepRecentTokens,
-      context_compaction_min_savings_tokens: policy.compactionMinSavingsTokens,
-      context_tokens_estimate_max: maxContextTokensEstimate,
-      tool_results_compacted: toolResultsCompacted,
-      tool_results_pruned: toolResultsPruned,
-      tool_payload_chars_since_compaction: toolPayloadCharsSinceCompaction,
-      tool_payload_chars_since_compaction_max: maxToolPayloadCharsSinceCompaction,
-      tool_payload_compaction_trigger_chars: policy.toolPayloadCompactionTriggerChars,
-      tool_prune_trigger_tokens: policy.toolPruneTriggerTokens,
-      context_compaction_pending_reason: forcedCompactionReason,
-      tool_text_limit_chars: policy.toolTextLimitChars,
-      bash_output_limit_chars: policy.bashOutputLimitChars,
-      mcp_text_limit_chars: policy.mcpTextLimitChars,
-      search_result_limit: policy.searchResultLimit,
-      image_inline_max_bytes: policy.imageInlineMaxBytes,
-      mcp_call_timeout_ms: policy.mcpCallTimeoutMs,
-    };
-  }
-
-  return {
-    policy,
-    transformContext,
-    afterToolCall,
-    diagnostics,
-  };
-}