arisa 5.1.13 → 5.1.49

package/src/core/tools/official-tool-installer.js

@@ -14,6 +14,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import { getToolDir } from "../../runtime/paths.js";
+import { normalizeToolDependencies, resolveToolDependencyPlan, satisfiesToolVersion } from "./tool-dependencies.js";
 
 const bundledLockFile = new URL("../../official-tools.lock.json", import.meta.url);
 
@@ -46,7 +47,8 @@ export function validateOfficialToolLock(lock, toolName) {
   if (!COMMIT_PATTERN.test(String(lock.commit || ""))) {
     throw new Error("Official tool lock requires an immutable 40-character commit");
   }
-  const files = lock.tools?.[toolName]?.files;
+  const entry = lock.tools?.[toolName];
+  const files = entry?.files;
   if (!files || typeof files !== "object" || Array.isArray(files) || !Object.keys(files).length) {
     throw new Error(`Official tool lock has no files for ${toolName}`);
   }
@@ -56,7 +58,12 @@ export function validateOfficialToolLock(lock, toolName) {
       throw new Error(`Invalid SHA-256 digest for ${toolName}/${file}`);
     }
   }
-  return { repository: lock.repository, commit: lock.commit, files };
+  const toolDependencies = normalizeToolDependencies(entry.toolDependencies);
+  const toolVersion = entry.version == null ? null : String(entry.version);
+  if (toolVersion && !satisfiesToolVersion(toolVersion, toolVersion)) {
+    throw new Error(`Invalid locked tool version for ${toolName}: ${toolVersion}`);
+  }
+  return { repository: lock.repository, commit: lock.commit, files, toolVersion, toolDependencies };
 }
 
 async function walkFiles(root, relative = "") {
@@ -133,11 +140,36 @@ async function checkoutRepository({ repository, commit, checkoutDir }) {
   if (resolved !== commit) throw new Error(`Official tool checkout resolved ${resolved}, expected ${commit}`);
 }
 
-async function validateEntrypoint(toolDir, toolName) {
+async function installPackageDependencies(toolDir) {
+  let packageJson;
+  try {
+    packageJson = JSON.parse(await readFile(path.join(toolDir, "package.json"), "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return { installed: false };
+    throw error;
+  }
+  const dependencyCount = Object.keys(packageJson.dependencies || {}).length + Object.keys(packageJson.optionalDependencies || {}).length;
+  if (!dependencyCount) return { installed: false };
+  if (await exists(path.join(toolDir, "package-lock.json"))) {
+    await runCommand("npm", ["ci", "--omit=dev"], { cwd: toolDir });
+  } else {
+    await runCommand("npm", ["install", "--omit=dev"], { cwd: toolDir });
+  }
+  return { installed: true, dependencyCount };
+}
+
+async function validateEntrypoint(toolDir, toolName, locked) {
   const manifest = JSON.parse(await readFile(path.join(toolDir, "tool.manifest.json"), "utf8"));
   if (manifest.name !== toolName) {
     throw new Error(`Official tool manifest mismatch: expected ${toolName}, got ${manifest.name || "missing"}`);
   }
+  if (locked.toolVersion && manifest.version !== locked.toolVersion) {
+    throw new Error(`Official tool version mismatch: expected ${locked.toolVersion}, got ${manifest.version || "missing"}`);
+  }
+  const manifestDependencies = normalizeToolDependencies(manifest.toolDependencies);
+  if (JSON.stringify(manifestDependencies) !== JSON.stringify(locked.toolDependencies)) {
+    throw new Error(`Official tool dependency metadata mismatch: ${toolName}`);
+  }
   const entry = manifest.entry || "index.js";
   const entryPath = path.join(toolDir, entry);
   if (!(await exists(entryPath))) throw new Error(`Official tool entry does not exist: ${entry}`);
@@ -151,6 +183,7 @@ export async function installLockedOfficialTool({
   destination,
   scratchRoot = os.tmpdir(),
   checkout = checkoutRepository,
+  installDependencies = installPackageDependencies,
   validate = validateEntrypoint
 }) {
   const locked = validateOfficialToolLock(lock, toolName);
@@ -165,7 +198,8 @@ export async function installLockedOfficialTool({
     const sourceDir = path.join(checkoutDir, "tools", toolName);
     await verifyOfficialToolTree(sourceDir, locked.files);
     await cp(sourceDir, stageDir, { recursive: true, errorOnExist: true, force: false });
-    await validate(stageDir, toolName);
+    await installDependencies(stageDir, toolName);
+    await validate(stageDir, toolName, locked);
     await mkdir(path.dirname(destination), { recursive: true });
     await rename(stageDir, destination);
     return { toolName, destination, commit: locked.commit, files: Object.keys(locked.files).length };
@@ -174,10 +208,48 @@ export async function installLockedOfficialTool({
   }
 }
 
+async function installedToolVersion(toolName) {
+  try {
+    const manifest = JSON.parse(await readFile(path.join(getToolDir(toolName), "tool.manifest.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : null;
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
 export async function installBundledOfficialTool(toolName, {
   lockFile = bundledLockFile,
-  install = installLockedOfficialTool
+  install = installLockedOfficialTool,
+  resolveInstalledVersion = installedToolVersion
 } = {}) {
   const lock = JSON.parse(await readFile(lockFile, "utf8"));
-  return install({ toolName, lock, destination: getToolDir(toolName) });
+  const entries = new Map(Object.entries(lock.tools || {}).map(([name, entry]) => [name, {
+    version: entry.version || null,
+    toolDependencies: normalizeToolDependencies(entry.toolDependencies)
+  }]));
+  const plan = resolveToolDependencyPlan(entries, toolName);
+  const dependencies = [];
+  let result = null;
+  for (const name of plan) {
+    const locked = validateOfficialToolLock(lock, name);
+    if (name !== toolName) {
+      const installedVersion = await resolveInstalledVersion(name);
+      if (installedVersion !== undefined) {
+        const requiredRanges = plan
+          .map((dependentName) => entries.get(dependentName)?.toolDependencies?.[name])
+          .filter(Boolean);
+        const incompatibleRange = requiredRanges.find((range) => !satisfiesToolVersion(installedVersion, range));
+        if (incompatibleRange || (!requiredRanges.length && locked.toolVersion !== installedVersion)) {
+          throw new Error(`Installed tool dependency is incompatible: ${name}@${installedVersion} does not satisfy ${incompatibleRange || locked.toolVersion || "locked version"}`);
+        }
+        dependencies.push({ name, version: installedVersion, status: "already-installed" });
+        continue;
+      }
+    }
+    const installed = await install({ toolName: name, lock, destination: getToolDir(name) });
+    if (name === toolName) result = installed;
+    else dependencies.push({ name, version: locked.toolVersion, status: "installed" });
+  }
+  return { ...result, dependencies };
 }

package/src/core/tools/tool-dependencies.js

@@ -0,0 +1,99 @@
+const TOOL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const RANGE_PATTERN = /^(\^)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+function versionParts(version) {
+  const match = VERSION_PATTERN.exec(String(version || ""));
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+}
+
+export function normalizeToolDependencies(value) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) throw new Error("toolDependencies must be an object");
+  const normalized = {};
+  for (const [name, range] of Object.entries(value)) {
+    if (!TOOL_NAME_PATTERN.test(name)) throw new Error(`Invalid tool dependency name: ${name}`);
+    if (!RANGE_PATTERN.test(String(range || ""))) throw new Error(`Unsupported tool dependency range for ${name}: ${range || "empty"}`);
+    normalized[name] = String(range);
+  }
+  return normalized;
+}
+
+export function satisfiesToolVersion(version, range) {
+  const actual = versionParts(version);
+  const match = RANGE_PATTERN.exec(String(range || ""));
+  if (!actual || !match) return false;
+  const expected = match.slice(2).map(Number);
+  if (!match[1]) return compareVersions(actual, expected) === 0;
+  if (compareVersions(actual, expected) < 0) return false;
+  if (expected[0] > 0) return actual[0] === expected[0];
+  if (expected[1] > 0) return actual[0] === 0 && actual[1] === expected[1];
+  return actual[0] === 0 && actual[1] === 0 && actual[2] === expected[2];
+}
+
+export function inspectToolDependencies(tools, rootName = null) {
+  const issues = [];
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (name, chain = []) => {
+    if (visiting.has(name)) {
+      issues.push({ tool: name, type: "cycle", dependency: name, chain: [...chain, name] });
+      return;
+    }
+    if (visited.has(name)) return;
+    const tool = tools.get(name);
+    if (!tool) return;
+    visiting.add(name);
+    for (const [dependency, range] of Object.entries(normalizeToolDependencies(tool.toolDependencies))) {
+      const installed = tools.get(dependency);
+      if (!installed) {
+        issues.push({ tool: name, type: "missing", dependency, range });
+        continue;
+      }
+      if (!satisfiesToolVersion(installed.version, range)) {
+        issues.push({ tool: name, type: "incompatible", dependency, range, installedVersion: installed.version || null });
+        continue;
+      }
+      visit(dependency, [...chain, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+  };
+  if (rootName) visit(rootName);
+  else for (const name of tools.keys()) visit(name);
+  return issues;
+}
+
+export function resolveToolDependencyPlan(entries, rootName) {
+  const tools = entries instanceof Map ? entries : new Map(Object.entries(entries || {}));
+  const order = [];
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (name, chain = []) => {
+    const tool = tools.get(name);
+    if (!tool) throw new Error(`Official tool dependency is not locked: ${name}`);
+    if (visiting.has(name)) throw new Error(`Circular official tool dependency: ${[...chain, name].join(" -> ")}`);
+    if (visited.has(name)) return;
+    visiting.add(name);
+    for (const [dependency, range] of Object.entries(normalizeToolDependencies(tool.toolDependencies))) {
+      const lockedDependency = tools.get(dependency);
+      if (!lockedDependency) throw new Error(`Official tool dependency is not locked: ${name} -> ${dependency}`);
+      if (!satisfiesToolVersion(lockedDependency.version, range)) {
+        throw new Error(`Locked tool dependency is incompatible: ${name} requires ${dependency}@${range}, lock has ${lockedDependency.version || "no version"}`);
+      }
+      visit(dependency, [...chain, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+    order.push(name);
+  };
+  visit(rootName);
+  return order;
+}

package/src/core/tools/tool-output-materializer.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { unlink } from "node:fs/promises";
+
+export async function materializeToolOutput({ result, name, chatId, artifactStore, taskStore, taskContext = null }) {
+  const chatArtifactStore = artifactStore.forChat(chatId);
+
+  if (result.output?.text) {
+    const artifact = await chatArtifactStore.createText({
+      text: result.output.text,
+      source: { type: "tool", toolName: name },
+      metadata: { tool: name }
+    });
+    result.output.artifactId = artifact.id;
+  }
+
+  if (result.output?.filePath) {
+    const generated = await chatArtifactStore.createFromFile({
+      originalPath: result.output.filePath,
+      fileName: result.output.fileName || path.basename(result.output.filePath),
+      kind: result.output.kind || "file",
+      mimeType: result.output.mimeType || "application/octet-stream",
+      source: { type: "tool", toolName: name },
+      metadata: { tool: name, delivery: result.output.delivery }
+    });
+    result.output.artifactId = generated.id;
+    await unlink(result.output.filePath).catch(() => {});
+  }
+
+  if (result.asyncTask || result.asyncTasks?.length) {
+    result.asyncTasks = await taskStore.addMany(result.asyncTasks || [result.asyncTask], {
+      payload: {
+        chatId,
+        ...(taskContext ? { telegramContext: taskContext } : {})
+      },
+      source: { type: "tool", toolName: name, chatId }
+    });
+    delete result.asyncTask;
+  }
+
+  return result;
+}

package/src/core/tools/tool-registry.js

@@ -2,7 +2,7 @@ import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from "node:fs/prom
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { arisaIpcSocketFile, arisaPackageDir, getToolConfigPath, getToolTmpDir, getChatToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
+import { arisaIpcSocketFile, arisaPackageDir, getToolConfigPath, getToolStateDir, getToolTmpDir, getChatToolTmpDir, toolsDir as userToolsRoot } from "../../runtime/paths.js";
 import { loadToolConfig, parseConfigModule, writeToolConfig } from "./tool-config.js";
 import { normalizeToolResult } from "./tool-result.js";
 import { readDaemonDiagnostic } from "./daemon-processes.js";
@@ -10,22 +10,59 @@ import { createDaemonRuntime, DAEMON_EVENT_TYPES, DAEMON_PROTOCOL_VERSION } from
 import { daemonConfigDefaults } from "../config/config-defaults.js";
 import { SkillRegistry } from "../skills/skill-registry.js";
 import { ToolUsageStore } from "./tool-usage-store.js";
+import { inspectToolDependencies, normalizeToolDependencies } from "./tool-dependencies.js";
 
 function toolEnv() {
   return { ...process.env, ARISA_PACKAGE_DIR: arisaPackageDir, ARISA_IPC_SOCKET: arisaIpcSocketFile };
 }
 
-function runProcess(command, args, options = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
+const defaultToolHelpTimeoutMs = 10_000;
+const defaultToolRunTimeoutMs = 30 * 60_000;
+const defaultToolKillGraceMs = 2_000;
+
+function positiveDuration(value, fallback) {
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function waitForToolProcess(child, { timeoutMs, killGraceMs, label }) {
+  return new Promise((resolve, reject) => {
+    let timedOut = false;
+    let forceTimer = null;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      forceTimer = setTimeout(() => child.kill("SIGKILL"), killGraceMs);
+    }, timeoutMs);
+
+    const finish = (callback, value) => {
+      clearTimeout(timeout);
+      clearTimeout(forceTimer);
+      callback(value);
+    };
+
+    child.once("error", (error) => finish(reject, error));
+    child.once("close", (code) => {
+      if (!timedOut) {
+        finish(resolve, code);
+        return;
+      }
+      const error = new Error(`${label} timed out after ${timeoutMs}ms`);
+      error.code = "TOOL_PROCESS_TIMEOUT";
+      finish(reject, error);
+    });
   });
 }
 
+async function runProcess(command, args, { timeoutMs, killGraceMs, label, ...options } = {}) {
+  const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (d) => { stdout += d.toString(); });
+  child.stderr.on("data", (d) => { stderr += d.toString(); });
+  const code = await waitForToolProcess(child, { timeoutMs, killGraceMs, label });
+  return { code, stdout, stderr };
+}
+
 function requirementNames(requirements) {
   if (Array.isArray(requirements)) {
     return requirements.map((item) => typeof item === "string" ? item : item?.name).filter(Boolean);
@@ -120,7 +157,7 @@ export function createToolOutputParser(name, { onEvent, maxFrameBytes = 1_048_57
   };
 }
 
-async function runToolProcess(command, args, { onEvent, maxFrameBytes, ...options } = {}) {
+async function runToolProcess(command, args, { onEvent, maxFrameBytes, timeoutMs, killGraceMs, label, ...options } = {}) {
   const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
   const parser = createToolOutputParser(path.basename(args[0] || command), { onEvent, maxFrameBytes });
   const stderrChunks = [];
@@ -138,13 +175,15 @@ async function runToolProcess(command, args, { onEvent, maxFrameBytes, ...option
     }
     return Buffer.concat(stderrChunks).toString("utf8");
   })();
-  const exitPromise = new Promise((resolve, reject) => {
-    child.once("error", reject);
-    child.once("close", resolve);
-  });
   child.stdout.resume();
   child.stderr.resume();
-  const code = await exitPromise;
+  let code;
+  try {
+    code = await waitForToolProcess(child, { timeoutMs, killGraceMs, label });
+  } catch (error) {
+    await Promise.allSettled([stdoutTask, stderrTask]);
+    throw error;
+  }
   const [parsed, stderr] = await Promise.all([stdoutTask, stderrTask]);
   return { code, parsed, stderr };
 }
@@ -203,17 +242,50 @@ function formatSemanticMetadata(tool) {
   ].join("\n");
 }
 
+function formatToolDependencies(tool, tools) {
+  const dependencies = Object.entries(tool.toolDependencies || {});
+  if (!dependencies.length) return null;
+  const lines = dependencies.map(([name, range]) => {
+    const issue = inspectToolDependencies(tools, tool.name).find((item) => item.dependency === name);
+    return `- ${name}@${range}: ${issue ? issue.type : "ready"}`;
+  });
+  return `Tool dependencies:\n${lines.join("\n")}`;
+}
+
+async function readOfficialToolNames() {
+  const baselinesDir = path.join(getToolStateDir("official-tool-sync"), "baselines");
+  try {
+    const entries = await readdir(baselinesDir, { withFileTypes: true });
+    return new Set(entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => entry.name.slice(0, -5)));
+  } catch (error) {
+    if (error?.code === "ENOENT") return new Set();
+    throw error;
+  }
+}
+
 export class ToolRegistry {
-  constructor({ logger, usageStore = new ToolUsageStore() } = {}) {
+  constructor({
+    logger,
+    usageStore = new ToolUsageStore(),
+    resolveOfficialToolNames = readOfficialToolNames,
+    helpTimeoutMs = defaultToolHelpTimeoutMs,
+    runTimeoutMs = defaultToolRunTimeoutMs,
+    killGraceMs = defaultToolKillGraceMs
+  } = {}) {
     this.logger = logger;
+    this.helpTimeoutMs = positiveDuration(helpTimeoutMs, defaultToolHelpTimeoutMs);
+    this.runTimeoutMs = positiveDuration(runTimeoutMs, defaultToolRunTimeoutMs);
+    this.killGraceMs = positiveDuration(killGraceMs, defaultToolKillGraceMs);
     this.tools = new Map();
     this.skillRegistry = new SkillRegistry();
     this.usageStore = usageStore;
+    this.resolveOfficialToolNames = resolveOfficialToolNames;
   }
 
-  async load() {
-    this.tools.clear();
-
+  async buildSnapshot() {
+    const snapshot = new Map();
     let entries = [];
     try {
       entries = await readdir(userToolsRoot, { withFileTypes: true });
@@ -228,13 +300,14 @@ export class ToolRegistry {
       const configPath = path.join(toolDir, "config.js");
       try {
         const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-        if (this.tools.has(manifest.name)) continue;
+        if (snapshot.has(manifest.name)) continue;
         const configSource = await readFile(configPath, "utf8");
         const defaults = parseConfigModule(configSource);
         const config = await loadToolConfig(manifest.name, defaults);
         const skillHints = this.skillRegistry.normalizeHints(manifest);
-        this.tools.set(manifest.name, {
+        snapshot.set(manifest.name, {
           ...manifest,
+          toolDependencies: normalizeToolDependencies(manifest.toolDependencies),
           category: normalizeCategory(manifest.category),
           keywords: normalizeKeywords(manifest.keywords),
           skillHints,
@@ -249,8 +322,13 @@ export class ToolRegistry {
         // ignore invalid tool dirs in v1
       }
     }
+    return snapshot;
+  }
 
-    this.logger?.log("tools", `loaded ${this.tools.size} tool(s)`);
+  async load() {
+    const snapshot = await this.buildSnapshot();
+    this.tools = snapshot;
+    this.logger?.log("tools", `loaded ${snapshot.size} tool(s)`);
   }
 
   list() {
@@ -259,6 +337,7 @@ export class ToolRegistry {
       version: typeof tool.version === "string" ? tool.version : null,
       packageDigest: typeof tool.packageDigest === "string" ? tool.packageDigest : null,
       requirements: requirementNames(tool.requirements),
+      toolDependencies: tool.toolDependencies || {},
       description: tool.description,
       input: tool.input,
       output: tool.output,
@@ -306,12 +385,19 @@ export class ToolRegistry {
   async help(name) {
     const tool = this.get(name);
     if (!tool) throw new Error(`Tool not found: ${name}`);
-    const result = await runProcess("node", [tool.entry, "--help"], { cwd: tool.dir, env: toolEnv() });
+    const result = await runProcess("node", [tool.entry, "--help"], {
+      cwd: tool.dir,
+      env: toolEnv(),
+      timeoutMs: this.helpTimeoutMs,
+      killGraceMs: this.killGraceMs,
+      label: `Tool help for ${name}`
+    });
     const help = result.stdout || result.stderr;
     const skills = await this.resolveSkills(name);
     const sections = [
       help.trimEnd(),
-      formatSemanticMetadata(tool)
+      formatSemanticMetadata(tool),
+      formatToolDependencies(tool, this.tools)
     ];
     if (skills.length) {
       const skillHelp = skills.map((item) => [
@@ -360,16 +446,32 @@ export class ToolRegistry {
     return { ok: true, tool: name, field, configPath };
   }
 
+  dependencyIssues(name = null) {
+    return inspectToolDependencies(this.tools, name);
+  }
+
   async usage(chatId) {
-    const counts = await this.usageStore.counts(chatId);
-    return this.list()
-      .map((tool) => ({ name: tool.name, count: counts[tool.name] || 0 }))
+    const [counts, officialNames] = await Promise.all([
+      this.usageStore.counts(chatId),
+      this.resolveOfficialToolNames()
+    ]);
+    const names = new Set([
+      ...this.list().map((tool) => tool.name),
+      ...Object.keys(counts)
+    ]);
+    return [...names]
+      .map((name) => ({ name, count: counts[name] || 0, official: officialNames.has(name) }))
       .sort((left, right) => left.name.localeCompare(right.name));
   }
 
   async run({ name, request, chatId = null, onEvent = null }) {
     const tool = this.get(name);
     if (!tool) throw new Error(`Tool not found: ${name}`);
+    const dependencyIssue = this.dependencyIssues(name)[0];
+    if (dependencyIssue) {
+      const version = dependencyIssue.installedVersion ? `; installed ${dependencyIssue.installedVersion}` : "";
+      throw new Error(`Tool dependency ${dependencyIssue.type}: ${dependencyIssue.tool} requires ${dependencyIssue.dependency}@${dependencyIssue.range || "valid"}${version}`);
+    }
     await this.usageStore.record(chatId, name).catch((error) => {
       this.logger?.error("tools", `could not record ${name} usage: ${error?.message || String(error)}`);
     });
@@ -399,7 +501,10 @@ export class ToolRegistry {
           cwd: tool.dir,
           env: toolEnv(),
           onEvent,
-          maxFrameBytes: daemonConfigDefaults.ipcFrameBytes
+          maxFrameBytes: daemonConfigDefaults.ipcFrameBytes,
+          timeoutMs: this.runTimeoutMs,
+          killGraceMs: this.killGraceMs,
+          label: `Tool run for ${name}`
         });
         if (processResult.stderr.trim()) {
           this.logger?.log("tools", `${name} stderr: ${processResult.stderr.trim()}`);
@@ -416,6 +521,18 @@ export class ToolRegistry {
       }
       return normalized;
     } catch (error) {
+      if (error?.code === "TOOL_PROCESS_TIMEOUT") {
+        return normalizeToolResult(name, {
+          ok: false,
+          status: "outcome_uncertain",
+          error: error.message,
+          resolution: {
+            type: "status_check_required",
+            retry: false,
+            message: "The tool process was terminated after timing out. Check external state before retrying."
+          }
+        });
+      }
       return normalizeToolResult(name, {
         ok: false,
         error: error?.message || `Invalid tool response for ${name}`