@mono-agent/agent-runtime 0.11.5 → 0.12.0

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

@@ -32,8 +32,9 @@ 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
+ * 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,9 +43,8 @@ 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";
 }

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

@@ -223,6 +223,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 +400,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 +416,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.
@@ -654,7 +661,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 +757,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,9 @@ 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
+ * 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

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;
 };