@mono-agent/agent-runtime 0.20.3 → 0.20.5

package/README.md

@@ -343,6 +343,8 @@ grepToolImpl
 inspectCodexSubscriptionSearch
 isPathAllowed
 isWorkdirAllowed
+normalizeBackgroundBashTimeoutMs
+normalizeBackgroundTimeoutMs
 normalizeBashTimeoutMs
 normalizeProcessTimeoutMs
 performWebFetch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/tools/bash.js

@@ -54,6 +54,31 @@ export function normalizeProcessTimeoutMs(value, fallback = DEFAULT_BASH_TIMEOUT
   return Math.max(1, Math.min(Math.floor(n), cap));
 }
 
+/**
+ * Background process-job timeout: positive-integer milliseconds with no
+ * foreground ceiling. A background budget belongs to the host's `processJobs`
+ * settings (`maxRuntimeMs`), which clamp it on their own side; reusing the
+ * foreground default as a cap here silently discarded the long runtime a caller
+ * deliberately asked for. `undefined` means "no explicit request", leaving the
+ * host default in force.
+ */
+export function normalizeBackgroundTimeoutMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.max(1, Math.floor(n));
+}
+
+/**
+ * Legacy Bash `timeout` for a background job: the same seconds-vs-milliseconds
+ * heuristic as {@link normalizeBashTimeoutMs}, minus the foreground ceiling.
+ */
+export function normalizeBackgroundBashTimeoutMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  const floored = Math.floor(n);
+  return Math.max(1_000, floored <= 600 ? floored * 1_000 : floored);
+}
+
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
@@ -131,9 +156,11 @@ export async function bashToolRun(
   }
 
   if (background === true && processJobsController) {
+    // Deliberately re-derived from the raw params: `timeoutMs` above carries the
+    // foreground ceiling, which is not this job's budget.
     const requestedTimeoutMs = timeout_ms !== undefined
-      ? timeoutMs
-      : (timeout === undefined ? undefined : timeoutMs);
+      ? normalizeBackgroundTimeoutMs(timeout_ms)
+      : normalizeBackgroundBashTimeoutMs(timeout);
     const handedOff = await handOffProcessJob({
       controller: processJobsController,
       tool: "Bash",

package/src/agent/tools/exec.js

@@ -3,7 +3,7 @@
 import { existsSync } from "node:fs";
 import { passthroughSandbox } from "../sandbox-seam.js";
 import { DEFAULT_MAX_BASH_OUTPUT_CHARS } from "./shared/constants.js";
-import { normalizeProcessTimeoutMs } from "./bash.js";
+import { normalizeBackgroundTimeoutMs, normalizeProcessTimeoutMs } from "./bash.js";
 import { capChars } from "./shared/output-truncation.js";
 import {
   isPathAllowed,
@@ -101,7 +101,9 @@ export async function execToolRun(
       tool: "Exec",
       prepared,
       summary: `Exec command (${args.length} argument${args.length === 1 ? "" : "s"}; values redacted)`,
-      timeoutMs: timeout_ms === undefined ? undefined : timeoutMs,
+      // Re-derived from the raw param: `timeoutMs` carries the foreground
+      // ceiling, and a background job is bounded by processJobs instead.
+      timeoutMs: timeout_ms === undefined ? undefined : normalizeBackgroundTimeoutMs(timeout_ms),
       maxOutputChars: max_output_chars === undefined ? undefined : maxChars,
       startedAt,
       failed,

package/src/agent/tools/index.js

@@ -12,6 +12,8 @@ export { grepToolImpl } from "./grep.js";
 export {
   bashToolImpl,
   bashToolRun,
+  normalizeBackgroundBashTimeoutMs,
+  normalizeBackgroundTimeoutMs,
   normalizeBashTimeoutMs,
   normalizeProcessTimeoutMs,
 } from "./bash.js";

package/src/agent/tools/pi-bridge.js

@@ -4,6 +4,7 @@ import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { passthroughSandbox } from "../sandbox-seam.js";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
@@ -185,6 +186,20 @@ function writeFileChangeDetails(path, before, after) {
   };
 }
 
+/**
+ * Render a budget for a tool description: the exact milliseconds the host
+ * enforces, plus a human unit, so the model can both reason about the scale and
+ * pass an exact value back.
+ */
+function formatDurationForModel(ms) {
+  const hours = ms / 3_600_000;
+  const minutes = ms / 60_000;
+  const human = hours >= 1
+    ? `${Number.isInteger(hours) ? String(hours) : hours.toFixed(1)}h`
+    : (minutes >= 1 ? `${Number.isInteger(minutes) ? String(minutes) : minutes.toFixed(1)}m` : `${String(Math.round(ms / 1_000))}s`);
+  return `${human} (${String(ms)} ms)`;
+}
+
 function limitedNumber(value, fallback) {
   const n = Number(value);
   if (!Number.isFinite(n) || n <= 0) return fallback;
@@ -208,10 +223,19 @@ function withToolLimits(name, params, limits = {}) {
   if (name === "Bash" || name === "Exec") {
     const timeoutLimit = limits.bashTimeoutMs || DEFAULT_BASH_TIMEOUT_MS;
     next.max_output_chars = limitedNumber(next.max_output_chars, limits.bashOutputLimitChars || limits.toolTextLimitChars || 20000);
-    if (name === "Bash" && next.timeout_ms === undefined && next.timeout !== undefined) {
-      next.timeout = normalizeBashTimeoutMs(next.timeout, timeoutLimit);
-    } else {
-      next.timeout_ms = normalizeProcessTimeoutMs(next.timeout_ms, timeoutLimit);
+    // A background hand-off is bounded by the host's processJobs budget, so the
+    // FOREGROUND DEFAULT must never bound it: falling back to that default is what
+    // silently capped multi-hour background jobs at two minutes, and the `else`
+    // branch injects it even when no timeout was requested at all. An explicitly
+    // configured bashTimeoutMs still narrows them — a host that sets one means it
+    // for background work too.
+    const effectiveTimeoutLimit = next.background === true ? limits.bashTimeoutMs : timeoutLimit;
+    if (effectiveTimeoutLimit !== undefined) {
+      if (name === "Bash" && next.timeout_ms === undefined && next.timeout !== undefined) {
+        next.timeout = normalizeBashTimeoutMs(next.timeout, effectiveTimeoutLimit);
+      } else {
+        next.timeout_ms = normalizeProcessTimeoutMs(next.timeout_ms, effectiveTimeoutLimit);
+      }
     }
   }
   return next;
@@ -389,7 +413,7 @@ function readSkillTool(skillNames = [], { skillsRoot, dataDir, skills = [] } = {
   return {
     name: "ReadSkill",
     label: "Read Skill",
-    description: "Load the complete instructions for a named skill. Use ReadSkill instead of Read for SKILL.md files.",
+    description: "Load the complete instructions for a named skill. Use ReadSkill instead of Read for SKILL.md files. If a skill's instructions are already present in this conversation, apply those instead of loading it again.",
     parameters: objectSchema({ name: { type: "string", enum: enumNames } }, ["name"]),
     async execute(_toolCallId, { name }) {
       if (sharedRoot) {
@@ -468,10 +492,28 @@ export function getPiBuiltinTools(allowedTools, {
     type: "integer",
     description: "Deprecated compatibility timeout. Values up to 600 mean seconds and larger values mean milliseconds; use timeout_ms instead.",
   };
+  const foregroundTimeoutLimitMs = toolLimits?.bashTimeoutMs || DEFAULT_BASH_TIMEOUT_MS;
+  const backgroundLimitMs = processJobsController?.limits?.maxRuntimeMs;
   const processTimeoutSchema = {
     type: "integer",
     minimum: 1,
-    description: "Exact timeout in milliseconds.",
+    description: `Exact timeout in milliseconds. A foreground run is capped at ${formatDurationForModel(foregroundTimeoutLimitMs)} and is killed at that point, so anything longer belongs in the background${
+      backgroundLimitMs === undefined
+        ? ""
+        : `, where this host allows up to ${formatDurationForModel(backgroundLimitMs)}`
+    }.`,
+  };
+  // Shared by Exec and Bash, and injected only when the host supplies a
+  // process-job controller. House style for a tool description is
+  // capability + when-to-prefer + caveat, so the middle sentence is what tells
+  // the model which commands belong here rather than in the foreground.
+  const backgroundSchema = {
+    type: "boolean",
+    description: `Run as a durable background process job and notify this conversation when it finishes. Prefer this for work that outlives a reply — builds, full test suites, long installs, migrations, long-running watchers — and leave it off whenever you need the output to answer right now. Do not use for commands that daemonize into another POSIX process group or session.${
+      backgroundLimitMs === undefined
+        ? ""
+        : ` This host runs a background job for up to ${formatDurationForModel(backgroundLimitMs)}; \`timeout_ms\` may lower that but never raise it, and the start receipt reports \`max_runtime_ms\`, the budget actually granted — check it, because a job is killed at that limit.`
+    }`,
   };
   // Per-tool closure config (cwd/event sink/limits/policy) plus the per-instance
   // ToolContext `ctx` that the tool impls and shared helpers read from.
@@ -533,9 +575,7 @@ export function getPiBuiltinTools(allowedTools, {
       timeout_ms: processTimeoutSchema,
       timeout: legacyBashTimeoutSchema,
       max_output_chars: bashLimitSchema,
-      ...(processJobsController ? {
-        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
-      } : {}),
+      ...(processJobsController ? { background: backgroundSchema } : {}),
     }, ["command"]), bashToolRun, toolContext),
     Exec: createBuiltinTool("Exec", "Exec", "Execute one program directly from an argv array without shell parsing. Prefer this for ordinary commands; use Bash only when shell syntax is required.", objectSchema({
       executable: { type: "string", minLength: 1 },
@@ -543,9 +583,7 @@ export function getPiBuiltinTools(allowedTools, {
       workdir: { type: "string" },
       timeout_ms: processTimeoutSchema,
       max_output_chars: bashLimitSchema,
-      ...(processJobsController ? {
-        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
-      } : {}),
+      ...(processJobsController ? { background: backgroundSchema } : {}),
     }, ["executable"]), execToolRun, toolContext),
     NodeRepl: nodeReplController
       ? createBuiltinTool(
@@ -693,6 +731,9 @@ async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine,
       retainedByMcpApps: false,
       privateCapabilityUrl,
       closed: false,
+      // AbortControllers for calls currently on the wire. Teardown aborts these
+      // BEFORE closing so the server is told to stop — see closeConnectedMcpClient.
+      inFlight: new Set(),
     };
   } catch (error) {
     try { await transport?.close?.(); } catch { /* best-effort */ }
@@ -868,6 +909,25 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
         parameters: sourceTool.inputSchema || /** @type {any} */ (sourceTool).input_schema || objectSchema({}),
         async execute(toolCallId, params, signal) {
           if (signal?.aborted) throw new Error("tool execution aborted");
+          // OWN this request's abort signal rather than forwarding the caller's
+          // directly, so run teardown can cancel the call ON THE WIRE. The SDK
+          // turns an abort into `notifications/cancelled`; closing the client
+          // only rejects the caller locally (Protocol._onclose) and then
+          // SIGTERM/SIGKILLs a stdio child with its request still outstanding —
+          // which is how a proxy's upstream work was left dangling in #664.
+          const callAbort = new AbortController();
+          const forwardAbort = () => callAbort.abort(signal?.reason);
+          signal?.addEventListener("abort", forwardAbort, { once: true });
+          const inFlight = { controller: callAbort, label: `${serverName}:${sourceTool.name}` };
+          connected.inFlight.add(inFlight);
+          try {
+            return await callMcpTool();
+          } finally {
+            connected.inFlight.delete(inFlight);
+            signal?.removeEventListener("abort", forwardAbort);
+          }
+
+          async function callMcpTool() {
           const textLimit = limits.mcpTextLimitChars || MCP_TEXT_RESULT_LIMIT;
           const imageInlineMaxBytes = limits.imageInlineMaxBytes ?? MCP_IMAGE_INLINE_MAX_BYTES;
           const normalizedParams = normalizeMcpToolParams(serverName, sourceTool.name, params || {}, { qaOutputDir, ctx });
@@ -913,7 +973,7 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
               timeout: mcpCallTimeoutMs,
               resetTimeoutOnProgress: true,
               maxTotalTimeout: mcpCallMaxTotalTimeoutMs,
-              signal,
+              signal: callAbort.signal,
               onprogress,
             },
           ).catch((error) => {
@@ -925,7 +985,7 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
           const out = await withTimeout(
             request,
             mcpCallTimeoutMs,
-            signal,
+            callAbort.signal,
             `${serverName}:${sourceTool.name}`,
             (reset) => {
               resetInactivityTimeout = reset;
@@ -976,6 +1036,7 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
               } : {}),
             },
           };
+          }
         },
       });
     }
@@ -1067,15 +1128,30 @@ async function registerMcpAppForToolResult({
   const connection = {
     connectionId: connected.connectionId,
     readResource: async (uri) => await connected.client.readResource({ uri }),
-    callTool: async (name, args, signal) => await connected.client.callTool(
-      { name, arguments: args && typeof args === "object" && !Array.isArray(args) ? args : {} },
-      undefined,
-      {
-        timeout: 120_000,
-        maxTotalTimeout: 120_000,
-        ...(signal ? { signal } : {}),
-      },
-    ),
+    // Same in-flight registration as the tool path: a retained MCP App
+    // connection torn down mid-call must cancel on the wire, not be closed out
+    // from under the request. See closeConnectedMcpClient.
+    callTool: async (name, args, signal) => {
+      const callAbort = new AbortController();
+      const forwardAbort = () => callAbort.abort(signal?.reason);
+      signal?.addEventListener("abort", forwardAbort, { once: true });
+      const inFlight = { controller: callAbort, label: `${serverName}:${name}` };
+      connected.inFlight.add(inFlight);
+      try {
+        return await connected.client.callTool(
+          { name, arguments: args && typeof args === "object" && !Array.isArray(args) ? args : {} },
+          undefined,
+          {
+            timeout: 120_000,
+            maxTotalTimeout: 120_000,
+            signal: callAbort.signal,
+          },
+        );
+      } finally {
+        connected.inFlight.delete(inFlight);
+        signal?.removeEventListener("abort", forwardAbort);
+      }
+    },
     close: async () => {
       connected.retainedByMcpApps = false;
       await closeConnectedMcpClient(connected, 5_000);
@@ -1139,9 +1215,36 @@ function selectMcpAppResource(response, resourceUri) {
   };
 }
 
+/**
+ * Cancel every call still on the wire, then close.
+ *
+ * Order matters. `Protocol._onclose` rejects pending requests LOCALLY with
+ * ConnectionClosed and never notifies the server, and StdioClientTransport then
+ * escalates stdin.end -> SIGTERM -> SIGKILL — so closing first kills a stdio
+ * proxy mid-request with its upstream work still outstanding, and the caller
+ * gets a bare "Connection closed" that cannot be told apart from a server that
+ * died on its own. Aborting first makes the SDK emit `notifications/cancelled`
+ * so the server can unwind, and rejects the caller with a sentence naming the
+ * server and tool. See mono-agent#664.
+ */
+function cancelInFlightMcpCalls(connected) {
+  const pending = connected?.inFlight;
+  if (!pending || pending.size === 0) return;
+  for (const entry of [...pending]) {
+    try {
+      entry.controller.abort(new McpError(
+        ErrorCode.ConnectionClosed,
+        `${entry.label} was cancelled because its MCP connection was torn down.`,
+      ));
+    } catch { /* best-effort */ }
+  }
+  pending.clear();
+}
+
 async function closeConnectedMcpClient(connected, timeoutMs) {
   if (!connected || connected.closed === true) return;
   connected.closed = true;
+  cancelInFlightMcpCalls(connected);
   const { client, transport } = connected;
   try { await closeWithTimeout(client?.close?.bind(client), timeoutMs); } catch { /* best-effort */ }
   try { await closeWithTimeout(transport?.close?.bind(transport), timeoutMs); } catch { /* best-effort */ }

package/src/agent/tools/shared/process-jobs.js

@@ -16,7 +16,7 @@ import { startPreparedProcess } from "./process-runner.js";
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
- * }) => Promise<{jobId: string, state: "queued"|"starting"|"running", startedAt: string|null}>} start
+ * }) => Promise<{jobId: string, state: "queued"|"starting"|"running", startedAt: string|null, maxRuntimeMs?: number}>} start
  */
 
 /**
@@ -82,9 +82,10 @@ export async function handOffProcessJob({
       job_id: result.jobId,
       state: result.state,
       started_at: result.startedAt,
+      ...(result.maxRuntimeMs === undefined ? {} : { max_runtime_ms: result.maxRuntimeMs }),
     };
     return {
-      text: JSON.stringify(payload),
+      text: `${BACKGROUND_START_GUIDANCE}\n${JSON.stringify(payload)}`,
       outcome: {
         status: "ok",
         code: "background_started",
@@ -111,6 +112,16 @@ export async function handOffProcessJob({
   }
 }
 
+/**
+ * A bare id/state payload leaves the model to guess what happens next, and the
+ * cheapest wrong guess is a polling loop. Completion delivers its own turn, so
+ * the result says so itself rather than relying on the schema line alone. No
+ * operator command is named on purpose: the model has a shell, and naming a
+ * status command invites exactly the polling this forbids.
+ */
+const BACKGROUND_START_GUIDANCE =
+  "Background process job started (tool-authored guidance): this conversation is woken with a new turn when the job reaches a terminal state, and its output arrives with that turn. Do not poll, sleep, wait on it, or re-run the command to check progress, and do not report the work as finished yet. `max_runtime_ms` is the budget the host granted; if it is below what you requested, the host capped it and the job will be killed at that limit, so plan the work around the granted budget rather than re-running the same command.";
+
 const PUBLIC_BACKGROUND_START_FAILURES = Object.freeze({
   background_unsupported: "Background process jobs are unsupported for this tool call.",
   background_unsupported_channel: "Background process jobs are unsupported for this channel.",
@@ -181,6 +192,8 @@ function validProcessJobStartResult(value) {
   if (!value || typeof value !== "object") return false;
   if (typeof value.jobId !== "string" || value.jobId.trim().length === 0 || value.jobId.length > 256) return false;
   if (value.state !== "queued" && value.state !== "starting" && value.state !== "running") return false;
+  if (value.maxRuntimeMs !== undefined
+    && (!Number.isSafeInteger(value.maxRuntimeMs) || value.maxRuntimeMs <= 0)) return false;
   if (value.startedAt === null) return true;
   if (typeof value.startedAt !== "string") return false;
   const timestamp = Date.parse(value.startedAt);

package/src/ai/failure.js

@@ -84,7 +84,7 @@ const PROVIDER_AUTH_RE = /(no api key|missing api key|api key required|invalid a
 // like worklab's coordinator, independent of retryableProviderFailureInfo) maps
 // that same terse text to the generic "spawn" kind instead of
 // "provider_unavailable".
-const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
+const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
 const TOOL_FAILURE_RE = /(tool .* failed|mcp tool|permission denied|EACCES|read-only file system)/i;
 const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api key|missing api key|api key required|invalid api key|incorrect api key|provider is not configured:|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
 // pi 0.80's openai-client-style bridge collapses a connection-refused/unreachable
@@ -92,7 +92,15 @@ const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api
 // no fetch failed) — the `\bconnection (?:error|refused|failed)\b|\bcould not connect\b`
 // alternation below is the motivating fix so that case still fails over instead of
 // being classified as non-retryable.
-const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
+// pi-ai 0.83.0 adds a second such bare sentence: openai-completions.js throws
+// "Stream ended without finish_reason" when an SSE stream terminates without a
+// finish_reason chunk. Because pi-models.js pins every custom/OpenAI-compatible
+// provider to the openai-completions api, a truncated gateway response was terminal
+// on the first occurrence — a configured fallback chain never advanced off the
+// primary. Matched as the full sentence on purpose: mono-agent's own TUI/web
+// transports emit a similar "Stream ended without a finish or error frame." that is a
+// local protocol fault and must NOT trigger a provider failover.
+const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
 export const PROVIDER_ABORT_RE = /\b(?:terminated|aborted before final output|aborted before final|stream aborted|stream was aborted|stream disconnected|websocket (?:error|disconnected|closed)|socket hang up|und_err_socket|econnreset|premature close)\b/i;
 
 /**
@@ -129,7 +137,12 @@ function retryableProviderSubkind(text) {
   if (/timed? ?out|etimedout/i.test(text)) return "timeout";
   // pi 0.80's terse "Connection error." (no ECONNREFUSED/fetch-failed detail) still
   // needs to land in the "network" subkind so a down provider fails over.
-  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network|\bconnection (?:error|refused|failed)\b|\bcould not connect\b/i.test(text)) return "network";
+  // pi-ai 0.83.0's openai-completions adapter throws the bare sentence
+  // "Stream ended without finish_reason" when an OpenAI-compatible SSE stream closes
+  // cleanly but no chunk ever carried a truthy finish_reason — i.e. a gateway
+  // truncated the response. That is a provider-side outage, so it belongs in the same
+  // "network" subkind as the terse connection error above.
+  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b/i.test(text)) return "network";
   if (/500|502|503|504|service unavailable|gateway|internal server error/i.test(text)) return "server_error";
   if (/retry your request|try again later|request id|processing your request/i.test(text)) return "retryable_request";
   return null;

package/src/ai/types.js

@@ -214,9 +214,10 @@
  * @property {number} [toolPayloadMaxBytes]       Hard cap on a single tool_result payload.
  * @property {number} [mcpCallTimeoutMs]          Per-MCP-call inactivity timeout.
  * @property {number} [mcpCallMaxTotalTimeoutMs]  Hard wall-clock cap for one MCP call.
- * @property {number} [bashTimeoutMs]             Documented for forward-compat; NOT wired to
- *   any tool today (no `agent_bash_*_timeout` mechanism exists — bash reads its per-call
- *   `timeout` argument), so setting it has no effect until a run-level default is introduced.
+ * @property {number} [bashTimeoutMs]             Foreground ceiling and default for
+ *   Bash/Exec timeouts on the Pi bridge, applied by `normalizePiBuiltinToolParams`
+ *   (defaults to 120_000). Background hand-offs deliberately ignore it: a process job is
+ *   bounded by the host's `processJobs.maxRuntimeMs` instead.
  */
 
 /**

package/types/agent/tools/bash.d.ts

@@ -7,6 +7,20 @@ export function normalizeBashTimeoutMs(value: any, fallback?: number): any;
  * Exact millisecond timeout used by Bash.timeout_ms and Exec.timeout_ms.
  */
 export function normalizeProcessTimeoutMs(value: any, fallback?: number): any;
+/**
+ * Background process-job timeout: positive-integer milliseconds with no
+ * foreground ceiling. A background budget belongs to the host's `processJobs`
+ * settings (`maxRuntimeMs`), which clamp it on their own side; reusing the
+ * foreground default as a cap here silently discarded the long runtime a caller
+ * deliberately asked for. `undefined` means "no explicit request", leaving the
+ * host default in force.
+ */
+export function normalizeBackgroundTimeoutMs(value: any): number;
+/**
+ * Legacy Bash `timeout` for a background job: the same seconds-vs-milliseconds
+ * heuristic as {@link normalizeBashTimeoutMs}, minus the foreground ceiling.
+ */
+export function normalizeBackgroundBashTimeoutMs(value: any): number;
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *

package/types/agent/tools/index.d.ts

@@ -5,7 +5,7 @@ export { globToolImpl } from "./glob.js";
 export { grepToolImpl } from "./grep.js";
 export { createWebToolController } from "./web-controller.js";
 export { resolveRgPath } from "./shared/ripgrep.js";
-export { bashToolImpl, bashToolRun, normalizeBashTimeoutMs, normalizeProcessTimeoutMs } from "./bash.js";
+export { bashToolImpl, bashToolRun, normalizeBackgroundBashTimeoutMs, normalizeBackgroundTimeoutMs, normalizeBashTimeoutMs, normalizeProcessTimeoutMs } from "./bash.js";
 export { execToolImpl, execToolRun } from "./exec.js";
 export { webFetchToolImpl, performWebFetch } from "./web-fetch.js";
 export { webSearchToolImpl, performWebSearch } from "./web-search.js";

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

@@ -138,6 +138,7 @@ export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limit
         retainedByMcpApps: boolean;
         privateCapabilityUrl: boolean;
         closed: boolean;
+        inFlight: Set<any>;
     }[];
     tools: any[];
     warnings: {

package/types/agent/tools/shared/process-jobs.d.ts

@@ -10,7 +10,7 @@
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
- * }) => Promise<{jobId: string, state: "queued"|"starting"|"running", startedAt: string|null}>} start
+ * }) => Promise<{jobId: string, state: "queued"|"starting"|"running", startedAt: string|null, maxRuntimeMs?: number}>} start
  */
 /**
  * Transfer one prepared command to the injected host controller. From the
@@ -59,6 +59,7 @@ export type ProcessJobsController = {
         jobId: string;
         state: "queued" | "starting" | "running";
         startedAt: string | null;
+        maxRuntimeMs?: number;
     }>;
 };
 import { startPreparedProcess } from "./process-runner.js";

package/types/ai/types.d.ts

@@ -177,9 +177,10 @@
  * @property {number} [toolPayloadMaxBytes]       Hard cap on a single tool_result payload.
  * @property {number} [mcpCallTimeoutMs]          Per-MCP-call inactivity timeout.
  * @property {number} [mcpCallMaxTotalTimeoutMs]  Hard wall-clock cap for one MCP call.
- * @property {number} [bashTimeoutMs]             Documented for forward-compat; NOT wired to
- *   any tool today (no `agent_bash_*_timeout` mechanism exists — bash reads its per-call
- *   `timeout` argument), so setting it has no effect until a run-level default is introduced.
+ * @property {number} [bashTimeoutMs]             Foreground ceiling and default for
+ *   Bash/Exec timeouts on the Pi bridge, applied by `normalizePiBuiltinToolParams`
+ *   (defaults to 120_000). Background hand-offs deliberately ignore it: a process job is
+ *   bounded by the host's `processJobs.maxRuntimeMs` instead.
  */
 /**
  * @typedef {Object} RuntimeCompactionPolicy
@@ -754,9 +755,10 @@ export type RuntimeToolLimits = {
      */
     mcpCallMaxTotalTimeoutMs?: number;
     /**
-     * Documented for forward-compat; NOT wired to
-     * any tool today (no `agent_bash_*_timeout` mechanism exists — bash reads its per-call
-     * `timeout` argument), so setting it has no effect until a run-level default is introduced.
+     * Foreground ceiling and default for
+     * Bash/Exec timeouts on the Pi bridge, applied by `normalizePiBuiltinToolParams`
+     * (defaults to 120_000). Background hand-offs deliberately ignore it: a process job is
+     * bounded by the host's `processJobs.maxRuntimeMs` instead.
      */
     bashTimeoutMs?: number;
 };