@mono-agent/agent-runtime 0.15.2 → 0.15.4

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

@@ -7,14 +7,14 @@ import { passthroughSandbox } from "../sandbox-seam.js";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import {
-  bashToolImpl,
+  bashToolRun,
   editToolImpl,
+  execToolRun,
   globToolImpl,
   grepToolImpl,
   normalizeBashTimeoutMs,
+  normalizeProcessTimeoutMs,
   readToolImpl,
-  webFetchToolImpl,
-  webSearchToolImpl,
   writeToolImpl,
 } from "./index.js";
 import {
@@ -28,6 +28,7 @@ import { wrapToolsWithApprovalGate } from "../approval.js";
 import { isInsidePath } from "./shared/path-resolver.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { createAgentTool } from "./agent-tool.js";
 
 function textResult(text, details = {}) {
   return {
@@ -114,7 +115,7 @@ 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)) {
+  if (["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Exec"].includes(name)) {
     next.workdir = normalizeWorkdir(next.workdir, cwd, ctx);
   }
   return next;
@@ -198,9 +199,14 @@ function withToolLimits(name, params, limits = {}) {
     next.output_mode = next.output_mode || "files_with_matches";
     delete next.max_matches;
   }
-  if (name === "Bash") {
+  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);
-    next.timeout = normalizeBashTimeoutMs(next.timeout, limits.bashTimeoutMs || DEFAULT_BASH_TIMEOUT_MS);
+    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);
+    }
   }
   return next;
 }
@@ -238,21 +244,41 @@ function isReadOnlyShellCommand(command) {
   ].some((pattern) => pattern.test(text));
 }
 
+const ALWAYS_SEQUENTIAL_BUILTINS = new Set(["Write", "Edit", "Bash", "Exec", "NodeRepl"]);
+const SENSITIVE_RESULT_PARAMS = new Set(["Bash", "Exec", "WebFetch", "WebSearch"]);
+
+function isStructuredToolRun(value) {
+  return Boolean(value)
+    && typeof value === "object"
+    && typeof value.text === "string"
+    && value.outcome
+    && typeof value.outcome === "object";
+}
+
 /**
  * @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]
+ * @param {{cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, forceSequential?: boolean}} [options]
  */
-function createBuiltinTool(name, label, description, parameters, execute, { cwd, onEvent, toolLimits, toolPolicy, sandboxPolicy, sandboxEngine, ctx } = {}) {
+function createBuiltinTool(name, label, description, parameters, execute, {
+  cwd,
+  onEvent,
+  toolLimits,
+  toolPolicy,
+  sandboxPolicy,
+  sandboxEngine,
+  ctx,
+  forceSequential = false,
+} = {}) {
   return {
     name,
     label,
     description,
     parameters,
-    executionMode: name === "Write" || name === "Edit" || name === "Bash" || name === "NodeRepl" ? "sequential" : undefined,
+    executionMode: forceSequential || ALWAYS_SEQUENTIAL_BUILTINS.has(name) ? "sequential" : undefined,
     async execute(toolCallId, params, signal) {
       if (signal?.aborted) throw new Error("tool execution aborted");
       const normalized = normalizePiBuiltinToolParams(name, params, { cwd, toolLimits, ctx });
@@ -268,9 +294,21 @@ function createBuiltinTool(name, label, description, parameters, execute, { cwd,
       if (isImageToolResult(raw)) {
         return imageResult(raw.data, raw.mimeType, { tool: name, params: normalized });
       }
-      const text = toolText(raw);
-      if (isErrorText(text)) throw new Error(text);
-      const details = { tool: name, params: normalized };
+      const structured = isStructuredToolRun(raw) ? raw : null;
+      const text = structured ? structured.text : toolText(raw);
+      if (!structured && isErrorText(text)) throw new Error(text);
+      if (structured?.outcome?.legacyTimeoutUsed) {
+        onEvent?.({
+          type: "runtime_warning",
+          warning_kind: "deprecated_bash_timeout",
+          message: "Bash.timeout is deprecated; use timeout_ms for exact millisecond semantics.",
+        });
+      }
+      const details = /** @type {any} */ ({
+        tool: name,
+        ...(SENSITIVE_RESULT_PARAMS.has(name) ? {} : { params: normalized }),
+        ...(structured ? { outcome: structured.outcome } : {}),
+      });
       if (shouldTrackWrite) {
         details.file_change = writeFileChangeDetails(normalized.file_path, beforeWrite, readFileChangeSnapshot(normalized.file_path));
       }
@@ -379,7 +417,7 @@ export function createStructuredOutputTool(outputSchema, 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, nodeReplController?: 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, webController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
  */
 export function getPiBuiltinTools(allowedTools, {
   disallowedTools = [],
@@ -400,17 +438,35 @@ export function getPiBuiltinTools(allowedTools, {
   approvalManager = null,
   approvalModel = null,
   nodeReplController = null,
+  webController = null,
+  subagents = null,
+  subagentContext = null,
+  toolExecutionMode = "safe-parallel",
   ctx = null,
 } = {}) {
   const textLimitSchema = integerSchema();
   const bashLimitSchema = integerSchema();
-  const bashTimeoutSchema = {
+  const legacyBashTimeoutSchema = {
+    type: "integer",
+    description: "Deprecated compatibility timeout. Values up to 600 mean seconds and larger values mean milliseconds; use timeout_ms instead.",
+  };
+  const processTimeoutSchema = {
     type: "integer",
-    description: "Timeout in milliseconds. Use 30000 for 30 seconds; small values like 30 are treated as seconds for compatibility.",
+    minimum: 1,
+    description: "Exact timeout in milliseconds.",
   };
   // 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 toolContext = {
+    cwd,
+    onEvent,
+    toolLimits,
+    toolPolicy,
+    sandboxPolicy,
+    sandboxEngine,
+    forceSequential: toolExecutionMode === "sequential",
+    ctx,
+  };
   const all = {
     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" },
@@ -451,32 +507,64 @@ export function getPiBuiltinTools(allowedTools, {
       max_matches: { type: "integer" },
       max_output_chars: textLimitSchema,
     }, ["pattern"]), grepToolImpl, toolContext),
-    Bash: createBuiltinTool("Bash", "Bash", "Execute a shell command in the workspace.", objectSchema({
+    Bash: createBuiltinTool("Bash", "Bash", "Execute a shell command for pipelines, redirection, conditionals, or other shell syntax. Prefer Exec for one executable with an argv array. This is macOS: do not assume GNU-only commands or flags.", objectSchema({
       command: { type: "string" },
       workdir: { type: "string" },
       description: { type: "string" },
-      timeout: bashTimeoutSchema,
+      timeout_ms: processTimeoutSchema,
+      timeout: legacyBashTimeoutSchema,
+      max_output_chars: bashLimitSchema,
+    }, ["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 },
+      args: { type: "array", items: { type: "string" }, maxItems: 256 },
+      workdir: { type: "string" },
+      timeout_ms: processTimeoutSchema,
       max_output_chars: bashLimitSchema,
-    }, ["command"]), bashToolImpl, toolContext),
+    }, ["executable"]), execToolRun, toolContext),
     NodeRepl: nodeReplController
       ? createBuiltinTool(
         "NodeRepl",
         "Node REPL",
         "Evaluate JavaScript in a run-scoped Node.js REPL. Variables persist across NodeRepl calls in this run.",
         objectSchema({ code: { type: "string", minLength: 1 } }, ["code"]),
-        (params, { signal }) => nodeReplController.execute(params, { signal }),
+        (params, { signal }) => typeof nodeReplController.executeDetailed === "function"
+          ? nodeReplController.executeDetailed(params, { signal })
+          : nodeReplController.execute(params, { signal }),
         toolContext,
       )
       : null,
-    WebFetch: createBuiltinTool("WebFetch", "Web Fetch", "Fetch a URL and return text.", objectSchema({
+    // Built directly (not via createBuiltinTool) so a subagent answer starting
+    // with "Error:" is not reclassified as a tool failure, discarding its log.
+    Agent: createAgentTool(subagents, { onEvent, ...(subagentContext || {}) }),
+    WebFetch: createBuiltinTool("WebFetch", "Web Fetch", "Fetch and extract one HTTP(S) URL locally. Static extraction is preferred; browser rendering is available only through the configured render policy.", objectSchema({
       url: { type: "string" },
       headers: { type: "object", additionalProperties: { type: "string" } },
       max_output_chars: textLimitSchema,
-    }, ["url"]), webFetchToolImpl, toolContext),
-    WebSearch: createBuiltinTool("WebSearch", "Web Search", "Search the web and return result summaries.", objectSchema({
+      format: { type: "string", enum: ["markdown", "text", "raw"] },
+      render: { type: "string", enum: ["never", "auto", "always"] },
+    }, ["url"]), webController
+      ? (params, execution) => webController.fetch(params, execution)
+      : async () => ({
+        text: "Error: WebFetch controller is unavailable.",
+        outcome: { status: "error", code: "controller_unavailable", retryable: false, attempts: 0 },
+        error: true,
+      }), toolContext),
+    WebSearch: createBuiltinTool("WebSearch", "Web Search", "Search the public web with an operator-owned SearXNG endpoint when available, otherwise a keyless fallback, and return deduplicated ranked results.", objectSchema({
       query: { type: "string" },
       limit: { type: "integer" },
-    }, ["query"]), webSearchToolImpl, toolContext),
+      alternate_queries: { type: "array", items: { type: "string" }, maxItems: 3 },
+      domains: { type: "array", items: { type: "string" } },
+      exclude_domains: { type: "array", items: { type: "string" } },
+      language: { type: "string" },
+      time_range: { type: "string", enum: ["day", "month", "year"] },
+    }, ["query"]), webController
+      ? (params, execution) => webController.search(params, execution)
+      : async () => ({
+        text: "Error: WebSearch controller is unavailable.",
+        outcome: { status: "error", code: "controller_unavailable", retryable: false, attempts: 0 },
+        error: true,
+      }), toolContext),
   };
   // allowedTools honors the `"*"` allow-all sentinel (and undefined) as "every
   // built-in"; disallowedTools is the deny-wins filter applied to the final set.
@@ -489,6 +577,9 @@ export function getPiBuiltinTools(allowedTools, {
   // Deny-check the canonical PascalCase name AND the legacy snake_case alias so
   // an old denylist keeps disabling the tool after the rename.
   if (skillTool && !denied.has("ReadSkill") && !denied.has("read_skill" /* legacy alias */)) tools.push(skillTool);
+  if (toolExecutionMode === "sequential") {
+    for (const tool of tools) tool.executionMode = "sequential";
+  }
   const gated = approvalManager
     ? wrapToolsWithApprovalGate(tools, approvalManager, { model: approvalModel })
     : tools;

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

@@ -0,0 +1,162 @@
+// @ts-check
+
+import { spawn } from "node:child_process";
+
+export const DEFAULT_PROCESS_BUFFER_BYTES = 8 * 1024 * 1024;
+const KILL_GRACE_MS = 1_000;
+
+/**
+ * Run one already-prepared executable without adding a shell.
+ *
+ * The result is deliberately loss-aware: stdout/stderr are retained up to the
+ * shared byte cap even when the child times out, is aborted, exits by signal,
+ * or exceeds that cap.
+ *
+ * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number}} [options]
+ */
+export function runPreparedProcess(
+  commandSpec,
+  {
+    timeoutMs,
+    signal,
+    maxBufferBytes = DEFAULT_PROCESS_BUFFER_BYTES,
+  } = {},
+) {
+  const startedAt = Date.now();
+  return new Promise((resolve) => {
+    let child;
+    try {
+      const env = commandSpec.env ? mergedProcessEnv(commandSpec.env) : process.env;
+      child = spawn(commandSpec.command, commandSpec.args || [], {
+        cwd: commandSpec.cwd,
+        detached: process.platform !== "win32",
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      resolve({
+        code: null,
+        signal: null,
+        stdout: "",
+        stderr: "",
+        aborted: false,
+        timedOut: false,
+        bufferExceeded: false,
+        truncated: false,
+        bytes: 0,
+        storedBytes: 0,
+        spawnError: error,
+        durationMs: Date.now() - startedAt,
+      });
+      return;
+    }
+
+    const stdout = [];
+    const stderr = [];
+    const state = {
+      aborted: false,
+      bufferExceeded: false,
+      bytes: 0,
+      storedBytes: 0,
+      spawnError: null,
+      timedOut: false,
+      truncated: false,
+    };
+    let killTimer = null;
+    let timeoutTimer = null;
+    let settled = false;
+
+    function terminate() {
+      killProcessGroup(child, "SIGTERM");
+      if (killTimer === null) {
+        killTimer = setTimeout(() => killProcessGroup(child, "SIGKILL"), KILL_GRACE_MS);
+        killTimer.unref?.();
+      }
+    }
+
+    function append(target, chunk) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      state.bytes += buffer.length;
+      const remaining = Math.max(0, maxBufferBytes - state.storedBytes);
+      if (remaining > 0) {
+        const stored = buffer.length > remaining ? buffer.subarray(0, remaining) : buffer;
+        target.push(stored);
+        state.storedBytes += stored.length;
+      }
+      if (buffer.length > remaining) {
+        state.bufferExceeded = true;
+        state.truncated = true;
+        terminate();
+      }
+    }
+
+    if (Number.isFinite(timeoutMs) && Number(timeoutMs) > 0) {
+      timeoutTimer = setTimeout(() => {
+        state.timedOut = true;
+        terminate();
+      }, Number(timeoutMs));
+      timeoutTimer.unref?.();
+    }
+
+    const onAbort = () => {
+      state.aborted = true;
+      terminate();
+    };
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener?.("abort", onAbort, { once: true });
+
+    child.stdout?.on("data", (chunk) => append(stdout, chunk));
+    child.stderr?.on("data", (chunk) => append(stderr, chunk));
+    child.once("error", (error) => {
+      state.spawnError = error;
+    });
+    child.once("close", (code, closeSignal) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutTimer !== null) clearTimeout(timeoutTimer);
+      if (killTimer !== null) clearTimeout(killTimer);
+      signal?.removeEventListener?.("abort", onAbort);
+      resolve({
+        code,
+        signal: closeSignal,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        ...state,
+        durationMs: Date.now() - startedAt,
+      });
+    });
+  });
+}
+
+function mergedProcessEnv(overrides) {
+  const env = { ...process.env };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) delete env[key];
+    else env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {NodeJS.Signals} signal
+ */
+export function killProcessGroup(child, signal) {
+  if (!child?.pid) return;
+  try {
+    process.kill(process.platform === "win32" ? child.pid : -child.pid, signal);
+  } catch {
+    try { process.kill(child.pid, signal); } catch { /* already gone */ }
+  }
+}
+
+/**
+ * @param {{stdout?: string, stderr?: string}} result
+ */
+export function combinedProcessOutput(result) {
+  const stdout = String(result.stdout || "");
+  const stderr = String(result.stderr || "");
+  if (stdout && stderr) return `STDOUT:\n${stdout}\nSTDERR:\n${stderr}`;
+  return stdout || stderr || "(no output)";
+}

package/src/agent/tools/shared/semaphore.js

@@ -0,0 +1,73 @@
+// FIFO counting semaphore for run-scoped tool concurrency.
+//
+// agent-harness owns the equivalent helper for provider-execution width, but
+// the kernel cannot depend on the harness, so the shape is duplicated here for
+// the in-process tools that need to bound their own fan-out.
+
+// @ts-check
+
+/**
+ * @typedef {Object} CountingSemaphore
+ * @property {(signal?: AbortSignal) => Promise<() => void>} acquire Resolves with
+ *   a single-use release function once a slot is free. Rejects if `signal`
+ *   aborts while queued; an already-acquired slot is never leaked.
+ * @property {() => number} inFlight Slots currently held.
+ * @property {() => number} queued Waiters not yet admitted.
+ */
+
+/**
+ * @param {number} limit Maximum simultaneous holders. Values below 1 are clamped.
+ * @returns {CountingSemaphore}
+ */
+export function createCountingSemaphore(limit) {
+  const max = Number.isInteger(limit) && limit > 0 ? limit : 1;
+  let active = 0;
+  /** @type {Array<{resolve: (release: () => void) => void, reject: (error: Error) => void, settled: boolean}>} */
+  const waiters = [];
+
+  const release = () => {
+    // A release function is single-use: a double call would hand out a slot the
+    // holder no longer owns and let the limit drift upward for the whole run.
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      active -= 1;
+      pump();
+    };
+  };
+
+  const pump = () => {
+    while (active < max && waiters.length > 0) {
+      const waiter = /** @type {*} */ (waiters.shift());
+      if (waiter.settled) continue;
+      waiter.settled = true;
+      active += 1;
+      waiter.resolve(release());
+    }
+  };
+
+  return {
+    acquire(signal) {
+      if (signal?.aborted) {
+        return Promise.reject(new Error("tool execution aborted"));
+      }
+      if (active < max) {
+        active += 1;
+        return Promise.resolve(release());
+      }
+      return new Promise((resolve, reject) => {
+        /** @type {*} */
+        const waiter = { resolve, reject, settled: false };
+        waiters.push(waiter);
+        signal?.addEventListener("abort", () => {
+          if (waiter.settled) return;
+          waiter.settled = true;
+          reject(new Error("tool execution aborted"));
+        }, { once: true });
+      });
+    },
+    inFlight: () => active,
+    queued: () => waiters.filter((waiter) => !waiter.settled).length,
+  };
+}