@tencent-ai/agent-sdk 0.3.229 → 0.3.230-dev.80d16dd.202607272156

package/lib/transport/process-transport.d.ts

@@ -3,8 +3,32 @@
  *
  * Transport implementation that spawns CLI process and communicates via stdin/stdout.
  */
+import { type DelegatedServerDescriptorHost, type RealMcpTransport } from '../mcp/managed-remote-mcp-bridge';
 import type { ControlRequest, ControlRequestPayload, Message, SubscriptionChannel, UserMessage } from '../types';
 import type { NotificationHandler, ProcessTransportOptions, Transport } from './index';
+/**
+ * 委托 server 注册描述（宿主声明，不含 url / token）。
+ * serverName 只在当前 control connection / session scope 内唯一，真实 endpoint/token 由
+ * 受管层在 createTransport 内解析，不经过 CLI。
+ */
+export interface DelegatedServerRegistration {
+    serverName: string;
+    transport: 'http' | 'sse' | 'remote';
+    capabilityId?: string;
+}
+/**
+ * 受管层提供的委托 transport 工厂：按 scopedKey + descriptor 解析真实 endpoint/token 并建 transport。
+ * 部署方注入，测试用 mock 替代；这里不实现真实 endpoint / OAuth 解析。
+ */
+export type CreateDelegatedMcpTransport = (scopedKey: string, descriptor: DelegatedServerDescriptorHost) => Promise<RealMcpTransport>;
+/**
+ * transport 关闭的终止原因分类，用于决定是否需要合成一条补偿 error 帧。
+ *
+ * 只有异常类原因（进程非零退出、退出前未输出 result、stdout 意外关闭、spawn 失败）
+ * 才会触发合成；已经观察到 result / error 帧或上层主动关闭的场景下不合成，
+ * 避免将正常结束误报为失败。
+ */
+export type TerminalCause = 'sawResult' | 'sawError' | 'explicitClose' | 'processExitNonZero' | 'processExitZeroBeforeResult' | 'stdoutClosedUnexpectedly' | 'spawnError';
 /**
  * ProcessTransport - communicates with CLI via spawned process.
  */
@@ -21,12 +45,19 @@ export declare class ProcessTransport implements Transport {
     private _stderrBuffer;
     private readyPromise;
     private _isCliReady;
+    private _sessionId?;
+    private _currentRunId?;
+    private _sawRunStarted;
+    private _sawResult;
+    private _sawError;
     private _writeQueue;
     private _draining;
     private sdkMcpTransports;
     private sdkMcpServerInstances;
     private pendingMcpResponses;
     private _sdkMcpServerNames;
+    private managedRemoteMcpBridge?;
+    private registeredDelegatedScopedKeys;
     private _cliVersion;
     private notificationHandlers;
     constructor(options?: ProcessTransportOptions);
@@ -109,7 +140,7 @@ export declare class ProcessTransport implements Transport {
     /**
      * Send a user message to CLI.
      */
-    sendUserMessage(content: string | UserMessage, traceId?: string, parentSpanId?: string): void;
+    sendUserMessage(content: string | UserMessage, traceId?: string, parentSpanId?: string, remoteContext?: import('../types').RemoteOperationContext): void;
     /**
      * Send a control request and wait for response.
      */
@@ -126,7 +157,7 @@ export declare class ProcessTransport implements Transport {
     /**
      * Send a control error response.
      */
-    sendControlErrorResponse(requestId: string, error: string): void;
+    sendControlErrorResponse(requestId: string, error: string, code?: string): void;
     /**
      * Check if transport is ready.
      * Returns true only when CLI has produced its first output.
@@ -136,14 +167,31 @@ export declare class ProcessTransport implements Transport {
      * Register a handler for control notifications from a specific channel.
      */
     onNotification(channel: SubscriptionChannel, handler: NotificationHandler): void;
+    /**
+     * 向消息流注入一条 SDK 侧合成的消息（如 mirror_error 帧）。
+     * 流未建立或已结束时静默丢弃——此时没有消费者，合成帧无处投递。
+     */
+    enqueueMessage(message: Message): void;
     /**
      * Remove a notification handler for a specific channel.
      */
     offNotification(channel: SubscriptionChannel, handler: NotificationHandler): void;
     /**
-     * Close the transport.
+     * 关闭 transport。
+     *
+     * cause 标明终止原因：仅在异常类原因（进程非零退出、退出前未输出 result、
+     * stdout 意外关闭、spawn 失败）下才合成一条 error 帧；正常结束与主动关闭均不合成，
+     * 避免将成功的 run 误报为失败。
+     *
+     * 已有调用点（例如上层 Session.close()）不传 cause 时按主动关闭处理，
+     * 与"手动关闭不产生虚假 error"的既有行为保持一致。
      */
-    close(): void;
+    close(cause?: TerminalCause): void;
+    /**
+     * 为合成帧生成 uuid。旧 Node 运行时可能未内置 WebCrypto，
+     * crypto.randomUUID 不可用时降级为"时间戳 + 随机串"的形式。
+     */
+    private randomUuid;
     private handleLine;
     private handleControlNotification;
     private handleControlResponse;
@@ -171,6 +219,35 @@ export declare class ProcessTransport implements Transport {
      * Handle MCP message control request from CLI.
      */
     private handleMcpMessageRequest;
+    /**
+     * 注册远程委托 server（宿主驱动）。
+     *
+     * 首次调用时懒构造 ManagedRemoteMcpBridge：createTransport 由受管层注入（解析真实
+     * endpoint/token），redactResponse 接线为 redactDelegatedResponse（响应离开宿主回到 CLI
+     * 之前先脱敏）。随后对每个 descriptor 用与路由一致的 resolveDelegatedScopedKey 生成 scoped
+     * key 并注册，key 记入集合供 close 统一注销。
+     *
+     * 接线现状：ProcessTransport 构造期在 `delegatedMcpServers` + `mcpTransportFactory` 齐备时
+     * 自动调用本方法（host-driven v1 必做）。`unregisterAllDelegatedServers` 已接入
+     * close 兜底，control connection 关闭时统一释放 transport 与 pending。
+     */
+    registerDelegatedServers(descriptors: DelegatedServerRegistration[], createTransport: CreateDelegatedMcpTransport): void;
+    /**
+     * 注销所有已注册的委托 server（reject 在途 pending、关闭真实 transport）。
+     * 由 close 调用；单个注销失败不阻塞其他。
+     */
+    private unregisterAllDelegatedServers;
+    /**
+     * 组合远程委托 server 的 scoped key。
+     *
+     * 完整 scoped key 语义是 control connection / tenant / user / session / run + serverName。
+     * 本 transport 从 ProcessTransportOptions 拿到 controlConnectionId /
+     * tenantId / userId / sessionId / runId，按字符集校验后用分隔符 `::` 拼接，缺失维度直接跳过
+     * （不写空段，避免 `::` 退化成空字符串导致跨 scope 撞 key）。所有维度都缺时才退化为裸
+     * serverName——这是最后兜底，部署方应至少注入 controlConnectionId / sessionId 之一。
+     * 注册与路由必须复用这同一组合逻辑，两侧的 key 才能一致。
+     */
+    private resolveDelegatedScopedKey;
     /**
      * Handle MCP request and wait for response from MCP server.
      */

package/lib/transport/process-transport.d.ts.map

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

package/lib/transport/process-transport.js

@@ -41,7 +41,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProcessTransport = void 0;
 const node_child_process_1 = require("node:child_process");
 const readline = __importStar(require("node:readline"));
+const delegated_redaction_1 = require("../mcp/delegated-redaction");
+const managed_remote_mcp_bridge_1 = require("../mcp/managed-remote-mcp-bridge");
 const sdk_control_server_transport_1 = require("../mcp/sdk-control-server-transport");
+const remote_error_codes_1 = require("../remote-error-codes");
 const utils_1 = require("../utils");
 const version_1 = require("../version");
 function createDeferred() {
@@ -53,6 +56,12 @@ function createDeferred() {
     });
     return { promise, resolve, reject };
 }
+const ERROR_TERMINAL_CAUSES = new Set([
+    'processExitNonZero',
+    'processExitZeroBeforeResult',
+    'stdoutClosedUnexpectedly',
+    'spawnError',
+]);
 /**
  * Resolve the runtime configuration for spawning CLI process.
  *
@@ -121,6 +130,9 @@ class ProcessTransport {
         this._stderrBuffer = '';
         this.readyPromise = null;
         this._isCliReady = false;
+        this._sawRunStarted = false;
+        this._sawResult = false;
+        this._sawError = false;
         // Write queue for backpressure handling
         this._writeQueue = [];
         this._draining = false;
@@ -129,6 +141,8 @@ class ProcessTransport {
         this.sdkMcpServerInstances = new Map();
         this.pendingMcpResponses = new Map();
         this._sdkMcpServerNames = [];
+        // 已注册的委托 server scoped key 集合，供 close 时统一注销，避免残留 pending / transport。
+        this.registeredDelegatedScopedKeys = new Set();
         // Cached CLI version for UserAgent
         this._cliVersion = null;
         // Notification handlers by channel
@@ -150,6 +164,17 @@ class ProcessTransport {
                 this.connectSdkMcpServer(name, server);
             }
         }
+        // 接线 host-driven 委托 bridge：descriptor + transport 工厂齐备时，构造期即注册
+        // scoped key → descriptor 到 ManagedRemoteMcpBridge。bridge 不会主动建 transport，
+        // 真实 transport 在第一次 mcp_message 到达时按需懒建。
+        // 缺 mcpTransportFactory 时只跳过注册（CLI 会因 bridge 未命中显式 fail-closed）。
+        if (this.options.delegatedMcpServers && this.options.delegatedMcpServers.length > 0 && this.options.mcpTransportFactory) {
+            this.registerDelegatedServers(this.options.delegatedMcpServers.map(d => ({
+                serverName: d.serverName,
+                transport: d.transport,
+                capabilityId: d.capabilityId,
+            })), this.options.mcpTransportFactory);
+        }
     }
     /**
      * Get the list of SDK MCP server names.
@@ -345,6 +370,9 @@ class ProcessTransport {
         if (opts.forkSession) {
             args.push('--fork-session');
         }
+        if (opts.sessionStoreMode) {
+            args.push('--session-store-mode', opts.sessionStoreMode);
+        }
         // MCP options
         if (opts.mcpServers) {
             if (typeof opts.mcpServers === 'string') {
@@ -358,6 +386,32 @@ class ProcessTransport {
         if (opts.strictMcpConfig) {
             args.push('--strict-mcp-config');
         }
+        // FileSystem replacement: serialize explicit modules selection (handler stays in-process)
+        if (opts.fileSystem) {
+            args.push('--file-system-config', JSON.stringify(opts.fileSystem));
+        }
+        // Channel replacement: pass empty descriptor to opt in; handler stays in-process
+        if (opts.channel) {
+            args.push('--channel-config', JSON.stringify({}));
+        }
+        // Exec replacement: serialize maxOutputBytes / capabilityId / remoteExecutionContextId
+        // (handler stays in-process). Presence of --exec-config enables remote exec in cbc.
+        if (opts.exec) {
+            args.push('--exec-config', JSON.stringify({
+                ...(opts.exec.maxOutputBytes ? { maxOutputBytes: opts.exec.maxOutputBytes } : {}),
+                ...(opts.exec.capabilityId ? { capabilityId: opts.exec.capabilityId } : {}),
+                ...(opts.exec.remoteExecutionContextId ? { remoteExecutionContextId: opts.exec.remoteExecutionContextId } : {}),
+            }));
+        }
+        if (opts.remoteExtensions) {
+            args.push('--remote-extensions');
+        }
+        // Local-execution deny list. Only emit when it actually denies something, so
+        // that "unset" and "[]" (empty deny list) produce byte-identical argv/logs.
+        const led = opts.localExecutionDeny;
+        if (led === 'all' || (Array.isArray(led) && led.length > 0)) {
+            args.push('--local-execution-deny', JSON.stringify(led));
+        }
         // Settings
         // SDK default: don't load any filesystem settings for clean environment isolation
         // When settingSources is explicitly provided (including empty array), use it
@@ -453,6 +507,9 @@ class ProcessTransport {
         if (!env.CODEBUDDY_DISABLE_AUTO_MEMORY) {
             env.CODEBUDDY_DISABLE_AUTO_MEMORY = '1';
         }
+        if (this.options.remoteExtensions) {
+            env.CODEBUDDY_DISABLE_PRODUCT_CACHE = '1';
+        }
         // Thinking configuration → MAX_THINKING_TOKENS env var
         this.applyThinkingEnv(env);
         // Build SDK UserAgent and inject via CODEBUDDY_CUSTOM_HEADERS
@@ -551,7 +608,7 @@ class ProcessTransport {
     /**
      * Send a user message to CLI.
      */
-    sendUserMessage(content, traceId, parentSpanId) {
+    sendUserMessage(content, traceId, parentSpanId, remoteContext) {
         // Ensure transport is started
         this.start();
         let message;
@@ -566,16 +623,21 @@ class ProcessTransport {
                 parent_tool_use_id: null,
                 ...(traceId ? { trace_id: traceId } : {}),
                 ...(parentSpanId ? { parent_span_id: parentSpanId } : {}),
+                ...(remoteContext ? { remoteContext } : {}),
             };
         }
         else {
-            message = content;
-            if (traceId && !message.trace_id) {
-                message.trace_id = traceId;
-            }
-            if (parentSpanId && !message.parent_span_id) {
-                message.parent_span_id = parentSpanId;
+            const carrier = content;
+            if (remoteContext && carrier.remoteContext?.contextId !== undefined
+                && carrier.remoteContext.contextId !== remoteContext.contextId) {
+                throw new remote_error_codes_1.RemoteProtocolError('REMOTE_CONTEXT_MISMATCH', 'user message remote context does not match this query');
             }
+            message = {
+                ...content,
+                ...(traceId && !content.trace_id ? { trace_id: traceId } : {}),
+                ...(parentSpanId && !content.parent_span_id ? { parent_span_id: parentSpanId } : {}),
+                ...(remoteContext ? { remoteContext } : {}),
+            };
         }
         this.writeLine(message);
     }
@@ -641,13 +703,14 @@ class ProcessTransport {
     /**
      * Send a control error response.
      */
-    sendControlErrorResponse(requestId, error) {
+    sendControlErrorResponse(requestId, error, code) {
         const controlResponse = {
             type: 'control_response',
             response: {
                 subtype: 'error',
                 request_id: requestId,
                 error,
+                ...(code ? { code } : {}),
             },
         };
         this.writeLine(controlResponse);
@@ -670,6 +733,15 @@ class ProcessTransport {
         }
         handlers.add(handler);
     }
+    /**
+     * 向消息流注入一条 SDK 侧合成的消息（如 mirror_error 帧）。
+     * 流未建立或已结束时静默丢弃——此时没有消费者，合成帧无处投递。
+     */
+    enqueueMessage(message) {
+        if (this.messageStream && !this.messageStream.isFinished) {
+            this.messageStream.enqueue(message);
+        }
+    }
     /**
      * Remove a notification handler for a specific channel.
      */
@@ -683,9 +755,16 @@ class ProcessTransport {
         }
     }
     /**
-     * Close the transport.
+     * 关闭 transport。
+     *
+     * cause 标明终止原因：仅在异常类原因（进程非零退出、退出前未输出 result、
+     * stdout 意外关闭、spawn 失败）下才合成一条 error 帧；正常结束与主动关闭均不合成，
+     * 避免将成功的 run 误报为失败。
+     *
+     * 已有调用点（例如上层 Session.close()）不传 cause 时按主动关闭处理，
+     * 与"手动关闭不产生虚假 error"的既有行为保持一致。
      */
-    close() {
+    close(cause = 'explicitClose') {
         if (this.closed) {
             return;
         }
@@ -731,11 +810,47 @@ class ProcessTransport {
         }
         this.sdkMcpTransports.clear();
         this.sdkMcpServerInstances.clear();
+        // 注销远程委托 server：reject 在途 pending 并关闭真实 transport
+        this.unregisterAllDelegatedServers();
+        // 仅在 CLI 未输出终止信号时才合成 error 帧：
+        // sawResult / sawError 表示 consumer 已经收到权威的终止信号，
+        // explicitClose 属于用户主动关闭，均不应被视为失败。
+        const shouldSynthesize = this.messageStream !== null
+            && !this.messageStream.isFinished
+            && !this._sawResult
+            && !this._sawError
+            && ERROR_TERMINAL_CAUSES.has(cause);
+        if (shouldSynthesize) {
+            const syntheticError = {
+                type: 'error',
+                error: this._closeReason ?? `Transport closed: ${cause}`,
+                ...(this._sessionId ? { session_id: this._sessionId } : {}),
+                ...(this._currentRunId ? { run_id: this._currentRunId } : {}),
+                uuid: this.randomUuid(),
+            };
+            this.messageStream.enqueue(syntheticError);
+        }
         // Signal stream completion
         if (this.messageStream) {
             this.messageStream.done();
         }
     }
+    /**
+     * 为合成帧生成 uuid。旧 Node 运行时可能未内置 WebCrypto，
+     * crypto.randomUUID 不可用时降级为"时间戳 + 随机串"的形式。
+     */
+    randomUuid() {
+        try {
+            const c = globalThis.crypto;
+            if (c?.randomUUID) {
+                return c.randomUUID();
+            }
+        }
+        catch {
+            // fall through
+        }
+        return `syn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
     // ============= Private Methods =============
     handleLine(line) {
         const trimmed = line.trim();
@@ -767,6 +882,43 @@ class ProcessTransport {
                 }
                 return;
             }
+            // 更新终止态追踪字段：session_id / run_id 用于合成 error 帧时填充上下文,
+            // sawResult / sawError 用于 close() 判断是否需要合成补偿帧。
+            // 必须在 enqueue 之前更新，否则 consumer 收到首帧后立即退出循环时字段仍为空。
+            const framed = message;
+            if (framed.session_id && !this._sessionId) {
+                this._sessionId = framed.session_id;
+            }
+            const isRunStartedFrame = framed.type === 'system' && framed.subtype === 'run_started';
+            if (isRunStartedFrame && framed.run_id) {
+                // run_started 是权威的 run 起点：明确切换到新 run，并重置本 run 的累计状态。
+                // 这样即便未来在同一 transport 内跑多个 run，每次 run 的终止态判断都不会串扰。
+                if (this._currentRunId !== framed.run_id) {
+                    this._sawResult = false;
+                    this._sawError = false;
+                }
+                this._currentRunId = framed.run_id;
+                this._sawRunStarted = true;
+            }
+            else if (framed.run_id && !this._sawRunStarted) {
+                // 未启用 --emit-run-lifecycle 时的回退路径：从任意帧的 run_id 推断当前 run。
+                // 一旦见过 run_started，就以其为准，不再被其他帧的 run_id 覆写。
+                //
+                // 检测到 run_id 变化时，同步重置本 run 的累计终止态（sawResult / sawError）,
+                // 与 run_started 分支的处理对齐，避免旧 run 的终止信号污染新 run 的判定,
+                // 导致 close(cause) 误认为新 run 已正常结束而不合成补偿 error。
+                if (this._currentRunId && this._currentRunId !== framed.run_id) {
+                    this._sawResult = false;
+                    this._sawError = false;
+                }
+                this._currentRunId = framed.run_id;
+            }
+            if (framed.type === 'result') {
+                this._sawResult = true;
+            }
+            else if (framed.type === 'error') {
+                this._sawError = true;
+            }
             // Only regular messages are enqueued for consumer iteration
             if (this.messageStream) {
                 this.messageStream.enqueue(message);
@@ -797,7 +949,10 @@ class ProcessTransport {
         }
         this.pendingRequests.delete(response.request_id);
         if (response.subtype === 'error') {
-            pending.reject(new Error(response.error));
+            const error = (0, remote_error_codes_1.isRemoteErrorCode)(response.code)
+                ? new remote_error_codes_1.RemoteProtocolError(response.code, response.error)
+                : Object.assign(new Error(response.error), response.code ? { code: response.code } : {});
+            pending.reject(error);
         }
         else {
             pending.resolve(response.response ?? {});
@@ -808,21 +963,27 @@ class ProcessTransport {
         // Otherwise use a generic message — no setTimeout needed since
         // exit fires synchronously before close in Node.js child_process.
         this.setCloseReason('CLI process stdout closed unexpectedly');
-        this.close();
+        this.close('stdoutClosedUnexpectedly');
     }
     handleError(error) {
         this.setCloseReason(`CLI I/O error: ${error.message}`);
-        this.close();
+        this.close('stdoutClosedUnexpectedly');
     }
     handleProcessError(error) {
         this.setCloseReason(`CLI process spawn error: ${error.message}`);
-        this.close();
+        this.close('spawnError');
     }
     handleProcessExit(code) {
         const stderr = this._stderrBuffer.trim();
         const stderrSuffix = stderr ? ` | stderr: ${stderr.slice(-500)}` : '';
         this.setCloseReason(`CLI process exited with code ${code}${stderrSuffix}`);
-        this.close();
+        // 退出码为 0 且已观察到 result → 正常结束；
+        // 退出码为 0 但未观察到 result → CLI 在输出终止信号前提前退出，按异常处理以便下游归因；
+        // 退出码非 0 → 一律按异常处理。
+        const cause = code === 0
+            ? (this._sawResult ? 'sawResult' : 'processExitZeroBeforeResult')
+            : 'processExitNonZero';
+        this.close(cause);
     }
     setCloseReason(reason) {
         if (!this._closeReason) {
@@ -952,6 +1113,28 @@ class ProcessTransport {
         const { server_name, message } = mcpRequest;
         const transport = this.sdkMcpTransports.get(server_name);
         if (!transport) {
+            // in-process 未命中：尝试远程委托 bridge 回退（control ack 仍在本方法包装，不进 bridge）
+            const scopedKey = this.resolveDelegatedScopedKey(server_name);
+            if (this.managedRemoteMcpBridge && scopedKey && this.managedRemoteMcpBridge.isRegistered(scopedKey)) {
+                try {
+                    const anyMsg = message;
+                    const isRequest = 'id' in anyMsg && anyMsg.id !== null && anyMsg.id !== undefined;
+                    const result = await this.managedRemoteMcpBridge.handleMcpMessage(scopedKey, message);
+                    if (isRequest) {
+                        this.sendControlResponse(request.request_id, { mcp_response: result });
+                    }
+                    else {
+                        // notification：回 id-less sentinel 释放 CLI control pending
+                        this.sendControlResponse(request.request_id, {
+                            mcp_response: { jsonrpc: '2.0', result: {} },
+                        });
+                    }
+                }
+                catch (error) {
+                    this.sendControlErrorResponse(request.request_id, error instanceof Error ? error.message : String(error));
+                }
+                return;
+            }
             this.sendControlErrorResponse(request.request_id, `SDK MCP server not found: ${server_name}`);
             return;
         }
@@ -978,6 +1161,103 @@ class ProcessTransport {
             this.sendControlErrorResponse(request.request_id, error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * 注册远程委托 server（宿主驱动）。
+     *
+     * 首次调用时懒构造 ManagedRemoteMcpBridge：createTransport 由受管层注入（解析真实
+     * endpoint/token），redactResponse 接线为 redactDelegatedResponse（响应离开宿主回到 CLI
+     * 之前先脱敏）。随后对每个 descriptor 用与路由一致的 resolveDelegatedScopedKey 生成 scoped
+     * key 并注册，key 记入集合供 close 统一注销。
+     *
+     * 接线现状：ProcessTransport 构造期在 `delegatedMcpServers` + `mcpTransportFactory` 齐备时
+     * 自动调用本方法（host-driven v1 必做）。`unregisterAllDelegatedServers` 已接入
+     * close 兜底，control connection 关闭时统一释放 transport 与 pending。
+     */
+    registerDelegatedServers(descriptors, createTransport) {
+        if (!this.managedRemoteMcpBridge) {
+            // 审计出口：有 stderr 回调则写入（仅非 secret 的结构化事件），否则忽略。
+            const onAudit = (event) => {
+                this.options.stderr?.(`[mcp-delegation-audit] ${JSON.stringify(event)}\n`);
+            };
+            this.managedRemoteMcpBridge = new managed_remote_mcp_bridge_1.ManagedRemoteMcpBridge({
+                createTransport,
+                requestTimeoutMs: this.options.requestTimeoutMs ?? 30000,
+                // 组合脱敏：先做 schema fail-close 筛查（剔除含凭证形参的 tool），再做值级脱敏；
+                // 被拒 tool 经 onAudit 上报，不抛异常。
+                redactResponse: (scopedKey, message) => {
+                    const { message: safe, rejected } = (0, delegated_redaction_1.redactAndScreenDelegatedResponse)(message);
+                    if (rejected.length > 0) {
+                        onAudit({ type: 'delegated_tool_schema_rejected', scopedKey, rejected });
+                    }
+                    return safe;
+                },
+                onAudit,
+            });
+        }
+        for (const descriptor of descriptors) {
+            const scopedKey = this.resolveDelegatedScopedKey(descriptor.serverName);
+            if (!scopedKey) {
+                continue;
+            }
+            this.managedRemoteMcpBridge.registerDelegatedServer(scopedKey, {
+                transport: descriptor.transport,
+                capabilityId: descriptor.capabilityId,
+            });
+            this.registeredDelegatedScopedKeys.add(scopedKey);
+        }
+    }
+    /**
+     * 注销所有已注册的委托 server（reject 在途 pending、关闭真实 transport）。
+     * 由 close 调用；单个注销失败不阻塞其他。
+     */
+    unregisterAllDelegatedServers() {
+        if (!this.managedRemoteMcpBridge) {
+            return;
+        }
+        for (const scopedKey of this.registeredDelegatedScopedKeys) {
+            this.managedRemoteMcpBridge.unregisterDelegatedServer(scopedKey).catch(() => {
+                // 清理阶段忽略单个注销错误
+            });
+        }
+        this.registeredDelegatedScopedKeys.clear();
+    }
+    /**
+     * 组合远程委托 server 的 scoped key。
+     *
+     * 完整 scoped key 语义是 control connection / tenant / user / session / run + serverName。
+     * 本 transport 从 ProcessTransportOptions 拿到 controlConnectionId /
+     * tenantId / userId / sessionId / runId，按字符集校验后用分隔符 `::` 拼接，缺失维度直接跳过
+     * （不写空段，避免 `::` 退化成空字符串导致跨 scope 撞 key）。所有维度都缺时才退化为裸
+     * serverName——这是最后兜底，部署方应至少注入 controlConnectionId / sessionId 之一。
+     * 注册与路由必须复用这同一组合逻辑，两侧的 key 才能一致。
+     */
+    resolveDelegatedScopedKey(serverName) {
+        const segments = [];
+        const push = (v, label) => {
+            if (typeof v === 'string' && v.length > 0) {
+                if (!/^[A-Za-z0-9_.:-]+$/.test(v)) {
+                    // 非法字符：跳过该维度并记审计，避免拼出含分隔符冲突的 scoped key。
+                    this.options.stderr?.(`[mcp-delegation-audit] scoped key segment "${label}" has invalid chars, skipped\n`);
+                    return;
+                }
+                segments.push(v);
+            }
+        };
+        push(this.options.controlConnectionId, 'controlConnectionId');
+        push(this.options.tenantId, 'tenantId');
+        push(this.options.userId, 'userId');
+        push(this.options.sessionId, 'sessionId');
+        push(this.options.runId, 'runId');
+        push(serverName, 'serverName');
+        if (segments.length === 0) {
+            return undefined;
+        }
+        if (segments.length === 1) {
+            // 仅 serverName 可用：兜底返回裸 serverName（部署方未注入 scope 维度的退化场景）。
+            return serverName;
+        }
+        return segments.join('::');
+    }
     /**
      * Handle MCP request and wait for response from MCP server.
      */