agent-gear 1.1.5 → 1.1.7

package/src/acp/bridge.ts

@@ -8,7 +8,9 @@ const ACP_PROTOCOL_VERSION = 1;
 export interface AcpBridgeOptions {
   sessionId: string;
   cwd: string;
+  additionalDirectories?: string[];
   mcpServers?: Array<{ name: string; command: string; args?: string[]; env?: Array<{ name: string; value: string }> }>;
+  mcpEndpoint?: { url: string; token: string; serverNames: string[] };
 }
 
 interface QueuedInput {
@@ -16,6 +18,39 @@ interface QueuedInput {
   content: string;
 }
 
+export interface SessionConfigOptionData {
+  id: string;
+  name: string;
+  description?: string | null;
+  category?: string | null;
+  type: 'select' | 'boolean';
+  currentValue: string | null;
+  options: Array<{ value: string; name?: string }>;
+}
+
+export interface AcpAuthMethodData {
+  id: string;
+  kind: 'env_var' | 'terminal' | 'agent' | null;
+  description?: string | null;
+  url?: string | null;
+}
+
+export interface AcpInitializedPayload {
+  sessionId: string;
+  acpSessionId: string | null;
+  modes: Array<{ id: string; name: string; description?: string }>;
+  currentModeId: string | null;
+  currentModel: { id: string; name: string; provider?: string } | null;
+  availableModels: Array<{ id: string; name: string; provider?: string }>;
+  currentModelId: string | null;
+  configOptions: SessionConfigOptionData[];
+  promptCapabilities: { image: boolean; audio: boolean; embeddedContext: boolean } | null;
+  agentInfo: { name: string; version?: string | null } | null;
+  authMethods: AcpAuthMethodData[];
+  supportsAdditionalDirectories: boolean;
+  protocolVersion?: number | null;
+}
+
 function toMcpServers(servers: AcpBridgeOptions['mcpServers']): acp.McpServer[] {
   return (servers ?? []).map((s) => ({
     name: s.name,
@@ -25,17 +60,138 @@ function toMcpServers(servers: AcpBridgeOptions['mcpServers']): acp.McpServer[]
   }));
 }
 
+// Sanitized, token-free summary of the MCP servers about to be sent to the
+// agent, so launch failures are diagnosable from local logs alone.
+function describeMcpServersForLog(servers: acp.McpServer[]): string {
+  if (servers.length === 0) return 'none';
+  return servers.map((s) => {
+    if ('url' in s) {
+      const headerNames = (s.headers ?? []).map((h) => h.name).join('+');
+      return `${s.name}(type=${(s as { type?: string }).type ?? 'http'}, url=${s.url}${headerNames ? `, headers=${headerNames}` : ''})`;
+    }
+    return `${s.name}(type=stdio, cmd=${(s as { command?: string }).command})`;
+  }).join(' ');
+}
+
+function toMcpEndpointServers(mcpEndpoint: NonNullable<AcpBridgeOptions['mcpEndpoint']>): acp.McpServer[] {
+  // Fail loudly with a diagnosable message instead of a raw TypeError when the
+  // upstream payload drifts from the contract (serverNames is required).
+  if (!Array.isArray(mcpEndpoint.serverNames) || mcpEndpoint.serverNames.length === 0) {
+    throw new Error(
+      `Invalid mcpEndpoint payload: "serverNames" must be a non-empty array ` +
+      `(received: ${JSON.stringify(mcpEndpoint.serverNames)}, url: ${mcpEndpoint.url})`,
+    );
+  }
+  const headers: acp.HttpHeader[] = [{ name: 'Authorization', value: `Bearer ${mcpEndpoint.token}` }];
+  // Each assembled server gets its own URL so the entry point can route
+  // standard MCP clients (which never send a serverName param) correctly.
+  return mcpEndpoint.serverNames.map((name) => ({
+    type: 'http' as const,
+    name,
+    url: `${mcpEndpoint.url}/${encodeURIComponent(name)}`,
+    headers,
+  }));
+}
+
+export function extractConfigOptions(
+  configOptions: acp.SessionConfigOption[] | null | undefined,
+): SessionConfigOptionData[] {
+  if (!configOptions) return [];
+  return configOptions.map((opt) => {
+    const base = {
+      id: opt.id,
+      name: opt.name,
+      description: opt.description ?? null,
+      category: opt.category ?? null,
+    };
+    if (opt.type === 'boolean') {
+      return {
+        ...base,
+        type: 'boolean' as const,
+        currentValue: String(opt.currentValue),
+        options: [],
+      };
+    }
+    const options = Array.isArray(opt.options)
+      ? (opt.options as Array<acp.SessionConfigSelectOption | acp.SessionConfigSelectGroup>).flatMap((o) =>
+          'group' in o
+            ? o.options.map((inner) => ({ value: inner.value, name: `${o.name}/${inner.name}` }))
+            : [{ value: o.value, name: o.name }],
+        )
+      : [];
+    return {
+      ...base,
+      type: 'select' as const,
+      currentValue: opt.currentValue,
+      options,
+    };
+  });
+}
+
+function findConfigByCategory(
+  configOptions: SessionConfigOptionData[],
+  category: string,
+): SessionConfigOptionData | null {
+  return configOptions.find((o) => o.category === category) ?? null;
+}
+
+function extractConfigModes(
+  configOptions: SessionConfigOptionData[],
+): { modes: Array<{ id: string; name: string }>; currentModeId: string | null } | null {
+  const opt = findConfigByCategory(configOptions, 'mode');
+  if (!opt || opt.type !== 'select') return null;
+  return {
+    modes: opt.options.map((o) => ({ id: o.value, name: o.name ?? o.value })),
+    currentModeId: opt.currentValue,
+  };
+}
+
+function extractConfigModels(
+  configOptions: SessionConfigOptionData[],
+): {
+  availableModels: Array<{ id: string; name: string; provider?: string }>;
+  currentModelId: string | null;
+  currentModel: { id: string; name: string; provider?: string } | null;
+} | null {
+  const opt = findConfigByCategory(configOptions, 'model');
+  if (!opt || opt.type !== 'select') return null;
+  const availableModels = opt.options.map((o) => ({ id: o.value, name: o.name ?? o.value }));
+  const currentModelId = opt.currentValue;
+  const current = availableModels.find((m) => m.id === currentModelId) ?? null;
+  return { availableModels, currentModelId, currentModel: current };
+}
+
+function toAuthMethods(authMethods: acp.AuthMethod[] | undefined): AcpAuthMethodData[] {
+  if (!authMethods || authMethods.length === 0) return [];
+  return authMethods.map((m) => {
+    if ('type' in m) {
+      const kind = m.type === 'env_var' ? 'env_var' : m.type === 'terminal' ? 'terminal' : 'agent';
+      return {
+        id: m.id,
+        kind,
+        description: (m as { description?: string | null }).description ?? null,
+        url: (m as { url?: string | null }).url ?? null,
+      };
+    }
+    // AuthMethodAgent 无 type 字段（SDK 1.3.0），是默认认证方式
+    return { id: m.id, kind: 'agent', description: null, url: null };
+  });
+}
+
 export class AcpSessionBridge extends EventEmitter implements acp.Client {
   private spawner: AcpSpawner;
   private socket: Socket;
   private sessionId: string;
   private cwd: string;
+  private additionalDirectories: string[];
   private mcpServers: AcpBridgeOptions['mcpServers'];
+  private mcpEndpoint: AcpBridgeOptions['mcpEndpoint'];
   private connection: acp.ClientSideConnection | null = null;
   private acpSessionId: string | null = null;
   private activePrompt: Promise<acp.PromptResponse> | null = null;
   private inputQueue: QueuedInput[] = [];
   private textChunkBuffer = '';
+  private textChunkMessageId: string | null | undefined;
   private textChunkTimer: ReturnType<typeof setTimeout> | null = null;
   private initializing = false;
   private stopped = false;
@@ -43,16 +199,52 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     resolve: (response: acp.RequestPermissionResponse) => void;
     timeout: NodeJS.Timeout;
   }>();
+  private pendingElicitations = new Map<string, {
+    resolve: (response: acp.CreateElicitationResponse) => void;
+    timeout: NodeJS.Timeout;
+  }>();
+
+  // Capability snapshot from initialize / session/new / resume
+  private configOptions: SessionConfigOptionData[] = [];
+  private promptCapabilities: AcpInitializedPayload['promptCapabilities'] = null;
+  private agentInfo: AcpInitializedPayload['agentInfo'] = null;
+  private authMethods: AcpAuthMethodData[] = [];
+  private supportsAdditionalDirectories = false;
+  private agentProtocolVersion: number | null = null;
+  private agentMcpCapabilities: { http?: boolean | null; sse?: boolean | null } | null = null;
 
   constructor(socket: Socket, options: AcpBridgeOptions, spawner?: AcpSpawner) {
     super();
     this.socket = socket;
     this.sessionId = options.sessionId;
     this.cwd = options.cwd;
+    this.additionalDirectories = options.additionalDirectories ?? [];
     this.mcpServers = options.mcpServers;
+    this.mcpEndpoint = options.mcpEndpoint;
     this.spawner = spawner ?? new AcpSpawner({ sessionId: options.sessionId, cwd: options.cwd });
   }
 
+  private resolveMcpServers(): acp.McpServer[] {
+    if (this.mcpEndpoint) {
+      return toMcpEndpointServers(this.mcpEndpoint);
+    }
+    return toMcpServers(this.mcpServers);
+  }
+
+  // Log the MCP configuration that is about to be handed to the agent via
+  // session/new (or session/resume), and warn when the agent did not
+  // advertise the required MCP transport capability in initialize.
+  private logMcpServersForSession(method: 'session/new' | 'session/resume', servers: acp.McpServer[]): void {
+    console.log(`[ACP bridge] session ${this.sessionId}: passing MCP servers via ${method}: ${describeMcpServersForLog(servers)}`);
+    const httpServers = servers.filter((s) => 'url' in s && (s as { type?: string }).type === 'http');
+    if (httpServers.length > 0 && this.agentMcpCapabilities && this.agentMcpCapabilities.http === false) {
+      console.warn(
+        `[ACP bridge] session ${this.sessionId}: agent did not advertise mcpCapabilities.http ` +
+        `but ${httpServers.length} http MCP server(s) are being passed: ${httpServers.map((s) => s.name).join(', ')}`,
+      );
+    }
+  }
+
   async start(): Promise<void> {
     if (this.initializing) return;
     this.initializing = true;
@@ -60,23 +252,17 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     this.spawner.start();
     try {
       await this.initConnection();
+      const mcpServers = this.resolveMcpServers();
+      this.logMcpServersForSession('session/new', mcpServers);
       const result = await this.connection!.newSession({
         cwd: this.cwd,
-        mcpServers: toMcpServers(this.mcpServers),
+        mcpServers,
+        additionalDirectories: this.additionalDirectories.length > 0 ? this.additionalDirectories : undefined,
       });
       this.acpSessionId = result.sessionId;
       this.initializing = false;
 
-      this.emit('acp:initialized', {
-        sessionId: this.sessionId,
-        acpSessionId: this.acpSessionId,
-        modes: this.extractModes(result.modes),
-        currentModeId: result.modes?.currentModeId ?? null,
-        currentModel: this.extractCurrentModel(result.models),
-        availableModels: this.extractAvailableModels(result.models),
-        currentModelId: result.models?.currentModelId ?? null,
-      });
-
+      this.emit('acp:initialized', this.buildInitializedPayload(result));
       this.flushInputQueue();
     } catch (error) {
       this.initializing = false;
@@ -91,42 +277,31 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     this.spawner.start();
     try {
       await this.initConnection();
+      const mcpServers = this.resolveMcpServers();
+      this.logMcpServersForSession('session/resume', mcpServers);
       const result = await this.connection!.resumeSession({
         sessionId: externalSessionId,
         cwd: this.cwd,
+        mcpServers,
+        additionalDirectories: this.additionalDirectories.length > 0 ? this.additionalDirectories : undefined,
       });
       this.acpSessionId = externalSessionId;
       this.initializing = false;
 
-      this.emit('acp:initialized', {
-        sessionId: this.sessionId,
-        acpSessionId: this.acpSessionId,
-        modes: this.extractModes(result.modes),
-        currentModeId: result.modes?.currentModeId ?? null,
-        currentModel: this.extractCurrentModel(result.models),
-        availableModels: this.extractAvailableModels(result.models),
-        currentModelId: result.models?.currentModelId ?? null,
-      });
+      this.emit('acp:initialized', this.buildInitializedPayload(result));
     } catch (error) {
       // resumeSession may fail if agent doesn't support session.resume
       // fallback to newSession
       try {
         const result = await this.connection!.newSession({
           cwd: this.cwd,
-          mcpServers: toMcpServers(this.mcpServers),
+          mcpServers: this.resolveMcpServers(),
+          additionalDirectories: this.additionalDirectories.length > 0 ? this.additionalDirectories : undefined,
         });
         this.acpSessionId = result.sessionId;
         this.initializing = false;
 
-        this.emit('acp:initialized', {
-          sessionId: this.sessionId,
-          acpSessionId: this.acpSessionId,
-          modes: this.extractModes(result.modes),
-          currentModeId: result.modes?.currentModeId ?? null,
-          currentModel: this.extractCurrentModel(result.models),
-        availableModels: this.extractAvailableModels(result.models),
-        currentModelId: result.models?.currentModelId ?? null,
-        });
+        this.emit('acp:initialized', this.buildInitializedPayload(result));
       } catch (fallbackError) {
         this.initializing = false;
         this.handleError(fallbackError);
@@ -155,6 +330,16 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
 
   async setMode(modeId: string): Promise<void> {
     if (!this.connection || !this.acpSessionId) return;
+    const modeConfig = findConfigByCategory(this.configOptions, 'mode');
+    if (modeConfig) {
+      // 配置项通道：Agent 提供 configOptions 时以配置项为准
+      await this.connection.setSessionConfigOption({
+        sessionId: this.acpSessionId,
+        configId: modeConfig.id,
+        value: modeId,
+      });
+      return;
+    }
     await this.connection.setSessionMode({
       sessionId: this.acpSessionId,
       modeId,
@@ -163,13 +348,70 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
 
   async setModel(modelId: string): Promise<void> {
     if (!this.connection || !this.acpSessionId) return;
-    await this.connection.unstable_setSessionModel({
+    const modelConfig = findConfigByCategory(this.configOptions, 'model');
+    if (modelConfig) {
+      await this.connection.setSessionConfigOption({
+        sessionId: this.acpSessionId,
+        configId: modelConfig.id,
+        value: modelId,
+      });
+      return;
+    }
+    // SDK 1.x 已移除 unstable_setSessionModel：无 configOptions 的旧 Agent 无法走配置项通道。
+    // 模型切换暂不支持，由上层提示（不保留 unstable 调用）。
+    throw new Error('Model switching is not supported: agent does not expose a model config option');
+  }
+
+  async setConfigOption(configId: string, value: string | boolean): Promise<acp.SetSessionConfigOptionResponse> {
+    if (!this.connection || !this.acpSessionId) {
+      throw new Error('ACP bridge is not initialized');
+    }
+    const response = await this.connection.setSessionConfigOption({
       sessionId: this.acpSessionId,
-      modelId,
+      configId,
+      ...(typeof value === 'boolean' ? { value, type: 'boolean' as const } : { value }),
     });
+    if (response.configOptions) {
+      // SDK 1.3.0：set_config_option 响应携带全量快照，与 config_option_update 通知同源
+      this.configOptions = extractConfigOptions(response.configOptions);
+      this.socket.emit('acp:config-options', {
+        sessionId: this.sessionId,
+        configOptions: this.configOptions,
+      });
+    }
+    return response;
+  }
+
+  async authenticate(methodId: string): Promise<void> {
+    if (!this.connection) {
+      throw new Error('ACP bridge is not initialized');
+    }
+    await this.connection.authenticate({ methodId });
+  }
+
+  async logout(): Promise<void> {
+    if (!this.connection) {
+      throw new Error('ACP bridge is not initialized');
+    }
+    await this.connection.logout({});
+  }
+
+  async deleteSession(): Promise<void> {
+    if (!this.connection || !this.acpSessionId) {
+      throw new Error('ACP bridge is not initialized');
+    }
+    await this.connection.deleteSession({ sessionId: this.acpSessionId });
   }
 
-  sendInput(message: { type: string; content: string }): void {
+  getConfigOptions(): SessionConfigOptionData[] {
+    return this.configOptions;
+  }
+
+  getSupportsAdditionalDirectories(): boolean {
+    return this.supportsAdditionalDirectories;
+  }
+
+  sendInput(message: { type: string; content: string; attachments?: Array<Record<string, unknown>> }): void {
     if (this.activePrompt) {
       this.inputQueue.push(message);
       return;
@@ -177,12 +419,18 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     this.processPrompt(message);
   }
 
-  private async processPrompt(message: QueuedInput): Promise<void> {
+  private async processPrompt(message: QueuedInput & { attachments?: Array<Record<string, unknown>> }): Promise<void> {
     if (!this.connection || !this.acpSessionId || this.stopped) return;
 
+    const prompt: acp.ContentBlock[] = [];
+    for (const attachment of message.attachments ?? []) {
+      prompt.push(attachment as acp.ContentBlock);
+    }
+    prompt.push({ type: 'text' as const, text: message.content });
+
     this.activePrompt = this.connection.prompt({
       sessionId: this.acpSessionId,
-      prompt: [{ type: 'text' as const, text: message.content }],
+      prompt,
     });
 
     this.socket.emit('acp:prompt:start', { sessionId: this.sessionId });
@@ -212,44 +460,113 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     const output = this.spawner.stdout;
     const stream = acp.ndJsonStream(input, output);
     this.connection = new acp.ClientSideConnection(() => this, stream);
-    await this.connection.initialize({
+    const result = await this.connection.initialize({
       protocolVersion: ACP_PROTOCOL_VERSION,
-      clientCapabilities: {},
+      clientCapabilities: {
+        session: {
+          configOptions: { boolean: {} },
+        },
+        elicitation: { form: {}, url: {} },
+      },
       clientInfo: {
         name: 'agent-gear',
-        version: '1.0.0',
+        version: '1.1.5',
       },
     });
-  }
 
-  private flushInputQueue(): void {
-    while (this.inputQueue.length > 0) {
-      this.processPrompt(this.inputQueue.shift()!);
+    this.agentProtocolVersion = result.protocolVersion ?? null;
+    if (result.protocolVersion != null && result.protocolVersion !== ACP_PROTOCOL_VERSION) {
+      // 版本不兼容：不断连，由上层提示用户
+      this.socket.emit('acp:protocol-version-mismatch', {
+        sessionId: this.sessionId,
+        expectedVersion: ACP_PROTOCOL_VERSION,
+        agentVersion: result.protocolVersion,
+      });
     }
-  }
 
-  private extractModes(modes: acp.SessionModeState | null | undefined): Array<{ id: string; name: string; description?: string }> {
-    if (!modes?.availableModes) return [];
-    return modes.availableModes.map((m) => ({
-      id: m.id,
-      name: m.name,
-      description: m.description ?? undefined,
-    }));
+    this.promptCapabilities = result.agentCapabilities?.promptCapabilities
+      ? {
+          image: result.agentCapabilities.promptCapabilities.image ?? false,
+          audio: result.agentCapabilities.promptCapabilities.audio ?? false,
+          embeddedContext: result.agentCapabilities.promptCapabilities.embeddedContext ?? false,
+        }
+      : null;
+    this.agentInfo = result.agentInfo
+      ? { name: result.agentInfo.name, version: result.agentInfo.version ?? null }
+      : null;
+    this.authMethods = toAuthMethods(result.authMethods);
+    this.agentMcpCapabilities = result.agentCapabilities?.mcpCapabilities ?? null;
+    console.log(
+      `[ACP bridge] session ${this.sessionId}: agent capabilities: ` +
+      `protocolVersion=${result.protocolVersion ?? 'n/a'} mcp=${JSON.stringify(this.agentMcpCapabilities)} ` +
+      `agent=${this.agentInfo ? `${this.agentInfo.name}@${this.agentInfo.version ?? 'n/a'}` : 'n/a'}`,
+    );
+    this.supportsAdditionalDirectories =
+      result.agentCapabilities?.sessionCapabilities?.additionalDirectories !== undefined &&
+      result.agentCapabilities?.sessionCapabilities?.additionalDirectories !== null;
+
+    if (this.authMethods.length > 0) {
+      this.socket.emit('acp:auth:required', {
+        sessionId: this.sessionId,
+        authMethods: this.authMethods,
+      });
+    }
   }
 
-  private extractCurrentModel(models: acp.SessionModelState | null | undefined): { id: string; name: string; provider?: string } | null {
-    if (!models?.availableModels || !models.currentModelId) return null;
-    const found = models.availableModels.find((m) => m.modelId === models.currentModelId);
-    if (!found) return null;
-    return { id: found.modelId, name: found.name };
+  private buildInitializedPayload(
+    result: acp.NewSessionResponse | acp.ResumeSessionResponse,
+  ): AcpInitializedPayload {
+    const configOptions = extractConfigOptions(result.configOptions);
+    this.configOptions = configOptions.length > 0 ? configOptions : this.configOptions;
+
+    // 协议要求：响应含 configOptions 时以其为准（忽略 modes）
+    const configModes = extractConfigModes(this.configOptions);
+    const configModels = extractConfigModels(this.configOptions);
+
+    let modes: Array<{ id: string; name: string; description?: string }> = [];
+    let currentModeId: string | null = null;
+    if (configModes) {
+      modes = configModes.modes;
+      currentModeId = configModes.currentModeId;
+    } else if (result.modes?.availableModes) {
+      modes = result.modes.availableModes.map((m) => ({
+        id: m.id,
+        name: m.name,
+        description: m.description ?? undefined,
+      }));
+      currentModeId = result.modes.currentModeId ?? null;
+    }
+
+    let currentModel: AcpInitializedPayload['currentModel'] = null;
+    let availableModels: Array<{ id: string; name: string; provider?: string }> = [];
+    let currentModelId: string | null = null;
+    if (configModels) {
+      availableModels = configModels.availableModels;
+      currentModelId = configModels.currentModelId;
+      currentModel = configModels.currentModel;
+    }
+
+    return {
+      sessionId: this.sessionId,
+      acpSessionId: this.acpSessionId,
+      modes,
+      currentModeId,
+      currentModel,
+      availableModels,
+      currentModelId,
+      configOptions: this.configOptions,
+      promptCapabilities: this.promptCapabilities,
+      agentInfo: this.agentInfo,
+      authMethods: this.authMethods,
+      supportsAdditionalDirectories: this.supportsAdditionalDirectories,
+      protocolVersion: this.agentProtocolVersion,
+    };
   }
 
-  private extractAvailableModels(models: acp.SessionModelState | null | undefined): Array<{ id: string; name: string; provider?: string }> {
-    if (!models?.availableModels) return [];
-    return models.availableModels.map((m) => ({
-      id: m.modelId,
-      name: m.name,
-    }));
+  private flushInputQueue(): void {
+    while (this.inputQueue.length > 0) {
+      this.processPrompt(this.inputQueue.shift()!);
+    }
   }
 
   // ── acp.Client implementation ──
@@ -259,8 +576,22 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     switch (update.sessionUpdate) {
       case 'agent_message_chunk':
         if (update.content.type === 'text') {
+          if (this.textChunkBuffer && this.textChunkMessageId !== update.messageId) {
+            // messageId 边界：不同消息立即 flush
+            this.flushTextBuffer();
+          }
           this.textChunkBuffer += update.content.text;
-          this.scheduleTextFlush();
+          this.textChunkMessageId = update.messageId;
+          if (update.messageId) {
+            // 有 messageId 时跳过 50ms debounce 猜测，按 ID 边界 flush
+            this.flushTextBuffer();
+          } else {
+            this.scheduleTextFlush();
+          }
+        } else {
+          // 非 text chunk（image/audio/resource）原样透传
+          this.flushTextBuffer();
+          this.sendUpdate(update);
         }
         break;
       case 'tool_call':
@@ -270,6 +601,14 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
         this.flushTextBuffer();
         this.sendUpdate(update);
         break;
+      case 'config_option_update':
+        this.flushTextBuffer();
+        this.configOptions = extractConfigOptions(update.configOptions);
+        this.socket.emit('acp:config-options', {
+          sessionId: this.sessionId,
+          configOptions: this.configOptions,
+        });
+        break;
       case 'user_message_chunk':
         break;
       default:
@@ -315,6 +654,78 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
     pending.resolve({ outcome });
   }
 
+  async unstable_createElicitation(
+    params: acp.CreateElicitationRequest,
+  ): Promise<acp.CreateElicitationResponse> {
+    // custom/未知模式不支持：立即取消，避免挂起 Agent
+    if (!acp.CreateElicitationRequest.isForm(params) && !acp.CreateElicitationRequest.isUrl(params)) {
+      return { action: 'cancel' };
+    }
+
+    const requestId = `elic_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const toolCallId = 'toolCallId' in params ? params.toolCallId : undefined;
+
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this.pendingElicitations.delete(requestId);
+        resolve({ action: 'cancel' });
+      }, 65_000);
+
+      this.pendingElicitations.set(requestId, { resolve, timeout });
+
+      if (acp.CreateElicitationRequest.isForm(params)) {
+        this.socket.emit('acp:elicitation', {
+          requestId,
+          sessionId: this.sessionId,
+          mode: 'form',
+          message: params.message,
+          ...(toolCallId != null ? { toolCallId } : {}),
+          requestedSchema: params.requestedSchema,
+        });
+      } else {
+        this.socket.emit('acp:elicitation', {
+          requestId,
+          sessionId: this.sessionId,
+          mode: 'url',
+          message: params.message,
+          ...(toolCallId != null ? { toolCallId } : {}),
+          elicitationId: params.elicitationId,
+          url: params.url,
+        });
+      }
+
+      this.emit('elicitation:sent', requestId);
+    });
+  }
+
+  handleElicitationResponse(
+    requestId: string,
+    action: 'accept' | 'decline' | 'cancel',
+    content?: Record<string, unknown>,
+  ): void {
+    const pending = this.pendingElicitations.get(requestId);
+    if (!pending) {
+      console.warn(`Elicitation request ${requestId} not found`);
+      return;
+    }
+
+    clearTimeout(pending.timeout);
+    this.pendingElicitations.delete(requestId);
+    pending.resolve({
+      action,
+      ...(action === 'accept' && content
+        ? { content: content as Record<string, acp.ElicitationContentValue> }
+        : {}),
+    });
+  }
+
+  async unstable_completeElicitation(params: acp.CompleteElicitationNotification): Promise<void> {
+    this.socket.emit('acp:elicitation:complete', {
+      sessionId: this.sessionId,
+      elicitationId: params.elicitationId,
+    });
+  }
+
   // ── text buffering ──
 
   private scheduleTextFlush(): void {
@@ -331,8 +742,10 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
       this.sendUpdate({
         sessionUpdate: 'agent_message_chunk' as const,
         content: { type: 'text' as const, text: this.textChunkBuffer },
+        ...(this.textChunkMessageId ? { messageId: this.textChunkMessageId } : {}),
       } as acp.SessionUpdate);
       this.textChunkBuffer = '';
+      this.textChunkMessageId = undefined;
     }
   }
 
@@ -346,14 +759,17 @@ export class AcpSessionBridge extends EventEmitter implements acp.Client {
   }
 
   private emitStopped(reason: string, exitCode?: number): void {
+    console.log(`[ACP bridge] session ${this.sessionId} stopped: reason=${reason} exitCode=${exitCode ?? 'n/a'}`);
     this.stopped = true;
     this.socket.emit('acp:stopped', { sessionId: this.sessionId, reason, exitCode });
     this.emit('acp:stopped', { sessionId: this.sessionId, reason, exitCode });
   }
 
   private handleError(error: unknown): void {
-    this.stopped = true;
     const msg = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ACP bridge] session ${this.sessionId} failed: ${msg}${stack ? `\n${stack}` : ''}`);
+    this.stopped = true;
     this.socket.emit('acp:stopped', {
       sessionId: this.sessionId,
       reason: 'error',