machine-bridge-mcp 0.16.1 → 0.17.0

package/src/local/managed-job-plan.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { lstatSync, realpathSync, statSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import { readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
 const RESOURCE_TOKEN = /\{\{resource:([a-z][a-z0-9._-]{0,63})\}\}/g;
@@ -112,7 +113,7 @@ function validateSteps(value, label, context, allowEmpty = false) {
       env_resources: envResources,
       stdin,
       stdin_resource: stdinResource,
-      timeout_seconds: clampInt(input.timeout_seconds, 600, 1, 3600),
+      timeout_seconds: clampInteger(input.timeout_seconds, 600, 1, 3600),
       allow_failure: input.allow_failure === true,
       capture_output: input.capture_output === "discard" ? "discard" : "redacted",
     };
@@ -227,9 +228,3 @@ function boundedString(value, maxBytes, label) {
   if (Buffer.byteLength(value) > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes`);
   return value;
 }
-
-function clampInt(value, fallback, min, max) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, min), max);
-}

package/src/local/managed-jobs.mjs

@@ -11,6 +11,7 @@ import { createToolAuthorizer } from "./policy.mjs";
 import { BridgeError } from "./errors.mjs";
 import { inspectResourceFile, normalizeResourceRegistry, publicResourceRegistry, validatePlan, validateResourceName } from "./managed-job-plan.mjs";
 export { inspectResourceFile, publicResourceRegistry, validateResourceName } from "./managed-job-plan.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 const JOB_ID = /^job_[A-Za-z0-9_-]{24,}$/;
 const MAX_JOBS = 50;
@@ -218,7 +219,7 @@ export class ManagedJobManager {
     this.authorizeTool("list_jobs");
     this.assertMaintenanceAvailable();
     this.prune();
-    const limit = clampInt(args.limit, 20, 1, MAX_JOBS);
+    const limit = clampInteger(args.limit, 20, 1, MAX_JOBS);
     const jobs = [];
     for (const entry of safeReadDir(this.jobRoot)) {
       if (!entry.isDirectory() || !JOB_ID.test(entry.name)) continue;
@@ -697,10 +698,17 @@ function runnerProcessIsCurrent(status, dir, { ownerOnly = false } = {}) {
 
 function scrubFinishedPlan(dir, status) {
   if (PLAN_RETAINING_STATES.has(status.status)) return;
-  rmSync(join(dir, "plan.json"), { force: true });
-  rmSync(join(dir, "runner.pid"), { force: true });
-  rmSync(join(dir, "recovery.lock"), { force: true });
-  rmSync(join(dir, "transition.lock"), { force: true });
+  const safeRm = (path) => {
+    try {
+      rmSync(path, { force: true });
+    } catch (error) {
+      if (!["ENOENT", "EPERM", "EACCES"].includes(error.code)) throw error;
+    }
+  };
+  safeRm(join(dir, "plan.json"));
+  safeRm(join(dir, "runner.pid"));
+  safeRm(join(dir, "recovery.lock"));
+  safeRm(join(dir, "transition.lock"));
 }
 
 function reviewablePlan(plan) {
@@ -843,9 +851,3 @@ function boundedString(value, maxBytes, label) {
   if (Buffer.byteLength(value) > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes`);
   return value;
 }
-
-function clampInt(value, fallback, min, max) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, min), max);
-}

package/src/local/numbers.mjs

@@ -0,0 +1,9 @@
+export function clampInteger(value, fallback, minimum, maximum) {
+  const parsed = typeof value === "number"
+    ? value
+    : typeof value === "string" && value.trim()
+      ? Number(value)
+      : Number.NaN;
+  const number = Number.isInteger(parsed) ? parsed : fallback;
+  return Math.min(Math.max(number, minimum), maximum);
+}

package/src/local/process-execution.mjs

@@ -3,6 +3,7 @@ import { stat } from "node:fs/promises";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
 import { MAX_COMMAND_BYTES, terminateProcessTreeWithEscalation, validateArgv } from "./process-sessions.mjs";
 import { BridgeError } from "./errors.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 const MAX_STDIN_BYTES = 1024 * 1024;
 const DEFAULT_OUTPUT_BYTES = 512 * 1024;
@@ -25,7 +26,7 @@ export class ProcessExecutionService {
     const argv = validateArgv(args.argv);
     const cwd = await this.resolveExistingPath(args.cwd || ".");
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "cwd is not a directory");
-    return this.run(argv[0], argv.slice(1), clampInt(args.timeout_seconds, 120, 1, 600) * 1000, false, DEFAULT_OUTPUT_BYTES, context, cwd);
+    return this.run(argv[0], argv.slice(1), clampInteger(args.timeout_seconds, 120, 1, 600) * 1000, false, DEFAULT_OUTPUT_BYTES, context, cwd);
   }
 
   async runRegistered(args, context = {}) {
@@ -36,7 +37,7 @@ export class ProcessExecutionService {
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "registered command cwd is not a directory");
     const requested = args.timeout_seconds === undefined
       ? command.timeoutSeconds
-      : clampInt(args.timeout_seconds, command.timeoutSeconds, 1, 600);
+      : clampInteger(args.timeout_seconds, command.timeoutSeconds, 1, 600);
     const timeoutSeconds = Math.min(requested, command.timeoutSeconds);
     const result = await this.run(argv[0], argv.slice(1), timeoutSeconds * 1000, false, DEFAULT_OUTPUT_BYTES, context, cwd);
     return { name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result };
@@ -53,7 +54,7 @@ export class ProcessExecutionService {
     if (command.includes("\0")) throw new BridgeError("invalid_request", "command contains a NUL byte");
     if (Buffer.byteLength(command) > MAX_COMMAND_BYTES) throw new BridgeError("limit_exceeded", `command exceeds maximum size (${MAX_COMMAND_BYTES} bytes)`);
     const shell = workspaceShellCommand(command);
-    return this.run(shell.cmd, shell.args, clampInt(timeoutSeconds, 120, 1, 600) * 1000, false, DEFAULT_OUTPUT_BYTES, context);
+    return this.run(shell.cmd, shell.args, clampInteger(timeoutSeconds, 120, 1, 600) * 1000, false, DEFAULT_OUTPUT_BYTES, context);
   }
 
   terminateAll(signal = "SIGTERM", escalate = false) {
@@ -145,9 +146,3 @@ function appendLimited(current, chunk, maximum) {
 function finalizeOutput(value, truncated) {
   return truncated > 0 ? `${value}\n\n[truncated ${truncated} bytes]` : value;
 }
-
-function clampInt(value, fallback, minimum, maximum) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, minimum), maximum);
-}

package/src/local/process-sessions.mjs

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import { basename } from "node:path";
 import { executionEnv } from "./shell.mjs";
 import { createToolAuthorizer } from "./policy.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 export const MAX_COMMAND_BYTES = 64 * 1024;
 const MAX_ARGV_ITEMS = 256;
@@ -112,10 +113,10 @@ export class ProcessSessionManager {
   async read(args, context = {}) {
     this.authorizeTool("read_process");
     const session = this.get(args.session_id);
-    const stdoutOffset = clampInt(args.stdout_offset, 0, 0, Number.MAX_SAFE_INTEGER);
-    const stderrOffset = clampInt(args.stderr_offset, 0, 0, Number.MAX_SAFE_INTEGER);
-    const maxBytes = clampInt(args.max_bytes, 64 * 1024, 1, 256 * 1024);
-    const waitMs = clampInt(args.wait_ms, 0, 0, 30_000);
+    const stdoutOffset = clampInteger(args.stdout_offset, 0, 0, Number.MAX_SAFE_INTEGER);
+    const stderrOffset = clampInteger(args.stderr_offset, 0, 0, Number.MAX_SAFE_INTEGER);
+    const maxBytes = clampInteger(args.max_bytes, 64 * 1024, 1, 256 * 1024);
+    const waitMs = clampInteger(args.wait_ms, 0, 0, 30_000);
     this.throwIfCancelled(context);
     const waitForExit = args.wait_for_exit === true;
     if (waitMs > 0 && session.closedAt === null) {
@@ -341,9 +342,3 @@ function boundedErrorMessage(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.replace(/[\r\n]+/g, " ").slice(0, 4096) || "process failed";
 }
-
-function clampInt(value, fallback, min, max) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, min), max);
-}

package/src/local/project-metadata.mjs

@@ -0,0 +1,50 @@
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+
+const SKIPPABLE_METADATA_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"]);
+
+export function safeSingleLine(value, maxLength) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maxLength);
+}
+
+export function skippableMetadataError(error) {
+  return SKIPPABLE_METADATA_CODES.has(error?.code);
+}
+
+export async function isRegularNonSymlink(filePath) {
+  const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
+  return Boolean(info && !info.isSymbolicLink() && info.isFile());
+}
+
+export async function readOptionalRegularUtf8(filePath, maxBytes) {
+  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0))
+    .catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
+  if (!handle) return null;
+  try {
+    let pathInfo;
+    let current;
+    try {
+      [pathInfo, current] = await Promise.all([lstat(filePath), handle.stat()]);
+    } catch (error) {
+      if (skippableMetadataError(error)) return null;
+      throw error;
+    }
+    if (pathInfo.isSymbolicLink() || !pathInfo.isFile() || !current.isFile()
+        || pathInfo.dev !== current.dev || pathInfo.ino !== current.ino || current.size > maxBytes) return null;
+    const buffer = Buffer.alloc(current.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
+    } catch {
+      return null;
+    }
+  } finally {
+    await handle.close();
+  }
+}

package/src/local/project-package.mjs

@@ -1,6 +1,6 @@
-import { constants as fsConstants } from "node:fs";
-import { lstat, open } from "node:fs/promises";
 import { join } from "node:path";
+import { isRegularNonSymlink, readOptionalRegularUtf8, safeSingleLine } from "./project-metadata.mjs";
+import { isPlainRecord } from "./records.mjs";
 
 const MAX_METADATA_FILE_BYTES = 1024 * 1024;
 const MAX_PACKAGE_COMMANDS = 64;
@@ -189,46 +189,3 @@ function safePackageManager(value) {
   const normalized = value.trim();
   return /^(?:npm|pnpm|yarn|bun)@[A-Za-z0-9][A-Za-z0-9.+_-]{0,90}$/.test(normalized) ? normalized : "";
 }
-
-async function isRegularNonSymlink(filePath) {
-  const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  return Boolean(info && !info.isSymbolicLink() && info.isFile());
-}
-
-async function readOptionalRegularUtf8(filePath, maxBytes) {
-  const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  if (!info || info.isSymbolicLink() || !info.isFile() || info.size > maxBytes) return null;
-  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0)).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  if (!handle) return null;
-  try {
-    const current = await handle.stat();
-    if (!current.isFile() || current.size > maxBytes) return null;
-    const buffer = Buffer.alloc(current.size);
-    let offset = 0;
-    while (offset < buffer.length) {
-      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
-      if (!bytesRead) break;
-      offset += bytesRead;
-    }
-    try {
-      return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
-    } catch {
-      return null;
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
-function skippableMetadataError(error) {
-  return ["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"].includes(error?.code);
-}
-
-function safeSingleLine(value, maxLength) {
-  if (typeof value !== "string") return "";
-  return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maxLength);
-}
-
-function isPlainRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/local/records.mjs

@@ -0,0 +1,5 @@
+export function isPlainRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/local/runtime.mjs

@@ -26,6 +26,8 @@ import { AppAutomationManager } from "./app-automation.mjs";
 import { BrowserBridgeManager } from "./browser-bridge.mjs";
 import { CapabilityObserver } from "./capability-observer.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { clampInteger } from "./numbers.mjs";
+import { isPlainRecord } from "./records.mjs";
 
 const MAX_WS_MESSAGE_BYTES = 8 * 1024 * 1024;
 const MAX_CONCURRENT_TOOL_CALLS = 16;
@@ -58,7 +60,7 @@ const RUNTIME_TOOL_HANDLERS = Object.freeze({
   browser_upload_files: (runtime, args, context) => runtime.browserBridgeManager.uploadFiles(args, context),
   list_roots: (runtime) => runtime.listRoots(),
   list_dir: (runtime, args, context) => runtime.listDir(args.path || ".", context),
-  list_files: (runtime, args, context) => runtime.listFiles(args.path || ".", clampInt(args.max_files, 1000, 1, 10000), context),
+  list_files: (runtime, args, context) => runtime.listFiles(args.path || ".", clampInteger(args.max_files, 1000, 1, 10000), context),
   read_file: (runtime, args, context) => runtime.readFile(args, context),
   view_image: (runtime, args, context) => runtime.viewImage(args, context),
   write_file: (runtime, args, context) => runtime.writeFile(args, context),
@@ -82,7 +84,7 @@ const RUNTIME_TOOL_HANDLERS = Object.freeze({
   read_process: (runtime, args, context) => runtime.processSessionManager.read(args, context),
   write_process: (runtime, args, context) => runtime.processSessionManager.write(args, context),
   kill_process: (runtime, args, context) => runtime.processSessionManager.kill(args, context),
-  exec_command: (runtime, args, context) => runtime.execCommand(args.command, clampInt(args.timeout_seconds, 120, 1, 600), context),
+  exec_command: (runtime, args, context) => runtime.execCommand(args.command, clampInteger(args.timeout_seconds, 120, 1, 600), context),
 });
 
 export function runtimeToolHandlerNames() {
@@ -809,13 +811,10 @@ function normalizeRelayToolCall(message) {
     id,
     tool,
     arguments: argumentsValue,
-    timeoutMs: clampInt(message.timeout_ms, 60_000, 1000, 610_000),
+    timeoutMs: clampInteger(message.timeout_ms, 60_000, 1000, 610_000),
   };
 }
 
-function isPlainRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 
 
 function collectToolPathCandidates(error, toolArgs, workspace) {
@@ -857,9 +856,3 @@ function replacePathPrefix(message, pathValue, replacement) {
 function shortCallId(value) {
   return String(value || "").slice(0, 20);
 }
-
-function clampInt(value, fallback, minimum, maximum) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, minimum), maximum);
-}

package/src/local/state-inventory.mjs

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { activeManagedJobs } from "./managed-jobs.mjs";
+import { inspectProcessInstance } from "./process-identity.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { expandHome, readDaemonLockOwner, resolveWorkspace } from "./state.mjs";
+
+const PROFILE_NAME = /^[a-f0-9]{24}$/;
+const WORKER_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const MAX_STATE_BYTES = 2 * 1024 * 1024;
+
+export function knownWorkerNames(stateRoot) {
+  const profiles = profilesDirectory(stateRoot);
+  if (!existsSync(profiles)) return [];
+  const names = new Set();
+  for (const entry of profileDirectories(profiles)) {
+    const profileDir = resolve(profiles, entry.name);
+    const stateFile = resolve(profileDir, "state.json");
+    if (!existsSync(stateFile)) {
+      const evidence = readdirSync(profileDir).some((name) => /^state\.json\.corrupt-/.test(name) || name === "daemon.lock");
+      if (evidence) throw unreadableWorkerState(entry.name);
+      continue;
+    }
+    let state;
+    try {
+      state = readStateJson(stateFile);
+    } catch {
+      throw unreadableWorkerState(entry.name);
+    }
+    if (!state || typeof state !== "object" || Array.isArray(state)) throw unreadableWorkerState(entry.name);
+    const name = String(state?.worker?.name || "");
+    if (name && !WORKER_NAME.test(name)) {
+      throw new Error(`profile ${entry.name} contains an invalid Worker name; local state was kept for inspection`);
+    }
+    if (name) names.add(name);
+  }
+  return [...names];
+}
+
+export function knownProfileStates(stateRoot) {
+  const canonicalStateRoot = canonicalRoot(stateRoot);
+  const profiles = resolve(canonicalStateRoot, "profiles");
+  if (!existsSync(profiles)) return [];
+  const states = [];
+  const seen = new Set();
+  for (const entry of profileDirectories(profiles)) {
+    const profileDir = resolve(profiles, entry.name);
+    const statePath = resolve(profileDir, "state.json");
+    const candidates = [];
+    if (existsSync(statePath)) {
+      try {
+        const value = readStateJson(statePath);
+        if (typeof value?.workspace?.path === "string") candidates.push(value.workspace.path);
+      } catch {
+        // A daemon lock may still provide a verified workspace for corrupt state.
+      }
+    }
+    const daemonLock = resolve(profileDir, "daemon.lock");
+    const daemonOwner = readDaemonLockOwner(daemonLock);
+    if (existsSync(daemonLock) && !daemonOwner) {
+      throw new Error(`cannot inspect daemon lock for profile ${entry.name}; service definitions and state were kept`);
+    }
+    if (typeof daemonOwner?.workspace === "string") candidates.push(daemonOwner.workspace);
+    for (const candidate of candidates) {
+      try {
+        const workspace = resolveWorkspace(candidate);
+        if (seen.has(workspace)) break;
+        states.push({
+          schemaVersion: 5,
+          workspace: { path: workspace, hash: entry.name },
+          paths: { stateRoot: canonicalStateRoot, profileDir, statePath },
+        });
+        seen.add(workspace);
+        break;
+      } catch {
+        // Ignore an invalid historical candidate and try the remaining evidence.
+      }
+    }
+  }
+  return states;
+}
+
+export function activeStateJobs(stateRoot) {
+  const profiles = profilesDirectory(stateRoot);
+  if (!existsSync(profiles)) return [];
+  const active = [];
+  for (const profile of profileDirectories(profiles)) {
+    for (const job of activeManagedJobs(resolve(profiles, profile.name, "jobs"))) {
+      active.push({ profile: profile.name, ...job });
+    }
+  }
+  return active;
+}
+
+export function activeStateLocks(stateRoot) {
+  const profiles = profilesDirectory(stateRoot);
+  if (!existsSync(profiles)) return [];
+  const active = [];
+  for (const profile of profileDirectories(profiles)) {
+    for (const [kind, name] of [["daemon", "daemon.lock"], ["startup", "startup.lock"]]) {
+      const lockPath = resolve(profiles, profile.name, name);
+      if (!existsSync(lockPath)) continue;
+      const owner = readDaemonLockOwner(lockPath);
+      if (!owner) {
+        active.push({ kind, pid: null, path: lockPath, reason: "invalid_or_unreadable_lock" });
+        continue;
+      }
+      const maxAgeMs = kind === "startup" ? 2 * 60 * 60 * 1000 : Number.POSITIVE_INFINITY;
+      const identity = inspectProcessInstance(owner, { maxAgeMs });
+      if (identity.current || (identity.alive && !identity.reclaimable)) {
+        active.push({ kind, pid: owner.pid, path: lockPath, reason: identity.reason });
+      }
+    }
+  }
+  return active;
+}
+
+function profilesDirectory(stateRoot) {
+  return resolve(canonicalRoot(stateRoot), "profiles");
+}
+
+function canonicalRoot(stateRoot) {
+  const expanded = resolve(expandHome(stateRoot));
+  if (!existsSync(expanded)) return expanded;
+  return realpathSync.native ? realpathSync.native(expanded) : realpathSync(expanded);
+}
+
+function profileDirectories(profiles) {
+  return readdirSync(profiles, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && PROFILE_NAME.test(entry.name));
+}
+
+function readStateJson(path) {
+  return JSON.parse(readBoundedRegularFileSync(path, MAX_STATE_BYTES).toString("utf8"));
+}
+
+function unreadableWorkerState(profile) {
+  return new Error(`cannot determine deployed Worker from profile ${profile}; local state was kept for inspection`);
+}

package/src/local/workspace-file-service.mjs

@@ -3,6 +3,7 @@ import { constants as fsConstants } from "node:fs";
 import { chmod, link, lstat, mkdir, open, opendir, rename, rm, stat, writeFile } from "node:fs/promises";
 import path, { basename, dirname, join, resolve } from "node:path";
 import { applyUpdateHunks, parsePatchEnvelope } from "./patch.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
 const MAX_DIRECTORY_ENTRIES = 10_000;
@@ -89,11 +90,11 @@ export class WorkspaceFileService {
     const { buffer, info } = await readBoundedFile(full, MAX_WRITE_BYTES, "readable text file");
     const content = decodeUtf8(buffer);
     this.throwIfCancelled(context);
-    const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, MAX_WRITE_BYTES);
-    const startLine = args.start_line === undefined ? 1 : clampInt(args.start_line, 1, 1, Number.MAX_SAFE_INTEGER);
+    const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, MAX_WRITE_BYTES);
+    const startLine = args.start_line === undefined ? 1 : clampInteger(args.start_line, 1, 1, Number.MAX_SAFE_INTEGER);
     const rawLines = content.split(/\r?\n/);
     const totalLines = content.endsWith("\n") ? Math.max(1, rawLines.length - 1) : rawLines.length;
-    const endLine = args.end_line === undefined ? totalLines : clampInt(args.end_line, totalLines, 1, Number.MAX_SAFE_INTEGER);
+    const endLine = args.end_line === undefined ? totalLines : clampInteger(args.end_line, totalLines, 1, Number.MAX_SAFE_INTEGER);
     if (endLine < startLine) throw new Error("end_line must be greater than or equal to start_line");
     if (startLine > totalLines) throw new Error(`start_line exceeds total lines (${startLine} > ${totalLines})`);
     const selectedEnd = Math.min(endLine, totalLines);
@@ -237,8 +238,8 @@ export class WorkspaceFileService {
     const query = String(args.query || "");
     if (!query) throw new Error("query is required");
     const root = await this.resolveExistingPath(args.path || ".");
-    const max = clampInt(args.max_matches, 100, 1, 1000);
-    const maxFiles = clampInt(args.max_files, 10000, 1, 100000);
+    const max = clampInteger(args.max_matches, 100, 1, 1000);
+    const maxFiles = clampInteger(args.max_files, 10000, 1, 100000);
     let visitedFiles = 0;
     const matches = [];
     const rootInfo = await stat(root);
@@ -435,13 +436,6 @@ export function sha256(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }
 
-function clampInt(value, fallback, min, max) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, min), max);
-}
-
-
 function detectImageMime(buffer) {
   if (buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
   if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return "image/jpeg";

package/src/worker/errors.ts

@@ -0,0 +1,41 @@
+const WORKER_ERROR_CODES = new Set([
+  "cancelled", "timeout", "authentication_failed", "authorization_denied", "policy_denied",
+  "invalid_request", "not_found", "conflict", "limit_exceeded", "permission_denied",
+  "path_boundary", "network_error", "protocol_error", "unavailable", "integrity_error",
+  "execution_failed", "internal_error",
+]);
+
+export class WorkerToolError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(code: string, message: string, retryable = false) {
+    super(message);
+    this.name = "WorkerToolError";
+    this.code = normalizeCode(code);
+    this.retryable = retryable;
+  }
+}
+
+export function daemonToolError(value: unknown): WorkerToolError {
+  const input = asObject(value);
+  const code = normalizeCode(input.code);
+  const message = typeof input.message === "string" && input.message
+    ? input.message.slice(0, 2000)
+    : "daemon tool failed";
+  return new WorkerToolError(code, message, input.retryable === true);
+}
+
+export function publicWorkerToolError(error: unknown): { code: string; message: string; retryable: boolean } {
+  if (error instanceof WorkerToolError) return { code: error.code, message: error.message, retryable: error.retryable };
+  return { code: "execution_failed", message: "tool execution failed", retryable: false };
+}
+
+function normalizeCode(value: unknown): string {
+  const code = String(value || "execution_failed").toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 64);
+  return WORKER_ERROR_CODES.has(code) ? code : "execution_failed";
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}