@mono-agent/agent-runtime 0.3.0 → 0.4.1

package/src/agent/index.js

@@ -5,8 +5,8 @@
 // from edge layers.
 
 export {
-  createAgentCompactionManager,
   isLikelyContextTermination,
+  resolveAgentCompactionPolicy,
 } from "./compaction.js";
 
 export {

package/src/agent/prompt/skill-index.js

@@ -23,6 +23,9 @@ export function getSkillAccessDirs(skills = []) {
   return [...new Set(skills.map(skillDir).filter(Boolean))];
 }
 
+/**
+ * @param {{assetsPath?: string, skillsRoot?: any}} [options]
+ */
 export function buildSkillPathNote({ assetsPath, skillsRoot } = {}) {
   const lines = [];
   if (skillsRoot) lines.push(`Configured skills root: ${resolve(skillsRoot)}`);
@@ -31,6 +34,9 @@ export function buildSkillPathNote({ assetsPath, skillsRoot } = {}) {
   return lines.join("\n");
 }
 
+/**
+ * @param {{body?: string, assetsPath?: string, skillsRoot?: any, maxChars?: number}} [options]
+ */
 export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxChars = 12000 } = {}) {
   const text = [
     buildSkillPathNote({ assetsPath, skillsRoot }),

package/src/agent/sandbox-seam.js

@@ -0,0 +1,227 @@
+// Injectable sandbox seam.
+//
+// agent-runtime is a provider-agnostic kernel. This module removes its last
+// workspace dependency by turning "how commands get sandboxed" into data a
+// host hands the kernel, not code the kernel imports. A host constructs a
+// `RuntimeSandbox` implementation and passes it to `createRuntime({sandbox})`
+// (see runtime.js); every internal tool helper that used to import the sandbox
+// implementation directly (bash.js, pi-bridge.js's MCP-stdio launcher,
+// web-fetch.js, web-search.js,
+// tool-context.js's policy merge) now reads `ctx.sandbox` and calls through
+// this interface instead.
+//
+// `passthroughSandbox` is the zero-dependency default every ToolContext gets
+// when no host supplies one (createToolContext/resetToolContext in
+// ./tools/shared/tool-context.js). Its contract covers both no-injected-sandbox
+// paths equally:
+//   - No policy at all (both sides of a merge undefined, or a resolved policy
+//     that is undefined): every operation is allowed, byte-identical to
+//     running with no sandbox implementation installed at all.
+//   - A policy IS present and its `mode` demands real enforcement ("native")
+//     but nothing was injected to actually enforce it: FAIL CLOSED. This is a
+//     deliberate behavior change from before this seam existed (where the
+//     real sandbox implementation was bundled in agent-runtime and always did
+//     the enforcing) — a host that configures a policy without wiring a real
+//     RuntimeSandbox implementation used to get silent, unenforced
+//     "enforcement"; now it gets a loud, actionable error instead. See
+//     MIGRATION.md.
+//   - `mergePolicies` still keeps I13's monotonic guarantee (a request-scoped
+//     policy can only tighten, never weaken, the host-configured one) for the
+//     two axes the passthrough itself inspects (`mode`, `network.mode`). It
+//     is deliberately SHALLOW — no readable/writableRoots intersection, no
+//     denyWrite union — the real, byte-identical merge algorithm is owned by
+//     @mono-agent/runtime-adapter in packages/runtime-adapter/src/sandbox.ts
+//     (`mergeSandboxPolicies`) and is wired in by every mono-agent host through
+//     runtime-adapter.
+//
+// Real hosts (mono-agent, via @mono-agent/runtime-adapter) inject
+// `{mergePolicies: mergeSandboxPolicies, prepareCommand: prepareSandboxedCommand,
+// networkAllowsUrl: networkPolicyAllowsUrl}` from packages/runtime-adapter/src/sandbox.ts.
+// Those exports already conform to this interface exactly, so the injection is a direct pass-through (see runtime-adapter's
+// sandbox-impl.ts for the thin TS-side adapter that satisfies the seam's
+// type shape).
+
+// @ts-check
+
+/**
+ * @typedef {Object} SandboxCommandSpec
+ * @property {string} command
+ * @property {ReadonlyArray<string>} [args]
+ * @property {string} [cwd]
+ * @property {Object<string, string|undefined>} [env]
+ */
+
+/**
+ * @typedef {SandboxCommandSpec & {sandboxed: boolean, cleanup?: () => Promise<void>}} PreparedSandboxCommand
+ */
+
+/**
+ * @typedef {Object} SandboxNetworkPolicyLike
+ * @property {string} [mode]
+ * @property {ReadonlyArray<string>} [allowlist]
+ */
+
+/**
+ * @typedef {Object} SandboxPolicy
+ * Opaque, host-defined sandbox policy. The kernel itself only ever inspects
+ * `mode` (passthroughSandbox's fail-closed check) and `network.mode`
+ * (passthroughSandbox's networkAllowsUrl) — every other field (root,
+ * readableRoots, writableRoots, denyWrite, ...) is read directly off whatever
+ * the injected `mergePolicies` returns by path-resolver.js, and is opaque
+ * pass-through data as far as this module is concerned. Real hosts get the
+ * full, richly-typed policy from @mono-agent/runtime-adapter
+ * (`packages/runtime-adapter/src/sandbox.ts`), whose `SandboxPolicy` is a
+ * structural superset of this shape.
+ * @property {string} [mode]
+ * @property {SandboxNetworkPolicyLike} [network]
+ * @property {ReadonlyArray<string>} [readableRoots]
+ * @property {ReadonlyArray<string>} [writableRoots]
+ * @property {ReadonlyArray<string>} [denyWrite]
+ * @property {string} [root]
+ */
+
+/**
+ * @typedef {Object} RuntimeSandboxEngine
+ * Optional concrete sandboxing backend a caller can hand to `prepareCommand`
+ * (matches @mono-agent/runtime-adapter's `SandboxEngine`). Not used by
+ * `passthroughSandbox` (see module doc: adapters live in runtime-adapter, not
+ * the kernel) — documented here only because it is part of the
+ * `prepareCommand` input shape real implementations accept.
+ * @property {() => Promise<boolean>} isAvailable
+ * @property {(command: SandboxCommandSpec, policy: SandboxPolicy) => Promise<PreparedSandboxCommand>} prepareCommand
+ */
+
+/**
+ * @typedef {Object} PrepareSandboxedCommandInput
+ * @property {SandboxPolicy} [policy]
+ * @property {RuntimeSandboxEngine} [engine]
+ * @property {SandboxCommandSpec} command
+ */
+
+/**
+ * @typedef {Object} RuntimeSandbox
+ * The injectable sandbox seam. A host constructs one (or reuses
+ * `passthroughSandbox`) and passes it to `createRuntime({sandbox})`.
+ * @property {(configured: (SandboxPolicy|undefined), request: (SandboxPolicy|undefined)) => (SandboxPolicy|undefined)} mergePolicies
+ *   Monotonic tighten-only merge (I13): the result must never allow anything
+ *   `configured` alone would have denied.
+ * @property {(input: PrepareSandboxedCommandInput) => Promise<PreparedSandboxCommand>} prepareCommand
+ *   Resolves a command spec into whatever the underlying process spawner
+ *   should actually exec (identity when no enforcement is needed).
+ * @property {(policy: (SandboxPolicy|undefined), url: string) => boolean} networkAllowsUrl
+ *   Whether a tool call to `url` is allowed under `policy`.
+ * @property {ReadonlyArray<string>} [additionalReadPaths]
+ *   Optional host-provided extra read-allowed roots beyond the tool
+ *   context's workspace/repoRoot. Not consumed by any kernel helper today;
+ *   documented for forward-compatibility with host-side path resolution.
+ */
+
+const SANDBOX_UNAVAILABLE_CODE = "sandbox_unavailable";
+
+/**
+ * Plain Error with a `.code`/`.details` shape matching the workspace's
+ * CodedError convention (code discriminant + details that echo it, see the
+ * agent-contracts package's CodedError) — duplicated here rather than
+ * imported, since the kernel must not depend on any workspace package.
+ */
+class SandboxUnavailableError extends Error {
+  /**
+   * @param {string} message
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "SandboxUnavailableError";
+    this.code = SANDBOX_UNAVAILABLE_CODE;
+    this.details = { ...details, code: SANDBOX_UNAVAILABLE_CODE };
+  }
+}
+
+/**
+ * @param {string|undefined} mode
+ * @returns {boolean}
+ */
+function isRealSandboxMode(mode) {
+  return typeof mode === "string" && mode !== "off";
+}
+
+/**
+ * @param {SandboxNetworkPolicyLike|undefined} configured
+ * @param {SandboxNetworkPolicyLike|undefined} request
+ * @returns {SandboxNetworkPolicyLike|undefined}
+ */
+function mergeNetwork(configured, request) {
+  if (configured === undefined) return request;
+  if (request === undefined) return configured;
+  // The passthrough only distinguishes "all" (unrestricted) from everything
+  // else (restricted); whichever side is NOT "all" tightens the result.
+  if (configured.mode === "all" && request.mode === "all") return { mode: "all" };
+  return configured.mode === "all" ? request : configured;
+}
+
+/**
+ * @param {SandboxPolicy|undefined} configured
+ * @param {SandboxPolicy|undefined} request
+ * @returns {SandboxPolicy|undefined}
+ */
+function mergePolicies(configured, request) {
+  if (configured === undefined) return request;
+  if (request === undefined) return configured;
+  // Only two modes exist today ("native" | "off"); "native" tightens over
+  // "off" regardless of which side introduced it.
+  const configuredIsReal = isRealSandboxMode(configured.mode);
+  const requestIsReal = isRealSandboxMode(request.mode);
+  const mode = configuredIsReal ? configured.mode : (requestIsReal ? request.mode : (request.mode ?? configured.mode));
+  return {
+    ...configured,
+    ...request,
+    mode,
+    network: mergeNetwork(configured.network, request.network),
+  };
+}
+
+/**
+ * Identity command preparation — no sandboxing infrastructure of its own.
+ * Fails closed the moment a policy actually demands enforcement, rather than
+ * silently returning an unsandboxed command under a policy that looks
+ * enforced.
+ * @param {PrepareSandboxedCommandInput} input
+ * @returns {Promise<PreparedSandboxCommand>}
+ */
+async function prepareCommand({ policy, command }) {
+  if (policy === undefined || !isRealSandboxMode(policy.mode)) {
+    return { ...command, args: command.args ?? [], cwd: command.cwd ?? process.cwd(), sandboxed: false };
+  }
+  throw new SandboxUnavailableError(
+    "Sandbox policy requires enforcement (mode !== \"off\") but no RuntimeSandbox implementation is configured. "
+      + "Inject a real implementation via createRuntime({sandbox}) (mono-agent hosts get this automatically through "
+      + "the runtime-adapter package) or relax the policy.",
+    { mode: policy.mode, command: command.command },
+  );
+}
+
+/**
+ * @param {SandboxPolicy|undefined} policy
+ * @param {string} _url
+ * @returns {boolean}
+ */
+function networkAllowsUrl(policy, _url) {
+  if (policy === undefined) return true;
+  // A policy whose mode demands real enforcement must fail closed on network
+  // access too when no `network` sub-field was given — an absent `network`
+  // is not "all", and this is the passthrough's safety net for hand-built
+  // policies from hosts with no real RuntimeSandbox wired in (see module
+  // doc's fail-closed rationale, and prepareCommand above for the analogous
+  // command-side check this mirrors via isRealSandboxMode).
+  if (isRealSandboxMode(policy.mode)) return policy.network?.mode === "all";
+  return policy.network === undefined || policy.network.mode === "all";
+}
+
+/** @type {RuntimeSandbox} */
+export const passthroughSandbox = {
+  mergePolicies,
+  prepareCommand,
+  networkAllowsUrl,
+};
+
+export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_CODE };

package/src/agent/tool-bloat.js

@@ -88,12 +88,17 @@ function summaryText(toolName, originalBytes, maxBytes, savedPaths) {
 export function summarisePayload(toolName, contentBlocks, persistArtifact, options = {}) {
   const {
     maxBytes = MAX_TOOL_RESULT_BYTES,
+    imageMaxBytes = maxBytes,
     toolUseId = null,
     now = Date.now,
   } = options;
   const blocks = Array.isArray(contentBlocks) ? contentBlocks : [];
   const originalBytes = totalBytes(blocks);
-  if (originalBytes <= maxBytes) {
+  // Images get their own (typically larger) budget so a vision model can still
+  // see large screenshots; text/other payloads stay bound by maxBytes.
+  const imageBytes = blocks.reduce((sum, block) => sum + (block?.type === "image" ? blockBytes(block) : 0), 0);
+  const otherBytes = originalBytes - imageBytes;
+  if (otherBytes <= maxBytes && imageBytes <= imageMaxBytes) {
     return { rewrittenBlocks: blocks, savedPaths: [], originalBytes, truncated: false };
   }
 
@@ -117,11 +122,12 @@ export async function applyToolBloatGuard(toolName, executePromise, options = {}
     persistArtifact = null,
     toolUseId = null,
     maxBytes = MAX_TOOL_RESULT_BYTES,
+    imageMaxBytes = maxBytes,
     onTruncate = null,
   } = options;
   const result = await executePromise;
   if (!result || typeof result !== "object" || !Array.isArray(result.content)) return result;
-  const summary = summarisePayload(toolName, result.content, persistArtifact, { maxBytes, toolUseId });
+  const summary = summarisePayload(toolName, result.content, persistArtifact, { maxBytes, imageMaxBytes, toolUseId });
   if (!summary.truncated) return result;
   if (typeof onTruncate === "function") {
     try {

package/src/agent/tools/bash.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { prepareSandboxedCommand } from "@mono-agent/sandbox";
+import { passthroughSandbox } from "../sandbox-seam.js";
 import { DEFAULT_MAX_BASH_OUTPUT_CHARS } from "./shared/constants.js";
 import { capChars } from "./shared/output-truncation.js";
 import {
@@ -8,7 +8,8 @@ import {
   isWorkdirAllowed,
   workspaceRoot,
 } from "./shared/path-resolver.js";
-import { resolveSandboxPolicy } from "./shared/runtime-context.js";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_BASH_TIMEOUT_MS = 120000;
 const BASH_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
@@ -112,18 +113,24 @@ function runCommand(commandSpec, { timeoutMs, signal, maxBufferBytes = BASH_MAX_
   });
 }
 
-export async function bashToolImpl({ command, timeout = DEFAULT_BASH_TIMEOUT_MS, max_output_chars, workdir }, { signal, sandboxPolicy, sandboxEngine } = {}) {
-  const policy = resolveSandboxPolicy(sandboxPolicy);
-  const pathOptions = { sandboxPolicy: policy };
+/**
+ * @param {{command: string, timeout?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{signal?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export async function bashToolImpl({ command, timeout = DEFAULT_BASH_TIMEOUT_MS, max_output_chars, workdir }, { signal, sandboxPolicy, sandboxEngine, ctx } = {}) {
+  const resolvedCtx = ctx ?? readToolRuntime();
+  const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+  const pathOptions = { sandboxPolicy: policy, ctx };
   if (workdir && !isWorkdirAllowed(workdir, pathOptions)) return `Error: Working directory not allowed: ${workdir}`;
-  const cwd = workspaceRoot(workdir);
+  const cwd = workspaceRoot(workdir, ctx);
   if (!isPathAllowed(cwd, workdir, pathOptions)) return `Error: Working directory not allowed: ${cwd}`;
   if (!existsSync(cwd)) return `Error: Working directory not found: ${cwd}`;
   const maxChars = Number(max_output_chars) || DEFAULT_MAX_BASH_OUTPUT_CHARS;
   const timeoutMs = normalizeBashTimeoutMs(timeout);
   let prepared;
   try {
-    prepared = await prepareSandboxedCommand({
+    prepared = await sandbox.prepareCommand({
       policy,
       engine: sandboxEngine ?? undefined,
       command: { command: "/bin/bash", args: ["-lc", command], cwd },
@@ -146,11 +153,12 @@ export async function bashToolImpl({ command, timeout = DEFAULT_BASH_TIMEOUT_MS,
       label: "Bash",
       maxChars,
       strategy: "head_tail",
+      ctx,
     });
   }
   if (result.signal) return `Exit code 1:\nCommand terminated by ${result.signal}`;
   const output = result.stdout && result.stderr
     ? `STDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`
     : (result.stdout || result.stderr || "(no output)");
-  return capChars(output, { label: "Bash", maxChars, strategy: "head_tail" });
+  return capChars(output, { label: "Bash", maxChars, strategy: "head_tail", ctx });
 }

package/src/agent/tools/edit.js

@@ -1,9 +1,13 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isPathAllowed, isWritablePathAllowed, resolveToolPath } from "./shared/path-resolver.js";
 
-export async function editToolImpl({ file_path, old_string, new_string, replace_all = false, workdir }, { sandboxPolicy } = {}) {
-  const target = resolveToolPath(file_path, workdir);
-  const pathOptions = { sandboxPolicy };
+/**
+ * @param {{file_path: string, old_string: string, new_string: string, replace_all?: boolean, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export async function editToolImpl({ file_path, old_string, new_string, replace_all = false, workdir }, { sandboxPolicy, ctx } = {}) {
+  const target = resolveToolPath(file_path, workdir, ctx);
+  const pathOptions = { sandboxPolicy, ctx };
   if (!isPathAllowed(target, workdir, pathOptions) || !isWritablePathAllowed(target, workdir, pathOptions)) return `Error: Path not allowed: ${file_path}`;
   if (!existsSync(target)) return `Error: File not found: ${file_path}`;
   const content = readFileSync(target, "utf8");

package/src/agent/tools/glob.js

@@ -24,9 +24,13 @@ import {
 
 const execFileAsync = promisify(execFile);
 
-export async function globToolImpl({ pattern, path, limit, offset = 0, max_matches, max_output_chars, workdir }, { sandboxPolicy } = {}) {
-  const cwd = resolveToolPath(path || workspaceRoot(workdir), workdir);
-  if (!isPathAllowed(cwd, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${cwd}`;
+/**
+ * @param {{pattern: string, path?: string, limit?: number, offset?: number, max_matches?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export async function globToolImpl({ pattern, path, limit, offset = 0, max_matches, max_output_chars, workdir }, { sandboxPolicy, ctx } = {}) {
+  const cwd = resolveToolPath(path || workspaceRoot(workdir, ctx), workdir, ctx);
+  if (!isPathAllowed(cwd, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${cwd}`;
   const stat = safeStat(cwd);
   if (!stat?.isDirectory()) return `Error: Glob path is not a directory: ${cwd}`;
   const resultLimit = boundedInt(limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
@@ -38,8 +42,8 @@ export async function globToolImpl({ pattern, path, limit, offset = 0, max_match
     normalizeGlobPattern(pattern),
     ...excludedGlobArgs(),
   ];
-  const rgPath = resolveRgPath();
-  if (!rgPath) return ripgrepMissingMessage();
+  const rgPath = resolveRgPath({ ctx });
+  if (!rgPath) return ripgrepMissingMessage(ctx);
   try {
     const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
     const lines = stdout.trim().split("\n").filter(Boolean).sort((a, b) => {
@@ -53,6 +57,7 @@ export async function globToolImpl({ pattern, path, limit, offset = 0, max_match
       maxLines: resultLimit,
       maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
       offset,
+      ctx,
     });
     return result === "No files found matching pattern." ? result : `${result}\n\n${excludedPathSummary()}`;
   } catch (err) {
@@ -64,6 +69,7 @@ export async function globToolImpl({ pattern, path, limit, offset = 0, max_match
         maxLines: resultLimit,
         maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
         offset,
+        ctx,
       })}\n\n${excludedPathSummary()}`;
     }
     return `Error: ${err.message}`;

package/src/agent/tools/grep.js

@@ -22,6 +22,10 @@ import {
 
 const execFileAsync = promisify(execFile);
 
+/**
+ * @param {{pattern: string, path?: string, glob?: string, type?: string, output_mode?: string, context?: number, case_insensitive?: boolean, multiline?: boolean, head_limit?: number, offset?: number, max_matches?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
 export async function grepToolImpl({
   pattern,
   path,
@@ -36,9 +40,9 @@ export async function grepToolImpl({
   max_matches,
   max_output_chars,
   workdir,
-}, { sandboxPolicy } = {}) {
-  const target = resolveToolPath(path || workspaceRoot(workdir), workdir);
-  if (!isPathAllowed(target, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${target}`;
+}, { sandboxPolicy, ctx } = {}) {
+  const target = resolveToolPath(path || workspaceRoot(workdir, ctx), workdir, ctx);
+  if (!isPathAllowed(target, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${target}`;
   const stat = safeStat(target);
   if (!stat) return `Error: Path not found: ${target}`;
   const cwd = stat.isDirectory() ? target : dirname(target);
@@ -55,8 +59,8 @@ export async function grepToolImpl({
   if (type) args.push("--type", type);
   args.push(...excludedGlobArgs(), "--", pattern, searchTarget);
   const resultLimit = boundedInt(head_limit ?? max_matches, DEFAULT_MAX_SEARCH_LINES, { min: 1, max: 1000 });
-  const rgPath = resolveRgPath();
-  if (!rgPath) return ripgrepMissingMessage();
+  const rgPath = resolveRgPath({ ctx });
+  if (!rgPath) return ripgrepMissingMessage(ctx);
   try {
     const { stdout } = await execFileAsync(rgPath, args, { cwd, timeout: 15000, maxBuffer: SEARCH_MAX_BUFFER });
     const normalized = stdout.trim().split("\n").filter(Boolean).map((line) => line.replace(/^\.\//, ""));
@@ -66,6 +70,7 @@ export async function grepToolImpl({
       maxLines: resultLimit,
       maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
       offset,
+      ctx,
     });
     return formatted === "No matches found." ? formatted : `${formatted}\n\n${excludedPathSummary()}`;
   } catch (err) {
@@ -77,6 +82,7 @@ export async function grepToolImpl({
         maxLines: resultLimit,
         maxChars: Number(max_output_chars) || DEFAULT_MAX_SEARCH_CHARS,
         offset,
+        ctx,
       })}\n\n${excludedPathSummary()}`;
     }
     return `Error: ${err.message}`;