@mono-agent/agent-runtime 0.4.0 → 0.5.0

package/src/agent/tools/shared/path-resolver.js

@@ -1,20 +1,24 @@
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
-import { readToolRuntime, resolveSandboxPolicy } from "./runtime-context.js";
-
-function configured() {
-  const { workspace, repoRoot } = readToolRuntime();
+import { readToolRuntime } from "./runtime-context.js";
+import { resolveSandboxPolicy } from "./tool-context.js";
+
+// Every read here falls back to the module-default context when no per-instance
+// ToolContext is threaded (`ctx ?? readToolRuntime()`), so hosts that only call
+// the deep-path configureToolRuntime keep their historical behavior.
+function configured(ctx) {
+  const { workspace, repoRoot } = ctx ?? readToolRuntime();
   return { workspace, repoRoot };
 }
 
-export function workspaceRoot(workdir) {
-  const { workspace, repoRoot } = configured();
+export function workspaceRoot(workdir, ctx) {
+  const { workspace, repoRoot } = configured(ctx);
   return resolve(workdir || workspace || repoRoot || process.cwd());
 }
 
-export function resolveToolPath(path, workdir) {
+export function resolveToolPath(path, workdir, ctx) {
   if (!path || typeof path !== "string") return path;
-  return resolve(isAbsolute(path) ? path : resolve(workspaceRoot(workdir), path));
+  return resolve(isAbsolute(path) ? path : resolve(workspaceRoot(workdir, ctx), path));
 }
 
 export function isPathAllowed(path, workdir, options = {}) {
@@ -26,25 +30,27 @@ export function isWritablePathAllowed(path, workdir, options = {}) {
 }
 
 function isPathAllowedFor(path, workdir, access, options) {
-  const r = resolveToolPath(path, workdir);
-  const policy = resolveSandboxPolicy(options.sandboxPolicy);
+  const ctx = options.ctx;
+  const r = resolveToolPath(path, workdir, ctx);
+  const policy = resolveSandboxPolicy(ctx ?? readToolRuntime(), options.sandboxPolicy);
   if (policy) {
     const field = access === "write" ? policy.writableRoots : policy.readableRoots;
     return insideSandboxRoots(Array.isArray(field) ? field : [], r)
-      && (access !== "write" || !sandboxDeniesWrite(policy, r));
+      && (access !== "write" || !sandboxDeniesWrite(policy, r, ctx));
   }
-  const { workspace, repoRoot } = configured();
+  const { workspace, repoRoot } = configured(ctx);
   return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r);
 }
 
 export function isWorkdirAllowed(workdir, options = {}) {
   if (!workdir) return true;
+  const ctx = options.ctx;
   const r = resolve(workdir);
-  const policy = resolveSandboxPolicy(options.sandboxPolicy);
+  const policy = resolveSandboxPolicy(ctx ?? readToolRuntime(), options.sandboxPolicy);
   if (policy) {
     return insideSandboxRoots(Array.isArray(policy.readableRoots) ? policy.readableRoots : [], r);
   }
-  const { workspace, repoRoot } = configured();
+  const { workspace, repoRoot } = configured(ctx);
   return insideLegacyRoots([workspace, repoRoot, process.cwd(), "/tmp"], r);
 }
 
@@ -95,21 +101,21 @@ function realTargetPath(target) {
   return resolved;
 }
 
-function sandboxDeniesWrite(policy, target) {
+function sandboxDeniesWrite(policy, target, ctx) {
   const patterns = Array.isArray(policy.denyWrite) ? policy.denyWrite : [];
   if (patterns.length === 0) return false;
   const candidates = [...new Set([resolve(target), realTargetPath(target)])];
   return candidates.some((candidate) =>
-    patterns.some((pattern) => denyWritePatternMatches(policy, pattern, candidate)));
+    patterns.some((pattern) => denyWritePatternMatches(policy, pattern, candidate, ctx)));
 }
 
-function denyWritePatternMatches(policy, pattern, target) {
+function denyWritePatternMatches(policy, pattern, target, ctx) {
   if (!pattern || typeof pattern !== "string") return false;
   const normalizedPattern = normalizeMatchPath(pattern);
   if (isAbsolute(pattern)) {
     return globPatternMatches(normalizedPattern, normalizeMatchPath(target));
   }
-  const root = resolve(policy.root || workspaceRoot());
+  const root = resolve(policy.root || workspaceRoot(undefined, ctx));
   const rel = relative(root, resolve(target));
   if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return false;
   return globPatternMatches(stripDotSlash(normalizedPattern), normalizeMatchPath(rel));

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

@@ -9,18 +9,31 @@ import {
 } from "./constants.js";
 import { boundedInt } from "./dedup.js";
 import { writeToolArtifact } from "./output-truncation.js";
-import { readRuntimeBrand, readToolRuntime } from "./runtime-context.js";
+import { readToolRuntime } from "./runtime-context.js";
 
 const requireFromHere = createRequire(import.meta.url);
 
 // Lazy so the message respects whatever runtimeBrand the host configured.
-export function ripgrepMissingMessage() {
-  const brand = readRuntimeBrand();
+export function ripgrepMissingMessage(ctx) {
+  const brand = (ctx ?? readToolRuntime()).runtimeBrand;
   return `Error: ripgrep (rg) is not available. Configure ripgrepPath via configureToolRuntime() or install ripgrep on PATH; run \`${brand.doctorCommand}\` for details.`;
 }
 
 // Mutable cache of the resolved ripgrep binary path. Stored on an object so
 // callers can read the latest value without re-importing the module.
+//
+// KNOWN cross-runtime sharing (pre-existing, out of scope for the per-instance
+// ToolContext work): this cache is MODULE-LEVEL, not per-ToolContext. The first
+// resolveRgPath call to resolve a non-undefined value wins process-wide, so two
+// createRuntime instances configured with DIFFERENT ripgrepPath values share
+// whichever binary was resolved first (a later instance's ripgrepPath is
+// ignored unless it passes `{refresh: true}`). Unlike workspace/repoRoot/
+// sandbox/brand — which are fully isolated per instance via ToolContext — the
+// ripgrep binary path is effectively global. In practice every runtime in a
+// process resolves the same vendored/PATH binary, so this is benign; it is
+// documented (and asserted as a known-shared cache in the two-runtimes
+// isolation test) rather than fixed, since a per-instance rg cache would be a
+// larger change with no real-world payoff today.
 export const cachedRgPath = { value: undefined };
 
 function vendoredRgPath() {
@@ -51,9 +64,12 @@ function rgFromPath() {
   return null;
 }
 
-export function resolveRgPath({ refresh = false } = {}) {
+/**
+ * @param {{refresh?: boolean, ctx?: any}} [options]
+ */
+export function resolveRgPath({ refresh = false, ctx } = {}) {
   if (!refresh && cachedRgPath.value !== undefined) return cachedRgPath.value;
-  const { ripgrepPath } = readToolRuntime();
+  const { ripgrepPath } = ctx ?? readToolRuntime();
   if (ripgrepPath) {
     cachedRgPath.value = existsSync(ripgrepPath) ? ripgrepPath : null;
   } else {
@@ -76,12 +92,17 @@ export function normalizeGlobPattern(pattern) {
   return raw || "**/*";
 }
 
+/**
+ * @param {any} rawLines
+ * @param {{label?: string, noMatches?: string, maxLines?: number, maxChars?: number, offset?: number, ctx?: any}} [options]
+ */
 export function formatSearchLines(rawLines, {
   label,
   noMatches,
   maxLines = DEFAULT_MAX_SEARCH_LINES,
   maxChars = DEFAULT_MAX_SEARCH_CHARS,
   offset = 0,
+  ctx,
 } = {}) {
   const lines = Array.isArray(rawLines) ? rawLines.filter(Boolean) : String(rawLines || "").trim().split("\n").filter(Boolean);
   if (!lines.length) return noMatches;
@@ -99,7 +120,7 @@ export function formatSearchLines(rawLines, {
   }
   if (kept.length === slice.length) return kept.join("\n");
   const fullText = lines.join("\n");
-  const artifact = writeToolArtifact(label, fullText);
+  const artifact = writeToolArtifact(label, fullText, ctx);
   const suffix = [
     `[truncated ${label || "search"} result: showing ${kept.length} of ${total} lines after excluding generated/vendor paths.`,
     start ? `Offset ${start} was applied.` : null,
@@ -109,12 +130,17 @@ export function formatSearchLines(rawLines, {
   return `${kept.join("\n")}\n\n${suffix}`;
 }
 
+/**
+ * @param {string} text
+ * @param {{label?: string, noMatches?: string, maxLines?: number, maxChars?: number, offset?: number, ctx?: any}} [options]
+ */
 export function capLines(text, {
   label,
   noMatches,
   maxLines = DEFAULT_MAX_SEARCH_LINES,
   maxChars = DEFAULT_MAX_SEARCH_CHARS,
   offset = 0,
+  ctx,
 } = {}) {
   return formatSearchLines(String(text || "").trim().split("\n").filter(Boolean), {
     label,
@@ -122,6 +148,7 @@ export function capLines(text, {
     maxLines,
     maxChars,
     offset,
+    ctx,
   });
 }
 

package/src/agent/tools/shared/runtime-context.js

@@ -1,69 +1,79 @@
-// Process-level configuration for the agent kernel's internal tool helpers.
-// The host configures this once at worker boot; internal
-// modules (output-truncation, ripgrep, path-resolver, pi-bridge) read from
-// it instead of reaching into process.env.
+// Module-level DEFAULT tool context — the back-compat layer over tool-context.js.
 //
-// Single shared object is acceptable because the worker is one-task-per-process.
+// Historically this file held the one-per-process tool-runtime singleton. That
+// assumed one task per process, which is false in a long-lived multi-channel
+// host: two `createRuntime` instances clobbered each other's workspace /
+// repoRoot / sandboxPolicy / brand. The per-instance ToolContext (tool-context.js)
+// fixes that — `createRuntime` now builds its own context and threads it to
+// bridges as `options.toolContext`.
 //
-// Recognized keys:
-//   workspace        — fallback for tool workdir resolution. Default: process.cwd().
-//   repoRoot         — secondary allowed root (the host's installation root).
-//                      Tool path-allowlist checks accept this in addition to workspace.
-//   runId            — used as the subdirectory under toolArtifactDir for tool output.
-//   toolArtifactDir  — root for {dir}/tool-output/{runId}/{file} artifact writes
-//                      from capChars/formatSearchLines. Null = no persistence.
-//   ripgrepPath      — absolute path to the ripgrep binary. When unset, falls
-//                      back to vendored binary, then PATH lookup.
-//   qaOutputDir      — fallback for normalizeMcpToolParams when the per-call
-//                      runArtifactDir isn't supplied.
-//   sandboxPolicy    — optional strict filesystem/process/network sandbox policy.
-//   runtimeBrand     — resolved RuntimeBrand object (see runtime-brand.js).
-//                      Internal helpers read it to stamp host-specific names
-//                      (MCP client name, transcript schema id, doctor command).
+// This module survives as the DEFAULT context every internal read site falls
+// back to when no per-instance context was threaded (`ctx ?? readToolRuntime()`).
+// Hosts that only call the deep-path `configureToolRuntime` (e.g. worklab's
+// worker.js / doctor.js) get byte-for-byte identical behavior to before: they
+// configure this default context and the tools read it.
+//
+// The public exports are unchanged: configureToolRuntime / readToolRuntime /
+// readRuntimeBrand / resetToolRuntime (plus the internal resolveSandboxPolicy
+// default-context convenience). See tool-context.js for the recognized keys.
+
+// @ts-check
+
+import {
+  createToolContext,
+  resetToolContext,
+  updateToolContext,
+  resolveSandboxPolicy as resolveContextSandboxPolicy,
+} from "./tool-context.js";
+import { DEFAULT_RUNTIME_BRAND } from "../../../runtime-brand.js";
 
-import { mergeSandboxPolicies } from "@mono-agent/sandbox";
-import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-brand.js";
+/** @typedef {import('./tool-context.js').ToolContext} ToolContext */
+/**
+ * @typedef {ToolContext} ToolRuntimeContext
+ * Back-compat alias for the historical name.
+ */
 
-const context = {
-  workspace: undefined,
-  repoRoot: undefined,
-  runId: undefined,
-  toolArtifactDir: undefined,
-  ripgrepPath: undefined,
-  qaOutputDir: undefined,
-  sandboxPolicy: undefined,
-  runtimeBrand: { ...DEFAULT_RUNTIME_BRAND },
-};
+/** @type {ToolContext} */
+const defaultContext = createToolContext({});
 
+/**
+ * @param {Partial<ToolContext>} [next]
+ * @returns {void}
+ */
 export function configureToolRuntime(next = {}) {
-  for (const key of Object.keys(context)) {
-    if (key === "runtimeBrand") continue;
-    if (key in next) context[key] = next[key];
-  }
-  if (next.runtimeBrand !== undefined) {
-    context.runtimeBrand = resolveRuntimeBrand(next.runtimeBrand);
-  }
+  updateToolContext(defaultContext, next);
 }
 
+/**
+ * @returns {ToolContext}
+ */
 export function readToolRuntime() {
-  return context;
+  return defaultContext;
 }
 
-// Single source of truth for the sandbox policy a tool call runs under.
-// Merging (rather than letting the per-call option shadow the context policy)
-// keeps the guarantee monotonic: a request-scoped policy can tighten the
-// host-configured policy but never weaken or disable it.
+// Default-context convenience: resolves a request policy against the module
+// default context. Internal read sites that carry a per-instance context call
+// tool-context.js's `resolveSandboxPolicy(ctx, requestPolicy)` directly with
+// `ctx ?? readToolRuntime()`; this wrapper preserves the historical
+// single-argument signature for the default path.
+/**
+ * @param {import('../../sandbox-seam.js').SandboxPolicy} [requestPolicy]
+ * @returns {import('../../sandbox-seam.js').SandboxPolicy|undefined}
+ */
 export function resolveSandboxPolicy(requestPolicy = undefined) {
-  const merged = mergeSandboxPolicies(context.sandboxPolicy ?? undefined, requestPolicy ?? undefined);
-  return merged && merged.mode !== "off" ? merged : undefined;
+  return resolveContextSandboxPolicy(defaultContext, requestPolicy);
 }
 
+/**
+ * @returns {import('../../../runtime-brand.js').RuntimeBrand}
+ */
 export function readRuntimeBrand() {
-  return context.runtimeBrand || { ...DEFAULT_RUNTIME_BRAND };
+  return defaultContext.runtimeBrand || { ...DEFAULT_RUNTIME_BRAND };
 }
 
+/**
+ * @returns {void}
+ */
 export function resetToolRuntime() {
-  for (const key of Object.keys(context)) {
-    context[key] = key === "runtimeBrand" ? { ...DEFAULT_RUNTIME_BRAND } : undefined;
-  }
+  resetToolContext(defaultContext);
 }

package/src/agent/tools/shared/tool-context.js

@@ -0,0 +1,157 @@
+// Per-runtime-instance tool context.
+//
+// A ToolContext carries the configuration the kernel's internal tool helpers
+// (output-truncation, ripgrep, path-resolver, pi-bridge, the tool impls) need
+// to resolve workdirs, artifact paths, the ripgrep binary, sandbox policy, and
+// host-specific brand strings. `createRuntime` builds ONE context per runtime
+// instance and threads it to every bridge via `options.toolContext`; tools read
+// from it instead of a process-global. This replaces the former one-per-process
+// singleton (see runtime-context.js) that clobbered its fields when a
+// long-lived host created more than one runtime.
+//
+// This module is pure: it owns no module-level state. The default/back-compat
+// singleton lives in runtime-context.js, which builds its own ToolContext with
+// createToolContext and mutates it with updateToolContext. Every internal read
+// site falls back to that default via `ctx ?? readToolRuntime()`.
+//
+// Recognized keys:
+//   workspace        — fallback for tool workdir resolution. Default: process.cwd().
+//   repoRoot         — secondary allowed root (the host's installation root).
+//                      Tool path-allowlist checks accept this in addition to workspace.
+//   runId            — used as the subdirectory under toolArtifactDir for tool output.
+//   toolArtifactDir  — root for {dir}/tool-output/{runId}/{file} artifact writes
+//                      from capChars/formatSearchLines. Null = no persistence.
+//   ripgrepPath      — absolute path to the ripgrep binary. When unset, falls
+//                      back to vendored binary, then PATH lookup.
+//   qaOutputDir      — fallback for normalizeMcpToolParams when the per-call
+//                      runArtifactDir isn't supplied.
+//   sandboxPolicy    — optional strict filesystem/process/network sandbox policy.
+//   sandboxEngine    — optional concrete engine handed to the injected sandbox
+//                      implementation when it prepares subprocess commands.
+//   sandbox          — RuntimeSandbox implementation the policy is enforced
+//                      through (see ../../sandbox-seam.js). Always resolved,
+//                      like runtimeBrand: defaults to passthroughSandbox when
+//                      a host doesn't inject a real one.
+//   runtimeBrand     — resolved RuntimeBrand object (see runtime-brand.js).
+//                      Internal helpers read it to stamp host-specific names
+//                      (MCP client name, transcript schema id, doctor command).
+
+// @ts-check
+
+import { passthroughSandbox } from "../../sandbox-seam.js";
+import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-brand.js";
+
+/** @typedef {import('../../../runtime-brand.js').RuntimeBrand} RuntimeBrand */
+/** @typedef {import('../../sandbox-seam.js').SandboxPolicy} SandboxPolicy */
+/** @typedef {import('../../sandbox-seam.js').RuntimeSandboxEngine} RuntimeSandboxEngine */
+/** @typedef {import('../../sandbox-seam.js').RuntimeSandbox} RuntimeSandbox */
+
+/**
+ * @typedef {Object} ToolContext
+ * @property {string} [workspace]
+ * @property {string} [repoRoot]
+ * @property {string} [runId]
+ * @property {string} [toolArtifactDir]
+ * @property {string} [ripgrepPath]
+ * @property {string} [qaOutputDir]
+ * @property {SandboxPolicy} [sandboxPolicy]
+ * @property {RuntimeSandboxEngine} [sandboxEngine]
+ * @property {RuntimeSandbox} sandbox
+ * @property {RuntimeBrand} runtimeBrand
+ */
+
+// The data keys (everything except the always-resolved runtimeBrand). A fixed
+// list — not `Object.keys(ctx)` — so an unknown key on `next` is ignored, matching
+// the historical configureToolRuntime contract.
+const TOOL_CONTEXT_KEYS = /** @type {const} */ ([
+  "workspace",
+  "repoRoot",
+  "runId",
+  "toolArtifactDir",
+  "ripgrepPath",
+  "qaOutputDir",
+  "sandboxPolicy",
+  "sandboxEngine",
+]);
+
+/**
+ * Build a fresh ToolContext from a partial input. `runtimeBrand` is always
+ * resolved (to the defaults when absent); the remaining keys default to
+ * undefined and are copied from `input` when present.
+ * @param {Partial<ToolContext>} [input]
+ * @returns {ToolContext}
+ */
+export function createToolContext(input = {}) {
+  /** @type {ToolContext} */
+  const ctx = {
+    workspace: undefined,
+    repoRoot: undefined,
+    runId: undefined,
+    toolArtifactDir: undefined,
+    ripgrepPath: undefined,
+    qaOutputDir: undefined,
+    sandboxPolicy: undefined,
+    sandboxEngine: undefined,
+    sandbox: passthroughSandbox,
+    runtimeBrand: { ...DEFAULT_RUNTIME_BRAND },
+  };
+  return updateToolContext(ctx, input);
+}
+
+/**
+ * Mutate an existing ToolContext in place with the keys present on `next`,
+ * leaving untouched keys as-is. Mutating in place (rather than returning a
+ * copy) is deliberate: `createRuntime` threads a single context object to its
+ * bridges and `configureTools` updates that same reference so subsequent runs
+ * observe the change — the instance-scoped equivalent of the old global
+ * configureToolRuntime.
+ * @param {ToolContext} ctx
+ * @param {Partial<ToolContext>} [next]
+ * @returns {ToolContext}
+ */
+export function updateToolContext(ctx, next = {}) {
+  for (const key of TOOL_CONTEXT_KEYS) {
+    // Per-key assignment across a heterogeneous record: TS can't correlate the
+    // looked-up value type with `key` across two independent indexed accesses
+    // (a known structural limitation, not a real type hazard here).
+    if (key in next) ctx[key] = /** @type {any} */ (next)[key];
+  }
+  if (next.sandbox !== undefined) {
+    ctx.sandbox = next.sandbox;
+  }
+  if (next.runtimeBrand !== undefined) {
+    ctx.runtimeBrand = resolveRuntimeBrand(next.runtimeBrand);
+  }
+  return ctx;
+}
+
+/**
+ * Reset every data key to undefined and the brand back to the defaults.
+ * @param {ToolContext} ctx
+ * @returns {ToolContext}
+ */
+export function resetToolContext(ctx) {
+  for (const key of TOOL_CONTEXT_KEYS) {
+    ctx[key] = /** @type {any} */ (undefined);
+  }
+  ctx.sandbox = passthroughSandbox;
+  ctx.runtimeBrand = { ...DEFAULT_RUNTIME_BRAND };
+  return ctx;
+}
+
+// Single source of truth for the sandbox policy a tool call runs under.
+// Merging (rather than letting the per-call option shadow the context policy)
+// keeps the guarantee monotonic (I13): a request-scoped policy can tighten the
+// host-configured policy but never weaken or disable it. The merge itself is
+// delegated to `ctx.sandbox.mergePolicies` (defaulting to passthroughSandbox)
+// so the actual algorithm is host-injected, not hard-coded here.
+/**
+ * @param {ToolContext|undefined} ctx
+ * @param {SandboxPolicy} [requestPolicy]
+ * @returns {SandboxPolicy|undefined}
+ */
+export function resolveSandboxPolicy(ctx, requestPolicy = undefined) {
+  const sandbox = ctx?.sandbox ?? passthroughSandbox;
+  const merged = sandbox.mergePolicies(ctx?.sandboxPolicy ?? undefined, requestPolicy ?? undefined);
+  return merged && merged.mode !== "off" ? merged : undefined;
+}

package/src/agent/tools/web-fetch.js

@@ -1,7 +1,8 @@
 import { DEFAULT_MAX_TOOL_OUTPUT_CHARS } from "./shared/constants.js";
 import { capChars } from "./shared/output-truncation.js";
-import { networkPolicyAllowsUrl } from "@mono-agent/sandbox";
-import { resolveSandboxPolicy } from "./shared/runtime-context.js";
+import { passthroughSandbox } from "../sandbox-seam.js";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const FETCH_TIMEOUT_MS = 15000;
 const MAX_REDIRECTS = 5;
@@ -21,9 +22,13 @@ function fetchRetryDelay(ms) {
   return new Promise((resolve) => { setTimeout(resolve, ms); });
 }
 
+/**
+ * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number}} params
+ * @param {{sandboxPolicy?: any, ctx?: any, retryDelaysMs?: number[]}} [options]
+ */
 export async function webFetchToolImpl(
   { url, headers = {}, max_output_chars },
-  { sandboxPolicy, retryDelaysMs = DEFAULT_FETCH_RETRY_DELAYS_MS } = {},
+  { sandboxPolicy, ctx, retryDelaysMs = DEFAULT_FETCH_RETRY_DELAYS_MS } = {},
 ) {
   const maxChars = Number(max_output_chars) || DEFAULT_MAX_TOOL_OUTPUT_CHARS;
   let parsed;
@@ -31,17 +36,23 @@ export async function webFetchToolImpl(
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     return "Error: WebFetch only supports http(s) URLs.";
   }
-  const policy = resolveSandboxPolicy(sandboxPolicy);
-  if (!networkPolicyAllowsUrl(policy, parsed.href)) return "Error: Network access denied by sandbox policy.";
+  const resolvedCtx = ctx ?? readToolRuntime();
+  const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+  if (!sandbox.networkAllowsUrl(policy, parsed.href)) return "Error: Network access denied by sandbox policy.";
   const requestHeaders = { "User-Agent": "AgentRuntime/0.1", ...headers };
-  const restricted = policy !== undefined && policy.network.mode !== "all";
+  // `policy.network` can be absent (a hand-built, non-real-mode policy — the
+  // networkAllowsUrl gate above already denied any real-mode policy missing
+  // it); treat that as unrestricted rather than dereferencing `.mode` on
+  // undefined.
+  const restricted = policy !== undefined && policy.network !== undefined && policy.network.mode !== "all";
   const maxRetries = Array.isArray(retryDelaysMs) ? retryDelaysMs.length : 0;
 
   let lastErrorMessage = "request failed";
   for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
     try {
       const resp = restricted
-        ? await fetchCheckingRedirects(parsed, requestHeaders, policy)
+        ? await fetchCheckingRedirects(parsed, requestHeaders, policy, sandbox)
         : await fetch(url, { headers: requestHeaders, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
       if (typeof resp === "string") return resp; // policy/redirect error — not retryable
       // Transient server errors (5xx) are worth one more attempt.
@@ -53,7 +64,7 @@ export async function webFetchToolImpl(
       }
       const text = await resp.text();
       if (!resp.ok) return `HTTP ${resp.status}: ${text.slice(0, 500)}`;
-      return capChars(text, { label: "WebFetch", maxChars });
+      return capChars(text, { label: "WebFetch", maxChars, ctx });
     } catch (err) {
       lastErrorMessage = err.message;
       if (isTransientFetchError(err) && attempt < maxRetries) {
@@ -69,7 +80,7 @@ export async function webFetchToolImpl(
 // fetch() follows redirects transparently, which would let an allowed host
 // bounce the request to a denied one — follow them manually and re-check the
 // policy on every hop. Custom headers only travel to the original origin.
-async function fetchCheckingRedirects(initialUrl, headers, policy) {
+async function fetchCheckingRedirects(initialUrl, headers, policy, sandbox) {
   let current = initialUrl;
   for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
     const sameOrigin = current.origin === initialUrl.origin;
@@ -85,7 +96,7 @@ async function fetchCheckingRedirects(initialUrl, headers, policy) {
     if (next.protocol !== "http:" && next.protocol !== "https:") {
       return "Error: WebFetch only supports http(s) URLs.";
     }
-    if (!networkPolicyAllowsUrl(policy, next.href)) {
+    if (!sandbox.networkAllowsUrl(policy, next.href)) {
       return "Error: Network access denied by sandbox policy (redirect).";
     }
     try { await resp.body?.cancel(); } catch { /* best-effort */ }

package/src/agent/tools/web-search.js

@@ -1,10 +1,17 @@
-import { networkPolicyAllowsUrl } from "@mono-agent/sandbox";
-import { resolveSandboxPolicy } from "./shared/runtime-context.js";
+import { passthroughSandbox } from "../sandbox-seam.js";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
-export async function webSearchToolImpl({ query, limit = 5 }, { sandboxPolicy } = {}) {
+/**
+ * @param {{query: string, limit?: number}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export async function webSearchToolImpl({ query, limit = 5 }, { sandboxPolicy, ctx } = {}) {
   const max = Math.min(Math.max(Number(limit) || 5, 1), 10);
   const url = `https://duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
-  if (!networkPolicyAllowsUrl(resolveSandboxPolicy(sandboxPolicy), url)) return "Error: Network access denied by sandbox policy.";
+  const resolvedCtx = ctx ?? readToolRuntime();
+  const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  if (!sandbox.networkAllowsUrl(resolveSandboxPolicy(resolvedCtx, sandboxPolicy), url)) return "Error: Network access denied by sandbox policy.";
   const resp = await fetch(url, {
     headers: { "User-Agent": "Mozilla/5.0 AgentRuntime/0.1" },
     signal: AbortSignal.timeout(15000),

package/src/agent/tools/write.js

@@ -3,9 +3,13 @@ import { dirname } from "node:path";
 import { MAX_WRITE_BYTES } from "./shared/constants.js";
 import { isWritablePathAllowed, resolveToolPath } from "./shared/path-resolver.js";
 
-export async function writeToolImpl({ file_path, content, workdir }, { sandboxPolicy } = {}) {
-  const target = resolveToolPath(file_path, workdir);
-  if (!isWritablePathAllowed(target, workdir, { sandboxPolicy })) return `Error: Path not allowed: ${file_path}`;
+/**
+ * @param {{file_path: string, content?: string, workdir?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ */
+export async function writeToolImpl({ file_path, content, workdir }, { sandboxPolicy, ctx } = {}) {
+  const target = resolveToolPath(file_path, workdir, ctx);
+  if (!isWritablePathAllowed(target, workdir, { sandboxPolicy, ctx })) return `Error: Path not allowed: ${file_path}`;
   const bytes = Buffer.byteLength(content || "", "utf8");
   if (bytes > MAX_WRITE_BYTES) return `Error: Content too large (${bytes} bytes)`;
   mkdirSync(dirname(target), { recursive: true });

package/src/agent/transcript.js

@@ -84,6 +84,17 @@ function summarizeTurn(turn, { maxChars = DEFAULT_TURN_SUMMARY_CHARS } = {}) {
 // is nothing usable to resume from. Older turns beyond `verbatimTurns` are
 // summarized into a one-paragraph snippet; only the trailing `verbatimTurns`
 // keep their full assistant text + tool detail.
+/**
+ * @param {Array<*>} events
+ * @param {Object} [options]
+ * @param {number} [options.maxTurns]
+ * @param {number} [options.verbatimTurns]
+ * @param {number} [options.maxChars]
+ * @param {number} [options.toolResultChars]
+ * @param {number} [options.assistantTextChars]
+ * @param {number} [options.turnSummaryChars]
+ * @param {import('../runtime-brand.js').RuntimeBrand} [options.runtimeBrand]
+ */
 export function buildTranscriptTailSnapshot(events, {
   maxTurns = DEFAULT_MAX_TURNS,
   verbatimTurns = DEFAULT_VERBATIM_TURNS,
@@ -91,6 +102,10 @@ export function buildTranscriptTailSnapshot(events, {
   toolResultChars = DEFAULT_TOOL_RESULT_CHARS,
   assistantTextChars = DEFAULT_ASSISTANT_TEXT_CHARS,
   turnSummaryChars = DEFAULT_TURN_SUMMARY_CHARS,
+  // The resolved RuntimeBrand for the schema id. The router (the only caller)
+  // threads the instance brand; absent (deep/default callers) it falls back to
+  // the module-default context brand.
+  runtimeBrand,
 } = {}) {
   if (!Array.isArray(events) || events.length === 0) return null;
   const turns = [];
@@ -154,7 +169,7 @@ export function buildTranscriptTailSnapshot(events, {
     turn_index: turns.length - tailWindow.length + idx + 1,
     summary: summarizeTurn(turn, { maxChars: turnSummaryChars }),
   }));
-  const brand = readRuntimeBrand();
+  const brand = runtimeBrand ?? readRuntimeBrand();
   const snapshot = {
     schema: `${brand.schemaPrefix}.transcript-tail.v1`,
     captured_at: Date.now(),