@mono-agent/agent-runtime 0.3.0 → 0.4.1

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

@@ -3,7 +3,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 { prepareSandboxedCommand } from "@mono-agent/sandbox";
+import { passthroughSandbox } from "../sandbox-seam.js";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import {
@@ -28,7 +28,8 @@ import { formatSkillBodyWithPathNote } from "../prompt/skill-index.js";
 import { MAX_TOOL_RESULT_BYTES, summarisePayload, wrapToolsWithBloatGuard } from "../tool-bloat.js";
 import { wrapToolsWithApprovalGate } from "../approval.js";
 import { isInsidePath } from "./shared/path-resolver.js";
-import { readRuntimeBrand, readToolRuntime, resolveSandboxPolicy } from "./shared/runtime-context.js";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
 function textResult(text, details = {}) {
   return {
@@ -37,7 +38,21 @@ function textResult(text, details = {}) {
   };
 }
 
+function imageResult(data, mimeType, details = {}) {
+  return {
+    content: [{ type: "image", data: String(data ?? ""), mimeType: mimeType || "image/png" }],
+    details,
+  };
+}
+
+function isImageToolResult(raw) {
+  return Boolean(raw) && typeof raw === "object" && raw.kind === "image" && typeof raw.data === "string";
+}
+
 const MCP_TEXT_RESULT_LIMIT = 12_000;
+// Fallback hard cap per MCP call when limits.mcpCallMaxTotalTimeoutMs is not
+// provided; mirrors DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS in agent/compaction.js.
+const DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS = 2_700_000;
 const MCP_RAW_DETAIL_LIMIT = 4_000;
 const MCP_IMAGE_INLINE_MAX_BYTES = 250_000;
 const DEFAULT_BASH_TIMEOUT_MS = 120_000;
@@ -75,28 +90,34 @@ function artifactFilename(filename, outputDir) {
   return target;
 }
 
-export function normalizeMcpToolParams(_serverName, toolName, params, { qaOutputDir } = {}) {
+/**
+ * @param {any} _serverName
+ * @param {any} toolName
+ * @param {any} params
+ * @param {{qaOutputDir?: any, ctx?: any}} [options]
+ */
+export function normalizeMcpToolParams(_serverName, toolName, params, { qaOutputDir, ctx } = {}) {
   if (!params || typeof params !== "object" || Array.isArray(params)) return params;
   if (!PLAYWRIGHT_FILENAME_TOOLS.has(toolName) || !params.filename || isAbsolute(String(params.filename))) return params;
-  const dir = qaOutputDir ?? readToolRuntime().qaOutputDir;
+  const dir = qaOutputDir ?? (ctx ?? readToolRuntime()).qaOutputDir;
   return {
     ...params,
     filename: artifactFilename(params.filename, dir),
   };
 }
 
-function normalizeWorkdir(value, cwd) {
-  const base = resolve(cwd || readToolRuntime().workspace || process.cwd());
+function normalizeWorkdir(value, cwd, ctx) {
+  const base = resolve(cwd || (ctx ?? readToolRuntime()).workspace || process.cwd());
   const resolved = value ? resolve(absolutizePath(value, base)) : base;
   return isInsidePath(base, resolved) ? resolved : base;
 }
 
-function withAbsolutePaths(name, params, cwd) {
+function withAbsolutePaths(name, params, cwd, ctx) {
   const next = { ...(params || {}) };
   if (["Read", "Write", "Edit"].includes(name)) next.file_path = absolutizePath(next.file_path, cwd);
   if (["Glob", "Grep"].includes(name)) next.path = absolutizePath(next.path, cwd);
   if (["Read", "Write", "Edit", "Glob", "Grep", "Bash"].includes(name)) {
-    next.workdir = normalizeWorkdir(next.workdir, cwd);
+    next.workdir = normalizeWorkdir(next.workdir, cwd, ctx);
   }
   return next;
 }
@@ -144,6 +165,10 @@ function compactRawMcpResult(out) {
   };
 }
 
+/**
+ * @param {any} change
+ * @param {{status?: any, before?: any, after?: any, error?: any}} [options]
+ */
 function fileEditPayload(change, { status, before, after, error } = {}) {
   const lineStats = statsForCompletedChange(change, before, after);
   const completedChange = lineStats ? { ...change, line_stats: lineStats } : change;
@@ -183,8 +208,13 @@ function withToolLimits(name, params, limits = {}) {
   return next;
 }
 
-export function normalizePiBuiltinToolParams(name, params, { cwd, toolLimits } = {}) {
-  return withToolLimits(name, withAbsolutePaths(name, params, cwd), toolLimits);
+/**
+ * @param {any} name
+ * @param {any} params
+ * @param {{cwd?: any, toolLimits?: any, ctx?: any}} [options]
+ */
+export function normalizePiBuiltinToolParams(name, params, { cwd, toolLimits, ctx } = {}) {
+  return withToolLimits(name, withAbsolutePaths(name, params, cwd, ctx), toolLimits);
 }
 
 function integerSchema() {
@@ -211,7 +241,15 @@ function isReadOnlyShellCommand(command) {
   ].some((pattern) => pattern.test(text));
 }
 
-function createBuiltinTool(name, label, description, parameters, execute, { cwd, onEvent, toolLimits, toolPolicy, sandboxPolicy, sandboxEngine } = {}) {
+/**
+ * @param {any} name
+ * @param {any} label
+ * @param {any} description
+ * @param {any} parameters
+ * @param {any} execute
+ * @param {{cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+function createBuiltinTool(name, label, description, parameters, execute, { cwd, onEvent, toolLimits, toolPolicy, sandboxPolicy, sandboxEngine, ctx } = {}) {
   return {
     name,
     label,
@@ -220,7 +258,7 @@ function createBuiltinTool(name, label, description, parameters, execute, { cwd,
     executionMode: name === "Write" || name === "Edit" || name === "Bash" ? "sequential" : undefined,
     async execute(toolCallId, params, signal) {
       if (signal?.aborted) throw new Error("tool execution aborted");
-      const normalized = normalizePiBuiltinToolParams(name, params, { cwd, toolLimits });
+      const normalized = normalizePiBuiltinToolParams(name, params, { cwd, toolLimits, ctx });
       if (name === "Bash" && toolPolicy?.bashReadOnly && !isReadOnlyShellCommand(normalized.command)) {
         throw new Error("Error: Planning shell policy allows only read-only inspection commands.");
       }
@@ -242,7 +280,13 @@ function createBuiltinTool(name, label, description, parameters, execute, { cwd,
         }));
       }
 
-      const raw = await execute(normalized, { signal, sandboxPolicy, sandboxEngine });
+      const raw = await execute(normalized, { signal, sandboxPolicy, sandboxEngine, ctx });
+      // Image reads (e.g. Read on a .png) come back as a structured image
+      // result so vision models see pixels; emit an image content block and let
+      // the shared bloat guard cap oversize payloads.
+      if (isImageToolResult(raw)) {
+        return imageResult(raw.data, raw.mimeType, { tool: name, params: normalized });
+      }
       const text = toolText(raw);
       if (isFileEdit && editState) {
         const failed = isErrorText(text);
@@ -264,24 +308,81 @@ function createBuiltinTool(name, label, description, parameters, execute, { cwd,
   };
 }
 
-function readSkillTool(skillNames = [], dataDir) {
-  const safe = skillNames.filter((name) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name));
-  if (!safe.length || !dataDir) return null;
+/**
+ * Progressive skill disclosure: exposes a `read_skill` tool so the agent can pull
+ * a named skill's FULL body on demand (skills are otherwise injected index-only).
+ *
+ * Two input shapes are accepted, matching what hosts pass:
+ *  - Minimal / legacy (mono-agent's agent-harness): bare `skillNames` + a shared
+ *    `skillsRoot` (the directory that directly contains `<name>/SKILL.md`), or the
+ *    back-compat `dataDir` (skills under `<dataDir>/skills`). This path is UNCHANGED.
+ *  - pi's neutral `Skill` shape (`{name, description, content, filePath, ...}`,
+ *    what worklab passes): each skill carries an absolute `filePath`. When NO shared
+ *    `skillsRoot`/`dataDir` is configured, read_skill derives each skill's root from
+ *    its own `filePath` — pi has no lazy-body equivalent, so the body is still read
+ *    from disk on demand rather than injected up front.
+ *
+ * The path-traversal guard (resolved file must stay under the shared root) is
+ * preserved on the shared-root path; on the filePath path the name→file binding is
+ * fixed at build time and the model can only pick an enum value, so there is no
+ * name-driven traversal surface.
+ */
+/**
+ * @param {any[]} [skillNames]
+ * @param {{skillsRoot?: any, dataDir?: any, skills?: any[]}} [options]
+ */
+function readSkillTool(skillNames = [], { skillsRoot, dataDir, skills = [] } = {}) {
+  const sharedRoot = skillsRoot
+    ? resolve(skillsRoot)
+    : (dataDir ? resolve(dataDir, "skills") : null);
+  const isSafeName = (name) => typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name);
+
+  // name -> {path, assetsPath, skillsRoot} derived from the pi Skill filePath.
+  // filePath is the skill file itself (nested `<root>/<name>/SKILL.md` or a flat
+  // `<root>/<name>.md`): assetsPath is its directory; the note-only skills root is
+  // one level up for the nested layout, else the directory itself.
+  const filePathEntries = new Map();
+  for (const skill of Array.isArray(skills) ? skills : []) {
+    if (!skill || typeof skill !== "object") continue;
+    if (!isSafeName(skill.name) || typeof skill.filePath !== "string" || !skill.filePath) continue;
+    if (filePathEntries.has(skill.name)) continue;
+    const path = resolve(skill.filePath);
+    const assetsPath = dirname(path);
+    const root = basename(path) === "SKILL.md" ? dirname(assetsPath) : assetsPath;
+    filePathEntries.set(skill.name, { path, assetsPath, skillsRoot: root });
+  }
+
+  // A shared root (minimal/legacy form) drives the tool exactly as before;
+  // filePath is consulted ONLY when it is absent — "derive root from
+  // skill.filePath when skillsRoot is absent".
+  const enumNames = sharedRoot
+    ? skillNames.filter(isSafeName)
+    : [...filePathEntries.keys()];
+  if (!enumNames.length) return null;
+
   return {
     name: "read_skill",
     label: "Read Skill",
     description: "Load the full instructions for a named skill.",
-    parameters: objectSchema({ name: { type: "string", enum: safe } }, ["name"]),
+    parameters: objectSchema({ name: { type: "string", enum: enumNames } }, ["name"]),
     async execute(_toolCallId, { name }) {
-      const path = resolve(dataDir, "skills", name, "SKILL.md");
-      const root = resolve(dataDir, "skills");
-      if (!path.startsWith(root + "/")) throw new Error(`invalid skill path: ${name}`);
-      if (!existsSync(path)) throw new Error(`SKILL.md not found for ${name}`);
+      if (sharedRoot) {
+        const path = resolve(sharedRoot, name, "SKILL.md");
+        if (!path.startsWith(sharedRoot + "/")) throw new Error(`invalid skill path: ${name}`);
+        if (!existsSync(path)) throw new Error(`SKILL.md not found for ${name}`);
+        return textResult(formatSkillBodyWithPathNote({
+          body: stripFrontmatter(readFileSync(path, "utf8")),
+          assetsPath: resolve(sharedRoot, name),
+          skillsRoot: sharedRoot,
+        }), { skill: name, path });
+      }
+      const entry = filePathEntries.get(name);
+      if (!entry || !existsSync(entry.path)) throw new Error(`SKILL.md not found for ${name}`);
       return textResult(formatSkillBodyWithPathNote({
-        body: stripFrontmatter(readFileSync(path, "utf8")),
-        assetsPath: resolve(root, name),
-        skillsRoot: root,
-      }), { skill: name, path });
+        body: stripFrontmatter(readFileSync(entry.path, "utf8")),
+        assetsPath: entry.assetsPath,
+        skillsRoot: entry.skillsRoot,
+      }), { skill: name, path: entry.path });
     },
   };
 }
@@ -305,8 +406,14 @@ export function createStructuredOutputTool(outputSchema, onStructuredOutput) {
   };
 }
 
+/**
+ * @param {any} allowedTools
+ * @param {{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]
+ */
 export function getPiBuiltinTools(allowedTools, {
   skillNames = [],
+  skills = [],
+  skillsRoot,
   dataDir,
   cwd,
   onEvent,
@@ -314,11 +421,13 @@ export function getPiBuiltinTools(allowedTools, {
   persistArtifact = null,
   onTruncate = null,
   toolPayloadMaxBytes = MAX_TOOL_RESULT_BYTES,
+  imageInlineMaxBytes = toolPayloadMaxBytes,
   toolPolicy = null,
   sandboxPolicy = null,
   sandboxEngine = null,
   approvalManager = null,
   approvalModel = null,
+  ctx = null,
 } = {}) {
   const textLimitSchema = integerSchema();
   const bashLimitSchema = integerSchema();
@@ -326,9 +435,11 @@ export function getPiBuiltinTools(allowedTools, {
     type: "integer",
     description: "Timeout in milliseconds. Use 30000 for 30 seconds; small values like 30 are treated as seconds for compatibility.",
   };
-  const toolContext = { cwd, onEvent, toolLimits, toolPolicy, sandboxPolicy, sandboxEngine };
+  // Per-tool closure config (cwd/event sink/limits/policy) plus the per-instance
+  // ToolContext `ctx` that the tool impls and shared helpers read from.
+  const toolContext = { cwd, onEvent, toolLimits, toolPolicy, sandboxPolicy, sandboxEngine, ctx };
   const all = {
-    Read: createBuiltinTool("Read", "Read", "Read a local file with line numbers.", objectSchema({
+    Read: createBuiltinTool("Read", "Read", "Read a local file. Text files return line-numbered content; image files (PNG, JPEG, GIF, WebP, BMP) are returned as a viewable image you can see directly — use this to look at image attachments.", objectSchema({
       file_path: { type: "string" },
       offset: { type: "integer" },
       start_line: { type: "integer" },
@@ -386,7 +497,7 @@ export function getPiBuiltinTools(allowedTools, {
   };
   const names = Array.isArray(allowedTools) ? allowedTools : Object.keys(all);
   const tools = names.map((name) => all[name]).filter(Boolean);
-  const skillTool = readSkillTool(skillNames, dataDir);
+  const skillTool = readSkillTool(skillNames, { skillsRoot, dataDir, skills });
   if (skillTool) tools.push(skillTool);
   const gated = approvalManager
     ? wrapToolsWithApprovalGate(tools, approvalManager, { model: approvalModel })
@@ -394,6 +505,7 @@ export function getPiBuiltinTools(allowedTools, {
   return wrapToolsWithBloatGuard(gated, {
     persistArtifact,
     maxBytes: toolPayloadMaxBytes,
+    imageMaxBytes: imageInlineMaxBytes,
     onTruncate,
   });
 }
@@ -405,9 +517,11 @@ export function resolveMcpStdioCwd(cfg = {}, cwd = null) {
   return cwd || process.cwd();
 }
 
-export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPolicy = null, sandboxEngine = null } = {}) {
-  return prepareSandboxedCommand({
-    policy: resolveSandboxPolicy(sandboxPolicy),
+export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPolicy = null, sandboxEngine = null, ctx = null } = {}) {
+  const resolvedCtx = ctx ?? readToolRuntime();
+  const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  return sandbox.prepareCommand({
+    policy: resolveSandboxPolicy(resolvedCtx, sandboxPolicy),
     engine: sandboxEngine ?? undefined,
     command: {
       command: cfg.command,
@@ -418,8 +532,13 @@ export async function prepareMcpStdioCommand(cfg = {}, { cwd = null, sandboxPoli
   });
 }
 
-async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine } = {}) {
-  const brand = readRuntimeBrand();
+/**
+ * @param {any} name
+ * @param {any} cfg
+ * @param {{cwd?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine, ctx } = {}) {
+  const brand = (ctx ?? readToolRuntime()).runtimeBrand;
   const client = new McpClient(
     { name: `${brand.mcpClientName}/${name}`, version: brand.mcpClientVersion },
     { capabilities: {} },
@@ -429,25 +548,28 @@ async function connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine }
     transport = new StreamableHTTPClientTransport(new URL(cfg.url), { requestInit: { headers: cfg.headers || {} } });
   } else if (cfg.type === "sse") {
     transport = new SSEClientTransport(new URL(cfg.url), {
-      eventSourceInit: { headers: cfg.headers || {} },
+      // SSE EventSourceInit's typed shape omits `headers`, but the transport
+      // forwards them to the underlying EventSource — keep the header pass-through.
+      eventSourceInit: /** @type {any} */ ({ headers: cfg.headers || {} }),
       requestInit: { headers: cfg.headers || {} },
     });
   } else {
-    const prepared = await prepareMcpStdioCommand(cfg, { cwd, sandboxPolicy, sandboxEngine });
+    const prepared = await prepareMcpStdioCommand(cfg, { cwd, sandboxPolicy, sandboxEngine, ctx });
     transport = new StdioClientTransport({
       command: prepared.command,
       args: prepared.args || [],
       cwd: prepared.cwd,
       env: { ...process.env, ...(prepared.env || {}) },
     });
-    transport.__monoSandboxCleanup = prepared.cleanup;
+    // Monkey-patched cleanup handle: not part of the MCP transport's typed shape.
+    /** @type {any} */ (transport).__monoSandboxCleanup = prepared.cleanup;
   }
   try {
     await client.connect(transport);
     return { name, client, transport };
   } catch (error) {
     try { await transport?.close?.(); } catch { /* best-effort */ }
-    try { await transport?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+    try { await /** @type {any} */ (transport)?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
     throw error;
   }
 }
@@ -515,16 +637,29 @@ function mcpToolName(serverName, toolName, reservedNames) {
   return `mcp__${serverName}__${toolName}`;
 }
 
-function withTimeout(promise, timeoutMs, signal, label) {
+// Inactivity wall clock around an MCP call. `registerReset` (optional) hands the
+// caller a rearm function so tool progress notifications can keep a legitimately
+// long call alive; the SDK's maxTotalTimeout stays the hard cap.
+function withTimeout(promise, timeoutMs, signal, label, registerReset) {
   if (signal?.aborted) return Promise.reject(new Error("tool execution aborted"));
   const ms = Number(timeoutMs) || 120000;
   let timeout;
   const timer = new Promise((_, reject) => {
-    timeout = setTimeout(() => reject(new Error(`${label || "MCP tool"} timed out after ${ms}ms`)), ms);
+    const arm = () => setTimeout(() => reject(new Error(`${label || "MCP tool"} timed out after ${ms}ms`)), ms);
+    timeout = arm();
+    registerReset?.(() => {
+      clearTimeout(timeout);
+      timeout = arm();
+    });
   });
   return Promise.race([promise, timer]).finally(() => clearTimeout(timeout));
 }
 
+/**
+ * @param {any} mcpConfig
+ * @param {Set<any>} [reservedNames]
+ * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any}} [options]
+ */
 export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
   limits = {},
   cwd = null,
@@ -534,14 +669,19 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
   toolPayloadMaxBytes = MAX_TOOL_RESULT_BYTES,
   sandboxPolicy = null,
   sandboxEngine = null,
+  onToolProgress = null,
+  ctx = null,
 } = {}) {
   const clients = [];
   const tools = [];
   const entries = Object.entries(mcpConfig || {});
-  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine })));
+  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectMcpClient(name, cfg, { cwd, sandboxPolicy, sandboxEngine, ctx })));
   const warnings = [];
   const seen = new Set(reservedNames);
 
+  // Phase 1: collect connected clients in entry order (so tool registration is
+  // deterministic) and record connect failures.
+  const connectedList = [];
   for (const [index, result] of settled.entries()) {
     const serverName = entries[index]?.[0];
     if (result.status !== "fulfilled") {
@@ -553,18 +693,28 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
       });
       continue;
     }
+    clients.push(result.value);
+    connectedList.push({ serverName, connected: result.value });
+  }
 
-    const connected = result.value;
-    clients.push(connected);
-    let listed;
+  // Phase 2: list tools from every connected server CONCURRENTLY (previously
+  // serial, adding ~Nx the slowest listTools to turn startup, painful over a
+  // SOCKS proxy). Results are awaited in entry order to keep registration stable.
+  const listings = await Promise.all(connectedList.map(async ({ serverName, connected }) => {
     try {
-      listed = await connected.client.listTools();
+      return { serverName, connected, listed: await connected.client.listTools() };
     } catch (err) {
+      return { serverName, connected, error: err };
+    }
+  }));
+
+  for (const { serverName, connected, listed, error } of listings) {
+    if (error) {
       warnings.push({
         type: "runtime_warning",
         warning_kind: "mcp_list_tools_failed",
         server: serverName,
-        message: err?.message || String(err),
+        message: error?.message || String(error),
       });
       continue;
     }
@@ -577,18 +727,67 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
         name,
         label: sourceTool.title || sourceTool.name,
         description: sourceTool.description || `${serverName}:${sourceTool.name}`,
-        parameters: sourceTool.inputSchema || sourceTool.input_schema || objectSchema({}),
+        parameters: sourceTool.inputSchema || /** @type {any} */ (sourceTool).input_schema || objectSchema({}),
         async execute(toolCallId, params, signal) {
           if (signal?.aborted) throw new Error("tool execution aborted");
           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 });
+          const normalizedParams = normalizeMcpToolParams(serverName, sourceTool.name, params || {}, { qaOutputDir, ctx });
+          // Measure the MCP round-trip so observability can separate slow MCP
+          // servers (e.g. context-example over a SOCKS proxy) from model latency.
+          const mcpCallStartMs = Date.now();
+          // The MCP SDK's per-request timeout defaults to 60s (DEFAULT_REQUEST_TIMEOUT_MSEC),
+          // which would fire -32001 well before the outer withTimeout wall-clock cap — fatal for
+          // in-process tools that run a whole agent turn (e.g. notify_conversation delivery).
+          // Pass it explicitly so the SDK request timeout matches our cap instead of pre-empting it.
+          const mcpCallTimeoutMs = limits.mcpCallTimeoutMs || 120000;
+          // Inactivity vs total: mcpCallTimeoutMs is reset by every progress
+          // notification (keep-alive for long tools like transcription or an
+          // ask-the-user wait); mcpCallMaxTotalTimeoutMs is the unresettable cap.
+          const mcpCallMaxTotalTimeoutMs = Math.max(
+            limits.mcpCallMaxTotalTimeoutMs || DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS,
+            mcpCallTimeoutMs,
+          );
+          // The SDK only attaches a progressToken (and thus honors
+          // resetTimeoutOnProgress) when an onprogress callback is present, so one
+          // is always attached: it rearms the outer wall clock and optionally
+          // surfaces the notification to the host.
+          let resetInactivityTimeout = null;
+          const onprogress = (progress) => {
+            resetInactivityTimeout?.();
+            onToolProgress?.({
+              type: "tool_progress",
+              server: serverName,
+              tool: sourceTool.name,
+              toolCallId,
+              ...(progress?.progress === undefined ? {} : { progress: progress.progress }),
+              ...(progress?.total === undefined ? {} : { total: progress.total }),
+              ...(progress?.message === undefined ? {} : { message: progress.message }),
+            });
+          };
           const out = await withTimeout(
-            connected.client.callTool({ name: sourceTool.name, arguments: normalizedParams || {} }),
-            limits.mcpCallTimeoutMs || 120000,
+            connected.client.callTool(
+              { name: sourceTool.name, arguments: normalizedParams || {} },
+              undefined,
+              // Forward the abort signal too, so a cancelled/timed-out call also cancels the
+              // in-flight MCP request on the wire (otherwise the SDK keeps awaiting until its own
+              // timeout, and an in-process loopback turn could post late after the bridge rejected).
+              {
+                timeout: mcpCallTimeoutMs,
+                resetTimeoutOnProgress: true,
+                maxTotalTimeout: mcpCallMaxTotalTimeoutMs,
+                signal,
+                onprogress,
+              },
+            ),
+            mcpCallTimeoutMs,
             signal,
             `${serverName}:${sourceTool.name}`,
+            (reset) => {
+              resetInactivityTimeout = reset;
+            },
           );
+          const mcpCallDurationMs = Date.now() - mcpCallStartMs;
           const imageTruncations = [];
           return {
             content: coerceMcpContent(out, {
@@ -605,6 +804,7 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
             details: {
               server: serverName,
               tool: sourceTool.name,
+              mcp_call_duration_ms: mcpCallDurationMs,
               result_truncated: mcpContentWasTruncated(out, { textLimit, imageInlineMaxBytes }),
               raw: compactRawMcpResult(out),
               ...(imageTruncations.length ? {
@@ -629,10 +829,28 @@ export async function initPiMcpTools(mcpConfig, reservedNames = new Set(), {
   };
 }
 
-export async function closePiMcpClients(clients) {
-  for (const { client, transport } of clients || []) {
-    try { await client.close?.(); } catch { /* best-effort */ }
-    try { await transport.close?.(); } catch { /* best-effort */ }
-    try { await transport.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+async function closeWithTimeout(close, timeoutMs) {
+  if (typeof close !== "function") return;
+  const result = close();
+  if (!(result && typeof result.then === "function")) return;
+  let timer;
+  try {
+    await Promise.race([
+      result,
+      new Promise((resolve) => { timer = setTimeout(resolve, timeoutMs); }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
   }
 }
+
+export async function closePiMcpClients(clients, { timeoutMs = 5000 } = {}) {
+  // Close the client first (stop accepting messages) then the transport (tear
+  // down I/O), each bounded by a timeout so a hung stdio pipe cannot stall
+  // shutdown — a common source of "Connection closed" churn on reconnect.
+  await Promise.all((clients || []).map(async ({ client, transport }) => {
+    try { await closeWithTimeout(client?.close?.bind(client), timeoutMs); } catch { /* best-effort */ }
+    try { await closeWithTimeout(transport?.close?.bind(transport), timeoutMs); } catch { /* best-effort */ }
+    try { await transport?.__monoSandboxCleanup?.(); } catch { /* best-effort */ }
+  }));
+}

package/src/agent/tools/read.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { extname } from "node:path";
 import {
   DEFAULT_MAX_READ_CHARS,
   DEFAULT_READ_LINES,
@@ -8,10 +9,33 @@ import { boundedInt, rememberRead, trimLine } from "./shared/dedup.js";
 import { capChars } from "./shared/output-truncation.js";
 import { isPathAllowed, resolveToolPath } from "./shared/path-resolver.js";
 
-export async function readToolImpl({ file_path, offset = 0, start_line, limit, max_output_chars, workdir }, { sandboxPolicy } = {}) {
-  const target = resolveToolPath(file_path, workdir);
-  if (!isPathAllowed(target, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${file_path}`;
+// Raster image formats a vision model can consume directly. SVG is intentionally
+// excluded — it is XML text, so it stays on the line-numbered text path.
+const IMAGE_MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+};
+
+/**
+ * @param {{file_path: string, offset?: number, start_line?: number, limit?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export async function readToolImpl({ file_path, offset = 0, start_line, limit, max_output_chars, workdir }, { sandboxPolicy, ctx } = {}) {
+  const target = resolveToolPath(file_path, workdir, ctx);
+  if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${file_path}`;
   if (!existsSync(target)) return `Error: File not found: ${file_path}`;
+  // Image files are returned as an image result so vision models see pixels
+  // rather than the raw bytes decoded (and garbled) as utf8 text. The builtin
+  // tool wrapper turns this into an image content block; oversize images are
+  // capped by the shared tool-result bloat guard.
+  const imageMime = IMAGE_MIME_BY_EXT[extname(target).toLowerCase()];
+  if (imageMime !== undefined) {
+    return { kind: "image", data: readFileSync(target).toString("base64"), mimeType: imageMime };
+  }
   const content = readFileSync(target, "utf8");
   let lines = content.split("\n");
   const total = lines.length;
@@ -35,5 +59,6 @@ export async function readToolImpl({ file_path, offset = 0, start_line, limit, m
     label: "Read",
     maxChars: Number(max_output_chars) || DEFAULT_MAX_READ_CHARS,
     hint: "Use Read with offset/start_line and limit for the specific range you need.",
+    ctx,
   });
 }

package/src/agent/tools/shared/output-truncation.js

@@ -9,8 +9,8 @@ function sanitizeName(value) {
   return String(value || "tool").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "tool";
 }
 
-export function writeToolArtifact(label, text) {
-  const { toolArtifactDir, runId } = readToolRuntime();
+export function writeToolArtifact(label, text, ctx) {
+  const { toolArtifactDir, runId } = ctx ?? readToolRuntime();
   if (!toolArtifactDir) return null;
   try {
     const safeRunId = sanitizeName(runId || "manual");
@@ -33,16 +33,21 @@ export function truncationSuffix({ label, shown, total, artifact, hint }) {
   ].filter(Boolean).join("\n");
 }
 
+/**
+ * @param {string} text
+ * @param {{label?: string, maxChars?: number, strategy?: string, hint?: string, ctx?: any}} [options]
+ */
 export function capChars(text, {
   label = "tool",
   maxChars = DEFAULT_MAX_TOOL_OUTPUT_CHARS,
   strategy = "head",
   hint,
+  ctx,
 } = {}) {
   const value = String(text || "");
   const limit = boundedInt(maxChars, DEFAULT_MAX_TOOL_OUTPUT_CHARS, { min: 200 });
   if (value.length <= limit) return value;
-  const artifact = writeToolArtifact(label, value);
+  const artifact = writeToolArtifact(label, value, ctx);
   const suffix = truncationSuffix({ label, shown: limit, total: value.length, artifact, hint });
   const budget = Math.max(0, limit - suffix.length);
   if (strategy === "head_tail" && budget > 200) {