@mono-agent/agent-runtime 0.1.0

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

@@ -0,0 +1,31 @@
+import { statSync } from "node:fs";
+import { MAX_READ_LINE_CHARS, READ_HISTORY_LIMIT } from "./constants.js";
+
+export const readHistory = new Map();
+
+export function boundedInt(value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(Math.floor(n), min), max);
+}
+
+export function safeStat(path) {
+  try { return statSync(path); } catch { return null; }
+}
+
+export function rememberRead(target, start, count) {
+  const key = `${target}:${start}:${count}`;
+  const repeated = readHistory.has(key);
+  readHistory.set(key, Date.now());
+  if (readHistory.size > READ_HISTORY_LIMIT) {
+    const oldest = [...readHistory.entries()].sort((a, b) => a[1] - b[1]).slice(0, readHistory.size - READ_HISTORY_LIMIT);
+    for (const [entry] of oldest) readHistory.delete(entry);
+  }
+  return repeated;
+}
+
+export function trimLine(line) {
+  const text = String(line ?? "");
+  if (text.length <= MAX_READ_LINE_CHARS) return text;
+  return `${text.slice(0, MAX_READ_LINE_CHARS)} [line truncated at ${MAX_READ_LINE_CHARS} of ${text.length} chars]`;
+}

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

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { DEFAULT_MAX_TOOL_OUTPUT_CHARS } from "./constants.js";
+import { boundedInt } from "./dedup.js";
+import { readToolRuntime } from "./runtime-context.js";
+
+function sanitizeName(value) {
+  return String(value || "tool").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "tool";
+}
+
+export function writeToolArtifact(label, text) {
+  const { toolArtifactDir, runId } = readToolRuntime();
+  if (!toolArtifactDir) return null;
+  try {
+    const safeRunId = sanitizeName(runId || "manual");
+    const dir = resolve(toolArtifactDir, "tool-output", safeRunId);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${Date.now()}-${sanitizeName(label)}-${randomUUID()}.txt`);
+    writeFileSync(path, String(text || ""), "utf8");
+    return { path, bytes: Buffer.byteLength(String(text || ""), "utf8") };
+  } catch {
+    return null;
+  }
+}
+
+export function truncationSuffix({ label, shown, total, artifact, hint }) {
+  return [
+    "",
+    `[truncated ${label} output: showing ${shown} of ${total} characters.]`,
+    artifact ? `Full output saved to: ${artifact.path}` : null,
+    hint || "Use a narrower path, range, command, or query for the missing detail.",
+  ].filter(Boolean).join("\n");
+}
+
+export function capChars(text, {
+  label = "tool",
+  maxChars = DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+  strategy = "head",
+  hint,
+} = {}) {
+  const value = String(text || "");
+  const limit = boundedInt(maxChars, DEFAULT_MAX_TOOL_OUTPUT_CHARS, { min: 200 });
+  if (value.length <= limit) return value;
+  const artifact = writeToolArtifact(label, value);
+  const suffix = truncationSuffix({ label, shown: limit, total: value.length, artifact, hint });
+  const budget = Math.max(0, limit - suffix.length);
+  if (strategy === "head_tail" && budget > 200) {
+    const head = Math.floor(budget * 0.6);
+    const tail = Math.max(0, budget - head - 40);
+    return `${value.slice(0, head)}\n\n[... middle omitted ...]\n\n${value.slice(Math.max(0, value.length - tail))}${suffix}`;
+  }
+  return `${value.slice(0, budget)}${suffix}`;
+}

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

@@ -0,0 +1,156 @@
+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();
+  return { workspace, repoRoot };
+}
+
+export function workspaceRoot(workdir) {
+  const { workspace, repoRoot } = configured();
+  return resolve(workdir || workspace || repoRoot || process.cwd());
+}
+
+export function resolveToolPath(path, workdir) {
+  if (!path || typeof path !== "string") return path;
+  return resolve(isAbsolute(path) ? path : resolve(workspaceRoot(workdir), path));
+}
+
+export function isPathAllowed(path, workdir, options = {}) {
+  return isPathAllowedFor(path, workdir, "read", options);
+}
+
+export function isWritablePathAllowed(path, workdir, options = {}) {
+  return isPathAllowedFor(path, workdir, "write", options);
+}
+
+function isPathAllowedFor(path, workdir, access, options) {
+  const r = resolveToolPath(path, workdir);
+  const policy = resolveSandboxPolicy(options.sandboxPolicy);
+  if (policy) {
+    const field = access === "write" ? policy.writableRoots : policy.readableRoots;
+    return insideSandboxRoots(Array.isArray(field) ? field : [], r)
+      && (access !== "write" || !sandboxDeniesWrite(policy, r));
+  }
+  const { workspace, repoRoot } = configured();
+  return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r);
+}
+
+export function isWorkdirAllowed(workdir, options = {}) {
+  if (!workdir) return true;
+  const r = resolve(workdir);
+  const policy = resolveSandboxPolicy(options.sandboxPolicy);
+  if (policy) {
+    return insideSandboxRoots(Array.isArray(policy.readableRoots) ? policy.readableRoots : [], r);
+  }
+  const { workspace, repoRoot } = configured();
+  return insideLegacyRoots([workspace, repoRoot, process.cwd(), "/tmp"], r);
+}
+
+// Sandbox roots also enforce realpath containment so a symlink inside an
+// allowed root cannot escape to a target outside the policy.
+function insideSandboxRoots(roots, target) {
+  const allowedRoots = normalizeRoots(roots);
+  const real = realTargetPath(target);
+  return allowedRoots.some((root) => isInsidePath(root, target))
+    && allowedRoots.some((root) => isInsidePath(root, real));
+}
+
+// Without a sandbox policy, keep the historical literal containment check —
+// symlinks out of the workspace (npm link et al.) stay usable by default.
+function insideLegacyRoots(roots, target) {
+  const allowedRoots = [...new Set(roots.filter(Boolean).map((p) => resolve(p)))];
+  return allowedRoots.some((root) => isInsidePath(root, target));
+}
+
+function normalizeRoots(paths) {
+  const out = new Set();
+  for (const path of paths.filter(Boolean)) {
+    const resolved = resolve(path);
+    out.add(resolved);
+    out.add(realTargetPath(resolved));
+  }
+  return [...out];
+}
+
+export function isInsidePath(root, target) {
+  if (!root || !target) return false;
+  const rel = relative(resolve(root), resolve(target));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function realTargetPath(target) {
+  const resolved = resolve(target);
+  if (existsSync(resolved)) {
+    try { return realpathSync(resolved); } catch { return resolved; }
+  }
+  let current = dirname(resolved);
+  while (current && current !== dirname(current)) {
+    if (existsSync(current)) {
+      try { return resolve(realpathSync(current), relative(current, resolved)); } catch { return resolved; }
+    }
+    current = dirname(current);
+  }
+  return resolved;
+}
+
+function sandboxDeniesWrite(policy, target) {
+  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)));
+}
+
+function denyWritePatternMatches(policy, pattern, target) {
+  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 rel = relative(root, resolve(target));
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return false;
+  return globPatternMatches(stripDotSlash(normalizedPattern), normalizeMatchPath(rel));
+}
+
+function normalizeMatchPath(path) {
+  return path.replaceAll("\\", "/");
+}
+
+function stripDotSlash(path) {
+  let out = path;
+  while (out.startsWith("./")) out = out.slice(2);
+  return out;
+}
+
+function globPatternMatches(pattern, target) {
+  return globPatternToRegExp(pattern).test(target);
+}
+
+function globPatternToRegExp(pattern) {
+  let source = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        source += ".*";
+        index += 1;
+      } else {
+        source += "[^/]*";
+      }
+      continue;
+    }
+    if (char === "?") {
+      source += "[^/]";
+      continue;
+    }
+    source += escapeRegExp(char);
+  }
+  return new RegExp(`${source}$`, "u");
+}
+
+function escapeRegExp(char) {
+  return /[\\^$.*+?()[\]{}|]/u.test(char) ? `\\${char}` : char;
+}

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

@@ -0,0 +1,130 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import {
+  DEFAULT_EXCLUDED_DIRS,
+  DEFAULT_EXCLUDED_FILES,
+  DEFAULT_MAX_SEARCH_CHARS,
+  DEFAULT_MAX_SEARCH_LINES,
+} from "./constants.js";
+import { boundedInt } from "./dedup.js";
+import { writeToolArtifact } from "./output-truncation.js";
+import { readRuntimeBrand, 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();
+  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.
+export const cachedRgPath = { value: undefined };
+
+function vendoredRgPath() {
+  try {
+    const sdkPkg = requireFromHere.resolve("@anthropic-ai/claude-agent-sdk/package.json");
+    const platform = process.platform === "win32" ? "win32" : process.platform;
+    const arch = process.arch === "x64" ? "x64" : process.arch === "arm64" ? "arm64" : null;
+    if (!arch) return null;
+    const binaryName = process.platform === "win32" ? "rg.exe" : "rg";
+    const candidate = join(dirname(sdkPkg), "vendor", "ripgrep", `${arch}-${platform}`, binaryName);
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function rgFromPath() {
+  const pathEnv = process.env.PATH || "";
+  if (!pathEnv) return null;
+  const exts = process.platform === "win32" ? (process.env.PATHEXT || ".EXE").split(";") : [""];
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = join(dir, `rg${ext.toLowerCase()}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function resolveRgPath({ refresh = false } = {}) {
+  if (!refresh && cachedRgPath.value !== undefined) return cachedRgPath.value;
+  const { ripgrepPath } = readToolRuntime();
+  if (ripgrepPath) {
+    cachedRgPath.value = existsSync(ripgrepPath) ? ripgrepPath : null;
+  } else {
+    cachedRgPath.value = vendoredRgPath() || rgFromPath() || null;
+  }
+  return cachedRgPath.value;
+}
+
+export function excludedGlobArgs() {
+  const args = [];
+  for (const dir of DEFAULT_EXCLUDED_DIRS) {
+    args.push("--glob", `!${dir}/**`, "--glob", `!**/${dir}/**`);
+  }
+  for (const filePattern of DEFAULT_EXCLUDED_FILES) args.push("--glob", `!${filePattern}`);
+  return args;
+}
+
+export function normalizeGlobPattern(pattern) {
+  const raw = String(pattern || "**/*").trim().replace(/^\.\//, "");
+  return raw || "**/*";
+}
+
+export function formatSearchLines(rawLines, {
+  label,
+  noMatches,
+  maxLines = DEFAULT_MAX_SEARCH_LINES,
+  maxChars = DEFAULT_MAX_SEARCH_CHARS,
+  offset = 0,
+} = {}) {
+  const lines = Array.isArray(rawLines) ? rawLines.filter(Boolean) : String(rawLines || "").trim().split("\n").filter(Boolean);
+  if (!lines.length) return noMatches;
+  const start = boundedInt(offset, 0, { min: 0 });
+  const total = lines.length;
+  const slice = lines.slice(start);
+  const kept = [];
+  let chars = 0;
+  const lineLimit = boundedInt(maxLines, DEFAULT_MAX_SEARCH_LINES, { min: 1 });
+  const charLimit = boundedInt(maxChars, DEFAULT_MAX_SEARCH_CHARS, { min: 200 });
+  for (const line of slice) {
+    if (kept.length >= lineLimit || chars + line.length + 1 > charLimit) break;
+    kept.push(line);
+    chars += line.length + 1;
+  }
+  if (kept.length === slice.length) return kept.join("\n");
+  const fullText = lines.join("\n");
+  const artifact = writeToolArtifact(label, fullText);
+  const suffix = [
+    `[truncated ${label || "search"} result: showing ${kept.length} of ${total} lines after excluding generated/vendor paths.`,
+    start ? `Offset ${start} was applied.` : null,
+    artifact ? `Full output saved to: ${artifact.path}` : null,
+    "Use a narrower path, glob, or pattern for the full result.]",
+  ].filter(Boolean).join(" ");
+  return `${kept.join("\n")}\n\n${suffix}`;
+}
+
+export function capLines(text, {
+  label,
+  noMatches,
+  maxLines = DEFAULT_MAX_SEARCH_LINES,
+  maxChars = DEFAULT_MAX_SEARCH_CHARS,
+  offset = 0,
+} = {}) {
+  return formatSearchLines(String(text || "").trim().split("\n").filter(Boolean), {
+    label,
+    noMatches,
+    maxLines,
+    maxChars,
+    offset,
+  });
+}
+
+export function excludedPathSummary() {
+  return `Excluded directories: ${DEFAULT_EXCLUDED_DIRS.join(", ")}; excluded files: ${DEFAULT_EXCLUDED_FILES.join(", ")}.`;
+}

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

@@ -0,0 +1,69 @@
+// 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.
+//
+// Single shared object is acceptable because the worker is one-task-per-process.
+//
+// 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).
+
+import { mergeSandboxPolicies } from "@mono-agent/sandbox";
+import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-brand.js";
+
+const context = {
+  workspace: undefined,
+  repoRoot: undefined,
+  runId: undefined,
+  toolArtifactDir: undefined,
+  ripgrepPath: undefined,
+  qaOutputDir: undefined,
+  sandboxPolicy: undefined,
+  runtimeBrand: { ...DEFAULT_RUNTIME_BRAND },
+};
+
+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);
+  }
+}
+
+export function readToolRuntime() {
+  return context;
+}
+
+// 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.
+export function resolveSandboxPolicy(requestPolicy = undefined) {
+  const merged = mergeSandboxPolicies(context.sandboxPolicy ?? undefined, requestPolicy ?? undefined);
+  return merged && merged.mode !== "off" ? merged : undefined;
+}
+
+export function readRuntimeBrand() {
+  return context.runtimeBrand || { ...DEFAULT_RUNTIME_BRAND };
+}
+
+export function resetToolRuntime() {
+  for (const key of Object.keys(context)) {
+    context[key] = key === "runtimeBrand" ? { ...DEFAULT_RUNTIME_BRAND } : undefined;
+  }
+}

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

@@ -0,0 +1,59 @@
+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";
+
+const FETCH_TIMEOUT_MS = 15000;
+const MAX_REDIRECTS = 5;
+
+export async function webFetchToolImpl({ url, headers = {}, max_output_chars }, { sandboxPolicy } = {}) {
+  const maxChars = Number(max_output_chars) || DEFAULT_MAX_TOOL_OUTPUT_CHARS;
+  let parsed;
+  try { parsed = new URL(url); } catch { return "Error: Invalid URL"; }
+  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 requestHeaders = { "User-Agent": "AgentRuntime/0.1", ...headers };
+  try {
+    const restricted = policy !== undefined && policy.network.mode !== "all";
+    const resp = restricted
+      ? await fetchCheckingRedirects(parsed, requestHeaders, policy)
+      : await fetch(url, { headers: requestHeaders, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (typeof resp === "string") return resp;
+    const text = await resp.text();
+    if (!resp.ok) return `HTTP ${resp.status}: ${text.slice(0, 500)}`;
+    return capChars(text, { label: "WebFetch", maxChars });
+  } catch (err) {
+    return `Error fetching URL: ${err.message}`;
+  }
+}
+
+// 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) {
+  let current = initialUrl;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const sameOrigin = current.origin === initialUrl.origin;
+    const resp = await fetch(current, {
+      headers: sameOrigin ? headers : { "User-Agent": headers["User-Agent"] },
+      redirect: "manual",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    const location = resp.headers.get("location");
+    if (resp.status < 300 || resp.status >= 400 || !location) return resp;
+    let next;
+    try { next = new URL(location, current); } catch { return "Error: Invalid redirect URL."; }
+    if (next.protocol !== "http:" && next.protocol !== "https:") {
+      return "Error: WebFetch only supports http(s) URLs.";
+    }
+    if (!networkPolicyAllowsUrl(policy, next.href)) {
+      return "Error: Network access denied by sandbox policy (redirect).";
+    }
+    try { await resp.body?.cancel(); } catch { /* best-effort */ }
+    current = next;
+  }
+  return "Error: Too many redirects.";
+}

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

@@ -0,0 +1,21 @@
+import { networkPolicyAllowsUrl } from "@mono-agent/sandbox";
+import { resolveSandboxPolicy } from "./shared/runtime-context.js";
+
+export async function webSearchToolImpl({ query, limit = 5 }, { sandboxPolicy } = {}) {
+  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 resp = await fetch(url, {
+    headers: { "User-Agent": "Mozilla/5.0 AgentRuntime/0.1" },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!resp.ok) return `Search failed: HTTP ${resp.status}`;
+  const html = await resp.text();
+  const results = [];
+  const re = /<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+  let m;
+  while ((m = re.exec(html)) && results.length < max) {
+    results.push(`${m[2].replace(/<[^>]+>/g, "").trim()}\n${m[1]}\n${m[3].replace(/<[^>]+>/g, "").trim()}`);
+  }
+  return results.length ? results.join("\n\n") : "No results.";
+}

package/src/agent/tools/write.js

@@ -0,0 +1,14 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+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}`;
+  const bytes = Buffer.byteLength(content || "", "utf8");
+  if (bytes > MAX_WRITE_BYTES) return `Error: Content too large (${bytes} bytes)`;
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content || "", "utf8");
+  return `Successfully wrote ${bytes} bytes to ${target}`;
+}