agent-gear 1.3.0 → 2.1.0

package/dist/mcp/local-server.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from 'vitest';
+import http from 'node:http';
+import { LocalMcpServer } from './local-server.js';
+function makeRelay(options) {
+    const session = options?.session ?? 'sess-1';
+    const server = options?.server ?? 'github-mcp';
+    return {
+        hasSession: (id) => id === session,
+        hasServer: (id, name) => id === session && name === server,
+        forward: vi.fn(async () => ({ status: 200, body: { result: 'ok' } })),
+    };
+}
+async function startServer(relay) {
+    const server = new LocalMcpServer(relay);
+    await server.start();
+    return server;
+}
+function request(server, method, path, headers, body) {
+    return new Promise((resolve, reject) => {
+        const req = http.request({ host: '127.0.0.1', port: server.port, path, method, headers }, (res) => {
+            let data = '';
+            res.on('data', (c) => (data += c));
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, data }));
+        });
+        req.on('error', reject);
+        if (body !== undefined)
+            req.write(body);
+        req.end();
+    });
+}
+const AUTH = { authorization: 'Bearer tok-1' };
+function httpAddress(server) {
+    return server.server.address();
+}
+describe('LocalMcpServer', () => {
+    it('T-C1 forwards a valid POST to the relay and writes back the response', async () => {
+        const relay = makeRelay();
+        const server = await startServer(relay);
+        const path = '/mcp/sess-1/github-mcp';
+        const res = await request(server, 'POST', path, AUTH, JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }));
+        expect(relay.forward).toHaveBeenCalledWith('sess-1', 'github-mcp', { jsonrpc: '2.0', id: 1, method: 'tools/list' });
+        expect(res.status).toBe(200);
+        expect(JSON.parse(res.data)).toEqual({ result: 'ok' });
+        await server.stop();
+    });
+    it('T-C2 fast-fails unregistered session (404), out-of-snapshot server (404), missing Authorization (401)', async () => {
+        const relay = makeRelay({ session: 'sess-1', server: 'github-mcp' });
+        const server = await startServer(relay);
+        const body = JSON.stringify({ id: 1 });
+        const unregistered = await request(server, 'POST', '/mcp/ghost-mcp/anything', AUTH, body);
+        expect(unregistered.status).toBe(404);
+        const unknownServer = await request(server, 'POST', '/mcp/sess-1/unknown-server', AUTH, body);
+        expect(unknownServer.status).toBe(404);
+        const noAuth = await request(server, 'POST', '/mcp/sess-1/github-mcp', undefined, body);
+        expect(noAuth.status).toBe(401);
+        expect(relay.forward).not.toHaveBeenCalled();
+        await server.stop();
+    });
+    it('T-C3 returns 405 for GET', async () => {
+        const relay = makeRelay();
+        const server = await startServer(relay);
+        const res = await request(server, 'GET', '/mcp/sess-1/github-mcp');
+        expect(res.status).toBe(405);
+        expect(relay.forward).not.toHaveBeenCalled();
+        await server.stop();
+    });
+    it('T-C4 listens only on 127.0.0.1 with an ephemeral port > 0', async () => {
+        const relay = makeRelay();
+        const server = await startServer(relay);
+        const address = httpAddress(server);
+        expect(address.address).toBe('127.0.0.1');
+        expect(address.port).toBeGreaterThan(0);
+        expect(server.port).toBe(address.port);
+        await server.stop();
+    });
+    it('T-C5 concurrent requests resolve independently without interfering', async () => {
+        const resolvers = [];
+        const relay = {
+            hasSession: (id) => id === 'sess-1',
+            hasServer: (id, name) => id === 'sess-1' && name === 'github-mcp',
+            forward: vi.fn(() => new Promise((resolve) => {
+                resolvers.push(resolve);
+            })),
+        };
+        const server = await startServer(relay);
+        const p1 = request(server, 'POST', '/mcp/sess-1/github-mcp', AUTH, JSON.stringify({ id: 1 }));
+        const p2 = request(server, 'POST', '/mcp/sess-1/github-mcp', AUTH, JSON.stringify({ id: 2 }));
+        const p3 = request(server, 'POST', '/mcp/sess-1/github-mcp', AUTH, JSON.stringify({ id: 3 }));
+        await new Promise((r) => setTimeout(r, 20));
+        expect(relay.forward).toHaveBeenCalledTimes(3);
+        expect(resolvers).toHaveLength(3);
+        resolvers[0]({ status: 200, body: { result: 'first' } });
+        resolvers[1]({ status: 504, body: { error: 'TIMEOUT' } });
+        resolvers[2]({ status: 200, body: { result: 'third' } });
+        expect((await p1).status).toBe(200);
+        expect((await p2).status).toBe(504);
+        expect((await p3).status).toBe(200);
+        await server.stop();
+    });
+});
+//# sourceMappingURL=local-server.test.js.map

package/dist/mcp/local-server.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-server.test.js","sourceRoot":"","sources":["../../src/mcp/local-server.test.ts"],"names":[],"mappings":"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"}

package/dist/mcp/relay.d.ts

@@ -0,0 +1,30 @@
+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;
+}
+export declare class McpRelay {
+    private pendingRequests;
+    private sessionEndpoints;
+    private emitMcpRequest;
+    constructor(emitMcpRequest: (payload: McpRequestPayload) => void);
+    registerSession(sessionId: string, endpoint: SessionEndpoint): void;
+    hasSession(sessionId: string): boolean;
+    hasServer(sessionId: string, serverName: string): boolean;
+    unregisterSession(sessionId: string): void;
+    forward(sessionId: string, serverName: string, body: unknown): Promise<McpRelayResult>;
+    handleMcpResponse(requestId: string, status: number, body: unknown): void;
+    handleDisconnect(): void;
+}
+export {};
+//# sourceMappingURL=relay.d.ts.map

package/dist/mcp/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../src/mcp/relay.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,iBAAiB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAUD,qBAAa,QAAQ;IACnB,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,gBAAgB,CAAsC;IAC9D,OAAO,CAAC,cAAc,CAAuC;gBAEjD,cAAc,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI;IAIhE,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAInE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAKzD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAUpC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAgB5F,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAYzE,gBAAgB,IAAI,IAAI;CAOzB"}

package/dist/mcp/relay.js

@@ -0,0 +1,65 @@
+const REQUEST_TIMEOUT_MS = 60_000;
+export class McpRelay {
+    pendingRequests = new Map();
+    sessionEndpoints = new Map();
+    emitMcpRequest;
+    constructor(emitMcpRequest) {
+        this.emitMcpRequest = emitMcpRequest;
+    }
+    registerSession(sessionId, endpoint) {
+        this.sessionEndpoints.set(sessionId, endpoint);
+    }
+    hasSession(sessionId) {
+        return this.sessionEndpoints.has(sessionId);
+    }
+    hasServer(sessionId, serverName) {
+        const endpoint = this.sessionEndpoints.get(sessionId);
+        return endpoint ? endpoint.serverNames.includes(serverName) : false;
+    }
+    unregisterSession(sessionId) {
+        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, serverName, body) {
+        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?.method ?? '?'}`);
+        return new Promise((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, status, body) {
+        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() {
+        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' } });
+        }
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/mcp/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/mcp/relay.ts"],"names":[],"mappings":"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"}

package/dist/mcp/relay.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=relay.test.d.ts.map

package/dist/mcp/relay.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.test.d.ts","sourceRoot":"","sources":["../../src/mcp/relay.test.ts"],"names":[],"mappings":""}

package/dist/mcp/relay.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { McpRelay } from './relay.js';
+function createRelay() {
+    const emitted = [];
+    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 = await relay.forward('missing', 'a-mcp', {});
+        expect(result.status).toBe(404);
+    });
+});
+//# sourceMappingURL=relay.test.js.map

package/dist/mcp/relay.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.test.js","sourceRoot":"","sources":["../../src/mcp/relay.test.ts"],"names":[],"mappings":"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"}

package/dist/socketio-client.d.ts

@@ -1,4 +1,29 @@
 import { type Socket } from 'socket.io-client';
+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 declare function parseEndpoint(endpoint: string): ParsedEndpoint;
+export declare function extractHandshakeToken(endpoint: string): string | undefined;
+/**
+ * 从 endpoint 移除一次性 token query（问题 11：token 不进 URL/access log，改由 Socket.IO
+ * 握手 `auth.token` 承载）。无 token 时原样返回。
+ */
+export declare function stripTokenFromEndpoint(endpoint: string): string;
 export declare function connectToServer(endpoint: string, key: string, options?: {
     serverName?: string;
 }): Socket;

package/dist/socketio-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socketio-client.d.ts","sourceRoot":"","sources":["../src/socketio-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AA2M3E,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,MAAM,CAszBR;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C"}
+{"version":3,"file":"socketio-client.d.ts","sourceRoot":"","sources":["../src/socketio-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AA6M3E,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAc9D;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM1E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,MAAM,CAm3BR;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C"}

package/dist/socketio-client.js

@@ -15,7 +15,9 @@ 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';
-const CONTROLLER_VERSION = '1.1.1';
+import { McpRelay } from './mcp/relay.js';
+import { LocalMcpServer } from './mcp/local-server.js';
+const CONTROLLER_VERSION = '2.1.0';
 const acpBridges = new Map();
 const permissionRequestBridge = new Map();
 const elicitationRequestBridge = new Map();
@@ -34,26 +36,92 @@ function describeMcpConfig(data) {
         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]';
 }
+/**
+ * 解析 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) {
+    const result = { 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) {
+    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) {
+    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, key, options) {
-    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) => {
+        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).
     for (const entry of processRegistry.listEntries()) {
         fsHandler.registerAllowedPath(entry.cwd);
     }
     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,
@@ -74,6 +142,13 @@ export function connectToServer(endpoint, key, options) {
     });
     socket.on('error', (data) => {
         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();
@@ -142,11 +217,23 @@ export function connectToServer(endpoint, key, options) {
                 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,
@@ -159,6 +246,7 @@ export function connectToServer(endpoint, key, options) {
             bridge.on('acp:stopped', (payload) => {
                 if (payload.sessionId === data.sessionId) {
                     processRegistry.deregister(data.sessionId);
+                    mcpRelay.unregisterSession(data.sessionId);
                 }
             });
             // Register PID in process registry after spawner starts
@@ -230,6 +318,7 @@ export function connectToServer(endpoint, key, options) {
                 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,
@@ -245,6 +334,7 @@ export function connectToServer(endpoint, key, options) {
         }
         catch (error) {
             console.error(`[ACP ctrl] bridge.start() failed: ${error.message}`);
+            mcpRelay.unregisterSession(data.sessionId);
             socket.emit('acp:start:result', {
                 requestId: data.requestId,
                 sessionId: data.sessionId,
@@ -264,10 +354,22 @@ export function connectToServer(endpoint, key, options) {
                 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,
@@ -278,6 +380,7 @@ export function connectToServer(endpoint, key, options) {
             bridge.on('acp:stopped', (payload) => {
                 if (payload.sessionId === data.sessionId) {
                     processRegistry.deregister(data.sessionId);
+                    mcpRelay.unregisterSession(data.sessionId);
                 }
             });
             bridge.on('permission:sent', (requestId) => {
@@ -320,6 +423,7 @@ export function connectToServer(endpoint, key, options) {
                 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,
@@ -334,6 +438,7 @@ export function connectToServer(endpoint, key, options) {
         }
         catch (error) {
             console.error(`[ACP ctrl] bridge.resume() failed: ${error.message}`);
+            mcpRelay.unregisterSession(data.sessionId);
             socket.emit('acp:resume:result', {
                 requestId: data.requestId,
                 sessionId: data.sessionId,
@@ -513,6 +618,7 @@ export function connectToServer(endpoint, key, options) {
                 processRegistry.deregister(data.sessionId);
             }
         }
+        mcpRelay.unregisterSession(data.sessionId);
         if (data.ackRequired) {
             socket.emit('acp:stopped', {
                 sessionId: data.sessionId,
@@ -778,6 +884,7 @@ export function connectToServer(endpoint, key, options) {
                 }
                 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) {
@@ -812,12 +919,16 @@ export function connectToServer(endpoint, key, options) {
             bridge.handleElicitationResponse(data.requestId, data.action, data.content);
         }
     });
+    socket.on('mcp:response', (data) => {
+        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) => {
         console.error(`Connection error: ${err.message}`);