machine-bridge-mcp 0.12.1 → 0.13.0

package/src/local/default-instructions.mjs

@@ -2,8 +2,8 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, opendir } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
+import { packageScriptDisplayCommand, readProjectPackageMetadata, safeVersionValue } from "./project-package.mjs";
 
-const MAX_METADATA_FILE_BYTES = 1024 * 1024;
 const MAX_PROJECT_CONTEXT_BYTES = 16 * 1024;
 const MAX_SCRIPT_NAMES = 24;
 const MAX_WORKFLOW_FILES = 20;
@@ -77,14 +77,6 @@ const DOCUMENT_FILES = Object.freeze([
   "docs/TESTING.md",
 ]);
 
-const LOCKFILES = Object.freeze([
-  ["package-lock.json", "npm"],
-  ["pnpm-lock.yaml", "pnpm"],
-  ["yarn.lock", "yarn"],
-  ["bun.lock", "bun"],
-  ["bun.lockb", "bun"],
-]);
-
 const CI_FILES = Object.freeze([
   ".gitlab-ci.yml",
   "azure-pipelines.yml",
@@ -155,52 +147,34 @@ export async function discoverAutomaticProjectInstruction({
 }
 
 async function readPackageFacts(root, throwIfCancelled) {
-  const packagePath = join(root, "package.json");
-  const packageText = await readOptionalRegularUtf8(packagePath, MAX_METADATA_FILE_BYTES);
-  const lockfiles = [];
-  for (const [name, manager] of LOCKFILES) {
-    throwIfCancelled();
-    if (await isRegularNonSymlink(join(root, name))) lockfiles.push({ name, manager });
-  }
-  if (!packageText) {
-    const lines = lockfiles.length
-      ? [`- JavaScript lockfiles detected without readable root package metadata: ${lockfiles.map((item) => `\`${item.name}\``).join(", ")}. Inspect before installing dependencies.`]
+  const metadata = await readProjectPackageMetadata(root, throwIfCancelled);
+  if (!metadata.detected) return { detected: false, lines: [] };
+  if (metadata.packageState === "missing") {
+    const lines = metadata.lockfiles.length
+      ? [`- JavaScript lockfiles detected without readable root package metadata: ${metadata.lockfiles.map((item) => `\`${item.name}\``).join(", ")}. Inspect before installing dependencies.`]
       : [];
-    return { detected: lockfiles.length > 0, lines };
+    return { detected: metadata.lockfiles.length > 0, lines };
   }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(packageText);
-  } catch {
+  if (metadata.packageState === "invalid-json") {
     return { detected: true, lines: ["- A root `package.json` exists but is not valid JSON. Do not infer package commands until it is repaired or understood."] };
   }
-  if (!isPlainRecord(parsed)) return { detected: true, lines: ["- A root `package.json` exists but is not a JSON object."] };
+  if (metadata.packageState === "invalid-root") {
+    return { detected: true, lines: ["- A root `package.json` exists but is not a JSON object."] };
+  }
 
   const lines = [];
-  const declaredManager = safePackageManager(parsed.packageManager);
-  const managerName = packageManagerName(declaredManager) || uniqueLockManager(lockfiles);
-  if (declaredManager) lines.push(`- Declared package manager: \`${escapeInlineCode(declaredManager)}\`.`);
-  if (lockfiles.length === 1) lines.push(`- Package lockfile: \`${lockfiles[0].name}\`. Preserve it and use the matching package manager.`);
-  if (lockfiles.length > 1) lines.push(`- Multiple JavaScript lockfiles are present: ${lockfiles.map((item) => `\`${item.name}\``).join(", ")}. Do not choose or rewrite one automatically; inspect project guidance first.`);
-
-  const scripts = isPlainRecord(parsed.scripts)
-    ? Object.entries(parsed.scripts).filter(([name, value]) => validScriptName(name) && typeof value === "string").map(([name]) => name)
-    : [];
-  if (scripts.length) {
-    const selected = prioritizeScriptNames(scripts).slice(0, MAX_SCRIPT_NAMES);
-    const commands = selected.map((name) => formatPackageScriptCommand(managerName, name));
-    const suffix = scripts.length > selected.length ? `; ${scripts.length - selected.length} additional script(s) omitted` : "";
+  if (metadata.declaredManager) lines.push(`- Declared package manager: \`${escapeInlineCode(metadata.declaredManager)}\`.`);
+  if (metadata.lockfiles.length === 1) lines.push(`- Package lockfile: \`${metadata.lockfiles[0].name}\`. Preserve it and use the matching package manager.`);
+  if (metadata.lockfiles.length > 1) lines.push(`- Multiple JavaScript lockfiles are present: ${metadata.lockfiles.map((item) => `\`${item.name}\``).join(", ")}. Do not choose or rewrite one automatically; inspect project guidance first.`);
+  if (metadata.scripts.length) {
+    const selected = metadata.scripts.slice(0, MAX_SCRIPT_NAMES);
+    const commands = selected.map((name) => packageScriptDisplayCommand(metadata.managerName, name));
+    const suffix = metadata.scripts.length > selected.length ? `; ${metadata.scripts.length - selected.length} additional script(s) omitted` : "";
     lines.push(`- Declared package scripts (names only; bodies are not injected): ${commands.map((command) => `\`${escapeInlineCode(command)}\``).join(", ")}${suffix}.`);
   }
-
-  if (isPlainRecord(parsed.engines)) {
-    const engines = Object.entries(parsed.engines)
-      .map(([name, value]) => [name, safeVersionValue(value)])
-      .filter(([name, value]) => /^[A-Za-z0-9_.-]{1,40}$/.test(name) && value)
-      .slice(0, 10)
-      .map(([name, value]) => `\`${escapeInlineCode(name)} ${escapeInlineCode(value)}\``);
-    if (engines.length) lines.push(`- Declared runtime constraints: ${engines.join(", ")}.`);
+  if (metadata.engines.length) {
+    const engines = metadata.engines.map(([name, value]) => `\`${escapeInlineCode(name)} ${escapeInlineCode(value)}\``);
+    lines.push(`- Declared runtime constraints: ${engines.join(", ")}.`);
   }
   return { detected: true, lines };
 }
@@ -275,50 +249,6 @@ function virtualInstruction(source, content, precedence, scope) {
   };
 }
 
-function packageManagerName(value) {
-  if (!value) return "";
-  const match = /^(npm|pnpm|yarn|bun)(?:@|$)/.exec(value.trim());
-  return match?.[1] || "";
-}
-
-function uniqueLockManager(lockfiles) {
-  const managers = [...new Set(lockfiles.map((item) => item.manager))];
-  return managers.length === 1 ? managers[0] : "";
-}
-
-function formatPackageScriptCommand(manager, name) {
-  if (manager === "pnpm") return `pnpm run ${name}`;
-  if (manager === "yarn") return `yarn ${name}`;
-  if (manager === "bun") return `bun run ${name}`;
-  return `npm run ${name}`;
-}
-
-function prioritizeScriptNames(names) {
-  const preferred = ["check", "test", "lint", "typecheck", "build", "format", "verify", "ci", "prepack", "start", "dev"];
-  const rank = new Map(preferred.map((name, index) => [name, index]));
-  return [...new Set(names)].sort((left, right) => {
-    const leftRank = rank.has(left) ? rank.get(left) : preferred.length;
-    const rightRank = rank.has(right) ? rank.get(right) : preferred.length;
-    return leftRank - rightRank || left.localeCompare(right);
-  });
-}
-
-function validScriptName(value) {
-  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9:._/-]{0,119}$/.test(value);
-}
-
-function safePackageManager(value) {
-  if (typeof value !== "string") return "";
-  const normalized = value.trim();
-  return /^(?:npm|pnpm|yarn|bun)@[A-Za-z0-9][A-Za-z0-9.+_-]{0,90}$/.test(normalized) ? normalized : "";
-}
-
-function safeVersionValue(value) {
-  if (typeof value !== "string") return "";
-  const normalized = safeSingleLine(value, 120);
-  return normalized && /^[A-Za-z0-9][A-Za-z0-9 ._*+<>=~^|&!/-]{0,119}$/.test(normalized) ? normalized : "";
-}
-
 function skippableMetadataError(error) {
   return ["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"].includes(error?.code);
 }

package/src/local/network-proxy.mjs

@@ -0,0 +1,34 @@
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { getProxyForUrl } from "proxy-from-env";
+
+export function proxyAgentForWebSocket(webSocketUrl, proxyResolver = getProxyForUrl) {
+  const target = new URL(String(webSocketUrl));
+  if (target.protocol !== "ws:" && target.protocol !== "wss:") throw new Error("relay WebSocket URL must use ws or wss");
+  const proxyLookupUrl = new URL(target);
+  proxyLookupUrl.protocol = target.protocol === "wss:" ? "https:" : "http:";
+  const proxyValue = String(proxyResolver(proxyLookupUrl.href) || "").trim();
+  if (!proxyValue) return { agent: null, mode: "direct" };
+  let proxyUrl;
+  try {
+    proxyUrl = new URL(proxyValue);
+  } catch {
+    throw proxyConfigurationError("relay proxy configuration is not a valid URL");
+  }
+  if (!new Set(["http:", "https:"]).has(proxyUrl.protocol)) {
+    throw proxyConfigurationError("relay proxy must use HTTP or HTTPS");
+  }
+  try {
+    return {
+      agent: new HttpsProxyAgent(proxyUrl),
+      mode: "proxy",
+    };
+  } catch {
+    throw proxyConfigurationError("relay proxy configuration could not be initialized");
+  }
+}
+
+function proxyConfigurationError(message) {
+  const error = new Error(message);
+  error.code = "relay_proxy_configuration";
+  return error;
+}

package/src/local/process-sessions.mjs

@@ -253,6 +253,13 @@ export function terminateProcessTree(child, signal) {
   }
 }
 
+export function terminateProcessTreeWithEscalation(child, options = {}) {
+  const graceMs = Number.isFinite(Number(options.graceMs)) ? Math.max(0, Number(options.graceMs)) : 2000;
+  const schedule = typeof options.setTimeout === "function" ? options.setTimeout : setTimeout;
+  terminateProcessTree(child, "SIGTERM");
+  return schedule(() => terminateProcessTree(child, "SIGKILL"), graceMs);
+}
+
 function waitForSpawn(child) {
   return new Promise((resolvePromise, rejectPromise) => {
     const onSpawn = () => { cleanup(); resolvePromise(); };

package/src/local/project-package.mjs

@@ -0,0 +1,234 @@
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { join } from "node:path";
+
+const MAX_METADATA_FILE_BYTES = 1024 * 1024;
+const MAX_PACKAGE_COMMANDS = 64;
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+
+const PACKAGE_SCRIPT_INTENTS = Object.freeze({
+  check: "check verify validate validation test lint typecheck 完整测试 检查 验证 测试 校验 审查",
+  verify: "check verify validate validation test 检查 验证 测试 校验",
+  validate: "check verify validate validation test 检查 验证 测试 校验",
+  test: "test tests testing unit integration 完整测试 测试 单元测试 集成测试",
+  lint: "lint static analysis code quality 检查 静态检查 代码质量",
+  typecheck: "typecheck type check typescript 类型检查",
+  build: "build compile bundle package 构建 编译 打包",
+  compile: "build compile 构建 编译",
+  format: "format formatting 格式化",
+  start: "start run launch 启动 运行",
+  dev: "develop development start server 开发 启动 服务",
+  serve: "serve server start 服务 启动",
+  audit: "audit security vulnerability 审计 安全 漏洞",
+  deploy: "deploy deployment 部署",
+  release: "release publish 发布",
+  publish: "publish release 发布",
+  pack: "pack package 打包",
+  prepack: "pack package 打包",
+});
+
+const LOCKFILES = Object.freeze([
+  ["package-lock.json", "npm"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+]);
+
+export async function readProjectPackageMetadata(root, throwIfCancelled = () => {}) {
+  const packagePath = join(root, "package.json");
+  const packageText = await readOptionalRegularUtf8(packagePath, MAX_METADATA_FILE_BYTES);
+  const lockfiles = [];
+  for (const [name, manager] of LOCKFILES) {
+    throwIfCancelled();
+    if (await isRegularNonSymlink(join(root, name))) lockfiles.push({ name, manager });
+  }
+  if (!packageText) {
+    return {
+      detected: lockfiles.length > 0,
+      packagePath,
+      packageState: "missing",
+      declaredManager: "",
+      managerName: uniqueLockManager(lockfiles),
+      lockfiles,
+      scripts: [],
+      engines: [],
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(packageText);
+  } catch {
+    return invalidPackageMetadata(packagePath, lockfiles, "invalid-json");
+  }
+  if (!isPlainRecord(parsed)) return invalidPackageMetadata(packagePath, lockfiles, "invalid-root");
+
+  const declaredManager = safePackageManager(parsed.packageManager);
+  const scripts = isPlainRecord(parsed.scripts)
+    ? Object.entries(parsed.scripts)
+      .filter(([name, value]) => validScriptName(name) && typeof value === "string")
+      .map(([name]) => name)
+    : [];
+  const engines = isPlainRecord(parsed.engines)
+    ? Object.entries(parsed.engines)
+      .map(([name, value]) => [name, safeVersionValue(value)])
+      .filter(([name, value]) => /^[A-Za-z0-9_.-]{1,40}$/.test(name) && value)
+      .slice(0, 10)
+    : [];
+
+  const inferredManager = packageManagerName(declaredManager) || uniqueLockManager(lockfiles);
+  return {
+    detected: true,
+    packagePath,
+    packageState: "valid",
+    declaredManager,
+    managerName: inferredManager || (lockfiles.length === 0 ? "npm" : ""),
+    lockfiles,
+    scripts: prioritizeScriptNames(scripts),
+    engines,
+  };
+}
+
+export function packageScriptCommand(manager, script, platform = process.platform, commandShell = process.env.ComSpec || "cmd.exe") {
+  const executable = PACKAGE_MANAGERS.has(manager) ? manager : "npm";
+  if (!validScriptName(script)) throw new Error("package script name is invalid");
+  if (platform === "win32") return [commandShell, "/d", "/s", "/c", `${executable} run ${script}`];
+  return [executable, "run", script];
+}
+
+export function packageScriptDisplayCommand(manager, script) {
+  const executable = PACKAGE_MANAGERS.has(manager) ? manager : "npm";
+  if (!validScriptName(script)) throw new Error("package script name is invalid");
+  return `${executable} run ${script}`;
+}
+
+export function automaticPackageCommands(metadata, cwd, platform = process.platform) {
+  if (metadata?.packageState !== "valid" || !metadata.managerName || !metadata.scripts?.length) return new Map();
+  const commands = new Map();
+  for (const script of metadata.scripts.slice(0, MAX_PACKAGE_COMMANDS)) {
+    const base = normalizedCommandName(script);
+    if (!base) continue;
+    let name = `package.${base}`;
+    let suffix = 2;
+    while (commands.has(name)) name = `package.${base}.${suffix++}`;
+    commands.set(name, {
+      name,
+      description: `Run the declared package script '${script}' using the detected package manager.`,
+      argv: packageScriptCommand(metadata.managerName, script, platform),
+      cwd,
+      timeoutSeconds: 600,
+      allowExtraArgs: false,
+      source: metadata.packagePath,
+      sourceType: "automatic-package-script",
+      searchTerms: packageScriptSearchTerms(script),
+      script,
+    });
+  }
+  return commands;
+}
+
+export function safeVersionValue(value) {
+  if (typeof value !== "string") return "";
+  const normalized = safeSingleLine(value, 120);
+  return normalized && /^[A-Za-z0-9][A-Za-z0-9 ._*+<>=~^|&!/-]{0,119}$/.test(normalized) ? normalized : "";
+}
+
+
+function packageScriptSearchTerms(script) {
+  const normalized = String(script).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const root = normalized.split("-")[0];
+  return PACKAGE_SCRIPT_INTENTS[root] || "";
+}
+
+function invalidPackageMetadata(packagePath, lockfiles, packageState) {
+  return {
+    detected: true,
+    packagePath,
+    packageState,
+    declaredManager: "",
+    managerName: uniqueLockManager(lockfiles),
+    lockfiles,
+    scripts: [],
+    engines: [],
+  };
+}
+
+function packageManagerName(value) {
+  if (!value) return "";
+  const match = /^(npm|pnpm|yarn|bun)(?:@|$)/.exec(value.trim());
+  return match?.[1] || "";
+}
+
+function uniqueLockManager(lockfiles) {
+  const managers = [...new Set(lockfiles.map((item) => item.manager))];
+  return managers.length === 1 ? managers[0] : "";
+}
+
+function prioritizeScriptNames(names) {
+  const preferred = ["check", "test", "lint", "typecheck", "build", "format", "verify", "ci", "prepack", "start", "dev"];
+  const rank = new Map(preferred.map((name, index) => [name, index]));
+  return [...new Set(names)].sort((left, right) => {
+    const leftRank = rank.has(left) ? rank.get(left) : preferred.length;
+    const rightRank = rank.has(right) ? rank.get(right) : preferred.length;
+    return leftRank - rightRank || left.localeCompare(right);
+  });
+}
+
+function validScriptName(value) {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9:._/-]{0,119}$/.test(value);
+}
+
+function normalizedCommandName(value) {
+  const normalized = String(value).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+  return /^[a-z][a-z0-9._-]{0,47}$/.test(normalized) ? normalized : "";
+}
+
+function safePackageManager(value) {
+  if (typeof value !== "string") return "";
+  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/relay-connection.mjs

@@ -1,5 +1,6 @@
 import WebSocket from "ws";
 import { classifyOperationalError } from "./log.mjs";
+import { proxyAgentForWebSocket } from "./network-proxy.mjs";
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75_000;
@@ -35,6 +36,8 @@ export class RelayConnection {
     this.scheduler = options.scheduler || DEFAULT_SCHEDULER;
     this.now = typeof options.now === "function" ? options.now : Date.now;
     this.reconnectDelay = typeof options.reconnectDelay === "function" ? options.reconnectDelay : reconnectDelay;
+    this.proxyAgentForUrl = typeof options.proxyAgentForUrl === "function" ? options.proxyAgentForUrl : proxyAgentForWebSocket;
+    this.networkRoute = "unresolved";
     this.maxPayload = boundedPositiveInteger(options.maxPayload, 8 * 1024 * 1024);
     this.heartbeatIntervalMs = boundedPositiveInteger(options.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS);
     this.heartbeatTimeoutMs = boundedPositiveInteger(options.heartbeatTimeoutMs, DEFAULT_HEARTBEAT_TIMEOUT_MS);
@@ -72,6 +75,16 @@ export class RelayConnection {
     this.connectedOnceReject = null;
   }
 
+  status() {
+    return {
+      ready: this.ready,
+      closed: this.closed,
+      network_route: this.networkRoute,
+      reconnect_attempt: this.reconnectAttempt,
+      outage_active: this.outageStartedAt > 0,
+    };
+  }
+
   start() {
     if (!this.closed && this.connectedOnce) return this.connectedOnce;
     this.closed = false;
@@ -182,11 +195,20 @@ export class RelayConnection {
     this.logger.debug?.("connecting to remote relay", { endpoint: redactUrl(wsUrl), attempt: this.reconnectAttempt + 1 });
     let socket;
     try {
+      const proxy = this.proxyAgentForUrl(wsUrl);
+      this.networkRoute = proxy?.agent ? "proxy" : "direct";
       socket = new this.WebSocketClass(wsUrl, {
         headers: { "X-Bridge-Token": this.secret },
         maxPayload: this.maxPayload,
+        ...(proxy?.agent ? { agent: proxy.agent } : {}),
       });
+      this.logger.debug?.("remote relay network route selected", { route: this.networkRoute });
     } catch (error) {
+      if (error?.code === "relay_proxy_configuration") {
+        this.networkRoute = "invalid-proxy-configuration";
+        this.failPermanently("relay_proxy_configuration");
+        return;
+      }
       this.lastTransportErrorClass = classifyOperationalError(error);
       this.logger.debug?.("remote relay connection could not be created", { error_class: this.lastTransportErrorClass });
       this.scheduleReconnect("connection_interrupted");
@@ -475,6 +497,9 @@ function relayFatalMessage(category) {
   if (category === "relay_protocol_error") {
     return "remote relay protocol error; upgrade and redeploy both components, then restart the daemon";
   }
+  if (category === "relay_proxy_configuration") {
+    return "remote relay proxy configuration is invalid; check HTTP_PROXY, HTTPS_PROXY, and NO_PROXY";
+  }
   return "remote relay rejected the daemon connection; verify credentials or redeploy the Worker";
 }
 
@@ -491,6 +516,7 @@ function relayCloseUserCause(category) {
     relay_heartbeat_timeout: "relay stopped responding",
     relay_transport_error: "relay transport error",
     relay_protocol_error: "relay protocol error",
+    relay_proxy_configuration: "relay proxy configuration invalid",
     invalid_transport_payload: "invalid transport payload",
     message_too_large: "message exceeded the relay limit",
     normal_close: "connection closed",

package/src/local/runtime.mjs

@@ -7,7 +7,7 @@ import path, { basename, dirname, isAbsolute, join, relative, resolve, sep } fro
 import { RelayConnection } from "./relay-connection.mjs";
 import { applyUpdateHunks, parsePatchEnvelope } from "./patch.mjs";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
-import { MAX_COMMAND_BYTES, ProcessSessionManager, terminateProcessTree, validateArgv } from "./process-sessions.mjs";
+import { MAX_COMMAND_BYTES, ProcessSessionManager, terminateProcessTree, terminateProcessTreeWithEscalation, validateArgv } from "./process-sessions.mjs";
 export { MAX_COMMAND_BYTES } from "./process-sessions.mjs";
 import { allToolNames, assertCanonicalFullPolicy, isCanonicalFullPolicy, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, POLICY_PROFILES, SERVER_NAME, toolNamesForPolicy } from "./tools.mjs";
 import { classifyOperationalError } from "./log.mjs";
@@ -17,6 +17,7 @@ import { expandHome } from "./state.mjs";
 import { AgentContextManager } from "./agent-context.mjs";
 import { AppAutomationManager } from "./app-automation.mjs";
 import { BrowserBridgeManager } from "./browser-bridge.mjs";
+import { CapabilityObserver } from "./capability-observer.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
 
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
@@ -85,7 +86,7 @@ export function runtimeToolHandlerNames() {
 }
 
 export class LocalRuntime {
-  constructor({ workerUrl = "", secret = "", expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "", agentHome = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "", recoverJobs = true }) {
+  constructor({ workerUrl = "", secret = "", expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "", agentHome = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "", recoverJobs = true, applicationAutomation = {} }) {
     const remoteWorkerUrl = workerUrl ? String(workerUrl) : "";
     const remoteSecret = secret || "";
     this.workspaceInput = resolve(workspace || process.cwd());
@@ -100,6 +101,7 @@ export class LocalRuntime {
     this.callProcesses = new Map();
     this.cancelledCalls = new Set();
     this.mutationQueue = Promise.resolve();
+    this.capabilityObserver = new CapabilityObserver();
     this.runtimeDir = createRuntimeDir();
     if (typeof jobRoot !== "string" || !jobRoot.trim()) throw new Error("persistent managed-job root is required");
     this.managedJobManager = new ManagedJobManager({
@@ -139,6 +141,7 @@ export class LocalRuntime {
     const readResourceText = (name) => this.readLocalResourceText(name);
     const readResourceBinary = (name) => this.readLocalResourceBinary(name);
     this.appAutomationManager = new AppAutomationManager({
+      ...applicationAutomation,
       policy: this.policy,
       displayPath: (value) => this.displayPath(value),
       runProcess,
@@ -198,9 +201,11 @@ export class LocalRuntime {
         per_tool_events: "debug-only",
         default_logs_include_tool_failures: false,
         tool_arguments_or_results_logged: false,
+        capability_routing: this.capabilityObserver.snapshot(),
       },
       runtime: {
         environment: this.policy.minimalEnv ? "isolated-minimal" : "full-parent",
+        relay: this.relay?.status?.() || null,
         runtime_dir: this.policy.exposeAbsolutePaths ? this.runtimeDir : "<private-runtime-dir>",
         process_sessions: this.processSessionManager.status(),
         managed_jobs: this.managedJobManager.status(),
@@ -323,14 +328,8 @@ export class LocalRuntime {
     this.cancelledCalls.add(callId);
     this.processSessionManager.notifyCancellation();
     this.browserBridgeManager?.cancelCall(callId);
-    for (const child of this.callProcesses.get(callId) || []) terminateProcessTree(child, "SIGTERM");
     const children = [...(this.callProcesses.get(callId) || [])];
-    if (children.length) {
-      const timer = setTimeout(() => {
-        for (const child of children) if (this.activeProcesses.has(child)) terminateProcessTree(child, "SIGKILL");
-      }, 2000);
-      timer.unref?.();
-    }
+    for (const child of children) terminateProcessTreeWithEscalation(child);
     this.logger.debug?.("tool call cancellation requested", { call_id: shortCallId(callId), reason });
   }
 
@@ -351,6 +350,7 @@ export class LocalRuntime {
       gitRoot: git.code === 0 ? this.displayPath(git.stdout.trim()) : "",
       policy: this.policy,
       tools: ["server_info", ...this.tools()],
+      capabilityRouting: this.capabilityObserver.snapshot(),
       topLevel: top.entries || [],
     };
   }
@@ -795,13 +795,14 @@ export class LocalRuntime {
         status_tool: "browser_status",
       } : null,
     };
+    this.capabilityObserver.recordBootstrap(bootstrap);
     return bootstrap;
   }
 
   async resolveTaskCapabilities(args = {}, context = {}) {
     const result = await this.agentContextManager.resolveTaskCapabilities(args, context);
     const task = String(args.task || "");
-    if (/app|application|gui|window|应用|软件|窗口|界面/i.test(task) && this.policy.profile === "full") {
+    if (this.policy.profile === "full") {
       const applications = await this.appAutomationManager.listApplications({ query: "", max_results: 500 }, context).catch(() => ({ applications: [] }));
       const lower = task.toLowerCase();
       result.application_matches = applications.applications
@@ -813,7 +814,12 @@ export class LocalRuntime {
     } else {
       result.application_matches = [];
     }
+    if (result.application_matches.length) {
+      result.recommended_tools = [...new Set([...result.recommended_tools, "list_local_applications", "open_local_application", "inspect_local_application", "operate_local_application"])];
+    }
     result.browser_backend = this.policy.profile === "full" ? { tool: "browser_status", existing_profile: true, extension_bridge: true } : null;
+    result.routing_observability = "Call server_info or project_overview to verify that bootstrap and task capability resolution reached the local runtime.";
+    this.capabilityObserver.recordResolution(task, result);
     return result;
   }
 
@@ -873,12 +879,9 @@ export class LocalRuntime {
 
   terminateActiveProcesses(signal = "SIGTERM", escalate = false) {
     const children = [...this.activeProcesses];
-    for (const child of children) terminateProcessTree(child, signal);
-    if (escalate && signal !== "SIGKILL" && children.length) {
-      const timer = setTimeout(() => {
-        for (const child of children) if (this.activeProcesses.has(child)) terminateProcessTree(child, "SIGKILL");
-      }, 2000);
-      timer.unref?.();
+    for (const child of children) {
+      if (escalate && signal !== "SIGKILL") terminateProcessTreeWithEscalation(child);
+      else terminateProcessTree(child, signal);
     }
   }
 
@@ -911,14 +914,12 @@ export class LocalRuntime {
       let killTimer = null;
       const timer = setTimeout(() => {
         timedOut = true;
-        terminateProcessTree(child, "SIGTERM");
-        killTimer = setTimeout(() => terminateProcessTree(child, "SIGKILL"), 2000);
-        killTimer.unref?.();
+        killTimer = terminateProcessTreeWithEscalation(child);
       }, timeoutMs);
       timer.unref?.();
       const cleanup = () => {
         clearTimeout(timer);
-        if (killTimer) clearTimeout(killTimer);
+        if (killTimer && !timedOut) clearTimeout(killTimer);
         this.activeProcesses.delete(child);
         if (context.callId) {
           const set = this.callProcesses.get(context.callId);