agent-gear 1.3.0 → 2.1.0

package/src/mcp/relay.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { McpRelay, type McpRelayResult } from './relay.js';
+
+function createRelay() {
+  const emitted: Array<{ requestId: string; sessionId: string; serverName: string; token: string; body: unknown }> = [];
+  const relay = new McpRelay((payload) => emitted.push(payload));
+  return { relay, emitted };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('McpRelay', () => {
+  it('T-C6 resolves a pending request by requestId on mcp:response', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['github-mcp'] });
+
+    const promise = relay.forward('sess-1', 'github-mcp', { method: 'tools/list' });
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0].requestId).toMatch(/^mcpreq_/);
+    expect(emitted[0]).toMatchObject({
+      sessionId: 'sess-1',
+      serverName: 'github-mcp',
+      token: 'tok-1',
+      body: { method: 'tools/list' },
+    });
+
+    relay.handleMcpResponse(emitted[0].requestId, 200, { result: [] });
+    await expect(promise).resolves.toEqual({ status: 200, body: { result: [] } });
+  });
+
+  it('T-C7 times out after 60s with 504 and cleans up pending', async () => {
+    vi.useFakeTimers();
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['github-mcp'] });
+
+    const first = relay.forward('sess-1', 'github-mcp', { method: 'tools/list' });
+    await vi.advanceTimersByTimeAsync(60_000);
+    await expect(first).resolves.toEqual(expect.objectContaining({ status: 504 }));
+
+    const second = relay.forward('sess-1', 'github-mcp', { method: 'tools/call' });
+    emitted[1] && relay.handleMcpResponse(emitted[1].requestId, 200, { ok: true });
+    await expect(second).resolves.toEqual({ status: 200, body: { ok: true } });
+  });
+
+  it('T-C8 fails all pending immediately with 503 on disconnect', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['a-mcp'] });
+    const promises = [
+      relay.forward('sess-1', 'a-mcp', { id: 1 }),
+      relay.forward('sess-1', 'a-mcp', { id: 2 }),
+    ];
+    expect(emitted).toHaveLength(2);
+
+    relay.handleDisconnect();
+    const results = await Promise.all(promises);
+    expect(results).toEqual([
+      expect.objectContaining({ status: 503 }),
+      expect.objectContaining({ status: 503 }),
+    ]);
+  });
+
+  it('T-C9 unregistering a session fails its pending with 410, other sessions unaffected', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['a-mcp'] });
+    relay.registerSession('sess-2', { token: 'tok-2', serverNames: ['b-mcp'] });
+
+    const sess1 = relay.forward('sess-1', 'a-mcp', { id: 1 });
+    const sess2 = relay.forward('sess-2', 'b-mcp', { id: 2 });
+
+    relay.unregisterSession('sess-1');
+    await expect(sess1).resolves.toEqual(expect.objectContaining({ status: 410 }));
+    expect(relay.hasSession('sess-1')).toBe(false);
+    expect(relay.hasSession('sess-2')).toBe(true);
+
+    emitted[1] && relay.handleMcpResponse(emitted[1].requestId, 200, { ok: true });
+    await expect(sess2).resolves.toEqual({ status: 200, body: { ok: true } });
+  });
+
+  it('T-C10 ignores mcp:response for an unknown requestId', async () => {
+    const { relay } = createRelay();
+    expect(() => relay.handleMcpResponse('mcpreq_unknown', 200, {})).not.toThrow();
+  });
+
+  it('forward returns 404 for an unregistered session', async () => {
+    const { relay } = createRelay();
+    const result: McpRelayResult = await relay.forward('missing', 'a-mcp', {});
+    expect(result.status).toBe(404);
+  });
+});

package/src/mcp/relay.ts

@@ -0,0 +1,94 @@
+export interface SessionEndpoint {
+  token: string;
+  serverNames: string[];
+}
+
+export interface McpRelayResult {
+  status: number;
+  body: unknown;
+}
+
+interface McpRequestPayload {
+  requestId: string;
+  sessionId: string;
+  serverName: string;
+  token: string;
+  body: unknown;
+}
+
+interface PendingRequest {
+  sessionId: string;
+  resolve: (result: McpRelayResult) => void;
+  timer: NodeJS.Timeout;
+}
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+export class McpRelay {
+  private pendingRequests = new Map<string, PendingRequest>();
+  private sessionEndpoints = new Map<string, SessionEndpoint>();
+  private emitMcpRequest: (payload: McpRequestPayload) => void;
+
+  constructor(emitMcpRequest: (payload: McpRequestPayload) => void) {
+    this.emitMcpRequest = emitMcpRequest;
+  }
+
+  registerSession(sessionId: string, endpoint: SessionEndpoint): void {
+    this.sessionEndpoints.set(sessionId, endpoint);
+  }
+
+  hasSession(sessionId: string): boolean {
+    return this.sessionEndpoints.has(sessionId);
+  }
+
+  hasServer(sessionId: string, serverName: string): boolean {
+    const endpoint = this.sessionEndpoints.get(sessionId);
+    return endpoint ? endpoint.serverNames.includes(serverName) : false;
+  }
+
+  unregisterSession(sessionId: string): void {
+    if (!this.sessionEndpoints.delete(sessionId)) return;
+    for (const [requestId, pending] of this.pendingRequests) {
+      if (pending.sessionId !== sessionId) continue;
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(requestId);
+      pending.resolve({ status: 410, body: { error: 'SESSION_ENDED', message: 'MCP session has ended' } });
+    }
+  }
+
+  async forward(sessionId: string, serverName: string, body: unknown): Promise<McpRelayResult> {
+    const endpoint = this.sessionEndpoints.get(sessionId);
+    if (!endpoint) return { status: 404, body: { error: 'SESSION_NOT_FOUND' } };
+    const requestId = `mcpreq_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    console.log(`[MCP relay] forward requestId=${requestId} session=${sessionId} server=${serverName} method=${(body as { method?: string })?.method ?? '?'}`);
+    return new Promise<McpRelayResult>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        console.log(`[MCP relay] requestId=${requestId} -> 504 (timeout after ${REQUEST_TIMEOUT_MS}ms, no mcp:response received)`);
+        resolve({ status: 504, body: { error: 'TIMEOUT', message: 'MCP request timed out' } });
+      }, REQUEST_TIMEOUT_MS);
+      this.pendingRequests.set(requestId, { sessionId, resolve, timer });
+      this.emitMcpRequest({ requestId, sessionId, serverName, token: endpoint.token, body });
+    });
+  }
+
+  handleMcpResponse(requestId: string, status: number, body: unknown): void {
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) {
+      console.log(`[MCP relay] response requestId=${requestId} status=${status} IGNORED (no pending request)`);
+      return;
+    }
+    console.log(`[MCP relay] response requestId=${requestId} status=${status}`);
+    clearTimeout(pending.timer);
+    this.pendingRequests.delete(requestId);
+    pending.resolve({ status, body });
+  }
+
+  handleDisconnect(): void {
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(requestId);
+      pending.resolve({ status: 503, body: { error: 'CONTROLLER_DISCONNECTED', message: 'Controller disconnected' } });
+    }
+  }
+}

package/src/socketio-client.ts

@@ -16,8 +16,10 @@ import { worktreeHandler } from './worktree-handler.js';
 import { fsHandler } from './fs-handler.js';
 import { gatewayManager } from './gateway.js';
 import { processRegistry, isProcessAlive } from './acp/process-registry.js';
+import { McpRelay } from './mcp/relay.js';
+import { LocalMcpServer } from './mcp/local-server.js';
 
-const CONTROLLER_VERSION = '1.1.1';
+const CONTROLLER_VERSION = '2.1.0';
 const acpBridges = new Map<string, AcpSessionBridge>();
 const permissionRequestBridge = new Map<string, AcpSessionBridge>();
 const elicitationRequestBridge = new Map<string, AcpSessionBridge>();
@@ -60,7 +62,7 @@ interface AcpStartPayload {
   serverType: string;
   cwd: string;
   mcpServers?: Array<{ name: string; command: string; args?: string[]; env?: Array<{ name: string; value: string }> }>;
-  mcpEndpoint?: { url: string; token: string; serverNames: string[] };
+  mcpEndpoint?: { token: string; serverNames: string[] };
   additionalDirectories?: string[];
   modeId?: string;
   modelId?: string;
@@ -73,13 +75,13 @@ interface AcpMessagePayload {
 
 // Summarize the MCP configuration of an acp:start/acp:resume payload for logs,
 // without leaking the endpoint token.
-function describeMcpConfig(data: { mcpServers?: unknown[]; mcpEndpoint?: { url: string; serverNames?: string[] } }): string {
+function describeMcpConfig(data: { mcpServers?: unknown[]; mcpEndpoint?: { serverNames?: string[] } }): string {
   const parts: string[] = [];
   if (data.mcpServers && data.mcpServers.length > 0) {
     parts.push(`mcpServers=${data.mcpServers.length}`);
   }
   if (data.mcpEndpoint) {
-    parts.push(`mcpEndpoint(url=${data.mcpEndpoint.url}, serverNames=${JSON.stringify(data.mcpEndpoint.serverNames ?? null)})`);
+    parts.push(`mcpEndpoint(serverNames=${JSON.stringify(data.mcpEndpoint.serverNames ?? null)})`);
   }
   return parts.length > 0 ? `mcp=[${parts.join(' ')}]` : 'mcp=[none]';
 }
@@ -132,7 +134,7 @@ interface AcpResumePayload {
   externalSessionId: string;
   serverType: string;
   cwd: string;
-  mcpEndpoint?: { url: string; token: string; serverNames: string[] };
+  mcpEndpoint?: { token: string; serverNames: string[] };
   additionalDirectories?: string[];
   modeId?: string;
   modelId?: string;
@@ -201,20 +203,93 @@ interface GitCommitPayload {
   message: string;
 }
 
+export interface ParsedEndpoint {
+  /** 服务源（协议 + host + port），不含 path/query，例如 `wss://cloud.example.com`。 */
+  origin: string;
+  /** Socket.IO namespace：旧 endpoint 为 `/`，带 pathname 的 endpoint 取其路径（如 `/worker`）。 */
+  namespace: string;
+  /** 握手 query 参数（如 `?token=xxx`）；旧 endpoint 为空对象。 */
+  query: Record<string, string>;
+}
+
+/**
+ * 解析 controller endpoint，区分「旧 controller-api endpoint」与「带 path/query 的 cloud-controller endpoint」。
+ *
+ * - `http://host:4001`          → namespace `/`、无 query（对 controller-api 旧行为零变化）
+ * - `wss://host/worker?token=x` → namespace `/worker`、query `{ token: 'x' }`
+ *
+ * socket.io-client v4 原生即按此规则解析 URL（pathname→namespace、search→handshake query），
+ * 因此 `connectToServer` 仍直接把 endpoint 透传给 `io()`。本函数用于单测锚定该解析口径，
+ * 并为日志输出提供不含凭据的连接目标。
+ */
+export function parseEndpoint(endpoint: string): ParsedEndpoint {
+  const result: ParsedEndpoint = { origin: endpoint, namespace: '/', query: {} };
+  try {
+    const url = new URL(endpoint);
+    result.origin = url.origin;
+    const pathname = url.pathname.replace(/\/+$/, '');
+    result.namespace = pathname === '' ? '/' : pathname;
+    for (const [name, value] of url.searchParams) {
+      result.query[name] = value;
+    }
+  } catch {
+    // 非法 URL：保持透传（origin=原始字符串、默认 namespace、无 query），与既有行为一致
+  }
+  return result;
+}
+
+export function extractHandshakeToken(endpoint: string): string | undefined {
+  try {
+    return new URL(endpoint).searchParams.get('token') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 从 endpoint 移除一次性 token query（问题 11：token 不进 URL/access log，改由 Socket.IO
+ * 握手 `auth.token` 承载）。无 token 时原样返回。
+ */
+export function stripTokenFromEndpoint(endpoint: string): string {
+  try {
+    const url = new URL(endpoint);
+    if (!url.searchParams.has('token')) return endpoint;
+    url.searchParams.delete('token');
+    return url.toString();
+  } catch {
+    return endpoint;
+  }
+}
+
 export function connectToServer(
   endpoint: string,
   key: string,
   options?: { serverName?: string },
 ): Socket {
-  const socket = createSocketIOClient(endpoint, {
+  // 一次性 token 优先取 endpoint query（兼容旧注入），否则用 key（cloud-controller 场景 key=token）。
+  // token 不再放进 URL，改经 Socket.IO 握手 auth 传递，避免进入 ingress/中间层访问日志。
+  const handshakeToken = extractHandshakeToken(endpoint) ?? (key || undefined);
+  const connectEndpoint = stripTokenFromEndpoint(endpoint);
+
+  const socket = createSocketIOClient(connectEndpoint, {
     transports: ['websocket'],
     reconnection: true,
     reconnectionDelay: 1000,
     reconnectionDelayMax: 60000,
+    auth: handshakeToken ? { token: handshakeToken } : {},
   });
 
   const heartbeat = new Heartbeat();
   const controllerName = options?.serverName || hostname();
+  const mcpRelay = new McpRelay((payload) => socket.emit('mcp:request', payload));
+  const localServer = new LocalMcpServer(mcpRelay);
+  // 回环 HTTP 服务在守护进程内只启动一次、进程退出前不停止（提案 Phase 2 要求全守护进程共享一个端口）。
+  // 断线快速失败由 mcpRelay.handleDisconnect()（503）承担，无需随 socket 连接启停 HTTP 服务。
+  // ready promise 保证 acp:start/acp:resume 读取 localServer.port 前服务已 listening（启动只 await 一次）。
+  const mcpServerReady = localServer.start();
+  mcpServerReady.catch((err: Error) => {
+    console.error(`[MCP] failed to start local MCP endpoint: ${err.message}`);
+  });
 
   // Seed the fs:remove-dir whitelist with cwds of ACP processes that survived
   // a controller restart (their worktrees remain controller-managed).
@@ -223,7 +298,9 @@ export function connectToServer(
   }
 
   socket.on('connect', () => {
-    console.log(`Connected to ${endpoint}`);
+    // 不直接打印 endpoint：cloud-controller 场景下 endpoint 含一次性 token，避免凭据进入日志
+    const { origin, namespace } = parseEndpoint(connectEndpoint);
+    console.log(`Connected to ${origin}${namespace === '/' ? '' : namespace}`);
     const resumeToken = getResumeTokenFromConfig();
     socket.emit('register', {
       key,
@@ -246,6 +323,13 @@ export function connectToServer(
 
   socket.on('error', (data: ErrorPayload) => {
     console.error(`Server error: ${data.code} - ${data.message}`);
+    if (data.code === 'VERSION_MISMATCH') {
+      console.error('The agent-controller version is not supported by the server.');
+      console.error('Please upgrade agent-controller to 2.x (npm i -g agent-gear@2 or the matching release).');
+      socket.disconnect();
+      process.exit(1);
+      return;
+    }
     if (data.code === 'KEY_ALREADY_ONLINE') {
       console.log('Clearing resume token and retrying connection...');
       clearResumeTokenFromConfig();
@@ -319,11 +403,23 @@ export function connectToServer(
         await existingBridge.stop().catch(() => {});
       }
       const spawner = createSpawner(data.serverType, data.sessionId, data.cwd);
+      if (data.mcpEndpoint) {
+        // 确保回环服务已 listening 后再读取 port 并注入（启动失败时 fail loudly，不静默注入端口 0）
+        await mcpServerReady;
+        if (localServer.port <= 0) {
+          throw new Error(`MCP endpoint unavailable: local loopback server not listening (port=${localServer.port})`);
+        }
+        mcpRelay.registerSession(data.sessionId, {
+          token: data.mcpEndpoint.token,
+          serverNames: data.mcpEndpoint.serverNames,
+        });
+      }
       const bridge = new AcpSessionBridge(socket, {
         sessionId: data.sessionId,
         cwd: data.cwd,
         mcpServers: data.mcpServers,
         mcpEndpoint: data.mcpEndpoint,
+        mcpPort: localServer.port,
         additionalDirectories: data.additionalDirectories,
         initialModeId: data.modeId,
         initialModelId: data.modelId,
@@ -338,6 +434,7 @@ export function connectToServer(
       bridge.on('acp:stopped', (payload: { sessionId: string }) => {
         if (payload.sessionId === data.sessionId) {
           processRegistry.deregister(data.sessionId);
+          mcpRelay.unregisterSession(data.sessionId);
         }
       });
 
@@ -406,6 +503,7 @@ export function connectToServer(
         bridge.off('acp:stopped', onStopped);
         acpBridges.delete(data.sessionId);
         processRegistry.deregister(data.sessionId);
+        mcpRelay.unregisterSession(data.sessionId);
         console.log(`[ACP ctrl] emitting acp:start:result: requestId=${data.requestId} sessionId=${data.sessionId} success=false reason=${payload.reason} error=${payload.error ?? 'n/a'}`);
         socket.emit('acp:start:result', {
           requestId: data.requestId,
@@ -422,6 +520,7 @@ export function connectToServer(
       await bridge.start();
     } catch (error) {
       console.error(`[ACP ctrl] bridge.start() failed: ${(error as Error).message}`);
+      mcpRelay.unregisterSession(data.sessionId);
       socket.emit('acp:start:result', {
         requestId: data.requestId,
         sessionId: data.sessionId,
@@ -443,10 +542,22 @@ export function connectToServer(
         await existingBridge.stop().catch(() => {});
       }
       const spawner = createSpawner(data.serverType, data.sessionId, data.cwd);
+      if (data.mcpEndpoint) {
+        // 确保回环服务已 listening 后再读取 port 并注入（启动失败时 fail loudly，不静默注入端口 0）
+        await mcpServerReady;
+        if (localServer.port <= 0) {
+          throw new Error(`MCP endpoint unavailable: local loopback server not listening (port=${localServer.port})`);
+        }
+        mcpRelay.registerSession(data.sessionId, {
+          token: data.mcpEndpoint.token,
+          serverNames: data.mcpEndpoint.serverNames,
+        });
+      }
       const bridge = new AcpSessionBridge(socket, {
         sessionId: data.sessionId,
         cwd: data.cwd,
         mcpEndpoint: data.mcpEndpoint,
+        mcpPort: localServer.port,
         additionalDirectories: data.additionalDirectories,
         // 初始 mode/model：resume 完成后、acp:initialized 之前应用（时序同 acp:start）
         initialModeId: data.modeId,
@@ -459,6 +570,7 @@ export function connectToServer(
       bridge.on('acp:stopped', (payload: { sessionId: string }) => {
         if (payload.sessionId === data.sessionId) {
           processRegistry.deregister(data.sessionId);
+          mcpRelay.unregisterSession(data.sessionId);
         }
       });
 
@@ -497,6 +609,7 @@ export function connectToServer(
         bridge.off('acp:stopped', onStopped);
         acpBridges.delete(data.sessionId);
         processRegistry.deregister(data.sessionId);
+        mcpRelay.unregisterSession(data.sessionId);
         console.log(`[ACP ctrl] emitting acp:resume:result: requestId=${data.requestId} sessionId=${data.sessionId} success=false reason=${payload.reason} error=${payload.error ?? 'n/a'}`);
         socket.emit('acp:resume:result', {
           requestId: data.requestId,
@@ -512,6 +625,7 @@ export function connectToServer(
       await bridge.resume(data.externalSessionId);
     } catch (error) {
       console.error(`[ACP ctrl] bridge.resume() failed: ${(error as Error).message}`);
+      mcpRelay.unregisterSession(data.sessionId);
       socket.emit('acp:resume:result', {
         requestId: data.requestId,
         sessionId: data.sessionId,
@@ -693,6 +807,7 @@ export function connectToServer(
         processRegistry.deregister(data.sessionId);
       }
     }
+    mcpRelay.unregisterSession(data.sessionId);
     if (data.ackRequired) {
       socket.emit('acp:stopped', {
         sessionId: data.sessionId,
@@ -967,6 +1082,7 @@ export function connectToServer(
           }
         } catch { /* process may already be dead */ }
         processRegistry.deregister(entry.sessionId);
+        mcpRelay.unregisterSession(entry.sessionId);
         // Also clean up bridge if present
         const bridge = acpBridges.get(entry.sessionId);
         if (bridge) {
@@ -1014,12 +1130,17 @@ export function connectToServer(
     }
   });
 
+  socket.on('mcp:response', (data: { requestId: string; status: number; body: unknown }) => {
+    mcpRelay.handleMcpResponse(data.requestId, data.status, data.body);
+  });
+
   socket.on('disconnect', (reason) => {
     console.log(`Disconnected: ${reason}`);
     heartbeat.stop();
     gatewayManager.closeAll();
     permissionRequestBridge.clear();
     elicitationRequestBridge.clear();
+    mcpRelay.handleDisconnect();
   });
 
   socket.on('connect_error', (err) => {

package/tests/acp-wire-mcp.test.ts

@@ -49,10 +49,10 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
       sessionId: 'sess-wire',
       cwd: workdir,
       mcpEndpoint: {
-        url: 'http://gateway/mcp/sess-wire',
         token: 'wire-token',
         serverNames: ['fluentui-mcp', 'fs-mcp'],
       },
+      mcpPort: 41234,
     }, spawner);
     return socket;
   }
@@ -76,13 +76,13 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
       {
         type: 'http',
         name: 'fluentui-mcp',
-        url: 'http://gateway/mcp/sess-wire/fluentui-mcp',
+        url: 'http://127.0.0.1:41234/mcp/sess-wire/fluentui-mcp',
         headers: [{ name: 'Authorization', value: 'Bearer wire-token' }],
       },
       {
         type: 'http',
         name: 'fs-mcp',
-        url: 'http://gateway/mcp/sess-wire/fs-mcp',
+        url: 'http://127.0.0.1:41234/mcp/sess-wire/fs-mcp',
         headers: [{ name: 'Authorization', value: 'Bearer wire-token' }],
       },
     ]);
@@ -92,7 +92,7 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
     const logLines = logSpy.mock.calls.map((c) => String(c[0]));
     const mcpLog = logLines.find((l) => l.includes('passing MCP servers via session/new'));
     expect(mcpLog).toBeDefined();
-    expect(mcpLog).toContain('fluentui-mcp(type=http, url=http://gateway/mcp/sess-wire/fluentui-mcp, headers=Authorization)');
+    expect(mcpLog).toContain('fluentui-mcp(type=http, url=http://127.0.0.1:41234/mcp/sess-wire/fluentui-mcp, headers=Authorization)');
     expect(mcpLog).not.toContain('wire-token');
   }, 15000);