@qwen-code/channel-base 0.26.4 → 0.26.5

package/dist/AcpBridge.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { RequestPermissionResponse } from '@agentclientprotocol/sdk';
-import { type AvailableCommand, type ChannelAgentBridge, type ChannelBtwResult, type ChannelAgentBridgePromptOptions, type ChannelAgentBridgeSessionOptions, type ChannelLoopToolHandler } from './ChannelAgentBridge.js';
+import { type AvailableCommand, type ChannelAgentBridge, type ChannelBtwResult, type ChannelAgentBridgePromptOptions, type ChannelAgentBridgeSessionOptions, type ChannelLoopToolHandler, type ChannelToolDefinition } from './ChannelAgentBridge.js';
 export type { AvailableCommand, ToolCallEvent } from './ChannelAgentBridge.js';
 export interface AcpBridgeOptions {
     cliEntryPath: string;
@@ -9,6 +9,14 @@ export interface AcpBridgeOptions {
 }
 export declare const ACP_EVENT_LOOP_STALL_RESTART_MS: number;
 export declare const ACP_START_TIMEOUT_MS: number;
+/**
+ * Bound for the session-scoped channel_loop MCP runtime add/remove. The add is
+ * not a local write: the child discovers the server inside the call and drives
+ * `initialize`/`tools/list` back into this bridge, so a stalled child would
+ * otherwise hang session creation (and with it every later message for that
+ * chat) with no stderr line.
+ */
+export declare const CHANNEL_TOOL_BIND_TIMEOUT_MS: number;
 export declare const ACP_PERMISSION_RESPONSE_TIMEOUT_MS: number;
 /**
  * Read a command's aliases off a raw wire `available_commands_update` entry. ACP
@@ -24,16 +32,61 @@ export declare class AcpBridge extends EventEmitter implements ChannelAgentBridg
     private _availableCommands;
     private channelLoopMcpServer;
     private readonly channelLoopToolHandlers;
+    private readonly channelTools;
+    /** Channel instance that owns each session, for adapter-tool scoping. */
+    private readonly sessionOwners;
     private readonly knownSessionIds;
     private readonly sessionBindingTokens;
     private readonly toolCallKindsBySession;
-    private channelLoopMcpRegistered;
-    private channelLoopMcpRegistration;
+    /**
+     * Sessions this bridge bound the channel_loop MCP server to. The binding is
+     * the session's channel-tool identity: a `client_mcp/message` frame is served
+     * only for a session in this ledger, never because the frame names one.
+     */
+    private readonly channelLoopMcpBoundSessions;
+    /**
+     * Ownership token of the bind attempt that added each session to the bound
+     * ledger. A bind can outlive a discard/reload of its session, so a failed
+     * attempt must only release a claim it still owns.
+     */
+    private readonly channelLoopMcpBindClaims;
+    /** In-flight per-session bindings, so one session binds once. */
+    private readonly channelLoopMcpBindings;
     private readonly pendingPermissions;
     constructor(options: AcpBridgeOptions);
     get availableCommands(): AvailableCommand[];
     start(): Promise<void>;
     registerChannelLoopToolHandler(handler: ChannelLoopToolHandler): void;
+    registerChannelTool(tool: ChannelToolDefinition): void;
+    /**
+     * Shared registration guard: one tool per name per owning channel, and never
+     * a name the built-in channel_loop_* tools already own. Two instances of the
+     * same channel type register the same names, so the owner scopes the entry
+     * instead of the second registration being dropped.
+     */
+    private addChannelTool;
+    /**
+     * Adapter tools one bound session may see. Visibility follows the session's
+     * channel: a session this bridge bound the server to sees its owner's tools
+     * plus the ownerless ones; a session that never bound it sees nothing.
+     */
+    private channelToolsForSession;
+    /**
+     * Channel-tool identity for one `client_mcp/message` frame. The frame's
+     * `sessionId` is a carrier, not a credential: it resolves only when this
+     * bridge itself bound the channel_loop server to that session, so an id the
+     * bridge never bound resolves to nothing and no channel tool can run.
+     *
+     * This is a membership check, not a transport check: every id in the bound
+     * ledger resolves, so a bound session that named another bound session would
+     * be treated as that one. The child injects the id into its own reverse
+     * frames and the model cannot set it, which is what makes the ledger — not
+     * the frame — the authority on which chat a call may touch.
+     */
+    private boundSessionId;
+    /** Bind the channel_loop server to every session this bridge already knows. */
+    private bindKnownSessions;
+    private ensureChannelToolServer;
     private applySessionApprovalMode;
     newSession(cwd: string, options?: ChannelAgentBridgeSessionOptions, bindingToken?: object): Promise<string>;
     loadSession(sessionId: string, cwd: string, options?: ChannelAgentBridgeSessionOptions, bindingToken?: object): Promise<string>;
@@ -50,9 +103,29 @@ export declare class AcpBridge extends EventEmitter implements ChannelAgentBridg
     private emitResponseBoundary;
     private resolvePendingPermissions;
     private maybeKillOnEventLoopStall;
+    /**
+     * Bind the channel_loop SDK MCP server to ONE session through the child's
+     * session-scoped runtime-add. The child then drives that server through the
+     * session's own `sendSdkMcpMessage`, so its reverse frames carry the session
+     * id, and the binding here is what makes that id trustworthy.
+     */
     private registerChannelLoopMcpServer;
+    private bindChannelLoopMcpServer;
+    /**
+     * Release a failed bind's optimistic claim, but only while this attempt
+     * still owns it: a newer bind for the same session may have claimed it.
+     */
+    private releaseChannelLoopMcpBindClaim;
+    private removeChannelLoopMcpServer;
     private handleExtMethod;
     private handleClientMcpMessage;
+    /**
+     * `QWEN_CHANNEL_TOOL_DIAG=1` trace of one `client_mcp/message` frame: which
+     * method it is, which session id the frame carried, whether this bridge had
+     * bound that session, and what the reply contained. Off by default because
+     * the read runs per frame on a hot path.
+     */
+    private logChannelToolDiagnostic;
     private resolveChannelLoopToolHandler;
 }
 //# sourceMappingURL=AcpBridge.d.ts.map

package/dist/AcpBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcpBridge.d.ts","sourceRoot":"","sources":["../src/AcpBridge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,KAAK,EAIV,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAaL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,+BAA+B,EACpC,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAC;AAUjC,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM/E,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,+BAA+B,QAAgB,CAAC;AAC7D,eAAO,MAAM,oBAAoB,QAAY,CAAC;AAC9C,eAAO,MAAM,kCAAkC,QAAgB,CAAC;AAIhE;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,OAAO,GACX,MAAM,EAAE,GAAG,SAAS,CAgBtB;AAED,qBAAa,SAAU,SAAQ,YAAa,YAAW,kBAAkB;IACvE,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,kBAAkB,CAA0B;IACpD,OAAO,CAAC,oBAAoB,CAAmC;IAC/D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAgC;IACxE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAyC;IAC9E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAGnC;IACJ,OAAO,CAAC,wBAAwB,CAAS;IACzC,OAAO,CAAC,0BAA0B,CAA8B;IAChE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAO/B;gBAEQ,OAAO,EAAE,gBAAgB;IAKrC,IAAI,iBAAiB,IAAI,gBAAgB,EAAE,CAE1C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwG5B,8BAA8B,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI;YAevD,wBAAwB;IAoBhC,UAAU,CACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gCAAgC,EAC1C,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC;IAcZ,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gCAAgC,EAC1C,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC;IAcZ,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,MAAM,CAAC;IAwEZ,GAAG,CACP,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC;IA0BtB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,oBAAoB,CAAC,EAAE,MAAM,GAC5B,OAAO,CAAC,IAAI,CAAC;IAiBV,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,yBAAyB,GAClC,OAAO,CAAC,OAAO,CAAC;IAenB,IAAI,IAAI,IAAI;IAYZ,IAAI,WAAW,IAAI,OAAO,CAIzB;IAED,OAAO,CAAC,mBAAmB;IA0I3B,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,yBAAyB;YAoBnB,4BAA4B;YA2C5B,eAAe;YAqBf,sBAAsB;IA4BpC,OAAO,CAAC,6BAA6B;CAmBtC"}
+{"version":3,"file":"AcpBridge.d.ts","sourceRoot":"","sources":["../src/AcpBridge.ts"],"names":[],"mappings":"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"}

package/dist/AcpBridge.js

@@ -4,12 +4,27 @@ import { Readable, Writable } from 'node:stream';
 import { EventEmitter } from 'node:events';
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
 import { ACP_PRIVATE_PARENT_CAPABILITY_ENV, ACP_PRIVATE_PARENT_CAPABILITY_META_KEY, CHANNEL_BTW_METHOD, CHANNEL_PROMPT_DISPLAY_TEXT_META_KEY, CHANNEL_PROMPT_META_KEY, CHANNEL_OUTPUT_MODE_META_KEY, CHANNEL_TASK_RESULT_META_KEY, CHANNEL_TASK_RESULT_PARTIAL_META_KEY, CHANNEL_TASK_OUTPUT_META_KEY, ChannelPromptCancelledError, parseBackgroundResponseContext, resolvePromptImages, } from './ChannelAgentBridge.js';
-import { CHANNEL_LOOP_MCP_SERVER_NAME, CLIENT_MCP_MESSAGE_METHOD, CLIENT_MCP_OVER_WS_CONFIG_FLAG, ChannelLoopMcpServer, WORKSPACE_MCP_RUNTIME_ADD_METHOD, } from './ChannelLoopTools.js';
+import { CHANNEL_LOOP_MCP_SERVER_NAME, CHANNEL_LOOP_MCP_TOOLS, CLIENT_MCP_MESSAGE_METHOD, CLIENT_MCP_OVER_WS_CONFIG_FLAG, ChannelLoopMcpServer, SESSION_MCP_RUNTIME_ADD_METHOD, SESSION_MCP_RUNTIME_REMOVE_METHOD, selectChannelToolsForSession, } from './ChannelLoopTools.js';
 import { sanitizeLogText } from './sanitize.js';
 const MID_TURN_QUEUE_DRAIN_METHOD = 'craft/drainMidTurnQueue';
 const TODO_STOP_GUARD_CONTINUATION_CLAIM_METHOD = 'craft/claimTodoStopGuardContinuation';
+/**
+ * Opt-in trace of the session→owner resolution the channel tool surface
+ * depends on. An unresolvable session silently narrows `tools/list` to no
+ * tools, which is invisible in the model transcript, so operators need a
+ * switch that costs nothing when unset.
+ */
+const CHANNEL_TOOL_DIAG_ENV = 'QWEN_CHANNEL_TOOL_DIAG';
 export const ACP_EVENT_LOOP_STALL_RESTART_MS = 5 * 60 * 1000;
 export const ACP_START_TIMEOUT_MS = 30 * 1000;
+/**
+ * Bound for the session-scoped channel_loop MCP runtime add/remove. The add is
+ * not a local write: the child discovers the server inside the call and drives
+ * `initialize`/`tools/list` back into this bridge, so a stalled child would
+ * otherwise hang session creation (and with it every later message for that
+ * chat) with no stderr line.
+ */
+export const CHANNEL_TOOL_BIND_TIMEOUT_MS = 30 * 1000;
 export const ACP_PERMISSION_RESPONSE_TIMEOUT_MS = 5 * 60 * 1000;
 const ACP_EVENT_LOOP_STALL_RE = /^\[perf\] acp agent event loop stall: max=(\d+(?:\.\d+)?)ms/m;
 /**
@@ -43,11 +58,26 @@ export class AcpBridge extends EventEmitter {
     _availableCommands = [];
     channelLoopMcpServer;
     channelLoopToolHandlers = [];
+    channelTools = [];
+    /** Channel instance that owns each session, for adapter-tool scoping. */
+    sessionOwners = new Map();
     knownSessionIds = new Set();
     sessionBindingTokens = new Map();
     toolCallKindsBySession = new Map();
-    channelLoopMcpRegistered = false;
-    channelLoopMcpRegistration = null;
+    /**
+     * Sessions this bridge bound the channel_loop MCP server to. The binding is
+     * the session's channel-tool identity: a `client_mcp/message` frame is served
+     * only for a session in this ledger, never because the frame names one.
+     */
+    channelLoopMcpBoundSessions = new Set();
+    /**
+     * Ownership token of the bind attempt that added each session to the bound
+     * ledger. A bind can outlive a discard/reload of its session, so a failed
+     * attempt must only release a claim it still owns.
+     */
+    channelLoopMcpBindClaims = new Map();
+    /** In-flight per-session bindings, so one session binds once. */
+    channelLoopMcpBindings = new Map();
     pendingPermissions = new Map();
     constructor(options) {
         super();
@@ -94,6 +124,10 @@ export class AcpBridge extends EventEmitter {
             this.resolvePendingPermissions();
             this.knownSessionIds.clear();
             this.sessionBindingTokens.clear();
+            this.sessionOwners.clear();
+            this.channelLoopMcpBoundSessions.clear();
+            this.channelLoopMcpBindClaims.clear();
+            this.channelLoopMcpBindings.clear();
             this.toolCallKindsBySession.clear();
             this.connection = null;
             this.child = null;
@@ -124,7 +158,6 @@ export class AcpBridge extends EventEmitter {
                     [ACP_PRIVATE_PARENT_CAPABILITY_META_KEY]: privateParentCapability,
                 },
             }), ACP_START_TIMEOUT_MS, `ACP initialization timed out after ${ACP_START_TIMEOUT_MS}ms`);
-            await this.registerChannelLoopMcpServer();
         }
         catch (error) {
             this.stop();
@@ -135,12 +168,81 @@ export class AcpBridge extends EventEmitter {
         if (!this.channelLoopToolHandlers.includes(handler)) {
             this.channelLoopToolHandlers.push(handler);
         }
-        this.channelLoopMcpServer ??= new ChannelLoopMcpServer({
+        this.ensureChannelToolServer();
+        this.bindKnownSessions();
+    }
+    registerChannelTool(tool) {
+        if (!this.addChannelTool(tool))
+            return;
+        this.ensureChannelToolServer();
+        this.bindKnownSessions();
+    }
+    /**
+     * Shared registration guard: one tool per name per owning channel, and never
+     * a name the built-in channel_loop_* tools already own. Two instances of the
+     * same channel type register the same names, so the owner scopes the entry
+     * instead of the second registration being dropped.
+     */
+    addChannelTool(tool) {
+        if (CHANNEL_LOOP_MCP_TOOLS.some((loopTool) => loopTool.name === tool.name)) {
+            process.stderr.write(`[AcpBridge] Channel tool "${sanitizeLogText(tool.name, 64)}" ignored: name is reserved for the built-in channel loop tools\n`);
+            return false;
+        }
+        if (this.channelTools.some((existing) => existing.name === tool.name && existing.owner === tool.owner)) {
+            process.stderr.write(`[AcpBridge] Channel tool "${sanitizeLogText(tool.name, 64)}" ignored: already registered for owner "${sanitizeLogText(tool.owner ?? '', 64)}"\n`);
+            return false;
+        }
+        this.channelTools.push(tool);
+        return true;
+    }
+    /**
+     * Adapter tools one bound session may see. Visibility follows the session's
+     * channel: a session this bridge bound the server to sees its owner's tools
+     * plus the ownerless ones; a session that never bound it sees nothing.
+     */
+    channelToolsForSession(sessionId) {
+        if (sessionId.length === 0 ||
+            !this.channelLoopMcpBoundSessions.has(sessionId)) {
+            return [];
+        }
+        return selectChannelToolsForSession(this.channelTools, this.sessionOwners.get(sessionId));
+    }
+    /**
+     * Channel-tool identity for one `client_mcp/message` frame. The frame's
+     * `sessionId` is a carrier, not a credential: it resolves only when this
+     * bridge itself bound the channel_loop server to that session, so an id the
+     * bridge never bound resolves to nothing and no channel tool can run.
+     *
+     * This is a membership check, not a transport check: every id in the bound
+     * ledger resolves, so a bound session that named another bound session would
+     * be treated as that one. The child injects the id into its own reverse
+     * frames and the model cannot set it, which is what makes the ledger — not
+     * the frame — the authority on which chat a call may touch.
+     */
+    boundSessionId(params) {
+        const sessionId = params['sessionId'];
+        return typeof sessionId === 'string' &&
+            this.channelLoopMcpBoundSessions.has(sessionId)
+            ? sessionId
+            : undefined;
+    }
+    /** Bind the channel_loop server to every session this bridge already knows. */
+    bindKnownSessions() {
+        for (const sessionId of this.knownSessionIds) {
+            if (!this.channelLoopMcpBoundSessions.has(sessionId)) {
+                void this.registerChannelLoopMcpServer(sessionId);
+            }
+        }
+    }
+    ensureChannelToolServer() {
+        return (this.channelLoopMcpServer ??= new ChannelLoopMcpServer({
             create: (sessionId, input) => this.resolveChannelLoopToolHandler(sessionId).create(sessionId, input),
             list: (sessionId) => this.resolveChannelLoopToolHandler(sessionId).list(sessionId),
             cancel: (sessionId, id) => this.resolveChannelLoopToolHandler(sessionId).cancel(sessionId, id),
-        });
-        void this.registerChannelLoopMcpServer();
+        }, {
+            extraTools: (sessionId) => this.channelToolsForSession(sessionId),
+            loopToolsEnabled: () => this.channelLoopToolHandlers.length > 0,
+        }));
     }
     async applySessionApprovalMode(conn, sessionId, approvalMode) {
         if (!approvalMode)
@@ -159,16 +261,18 @@ export class AcpBridge extends EventEmitter {
     }
     async newSession(cwd, options, bindingToken) {
         const conn = this.ensureConnection();
-        await this.registerChannelLoopMcpServer();
         const response = await conn.newSession({ cwd, mcpServers: [] });
         await this.applySessionApprovalMode(conn, response.sessionId, options?.approvalMode);
         this.knownSessionIds.add(response.sessionId);
         this.sessionBindingTokens.set(response.sessionId, bindingToken);
+        if (options?.sourceId) {
+            this.sessionOwners.set(response.sessionId, options.sourceId);
+        }
+        await this.registerChannelLoopMcpServer(response.sessionId);
         return response.sessionId;
     }
     async loadSession(sessionId, cwd, options, bindingToken) {
         const conn = this.ensureConnection();
-        await this.registerChannelLoopMcpServer();
         await conn.unstable_resumeSession({
             sessionId,
             cwd,
@@ -177,10 +281,23 @@ export class AcpBridge extends EventEmitter {
         await this.applySessionApprovalMode(conn, sessionId, options?.approvalMode);
         this.knownSessionIds.add(sessionId);
         this.sessionBindingTokens.set(sessionId, bindingToken);
+        if (options?.sourceId) {
+            this.sessionOwners.set(sessionId, options.sourceId);
+        }
+        await this.registerChannelLoopMcpServer(sessionId);
         return sessionId;
     }
     async prompt(sessionId, text, options) {
         const conn = this.ensureConnection();
+        // A binding skipped at session creation (MCP budget, one transient
+        // runtime-add failure) must not cost the session every channel tool for its
+        // lifetime. Retry it on the next turn, fire-and-forget so a slow or skipped
+        // bind never delays the prompt; registerChannelLoopMcpServer is idempotent
+        // and deduplicates concurrent attempts.
+        if (this.knownSessionIds.has(sessionId) &&
+            !this.channelLoopMcpBoundSessions.has(sessionId)) {
+            void this.registerChannelLoopMcpServer(sessionId);
+        }
         const chunks = [];
         let slashCommandOutput = '';
         const onChunk = (sid, chunk) => {
@@ -284,11 +401,18 @@ export class AcpBridge extends EventEmitter {
         if (!this.knownSessionIds.delete(sessionId))
             return;
         this.sessionBindingTokens.delete(sessionId);
+        this.sessionOwners.delete(sessionId);
         this.toolCallKindsBySession.delete(sessionId);
+        this.channelLoopMcpBindings.delete(sessionId);
+        this.channelLoopMcpBindClaims.delete(sessionId);
+        const wasBound = this.channelLoopMcpBoundSessions.delete(sessionId);
         this.resolvePendingPermissions(sessionId);
         const conn = this.connection;
         if (!conn || !this.isConnected)
             return;
+        if (wasBound) {
+            await this.removeChannelLoopMcpServer(conn, sessionId);
+        }
         await conn.extMethod('qwen/control/session/close', { sessionId });
     }
     async respondToPermission(requestId, response) {
@@ -309,6 +433,10 @@ export class AcpBridge extends EventEmitter {
         this.resolvePendingPermissions();
         this.knownSessionIds.clear();
         this.sessionBindingTokens.clear();
+        this.sessionOwners.clear();
+        this.channelLoopMcpBoundSessions.clear();
+        this.channelLoopMcpBindClaims.clear();
+        this.channelLoopMcpBindings.clear();
         this.toolCallKindsBySession.clear();
         if (this.child) {
             this.child.kill();
@@ -500,41 +628,82 @@ export class AcpBridge extends EventEmitter {
         process.stderr.write(`[AcpBridge] ACP agent event loop stalled for ${Math.round(maxMs)}ms; killing child process to trigger restart\n`);
         child.kill('SIGKILL');
     }
-    async registerChannelLoopMcpServer() {
-        if (!this.connection ||
-            !this.channelLoopMcpServer ||
-            this.channelLoopMcpRegistered) {
-            return;
+    /**
+     * Bind the channel_loop SDK MCP server to ONE session through the child's
+     * session-scoped runtime-add. The child then drives that server through the
+     * session's own `sendSdkMcpMessage`, so its reverse frames carry the session
+     * id, and the binding here is what makes that id trustworthy.
+     */
+    async registerChannelLoopMcpServer(sessionId) {
+        if (!this.connection || !this.channelLoopMcpServer)
+            return false;
+        const inFlight = this.channelLoopMcpBindings.get(sessionId);
+        if (inFlight)
+            return inFlight;
+        if (this.channelLoopMcpBoundSessions.has(sessionId))
+            return true;
+        const binding = this.bindChannelLoopMcpServer(sessionId).finally(() => {
+            if (this.channelLoopMcpBindings.get(sessionId) === binding) {
+                this.channelLoopMcpBindings.delete(sessionId);
+            }
+        });
+        this.channelLoopMcpBindings.set(sessionId, binding);
+        return binding;
+    }
+    async bindChannelLoopMcpServer(sessionId) {
+        // Claim the binding before the runtime-add can answer: the child discovers
+        // the newly added server inside that call, so its `tools/list` frame can
+        // arrive before the add resolves, and it must already resolve here.
+        this.channelLoopMcpBoundSessions.add(sessionId);
+        // The claim is ownership-checked: a discard can drop it and a reload can
+        // bind the same session again while this attempt is still in flight, so a
+        // late failure must not erase the newer attempt's claim.
+        const claim = {};
+        this.channelLoopMcpBindClaims.set(sessionId, claim);
+        try {
+            const result = await withTimeout(this.connection.extMethod(SESSION_MCP_RUNTIME_ADD_METHOD, {
+                sessionId,
+                name: CHANNEL_LOOP_MCP_SERVER_NAME,
+                originatorClientId: 'channel',
+                config: {
+                    type: 'sdk',
+                    [CLIENT_MCP_OVER_WS_CONFIG_FLAG]: true,
+                },
+            }), CHANNEL_TOOL_BIND_TIMEOUT_MS, `channel loop MCP bind timed out after ${CHANNEL_TOOL_BIND_TIMEOUT_MS}ms`);
+            if (isSkippedMcpRegistration(result)) {
+                this.releaseChannelLoopMcpBindClaim(sessionId, claim);
+                process.stderr.write(`[AcpBridge] Channel loop MCP server binding for session ${sanitizeLogText(sessionId, 128)} skipped${formatSkippedRegistrationReason(result)}\n`);
+                return false;
+            }
+            return true;
         }
-        if (this.channelLoopMcpRegistration) {
-            await this.channelLoopMcpRegistration;
+        catch (error) {
+            this.releaseChannelLoopMcpBindClaim(sessionId, claim);
+            process.stderr.write(`[AcpBridge] Failed to bind channel loop MCP server to session ${sanitizeLogText(sessionId, 128)}: ${sanitizeLogText(error instanceof Error ? error.message : String(error), 512)}\n`);
+            return false;
+        }
+    }
+    /**
+     * Release a failed bind's optimistic claim, but only while this attempt
+     * still owns it: a newer bind for the same session may have claimed it.
+     */
+    releaseChannelLoopMcpBindClaim(sessionId, claim) {
+        if (this.channelLoopMcpBindClaims.get(sessionId) !== claim)
             return;
+        this.channelLoopMcpBindClaims.delete(sessionId);
+        this.channelLoopMcpBoundSessions.delete(sessionId);
+    }
+    async removeChannelLoopMcpServer(conn, sessionId) {
+        try {
+            await withTimeout(conn.extMethod(SESSION_MCP_RUNTIME_REMOVE_METHOD, {
+                sessionId,
+                name: CHANNEL_LOOP_MCP_SERVER_NAME,
+                originatorClientId: 'channel',
+            }), CHANNEL_TOOL_BIND_TIMEOUT_MS, `channel loop MCP unbind timed out after ${CHANNEL_TOOL_BIND_TIMEOUT_MS}ms`);
+        }
+        catch (error) {
+            process.stderr.write(`[AcpBridge] Failed to remove channel loop MCP server from session ${sanitizeLogText(sessionId, 128)}: ${sanitizeLogText(error instanceof Error ? error.message : String(error), 512)}\n`);
         }
-        this.channelLoopMcpRegistration = this.connection
-            .extMethod(WORKSPACE_MCP_RUNTIME_ADD_METHOD, {
-            name: CHANNEL_LOOP_MCP_SERVER_NAME,
-            originatorClientId: 'channel',
-            config: {
-                type: 'sdk',
-                [CLIENT_MCP_OVER_WS_CONFIG_FLAG]: true,
-            },
-        })
-            .then((result) => {
-            if (isSkippedMcpRegistration(result)) {
-                this.channelLoopMcpRegistered = false;
-                process.stderr.write(`[AcpBridge] Channel loop MCP server registration skipped${formatSkippedRegistrationReason(result)}\n`);
-                return;
-            }
-            this.channelLoopMcpRegistered = true;
-        })
-            .catch((error) => {
-            this.channelLoopMcpRegistered = false;
-            process.stderr.write(`[AcpBridge] Failed to register channel loop MCP server: ${error instanceof Error ? error.message : String(error)}\n`);
-        })
-            .finally(() => {
-            this.channelLoopMcpRegistration = null;
-        });
-        await this.channelLoopMcpRegistration;
     }
     async handleExtMethod(method, params) {
         if (method === CLIENT_MCP_MESSAGE_METHOD) {
@@ -564,15 +733,72 @@ export class AcpBridge extends EventEmitter {
         if (typeof payload !== 'object' || payload === null) {
             throw new Error('Invalid client MCP payload.');
         }
-        const sessionId = typeof params['sessionId'] === 'string'
-            ? params['sessionId']
+        const sessionId = this.boundSessionId(params);
+        const rawSessionId = params['sessionId'];
+        const carriedSessionId = sessionId === undefined &&
+            typeof rawSessionId === 'string' &&
+            rawSessionId.length > 0
+            ? rawSessionId
             : undefined;
-        const response = await this.channelLoopMcpServer.handleMessage(payload, { sessionId });
+        const response = await this.channelLoopMcpServer.handleMessage(payload, { sessionId, carriedSessionId });
+        this.logChannelToolDiagnostic(params, sessionId, response);
         if (!response) {
             return { payload: { jsonrpc: '2.0', id: 0, result: {} } };
         }
         return { payload: response };
     }
+    /**
+     * `QWEN_CHANNEL_TOOL_DIAG=1` trace of one `client_mcp/message` frame: which
+     * method it is, which session id the frame carried, whether this bridge had
+     * bound that session, and what the reply contained. Off by default because
+     * the read runs per frame on a hot path.
+     */
+    logChannelToolDiagnostic(params, sessionId, response) {
+        if (process.env[CHANNEL_TOOL_DIAG_ENV] !== '1')
+            return;
+        const payload = params['payload'];
+        const message = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const method = typeof message?.['method'] === 'string'
+            ? message['method']
+            : '<none>';
+        if (method !== 'tools/list' && method !== 'tools/call')
+            return;
+        const rawSessionId = params['sessionId'];
+        const carried = typeof rawSessionId === 'string' && rawSessionId.length > 0
+            ? rawSessionId
+            : undefined;
+        // A known-but-unbound session is exactly the state this switch exists to
+        // explain, so resolve the owner from the id the frame carried too. An id
+        // in neither ledger acquires nothing (fail closed).
+        const ownerId = sessionId ??
+            (carried !== undefined && this.knownSessionIds.has(carried)
+                ? carried
+                : undefined);
+        const owner = ownerId === undefined ? undefined : this.sessionOwners.get(ownerId);
+        const result = response?.['result'];
+        const resultRecord = typeof result === 'object' && result !== null
+            ? result
+            : undefined;
+        const listed = resultRecord?.['tools'];
+        const rpcError = response?.['error'];
+        let detail;
+        if (method === 'tools/list') {
+            detail = `tools=${Array.isArray(listed) ? listed.length : '?'}`;
+        }
+        else {
+            // The tool name is what separates a loop-handler failure from a platform
+            // failure; the JSON-RPC error arm never carries a result, so read it
+            // alongside the result arm or a failed call looks like a success.
+            const toolName = readToolCallName(message);
+            detail =
+                `tool=${toolName === undefined ? '<none>' : sanitizeLogText(toolName, 64)}` +
+                    ` isError=${resultRecord?.['isError'] === true || rpcError !== undefined}` +
+                    ` rpcError=${rpcError === undefined ? 'none' : sanitizeLogText(describeRpcError(rpcError), 256)}`;
+        }
+        process.stderr.write(`[AcpBridge] channel-tool-diag method=${method} sessionId=${carried === undefined ? '<absent>' : sanitizeLogText(carried, 128)} bound=${sessionId !== undefined} known=${carried !== undefined && this.knownSessionIds.has(carried)} owner=${owner === undefined ? '<none>' : sanitizeLogText(owner, 64)} ${detail}\n`);
+    }
     resolveChannelLoopToolHandler(sessionId) {
         if (this.channelLoopToolHandlers.length === 1 &&
             !this.channelLoopToolHandlers[0].canHandle) {
@@ -623,6 +849,23 @@ function createAbortError() {
     error.name = 'AbortError';
     return error;
 }
+/** Tool name a `tools/call` payload names, for the diagnostic trace. */
+function readToolCallName(message) {
+    const callParams = message?.['params'];
+    if (typeof callParams !== 'object' || callParams === null)
+        return undefined;
+    const name = callParams['name'];
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+/** Stringify a JSON-RPC error reply for the diagnostic trace. */
+function describeRpcError(error) {
+    try {
+        return JSON.stringify(error) ?? String(error);
+    }
+    catch {
+        return String(error);
+    }
+}
 function isSkippedMcpRegistration(result) {
     return (typeof result === 'object' &&
         result !== null &&