@mono-agent/agent-runtime 0.11.5 → 0.13.0

package/src/ai/providers/pi-native/result-builder.js

@@ -7,6 +7,7 @@
 // takes its inputs explicitly and returns the verbatim runtime-result contract
 // (diagnostics key spellings, error fields, and shape unchanged — I9).
 
+import { calculateContextTokens } from "@earendil-works/pi-agent-core";
 import { isContextLimitError } from "../pi-errors.js";
 import { isLikelyContextTermination } from "../../../agent/compaction.js";
 import { isProviderAuthFailureText } from "../../failure.js";
@@ -32,8 +33,31 @@ export function usageFromMessages(messages = []) {
 }
 
 /**
- * Classify a pi error message into a runtime failure kind. Context-limit /
- * max-turns terminations map to usage_limit; credential/config auth failures
+ * Normalize the final provider request's usage into an exact context snapshot.
+ * Unlike usageFromMessages(), this deliberately does not aggregate earlier
+ * requests in the run: the last assistant usage is the same provider-counted
+ * value Pi's compaction logic trusts, so it can decrease after compaction.
+ * @param {any} assistantMessage
+ * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null}
+ */
+export function contextUsageFromAssistantMessage(assistantMessage) {
+  if (assistantMessage?.role !== "assistant" || !assistantMessage.usage) return null;
+  if (assistantMessage.stopReason === "error" || assistantMessage.stopReason === "aborted") return null;
+  const total = Number(calculateContextTokens(assistantMessage.usage)) || 0;
+  if (total <= 0) return null;
+  return {
+    input: Number(assistantMessage.usage.input) || 0,
+    output: Number(assistantMessage.usage.output) || 0,
+    cacheRead: Number(assistantMessage.usage.cacheRead) || 0,
+    cacheCreation: Number(assistantMessage.usage.cacheWrite) || 0,
+    total,
+  };
+}
+
+/**
+ * Classify a pi error message into a runtime failure kind. Context-window
+ * overflows map to context_limit so the router can try the configured fallback;
+ * max-turns terminations remain usage_limit. Credential/config auth failures
  * map to provider_auth; everything else to provider_unavailable. Null message → null.
  * @param {string|null} message
  * @param {Record<string, unknown>} diagnostics
@@ -42,18 +66,27 @@ export function usageFromMessages(messages = []) {
  */
 export function failureKindForPiError(message, diagnostics, { maxTurnsHit = false } = {}) {
   if (!message) return null;
-  if (maxTurnsHit || isContextLimitError(message) || isLikelyContextTermination(message, diagnostics)) {
-    return "usage_limit";
-  }
+  if (maxTurnsHit) return "usage_limit";
+  if (isContextLimitError(message) || isLikelyContextTermination(message, diagnostics)) return "context_limit";
   if (isProviderAuthFailureText(message)) return "provider_auth";
   return "provider_unavailable";
 }
 
 /**
  * Emit the per-run cache / cost / provider-completed events.
- * @param {{onEvent: (event: any) => void, resolved: any, reference: string, usage: {input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}, estimatedCost: number, start: number, externalAbort: boolean}} params
+ * @param {{onEvent: (event: any) => void, resolved: any, reference: string, usage: {input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}, contextUsage?: {input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null, contextWindow?: number, estimatedCost: number, start: number, externalAbort: boolean}} params
  */
-export function emitUsageCostEvents({ onEvent, resolved, reference, usage, estimatedCost, start, externalAbort }) {
+export function emitUsageCostEvents({
+  onEvent,
+  resolved,
+  reference,
+  usage,
+  contextUsage,
+  contextWindow,
+  estimatedCost,
+  start,
+  externalAbort,
+}) {
   if (usage.cacheRead > 0) {
     onEvent({ type: "cache_hit", sdk: resolved.sdk, model: reference, tokens: usage.cacheRead, source: "prompt_cache" });
   }
@@ -72,6 +105,16 @@ export function emitUsageCostEvents({ onEvent, resolved, reference, usage, estim
       cacheCreationTokens: Number(usage.cacheWrite) || 0,
     },
   });
+  if (contextUsage) {
+    const effectiveContextWindow = Number(contextWindow) || 0;
+    onEvent({
+      type: "context_usage",
+      sdk: resolved.sdk,
+      model: reference,
+      ...(effectiveContextWindow > 0 ? { contextWindow: effectiveContextWindow } : {}),
+      tokens: contextUsage,
+    });
+  }
   onEvent({
     type: "provider_request_completed",
     sdk: resolved.sdk,

package/src/ai/providers/pi-native/turn-runner.js

@@ -14,6 +14,7 @@ import {
   getPiBuiltinTools,
   initPiMcpTools,
 } from "../../../agent/tools/pi-bridge.js";
+import { createNodeReplController } from "../../../agent/tools/node-repl.js";
 import { readToolRuntime } from "../../../agent/tools/shared/runtime-context.js";
 import { formatLiveInputGuidance } from "../../live-input-prompt.js";
 import { appendStructuredOutputInstruction } from "./structured-output.js";
@@ -24,10 +25,11 @@ import { createStreamSubscriber } from "./stream-subscriber.js";
  * tools, the MCP tool bridge, and the StructuredOutput tool (whose callback
  * writes runState.structuredResult). Surfaces MCP init/list failures to both the
  * event stream and runtimeWarnings. Returns the assembled tools plus the MCP
- * clients (closed by the caller's finally) and the structured tool.
+ * clients (closed by the caller's finally), run-owned tool cleanup, and the
+ * structured tool.
  * @param {any} runState
  * @param {any} params
- * @returns {Promise<{tools: any[], structuredTool: any, mcpClients: any[]}>}
+ * @returns {Promise<{tools: any[], structuredTool: any, mcpClients: any[], closeRunTools: () => Promise<void>}>}
  */
 export async function buildTurnTools(runState, {
   options,
@@ -62,6 +64,15 @@ export async function buildTurnTools(runState, {
     ? { ...(options.toolContext ?? readToolRuntime()), sandbox: options.sandbox }
     : options.toolContext;
   const sandboxEngine = options.sandboxEngine ?? runCtx?.sandboxEngine;
+  const nodeReplController = capabilities.tool_use === false
+    ? null
+    : createNodeReplController({
+      cwd: options.cwd,
+      maxOutputChars: toolLimits.bashOutputLimitChars || toolLimits.toolTextLimitChars,
+      sandboxPolicy: options.sandboxPolicy,
+      sandboxEngine,
+      ctx: runCtx,
+    });
 
   // REUSED custom pieces: built-in tool sandboxing + allowlist/bloat filter +
   // approval gates. These are identical to the legacy bridge.
@@ -97,6 +108,7 @@ export async function buildTurnTools(runState, {
       sandboxEngine,
       approvalManager,
       approvalModel: runtime.model?.id || runtime.model?.name || resolved.model,
+      nodeReplController,
       ctx: runCtx,
     }));
 
@@ -134,7 +146,12 @@ export async function buildTurnTools(runState, {
     ...mcpInit.tools,
     ...(structuredTool ? [structuredTool] : []),
   ];
-  return { tools, structuredTool, mcpClients: mcpInit.clients };
+  return {
+    tools,
+    structuredTool,
+    mcpClients: mcpInit.clients,
+    closeRunTools: async () => { await nodeReplController?.close(); },
+  };
 }
 
 /**

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

@@ -52,6 +52,7 @@ import {
   buildErrorDetails,
   buildErrorResult,
   buildSuccessResult,
+  contextUsageFromAssistantMessage,
   emitCapabilitiesResolved,
   emitUsageCostEvents,
   usageFromMessages,
@@ -223,6 +224,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
   const events = [];
   const runtimeWarnings = [];
   let mcpClients = [];
+  let closeRunTools = async () => {};
   let harness = null;
   // The ONE explicit runState the extracted modules (stream subscriber, session
   // lifecycle, compaction driver, turn runner, result builder) read/write.
@@ -399,7 +401,12 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // Build the turn's tools (builtins + MCP bridge + StructuredOutput). The
     // StructuredOutput callback writes runState.structuredResult; the MCP clients
     // are closed in the finally.
-    const { tools, structuredTool, mcpClients: builtMcpClients } = await buildTurnTools(runState, {
+    const {
+      tools,
+      structuredTool,
+      mcpClients: builtMcpClients,
+      closeRunTools: builtCloseRunTools,
+    } = await buildTurnTools(runState, {
       options,
       capabilities,
       toolLimits,
@@ -410,6 +417,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       runtimeWarnings,
     });
     mcpClients = builtMcpClients;
+    closeRunTools = builtCloseRunTools;
 
     // Provider retry/backoff is delegated to pi-ai via streamOptions, replacing
     // the legacy hand-rolled stream-retry loop.
@@ -601,7 +609,19 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       cachedTokens: usage.cacheRead,
       cacheWriteTokens: usage.cacheWrite,
     });
-    emitUsageCostEvents({ onEvent, resolved, reference, usage, estimatedCost, start, externalAbort: runState.externalAbort });
+    emitUsageCostEvents({
+      onEvent,
+      resolved,
+      reference,
+      usage,
+      contextUsage: runState.externalAbort || runState.maxTurnsHit || runError
+        ? null
+        : contextUsageFromAssistantMessage(lastAssistant),
+      contextWindow: runState.compaction.policy?.contextWindow,
+      estimatedCost,
+      start,
+      externalAbort: runState.externalAbort,
+    });
 
     const rawErrorMessage = runState.externalAbort
       ? null
@@ -654,7 +674,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       toolCompactionApplied: toolCompactionAppliedFromWarnings(runtimeWarnings),
       // Tristate: true = a compaction fired this run (proactive or reactive),
       // false = the path is enabled but did not need to fire, null = disabled via
-      // agent_compaction_enabled. See docs/reference/feature-registry.md runtime.context-compaction.
+      // runtime.compaction.enabled. See docs/reference/feature-registry.md runtime.context-compaction.
       contextCompactionApplied: runState.compaction.policy?.enabled ? runState.compaction.applied : null,
     });
     emitCapabilitiesResolved(onEvent, { sdk: resolved.sdk, model: reference, capabilitiesUsed });
@@ -750,7 +770,11 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
   } finally {
     if (runState.sessionEntry) runState.sessionEntry.busy = false;
     runState.removeAbortHandler?.();
-    await closePiMcpClients(mcpClients);
+    try {
+      await closeRunTools();
+    } finally {
+      await closePiMcpClients(mcpClients);
+    }
   }
 }
 

package/src/ai/types.js

@@ -98,14 +98,15 @@
  * @typedef {Object} RuntimeCompactionPolicy
  * Typed per-run context-compaction policy (the supported replacement for the
  * `agent_compaction_*` keys of the deprecated `settings` bag). Every field is
- * optional; an omitted field falls back to the kernel default.
+ * optional; omitted scalar budgets resolve adaptively against the effective
+ * model context window.
  * @property {boolean} [enabled]              Whether auto-compaction runs at all.
  * @property {number} [triggerRatio]          Fraction of the context window that arms the proactive trigger.
  * @property {number} [keepRecentTokens]      Recent-token budget preserved across a compaction.
- * @property {number} [summaryMaxTokens]      Max tokens of the generated summary.
- * @property {number} [minSavingsTokens]      Minimum token savings required to keep a compaction.
+ * @property {number} [summaryMaxTokens]      Combined output-token budget for generated compaction summaries.
+ * @property {number} [minSavingsTokens]      Minimum token savings required for proactive compaction; reactive recovery accepts any positive reduction.
  * @property {boolean} [fixedOverheadEnabled] Whether the system-prompt + tool-schema overhead correction is folded into the trigger.
- * @property {number} [contextWindowOverride] Forces the compaction window instead of the live-model-recognized one (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
+ * @property {number} [contextWindowOverride] Persistent correction for provider context-window metadata; learned overflow evidence may lower it process-locally (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
  */
 
 /**

package/types/agent/tools/node-repl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One lazy Node REPL process owned by a single Pi run.
+ * @param {{cwd?: string, maxOutputChars?: number, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function createNodeReplController({ cwd, maxOutputChars, sandboxPolicy, sandboxEngine, ctx, }?: {
+    cwd?: string;
+    maxOutputChars?: number;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+}): {
+    /** @param {{code: string}} params @param {{signal?: AbortSignal}} [execution] */
+    execute({ code }: {
+        code: string;
+    }, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<any>;
+    close(): Promise<void>;
+};

package/types/agent/tools/pi-bridge.d.ts

@@ -35,9 +35,9 @@ export function createStructuredOutputTool(outputSchema: any, onStructuredOutput
 };
 /**
  * @param {any} allowedTools
- * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, ctx?: any}} [options]
+ * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, ctx?: any}} [options]
  */
-export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, ctx, }?: {
+export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, nodeReplController, ctx, }?: {
     disallowedTools?: any[];
     skillNames?: any[];
     skills?: any[];
@@ -55,6 +55,7 @@ export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNam
     sandboxEngine?: any;
     approvalManager?: any;
     approvalModel?: any;
+    nodeReplController?: any;
     ctx?: any;
 }): any[];
 export function resolveMcpStdioCwd(cfg?: {}, cwd?: any): any;

package/types/ai/failure.d.ts

@@ -3,6 +3,15 @@
  * @returns {boolean}
  */
 export function isProviderAuthFailureText(text?: string): boolean;
+/**
+ * Identify request-input/context-window overflows without conflating provider
+ * throttling or output-token ceilings. Context overflows are route-local: a
+ * fallback model may have a larger usable window, while rate/quota/max-turn
+ * failures retain the terminal `usage_limit` classification.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isContextLimitFailureText(text?: string): boolean;
 /**
  * @param {Object} [options]
  * @param {string} [options.errorText]
@@ -64,7 +73,7 @@ export function createStderrTail({ limit }?: {
  * @property {string|null} requestId
  */
 /**
- * @typedef {"spawn" | "timeout" | "stall" | "usage_limit" | "invalid_result"
+ * @typedef {"spawn" | "timeout" | "stall" | "context_limit" | "usage_limit" | "invalid_result"
  *   | "invalid_delegation" | "tool_failure" | "provider_unavailable"
  *   | "provider_unavailable_exhausted" | "provider_auth"
  *   | "skipped_capability_mismatch" | "cancelled" | "cancelled_user"
@@ -114,4 +123,4 @@ export type RetryableProviderFailureInfo = {
  * Hosts (e.g. worklab's coordinator) validate against `FAILURE_KINDS` and may
  * define additional kinds — accepting them at the type level is deliberate.
  */
-export type FailureKind = "spawn" | "timeout" | "stall" | "usage_limit" | "invalid_result" | "invalid_delegation" | "tool_failure" | "provider_unavailable" | "provider_unavailable_exhausted" | "provider_auth" | "skipped_capability_mismatch" | "cancelled" | "cancelled_user" | "cancelled_shutdown" | "cancelled_signal" | "abandoned" | "session_not_found" | "session_busy" | (string & {});
+export type FailureKind = "spawn" | "timeout" | "stall" | "context_limit" | "usage_limit" | "invalid_result" | "invalid_delegation" | "tool_failure" | "provider_unavailable" | "provider_unavailable_exhausted" | "provider_auth" | "skipped_capability_mismatch" | "cancelled" | "cancelled_user" | "cancelled_shutdown" | "cancelled_signal" | "abandoned" | "session_not_found" | "session_busy" | (string & {});

package/types/ai/providers/opencode-app.d.ts

@@ -4,7 +4,7 @@
  * can contain provider credentials or echoed request secrets.
  */
 export function safeOpenCodeErrorMessage(error: any, fallback?: string): any;
-export function mapErrorFailureKind(error: any): "usage_limit" | "provider_unavailable" | "provider_auth" | "cancelled";
+export function mapErrorFailureKind(error: any): "context_limit" | "usage_limit" | "provider_unavailable" | "provider_auth" | "cancelled";
 export function mapSpawnFailureKind(err: any): "spawn" | "provider_unavailable";
 export namespace opencodeAppRuntimeBridge {
     export let id: string;

package/types/ai/providers/pi-native/compaction-driver.d.ts

@@ -1,17 +1,31 @@
-export function estimateCurrentContextTokens(session: any, fixedOverheadTokens?: number): Promise<{
+export function estimateCurrentContextTokens(session: any, fixedOverheadTokens?: number, usageIncrementTokens?: number): Promise<{
     tokens: number;
     source: string;
 }>;
-export function tryCompact(harness: any, { trigger, onEvent, runtimeWarnings, onCompactionRecorded, runId, model }: {
+/**
+ * Pi derives its summary output limit from reserveTokens. A normal compaction
+ * uses floor(0.8 * reserve); a split-turn compaction may generate both that
+ * history summary and floor(0.5 * reserve) for the turn prefix. Return the
+ * largest reserve whose derived generation budget does not exceed the public
+ * summaryMaxTokens setting.
+ * @param {number} summaryMaxTokens
+ * @param {boolean} isSplitTurn
+ */
+export function piSummaryReserveTokens(summaryMaxTokens: number, isSplitTurn: boolean): number;
+export function tryCompact(harness: any, { trigger, onEvent, runtimeWarnings, onCompactionRecorded, runId, model, session, policy, }: {
     trigger: any;
     onEvent: any;
     runtimeWarnings: any;
     onCompactionRecorded: any;
     runId: any;
     model: any;
+    session: any;
+    policy: any;
 }): Promise<{
     applied: boolean;
     tokensBefore: number;
+    tokensAfter: any;
+    reduced: boolean;
     nothingToCompact: boolean;
 }>;
 /**
@@ -49,10 +63,10 @@ export function piCompactionSettings(policy: {
  * 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.
+ * (from the typed `compaction` policy object) replaces provider metadata, but
+ * process-local overflow evidence can still lower it. 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 }: {

package/types/ai/providers/pi-native/result-builder.d.ts

@@ -11,8 +11,24 @@ export function usageFromMessages(messages?: Array<any>): {
     cost: number;
 };
 /**
- * Classify a pi error message into a runtime failure kind. Context-limit /
- * max-turns terminations map to usage_limit; credential/config auth failures
+ * Normalize the final provider request's usage into an exact context snapshot.
+ * Unlike usageFromMessages(), this deliberately does not aggregate earlier
+ * requests in the run: the last assistant usage is the same provider-counted
+ * value Pi's compaction logic trusts, so it can decrease after compaction.
+ * @param {any} assistantMessage
+ * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null}
+ */
+export function contextUsageFromAssistantMessage(assistantMessage: any): {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreation: number;
+    total: number;
+} | null;
+/**
+ * Classify a pi error message into a runtime failure kind. Context-window
+ * overflows map to context_limit so the router can try the configured fallback;
+ * max-turns terminations remain usage_limit. Credential/config auth failures
  * map to provider_auth; everything else to provider_unavailable. Null message → null.
  * @param {string|null} message
  * @param {Record<string, unknown>} diagnostics
@@ -24,9 +40,9 @@ export function failureKindForPiError(message: string | null, diagnostics: Recor
 }): string | null;
 /**
  * Emit the per-run cache / cost / provider-completed events.
- * @param {{onEvent: (event: any) => void, resolved: any, reference: string, usage: {input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}, estimatedCost: number, start: number, externalAbort: boolean}} params
+ * @param {{onEvent: (event: any) => void, resolved: any, reference: string, usage: {input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}, contextUsage?: {input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null, contextWindow?: number, estimatedCost: number, start: number, externalAbort: boolean}} params
  */
-export function emitUsageCostEvents({ onEvent, resolved, reference, usage, estimatedCost, start, externalAbort }: {
+export function emitUsageCostEvents({ onEvent, resolved, reference, usage, contextUsage, contextWindow, estimatedCost, start, externalAbort, }: {
     onEvent: (event: any) => void;
     resolved: any;
     reference: string;
@@ -37,6 +53,14 @@ export function emitUsageCostEvents({ onEvent, resolved, reference, usage, estim
         cacheWrite: number;
         cost: number;
     };
+    contextUsage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreation: number;
+        total: number;
+    } | null;
+    contextWindow?: number;
     estimatedCost: number;
     start: number;
     externalAbort: boolean;

package/types/ai/providers/pi-native/turn-runner.d.ts

@@ -3,15 +3,17 @@
  * tools, the MCP tool bridge, and the StructuredOutput tool (whose callback
  * writes runState.structuredResult). Surfaces MCP init/list failures to both the
  * event stream and runtimeWarnings. Returns the assembled tools plus the MCP
- * clients (closed by the caller's finally) and the structured tool.
+ * clients (closed by the caller's finally), run-owned tool cleanup, and the
+ * structured tool.
  * @param {any} runState
  * @param {any} params
- * @returns {Promise<{tools: any[], structuredTool: any, mcpClients: any[]}>}
+ * @returns {Promise<{tools: any[], structuredTool: any, mcpClients: any[], closeRunTools: () => Promise<void>}>}
  */
 export function buildTurnTools(runState: any, { options, capabilities, toolLimits, approvalManager, runtime, resolved, onEvent, runtimeWarnings, }: any): Promise<{
     tools: any[];
     structuredTool: any;
     mcpClients: any[];
+    closeRunTools: () => Promise<void>;
 }>;
 /**
  * Map an effort level to the harness thinkingLevel, respecting model reasoning

package/types/ai/types.d.ts

@@ -71,14 +71,15 @@
  * @typedef {Object} RuntimeCompactionPolicy
  * Typed per-run context-compaction policy (the supported replacement for the
  * `agent_compaction_*` keys of the deprecated `settings` bag). Every field is
- * optional; an omitted field falls back to the kernel default.
+ * optional; omitted scalar budgets resolve adaptively against the effective
+ * model context window.
  * @property {boolean} [enabled]              Whether auto-compaction runs at all.
  * @property {number} [triggerRatio]          Fraction of the context window that arms the proactive trigger.
  * @property {number} [keepRecentTokens]      Recent-token budget preserved across a compaction.
- * @property {number} [summaryMaxTokens]      Max tokens of the generated summary.
- * @property {number} [minSavingsTokens]      Minimum token savings required to keep a compaction.
+ * @property {number} [summaryMaxTokens]      Combined output-token budget for generated compaction summaries.
+ * @property {number} [minSavingsTokens]      Minimum token savings required for proactive compaction; reactive recovery accepts any positive reduction.
  * @property {boolean} [fixedOverheadEnabled] Whether the system-prompt + tool-schema overhead correction is folded into the trigger.
- * @property {number} [contextWindowOverride] Forces the compaction window instead of the live-model-recognized one (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
+ * @property {number} [contextWindowOverride] Persistent correction for provider context-window metadata; learned overflow evidence may lower it process-locally (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
  */
 /**
  * @typedef {Object} RuntimePromptOverrides
@@ -406,7 +407,8 @@ export type RuntimeToolLimits = {
 /**
  * Typed per-run context-compaction policy (the supported replacement for the
  * `agent_compaction_*` keys of the deprecated `settings` bag). Every field is
- * optional; an omitted field falls back to the kernel default.
+ * optional; omitted scalar budgets resolve adaptively against the effective
+ * model context window.
  */
 export type RuntimeCompactionPolicy = {
     /**
@@ -422,11 +424,11 @@ export type RuntimeCompactionPolicy = {
      */
     keepRecentTokens?: number;
     /**
-     * Max tokens of the generated summary.
+     * Combined output-token budget for generated compaction summaries.
      */
     summaryMaxTokens?: number;
     /**
-     * Minimum token savings required to keep a compaction.
+     * Minimum token savings required for proactive compaction; reactive recovery accepts any positive reduction.
      */
     minSavingsTokens?: number;
     /**
@@ -434,7 +436,7 @@ export type RuntimeCompactionPolicy = {
      */
     fixedOverheadEnabled?: boolean;
     /**
-     * Forces the compaction window instead of the live-model-recognized one (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
+     * Persistent correction for provider context-window metadata; learned overflow evidence may lower it process-locally (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
      */
     contextWindowOverride?: number;
 };