machine-bridge-mcp 0.8.1 → 0.9.0

package/src/local/cli.mjs

@@ -337,6 +337,10 @@ async function prepareStartMode(args, state, logger) {
 
 function reportExistingDaemon(args, state, owner, logger) {
   const pid = owner?.pid ? `pid ${owner.pid}` : "unknown pid";
+  if (isIdempotentDaemonOnlyStart(args)) {
+    logger.debug?.("local daemon already running; daemon-only start completed as an idempotent no-op", { owner_pid_known: Boolean(owner?.pid) });
+    return;
+  }
   logger.warn(`local daemon already running for this workspace (${pid}); requested changes were not applied`);
   if (args.json) {
     printStartJson(state, {
@@ -354,6 +358,24 @@ function reportExistingDaemon(args, state, owner, logger) {
   });
 }
 
+function isIdempotentDaemonOnlyStart(args) {
+  if (!args.daemonOnly || args.json) return false;
+  return !Boolean(
+    args.profile
+    || args.execMode
+    || args.rotateSecrets
+    || args.forceWorker
+    || args.workerName
+    || args.noWrite
+    || args.noExec
+    || args.fullEnv
+    || args.unrestrictedPaths
+    || args.absolutePaths
+    || args.printMcpCredentials
+    || args.printCredentials
+  );
+}
+
 async function startRemoteRuntime({ args, workspace, state, daemonLock, logger }) {
   let runtime = null;
   try {

package/src/local/relay-connection.mjs

@@ -3,10 +3,13 @@ import { classifyOperationalError } from "./log.mjs";
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 const DEFAULT_OUTAGE_WARN_AFTER_MS = 10_000;
 const DEFAULT_OUTAGE_WARN_REPEAT_MS = 60_000;
+const DEFAULT_OUTAGE_WARN_MAX_REPEAT_MS = 15 * 60_000;
 const MAX_CLOSE_REASON_CHARS = 128;
+const MAX_PROTOCOL_ERROR_CODE_CHARS = 64;
 
 const DEFAULT_SCHEDULER = Object.freeze({
   setTimeout: (callback, delay) => setTimeout(callback, delay),
@@ -35,9 +38,14 @@ export class RelayConnection {
     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);
+    this.connectTimeoutMs = boundedPositiveInteger(options.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
     this.handshakeTimeoutMs = boundedPositiveInteger(options.handshakeTimeoutMs, DEFAULT_HANDSHAKE_TIMEOUT_MS);
     this.outageWarnAfterMs = boundedPositiveInteger(options.outageWarnAfterMs, DEFAULT_OUTAGE_WARN_AFTER_MS);
     this.outageWarnRepeatMs = boundedPositiveInteger(options.outageWarnRepeatMs, DEFAULT_OUTAGE_WARN_REPEAT_MS);
+    this.outageWarnMaxRepeatMs = Math.max(
+      this.outageWarnRepeatMs,
+      boundedPositiveInteger(options.outageWarnMaxRepeatMs, DEFAULT_OUTAGE_WARN_MAX_REPEAT_MS),
+    );
 
     this.closed = true;
     this.socket = null;
@@ -47,12 +55,14 @@ export class RelayConnection {
     this.lastInboundAt = 0;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
+    this.connectTimer = null;
     this.heartbeatTimer = null;
     this.handshakeTimer = null;
     this.outageWarnTimer = null;
     this.outageStartedAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
+    this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
     this.lastCloseCategory = "connection_interrupted";
     this.lastTransportErrorClass = "";
@@ -77,6 +87,7 @@ export class RelayConnection {
     this.closed = true;
     this.ready = false;
     this.clearTimer("heartbeatTimer", "clearInterval");
+    this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
     this.clearTimer("outageWarnTimer", "clearTimeout");
@@ -128,7 +139,8 @@ export class RelayConnection {
     } else if (this.outageStartedAt > 0) {
       const outageMs = Math.max(0, this.connectedAt - this.outageStartedAt);
       if (this.outageNoticeEmitted) {
-        this.logger.info?.("remote relay connection restored", {
+        this.logger.info?.(`remote relay connection restored after ${formatDuration(outageMs)} (${formatAttempts(this.outageAttempts)})`);
+        this.logger.debug?.("remote relay outage recovery details", {
           outage_seconds: roundSeconds(outageMs),
           attempts: this.outageAttempts,
         });
@@ -150,6 +162,20 @@ export class RelayConnection {
     return true;
   }
 
+  handleServerError(message = {}) {
+    const errorCode = sanitizeProtocolErrorCode(message?.error);
+    this.logger.debug?.("remote relay reported a protocol error", { error_code: errorCode });
+    if (errorCode === "daemon_hello_timeout" && !this.ready) {
+      const socket = this.socket;
+      if (this.closed || !socket) return true;
+      this.pendingCloseCategory = "relay_handshake_timeout";
+      terminateSocket(socket);
+      return true;
+    }
+    this.failPermanently("relay_protocol_error");
+    return true;
+  }
+
   connect() {
     if (this.closed || this.socket) return;
     const wsUrl = `${this.workerUrl.replace(/^http/i, "ws")}/daemon/ws`;
@@ -167,8 +193,17 @@ export class RelayConnection {
       return;
     }
     this.socket = socket;
+    this.clearTimer("connectTimer", "clearTimeout");
+    this.connectTimer = this.scheduler.setTimeout(() => {
+      if (this.socket !== socket || this.closed || this.isSocketOpen(socket)) return;
+      this.logger.debug?.("remote relay transport connection timed out", { timeout_ms: this.connectTimeoutMs });
+      this.pendingCloseCategory = "relay_connect_timeout";
+      terminateSocket(socket);
+    }, this.connectTimeoutMs);
+    this.connectTimer?.unref?.();
 
     socket.on("open", () => {
+      this.clearTimer("connectTimer", "clearTimeout");
       if (this.socket !== socket || this.closed) {
         try { socket.close(1000, "stale daemon connection"); } catch {}
         return;
@@ -204,6 +239,7 @@ export class RelayConnection {
       const wasReady = this.ready;
       this.socket = null;
       this.ready = false;
+      this.clearTimer("connectTimer", "clearTimeout");
       this.clearTimer("heartbeatTimer", "clearInterval");
       this.clearTimer("handshakeTimer", "clearTimeout");
       const reasonText = sanitizeCloseReason(reason);
@@ -265,6 +301,7 @@ export class RelayConnection {
     this.closed = true;
     this.ready = false;
     this.socket = null;
+    this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("heartbeatTimer", "clearInterval");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
@@ -286,7 +323,8 @@ export class RelayConnection {
       reject(error);
       return;
     }
-    this.logger.error?.(message, { cause: relayCloseUserCause(category) });
+    this.logger.error?.(message);
+    this.logger.debug?.("remote relay fatal details", { category, cause: relayCloseUserCause(category) });
     queueMicrotask(() => {
       try { this.onFatal(error); } catch (callbackError) {
         this.logger.error?.("relay fatal callback failed", { error_class: classifyOperationalError(callbackError) });
@@ -299,7 +337,6 @@ export class RelayConnection {
     this.recordOutage(category);
     const delay = this.reconnectDelay(this.reconnectAttempt++);
     this.scheduleOutageWarning();
-    this.maybeRepeatOutageWarning();
     this.logger.debug?.("scheduling daemon reconnect", { delay_ms: delay, attempt: this.outageAttempts });
     this.reconnectTimer = this.scheduler.setTimeout(() => {
       this.reconnectTimer = null;
@@ -352,31 +389,39 @@ export class RelayConnection {
   }
 
   scheduleOutageWarning() {
-    if (this.outageNoticeEmitted || this.outageWarnTimer || this.outageStartedAt === 0) return;
-    const elapsed = Math.max(0, this.now() - this.outageStartedAt);
-    const delay = Math.max(0, this.outageWarnAfterMs - elapsed);
+    if (this.outageWarnTimer || this.outageStartedAt === 0 || this.closed || this.ready) return;
+    const dueAt = this.outageNoticeEmitted
+      ? this.lastOutageWarnAt + this.nextOutageWarningDelay()
+      : this.outageStartedAt + this.outageWarnAfterMs;
+    const delay = Math.max(0, dueAt - this.now());
     this.outageWarnTimer = this.scheduler.setTimeout(() => {
       this.outageWarnTimer = null;
       if (this.closed || this.ready || this.outageStartedAt === 0) return;
       this.emitOutageWarning();
+      this.scheduleOutageWarning();
     }, delay);
     this.outageWarnTimer?.unref?.();
   }
 
-  maybeRepeatOutageWarning() {
-    if (!this.outageNoticeEmitted || this.lastOutageWarnAt === 0) return;
-    if (this.now() - this.lastOutageWarnAt < this.outageWarnRepeatMs) return;
-    this.emitOutageWarning();
+  nextOutageWarningDelay() {
+    const exponent = Math.max(0, Math.min(this.outageWarningCount - 1, 20));
+    return Math.min(this.outageWarnRepeatMs * (2 ** exponent), this.outageWarnMaxRepeatMs);
   }
 
   emitOutageWarning() {
     const outageMs = Math.max(0, this.now() - this.outageStartedAt);
     this.outageNoticeEmitted = true;
+    this.outageWarningCount += 1;
     this.lastOutageWarnAt = this.now();
-    this.logger.warn?.(relayOutageWarningMessage(), {
+    const cause = relayCloseUserCause(this.lastCloseCategory);
+    const action = outageMs >= 5 * 60_000
+      ? " If this persists, check internet access and the deployed Worker."
+      : "";
+    this.logger.warn?.(`remote relay unavailable for ${formatDuration(outageMs)}; reconnecting automatically (${formatAttempts(this.outageAttempts)}; ${cause}).${action}`);
+    this.logger.debug?.("remote relay outage details", {
       outage_seconds: roundSeconds(outageMs),
       attempts: this.outageAttempts,
-      cause: relayCloseUserCause(this.lastCloseCategory),
+      cause,
       ...(this.lastTransportErrorClass ? { error_class: this.lastTransportErrorClass } : {}),
     });
   }
@@ -386,6 +431,7 @@ export class RelayConnection {
     this.outageStartedAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
+    this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
     this.lastCloseCategory = "connection_interrupted";
     this.lastTransportErrorClass = "";
@@ -406,10 +452,15 @@ export class RelayConnection {
 
 export function relayCloseCategory(code, reason = "") {
   const numeric = Number(code);
-  if (isSupersededClose(numeric, reason)) return "superseded";
+  const reasonText = String(reason || "");
+  if (isSupersededClose(numeric, reasonText)) return "superseded";
+  if (numeric === 1008 && reasonText === "daemon hello timeout") return "relay_handshake_timeout";
+  if (numeric === 1008 && ["stale daemon candidate", "expired daemon candidate"].includes(reasonText)) return "relay_restarting_or_unavailable";
+  if (numeric === 1008 && ["daemon hello required", "missing daemon attachment", "invalid daemon candidate timestamp"].includes(reasonText)) return "relay_protocol_error";
   if (numeric === 1000) return "normal_close";
   if (numeric === 1001 || numeric === 1012 || numeric === 1013) return "relay_restarting_or_unavailable";
   if (numeric === 1006) return "connection_interrupted";
+  if (numeric === 1002) return "relay_protocol_error";
   if (numeric === 1007) return "invalid_transport_payload";
   if (numeric === 1008) return "relay_policy_rejected";
   if (numeric === 1009) return "message_too_large";
@@ -421,13 +472,12 @@ function relayFatalMessage(category) {
   if (category === "relay_protocol_mismatch") {
     return "remote relay identity or version does not match this daemon; upgrade and redeploy both components";
   }
+  if (category === "relay_protocol_error") {
+    return "remote relay protocol error; upgrade and redeploy both components, then restart the daemon";
+  }
   return "remote relay rejected the daemon connection; verify credentials or redeploy the Worker";
 }
 
-function relayOutageWarningMessage() {
-  return "remote relay is unavailable; automatic reconnection is still in progress";
-}
-
 function relayCloseUserCause(category) {
   const causes = {
     connection_interrupted: "connection interrupted",
@@ -436,9 +486,11 @@ function relayCloseUserCause(category) {
     relay_internal_error: "relay internal error",
     relay_protocol_mismatch: "relay identity or version mismatch",
     relay_authentication_failed: "relay authentication failed",
+    relay_connect_timeout: "relay connection attempt timed out",
     relay_handshake_timeout: "relay authentication acknowledgement timed out",
     relay_heartbeat_timeout: "relay stopped responding",
     relay_transport_error: "relay transport error",
+    relay_protocol_error: "relay protocol error",
     invalid_transport_payload: "invalid transport payload",
     message_too_large: "message exceeded the relay limit",
     normal_close: "connection closed",
@@ -512,6 +564,37 @@ function boundedPositiveInteger(value, fallback) {
   return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
 }
 
+function sanitizeProtocolErrorCode(value) {
+  const code = String(value || "unknown_error").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_PROTOCOL_ERROR_CODE_CHARS);
+  return code || "unknown_error";
+}
+
+function formatAttempts(value) {
+  const attempts = Math.max(1, Math.floor(Number(value) || 1));
+  return `${attempts} reconnect attempt${attempts === 1 ? "" : "s"}`;
+}
+
+function formatDuration(milliseconds) {
+  let seconds = Math.max(1, Math.round(Number(milliseconds) / 1000));
+  const units = [
+    ["day", 86_400],
+    ["hour", 3_600],
+    ["minute", 60],
+    ["second", 1],
+  ];
+  const parts = [];
+  for (const [label, size] of units) {
+    if (seconds < size && parts.length === 0) continue;
+    const amount = Math.floor(seconds / size);
+    if (amount > 0) {
+      parts.push(`${amount} ${label}${amount === 1 ? "" : "s"}`);
+      seconds -= amount * size;
+    }
+    if (parts.length === 2) break;
+  }
+  return parts.join(" ") || "1 second";
+}
+
 function roundSeconds(milliseconds) {
   return Math.max(1, Math.round(milliseconds / 1000));
 }

package/src/local/runtime.mjs

@@ -14,6 +14,7 @@ import { classifyOperationalError } from "./log.mjs";
 import { ManagedJobManager } from "./managed-jobs.mjs";
 import { generateRegisteredSshKey } from "./resource-operations.mjs";
 import { expandHome } from "./state.mjs";
+import { AgentContextManager } from "./agent-context.mjs";
 
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
 const MAX_WS_MESSAGE_BYTES = 8 * 1024 * 1024;
@@ -27,6 +28,11 @@ const SLOW_TOOL_CALL_MS = 30_000;
 const RUNTIME_TOOL_HANDLERS = Object.freeze({
   server_info: (runtime) => runtime.runtimeInfo(),
   project_overview: (runtime, _args, context) => runtime.projectOverview(context),
+  agent_context: (runtime, args, context) => runtime.agentContextManager.agentContext(args, context),
+  list_local_skills: (runtime, args, context) => runtime.agentContextManager.listLocalSkills(args, context),
+  load_local_skill: (runtime, args, context) => runtime.agentContextManager.loadLocalSkill(args, context),
+  list_local_commands: (runtime, args, context) => runtime.agentContextManager.listLocalCommands(args, context),
+  run_local_command: (runtime, args, context) => runtime.runLocalCommand(args, context),
   list_roots: (runtime) => runtime.listRoots(),
   list_dir: (runtime, args, context) => runtime.listDir(args.path || ".", context),
   list_files: (runtime, args, context) => runtime.listFiles(args.path || ".", clampInt(args.max_files, 1000, 1, 10000), context),
@@ -101,6 +107,13 @@ export class LocalRuntime {
       displayPath: (value) => this.displayPath(value),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
     });
+    this.agentContextManager = new AgentContextManager({
+      workspace: this.workspace,
+      policy: this.policy,
+      displayPath: (value) => this.displayPath(value),
+      resolveExistingPath: (value) => this.resolveExistingPath(value),
+      throwIfCancelled: (context) => this.throwIfCancelled(context),
+    });
     this.relay = createRelayConnection(this, {
       workerUrl: remoteWorkerUrl,
       secret: remoteSecret,
@@ -176,12 +189,16 @@ export class LocalRuntime {
   async handleMessage(raw) {
     let message;
     try { message = JSON.parse(raw); } catch {
-      this.logger.warn?.("invalid websocket JSON");
+      this.handleRelayProtocolViolation("invalid_server_json");
+      return;
+    }
+    if (!isPlainRecord(message)) {
+      this.handleRelayProtocolViolation("invalid_server_message");
       return;
     }
     if (this.handleRelayControlMessage(message)) return;
     if (message.type !== "tool_call") {
-      this.logger.warn?.("unknown websocket message", { type: String(message.type || "") });
+      this.handleRelayProtocolViolation("unexpected_server_message_type");
       return;
     }
     await this.handleRelayToolCall(message);
@@ -197,6 +214,10 @@ export class LocalRuntime {
       return true;
     }
     if (message.type === "pong") return true;
+    if (message.type === "error") {
+      this.relay?.handleServerError(message);
+      return true;
+    }
     if (message.type === "cancel_call") {
       if (typeof message.id === "string") this.cancelCall(message.id, "remote cancellation");
       return true;
@@ -204,6 +225,14 @@ export class LocalRuntime {
     return false;
   }
 
+  handleRelayProtocolViolation(errorCode) {
+    if (this.relay) {
+      this.relay.handleServerError({ type: "error", error: errorCode });
+      return;
+    }
+    this.logger.error?.("remote relay protocol error; upgrade and redeploy both components, then restart the daemon");
+  }
+
   async handleRelayToolCall(message) {
     const envelope = normalizeRelayToolCall(message);
     if (!envelope.ok) {
@@ -717,6 +746,25 @@ export class LocalRuntime {
     return this.runProcess(argv[0], argv.slice(1), clampInt(args.timeout_seconds, 120, 1, 600) * 1000, false, 512 * 1024, context, cwd);
   }
 
+  async runLocalCommand(args, context = {}) {
+    if (this.policy.execMode !== "direct" && this.policy.execMode !== "shell") throw new Error("run_local_command is disabled by daemon policy");
+    const command = await this.agentContextManager.resolveLocalCommand(args, context);
+    const argv = validateArgv(command.argv);
+    const cwd = await this.resolveExistingPath(command.cwd);
+    if (!(await stat(cwd)).isDirectory()) throw new Error("registered command cwd is not a directory");
+    const requestedTimeout = args.timeout_seconds === undefined
+      ? command.timeoutSeconds
+      : clampInt(args.timeout_seconds, command.timeoutSeconds, 1, 600);
+    const timeoutSeconds = Math.min(requestedTimeout, command.timeoutSeconds);
+    const result = await this.runProcess(argv[0], argv.slice(1), timeoutSeconds * 1000, false, 512 * 1024, context, cwd);
+    return {
+      name: command.name,
+      cwd: this.displayPath(cwd),
+      timeout_seconds: timeoutSeconds,
+      ...result,
+    };
+  }
+
   async execCommand(command, timeoutSeconds, context = {}) {
     if (this.policy.execMode !== "shell") throw new Error("exec_command requires shell execution mode");
     if (!command || typeof command !== "string") throw new Error("command is required");
@@ -1154,7 +1202,7 @@ function createRelayConnection(runtime, { workerUrl, secret, expectedVersion, on
 function handleRelayData(runtime, data) {
   const raw = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
   if (Buffer.byteLength(raw) > MAX_WS_MESSAGE_BYTES) {
-    runtime.logger.warn?.("oversized websocket message rejected");
+    runtime.handleRelayProtocolViolation("server_message_too_large");
     return;
   }
   return runtime.handleMessage(raw);

package/src/local/service.mjs

@@ -9,7 +9,7 @@ import { readBoundedRegularFileSync } from "./secure-file.mjs";
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const WINDOWS_TASK = "MachineBridgeMCP";
 const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
-const AUTOSTART_LOG_SCHEMA_VERSION = 2;
+const AUTOSTART_LOG_SCHEMA_VERSION = 3;
 
 function serviceRun(command, args) {
   return run(command, args, {

package/src/shared/server-metadata.json

@@ -8,6 +8,7 @@
   ],
   "instructions": [
     "You are connected to a local workspace through machine-bridge-mcp.",
+    "For substantive workspace tasks, call agent_context for the relevant target path before editing or executing. Apply returned instruction files in precedence order, load only relevant local skills, and prefer registered local commands for repeatable workflows.",
     "Remote mode uses a Cloudflare relay; stdio mode runs on the local machine. File and command operations execute on the user's local runtime, not in the Worker.",
     "Filesystem scope and path display follow the active local policy; the default full profile is unrestricted.",
     "Filename sensitivity is not classified by this server; the MCP host, connector gateway, local OS, or endpoint-security software may enforce additional independent rules.",

package/src/shared/tool-catalog.json

@@ -31,6 +31,178 @@
       "additionalProperties": false
     }
   },
+  {
+    "name": "agent_context",
+    "title": "Load agent context",
+    "description": "Discover Codex-compatible global and root-to-target instruction precedence, progressively disclosed local skills, and registered commands for a target path.",
+    "availability": "always",
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    },
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "default": ".",
+          "maxLength": 32768
+        },
+        "include_instruction_content": {
+          "type": "boolean",
+          "default": true
+        },
+        "max_skills": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500,
+          "default": 100
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "list_local_skills",
+    "title": "List local skills",
+    "description": "Search bounded SKILL.md or skill.md bundles from Codex-compatible and explicitly configured skill roots without executing them.",
+    "availability": "always",
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    },
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "default": ".",
+          "maxLength": 32768
+        },
+        "query": {
+          "type": "string",
+          "default": "",
+          "maxLength": 1000
+        },
+        "max_results": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500,
+          "default": 100
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "load_local_skill",
+    "title": "Load local skill",
+    "description": "Load one discovered local skill entrypoint and a bounded relative file inventory. Loading returns instructions and never executes skill files implicitly.",
+    "availability": "always",
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    },
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "skill": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32768
+        },
+        "path": {
+          "type": "string",
+          "default": ".",
+          "maxLength": 32768
+        },
+        "max_files": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500,
+          "default": 200
+        }
+      },
+      "required": [
+        "skill"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "list_local_commands",
+    "title": "List registered local commands",
+    "description": "List commands registered by hierarchical .machine-bridge/agent.json manifests for the selected target path.",
+    "availability": "always",
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    },
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "default": ".",
+          "maxLength": 32768
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "run_local_command",
+    "title": "Run registered local command",
+    "description": "Execute a named command registered in .machine-bridge/agent.json as a direct argv process without shell parsing. Manifest timeout and argument policy remain authoritative.",
+    "availability": "direct-exec",
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": false,
+      "openWorldHint": true
+    },
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "path": {
+          "type": "string",
+          "default": ".",
+          "maxLength": 32768
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 65536
+          },
+          "maxItems": 64,
+          "default": []
+        },
+        "timeout_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 600
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "list_roots",
     "title": "List workspace roots",