@mono-agent/agent-runtime 0.4.0 → 0.4.1

package/src/agent/compaction.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 // Context-compaction policy + heuristics for the pi-native bridge.
 //
 // The hand-rolled in-loop compaction manager (transformContext/afterToolCall)
@@ -10,6 +12,28 @@
 //   - isLikelyContextTermination: classifies a provider error/termination as a
 //     context-pressure event.
 
+/**
+ * @typedef {Object} AgentCompactionPolicy
+ * @property {boolean} enabled
+ * @property {number} contextWindow
+ * @property {number} triggerRatio
+ * @property {number} triggerTokens
+ * @property {number} keepRecentTokens
+ * @property {number} summaryMaxTokens
+ * @property {boolean} fixedOverheadEnabled
+ * @property {number} compactionMinSavingsTokens
+ * @property {number} toolPayloadCompactionTriggerChars
+ * @property {number} toolPruneTriggerTokens
+ * @property {number} toolTextLimitChars
+ * @property {number} bashOutputLimitChars
+ * @property {number} mcpTextLimitChars
+ * @property {number} searchResultLimit
+ * @property {number} imageInlineMaxBytes
+ * @property {number} toolPayloadMaxBytes
+ * @property {number} mcpCallTimeoutMs
+ * @property {number} mcpCallMaxTotalTimeoutMs
+ */
+
 const DEFAULT_CONTEXT_WINDOW = 128000;
 const DEFAULT_TRIGGER_RATIO = 0.85;
 const DEFAULT_KEEP_RECENT_TOKENS = 24000;
@@ -25,20 +49,49 @@ const DEFAULT_TOOL_TEXT_LIMIT_CHARS = 64000;
 const DEFAULT_BASH_OUTPUT_LIMIT_CHARS = 64000;
 const DEFAULT_MCP_TEXT_LIMIT_CHARS = 48000;
 const DEFAULT_SEARCH_RESULT_LIMIT = 100;
-const DEFAULT_IMAGE_INLINE_MAX_BYTES = 250000;
+// Images are returned to vision models whole (a Read of an image attachment, an
+// MCP screenshot). The byte size is large but token cost is driven by image
+// tokens, not base64 length, so allow multi-MB screenshots through instead of
+// clipping them to a "[truncated]" summary the model can't see. Clamp ceiling
+// (10MB) is enforced in resolveAgentCompactionPolicy.
+const DEFAULT_IMAGE_INLINE_MAX_BYTES = 5_000_000;
 const DEFAULT_TOOL_PAYLOAD_MAX_BYTES = 262144;
 const DEFAULT_MCP_CALL_TIMEOUT_MS = 120000;
+// Hard wall clock for a single MCP tool call. Progress notifications reset the
+// inactivity timeout above but must never extend a call past this cap (45 min) —
+// sized for legitimately long tools (audio transcription, ask-the-user waits).
+const DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS = 2_700_000;
 
+/**
+ * @param {*} value
+ * @param {number} fallback
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 function clampNumber(value, fallback, min, max) {
   const n = Number(value);
   if (!Number.isFinite(n)) return fallback;
   return Math.min(Math.max(n, min), max);
 }
 
+/**
+ * @param {*} value
+ * @param {number} fallback
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 function clampInteger(value, fallback, min, max) {
   return Math.floor(clampNumber(value, fallback, min, max));
 }
 
+/**
+ * @param {Object<string, *>} [settings]
+ * @param {Object} [model]
+ * @param {number} [model.contextWindow]
+ * @returns {AgentCompactionPolicy}
+ */
 export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
   const contextWindow = clampInteger(model?.contextWindow, DEFAULT_CONTEXT_WINDOW, 32000, 10_000_000);
   const triggerRatio = clampNumber(
@@ -57,6 +110,11 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
     triggerTokens: Math.min(ratioTrigger, reserveTrigger),
     keepRecentTokens: clampInteger(settings.agent_compaction_keep_recent_tokens, DEFAULT_KEEP_RECENT_TOKENS, 4000, 200000),
     summaryMaxTokens: clampInteger(settings.agent_compaction_summary_max_tokens, DEFAULT_SUMMARY_MAX_TOKENS, 1000, 64000),
+    // ON by default; the proactive fixed-overhead correction (system prompt +
+    // tool schemas + per-turn message) is disabled only when explicitly false.
+    // Read by the compaction driver off the resolved policy so it never has to
+    // re-sniff the raw settings/policy inputs.
+    fixedOverheadEnabled: settings.agent_compaction_fixed_overhead_enabled !== false,
     compactionMinSavingsTokens: clampInteger(settings.agent_compaction_min_savings_tokens, DEFAULT_MIN_SAVINGS_TOKENS, 0, 500000),
     toolPayloadCompactionTriggerChars: clampInteger(
       settings.agent_tool_payload_compaction_trigger_chars,
@@ -72,9 +130,194 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
     imageInlineMaxBytes: clampInteger(settings.agent_image_inline_max_bytes, DEFAULT_IMAGE_INLINE_MAX_BYTES, 0, 10 * 1024 * 1024),
     toolPayloadMaxBytes: clampInteger(settings.agent_tool_payload_max_bytes, DEFAULT_TOOL_PAYLOAD_MAX_BYTES, 0, 16 * 1024 * 1024),
     mcpCallTimeoutMs: clampInteger(settings.agent_mcp_call_timeout_ms, DEFAULT_MCP_CALL_TIMEOUT_MS, 1000, Number.MAX_SAFE_INTEGER),
+    mcpCallMaxTotalTimeoutMs: clampInteger(
+      settings.agent_mcp_call_max_total_timeout_ms,
+      DEFAULT_MCP_CALL_MAX_TOTAL_TIMEOUT_MS,
+      1000,
+      Number.MAX_SAFE_INTEGER,
+    ),
+  };
+}
+
+// --- Typed policy objects <-> deprecated `settings` shim -------------------
+//
+// RuntimeRunOptions now carries typed `toolLimits` / `compaction` policy
+// objects. The DEPRECATED `settings` bag remains a per-group fallback: it is
+// consumed only when the corresponding typed object is ABSENT, and consuming it
+// surfaces one `deprecated_settings_option` runtime_warning per run.
+//
+// resolveAgentCompactionPolicy stays the canonical settings->policy clamp/mapper
+// (its signature is unchanged — worklab deep-imports it). The helpers below
+// project the typed objects back onto the same snake_case settings keys so the
+// resolution goes through that one clamp path unchanged, whether the values came
+// from a typed object or the legacy settings bag.
+
+// Typed toolLimits field -> settings key. `bashTimeoutMs` is intentionally
+// ABSENT: no `agent_bash_*_timeout` setting exists today and this phase does not
+// invent new timeout behavior, so the field is documented on the RuntimeToolLimits
+// typedef but not wired through the settings shim or any tool.
+const TOOL_LIMIT_SETTINGS_KEYS = /** @type {const} */ ({
+  toolTextLimitChars: "agent_tool_text_limit_chars",
+  bashOutputLimitChars: "agent_bash_output_limit_chars",
+  mcpTextLimitChars: "agent_mcp_text_limit_chars",
+  searchResultLimit: "agent_search_result_limit",
+  imageInlineMaxBytes: "agent_image_inline_max_bytes",
+  toolPayloadMaxBytes: "agent_tool_payload_max_bytes",
+  mcpCallTimeoutMs: "agent_mcp_call_timeout_ms",
+  mcpCallMaxTotalTimeoutMs: "agent_mcp_call_max_total_timeout_ms",
+});
+
+// Typed compaction field -> settings key. `contextWindowOverride` is ABSENT: it
+// has no legacy settings equivalent and is applied directly at the live-window
+// resolution site (resolveLiveCompactionPolicy), not through this shim.
+const COMPACTION_SETTINGS_KEYS = /** @type {const} */ ({
+  enabled: "agent_compaction_enabled",
+  triggerRatio: "agent_compaction_trigger_ratio",
+  keepRecentTokens: "agent_compaction_keep_recent_tokens",
+  summaryMaxTokens: "agent_compaction_summary_max_tokens",
+  minSavingsTokens: "agent_compaction_min_savings_tokens",
+  fixedOverheadEnabled: "agent_compaction_fixed_overhead_enabled",
+});
+
+export const DEPRECATED_SETTINGS_WARNING_KIND = "deprecated_settings_option";
+
+/**
+ * @param {Object<string, *>|null|undefined} group
+ * @param {Record<string, string>} keyMap
+ * @param {Object<string, *>} out
+ */
+function copyTypedGroup(group, keyMap, out) {
+  for (const [field, settingKey] of Object.entries(keyMap)) {
+    if (group && group[field] !== undefined) out[settingKey] = group[field];
+  }
+}
+
+/**
+ * @param {Object<string, *>|null|undefined} settings
+ * @param {Record<string, string>} keyMap
+ * @param {Object<string, *>} out
+ * @param {Array<string>} consumed
+ */
+function copySettingsGroup(settings, keyMap, out, consumed) {
+  if (!settings || typeof settings !== "object") return;
+  for (const settingKey of Object.values(keyMap)) {
+    if (settings[settingKey] !== undefined) {
+      out[settingKey] = settings[settingKey];
+      consumed.push(settingKey);
+    }
+  }
+}
+
+/**
+ * Fold the typed `toolLimits` / `compaction` policy objects and the deprecated
+ * `settings` bag into ONE settings-like object resolveAgentCompactionPolicy
+ * consumes, honoring PER-GROUP precedence: when a typed object is present its
+ * fields win and the legacy settings keys for that group are ignored entirely;
+ * when the typed object is absent, that group's settings keys are consumed (and
+ * reported in `consumedSettingsKeys` so the caller can emit exactly one
+ * deprecation warning per run).
+ * @param {{toolLimits?: Object<string, *>, compaction?: Object<string, *>, settings?: Object<string, *>}} [options]
+ * @returns {{settingsLike: Object<string, *>, consumedSettingsKeys: Array<string>}}
+ */
+export function resolveRuntimePolicyInputs({ toolLimits, compaction, settings } = {}) {
+  /** @type {Object<string, *>} */
+  const settingsLike = {};
+  /** @type {Array<string>} */
+  const consumedSettingsKeys = [];
+
+  if (toolLimits && typeof toolLimits === "object") {
+    copyTypedGroup(toolLimits, TOOL_LIMIT_SETTINGS_KEYS, settingsLike);
+  } else {
+    copySettingsGroup(settings, TOOL_LIMIT_SETTINGS_KEYS, settingsLike, consumedSettingsKeys);
+  }
+
+  if (compaction && typeof compaction === "object") {
+    copyTypedGroup(compaction, COMPACTION_SETTINGS_KEYS, settingsLike);
+  } else {
+    copySettingsGroup(settings, COMPACTION_SETTINGS_KEYS, settingsLike, consumedSettingsKeys);
+  }
+
+  return { settingsLike, consumedSettingsKeys };
+}
+
+/**
+ * Build the one-per-run deprecation warning fired when the legacy `settings`
+ * bag was consumed as a policy fallback. Shape matches the other pi/claude
+ * bridge runtime warnings ({warning_kind, source, message}).
+ * @param {ReadonlyArray<string>} consumedKeys
+ * @returns {{warning_kind: string, source: string, message: string, settings_keys: Array<string>}}
+ */
+export function deprecatedSettingsWarning(consumedKeys) {
+  const keys = Array.from(consumedKeys || []);
+  return {
+    warning_kind: DEPRECATED_SETTINGS_WARNING_KIND,
+    source: "runtime",
+    message:
+      "runOptions.settings is deprecated; pass the typed `toolLimits` / `compaction` policy objects instead "
+      + "(host migration helper: resolveRuntimePolicies in @mono-agent/runtime-adapter). Consumed settings keys: "
+      + `${keys.join(", ")}.`,
+    settings_keys: keys,
+  };
+}
+
+// Estimate the FIXED per-request overhead the provider meters but the raw
+// transcript estimate excludes: the system prompt, the tool/MCP schemas, and the
+// per-turn user message(s). estimateCurrentContextTokens' raw branch sums ONLY
+// session.buildContext().messages (the transcript), so on a seeded session whose
+// last-assistant usage is stale/0 the proactive-compaction trigger under-counts
+// and under-fires, letting the real request overflow the window. Adding this
+// overhead to the raw estimate makes the trigger reflect what the provider counts.
+//
+// Uses Math.ceil(len/4) to mirror pi-ai's chars/4 heuristic — consistency with
+// the transcript estimate matters more than precision. Pure + dependency-free.
+/**
+ * @param {Object} [options]
+ * @param {string} [options.systemPrompt]
+ * @param {Array<Object>} [options.tools]
+ * @param {Array<Object>} [options.messages]
+ * @returns {{systemPromptTokens: number, toolSchemaTokens: number, userMessageTokens: number, fixedOverheadTokens: number}}
+ */
+export function estimateFixedOverheadTokens({ systemPrompt, tools, messages } = {}) {
+  const tokensForChars = (value) => Math.ceil(String(value ?? "").length / 4);
+
+  const systemPromptTokens = tokensForChars(systemPrompt);
+
+  let toolSchemaTokens = 0;
+  for (const tool of Array.isArray(tools) ? tools : []) {
+    try {
+      const serialized = JSON.stringify({
+        name: tool?.name,
+        description: tool?.description,
+        parameters: tool?.parameters ?? tool?.inputSchema ?? {},
+      });
+      toolSchemaTokens += tokensForChars(serialized);
+    } catch {
+      // Circular/unserializable tool schema — count it as 0 rather than throw.
+    }
+  }
+
+  let userMessageTokens = 0;
+  for (const message of Array.isArray(messages) ? messages : []) {
+    try {
+      userMessageTokens += tokensForChars(JSON.stringify(message?.content ?? ""));
+    } catch {
+      // Unserializable content — count it as 0 rather than throw.
+    }
+  }
+
+  return {
+    systemPromptTokens,
+    toolSchemaTokens,
+    userMessageTokens,
+    fixedOverheadTokens: systemPromptTokens + toolSchemaTokens + userMessageTokens,
   };
 }
 
+/**
+ * @param {string} message
+ * @param {Object<string, *>} [diagnostics]
+ * @returns {boolean}
+ */
 export function isLikelyContextTermination(message, diagnostics = {}) {
   const text = String(message || "");
   if (!/terminated|aborted before final output|aborted before final|stream.*aborted|context window|context budget/i.test(text)) return false;

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");