machine-bridge-mcp 1.1.4 → 1.2.0

package/src/local/numbers.mjs

@@ -1,3 +1,11 @@
+// @ts-check
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @param {number} minimum
+ * @param {number} maximum
+ */
 export function clampInteger(value, fallback, minimum, maximum) {
   const parsed = typeof value === "number"
     ? value

package/src/local/policy.mjs

@@ -1,35 +1,96 @@
+// @ts-check
+
 import catalog from "../shared/tool-catalog.json" with { type: "json" };
 import contract from "../shared/policy-contract.json" with { type: "json" };
 import { BridgeError } from "./errors.mjs";
 
+/** @typedef {"off" | "direct" | "shell"} ExecMode */
+/**
+ * @typedef {{
+ *   profile: string,
+ *   allowWrite: boolean,
+ *   execMode: ExecMode,
+ *   unrestrictedPaths: boolean,
+ *   minimalEnv: boolean,
+ *   exposeAbsolutePaths: boolean,
+ * }} PolicyCapabilities
+ */
+/**
+ * @typedef {PolicyCapabilities & {
+ *   origin: string,
+ *   revision: number,
+ *   allowExec: boolean,
+ * }} NormalizedPolicy
+ */
+/**
+ * @typedef {{
+ *   profile?: string,
+ *   allowWrite?: boolean,
+ *   execModes?: ExecMode[],
+ *   unrestrictedPaths?: boolean,
+ *   minimalEnv?: boolean,
+ *   exposeAbsolutePaths?: boolean,
+ * }} AvailabilityRequirements
+ */
+/** @typedef {{name: string, availability: string} & Record<string, unknown>} ToolDefinition */
+/**
+ * @typedef {{
+ *   profile?: unknown,
+ *   origin?: unknown,
+ *   revision?: unknown,
+ *   allowWrite?: unknown,
+ *   allowExec?: unknown,
+ *   execMode?: unknown,
+ *   unrestrictedPaths?: unknown,
+ *   minimalEnv?: unknown,
+ *   exposeAbsolutePaths?: unknown,
+ * }} PolicyInput
+ */
+
 export const DEFAULT_POLICY_PROFILE = String(contract.defaultProfile);
 export const DEFAULT_POLICY_REVISION = Number(contract.revision);
+/** @type {Readonly<Record<string, Readonly<PolicyCapabilities>>>} */
 export const POLICY_PROFILES = Object.freeze(Object.fromEntries(
-  Object.entries(contract.profiles).map(([name, value]) => [name, Object.freeze({ ...value })]),
+  Object.entries(contract.profiles).map(([name, value]) => [name, Object.freeze(/** @type {PolicyCapabilities} */ ({ ...value }))]),
 ));
 export const POLICY_ORIGINS = Object.freeze(new Set(contract.origins.map(String)));
+/** @type {Readonly<Record<string, Readonly<AvailabilityRequirements>>>} */
 export const POLICY_AVAILABILITY = Object.freeze(Object.fromEntries(
-  Object.entries(contract.availability).map(([name, value]) => [name, Object.freeze({ ...value })]),
+  Object.entries(contract.availability).map(([name, value]) => [
+    name,
+    Object.freeze(/** @type {AvailabilityRequirements} */ ({ ...value })),
+  ]),
 ));
 
-const TOOLS = Object.freeze(catalog.map((tool) => Object.freeze({ ...tool })));
+/** @type {ReadonlyArray<Readonly<ToolDefinition>>} */
+const TOOLS = Object.freeze(catalog.map((tool) => Object.freeze(/** @type {ToolDefinition} */ ({ ...tool }))));
 const TOOL_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
 
+/** @param {unknown} name @param {unknown} [origin] */
 export function policyProfile(name, origin = "explicit") {
   const profile = String(name || "").trim().toLowerCase();
-  if (!POLICY_PROFILES[profile]) throw new BridgeError("invalid_request", `unknown policy profile: ${profile}`);
-  return normalizePolicy({ ...POLICY_PROFILES[profile], origin, revision: DEFAULT_POLICY_REVISION });
+  const canonical = POLICY_PROFILES[profile];
+  if (!canonical) throw new BridgeError("invalid_request", `unknown policy profile: ${profile}`);
+  return normalizePolicy({ ...canonical, origin, revision: DEFAULT_POLICY_REVISION });
 }
 
+/** @param {PolicyInput} [policy] @returns {Readonly<NormalizedPolicy>} */
 export function normalizePolicy(policy = {}) {
-  const execMode = ["off", "direct", "shell"].includes(policy.execMode)
-    ? policy.execMode
+  const requestedExecMode = policy.execMode;
+  /** @type {ExecMode} */
+  const execMode = requestedExecMode === "off" || requestedExecMode === "direct" || requestedExecMode === "shell"
+    ? requestedExecMode
     : policy.allowExec === true
       ? "shell"
       : "off";
-  const origin = POLICY_ORIGINS.has(policy.origin) ? policy.origin : "custom";
-  const revision = Number.isInteger(policy.revision) && policy.revision > 0 ? policy.revision : DEFAULT_POLICY_REVISION;
+  const requestedOrigin = typeof policy.origin === "string" ? policy.origin : "";
+  const origin = POLICY_ORIGINS.has(requestedOrigin) ? requestedOrigin : "custom";
+  const requestedRevision = typeof policy.revision === "number" ? policy.revision : Number.NaN;
+  const revision = Number.isInteger(requestedRevision) && requestedRevision > 0
+    ? requestedRevision
+    : DEFAULT_POLICY_REVISION;
   const requestedProfile = typeof policy.profile === "string" && policy.profile ? policy.profile : "custom";
+  /** @type {NormalizedPolicy} */
   const normalized = {
     profile: requestedProfile,
     origin,
@@ -46,6 +107,7 @@ export function normalizePolicy(policy = {}) {
   return Object.freeze(normalized);
 }
 
+/** @param {PolicyCapabilities} left @param {PolicyCapabilities} right */
 export function policyCapabilitiesEqual(left, right) {
   return left.allowWrite === right.allowWrite
     && left.execMode === right.execMode
@@ -54,10 +116,12 @@ export function policyCapabilitiesEqual(left, right) {
     && left.exposeAbsolutePaths === right.exposeAbsolutePaths;
 }
 
+/** @param {PolicyInput} [policy] */
 export function isCanonicalFullPolicy(policy = {}) {
   return policyCapabilitiesEqual(normalizePolicy(policy), POLICY_PROFILES.full);
 }
 
+/** @param {PolicyInput} [policy] */
 export function assertCanonicalFullPolicy(policy = {}) {
   const normalized = normalizePolicy(policy);
   if (normalized.profile !== "full" || !isCanonicalFullPolicy(normalized)) {
@@ -69,9 +133,10 @@ export function assertCanonicalFullPolicy(policy = {}) {
   return normalized;
 }
 
+/** @param {PolicyInput} policy @param {unknown} availability */
 export function policyAllowsAvailability(policy, availability) {
   const normalized = normalizePolicy(policy);
-  const requirements = POLICY_AVAILABILITY[availability];
+  const requirements = POLICY_AVAILABILITY[String(availability || "")];
   if (!requirements) return false;
   if (requirements.profile && normalized.profile !== requirements.profile) return false;
   if (requirements.allowWrite === true && normalized.allowWrite !== true) return false;
@@ -82,15 +147,18 @@ export function policyAllowsAvailability(policy, availability) {
   return true;
 }
 
+/** @param {unknown} name */
 export function toolDefinition(name) {
   return TOOL_BY_NAME.get(String(name || "")) || null;
 }
 
+/** @param {PolicyInput} policy @param {unknown} name */
 export function policyAllowsTool(policy, name) {
   const tool = toolDefinition(name);
   return Boolean(tool && policyAllowsAvailability(policy, tool.availability));
 }
 
+/** @param {PolicyInput} policy @param {unknown} name */
 export function assertToolAllowed(policy, name) {
   const tool = toolDefinition(name);
   if (!tool) throw new BridgeError("not_found", `unknown tool: ${String(name || "")}`);
@@ -102,12 +170,14 @@ export function assertToolAllowed(policy, name) {
   return tool;
 }
 
+/** @param {PolicyInput} [policy] */
 export function toolsForPolicy(policy = {}) {
   const normalized = normalizePolicy(policy);
   return TOOLS.filter((tool) => policyAllowsAvailability(normalized, tool.availability))
     .map(({ availability, ...tool }) => structuredClone(tool));
 }
 
+/** @param {PolicyInput} [policy] */
 export function toolNamesForPolicy(policy = {}) {
   const normalized = normalizePolicy(policy);
   return TOOLS.filter((tool) => policyAllowsAvailability(normalized, tool.availability)).map((tool) => tool.name);
@@ -117,23 +187,29 @@ export function allToolNames() {
   return TOOLS.map((tool) => tool.name);
 }
 
-
+/**
+ * @param {PolicyInput} policy
+ * @param {((tool: string) => unknown) | null | undefined} provided
+ */
 export function createToolAuthorizer(policy, provided) {
   if (typeof provided === "function") return provided;
   const gate = new PolicyGate(policy);
-  return (tool) => gate.assert(tool);
+  return (/** @type {string} */ tool) => gate.assert(tool);
 }
 
 export class PolicyGate {
+  /** @param {PolicyInput} policy */
   constructor(policy) {
     this.policy = normalizePolicy(policy);
     this.allowedNames = new Set(toolNamesForPolicy(this.policy));
   }
 
+  /** @param {unknown} name */
   allows(name) {
     return this.allowedNames.has(String(name || ""));
   }
 
+  /** @param {unknown} name */
   assert(name) {
     return assertToolAllowed(this.policy, name);
   }

package/src/local/project-metadata.mjs

@@ -1,22 +1,28 @@
+// @ts-check
+
 import { constants as fsConstants } from "node:fs";
 import { lstat, open } from "node:fs/promises";
 
 const SKIPPABLE_METADATA_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"]);
 
+/** @param {unknown} value @param {number} maxLength */
 export function safeSingleLine(value, maxLength) {
   if (typeof value !== "string") return "";
   return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maxLength);
 }
 
+/** @param {unknown} error */
 export function skippableMetadataError(error) {
-  return SKIPPABLE_METADATA_CODES.has(error?.code);
+  return SKIPPABLE_METADATA_CODES.has(/** @type {NodeJS.ErrnoException} */ (error)?.code || "");
 }
 
+/** @param {string} filePath */
 export async function isRegularNonSymlink(filePath) {
   const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
   return Boolean(info && !info.isSymbolicLink() && info.isFile());
 }
 
+/** @param {string} filePath @param {number} maxBytes */
 export async function readOptionalRegularUtf8(filePath, maxBytes) {
   const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0))
     .catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));

package/src/local/records.mjs

@@ -1,3 +1,9 @@
+// @ts-check
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
 export function isPlainRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const prototype = Object.getPrototypeOf(value);

package/src/local/runtime-capabilities.mjs

@@ -0,0 +1,66 @@
+export async function sessionBootstrap({
+  agentContextManager,
+  appAutomationManager,
+  capabilityObserver,
+  policy,
+}, args = {}, context = {}) {
+  const bootstrap = await agentContextManager.sessionBootstrap(args, context);
+  bootstrap.local_automation = {
+    applications: appAutomationManager.capabilities(),
+    browser: policy.profile === "full" ? {
+      existing_profile: true,
+      extension_bridge: true,
+      status_tool: "browser_status",
+    } : null,
+  };
+  capabilityObserver.recordBootstrap(bootstrap);
+  return bootstrap;
+}
+
+export async function resolveTaskCapabilities({
+  agentContextManager,
+  appAutomationManager,
+  capabilityObserver,
+  policy,
+}, args = {}, context = {}) {
+  const result = await agentContextManager.resolveTaskCapabilities(args, context);
+  const task = String(args.task || "");
+  if (policy.profile === "full") {
+    const applications = await appAutomationManager
+      .listApplications({ query: "", max_results: 500 }, context)
+      .catch(() => ({ applications: [] }));
+    const lower = task.toLowerCase();
+    result.application_matches = applications.applications
+      .map((application) => ({ application, score: applicationMatchScore(lower, application) }))
+      .filter((item) => item.score > 0)
+      .sort((left, right) => right.score - left.score || left.application.name.localeCompare(right.application.name))
+      .slice(0, 20)
+      .map(({ application, score }) => ({ ...application, score }));
+  } 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 = 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.";
+  capabilityObserver.recordResolution(task, result);
+  return result;
+}
+
+function applicationMatchScore(task, application) {
+  const name = String(application.name || "").toLowerCase();
+  const id = String(application.id || "").toLowerCase();
+  if (!name) return 0;
+  if (task.includes(name)) return 10 + Math.min(name.length, 20);
+  const words = name.split(/[^\p{L}\p{N}]+/u).filter((word) => word.length >= 2);
+  return words.reduce((score, word) => score + (task.includes(word) ? 2 : 0), id && task.includes(id) ? 5 : 0);
+}

package/src/local/runtime-diagnostics.mjs

@@ -0,0 +1,91 @@
+import { randomBytes } from "node:crypto";
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { classifyOperationalError } from "./log.mjs";
+import { readBoundedFile } from "./workspace-file-service.mjs";
+
+export async function diagnoseRuntime({
+  policy,
+  runtimeDir,
+  workspace,
+  runProcess,
+  probeShell,
+  managedJobManager,
+  throwIfCancelled,
+}, context = {}) {
+  throwIfCancelled(context);
+  const checks = [{
+    layer: "mcp-host-to-daemon",
+    ok: true,
+    detail: "This diagnostic request reached the local Machine Bridge runtime.",
+  }, {
+    layer: "machine-bridge-policy",
+    ok: policy.execMode === "direct" || policy.execMode === "shell",
+    detail: `profile=${policy.profile}; exec_mode=${policy.execMode}; unrestricted_paths=${policy.unrestrictedPaths}`,
+  }];
+
+  const probe = join(runtimeDir, `.diagnostic-${process.pid}-${randomBytes(6).toString("hex")}`);
+  try {
+    await writeFile(probe, "ok\n", { mode: 0o600, flag: "wx" });
+    const { buffer } = await readBoundedFile(probe, 64, "diagnostic file");
+    checks.push({ layer: "local-filesystem", ok: buffer.toString("utf8") === "ok\n", error_class: null });
+  } catch (error) {
+    checks.push({ layer: "local-filesystem", ok: false, error_class: classifyOperationalError(error) });
+  } finally {
+    await rm(probe, { force: true }).catch(() => {});
+  }
+
+  if (policy.execMode === "direct" || policy.execMode === "shell") {
+    const direct = await runProcess(
+      process.execPath,
+      ["-e", "process.stdout.write('ok')"],
+      5000,
+      true,
+      1024,
+      context,
+      workspace,
+    ).catch((error) => ({ code: 127, stdout: "", stderr: "", error_class: classifyOperationalError(error) }));
+    checks.push({
+      layer: "local-process-spawn",
+      ok: direct.code === 0 && direct.stdout === "ok",
+      error_class: direct.error_class || (direct.code === 0 ? null : classifyOperationalError(direct.stderr || direct.stdout || "execution failed")),
+    });
+  } else {
+    checks.push({ layer: "local-process-spawn", ok: false, skipped: true, error_class: "policy_denied" });
+  }
+
+  if (policy.execMode === "shell") {
+    const result = await probeShell(context)
+      .catch((error) => ({ code: 127, error_class: classifyOperationalError(error) }));
+    checks.push({
+      layer: "local-shell",
+      ok: result.code === 0,
+      error_class: result.error_class || (result.code === 0 ? null : classifyOperationalError(result.stderr || result.stdout || "execution failed")),
+    });
+  } else {
+    checks.push({ layer: "local-shell", ok: false, skipped: true, error_class: "policy_denied" });
+  }
+
+  checks.push({ layer: "managed-job-storage", ...managedJobManager.diagnoseStorage() });
+  const resources = managedJobManager.listResources();
+  checks.push({
+    layer: "local-resource-registry",
+    ok: resources.resources.every((resource) => resource.available),
+    registered: resources.count,
+    unavailable: resources.resources
+      .filter((resource) => !resource.available)
+      .map((resource) => ({ name: resource.name, error_class: resource.error_class })),
+  });
+
+  return {
+    request_reached_local_runtime: true,
+    interpretation: {
+      tool_call_blocked_before_response: "host/platform or connector gateway",
+      diagnostic_reached_daemon_but_spawn_failed: "local OS, endpoint security, shell configuration, or Machine Bridge policy",
+      managed_job_accepted_then_later_tools_blocked: "job continues independently; inspect with local CLI or a later read_job call",
+    },
+    policy,
+    checks,
+    ok: checks.filter((check) => !check.skipped).every((check) => check.ok),
+  };
+}

package/src/local/runtime-reporting.mjs

@@ -0,0 +1,113 @@
+import { basename } from "node:path";
+import {
+  allToolNames, isCanonicalFullPolicy, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS,
+  POLICY_PROFILES, SERVER_NAME,
+} from "./tools.mjs";
+
+export function buildRuntimeInfo({
+  workspace,
+  displayPath,
+  policy,
+  toolNames,
+  capabilityObserver,
+  observability,
+  callRegistry,
+  lifecycle,
+  relayStatus,
+  runtimeDir,
+  processTracker,
+  processSessionManager,
+  managedJobManager,
+}) {
+  return {
+    name: SERVER_NAME,
+    protocol_version: MCP_PROTOCOL_VERSION,
+    supported_protocol_versions: MCP_SUPPORTED_PROTOCOL_VERSIONS,
+    workspace: displayPath(workspace),
+    workspace_name: policy.exposeAbsolutePaths ? basename(workspace) : "workspace",
+    policy,
+    policy_contract: {
+      named_profile_is_canonical: policy.profile === "custom" || policyMatchesNamedProfile(policy),
+      full_catalog_complete: policy.profile === "full"
+        ? isCanonicalFullPolicy(policy) && toolNames.length + 1 === allToolNames().length
+        : null,
+      machine_bridge_internal_denials_under_full: policy.profile === "full" && isCanonicalFullPolicy(policy) ? false : null,
+    },
+    enforcement: {
+      filesystem_scope: policy.unrestrictedPaths ? "local-user-accessible" : "workspace",
+      sensitive_filename_filter: false,
+      operating_system_permissions_apply: true,
+      host_policy_is_independent: true,
+    },
+    tool_delivery: {
+      full_profile_scope: "local-daemon-and-relay-advertisement",
+      daemon_advertised_tool_count: toolNames.length + 1,
+      host_exposed_tools_known_to_server: false,
+      host_may_expose_subset: true,
+    },
+    tools: ["server_info", ...toolNames],
+    observability: {
+      relay_readiness: "authenticated-hello-acknowledged",
+      brief_relay_interruptions: "debug-only",
+      raw_transport_details: "debug-only",
+      per_tool_events: "structured-debug-events",
+      default_logs_include_tool_failures: false,
+      tool_arguments_or_results_logged: false,
+      capability_routing: capabilityObserver.snapshot(),
+      tool_calls: observability.snapshot(),
+      in_flight_calls: callRegistry.snapshot(),
+    },
+    runtime: {
+      environment: policy.minimalEnv ? "isolated-minimal" : "full-parent",
+      lifecycle: lifecycle.snapshot(),
+      relay: relayStatus(),
+      runtime_dir: policy.exposeAbsolutePaths ? runtimeDir : "<private-runtime-dir>",
+      processes: processTracker.snapshot(),
+      process_sessions: processSessionManager.status(),
+      managed_jobs: managedJobManager.status(),
+      local_resources: managedJobManager.resourceInfo(),
+    },
+  };
+}
+
+export async function buildProjectOverview({
+  workspace,
+  displayPath,
+  policy,
+  toolNames,
+  capabilityObserver,
+  listTopLevel,
+  runProcess,
+  safeErrorMessage,
+  throwIfCancelled,
+}, context = {}) {
+  throwIfCancelled(context);
+  const top = await listTopLevel(context).catch((error) => ({ error: safeErrorMessage(error), entries: [] }));
+  const git = await runProcess(
+    "git",
+    ["-c", "core.fsmonitor=false", "-C", workspace, "rev-parse", "--show-toplevel"],
+    10_000,
+    true,
+    512 * 1024,
+    context,
+  );
+  return {
+    workspace: displayPath(workspace),
+    workspaceName: policy.exposeAbsolutePaths ? basename(workspace) : "workspace",
+    gitRoot: git.code === 0 ? displayPath(git.stdout.trim()) : "",
+    policy,
+    tools: ["server_info", ...toolNames],
+    capabilityRouting: capabilityObserver.snapshot(),
+    topLevel: top.entries || [],
+  };
+}
+
+function policyMatchesNamedProfile(policy) {
+  const named = POLICY_PROFILES[policy.profile];
+  if (!named) return false;
+  return policy.allowWrite === named.allowWrite
+    && policy.execMode === named.execMode
+    && policy.unrestrictedPaths === named.unrestrictedPaths
+    && policy.minimalEnv === named.minimalEnv
+    && policy.exposeAbsolutePaths === named.exposeAbsolutePaths;
+}