@band-ai/sdk 0.4.1 → 0.4.3

package/dist/index.cjs

@@ -1058,6 +1058,7 @@ __export(src_exports, {
   A2AAdapter: () => A2AAdapter,
   A2AGatewayAdapter: () => A2AGatewayAdapter,
   ACPClientAdapter: () => ACPClientAdapter,
+  AcpSessionConfigError: () => AcpSessionConfigError,
   Agent: () => Agent,
   AgentFailure: () => import_band_sdk_core13.AgentFailure,
   AgentRuntime: () => AgentRuntime,
@@ -1069,10 +1070,13 @@ __export(src_exports, {
   ClaudeSDKAdapter: () => ClaudeSDKAdapter,
   CodexAdapter: () => CodexAdapter,
   CopilotACPAdapter: () => CopilotACPAdapter,
+  CursorACPAdapter: () => CursorACPAdapter,
   DEFAULT_COPILOT_ACP_COMMAND: () => DEFAULT_COPILOT_ACP_COMMAND,
+  DEFAULT_CURSOR_ACP_COMMAND: () => DEFAULT_CURSOR_ACP_COMMAND,
   DEFAULT_OMP_ACP_COMMAND: () => DEFAULT_OMP_ACP_COMMAND,
   DefaultPreprocessor: () => DefaultPreprocessor,
   DeliveryFailedError: () => DeliveryFailedError,
+  FAILURE_CODE_SESSION_CONFIG: () => FAILURE_CODE_SESSION_CONFIG,
   FAILURE_EVENT_TYPE: () => FAILURE_EVENT_TYPE,
   FAILURE_METADATA_KEY: () => FAILURE_METADATA_KEY,
   GeminiAdapter: () => GeminiAdapter,
@@ -1082,6 +1086,7 @@ __export(src_exports, {
   LettaAdapter: () => LettaAdapter,
   MCP_SERVER_NAME: () => MCP_SERVER_NAME,
   MCP_TOOL_PREFIX: () => MCP_TOOL_PREFIX,
+  MISSING_CONFIG_OPTIONS_REASON: () => MISSING_CONFIG_OPTIONS_REASON,
   OmpACPAdapter: () => OmpACPAdapter,
   OpenAIAdapter: () => OpenAIAdapter,
   OpencodeAdapter: () => OpencodeAdapter,
@@ -1094,6 +1099,7 @@ __export(src_exports, {
   VercelAISDKAdapter: () => VercelAISDKAdapter,
   WebSocketDisconnectError: () => WebSocketDisconnectError,
   agentFailure: () => agentFailure,
+  applySessionConfigSelections: () => applySessionConfigSelections,
   deliverReply: () => deliverReply,
   deriveDefaultRestUrl: () => deriveDefaultRestUrl,
   isDirectExecution: () => isDirectExecution,
@@ -17103,26 +17109,165 @@ var ACPClientHistoryConverter = class {
 
 // src/adapters/acp/ACPClientAdapter.ts
 init_errors();
-init_chatEvents();
-init_schemas();
 
-// src/adapters/acp/types.ts
-function choosePermissionOption(options) {
-  if (options.length === 0) {
-    return null;
+// src/adapters/acp/sessionConfigReconciliation.ts
+var FAILURE_CODE_SESSION_CONFIG = "session_config";
+var MISSING_CONFIG_OPTIONS_REASON = "missing_config_options";
+var AcpSessionConfigTimeoutError = class extends Error {
+};
+var AcpSessionConfigError = class extends Error {
+  provider;
+  sessionId;
+  optionId;
+  selectedValue;
+  acpCode;
+  detail;
+  timedOut;
+  constructor(input) {
+    super(input.message, input.cause !== void 0 ? { cause: input.cause } : void 0);
+    this.name = "AcpSessionConfigError";
+    this.provider = input.provider;
+    this.sessionId = input.sessionId;
+    this.optionId = input.optionId;
+    this.selectedValue = input.selectedValue;
+    this.acpCode = input.acpCode;
+    this.detail = input.detail;
+    this.timedOut = input.timedOut ?? false;
+  }
+  toAgentFailure() {
+    return agentFailure(
+      this.provider,
+      this.message,
+      this.acpCode !== void 0 ? String(this.acpCode) : FAILURE_CODE_SESSION_CONFIG,
+      {
+        sessionId: this.sessionId,
+        optionId: this.optionId,
+        selectedValue: this.selectedValue,
+        detail: this.detail
+      }
+    );
   }
-  return options.find((option) => option.kind === "allow_once") ?? options.find((option) => option.kind === "allow_always") ?? options[0];
+};
+async function applySessionConfigSelections(input) {
+  let catalog = input.catalog;
+  for (const { configId, value: selectedValue } of sessionConfigSelectionEntries(input.selections)) {
+    if (selectedValue === void 0) {
+      continue;
+    }
+    const option = catalog.find((entry) => entry?.id === configId);
+    if (!option || !isSessionConfigSelect(option)) {
+      throw new AcpSessionConfigError({
+        provider: input.provider,
+        sessionId: input.sessionId,
+        optionId: configId,
+        selectedValue,
+        message: `Session config option "${configId}" is not available after prior selections.`
+      });
+    }
+    if (selectedValue === option.currentValue) {
+      continue;
+    }
+    const availableValues = flattenConfigSelectOptions(option.options).map((entry) => entry.value);
+    if (!availableValues.includes(selectedValue)) {
+      throw new AcpSessionConfigError({
+        provider: input.provider,
+        sessionId: input.sessionId,
+        optionId: configId,
+        selectedValue,
+        message: `Session config value "${selectedValue}" is not advertised for option "${configId}".`,
+        detail: { availableValues }
+      });
+    }
+    const timeoutMessage = `setSessionConfigOption did not respond within ${input.timeoutMs}ms`;
+    try {
+      const response = await withTimeout(
+        input.setOption({ sessionId: input.sessionId, configId, value: selectedValue }),
+        input.timeoutMs,
+        () => new AcpSessionConfigTimeoutError(timeoutMessage)
+      );
+      if (!Array.isArray(response?.configOptions)) {
+        throw new AcpSessionConfigError({
+          provider: input.provider,
+          sessionId: input.sessionId,
+          optionId: configId,
+          selectedValue,
+          message: `Session config option "${configId}" response did not include a refreshed catalog.`,
+          detail: { reason: MISSING_CONFIG_OPTIONS_REASON }
+        });
+      }
+      catalog = response.configOptions;
+    } catch (error) {
+      if (error instanceof AcpSessionConfigError) {
+        throw error;
+      }
+      const acpError = asAcpJsonRpcError(error);
+      throw new AcpSessionConfigError({
+        provider: input.provider,
+        sessionId: input.sessionId,
+        optionId: configId,
+        selectedValue,
+        acpCode: acpError?.code,
+        detail: acpError?.data,
+        message: acpError?.message ?? asErrorMessage(error),
+        cause: error,
+        timedOut: error instanceof AcpSessionConfigTimeoutError
+      });
+    }
+  }
+  return { catalog };
+}
+function sessionConfigSelectionEntries(selections) {
+  if (isOrderedSessionConfigSelections(selections)) {
+    return selections;
+  }
+  return Object.keys(selections).map((configId) => ({ configId, value: selections[configId] }));
+}
+function isOrderedSessionConfigSelections(selections) {
+  return Array.isArray(selections);
+}
+function isSessionConfigSelect(option) {
+  return option?.type === "select";
+}
+function flattenConfigSelectOptions(options) {
+  if (!Array.isArray(options)) {
+    return [];
+  }
+  return options.flatMap((entry) => {
+    if (!asOptionalRecord2(entry)) {
+      return [];
+    }
+    if ("group" in entry) {
+      return Array.isArray(entry.options) ? entry.options : [];
+    }
+    return [entry];
+  });
+}
+function isAcpErrorResponse(error) {
+  return typeof error === "object" && error !== null && typeof error.code === "number" && typeof error.message === "string";
+}
+function asAcpJsonRpcError(error) {
+  if (isAcpErrorResponse(error)) {
+    return error;
+  }
+  const nested = asOptionalRecord2(error)?.error;
+  return isAcpErrorResponse(nested) ? nested : void 0;
 }
 
+// src/adapters/acp/ACPClientAdapter.ts
+init_chatEvents();
+init_schemas();
+
 // src/adapters/acp/client.ts
 var BandACPClient = class {
   sessionChunks = /* @__PURE__ */ new Map();
   permissionHandler;
+  extensionHandler;
   // The handler is connection-scoped and required at construction, so it is
   // already in place before the agent process is spawned: there is no window
   // in which a `session/request_permission` has nowhere to go.
-  constructor(permissionHandler) {
+  constructor(permissionHandler, extensionHandler) {
     this.permissionHandler = permissionHandler;
+    this.extensionHandler = extensionHandler;
   }
   beginSession(sessionId) {
     this.sessionChunks.set(sessionId, []);
@@ -17167,62 +17312,26 @@ var BandACPClient = class {
     return chunks;
   }
   async extMethod(method, params) {
-    if (method === "cursor/ask_question") {
-      const options = Array.isArray(params.options) ? params.options : [];
-      const selected = choosePermissionOption(
-        options.filter((option) => !!option && typeof option === "object")
-      );
-      if (!selected) {
-        return {
-          outcome: {
-            type: "cancelled"
-          }
-        };
-      }
-      return {
-        outcome: {
-          type: "selected",
-          optionId: selected.optionId
-        }
-      };
-    }
-    if (method === "cursor/create_plan") {
-      return {
-        outcome: {
-          type: "approved"
-        }
-      };
-    }
-    return {};
+    const result = await this.extensionHandler?.extMethod?.(
+      method,
+      params,
+      { sessionId: sessionIdFrom(params) }
+    );
+    return result ?? {};
   }
   async extNotification(method, params) {
-    const sessionId = toOptionalString(params.sessionId) ?? toOptionalString(params.session_id);
-    if (!sessionId) {
-      return;
-    }
-    if (method === "cursor/update_todos") {
-      const todos = Array.isArray(params.todos) ? params.todos : [];
-      const lines = todos.filter((todo) => !!todo && typeof todo === "object").map((todo) => `- [${todo.completed === true ? "x" : " "}] ${String(todo.content ?? "")}`).filter((line) => line.trim().length > 0);
-      if (lines.length > 0) {
-        this.appendChunk(sessionId, {
-          chunkType: "plan",
-          content: lines.join("\n"),
-          metadata: {},
-          streamed: false
-        });
-      }
+    const sessionId = sessionIdFrom(params);
+    const chunks = await this.extensionHandler?.extNotification?.(
+      method,
+      params,
+      { sessionId }
+    );
+    const targetSessionId = sessionId ?? this.extensionHandler?.extensionSessionId?.() ?? null;
+    if (!targetSessionId || !chunks) {
       return;
     }
-    if (method === "cursor/task") {
-      const result = toOptionalString(params.result);
-      if (result) {
-        this.appendChunk(sessionId, {
-          chunkType: "text",
-          content: `[Task completed] ${result}`,
-          metadata: {},
-          streamed: false
-        });
-      }
+    for (const chunk of chunks) {
+      this.appendChunk(targetSessionId, chunk);
     }
   }
   appendChunk(sessionId, chunk) {
@@ -17347,6 +17456,17 @@ function extractTextFromContent(content) {
 function toOptionalString(value) {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
+function sessionIdFrom(params) {
+  return toOptionalString(params.sessionId) ?? toOptionalString(params.session_id);
+}
+
+// src/adapters/acp/types.ts
+function choosePermissionOption(options) {
+  if (options.length === 0) {
+    return null;
+  }
+  return options.find((option) => option.kind === "allow_once") ?? options.find((option) => option.kind === "allow_always") ?? options[0];
+}
 
 // src/adapters/acp/loader.ts
 init_errors();
@@ -17361,6 +17481,13 @@ var acpModule = new LazyAsyncValue({
 });
 
 // src/adapters/acp/ACPClientAdapter.ts
+function createConnectionRetirement() {
+  let reject = () => void 0;
+  const promise = new Promise((_resolve, rejectPromise) => {
+    reject = rejectPromise;
+  });
+  return { promise, reject };
+}
 var DEFAULT_PERMISSION_TIMEOUT_MS = 5 * 6e4;
 var DEFAULT_TURN_TIMEOUT_MS = 60 * 6e4;
 var SET_SESSION_CONFIG_TIMEOUT_MS = 1e4;
@@ -17386,6 +17513,7 @@ var ACPClientAdapter = class extends SimpleAdapter {
   additionalMcpTools;
   clientCapabilities;
   connectionFactory;
+  extensionHandler;
   tcpEndpoint;
   // The value's `generation` is the connection generation the session was
   // last established/restored against. `client` is the exact BandACPClient
@@ -17418,6 +17546,7 @@ var ACPClientAdapter = class extends SimpleAdapter {
   permissionTimeoutMs;
   turnTimeoutMs;
   logger;
+  customSection;
   backend = null;
   backendPromise = null;
   client = null;
@@ -17428,6 +17557,7 @@ var ACPClientAdapter = class extends SimpleAdapter {
   started = false;
   systemPrompt = "";
   spawnPromise = null;
+  connectionRetirements = /* @__PURE__ */ new WeakMap();
   // Bumped by `stop()` and on every successful spawn install. Cleanup/timeout
   // and permission maps key by this plus session id so a stale generation
   // cannot alias a same-id session on a newer connection.
@@ -17448,12 +17578,14 @@ var ACPClientAdapter = class extends SimpleAdapter {
     this.additionalMcpTools = [...options.additionalMcpTools ?? []];
     this.clientCapabilities = options.clientCapabilities;
     this.connectionFactory = options.connectionFactory;
+    this.extensionHandler = options.extensionHandler;
     this.tcpEndpoint = tcpEndpoint;
     this.resolvePermission = options.resolvePermission;
     this.resolveSessionMode = options.resolveSessionMode;
     this.resolveSessionModel = options.resolveSessionModel;
     this.resolveSessionConfig = options.resolveSessionConfig;
     this.logger = resolveLogger(options.logger);
+    this.customSection = options.customSection;
     this.permissionTimeoutMs = options.permissionTimeoutMs ?? DEFAULT_PERMISSION_TIMEOUT_MS;
     if ((this.resolvePermission || this.resolveSessionMode || this.resolveSessionModel || this.resolveSessionConfig) && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
       throw new ValidationError(`permissionTimeoutMs must be a positive finite number, got ${options.permissionTimeoutMs}`);
@@ -17485,7 +17617,8 @@ var ACPClientAdapter = class extends SimpleAdapter {
     this.systemPrompt = renderSystemPrompt({
       agentName,
       agentDescription,
-      includeBaseInstructions: false
+      includeBaseInstructions: false,
+      customSection: this.customSection
     });
     await this.ensureConnection();
   }
@@ -17501,6 +17634,7 @@ var ACPClientAdapter = class extends SimpleAdapter {
     let client = null;
     let sessionId;
     let generation = 0;
+    await this.onAcpTurnStarted(message, tools, context);
     try {
       const ensured = await this.ensureConnection();
       connection = ensured.connection;
@@ -17511,6 +17645,7 @@ var ACPClientAdapter = class extends SimpleAdapter {
       }
       sessionId = await this.getOrCreateSession(context.roomId, connection, generation, client);
       const sessionKey = this.sessionKey(generation, sessionId);
+      await this.onAcpSessionReady(message, tools, context, sessionId);
       client.beginSession(sessionId);
       const content = replaceUuidMentions(message.content, mentionSubjectsFromMetadata(message.metadata));
       const messageWithContext = [...systemUpdateParts(participantsMessage, contactsMessage), content].join("\n\n");
@@ -17518,13 +17653,17 @@ var ACPClientAdapter = class extends SimpleAdapter {
 
 ${messageWithContext}`;
       this.bootstrappedSessions.add(sessionKey);
-      const response = await withTimeout(connection.prompt({
-        sessionId,
-        prompt: [{
-          type: "text",
-          text: promptText
-        }]
-      }), this.turnTimeoutMs, () => new AcpTurnTimeoutError());
+      const response = await withTimeout(
+        this.raceAgainstConnectionRetirement(connection, connection.prompt({
+          sessionId,
+          prompt: [{
+            type: "text",
+            text: promptText
+          }]
+        })),
+        this.turnTimeoutMs,
+        () => new AcpTurnTimeoutError()
+      );
       await this.flushChunks({
         client,
         tools,
@@ -17565,15 +17704,28 @@ ${messageWithContext}`;
           }
         }
       }
-      const acpError = asAcpJsonRpcError(error);
+      const configError = error instanceof AcpSessionConfigError ? error : void 0;
+      const acpError = configError ? void 0 : asAcpJsonRpcError(error);
       await reportTurnFailure(
         tools,
-        isTimeout ? agentFailure(this.provider, "ACP turn timed out.", FAILURE_CODE_TIMEOUT) : acpError ? agentFailure(this.provider, acpError.message, String(acpError.code), acpError.data) : agentFailure(this.provider, asErrorMessage(error)),
+        isTimeout ? agentFailure(this.provider, "ACP turn timed out.", FAILURE_CODE_TIMEOUT) : configError ? configError.toAgentFailure() : acpError ? agentFailure(this.provider, acpError.message, String(acpError.code), acpError.data) : agentFailure(this.provider, asErrorMessage(error)),
         this.logger,
-        { roomId: context.roomId, sessionId }
+        {
+          roomId: context.roomId,
+          sessionId: configError?.sessionId ?? sessionId,
+          ...configError ? { optionId: configError.optionId, selectedValue: configError.selectedValue } : {}
+        }
       );
+    } finally {
+      await this.onAcpTurnFinished(message, tools, context);
     }
   }
+  async onAcpTurnStarted(_message, _tools, _context) {
+  }
+  async onAcpTurnFinished(_message, _tools, _context) {
+  }
+  async onAcpSessionReady(_message, _tools, _context, _sessionId) {
+  }
   // Best-effort: tells the agent to stop working on a turn Band has already
   // given up waiting for (the ACP client has no way to force it), evicts the
   // session so the room's next turn re-establishes rather than reuses it
@@ -17589,17 +17741,12 @@ ${messageWithContext}`;
   // would risk blocking this room's turn lock forever on the very process
   // that just proved it can hang.
   async abandonTimedOutTurn(connection, sessionId, generation) {
-    const key = this.sessionKey(generation, sessionId);
-    this.activeSessions.delete(key);
-    this.abandonedSessions.add(key);
-    const owner = [...this.roomToSession.entries()].find(([, value]) => value.sessionId === sessionId && value.generation === generation);
-    if (owner) {
-      this.unlinkOwner(owner[0], owner[1]);
-    }
-    abandon(
-      () => connection.cancel({ sessionId }),
-      (error) => this.safeWarn("acp_client.cancel_failed", { sessionId, error: asErrorMessage(error) })
-    );
+    this.evictAbandonedSession(sessionId, generation, connection, () => {
+      const owner = [...this.roomToSession.entries()].find(([, value]) => value.sessionId === sessionId && value.generation === generation);
+      if (owner) {
+        this.unlinkOwner(owner[0], owner[1]);
+      }
+    });
   }
   // A per-room async mutex: `fn` for a given `roomId` never overlaps another
   // call for that same room, while different rooms stay fully concurrent.
@@ -17725,6 +17872,11 @@ ${messageWithContext}`;
     void connection.closed.then(() => reject(new Error("ACP connection closed while a session operation was still in flight")));
     return Promise.race([operation, closedRejection]);
   }
+  raceAgainstConnectionRetirement(connection, operation) {
+    const retirement = this.connectionRetirements.get(connection) ?? createConnectionRetirement();
+    this.connectionRetirements.set(connection, retirement);
+    return Promise.race([operation, retirement.promise]);
+  }
   unlinkRoom(roomId) {
     const owner = this.roomToSession.get(roomId);
     if (owner) {
@@ -17743,6 +17895,9 @@ ${messageWithContext}`;
   sessionKey(generation, sessionId) {
     return `${generation}:${sessionId}`;
   }
+  roomIdForSession(sessionId) {
+    return [...this.roomToSession.entries()].find(([, owner]) => owner.sessionId === sessionId)?.[0];
+  }
   async ensureConnection() {
     if (this.connection && !this.connection.signal.aborted) {
       return { connection: this.connection, generation: this.connectionGeneration };
@@ -17779,7 +17934,10 @@ ${messageWithContext}`;
         throw new Error(CONNECTION_ATTEMPT_SUPERSEDED_ERROR);
       }
       const owner = { generation: -1 };
-      const client = new BandACPClient((params) => this.routePermissionRequest(params, owner.generation));
+      const client = new BandACPClient(
+        (params) => this.routePermissionRequest(params, owner.generation),
+        this.extensionHandler
+      );
       handle = await (this.connectionFactory ? this.connectionFactory(client, {
         command: this.command,
         cwd: this.cwd,
@@ -17869,7 +18027,7 @@ ${messageWithContext}`;
         this.activeSessions.add(restoredKey);
         this.bootstrappedSessions.add(restoredKey);
         await this.configureSessionMode(roomId, existingSessionId, restored.modes, connection);
-        await this.configureSessionConfig(roomId, existingSessionId, restored.configOptions, connection);
+        await this.configureSessionConfig(roomId, existingSessionId, restored.configOptions, connection, connectionGeneration, client);
         if (!this.resolveSessionConfig) {
           await this.configureSessionModel(roomId, existingSessionId, restored.configOptions, connection);
         }
@@ -17883,13 +18041,13 @@ ${messageWithContext}`;
     this.linkOrAbandon(roomId, created.sessionId, generation, connectionGeneration, client);
     this.activeSessions.add(this.sessionKey(connectionGeneration, created.sessionId));
     await this.configureSessionMode(roomId, created.sessionId, created.modes, connection);
-    await this.configureSessionConfig(roomId, created.sessionId, created.configOptions, connection);
+    await this.configureSessionConfig(roomId, created.sessionId, created.configOptions, connection, connectionGeneration, client);
     if (!this.resolveSessionConfig) {
       await this.configureSessionModel(roomId, created.sessionId, created.configOptions, connection);
     }
     return created.sessionId;
   }
-  async configureSessionConfig(roomId, sessionId, configOptions, connection) {
+  async configureSessionConfig(roomId, sessionId, configOptions, connection, connectionGeneration, client) {
     if (!this.resolveSessionConfig || !Array.isArray(configOptions) || configOptions.length === 0) {
       return;
     }
@@ -17902,35 +18060,76 @@ ${messageWithContext}`;
     if (!selections) {
       return;
     }
-    for (const option of advertisedOptions) {
-      const selectedValue = selections[option.id];
-      if (selectedValue === void 0 || selectedValue === option.currentValue || !isSessionConfigSelect(option)) {
-        continue;
-      }
-      const availableValues = flattenConfigSelectOptions(option.options).map((entry) => entry.value);
-      if (!availableValues.includes(selectedValue)) {
-        this.safeWarn("resolveSessionConfig selected a value this session does not advertise", {
-          sessionId,
-          configId: option.id,
-          selectedValue,
-          availableValues
-        });
-        continue;
-      }
-      try {
-        await withTimeout(
-          connection.setSessionConfigOption({ sessionId, configId: option.id, value: selectedValue }),
-          SET_SESSION_CONFIG_TIMEOUT_MS,
-          `setSessionConfigOption did not respond within ${SET_SESSION_CONFIG_TIMEOUT_MS}ms`
-        );
-      } catch (error) {
-        this.safeWarn("failed to switch session config option", {
-          sessionId,
-          configId: option.id,
-          selectedValue,
-          error: String(error)
-        });
+    try {
+      await applySessionConfigSelections({
+        provider: this.provider,
+        sessionId,
+        catalog: advertisedOptions,
+        selections,
+        setOption: (params) => connection.setSessionConfigOption(params),
+        timeoutMs: SET_SESSION_CONFIG_TIMEOUT_MS
+      });
+    } catch (error) {
+      this.abandonFailedConfigSession(
+        roomId,
+        sessionId,
+        connectionGeneration,
+        client,
+        connection,
+        error instanceof AcpSessionConfigError && error.timedOut
+      );
+      throw error;
+    }
+  }
+  // A config failure mid-establish must not leave a half-applied session
+  // active for the room: the next turn needs a fresh `newSession` catalog.
+  abandonFailedConfigSession(roomId, sessionId, connectionGeneration, client, connection, retireConnection) {
+    const key = this.sessionKey(connectionGeneration, sessionId);
+    this.bootstrappedSessions.delete(key);
+    client.resetChunks(sessionId);
+    this.evictAbandonedSession(sessionId, connectionGeneration, connection, () => {
+      const owner = this.roomToSession.get(roomId);
+      if (owner && owner.sessionId === sessionId && owner.generation === connectionGeneration) {
+        this.unlinkOwner(roomId, owner);
       }
+    });
+    if (retireConnection) {
+      this.retireConnection(connection, connectionGeneration);
+    }
+  }
+  // Common half of timeout and config-failure abandon: mark the session
+  // unusable for restore, unlink ownership, and best-effort cancel.
+  evictAbandonedSession(sessionId, connectionGeneration, connection, unlink) {
+    const key = this.sessionKey(connectionGeneration, sessionId);
+    const wasActive = this.activeSessions.delete(key);
+    if (wasActive) {
+      this.abandonedSessions.add(key);
+    }
+    unlink();
+    abandon(
+      () => connection.cancel({ sessionId }),
+      (error) => this.safeWarn("acp_client.cancel_failed", { sessionId, error: asErrorMessage(error) })
+    );
+  }
+  // A timed-out config RPC means this transport has already failed to answer
+  // one request. Retire it so the next turn cannot wait forever on another.
+  retireConnection(connection, generation) {
+    if (this.connection !== connection || this.connectionGeneration !== generation) {
+      return;
+    }
+    const handle = this.connectionHandle;
+    this.connectionGeneration++;
+    this.connection = null;
+    this.connectionHandle = null;
+    this.connectionState = null;
+    this.client = null;
+    this.pruneConnectionGeneration(generation);
+    this.connectionRetirements.get(connection)?.reject(new Error("ACP connection retired after a config timeout"));
+    if (handle) {
+      abandon(
+        () => handle.stop(),
+        (error) => this.safeWarn("acp_client.handle_stop_after_config_timeout", { error: asErrorMessage(error) })
+      );
     }
   }
   // The single gate an establishment must pass before it's allowed to claim
@@ -18544,39 +18743,12 @@ async function createTcpConnection(client, endpoint, signal) {
   };
 }
 var MODEL_CONFIG_OPTION_KEY = "model";
-function isSessionConfigSelect(option) {
-  return option?.type === "select";
-}
 function isModelConfigOption(option) {
   return isSessionConfigSelect(option) && option.category === MODEL_CONFIG_OPTION_KEY;
 }
 function isModelConfigOptionById(option) {
   return isSessionConfigSelect(option) && option.id === MODEL_CONFIG_OPTION_KEY;
 }
-function flattenConfigSelectOptions(options) {
-  if (!Array.isArray(options)) {
-    return [];
-  }
-  return options.flatMap((entry) => {
-    if (!asOptionalRecord2(entry)) {
-      return [];
-    }
-    if ("group" in entry) {
-      return Array.isArray(entry.options) ? entry.options : [];
-    }
-    return [entry];
-  });
-}
-function isAcpErrorResponse(error) {
-  return typeof error === "object" && error !== null && typeof error.code === "number" && typeof error.message === "string";
-}
-function asAcpJsonRpcError(error) {
-  if (isAcpErrorResponse(error)) {
-    return error;
-  }
-  const nested = asOptionalRecord2(error)?.error;
-  return isAcpErrorResponse(nested) ? nested : void 0;
-}
 
 // src/adapters/acp/ACPServer.ts
 var import_node_stream2 = require("stream");
@@ -18621,6 +18793,358 @@ var CopilotACPAdapter = class extends ACPClientAdapter {
   }
 };
 
+// src/adapters/cursor-acp/CursorACPAdapter.ts
+var DEFAULT_CURSOR_ACP_COMMAND = ["agent", "acp"];
+var DEFAULT_CURSOR_DECISION_TIMEOUT_MS = 3e5;
+var DEFAULT_CURSOR_MAX_PENDING_DECISIONS = 10;
+var CursorExtensions = class {
+  adapter = null;
+  todosBySession = /* @__PURE__ */ new Map();
+  bind(adapter) {
+    this.adapter = adapter;
+  }
+  async resolvePermission(request, signal) {
+    return this.adapter?.resolveCursorPermission(request, signal);
+  }
+  extensionSessionId() {
+    return this.adapter?.extensionSessionId() ?? null;
+  }
+  async extMethod(method, params, context) {
+    return this.adapter?.resolveExtension(method, params, context.sessionId) ?? null;
+  }
+  async extNotification(method, params, context) {
+    const sessionId = context.sessionId ?? this.extensionSessionId();
+    if (!sessionId) {
+      return;
+    }
+    if (method === "cursor/update_todos") {
+      const content = this.updateTodos(sessionId, params);
+      if (!content) {
+        return;
+      }
+      return [{ chunkType: "plan", content, metadata: { cursor_todos: true }, streamed: false }];
+    }
+    if (method === "cursor/task") {
+      const description = stringValue(params.description);
+      if (!description) {
+        return [];
+      }
+      const subagentType = stringValue(params.subagentType) ?? "unspecified";
+      const model = stringValue(params.model);
+      const suffix = model ? ` (${model})` : "";
+      return [{ chunkType: "plan", content: `[Cursor ${subagentType} task] ${description}${suffix}`, metadata: {}, streamed: false }];
+    }
+    if (method === "cursor/generate_image") {
+      const description = stringValue(params.description);
+      if (!description) {
+        return [];
+      }
+      const filePath = stringValue(params.filePath);
+      return [{ chunkType: "plan", content: `[Cursor generated image] ${description}${filePath ? ` \u2192 ${filePath}` : ""}`, metadata: {}, streamed: false }];
+    }
+  }
+  forgetSession(sessionId) {
+    this.todosBySession.delete(sessionId);
+  }
+  clearSessions() {
+    this.todosBySession.clear();
+  }
+  updateTodos(sessionId, params) {
+    const todos = parseTodos(params.todos);
+    if (params.merge === true) {
+      const current2 = this.todosBySession.get(sessionId) ?? /* @__PURE__ */ new Map();
+      for (const todo of todos) {
+        current2.set(todo.id, todo);
+      }
+      this.todosBySession.set(sessionId, current2);
+    } else {
+      this.todosBySession.set(sessionId, new Map(todos.map((todo) => [todo.id, todo])));
+    }
+    const current = this.todosBySession.get(sessionId);
+    return current && current.size > 0 ? [...current.values()].map((todo) => `- [${todoMark(todo.status)}] ${todo.content}`).join("\n") : void 0;
+  }
+};
+var CursorACPAdapter = class extends ACPClientAdapter {
+  provider = "cursor-acp";
+  approvalMode;
+  questionMode;
+  planMode;
+  decisionTimeoutMs;
+  maxPendingDecisions;
+  authorizedSenders;
+  decisionLogger;
+  extensions;
+  turns = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  activeTurn = null;
+  turnTail = Promise.resolve();
+  constructor(options = {}) {
+    const extensions = new CursorExtensions();
+    validateOptions(options);
+    const env = cursorEnv(options);
+    super({
+      ...options,
+      env,
+      command: options.command ?? [...DEFAULT_CURSOR_ACP_COMMAND],
+      authMethod: "cursor_login",
+      extensionHandler: extensions,
+      resolvePermission: (request, signal) => extensions.resolvePermission(request, signal)
+    });
+    extensions.bind(this);
+    this.extensions = extensions;
+    this.approvalMode = options.approvalMode ?? "manual";
+    this.questionMode = options.questionMode ?? "manual";
+    this.planMode = options.planMode ?? "manual";
+    this.decisionTimeoutMs = options.decisionTimeoutMs ?? DEFAULT_CURSOR_DECISION_TIMEOUT_MS;
+    this.maxPendingDecisions = options.maxPendingDecisions ?? DEFAULT_CURSOR_MAX_PENDING_DECISIONS;
+    this.authorizedSenders = options.decisionAuthorizedSenders ? new Set(options.decisionAuthorizedSenders) : null;
+    this.decisionLogger = resolveLogger(options.logger);
+  }
+  async onMessage(message, tools, history, participantsMessage, contactsMessage, context) {
+    if (await this.handleControl(message, tools, context.roomId)) {
+      return;
+    }
+    await this.withCursorTurnLock(() => super.onMessage(message, tools, history, participantsMessage, contactsMessage, context));
+  }
+  async onAcpTurnStarted(message, tools, context) {
+    const turn = { messageId: message.id, roomId: context.roomId, tools, requesterId: message.senderId };
+    this.turns.set(context.roomId, turn);
+    this.activeTurn = turn;
+  }
+  async onAcpSessionReady(message, _tools, context, sessionId) {
+    const turn = this.turns.get(context.roomId);
+    if (turn?.messageId === message.id) {
+      turn.sessionId = sessionId;
+    }
+  }
+  async onAcpTurnFinished(message, _tools, context) {
+    const turn = this.turns.get(context.roomId);
+    if (turn?.messageId === message.id) {
+      this.turns.delete(context.roomId);
+      this.cancelRoom(context.roomId);
+    }
+    if (this.activeTurn?.messageId === message.id) {
+      this.activeTurn = null;
+    }
+  }
+  async onCleanup(roomId) {
+    const sessionId = this.turns.get(roomId)?.sessionId;
+    this.cancelRoom(roomId);
+    this.turns.delete(roomId);
+    if (this.activeTurn?.roomId === roomId) {
+      this.activeTurn = null;
+    }
+    await super.onCleanup(roomId);
+    if (sessionId) {
+      this.extensions.forgetSession(sessionId);
+    }
+  }
+  async stop() {
+    for (const decision of this.pending.values()) {
+      decision.resolve(void 0);
+    }
+    this.pending.clear();
+    this.turns.clear();
+    this.activeTurn = null;
+    this.extensions.clearSessions();
+    await super.stop();
+  }
+  async resolveExtension(method, params, sessionId) {
+    const roomId = sessionId ? this.roomIdForSession(sessionId) : this.activeTurn?.roomId;
+    const turn = roomId ? this.turns.get(roomId) : void 0;
+    if (!turn || sessionId && turn.sessionId !== sessionId) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    if (method === "cursor/ask_question") {
+      return this.resolveQuestion(turn.roomId, turn, params);
+    }
+    if (method === "cursor/create_plan") {
+      return this.resolvePlan(turn.roomId, turn, params);
+    }
+    return {};
+  }
+  async resolveCursorPermission(request, signal) {
+    if (this.approvalMode === "autoAccept") {
+      return allowOption(request.options)?.optionId;
+    }
+    if (this.approvalMode === "autoDecline") {
+      return void 0;
+    }
+    const turn = this.turns.get(request.roomId);
+    if (!turn) {
+      return void 0;
+    }
+    const options = request.options.map((option) => option.optionId);
+    const token = await this.waitForDecision("permission", request.roomId, turn, /* @__PURE__ */ new Map([["permission", options]]), /* @__PURE__ */ new Set(), `Cursor needs permission. Reply \`/cursor select {token} option-id\` or \`/cursor deny {token}\`.`, signal);
+    return typeof token === "string" && options.includes(token) ? token : void 0;
+  }
+  extensionSessionId() {
+    return this.activeTurn?.sessionId ?? null;
+  }
+  async resolveQuestion(roomId, turn, params) {
+    const questions = questionChoices(params.questions);
+    if (questions.choices.size === 0) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    if (this.questionMode === "autoCancel") {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    if (this.questionMode === "autoFirst") {
+      return answered(Object.fromEntries([...questions.choices].map(([id, options]) => [id, [options[0]]])));
+    }
+    const result = await this.waitForDecision("question", roomId, turn, questions.choices, questions.multiSelect, "Cursor needs input. Reply `/cursor answer {token} question-id=option-id[,option-id] ...`.");
+    return isRecord3(result) ? result : { outcome: { outcome: "cancelled" } };
+  }
+  async resolvePlan(roomId, turn, params) {
+    if (this.planMode === "autoAccept") {
+      return { outcome: { outcome: "accepted" } };
+    }
+    if (this.planMode === "autoDecline") {
+      return { outcome: { outcome: "rejected" } };
+    }
+    const title = stringValue(params.title) ?? "Cursor plan";
+    const result = await this.waitForDecision("plan", roomId, turn, /* @__PURE__ */ new Map(), /* @__PURE__ */ new Set(), `${title} needs approval. Reply \`/cursor accept {token}\` or \`/cursor reject {token}\`.`);
+    return isRecord3(result) ? result : { outcome: { outcome: "cancelled" } };
+  }
+  async waitForDecision(kind, roomId, turn, choices, multiSelect, prompt, signal) {
+    if (this.pending.size >= this.maxPendingDecisions) {
+      this.pending.values().next().value?.resolve(void 0);
+    }
+    const token = crypto.randomUUID().slice(0, 8);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => settle(void 0), this.decisionTimeoutMs);
+      const abort = () => settle(void 0);
+      const settle = (value) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        this.pending.delete(token);
+        resolve(value);
+      };
+      this.pending.set(token, { kind, roomId, choices, multiSelect, resolve: settle });
+      signal?.addEventListener("abort", abort, { once: true });
+      void turn.tools.sendMessage(prompt.replaceAll("{token}", token), [turn.requesterId]).catch((error) => {
+        this.decisionLogger.warn("cursor_acp.decision_prompt_delivery_failed", { roomId, kind, error: String(error) });
+        settle(void 0);
+      });
+    });
+  }
+  async handleControl(message, tools, roomId) {
+    const words = message.content.trim().split(/\s+/);
+    if (words[0]?.toLowerCase() !== "/cursor") {
+      return false;
+    }
+    if (words.length === 1 || words[1]?.toLowerCase() === "decisions") {
+      const entries = [...this.pending.entries()].filter(([, decision2]) => decision2.roomId === roomId).map(([token2, decision2]) => `\`${token2}\` (${decision2.kind})`);
+      await tools.sendMessage(`Pending Cursor decisions: ${entries.join(", ") || "none"}`);
+      return true;
+    }
+    const [_, action, token, ...args] = words;
+    const decision = token ? this.pending.get(token) : void 0;
+    if (!decision || decision.roomId !== roomId) {
+      await tools.sendMessage(`Cursor decision \`${token ?? ""}\` is not pending.`);
+      return true;
+    }
+    if (this.authorizedSenders && !this.authorizedSenders.has(message.senderId)) {
+      await tools.sendMessage("You are not authorized to resolve Cursor decisions.");
+      return true;
+    }
+    const result = commandResult(action ?? "", args, decision);
+    if (result === null) {
+      await tools.sendMessage(`That command is not valid for Cursor ${decision.kind} decision \`${token}\`.`);
+      return true;
+    }
+    decision.resolve(result);
+    await tools.sendMessage(`Cursor ${decision.kind} decision \`${token}\` resolved.`);
+    return true;
+  }
+  cancelRoom(roomId) {
+    for (const [token, decision] of this.pending) {
+      if (decision.roomId === roomId) {
+        decision.resolve(void 0);
+        this.pending.delete(token);
+      }
+    }
+  }
+  async withCursorTurnLock(run) {
+    const queued = this.turnTail.then(run, run);
+    this.turnTail = queued.then(() => void 0, () => void 0);
+    return queued;
+  }
+};
+function cursorEnv(options) {
+  const env = { ...options.env };
+  if (options.apiKey) env.CURSOR_API_KEY ??= options.apiKey;
+  if (options.authToken) env.CURSOR_AUTH_TOKEN ??= options.authToken;
+  return Object.keys(env).length > 0 ? env : void 0;
+}
+function validateOptions(options) {
+  if (options.apiKey && options.authToken) throw new Error("set either apiKey or authToken, not both");
+  if (Array.isArray(options.command) && options.command.length === 0) throw new Error("Cursor ACP command must not be empty");
+  if (options.decisionTimeoutMs !== void 0 && (!Number.isFinite(options.decisionTimeoutMs) || options.decisionTimeoutMs <= 0)) throw new Error("decisionTimeoutMs must be a positive finite number");
+  if (options.maxPendingDecisions !== void 0 && (!Number.isInteger(options.maxPendingDecisions) || options.maxPendingDecisions <= 0)) throw new Error("maxPendingDecisions must be a positive integer");
+}
+function allowOption(options) {
+  return options.find((option) => option.kind === "allow_once") ?? options.find((option) => option.kind === "allow_always");
+}
+function questionChoices(value) {
+  const choices = /* @__PURE__ */ new Map();
+  const multiSelect = /* @__PURE__ */ new Set();
+  if (!Array.isArray(value)) return { choices, multiSelect };
+  for (const question of value) {
+    if (!isRecord3(question) || typeof question.id !== "string" || !Array.isArray(question.options)) continue;
+    const options = question.options.filter(isRecord3).map((option) => stringValue(option.id)).filter((id) => !!id);
+    if (options.length === 0) continue;
+    choices.set(question.id, options);
+    if (question.allowMultiple === true) multiSelect.add(question.id);
+  }
+  return { choices, multiSelect };
+}
+function commandResult(action, args, decision) {
+  if (decision.kind === "permission") return action === "deny" ? void 0 : action === "select" && args.length === 1 && decision.choices.get("permission")?.includes(args[0] ?? "") ? args[0] : null;
+  if (decision.kind === "plan") return action === "accept" ? { outcome: { outcome: "accepted" } } : action === "reject" ? { outcome: { outcome: "rejected" } } : null;
+  if (action !== "answer") return null;
+  const selected = {};
+  for (const argument of args) {
+    const [id, raw] = argument.split("=", 2);
+    const values = raw?.split(",") ?? [];
+    const offered = id ? decision.choices.get(id) : void 0;
+    if (!id || !offered || selected[id] || values.length === 0 || values.length > 1 && !decision.multiSelect.has(id) || values.some((value) => !offered.includes(value))) return null;
+    selected[id] = values;
+  }
+  return Object.keys(selected).length === decision.choices.size ? answered(selected) : null;
+}
+function answered(selected) {
+  return { outcome: { outcome: "answered", answers: Object.entries(selected).map(([questionId, selectedOptionIds]) => ({ questionId, selectedOptionIds })) } };
+}
+function parseTodos(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((todo) => {
+    if (!isRecord3(todo)) return [];
+    const id = stringValue(todo.id);
+    const content = stringValue(todo.content);
+    const status = stringValue(todo.status);
+    return id && content && status ? [{ id, content, status }] : [];
+  });
+}
+function todoMark(status) {
+  switch (status) {
+    case "completed":
+      return "x";
+    case "in_progress":
+      return "~";
+    case "cancelled":
+      return "-";
+    default:
+      return " ";
+  }
+}
+function isRecord3(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
 // src/core/index.ts
 var import_band_sdk_core13 = require("@band-ai/band-sdk-core");
 init_protocols();
@@ -18633,6 +19157,7 @@ init_schemas();
   A2AAdapter,
   A2AGatewayAdapter,
   ACPClientAdapter,
+  AcpSessionConfigError,
   Agent,
   AgentFailure,
   AgentRuntime,
@@ -18644,10 +19169,13 @@ init_schemas();
   ClaudeSDKAdapter,
   CodexAdapter,
   CopilotACPAdapter,
+  CursorACPAdapter,
   DEFAULT_COPILOT_ACP_COMMAND,
+  DEFAULT_CURSOR_ACP_COMMAND,
   DEFAULT_OMP_ACP_COMMAND,
   DefaultPreprocessor,
   DeliveryFailedError,
+  FAILURE_CODE_SESSION_CONFIG,
   FAILURE_EVENT_TYPE,
   FAILURE_METADATA_KEY,
   GeminiAdapter,
@@ -18657,6 +19185,7 @@ init_schemas();
   LettaAdapter,
   MCP_SERVER_NAME,
   MCP_TOOL_PREFIX,
+  MISSING_CONFIG_OPTIONS_REASON,
   OmpACPAdapter,
   OpenAIAdapter,
   OpencodeAdapter,
@@ -18669,6 +19198,7 @@ init_schemas();
   VercelAISDKAdapter,
   WebSocketDisconnectError,
   agentFailure,
+  applySessionConfigSelections,
   deliverReply,
   deriveDefaultRestUrl,
   isDirectExecution,