nolo-cli 0.1.19 → 0.1.21

package/agent-runtime/localWorkspaceTools.ts

@@ -0,0 +1,1532 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+
+import type {
+  AgentRuntimeToolCallInput,
+  AgentRuntimeToolResult,
+} from "./types";
+
+type LocalWorkspaceToolArgs = {
+  workspaceRoot: string;
+  commandTimeoutMs?: number;
+};
+
+type WorkspaceFileArgs = {
+  path?: unknown;
+  content?: unknown;
+  oldText?: unknown;
+  newText?: unknown;
+  expectedReplacements?: unknown;
+  query?: unknown;
+  command?: unknown;
+  cmd?: unknown;
+  patch?: unknown;
+  script?: unknown;
+  args?: unknown;
+  branch?: unknown;
+  paths?: unknown;
+  message?: unknown;
+  staged?: unknown;
+  baseUrl?: unknown;
+  base?: unknown;
+  waitSelector?: unknown;
+  scrollSelector?: unknown;
+  focusSelector?: unknown;
+  expectText?: unknown;
+  screenshotPath?: unknown;
+  metricsPath?: unknown;
+};
+
+type OpenAiCompatibleTool = Record<string, unknown> & {
+  function?: Record<string, unknown> & { name?: string };
+};
+
+const WORKSPACE_TOOL_NAMES = [
+  "listWorkspaceFiles",
+  "readWorkspaceFile",
+  "writeWorkspaceFile",
+  "replaceWorkspaceText",
+  "listFiles",
+  "readFile",
+  "writeFile",
+  "searchWorkspace",
+  "applyEdit",
+  "applyLineEdits",
+  "applyPatch",
+  "gitStatus",
+  "gitDiff",
+  "gitCreateBranch",
+  "gitAdd",
+  "gitCommit",
+  "commitWorkspace",
+  "runPackageScript",
+  "startPreview",
+  "getPreviewStatus",
+  "stopPreview",
+  "releasePreview",
+  "captureVisualState",
+  "execShell",
+  "execBash",
+] as const;
+
+const DEFAULT_LOCAL_CODING_TOOL_NAMES = [
+  "readWorkspaceFile",
+  "writeWorkspaceFile",
+  "replaceWorkspaceText",
+  "searchWorkspace",
+  "applyPatch",
+  "gitStatus",
+  "gitDiff",
+  "gitCreateBranch",
+  "commitWorkspace",
+  "runPackageScript",
+  "startPreview",
+  "getPreviewStatus",
+  "stopPreview",
+  "releasePreview",
+  "captureVisualState",
+] as const;
+
+const SHELL_TOOL_NAMES = ["execShell", "execBash"] as const;
+const DEFAULT_WORKSPACE_COMMAND_TIMEOUT_MS = 120_000;
+
+function buildWorkspacePathProperty() {
+  return {
+    type: "string",
+    description: "Path relative to the workspace root.",
+  };
+}
+
+function buildListWorkspaceFilesTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "listWorkspaceFiles",
+      description: "List files and directories inside a workspace directory.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: buildWorkspacePathProperty(),
+        },
+      },
+    },
+  };
+}
+
+function buildReadWorkspaceFileTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "readWorkspaceFile",
+      description: "Read a UTF-8 text file inside the workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: buildWorkspacePathProperty(),
+        },
+        required: ["path"],
+      },
+    },
+  };
+}
+
+function buildWriteWorkspaceFileTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "writeWorkspaceFile",
+      description: "Write UTF-8 text content to a file inside the workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: buildWorkspacePathProperty(),
+          content: {
+            type: "string",
+            description: "Full UTF-8 file content to write.",
+          },
+        },
+        required: ["path", "content"],
+      },
+    },
+  };
+}
+
+function buildReplaceWorkspaceTextTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "replaceWorkspaceText",
+      description: "Replace exact UTF-8 text in one workspace file without constructing a patch.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: buildWorkspacePathProperty(),
+          oldText: {
+            type: "string",
+            description: "Exact text currently present in the file.",
+          },
+          newText: {
+            type: "string",
+            description: "Replacement text to write in place of oldText.",
+          },
+          expectedReplacements: {
+            type: "integer",
+            description: "Expected replacement count. Defaults to 1.",
+          },
+        },
+        required: ["path", "oldText", "newText"],
+      },
+    },
+  };
+}
+
+function buildSearchWorkspaceTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "searchWorkspace",
+      description: "Search text in the current workspace using ripgrep when available.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query or regular expression.",
+          },
+          path: buildWorkspacePathProperty(),
+        },
+        required: ["query"],
+      },
+    },
+  };
+}
+
+function buildApplyPatchTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "applyPatch",
+      description: "Apply a unified diff patch to files inside the workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          patch: {
+            type: "string",
+            description: "Unified diff text accepted by git apply.",
+          },
+        },
+        required: ["patch"],
+      },
+    },
+  };
+}
+
+function buildGitStatusTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "gitStatus",
+      description: "Show concise git status for the workspace.",
+      parameters: { type: "object", properties: {} },
+    },
+  };
+}
+
+function buildGitDiffTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "gitDiff",
+      description: "Show git diff for the workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: buildWorkspacePathProperty(),
+          staged: {
+            type: "boolean",
+            description: "When true, show staged changes.",
+          },
+        },
+      },
+    },
+  };
+}
+
+function buildGitCreateBranchTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "gitCreateBranch",
+      description: "Create and switch to a local git branch in the workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          branch: {
+            type: "string",
+            description: "Branch name to create and check out.",
+          },
+        },
+        required: ["branch"],
+      },
+    },
+  };
+}
+
+function buildGitAddTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "gitAdd",
+      description: "Stage workspace files for commit.",
+      parameters: {
+        type: "object",
+        properties: {
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Workspace-relative paths to stage.",
+          },
+        },
+        required: ["paths"],
+      },
+    },
+  };
+}
+
+function buildGitCommitTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "gitCommit",
+      description: "Commit staged workspace changes.",
+      parameters: {
+        type: "object",
+        properties: {
+          message: {
+            type: "string",
+            description: "Commit subject.",
+          },
+        },
+        required: ["message"],
+      },
+    },
+  };
+}
+
+function buildCommitWorkspaceTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "commitWorkspace",
+      description: "Stage selected workspace paths, commit them, and return branch, commit hash, and clean status.",
+      parameters: {
+        type: "object",
+        properties: {
+          paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Workspace-relative paths to stage before committing.",
+          },
+          message: {
+            type: "string",
+            description: "Commit subject.",
+          },
+        },
+        required: ["paths", "message"],
+      },
+    },
+  };
+}
+
+function buildRunPackageScriptTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "runPackageScript",
+      description: "Run a package script in the workspace, for example a test or lint script.",
+      parameters: {
+        type: "object",
+        properties: {
+          script: {
+            type: "string",
+            description: "Package script name to run.",
+          },
+          args: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional extra arguments passed after --.",
+          },
+        },
+        required: ["script"],
+      },
+    },
+  };
+}
+
+function buildPreviewLifecycleTool(toolName: string): OpenAiCompatibleTool {
+  const descriptions: Record<string, string> = {
+    startPreview: "Start the local preview stack for the current workspace.",
+    getPreviewStatus: "Read local preview status, including localApiOrigin and process state.",
+    stopPreview: "Stop the local preview stack for the current workspace.",
+    releasePreview: "Release the local preview slot for the current workspace after stopping preview.",
+  };
+  return {
+    type: "function",
+    function: {
+      name: toolName,
+      description: descriptions[toolName] ?? "Run a local preview lifecycle action.",
+      parameters: { type: "object", properties: {} },
+    },
+  };
+}
+
+function buildCaptureVisualStateTool(): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: "captureVisualState",
+      description: "Capture a real local app screenshot and DOM/computed-style metrics for a selected UI state.",
+      parameters: {
+        type: "object",
+        properties: {
+          baseUrl: {
+            type: "string",
+            description: "Optional local preview base URL. When omitted, the tool reads preview:status.",
+          },
+          path: {
+            type: "string",
+            description: "App route to open, for example / or /dialog-123. Defaults to /.",
+          },
+          waitSelector: {
+            type: "string",
+            description: "CSS selector that must become visible before capture.",
+          },
+          scrollSelector: {
+            type: "string",
+            description: "Optional CSS selector to scroll into view before capture.",
+          },
+          focusSelector: {
+            type: "string",
+            description: "Optional CSS selector for the target element whose rect/style should be reported.",
+          },
+          expectText: {
+            type: "string",
+            description: "Optional visible text expected on the page before capture.",
+          },
+          screenshotPath: {
+            type: "string",
+            description: "Workspace-relative screenshot path. Defaults under test-results/frontend-agent/.",
+          },
+          metricsPath: {
+            type: "string",
+            description: "Workspace-relative metrics JSON path. Defaults under test-results/frontend-agent/.",
+          },
+        },
+        required: ["waitSelector"],
+      },
+    },
+  };
+}
+
+function buildExecShellTool(toolName: string): OpenAiCompatibleTool {
+  return {
+    type: "function",
+    function: {
+      name: toolName,
+      description: "Run a shell command in the local workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          cmd: {
+            type: "string",
+            description: "Shell command to run.",
+          },
+          command: {
+            type: "string",
+            description: "Shell command to run.",
+          },
+        },
+      },
+    },
+  };
+}
+
+function renameWorkspaceToolDefinition(
+  tool: OpenAiCompatibleTool,
+  name: string
+): OpenAiCompatibleTool {
+  return {
+    ...tool,
+    function: {
+      ...(tool.function ?? {}),
+      name,
+    },
+  };
+}
+
+function buildWorkspaceToolDefinition(toolName: string) {
+  if (toolName === "listWorkspaceFiles" || toolName === "listFiles") {
+    return renameWorkspaceToolDefinition(buildListWorkspaceFilesTool(), toolName);
+  }
+  if (toolName === "readWorkspaceFile" || toolName === "readFile") {
+    return renameWorkspaceToolDefinition(buildReadWorkspaceFileTool(), toolName);
+  }
+  if (toolName === "writeWorkspaceFile" || toolName === "writeFile") {
+    return renameWorkspaceToolDefinition(buildWriteWorkspaceFileTool(), toolName);
+  }
+  if (toolName === "replaceWorkspaceText" || toolName === "applyEdit" || toolName === "applyLineEdits") {
+    return renameWorkspaceToolDefinition(buildReplaceWorkspaceTextTool(), toolName);
+  }
+  if (toolName === "searchWorkspace") return buildSearchWorkspaceTool();
+  if (toolName === "applyPatch") return buildApplyPatchTool();
+  if (toolName === "gitStatus") return buildGitStatusTool();
+  if (toolName === "gitDiff") return buildGitDiffTool();
+  if (toolName === "gitCreateBranch") return buildGitCreateBranchTool();
+  if (toolName === "gitAdd") return buildGitAddTool();
+  if (toolName === "gitCommit") return buildGitCommitTool();
+  if (toolName === "commitWorkspace") return buildCommitWorkspaceTool();
+  if (toolName === "runPackageScript") return buildRunPackageScriptTool();
+  if (toolName === "startPreview" || toolName === "getPreviewStatus" || toolName === "stopPreview" || toolName === "releasePreview") {
+    return buildPreviewLifecycleTool(toolName);
+  }
+  if (toolName === "captureVisualState") return buildCaptureVisualStateTool();
+  if (toolName === "execShell" || toolName === "execBash") return buildExecShellTool(toolName);
+  return null;
+}
+
+function removeRedundantWorkspaceToolAliases(toolNames: Set<string>) {
+  const next = new Set(toolNames);
+  if (next.has("listWorkspaceFiles")) next.delete("listFiles");
+  if (next.has("readWorkspaceFile")) next.delete("readFile");
+  if (next.has("writeWorkspaceFile")) next.delete("writeFile");
+  if (next.has("replaceWorkspaceText")) {
+    next.delete("applyEdit");
+    next.delete("applyLineEdits");
+  }
+  return next;
+}
+
+export function buildLocalWorkspaceToolset(args: {
+  declaredToolNames?: string[];
+  exposeShellTools?: boolean;
+}) {
+  const exposeShellTools = args.exposeShellTools === true;
+  return {
+    toolNames: [
+      ...DEFAULT_LOCAL_CODING_TOOL_NAMES,
+      ...(exposeShellTools ? SHELL_TOOL_NAMES : []),
+    ],
+    exposeShellTools,
+  };
+}
+
+export function buildLocalWorkspacePolicyToolNames(args: {
+  declaredToolNames?: string[];
+  exposeShellTools?: boolean;
+}) {
+  return [...new Set([
+    ...buildLocalWorkspaceToolset(args).toolNames,
+    ...(args.declaredToolNames ?? []),
+  ])];
+}
+
+export function buildLocalWorkspaceOpenAiTools(args: {
+  toolNames?: string[];
+  exposeShellTools?: boolean;
+}) {
+  const declaredTools = removeRedundantWorkspaceToolAliases(new Set(args.toolNames ?? []));
+  return WORKSPACE_TOOL_NAMES
+    .filter((toolName) => {
+      if (!declaredTools.has(toolName)) return false;
+      if (!args.exposeShellTools && (toolName === "execShell" || toolName === "execBash")) {
+        return false;
+      }
+      return true;
+    })
+    .map((toolName) => buildWorkspaceToolDefinition(toolName))
+    .filter((tool): tool is OpenAiCompatibleTool => Boolean(tool));
+}
+
+function parseWorkspaceToolArguments(raw: string): WorkspaceFileArgs {
+  try {
+    const parsed = JSON.parse(raw || "{}");
+    return parsed && typeof parsed === "object" ? parsed as WorkspaceFileArgs : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeWorkspaceRelativePath(args: {
+  workspaceRoot: string;
+  targetPath: string;
+}) {
+  const relativePath = relative(args.workspaceRoot, args.targetPath);
+  return relativePath || ".";
+}
+
+function isPathInsideWorkspace(args: {
+  workspaceRoot: string;
+  targetPath: string;
+}) {
+  const relativePath = relative(args.workspaceRoot, args.targetPath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !relativePath.includes(`..${sep}`));
+}
+
+function requireWorkspaceToolPath(args: WorkspaceFileArgs) {
+  const requestedPath = typeof args.path === "string" ? args.path.trim() : "";
+  if (!requestedPath) throw new Error("Workspace tool requires a non-empty path.");
+  return requestedPath;
+}
+
+function requireWorkspaceFileContent(args: WorkspaceFileArgs) {
+  if (typeof args.content !== "string") {
+    throw new Error("writeWorkspaceFile requires string content.");
+  }
+  return args.content;
+}
+
+function requireWorkspaceOldText(args: WorkspaceFileArgs) {
+  if (typeof args.oldText !== "string" || !args.oldText) {
+    throw new Error("replaceWorkspaceText requires non-empty oldText.");
+  }
+  return args.oldText;
+}
+
+function requireWorkspaceNewText(args: WorkspaceFileArgs) {
+  if (typeof args.newText !== "string") {
+    throw new Error("replaceWorkspaceText requires string newText.");
+  }
+  return args.newText;
+}
+
+function readExpectedReplacementCount(args: WorkspaceFileArgs) {
+  if (args.expectedReplacements === undefined) return 1;
+  const value = Number(args.expectedReplacements);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("replaceWorkspaceText expectedReplacements must be a positive integer.");
+  }
+  return value;
+}
+
+function countExactTextOccurrences(args: {
+  content: string;
+  oldText: string;
+}) {
+  return args.content.split(args.oldText).length - 1;
+}
+
+function pluralizeReplacement(count: number) {
+  return count === 1 ? "replacement" : "replacements";
+}
+
+function requireWorkspaceSearchQuery(args: WorkspaceFileArgs) {
+  const query = typeof args.query === "string" ? args.query.trim() : "";
+  if (!query) throw new Error("searchWorkspace requires a non-empty query.");
+  return query;
+}
+
+function requireWorkspacePatch(args: WorkspaceFileArgs) {
+  const patch = typeof args.patch === "string" ? args.patch : "";
+  if (!patch.trim()) throw new Error("applyPatch requires a non-empty patch.");
+  return patch;
+}
+
+function requireShellCommand(args: WorkspaceFileArgs, toolName: string) {
+  const command = typeof args.cmd === "string"
+    ? args.cmd.trim()
+    : typeof args.command === "string"
+      ? args.command.trim()
+      : "";
+  if (!command) throw new Error(`${toolName} requires a non-empty command.`);
+  return command;
+}
+
+function requirePackageScript(args: WorkspaceFileArgs) {
+  const script = typeof args.script === "string" ? args.script.trim() : "";
+  if (!script) throw new Error("runPackageScript requires a non-empty script.");
+  return script;
+}
+
+function requireVisualWaitSelector(args: WorkspaceFileArgs) {
+  const selector = typeof args.waitSelector === "string" ? args.waitSelector.trim() : "";
+  if (!selector) throw new Error("captureVisualState requires a non-empty waitSelector.");
+  return selector;
+}
+
+function requireGitBranchName(args: WorkspaceFileArgs) {
+  const branch = typeof args.branch === "string" ? args.branch.trim() : "";
+  if (!branch) throw new Error("gitCreateBranch requires a non-empty branch.");
+  return branch;
+}
+
+function requireGitCommitMessage(args: WorkspaceFileArgs) {
+  const message = typeof args.message === "string" ? args.message.trim() : "";
+  if (!message) throw new Error("gitCommit requires a non-empty message.");
+  return message;
+}
+
+function readGitAddPaths(args: WorkspaceFileArgs) {
+  const paths = Array.isArray(args.paths)
+    ? args.paths.map((value) => String(value).trim()).filter(Boolean)
+    : [];
+  if (paths.length === 0) throw new Error("gitAdd requires at least one path.");
+  return paths;
+}
+
+function readPackageScriptArgs(args: WorkspaceFileArgs) {
+  return Array.isArray(args.args)
+    ? args.args.map((value) => String(value)).filter(Boolean)
+    : [];
+}
+
+function readOptionalStringArg(value: unknown) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readVisualStateCaptureArgs(args: WorkspaceFileArgs) {
+  const baseUrl = readOptionalStringArg(args.baseUrl) ?? readOptionalStringArg(args.base);
+  const path = readOptionalStringArg(args.path) ?? "/";
+  const waitSelector = requireVisualWaitSelector(args);
+  const scrollSelector = readOptionalStringArg(args.scrollSelector);
+  const focusSelector = readOptionalStringArg(args.focusSelector);
+  const expectText = readOptionalStringArg(args.expectText);
+  const screenshotPath =
+    readOptionalStringArg(args.screenshotPath) ?? "test-results/frontend-agent/visual-state.png";
+  const metricsPath =
+    readOptionalStringArg(args.metricsPath) ?? "test-results/frontend-agent/visual-state-metrics.json";
+  return {
+    baseUrl,
+    path,
+    waitSelector,
+    scrollSelector,
+    focusSelector,
+    expectText,
+    screenshotPath,
+    metricsPath,
+  };
+}
+
+async function readWorkspacePackageScripts(workspaceRoot: string) {
+  try {
+    const raw = await readFile(resolve(workspaceRoot, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const scripts = parsed && typeof parsed === "object" && parsed.scripts && typeof parsed.scripts === "object"
+      ? Object.keys(parsed.scripts).sort()
+      : [];
+    return { scripts };
+  } catch (error) {
+    return {
+      scripts: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function formatAvailableScripts(scripts: string[]) {
+  return scripts.length ? scripts.join(", ") : "(none)";
+}
+
+function truncateToolOutput(value: string, limit = 20_000) {
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit)}\n\n[truncated ${value.length - limit} chars]`;
+}
+
+function parseLastJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  for (let index = trimmed.lastIndexOf("{"); index >= 0; index = trimmed.lastIndexOf("{", index - 1)) {
+    try {
+      const parsed = JSON.parse(trimmed.slice(index));
+      return parsed && typeof parsed === "object" ? parsed as Record<string, unknown> : null;
+    } catch {
+      // Try the previous opening brace.
+    }
+  }
+  return null;
+}
+
+async function writeProcessInput(proc: any, input: string) {
+  const stdin = proc.stdin;
+  if (!stdin) return;
+  const encoded = new TextEncoder().encode(input);
+  if (typeof stdin.getWriter === "function") {
+    const writer = stdin.getWriter();
+    try {
+      await writer.write(encoded);
+      await writer.close();
+    } finally {
+      writer.releaseLock();
+    }
+    return;
+  }
+  if (typeof stdin.write === "function") {
+    await stdin.write(encoded);
+    await stdin.end?.();
+  }
+}
+
+async function runWorkspaceCommand(args: {
+  workspaceRoot: string;
+  command: string[];
+  stdin?: string;
+  timeoutMs?: number;
+}) {
+  const timeoutMs = args.timeoutMs ?? DEFAULT_WORKSPACE_COMMAND_TIMEOUT_MS;
+  const detached = process.platform !== "win32";
+  const proc = Bun.spawn(args.command, {
+    cwd: resolve(args.workspaceRoot),
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: args.stdin === undefined ? "ignore" : "pipe",
+    detached,
+  });
+  if (args.stdin !== undefined) await writeProcessInput(proc, args.stdin);
+  const stdoutPromise = new Response(proc.stdout).text();
+  const stderrPromise = new Response(proc.stderr).text();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutResult = Symbol("timeout");
+  const exitOrTimeout = await Promise.race([
+    proc.exited,
+    new Promise<typeof timeoutResult>((resolveTimeout) => {
+      timeout = setTimeout(() => resolveTimeout(timeoutResult), timeoutMs);
+    }),
+  ]);
+  if (timeout) clearTimeout(timeout);
+  const timedOut = exitOrTimeout === timeoutResult;
+  if (timedOut) {
+    const kill = (signal: NodeJS.Signals) => {
+      if (detached && typeof proc.pid === "number") {
+        try {
+          process.kill(-proc.pid, signal);
+          return;
+        } catch {
+          // Fall through to killing the immediate child.
+        }
+      }
+      try {
+        proc.kill(signal);
+      } catch {
+        // The command may have exited after the timeout won the race.
+      }
+    };
+    kill("SIGTERM");
+    await Promise.race([
+      proc.exited.catch(() => 124),
+      new Promise((resolveKill) => setTimeout(resolveKill, 500)),
+    ]);
+    kill("SIGKILL");
+  }
+  const [stdout, rawStderr] = await Promise.all([
+    stdoutPromise,
+    stderrPromise,
+  ]);
+  const exitCode = timedOut ? 124 : Number(exitOrTimeout);
+  const stderr = timedOut
+    ? `${rawStderr.trim() ? `${rawStderr.trim()}\n` : ""}command timed out after ${timeoutMs}ms\n`
+    : rawStderr;
+  return {
+    stdout,
+    stderr,
+    exitCode,
+    timedOut,
+    content: truncateToolOutput([
+      stdout.trim() ? `stdout:\n${stdout.trim()}` : "",
+      stderr.trim() ? `stderr:\n${stderr.trim()}` : "",
+      `exitCode: ${exitCode}`,
+    ].filter(Boolean).join("\n\n")),
+  };
+}
+
+export function resolveLocalWorkspaceToolPath(args: {
+  workspaceRoot: string;
+  requestedPath: string;
+}) {
+  const workspaceRoot = resolve(args.workspaceRoot);
+  const targetPath = resolve(workspaceRoot, args.requestedPath);
+  if (!isPathInsideWorkspace({ workspaceRoot, targetPath })) {
+    throw new Error(`Workspace tool path escapes workspace root: ${args.requestedPath}`);
+  }
+  return targetPath;
+}
+
+async function readWorkspaceFileTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const requestedPath = requireWorkspaceToolPath(parsed);
+  const absolutePath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  const content = await readFile(absolutePath, "utf8");
+  return {
+    content,
+    metadata: {
+      path: normalizeWorkspaceRelativePath({
+        workspaceRoot: resolve(args.workspaceRoot),
+        targetPath: absolutePath,
+      }),
+      bytes: Buffer.byteLength(content),
+    },
+  };
+}
+
+async function writeWorkspaceFileTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const requestedPath = requireWorkspaceToolPath(parsed);
+  const content = requireWorkspaceFileContent(parsed);
+  const absolutePath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, "utf8");
+  const relativePath = normalizeWorkspaceRelativePath({
+    workspaceRoot: resolve(args.workspaceRoot),
+    targetPath: absolutePath,
+  });
+  return {
+    content: `wrote ${relativePath}`,
+    metadata: {
+      path: relativePath,
+      bytes: Buffer.byteLength(content),
+    },
+  };
+}
+
+async function replaceWorkspaceTextTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const requestedPath = requireWorkspaceToolPath(parsed);
+  const oldText = requireWorkspaceOldText(parsed);
+  const newText = requireWorkspaceNewText(parsed);
+  const expectedReplacements = readExpectedReplacementCount(parsed);
+  const absolutePath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  const content = await readFile(absolutePath, "utf8");
+  const replacementCount = countExactTextOccurrences({ content, oldText });
+  if (replacementCount !== expectedReplacements) {
+    throw new Error(
+      `replaceWorkspaceText expected ${expectedReplacements} ${pluralizeReplacement(expectedReplacements)} ` +
+        `but found ${replacementCount} in ${requestedPath}.`
+    );
+  }
+  const nextContent = content.split(oldText).join(newText);
+  await writeFile(absolutePath, nextContent, "utf8");
+  const relativePath = normalizeWorkspaceRelativePath({
+    workspaceRoot: resolve(args.workspaceRoot),
+    targetPath: absolutePath,
+  });
+  return {
+    content: `replaced ${replacementCount} occurrence${replacementCount === 1 ? "" : "s"} in ${relativePath}`,
+    metadata: {
+      path: relativePath,
+      replacements: replacementCount,
+      bytes: Buffer.byteLength(nextContent),
+    },
+  };
+}
+
+async function formatWorkspaceDirEntry(args: {
+  workspaceRoot: string;
+  dirPath: string;
+  name: string;
+}) {
+  const absolutePath = resolve(args.dirPath, args.name);
+  const info = await stat(absolutePath);
+  const relativePath = normalizeWorkspaceRelativePath({
+    workspaceRoot: resolve(args.workspaceRoot),
+    targetPath: absolutePath,
+  });
+  return info.isDirectory() ? `${relativePath}/` : relativePath;
+}
+
+async function listWorkspaceFilesTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const requestedPath = typeof parsed.path === "string" && parsed.path.trim()
+    ? parsed.path.trim()
+    : ".";
+  const dirPath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  const names = (await readdir(dirPath)).sort((left, right) => left.localeCompare(right));
+  const entries = await Promise.all(names.map((name) => formatWorkspaceDirEntry({
+    workspaceRoot: args.workspaceRoot,
+    dirPath,
+    name,
+  })));
+  return {
+    content: entries.join("\n"),
+    metadata: {
+      path: requestedPath,
+      count: entries.length,
+    },
+  };
+}
+
+async function searchWorkspaceTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const query = requireWorkspaceSearchQuery(parsed);
+  const requestedPath = typeof parsed.path === "string" && parsed.path.trim()
+    ? parsed.path.trim()
+    : ".";
+  const searchPath = resolveLocalWorkspaceToolPath({
+    workspaceRoot: args.workspaceRoot,
+    requestedPath,
+  });
+  const relativeSearchPath = normalizeWorkspaceRelativePath({
+    workspaceRoot: resolve(args.workspaceRoot),
+    targetPath: searchPath,
+  });
+  const result = await (async () => {
+    try {
+      return await runWorkspaceCommand({
+        workspaceRoot: args.workspaceRoot,
+        command: [
+          "rg",
+          "--line-number",
+          "--no-heading",
+          "--hidden",
+          "--glob",
+          "!node_modules",
+          "--glob",
+          "!.git",
+          query,
+          relativeSearchPath,
+        ],
+      });
+    } catch {
+      return await runWorkspaceCommand({
+        workspaceRoot: args.workspaceRoot,
+        command: [
+          "grep",
+          "-R",
+          "-n",
+          "-I",
+          "--exclude-dir=node_modules",
+          "--exclude-dir=.git",
+          query,
+          relativeSearchPath,
+        ],
+      });
+    }
+  })();
+  return {
+    content: result.content,
+    metadata: {
+      query,
+      path: requestedPath,
+      exitCode: result.exitCode,
+    },
+  };
+}
+
+async function applyPatchTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const patch = requireWorkspacePatch(parsed);
+  const checkResult = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "apply", "--check", "--whitespace=nowarn", "-"],
+    stdin: patch,
+  });
+  if (checkResult.exitCode !== 0) {
+    throw new Error(
+      [
+        "applyPatch failed during git apply --check.",
+        "Use replaceWorkspaceText/applyEdit for exact single-file edits when possible.",
+        checkResult.content,
+      ].join("\n\n")
+    );
+  }
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "apply", "--whitespace=nowarn", "-"],
+    stdin: patch,
+  });
+  if (result.exitCode !== 0) throw new Error(result.content);
+  return {
+    content: "patch applied",
+    metadata: { bytes: Buffer.byteLength(patch) },
+  };
+}
+
+async function gitStatusTool(args: {
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "status", "--short"],
+  });
+  return {
+    content: result.content,
+    metadata: { exitCode: result.exitCode },
+  };
+}
+
+async function gitDiffTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const command = ["git", "diff"];
+  const staged = parsed.staged === true;
+  if (staged) command.push("--staged");
+  if (typeof parsed.path === "string" && parsed.path.trim()) {
+    const absolutePath = resolveLocalWorkspaceToolPath({
+      workspaceRoot: args.workspaceRoot,
+      requestedPath: parsed.path.trim(),
+    });
+    command.push("--", normalizeWorkspaceRelativePath({
+      workspaceRoot: resolve(args.workspaceRoot),
+      targetPath: absolutePath,
+    }));
+  }
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command,
+  });
+  return {
+    content: result.content,
+    metadata: { staged, exitCode: result.exitCode },
+  };
+}
+
+async function gitCreateBranchTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const branch = requireGitBranchName(parsed);
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "switch", "-c", branch],
+  });
+  if (result.exitCode !== 0) throw new Error(result.content);
+  return {
+    content: result.content,
+    metadata: { branch, exitCode: result.exitCode },
+  };
+}
+
+async function gitAddTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const paths = readGitAddPaths(parsed).map((requestedPath) => {
+    const absolutePath = resolveLocalWorkspaceToolPath({
+      workspaceRoot: args.workspaceRoot,
+      requestedPath,
+    });
+    return normalizeWorkspaceRelativePath({
+      workspaceRoot: resolve(args.workspaceRoot),
+      targetPath: absolutePath,
+    });
+  });
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "add", "--", ...paths],
+  });
+  if (result.exitCode !== 0) throw new Error(result.content);
+  return {
+    content: result.content,
+    metadata: { paths, exitCode: result.exitCode },
+  };
+}
+
+async function gitCommitTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const message = requireGitCommitMessage(parsed);
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "commit", "-m", message],
+  });
+  if (result.exitCode !== 0) throw new Error(result.content);
+  return {
+    content: result.content,
+    metadata: { exitCode: result.exitCode },
+  };
+}
+
+async function commitWorkspaceTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const paths = readGitAddPaths(parsed).map((requestedPath) => {
+    const absolutePath = resolveLocalWorkspaceToolPath({
+      workspaceRoot: args.workspaceRoot,
+      requestedPath,
+    });
+    return normalizeWorkspaceRelativePath({
+      workspaceRoot: resolve(args.workspaceRoot),
+      targetPath: absolutePath,
+    });
+  });
+  const message = requireGitCommitMessage(parsed);
+  const addResult = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "add", "--", ...paths],
+  });
+  if (addResult.exitCode !== 0) throw new Error(addResult.content);
+
+  const commitResult = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["git", "commit", "-m", message],
+  });
+  if (commitResult.exitCode !== 0) throw new Error(commitResult.content);
+
+  const [branchResult, hashResult, statusResult] = await Promise.all([
+    runWorkspaceCommand({
+      workspaceRoot: args.workspaceRoot,
+      command: ["git", "branch", "--show-current"],
+    }),
+    runWorkspaceCommand({
+      workspaceRoot: args.workspaceRoot,
+      command: ["git", "rev-parse", "HEAD"],
+    }),
+    runWorkspaceCommand({
+      workspaceRoot: args.workspaceRoot,
+      command: ["git", "status", "--short"],
+    }),
+  ]);
+  const branch = branchResult.stdout.trim();
+  const commitHash = hashResult.stdout.trim();
+  const status = statusResult.stdout.trim();
+  return {
+    content: [
+      `branch: ${branch}`,
+      `commit: ${commitHash}`,
+      `status: ${status || "clean"}`,
+      "",
+      commitResult.content,
+    ].join("\n"),
+    metadata: {
+      paths,
+      message,
+      branch,
+      commitHash,
+      status,
+      clean: status === "",
+      exitCode: commitResult.exitCode,
+    },
+  };
+}
+
+async function runPackageScriptTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+  commandTimeoutMs?: number;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const script = requirePackageScript(parsed);
+  const extraArgs = readPackageScriptArgs(parsed);
+  const packageScripts = await readWorkspacePackageScripts(args.workspaceRoot);
+  if (!packageScripts.scripts.includes(script)) {
+    return {
+      content: [
+        `script not found: ${script}`,
+        `available scripts: ${formatAvailableScripts(packageScripts.scripts)}`,
+        ...(packageScripts.error ? [`package.json read error: ${packageScripts.error}`] : []),
+      ].join("\n"),
+      metadata: {
+        script,
+        exitCode: 1,
+        reason: "script-not-found",
+        availableScripts: packageScripts.scripts,
+        ...(packageScripts.error ? { packageJsonError: packageScripts.error } : {}),
+      },
+    };
+  }
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["bun", "run", script, ...(extraArgs.length ? ["--", ...extraArgs] : [])],
+    timeoutMs: args.commandTimeoutMs,
+  });
+  return {
+    content: result.content,
+    metadata: {
+      script,
+      args: extraArgs,
+      exitCode: result.exitCode,
+      reason: result.exitCode === 0 ? "ok" : "script-failed",
+      timedOut: result.timedOut,
+      stdoutTail: result.stdout.trim().slice(-4000),
+      stderrTail: result.stderr.trim().slice(-4000),
+    },
+  };
+}
+
+async function resolveVisualStateBaseUrl(args: {
+  workspaceRoot: string;
+  explicitBaseUrl?: string;
+  commandTimeoutMs?: number;
+}) {
+  if (args.explicitBaseUrl) return args.explicitBaseUrl;
+  const statusResult = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["bun", "run", "preview:status"],
+    timeoutMs: args.commandTimeoutMs,
+  });
+  if (statusResult.exitCode !== 0) throw new Error(statusResult.content);
+  const status = parseLastJsonObject(statusResult.stdout);
+  const localApiOrigin = typeof status?.localApiOrigin === "string" ? status.localApiOrigin : "";
+  if (!localApiOrigin) {
+    throw new Error("captureVisualState could not read localApiOrigin from preview:status.");
+  }
+  return localApiOrigin;
+}
+
+async function captureVisualStateTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+  commandTimeoutMs?: number;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const captureArgs = readVisualStateCaptureArgs(parsed);
+  const baseUrl = await resolveVisualStateBaseUrl({
+    workspaceRoot: args.workspaceRoot,
+    explicitBaseUrl: captureArgs.baseUrl,
+    commandTimeoutMs: args.commandTimeoutMs,
+  });
+  const extraArgs = [
+    "--base",
+    baseUrl,
+    "--path",
+    captureArgs.path,
+    "--wait-selector",
+    captureArgs.waitSelector,
+    ...(captureArgs.scrollSelector ? ["--scroll-selector", captureArgs.scrollSelector] : []),
+    ...(captureArgs.focusSelector ? ["--focus-selector", captureArgs.focusSelector] : []),
+    ...(captureArgs.expectText ? ["--expect-text", captureArgs.expectText] : []),
+    "--screenshot",
+    captureArgs.screenshotPath,
+    "--metrics",
+    captureArgs.metricsPath,
+  ];
+  const result = await runPackageScriptTool({
+    call: {
+      id: args.call.id,
+      name: "runPackageScript",
+      arguments: JSON.stringify({
+        script: "probe:visual-review",
+        args: extraArgs,
+      }),
+    },
+    workspaceRoot: args.workspaceRoot,
+    commandTimeoutMs: args.commandTimeoutMs,
+  });
+  const metrics = parseLastJsonObject(String(result.metadata?.stdoutTail ?? result.content));
+  return {
+    content: [
+      `pageUrl: ${typeof metrics?.pageUrl === "string" ? metrics.pageUrl : ""}`,
+      `screenshotPath: ${captureArgs.screenshotPath}`,
+      `metricsPath: ${captureArgs.metricsPath}`,
+      `waitSelector: ${captureArgs.waitSelector}`,
+      ...(captureArgs.focusSelector ? [`focusSelector: ${captureArgs.focusSelector}`] : []),
+      ...(captureArgs.expectText ? [`expectText: ${captureArgs.expectText}`] : []),
+      "",
+      result.content,
+    ].join("\n").trim(),
+    metadata: {
+      ...result.metadata,
+      script: "probe:visual-review",
+      args: extraArgs,
+      baseUrl,
+      path: captureArgs.path,
+      waitSelector: captureArgs.waitSelector,
+      scrollSelector: captureArgs.scrollSelector,
+      focusSelector: captureArgs.focusSelector,
+      expectText: captureArgs.expectText,
+      screenshotPath: captureArgs.screenshotPath,
+      metricsPath: captureArgs.metricsPath,
+      ...(metrics ?? {}),
+    },
+  };
+}
+
+async function previewLifecycleTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+  commandTimeoutMs?: number;
+  script: "preview:start" | "preview:status" | "preview:stop" | "preview:release";
+}): Promise<AgentRuntimeToolResult> {
+  const result = await runPackageScriptTool({
+    call: {
+      id: args.call.id,
+      name: "runPackageScript",
+      arguments: JSON.stringify({ script: args.script }),
+    },
+    workspaceRoot: args.workspaceRoot,
+    commandTimeoutMs: args.commandTimeoutMs,
+  });
+  const summary = parseLastJsonObject(String(result.metadata?.stdoutTail ?? result.content)) ?? {};
+  return {
+    content: [
+      typeof summary.previewUrl === "string" ? `previewUrl: ${summary.previewUrl}` : "",
+      typeof summary.localApiOrigin === "string" ? `localApiOrigin: ${summary.localApiOrigin}` : "",
+      typeof summary.serverDbPath === "string" ? `serverDbPath: ${summary.serverDbPath}` : "",
+      "",
+      result.content,
+    ].filter((line, index, lines) => line || (index > 0 && lines[index - 1])).join("\n").trim(),
+    metadata: {
+      ...result.metadata,
+      script: args.script,
+      ...(summary ?? {}),
+    },
+  };
+}
+
+async function execShellTool(args: {
+  call: AgentRuntimeToolCallInput;
+  workspaceRoot: string;
+  commandTimeoutMs?: number;
+}): Promise<AgentRuntimeToolResult> {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const command = requireShellCommand(parsed, args.call.name);
+  const result = await runWorkspaceCommand({
+    workspaceRoot: args.workspaceRoot,
+    command: ["/bin/sh", "-lc", command],
+    timeoutMs: args.commandTimeoutMs,
+  });
+  return {
+    content: result.content,
+    metadata: { exitCode: result.exitCode, timedOut: result.timedOut },
+  };
+}
+
+export function createLocalWorkspaceToolExecutors(args: LocalWorkspaceToolArgs) {
+  return {
+    listWorkspaceFiles: (call: AgentRuntimeToolCallInput) => listWorkspaceFilesTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    readWorkspaceFile: (call: AgentRuntimeToolCallInput) => readWorkspaceFileTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    writeWorkspaceFile: (call: AgentRuntimeToolCallInput) => writeWorkspaceFileTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    replaceWorkspaceText: (call: AgentRuntimeToolCallInput) => replaceWorkspaceTextTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    applyEdit: (call: AgentRuntimeToolCallInput) => replaceWorkspaceTextTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    applyLineEdits: (call: AgentRuntimeToolCallInput) => replaceWorkspaceTextTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    listFiles: (call: AgentRuntimeToolCallInput) => listWorkspaceFilesTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    readFile: (call: AgentRuntimeToolCallInput) => readWorkspaceFileTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    writeFile: (call: AgentRuntimeToolCallInput) => writeWorkspaceFileTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    searchWorkspace: (call: AgentRuntimeToolCallInput) => searchWorkspaceTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    applyPatch: (call: AgentRuntimeToolCallInput) => applyPatchTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    gitStatus: () => gitStatusTool({
+      workspaceRoot: args.workspaceRoot,
+    }),
+    gitDiff: (call: AgentRuntimeToolCallInput) => gitDiffTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    gitCreateBranch: (call: AgentRuntimeToolCallInput) => gitCreateBranchTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    gitAdd: (call: AgentRuntimeToolCallInput) => gitAddTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    gitCommit: (call: AgentRuntimeToolCallInput) => gitCommitTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    commitWorkspace: (call: AgentRuntimeToolCallInput) => commitWorkspaceTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+    }),
+    runPackageScript: (call: AgentRuntimeToolCallInput) => runPackageScriptTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+    }),
+    startPreview: (call: AgentRuntimeToolCallInput) => previewLifecycleTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+      script: "preview:start",
+    }),
+    getPreviewStatus: (call: AgentRuntimeToolCallInput) => previewLifecycleTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+      script: "preview:status",
+    }),
+    stopPreview: (call: AgentRuntimeToolCallInput) => previewLifecycleTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+      script: "preview:stop",
+    }),
+    releasePreview: (call: AgentRuntimeToolCallInput) => previewLifecycleTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+      script: "preview:release",
+    }),
+    captureVisualState: (call: AgentRuntimeToolCallInput) => captureVisualStateTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+    }),
+    execShell: (call: AgentRuntimeToolCallInput) => execShellTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+    }),
+    execBash: (call: AgentRuntimeToolCallInput) => execShellTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      commandTimeoutMs: args.commandTimeoutMs,
+    }),
+  };
+}