u-foo 3.0.18 → 3.0.19

package/src/runtime/daemon/mcpServer.js

@@ -7,7 +7,10 @@ const { spawn } = require("child_process");
 
 const { getUfooPaths } = require("../../coordination/state/paths");
 const { isRunning, socketPath } = require("./index");
-const controlPlane = require("./controlPlaneService");
+const {
+  MCP_EXPOSED_SHARED_TOOLS,
+  createLocalProjectRuntimeGateway,
+} = require("./projectRuntimeGateway");
 const {
   normalizeProjectRoot,
   resolveGlobalControllerProjectRoot,
@@ -30,15 +33,8 @@ const {
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
 
-const EXPOSED_SHARED_TOOLS = Object.freeze([
-  "read_project_registry",
-  "read_bus_summary",
-  "read_prompt_history",
-  "read_open_decisions",
-  "list_agents",
-  "dispatch_message",
-  "ack_bus",
-]);
+const EXPOSED_SHARED_TOOLS = MCP_EXPOSED_SHARED_TOOLS;
+const DEFAULT_PROJECT_RUNTIME_GATEWAY = createLocalProjectRuntimeGateway();
 
 const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
   {
@@ -65,6 +61,10 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
         scoped_nickname: { type: "string" },
         launch_mode: { type: "string" },
         capabilities: { type: "object", additionalProperties: true },
+        client_instance_id: {
+          type: "string",
+          description: "Stable host-local instance id used to recover the same registration after transport restarts.",
+        },
       },
       additionalProperties: false,
     },
@@ -75,10 +75,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Refresh a registered agent heartbeat in its project bus.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber"],
+      required: ["project_root", "subscriber", "agent_handle"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
       },
       additionalProperties: false,
     },
@@ -89,10 +90,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Publish the caller agent activity state in its project bus metadata.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber", "activity_state"],
+      required: ["project_root", "subscriber", "agent_handle", "activity_state"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
         activity_state: { type: "string" },
         detail: { type: "string" },
         since: { type: "string" },
@@ -106,10 +108,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Update the caller agent nickname or MCP metadata in its project bus.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber"],
+      required: ["project_root", "subscriber", "agent_handle"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
         nickname: { type: "string" },
         metadata: { type: "object", additionalProperties: true },
       },
@@ -122,10 +125,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Read pending bus messages for the caller-owned subscriber queue without acknowledging them.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber"],
+      required: ["project_root", "subscriber", "agent_handle"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
         limit: { type: "integer", minimum: 1 },
       },
       additionalProperties: false,
@@ -137,10 +141,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Keep a Codex App-compatible MCP tool call pending until the caller-owned bus queue receives messages after after_seq or the wait reaches its timeout.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber"],
+      required: ["project_root", "subscriber", "agent_handle"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
         after_seq: {
           type: "integer",
           minimum: 0,
@@ -165,10 +170,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Queue an agent task status report through the project daemon report-control queue.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber", "task_id", "phase"],
+      required: ["project_root", "subscriber", "agent_handle", "task_id", "phase"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
         task_id: { type: "string" },
         phase: { type: "string", enum: ["start", "progress", "done", "error"] },
         message: { type: "string" },
@@ -186,10 +192,11 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     description: "Mark an MCP-registered agent inactive in its project bus.",
     input_schema: {
       type: "object",
-      required: ["project_root", "subscriber"],
+      required: ["project_root", "subscriber", "agent_handle"],
       properties: {
         project_root: { type: "string" },
         subscriber: { type: "string" },
+        agent_handle: { type: "string" },
       },
       additionalProperties: false,
     },
@@ -212,11 +219,16 @@ function withProjectRootSchema(schema, options = {}) {
       type: "string",
       description: "Caller-owned subscriber id returned by register_agent.",
     },
+    agent_handle: {
+      type: "string",
+      description: "Opaque ownership capability returned by register_agent.",
+    },
     ...(cloned.properties || {}),
   };
   const required = Array.isArray(cloned.required) ? cloned.required.slice() : [];
   if (!required.includes("project_root")) required.unshift("project_root");
   if (options.requireSubscriber && !required.includes("subscriber")) required.push("subscriber");
+  if (options.requireAgentHandle && !required.includes("agent_handle")) required.push("agent_handle");
   cloned.properties = properties;
   cloned.required = required;
   cloned.additionalProperties = false;
@@ -227,6 +239,7 @@ function toMcpTool(definition, options = {}) {
   const inputSchema = options.projectScoped
     ? withProjectRootSchema(definition.input_schema, {
       requireSubscriber: options.requireSubscriber,
+      requireAgentHandle: options.requireAgentHandle,
     })
     : cloneJson(definition.input_schema);
   return {
@@ -243,6 +256,7 @@ function buildToolList() {
     .map((tool) => toMcpTool(tool, {
       projectScoped: tool.name !== "read_project_registry",
       requireSubscriber: tool.name === "dispatch_message" || tool.name === "ack_bus",
+      requireAgentHandle: tool.name === "dispatch_message" || tool.name === "ack_bus",
     }));
   const custom = CUSTOM_TOOL_DEFINITIONS.map((tool) => toMcpTool(tool));
   return [...custom, ...shared];
@@ -265,6 +279,8 @@ function stripMcpRoutingArgs(args = {}) {
   delete next.project_root;
   delete next.projectRoot;
   delete next.subscriber;
+  delete next.agent_handle;
+  delete next.agentHandle;
   return next;
 }
 
@@ -408,12 +424,50 @@ async function ensureGlobalControllerDaemon(options = {}) {
 async function handleMcpStatus(ctx = {}) {
   const root = resolveGlobalControllerProjectRoot();
   const projects = listRegisteredProjectRows();
+  let http = null;
+  if (typeof ctx.getMcpHttpStatus === "function") {
+    http = ctx.getMcpHttpStatus();
+  } else {
+    try {
+      const endpointPath = getUfooPaths(root).mcpEndpoint;
+      http = JSON.parse(fs.readFileSync(endpointPath, "utf8"));
+      const pidRunning = Number(http.pid) > 0 && (() => {
+        try {
+          process.kill(Number(http.pid), 0);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      let healthRunning = false;
+      if (pidRunning && http.endpoint && typeof fetch === "function") {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 500);
+        if (typeof timer.unref === "function") timer.unref();
+        try {
+          const healthUrl = new URL(http.endpoint);
+          healthUrl.pathname = "/health";
+          healthUrl.search = "";
+          const response = await fetch(healthUrl, { signal: controller.signal });
+          healthRunning = response.ok;
+        } catch {
+          healthRunning = false;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+      http.running = pidRunning && healthRunning;
+    } catch {
+      http = { running: false };
+    }
+  }
   return {
     ok: true,
     global_controller_root: root,
     global_controller_sock: socketPath(root),
     global_controller_running: isRunning(root),
     auto_start: ctx.autoStart !== false,
+    http,
     project_count: projects.length,
     projects,
   };
@@ -421,48 +475,42 @@ async function handleMcpStatus(ctx = {}) {
 
 async function handleRegisterAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.registerAgent(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "register_agent", args, ctx);
 }
 
 async function handleHeartbeatAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.heartbeatAgent(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "heartbeat_agent", args, ctx);
 }
 
 async function handlePublishActivityState(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.publishActivityState(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "publish_activity_state", args, ctx);
 }
 
 async function handleUpdateAgentMetadata(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.updateAgentMetadata(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "update_agent_metadata", args, ctx);
 }
 
 async function handlePollInbox(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.pollInbox(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "poll_inbox", args, ctx);
 }
 
 async function handleWaitForMessage(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.waitForMessage(projectRoot, args, {
-    signal: ctx.signal,
-    pollIntervalMs: ctx.waitPollIntervalMs,
-    heartbeatIntervalMs: ctx.waitHeartbeatIntervalMs,
-    now: ctx.waitNow,
-    sleep: ctx.waitSleep,
-  });
+  return ctx.projectRuntimeGateway.call(projectRoot, "wait_for_message", args, ctx);
 }
 
 async function handleReportAgentStatus(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.reportAgentStatus(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "report_agent_status", args, ctx);
 }
 
 async function handleUnregisterAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  return controlPlane.unregisterAgent(projectRoot, args);
+  return ctx.projectRuntimeGateway.call(projectRoot, "unregister_agent", args, ctx);
 }
 
 function findCustomTool(name) {
@@ -481,23 +529,19 @@ async function invokeTool(name, args = {}, ctx = {}) {
     throw err;
   }
 
+  if (name !== "read_project_registry") {
+    const projectRoot = resolveRegisteredProjectRoot(args, ctx);
+    return ctx.projectRuntimeGateway.call(projectRoot, name, args, ctx);
+  }
+
   const tool = assertToolAllowedForCallerTier(name, CALLER_TIERS.WORKER, {
     tool_call_id: ctx.toolCallId,
   });
-  const projectRoot = name === "read_project_registry"
-    ? resolveGlobalControllerProjectRoot()
-    : resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = String(args.subscriber || args.source || "").trim();
-  const toolArgs = stripMcpRoutingArgs(args);
-  if (name === "dispatch_message" && !toolArgs.source && subscriber) {
-    toolArgs.source = subscriber;
-  }
-  const toolCtx = {
-    projectRoot,
-    subscriber,
+  return tool.handler({
+    projectRoot: resolveGlobalControllerProjectRoot(),
+    subscriber: "",
     caller_tier: CALLER_TIERS.WORKER,
-  };
-  return tool.handler(toolCtx, toolArgs);
+  }, stripMcpRoutingArgs(args));
 }
 
 class UfooMcpServer {
@@ -510,10 +554,10 @@ class UfooMcpServer {
       waitHeartbeatIntervalMs: options.waitHeartbeatIntervalMs,
       waitNow: options.waitNow,
       waitSleep: options.waitSleep,
+      projectRuntimeGateway: options.projectRuntimeGateway || DEFAULT_PROJECT_RUNTIME_GATEWAY,
     };
     this.initialized = false;
     this.startup = null;
-    this.registeredSubscribers = [];
     this.activeToolCalls = new Map();
   }
 
@@ -607,17 +651,6 @@ class UfooMcpServer {
         } finally {
           this.activeToolCalls.delete(id);
         }
-        if (name === "register_agent" && result && result.subscriber && result.project_root) {
-          this.registeredSubscribers.push({
-            subscriber: result.subscriber,
-            projectRoot: result.project_root,
-          });
-        }
-        if (name === "unregister_agent" && result && result.subscriber) {
-          this.registeredSubscribers = this.registeredSubscribers.filter(
-            (entry) => entry.subscriber !== result.subscriber
-          );
-        }
         return createJsonRpcResult(id, createMcpContent(result));
       }
 
@@ -636,14 +669,6 @@ class UfooMcpServer {
       active.abort();
     }
     this.activeToolCalls.clear();
-    for (const { subscriber, projectRoot } of this.registeredSubscribers) {
-      try {
-        controlPlane.unregisterAgent(projectRoot, { subscriber });
-      } catch {
-        // best-effort cleanup
-      }
-    }
-    this.registeredSubscribers = [];
   }
 }
 
@@ -652,52 +677,18 @@ function createUfooMcpServer(options = {}) {
 }
 
 async function runMcpServer(options = {}) {
-  const input = options.input || process.stdin;
-  const output = options.output || process.stdout;
-  const server = createUfooMcpServer(options);
-  let buffer = "";
-
-  const writeMessage = (message) => {
-    if (!message) return;
-    output.write(`${JSON.stringify(message)}\n`);
-  };
-
-  input.setEncoding("utf8");
-  input.on("data", (chunk) => {
-    buffer += chunk;
-    const lines = buffer.split(/\r?\n/);
-    buffer = lines.pop() || "";
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      let request;
-      try {
-        request = JSON.parse(line);
-      } catch (err) {
-        writeMessage(createJsonRpcError(null, MCP_ERROR_CODES.PARSE_ERROR, err.message || "Parse error"));
-        continue;
-      }
-      server.handleRequest(request)
-        .then(writeMessage)
-        .catch((err) => {
-          writeMessage(createJsonRpcError(
-            Object.prototype.hasOwnProperty.call(request, "id") ? request.id : null,
-            MCP_ERROR_CODES.INTERNAL_ERROR,
-            err.message || String(err)
-          ));
-        });
-    }
+  const { runMcpStdioProxy } = require("./mcpStdioProxy");
+  return runMcpStdioProxy({
+    ...options,
+    ensureDaemon: () => ensureGlobalControllerDaemon(options),
   });
-
-  input.on("end", () => server.cleanup());
-  input.on("close", () => server.cleanup());
-
-  return server;
 }
 
 module.exports = {
   EXPOSED_SHARED_TOOLS,
   CUSTOM_TOOL_DEFINITIONS,
   buildToolList,
+  createMcpContent,
   createUfooMcpServer,
   ensureGlobalControllerDaemon,
   invokeTool,

package/src/runtime/daemon/mcpStdioProxy.js

@@ -0,0 +1,247 @@
+"use strict";
+
+const fs = require("fs");
+
+const { getUfooPaths } = require("../../coordination/state/paths");
+const {
+  resolveGlobalControllerProjectRoot,
+} = require("../projects");
+const {
+  MCP_ERROR_CODES,
+  createJsonRpcError,
+} = require("../contracts/mcpContract");
+
+const DEFAULT_ENDPOINT_WAIT_MS = 5000;
+const DEFAULT_ENDPOINT_POLL_MS = 50;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function validateEndpoint(raw = "") {
+  let parsed;
+  try {
+    parsed = new URL(String(raw || ""));
+  } catch {
+    throw new Error("Invalid global MCP endpoint");
+  }
+  if (parsed.protocol !== "http:" || !LOOPBACK_HOSTS.has(parsed.hostname) || parsed.pathname !== "/mcp") {
+    const err = new Error(`Refusing non-loopback global MCP endpoint: ${parsed.toString()}`);
+    err.code = "UFOO_MCP_INVALID_ENDPOINT";
+    throw err;
+  }
+  return parsed.toString();
+}
+
+function readConnectionFiles(projectRoot) {
+  const paths = getUfooPaths(projectRoot);
+  const endpointRecord = JSON.parse(fs.readFileSync(paths.mcpEndpoint, "utf8"));
+  const endpoint = validateEndpoint(endpointRecord.endpoint);
+  const token = String(fs.readFileSync(paths.mcpToken, "utf8") || "").trim();
+  if (!token) {
+    const err = new Error("Global MCP bearer token is empty");
+    err.code = "UFOO_MCP_EMPTY_TOKEN";
+    throw err;
+  }
+  return { endpoint, token };
+}
+
+class McpStdioProxy {
+  constructor(options = {}) {
+    this.input = options.input || process.stdin;
+    this.output = options.output || process.stdout;
+    this.errorOutput = options.errorOutput || process.stderr;
+    this.projectRoot = options.projectRoot || resolveGlobalControllerProjectRoot();
+    this.autoStart = options.autoStart !== false;
+    this.ensureDaemon = options.ensureDaemon || (async () => {});
+    this.fetch = options.fetch || globalThis.fetch;
+    this.endpoint = options.endpoint ? validateEndpoint(options.endpoint) : "";
+    this.token = String(options.token || "");
+    this.endpointWaitMs = Number(options.endpointWaitMs) || DEFAULT_ENDPOINT_WAIT_MS;
+    this.endpointPollMs = Number(options.endpointPollMs) || DEFAULT_ENDPOINT_POLL_MS;
+    this.sessionId = "";
+    this.startup = null;
+    this.initializing = null;
+    this.activeRequests = new Map();
+    this.closed = false;
+    this.buffer = "";
+  }
+
+  writeMessage(message) {
+    if (!message || this.closed) return;
+    this.output.write(`${JSON.stringify(message)}\n`);
+  }
+
+  writeError(message) {
+    this.errorOutput.write(`[ufoo-mcp-proxy] ${String(message || "")}\n`);
+  }
+
+  async connect() {
+    if (this.endpoint && this.token) return { endpoint: this.endpoint };
+    if (this.startup) return this.startup;
+    this.startup = (async () => {
+      if (this.autoStart) await this.ensureDaemon();
+      const deadline = Date.now() + this.endpointWaitMs;
+      let lastError = null;
+      do {
+        try {
+          const connection = readConnectionFiles(this.projectRoot);
+          this.endpoint = connection.endpoint;
+          this.token = connection.token;
+          return { endpoint: this.endpoint };
+        } catch (err) {
+          lastError = err;
+        }
+        if (!this.autoStart) break;
+        await sleep(this.endpointPollMs);
+      } while (Date.now() < deadline);
+      const err = new Error(
+        `Global MCP endpoint is unavailable: ${lastError ? lastError.message : "not started"}`
+      );
+      err.code = "UFOO_MCP_UNAVAILABLE";
+      throw err;
+    })();
+    try {
+      return await this.startup;
+    } catch (err) {
+      this.startup = null;
+      throw err;
+    }
+  }
+
+  async post(request, controller) {
+    await this.connect();
+    const headers = {
+      accept: "application/json, text/event-stream",
+      authorization: `Bearer ${this.token}`,
+      "content-type": "application/json",
+    };
+    if (this.sessionId) headers["mcp-session-id"] = this.sessionId;
+    const response = await this.fetch(this.endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+      signal: controller.signal,
+    });
+    const nextSessionId = response.headers.get("mcp-session-id");
+    if (nextSessionId) this.sessionId = nextSessionId;
+    if (response.status === 202 || response.status === 204) return null;
+    const text = await response.text();
+    if (!text) {
+      if (response.ok) return null;
+      throw new Error(`Global MCP returned HTTP ${response.status}`);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      throw new Error(`Global MCP returned invalid JSON (HTTP ${response.status})`);
+    }
+    return payload;
+  }
+
+  async forward(request) {
+    const hasId = Object.prototype.hasOwnProperty.call(request || {}, "id");
+    const id = hasId ? request.id : undefined;
+    const method = String((request && request.method) || "");
+    if (method !== "initialize" && this.initializing) {
+      await this.initializing;
+    }
+
+    const controller = new AbortController();
+    if (hasId) this.activeRequests.set(id, controller);
+    const operation = this.post(request, controller);
+    if (method === "initialize") this.initializing = operation;
+    try {
+      const response = await operation;
+      if (response) this.writeMessage(response);
+      return response;
+    } catch (err) {
+      if (hasId) {
+        const response = createJsonRpcError(
+          id,
+          MCP_ERROR_CODES.INTERNAL_ERROR,
+          err && err.message ? err.message : String(err),
+          { code: err && err.code ? String(err.code) : "mcp_proxy_error" }
+        );
+        this.writeMessage(response);
+        return response;
+      }
+      this.writeError(err && err.message ? err.message : err);
+      return null;
+    } finally {
+      if (hasId) this.activeRequests.delete(id);
+      if (method === "initialize") this.initializing = null;
+    }
+  }
+
+  handleLine(line) {
+    if (!line.trim()) return;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch (err) {
+      this.writeMessage(createJsonRpcError(
+        null,
+        MCP_ERROR_CODES.PARSE_ERROR,
+        err.message || "Parse error"
+      ));
+      return;
+    }
+    void this.forward(request);
+  }
+
+  start() {
+    this.input.setEncoding("utf8");
+    this.input.on("data", (chunk) => {
+      this.buffer += chunk;
+      const lines = this.buffer.split(/\r?\n/);
+      this.buffer = lines.pop() || "";
+      for (const line of lines) this.handleLine(line);
+    });
+    this.input.on("end", () => {
+      void this.close();
+    });
+    this.input.on("close", () => {
+      void this.close();
+    });
+    return this;
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const controller of this.activeRequests.values()) controller.abort();
+    this.activeRequests.clear();
+    if (!this.endpoint || !this.token || !this.sessionId) return;
+    try {
+      await this.fetch(this.endpoint, {
+        method: "DELETE",
+        headers: {
+          accept: "application/json, text/event-stream",
+          authorization: `Bearer ${this.token}`,
+          "mcp-session-id": this.sessionId,
+        },
+      });
+    } catch {
+      // The adapter is disposable; the server will also close abandoned sessions.
+    }
+  }
+}
+
+function createMcpStdioProxy(options = {}) {
+  return new McpStdioProxy(options);
+}
+
+async function runMcpStdioProxy(options = {}) {
+  return createMcpStdioProxy(options).start();
+}
+
+module.exports = {
+  McpStdioProxy,
+  createMcpStdioProxy,
+  readConnectionFiles,
+  runMcpStdioProxy,
+  validateEndpoint,
+};