machine-bridge-mcp 0.12.2 → 0.14.0

package/src/local/capability-observer.mjs

@@ -0,0 +1,56 @@
+import { createHmac, randomBytes } from "node:crypto";
+
+export class CapabilityObserver {
+  constructor(now = () => Date.now(), taskFingerprintKey = randomBytes(32)) {
+    this.now = now;
+    this.taskFingerprintKey = Buffer.from(taskFingerprintKey);
+    this.bootstrapCount = 0;
+    this.resolutionCount = 0;
+    this.lastBootstrap = null;
+    this.lastResolution = null;
+  }
+
+  recordBootstrap(result) {
+    this.bootstrapCount += 1;
+    this.lastBootstrap = {
+      observed_at: timestamp(this.now()),
+      target: result?.target || ".",
+      instruction_bytes: Buffer.byteLength(String(result?.instructions || "")),
+      builtin_loaded: Boolean(result?.builtin_instructions),
+      automatic_project_context_loaded: Boolean(result?.automatic_project_context),
+      global_model_instructions_loaded: Boolean(result?.model_instructions_file),
+      refresh_fingerprint: String(result?.capability_refresh?.instruction_and_command_fingerprint || ""),
+    };
+  }
+
+  recordResolution(task, result) {
+    this.resolutionCount += 1;
+    this.lastResolution = {
+      observed_at: timestamp(this.now()),
+      task_fingerprint: createHmac("sha256", this.taskFingerprintKey).update(String(task || "")).digest("hex"),
+      target: result?.target || ".",
+      selected_skill: result?.selected_skill?.name || null,
+      matched_skills: Array.isArray(result?.skill_matches) ? result.skill_matches.length : 0,
+      matched_commands: Array.isArray(result?.command_matches) ? result.command_matches.length : 0,
+      matched_applications: Array.isArray(result?.application_matches) ? result.application_matches.length : 0,
+      recommended_tools: Array.isArray(result?.recommended_tools) ? [...result.recommended_tools] : [],
+      refresh_fingerprint: String(result?.refresh?.fingerprint || ""),
+    };
+  }
+
+  snapshot() {
+    return {
+      bootstrap_observed: this.bootstrapCount > 0,
+      bootstrap_count: this.bootstrapCount,
+      task_resolution_observed: this.resolutionCount > 0,
+      task_resolution_count: this.resolutionCount,
+      last_bootstrap: this.lastBootstrap ? structuredClone(this.lastBootstrap) : null,
+      last_task_resolution: this.lastResolution ? structuredClone(this.lastResolution) : null,
+      enforcement_boundary: "The server can discover, rank, load, and report capabilities; the MCP host decides whether to call the resolver or recommended tools.",
+    };
+  }
+}
+
+function timestamp(milliseconds) {
+  return new Date(Number(milliseconds)).toISOString();
+}

package/src/local/cli.mjs

@@ -10,7 +10,7 @@ import { runStdioServer } from "./stdio.mjs";
 import { assertCanonicalFullPolicy, DEFAULT_POLICY_PROFILE, DEFAULT_POLICY_REVISION, POLICY_PROFILES, normalizePolicy, policyProfile, toolsForPolicy } from "./tools.mjs";
 import { classifyOperationalError, createLogger, normalizeLogLevel, sanitizeLogText } from "./log.mjs";
 import { activeManagedJobs, inspectResourceFile, loadManagedJobPlan, ManagedJobManager, publicResourceRegistry, validateResourceName } from "./managed-jobs.mjs";
-import { runWrangler } from "./shell.mjs";
+import { run, runWrangler } from "./shell.mjs";
 import { generateRegisteredSshKey } from "./resource-operations.mjs";
 import { runFullAccessTest } from "./full-access-test.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
@@ -1124,6 +1124,10 @@ async function doctorCommand(args) {
   const workspace = await chooseWorkspace(args, { promptOnFirstRun: false, save: false, allowPositional: true });
   const checks = [];
   checks.push({ name: "node", ok: isSupportedNodeVersion(), detail: process.version });
+  const npmCommand = npmVersionCommand();
+  const npm = await run(npmCommand.file, npmCommand.args, { capture: true, allowFailure: true, timeoutMs: 10_000 });
+  const npmDetail = sanitizeLines(npm.stdout || npm.stderr);
+  checks.push({ name: "npm", ok: npm.code === 0 && isSupportedNpmVersion(npmDetail), detail: npmDetail || "unavailable" });
   const wrangler = await runWrangler(["--version"], { capture: true, allowFailure: true });
   checks.push({ name: "wrangler", ok: wrangler.code === 0, detail: (wrangler.stdout || wrangler.stderr).trim() });
   const whoami = await runWrangler(["whoami"], { capture: true, allowFailure: true });
@@ -1557,10 +1561,22 @@ function validateWorkerName(value) {
 }
 
 export function isSupportedNodeVersion(version = process.versions.node) {
-  const major = Number(String(version || "").split(".")[0]);
+  const major = Number(String(version || "").replace(/^v/, "").split(".")[0]);
   return Number.isInteger(major) && major >= 26;
 }
 
+export function isSupportedNpmVersion(version) {
+  const major = Number(String(version || "").trim().replace(/^v/, "").split(".")[0]);
+  return Number.isInteger(major) && major >= 12;
+}
+
+export function npmVersionCommand(platform = process.platform, comspec = process.env.ComSpec) {
+  if (platform === "win32") {
+    return { file: comspec || "cmd.exe", args: ["/d", "/s", "/c", "npm --version"] };
+  }
+  return { file: "npm", args: ["--version"] };
+}
+
 function assertNodeVersion() {
   if (!isSupportedNodeVersion()) throw new Error(`Node.js >=26 is required; current ${process.version}`);
 }
@@ -1568,8 +1584,10 @@ function assertNodeVersion() {
 function usage() {
   console.log(`machine-bridge-mcp
 
+Installation (run from a package-free temporary directory; Node.js >=26):
+  npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest && machine-mcp
+
 Usage:
-  npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest && machine-mcp
   npx machine-bridge-mcp@latest                  # no global install; autostart may rely on npm cache
   ./mbm                                          # from source checkout
   .\\mbm.cmd                                      # from source checkout on Windows cmd

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",