@band-ai/sdk 0.4.1 → 0.4.3

package/README.md

@@ -388,7 +388,7 @@ pnpm install
 cp agent_config.yaml.example agent_config.yaml  # add your credentials
 
 npx tsx examples/basic/basic-agent.ts
-npx tsx examples/openai/openai-agent.ts
+npx tsx examples/openai/01_basic_agent.ts
 ```
 
 ## Architecture

package/dist/{CopilotACPAdapter-B_AVyAl6.d.ts → CursorACPAdapter-7-Jtl1LV.d.ts}

@@ -7,7 +7,8 @@ import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from '.
 import { u as GoogleADKMessages, s as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, C as ChatTurn, v as OpencodeSessionState, O as OpencodeHistoryConverter, r as ACPClientSessionState } from './acp-client-DUXyczlF.js';
 import { c as createBandMcpBackend } from './backends-CgsPQa9B.js';
 import { M as McpToolRegistration } from './sdk-Cin80BTC.js';
-import { Client, ClientSideConnection, RequestPermissionRequest, McpServer, ClientCapabilities, SessionMode, SessionConfigOption, SessionConfigSelectOption } from '@agentclientprotocol/sdk';
+import { SessionConfigOption, Client, ClientSideConnection, RequestPermissionRequest, McpServer, ClientCapabilities, SessionMode, SessionConfigSelectOption } from '@agentclientprotocol/sdk';
+import { AgentFailure } from '@band-ai/band-sdk-core';
 
 type GenericAdapterHandler = (args: {
     message: PlatformMessage;
@@ -1338,6 +1339,86 @@ declare class ClaudeSDKAdapter extends SimpleAdapter<HistoryProvider, AdapterToo
     private reportSessionId;
 }
 
+/** Structured Band failure code when an ACP session config selection cannot be applied. */
+declare const FAILURE_CODE_SESSION_CONFIG = "session_config";
+/** Reason when a successful setter omits an array `configOptions` catalog. */
+declare const MISSING_CONFIG_OPTIONS_REASON = "missing_config_options";
+interface ACPConfigSelection {
+    configId: string;
+    value: string | undefined;
+}
+/**
+ * Session configuration selected by a caller. Use an array when the order is
+ * significant: JavaScript object enumeration sorts array-index property names.
+ * The record form remains supported for existing callers.
+ */
+type ACPConfigSelections$1 = readonly ACPConfigSelection[] | Readonly<Record<string, string | undefined>>;
+/**
+ * Deterministic failure applying ACP session configuration. Carries provider,
+ * option id, and optional ACP JSON-RPC code so callers can report a structured
+ * Band failure instead of silently skipping the selection.
+ */
+declare class AcpSessionConfigError extends Error {
+    readonly provider: string;
+    readonly sessionId: string;
+    readonly optionId: string;
+    readonly selectedValue: string | undefined;
+    readonly acpCode: number | undefined;
+    readonly detail: unknown;
+    readonly timedOut: boolean;
+    constructor(input: {
+        provider: string;
+        sessionId: string;
+        optionId: string;
+        message: string;
+        selectedValue?: string;
+        acpCode?: number;
+        detail?: unknown;
+        cause?: unknown;
+        timedOut?: boolean;
+    });
+    toAgentFailure(): AgentFailure;
+}
+type SessionConfigOptionSetter = (params: {
+    sessionId: string;
+    configId: string;
+    value: string;
+}) => Promise<{
+    configOptions?: readonly SessionConfigOption[] | null;
+}>;
+interface ApplySessionConfigSelectionsInput {
+    provider: string;
+    sessionId: string;
+    catalog: readonly SessionConfigOption[];
+    selections: ACPConfigSelections$1;
+    setOption: SessionConfigOptionSetter;
+    timeoutMs: number;
+}
+interface ApplySessionConfigSelectionsResult {
+    catalog: readonly SessionConfigOption[];
+}
+/**
+ * Applies ACP config selections in caller order. Each successful
+ * `session/set_config_option` response replaces the live catalog used to
+ * validate the next selection. Invalid or rejected selections throw
+ * {@link AcpSessionConfigError} — never silently skip or default.
+ */
+declare function applySessionConfigSelections(input: ApplySessionConfigSelectionsInput): Promise<ApplySessionConfigSelectionsResult>;
+
+interface CollectedChunk {
+    chunkType: "text" | "thought" | "tool_call" | "tool_result" | "plan";
+    content: string;
+    metadata: Record<string, unknown>;
+    streamed: boolean;
+}
+interface ACPClientExtensionHandler {
+    extensionSessionId?(): string | null;
+    extMethod?(method: string, params: Record<string, unknown>, context: ACPClientExtensionContext): Promise<Record<string, unknown> | null>;
+    extNotification?(method: string, params: Record<string, unknown>, context: ACPClientExtensionContext): Promise<readonly CollectedChunk[] | void>;
+}
+interface ACPClientExtensionContext {
+    sessionId: string | null;
+}
 interface ACPClientConnectionHandle {
     connection: ClientSideConnection;
     stop(): Promise<void>;
@@ -1370,8 +1451,10 @@ interface ACPConfigRequest {
     sessionId: string;
     configOptions: readonly SessionConfigOption[];
 }
-type ACPConfigSelections = Readonly<Record<string, string | undefined>>;
+type ACPConfigSelections = ACPConfigSelections$1;
 interface ACPClientAdapterBaseOptions {
+    /** Merged into the first-turn system context (character/persona sections for examples). */
+    customSection?: string;
     cwd?: string;
     env?: Record<string, string>;
     mcpServers?: McpServer[];
@@ -1381,6 +1464,7 @@ interface ACPClientAdapterBaseOptions {
     additionalMcpTools?: McpToolRegistration[];
     clientCapabilities?: ClientCapabilities;
     connectionFactory?: ACPClientConnectionFactory;
+    extensionHandler?: ACPClientExtensionHandler;
     resolvePermission?: (request: ACPPermissionRequest, signal: AbortSignal) => Promise<string | undefined>;
     permissionTimeoutMs?: number;
     turnTimeoutMs?: number;
@@ -1412,6 +1496,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly additionalMcpTools;
     private readonly clientCapabilities?;
     private readonly connectionFactory?;
+    private readonly extensionHandler?;
     private readonly tcpEndpoint;
     private readonly roomToSession;
     private readonly sessionToRoom;
@@ -1430,6 +1515,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly permissionTimeoutMs;
     private readonly turnTimeoutMs;
     private readonly logger;
+    private readonly customSection?;
     private backend;
     private backendPromise;
     private client;
@@ -1440,6 +1526,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private started;
     private systemPrompt;
     private spawnPromise;
+    private readonly connectionRetirements;
     private connectionGeneration;
     constructor(options: ACPClientAdapterOptions);
     onStarted(agentName: string, agentDescription: string): Promise<void>;
@@ -1448,6 +1535,18 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
         roomId: string;
     }): Promise<void>;
     private runTurn;
+    protected onAcpTurnStarted(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpTurnFinished(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpSessionReady(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }, _sessionId: string): Promise<void>;
     private abandonTimedOutTurn;
     private withRoomTurnLock;
     onCleanup(roomId: string): Promise<void>;
@@ -1458,14 +1557,19 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private nextRoomGeneration;
     private isCurrentGeneration;
     private raceAgainstConnectionClose;
+    private raceAgainstConnectionRetirement;
     private unlinkRoom;
     private unlinkOwner;
     private sessionKey;
+    protected roomIdForSession(sessionId: string): string | undefined;
     private ensureConnection;
     private spawnConnection;
     private getOrCreateSession;
     private establishSession;
     private configureSessionConfig;
+    private abandonFailedConfigSession;
+    private evictAbandonedSession;
+    private retireConnection;
     private linkOrAbandon;
     private configureSessionMode;
     private configureSessionModel;
@@ -1510,4 +1614,64 @@ declare class CopilotACPAdapter extends ACPClientAdapter {
     constructor(options?: CopilotACPAdapterOptions);
 }
 
-export { type ToolCallingModel as $, A2AAdapter as A, type CopilotACPTcpOptions as B, CODEX_REASONING_EFFORTS as C, DEFAULT_COPILOT_ACP_COMMAND as D, DEFAULT_OMP_ACP_COMMAND as E, type GeminiAdapterOptions as F, GeminiAdapter as G, GenericAdapter as H, type GenericAdapterHandler as I, GoogleADKAdapter as J, type GoogleADKAdapterOptions as K, LangGraphAdapter as L, type LangGraphAdapterOptions as M, type LangGraphGraph as N, LettaAdapter as O, type LettaAdapterOptions as P, OmpACPAdapter as Q, type OmpACPAdapterOptions as R, OpenAIAdapter as S, type OpenAIAdapterOptions as T, OpencodeAdapter as U, type OpencodeAdapterConfig as V, type OpencodeApprovalMode as W, type OpencodeApprovalReply as X, type OpencodeQuestionMode as Y, ParlantAdapter as Z, type ParlantAdapterOptions as _, type A2AAdapterOptions as a, VercelAISDKAdapter as a0, type VercelAISDKAdapterOptions as a1, type A2AClientFactory as a2, type A2AClientLike as a3, type ACPPermissionAbandonReason as a4, type ACPPermissionEndReason as a5, type ACPPermissionRequest as a6, type AnthropicClientFactory as a7, AnthropicToolCallingModel as a8, type AnthropicToolCallingModelOptions as a9, type OpenAIToolCallingModelOptions as aA, type OpencodeClientLike as aB, type ParlantClientFactory as aC, type ParlantClientLike as aD, type ToolCall as aE, ToolCallingAdapter as aF, type ToolCallingAdapterOptions as aG, type ToolCallingModelRequest as aH, type ToolCallingResponse as aI, type ToolResult as aJ, type TurnStartParams as aK, VercelAISDKToolCallingModel as aL, type VercelAISDKToolCallingModelOptions as aM, runSingleToolRound as aN, type ClaudeSDKQuery as aa, type ClaudeSDKQueryParams as ab, CodexAppServerStdioClient as ac, type CodexClientLike as ad, CodexJsonRpcError as ae, type DynamicToolCallParams as af, type DynamicToolCallResponse as ag, type DynamicToolSpec as ah, type GeminiClientFactory as ai, GeminiToolCallingModel as aj, type GeminiToolCallingModelOptions as ak, HttpOpencodeClient as al, type HttpOpencodeClientOptions as am, HttpStatusError as an, type LettaAgentCreateParams as ao, type LettaClientFactory as ap, type LettaClientLike as aq, LettaHistoryConverter as ar, type LettaMessage as as, type LettaMessageCreateParams as at, type LettaMessages as au, type LettaRequestOptions as av, type LettaResponse as aw, type LettaResponseMessage as ax, type OpenAIClientFactory as ay, OpenAIToolCallingModel as az, A2AGatewayAdapter as b, ACPClientAdapter as c, type ACPClientAdapterBaseOptions as d, type ACPClientAdapterOptions as e, type ACPClientStdioOptions as f, type ACPClientTcpOptions as g, type ACPConfigRequest as h, type ACPConfigSelections as i, AnthropicAdapter as j, type AnthropicAdapterOptions as k, CODEX_REASONING_SUMMARIES as l, CODEX_WEB_SEARCH_MODES as m, type ClaudePermissionMode as n, ClaudeSDKAdapter as o, type ClaudeSDKAdapterOptions as p, CodexAdapter as q, type CodexAdapterConfig as r, type CodexApprovalPolicy as s, type CodexReasoningEffort as t, type CodexReasoningSummary as u, type CodexSandboxMode as v, type CodexWebSearchMode as w, CopilotACPAdapter as x, type CopilotACPAdapterOptions as y, type CopilotACPStdioOptions as z };
+declare const DEFAULT_CURSOR_ACP_COMMAND: readonly ["agent", "acp"];
+type CursorApprovalMode = "manual" | "autoAccept" | "autoDecline";
+type CursorQuestionMode = "manual" | "autoFirst" | "autoCancel";
+type CursorPlanMode = "manual" | "autoAccept" | "autoDecline";
+interface CursorACPAdapterOptions extends Omit<ACPClientStdioOptions, "command" | "authMethod" | "env" | "extensionHandler" | "resolvePermission"> {
+    command?: string | string[];
+    env?: Record<string, string>;
+    apiKey?: string;
+    authToken?: string;
+    approvalMode?: CursorApprovalMode;
+    questionMode?: CursorQuestionMode;
+    planMode?: CursorPlanMode;
+    decisionTimeoutMs?: number;
+    maxPendingDecisions?: number;
+    decisionAuthorizedSenders?: readonly string[];
+}
+declare class CursorACPAdapter extends ACPClientAdapter {
+    protected readonly provider = "cursor-acp";
+    private readonly approvalMode;
+    private readonly questionMode;
+    private readonly planMode;
+    private readonly decisionTimeoutMs;
+    private readonly maxPendingDecisions;
+    private readonly authorizedSenders;
+    private readonly decisionLogger;
+    private readonly extensions;
+    private readonly turns;
+    private readonly pending;
+    private activeTurn;
+    private turnTail;
+    constructor(options?: CursorACPAdapterOptions);
+    onMessage(message: PlatformMessage, tools: AdapterToolsProtocol, history: ACPClientSessionState, participantsMessage: string | null, contactsMessage: string | null, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpTurnStarted(message: PlatformMessage, tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpSessionReady(message: PlatformMessage, _tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }, sessionId: string): Promise<void>;
+    protected onAcpTurnFinished(message: PlatformMessage, _tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    onCleanup(roomId: string): Promise<void>;
+    stop(): Promise<void>;
+    resolveExtension(method: string, params: Record<string, unknown>, sessionId: string | null): Promise<Record<string, unknown>>;
+    resolveCursorPermission(request: ACPPermissionRequest, signal: AbortSignal): Promise<string | undefined>;
+    extensionSessionId(): string | null;
+    private resolveQuestion;
+    private resolvePlan;
+    private waitForDecision;
+    private handleControl;
+    private cancelRoom;
+    private withCursorTurnLock;
+}
+
+export { OpenAIAdapter as $, A2AAdapter as A, type CopilotACPStdioOptions as B, CODEX_REASONING_EFFORTS as C, type CopilotACPTcpOptions as D, CursorACPAdapter as E, type CursorACPAdapterOptions as F, type CursorApprovalMode as G, type CursorPlanMode as H, type CursorQuestionMode as I, DEFAULT_COPILOT_ACP_COMMAND as J, DEFAULT_CURSOR_ACP_COMMAND as K, DEFAULT_OMP_ACP_COMMAND as L, FAILURE_CODE_SESSION_CONFIG as M, GeminiAdapter as N, type GeminiAdapterOptions as O, GenericAdapter as P, type GenericAdapterHandler as Q, GoogleADKAdapter as R, type GoogleADKAdapterOptions as S, LangGraphAdapter as T, type LangGraphAdapterOptions as U, type LangGraphGraph as V, LettaAdapter as W, type LettaAdapterOptions as X, MISSING_CONFIG_OPTIONS_REASON as Y, OmpACPAdapter as Z, type OmpACPAdapterOptions as _, type A2AAdapterOptions as a, type OpenAIAdapterOptions as a0, OpencodeAdapter as a1, type OpencodeAdapterConfig as a2, type OpencodeApprovalMode as a3, type OpencodeApprovalReply as a4, type OpencodeQuestionMode as a5, ParlantAdapter as a6, type ParlantAdapterOptions as a7, type ToolCallingModel as a8, VercelAISDKAdapter as a9, type LettaClientLike as aA, LettaHistoryConverter as aB, type LettaMessage as aC, type LettaMessageCreateParams as aD, type LettaMessages as aE, type LettaRequestOptions as aF, type LettaResponse as aG, type LettaResponseMessage as aH, type OpenAIClientFactory as aI, OpenAIToolCallingModel as aJ, type OpenAIToolCallingModelOptions as aK, type OpencodeClientLike as aL, type ParlantClientFactory as aM, type ParlantClientLike as aN, type ToolCall as aO, ToolCallingAdapter as aP, type ToolCallingAdapterOptions as aQ, type ToolCallingModelRequest as aR, type ToolCallingResponse as aS, type ToolResult as aT, type TurnStartParams as aU, VercelAISDKToolCallingModel as aV, type VercelAISDKToolCallingModelOptions as aW, runSingleToolRound as aX, type VercelAISDKAdapterOptions as aa, applySessionConfigSelections as ab, type A2AClientFactory as ac, type A2AClientLike as ad, type ACPPermissionAbandonReason as ae, type ACPPermissionEndReason as af, type ACPPermissionRequest as ag, type AnthropicClientFactory as ah, AnthropicToolCallingModel as ai, type AnthropicToolCallingModelOptions as aj, type ClaudeSDKQuery as ak, type ClaudeSDKQueryParams as al, CodexAppServerStdioClient as am, type CodexClientLike as an, CodexJsonRpcError as ao, type DynamicToolCallParams as ap, type DynamicToolCallResponse as aq, type DynamicToolSpec as ar, type GeminiClientFactory as as, GeminiToolCallingModel as at, type GeminiToolCallingModelOptions as au, HttpOpencodeClient as av, type HttpOpencodeClientOptions as aw, HttpStatusError as ax, type LettaAgentCreateParams as ay, type LettaClientFactory as az, A2AGatewayAdapter as b, ACPClientAdapter as c, type ACPClientAdapterBaseOptions as d, type ACPClientAdapterOptions as e, type ACPClientStdioOptions as f, type ACPClientTcpOptions as g, type ACPConfigRequest as h, type ACPConfigSelections as i, AcpSessionConfigError as j, AnthropicAdapter as k, type AnthropicAdapterOptions as l, CODEX_REASONING_SUMMARIES as m, CODEX_WEB_SEARCH_MODES as n, type ClaudePermissionMode as o, ClaudeSDKAdapter as p, type ClaudeSDKAdapterOptions as q, CodexAdapter as r, type CodexAdapterConfig as s, type CodexApprovalPolicy as t, type CodexReasoningEffort as u, type CodexReasoningSummary as v, type CodexSandboxMode as w, type CodexWebSearchMode as x, CopilotACPAdapter as y, type CopilotACPAdapterOptions as z };

package/dist/{CopilotACPAdapter-Clid9xGR.d.cts → CursorACPAdapter-_YhrXRWq.d.cts}

@@ -7,7 +7,8 @@ import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from '.
 import { u as GoogleADKMessages, s as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, C as ChatTurn, v as OpencodeSessionState, O as OpencodeHistoryConverter, r as ACPClientSessionState } from './acp-client-D-I_5lK-.cjs';
 import { c as createBandMcpBackend } from './backends-Dh2WXcHQ.cjs';
 import { M as McpToolRegistration } from './sdk-CXNqzoY1.cjs';
-import { Client, ClientSideConnection, RequestPermissionRequest, McpServer, ClientCapabilities, SessionMode, SessionConfigOption, SessionConfigSelectOption } from '@agentclientprotocol/sdk';
+import { SessionConfigOption, Client, ClientSideConnection, RequestPermissionRequest, McpServer, ClientCapabilities, SessionMode, SessionConfigSelectOption } from '@agentclientprotocol/sdk';
+import { AgentFailure } from '@band-ai/band-sdk-core';
 
 type GenericAdapterHandler = (args: {
     message: PlatformMessage;
@@ -1338,6 +1339,86 @@ declare class ClaudeSDKAdapter extends SimpleAdapter<HistoryProvider, AdapterToo
     private reportSessionId;
 }
 
+/** Structured Band failure code when an ACP session config selection cannot be applied. */
+declare const FAILURE_CODE_SESSION_CONFIG = "session_config";
+/** Reason when a successful setter omits an array `configOptions` catalog. */
+declare const MISSING_CONFIG_OPTIONS_REASON = "missing_config_options";
+interface ACPConfigSelection {
+    configId: string;
+    value: string | undefined;
+}
+/**
+ * Session configuration selected by a caller. Use an array when the order is
+ * significant: JavaScript object enumeration sorts array-index property names.
+ * The record form remains supported for existing callers.
+ */
+type ACPConfigSelections$1 = readonly ACPConfigSelection[] | Readonly<Record<string, string | undefined>>;
+/**
+ * Deterministic failure applying ACP session configuration. Carries provider,
+ * option id, and optional ACP JSON-RPC code so callers can report a structured
+ * Band failure instead of silently skipping the selection.
+ */
+declare class AcpSessionConfigError extends Error {
+    readonly provider: string;
+    readonly sessionId: string;
+    readonly optionId: string;
+    readonly selectedValue: string | undefined;
+    readonly acpCode: number | undefined;
+    readonly detail: unknown;
+    readonly timedOut: boolean;
+    constructor(input: {
+        provider: string;
+        sessionId: string;
+        optionId: string;
+        message: string;
+        selectedValue?: string;
+        acpCode?: number;
+        detail?: unknown;
+        cause?: unknown;
+        timedOut?: boolean;
+    });
+    toAgentFailure(): AgentFailure;
+}
+type SessionConfigOptionSetter = (params: {
+    sessionId: string;
+    configId: string;
+    value: string;
+}) => Promise<{
+    configOptions?: readonly SessionConfigOption[] | null;
+}>;
+interface ApplySessionConfigSelectionsInput {
+    provider: string;
+    sessionId: string;
+    catalog: readonly SessionConfigOption[];
+    selections: ACPConfigSelections$1;
+    setOption: SessionConfigOptionSetter;
+    timeoutMs: number;
+}
+interface ApplySessionConfigSelectionsResult {
+    catalog: readonly SessionConfigOption[];
+}
+/**
+ * Applies ACP config selections in caller order. Each successful
+ * `session/set_config_option` response replaces the live catalog used to
+ * validate the next selection. Invalid or rejected selections throw
+ * {@link AcpSessionConfigError} — never silently skip or default.
+ */
+declare function applySessionConfigSelections(input: ApplySessionConfigSelectionsInput): Promise<ApplySessionConfigSelectionsResult>;
+
+interface CollectedChunk {
+    chunkType: "text" | "thought" | "tool_call" | "tool_result" | "plan";
+    content: string;
+    metadata: Record<string, unknown>;
+    streamed: boolean;
+}
+interface ACPClientExtensionHandler {
+    extensionSessionId?(): string | null;
+    extMethod?(method: string, params: Record<string, unknown>, context: ACPClientExtensionContext): Promise<Record<string, unknown> | null>;
+    extNotification?(method: string, params: Record<string, unknown>, context: ACPClientExtensionContext): Promise<readonly CollectedChunk[] | void>;
+}
+interface ACPClientExtensionContext {
+    sessionId: string | null;
+}
 interface ACPClientConnectionHandle {
     connection: ClientSideConnection;
     stop(): Promise<void>;
@@ -1370,8 +1451,10 @@ interface ACPConfigRequest {
     sessionId: string;
     configOptions: readonly SessionConfigOption[];
 }
-type ACPConfigSelections = Readonly<Record<string, string | undefined>>;
+type ACPConfigSelections = ACPConfigSelections$1;
 interface ACPClientAdapterBaseOptions {
+    /** Merged into the first-turn system context (character/persona sections for examples). */
+    customSection?: string;
     cwd?: string;
     env?: Record<string, string>;
     mcpServers?: McpServer[];
@@ -1381,6 +1464,7 @@ interface ACPClientAdapterBaseOptions {
     additionalMcpTools?: McpToolRegistration[];
     clientCapabilities?: ClientCapabilities;
     connectionFactory?: ACPClientConnectionFactory;
+    extensionHandler?: ACPClientExtensionHandler;
     resolvePermission?: (request: ACPPermissionRequest, signal: AbortSignal) => Promise<string | undefined>;
     permissionTimeoutMs?: number;
     turnTimeoutMs?: number;
@@ -1412,6 +1496,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly additionalMcpTools;
     private readonly clientCapabilities?;
     private readonly connectionFactory?;
+    private readonly extensionHandler?;
     private readonly tcpEndpoint;
     private readonly roomToSession;
     private readonly sessionToRoom;
@@ -1430,6 +1515,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly permissionTimeoutMs;
     private readonly turnTimeoutMs;
     private readonly logger;
+    private readonly customSection?;
     private backend;
     private backendPromise;
     private client;
@@ -1440,6 +1526,7 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private started;
     private systemPrompt;
     private spawnPromise;
+    private readonly connectionRetirements;
     private connectionGeneration;
     constructor(options: ACPClientAdapterOptions);
     onStarted(agentName: string, agentDescription: string): Promise<void>;
@@ -1448,6 +1535,18 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
         roomId: string;
     }): Promise<void>;
     private runTurn;
+    protected onAcpTurnStarted(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpTurnFinished(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpSessionReady(_message: PlatformMessage, _tools: AdapterToolsProtocol, _context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }, _sessionId: string): Promise<void>;
     private abandonTimedOutTurn;
     private withRoomTurnLock;
     onCleanup(roomId: string): Promise<void>;
@@ -1458,14 +1557,19 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private nextRoomGeneration;
     private isCurrentGeneration;
     private raceAgainstConnectionClose;
+    private raceAgainstConnectionRetirement;
     private unlinkRoom;
     private unlinkOwner;
     private sessionKey;
+    protected roomIdForSession(sessionId: string): string | undefined;
     private ensureConnection;
     private spawnConnection;
     private getOrCreateSession;
     private establishSession;
     private configureSessionConfig;
+    private abandonFailedConfigSession;
+    private evictAbandonedSession;
+    private retireConnection;
     private linkOrAbandon;
     private configureSessionMode;
     private configureSessionModel;
@@ -1510,4 +1614,64 @@ declare class CopilotACPAdapter extends ACPClientAdapter {
     constructor(options?: CopilotACPAdapterOptions);
 }
 
-export { type ToolCallingModel as $, A2AAdapter as A, type CopilotACPTcpOptions as B, CODEX_REASONING_EFFORTS as C, DEFAULT_COPILOT_ACP_COMMAND as D, DEFAULT_OMP_ACP_COMMAND as E, type GeminiAdapterOptions as F, GeminiAdapter as G, GenericAdapter as H, type GenericAdapterHandler as I, GoogleADKAdapter as J, type GoogleADKAdapterOptions as K, LangGraphAdapter as L, type LangGraphAdapterOptions as M, type LangGraphGraph as N, LettaAdapter as O, type LettaAdapterOptions as P, OmpACPAdapter as Q, type OmpACPAdapterOptions as R, OpenAIAdapter as S, type OpenAIAdapterOptions as T, OpencodeAdapter as U, type OpencodeAdapterConfig as V, type OpencodeApprovalMode as W, type OpencodeApprovalReply as X, type OpencodeQuestionMode as Y, ParlantAdapter as Z, type ParlantAdapterOptions as _, type A2AAdapterOptions as a, VercelAISDKAdapter as a0, type VercelAISDKAdapterOptions as a1, type A2AClientFactory as a2, type A2AClientLike as a3, type ACPPermissionAbandonReason as a4, type ACPPermissionEndReason as a5, type ACPPermissionRequest as a6, type AnthropicClientFactory as a7, AnthropicToolCallingModel as a8, type AnthropicToolCallingModelOptions as a9, type OpenAIToolCallingModelOptions as aA, type OpencodeClientLike as aB, type ParlantClientFactory as aC, type ParlantClientLike as aD, type ToolCall as aE, ToolCallingAdapter as aF, type ToolCallingAdapterOptions as aG, type ToolCallingModelRequest as aH, type ToolCallingResponse as aI, type ToolResult as aJ, type TurnStartParams as aK, VercelAISDKToolCallingModel as aL, type VercelAISDKToolCallingModelOptions as aM, runSingleToolRound as aN, type ClaudeSDKQuery as aa, type ClaudeSDKQueryParams as ab, CodexAppServerStdioClient as ac, type CodexClientLike as ad, CodexJsonRpcError as ae, type DynamicToolCallParams as af, type DynamicToolCallResponse as ag, type DynamicToolSpec as ah, type GeminiClientFactory as ai, GeminiToolCallingModel as aj, type GeminiToolCallingModelOptions as ak, HttpOpencodeClient as al, type HttpOpencodeClientOptions as am, HttpStatusError as an, type LettaAgentCreateParams as ao, type LettaClientFactory as ap, type LettaClientLike as aq, LettaHistoryConverter as ar, type LettaMessage as as, type LettaMessageCreateParams as at, type LettaMessages as au, type LettaRequestOptions as av, type LettaResponse as aw, type LettaResponseMessage as ax, type OpenAIClientFactory as ay, OpenAIToolCallingModel as az, A2AGatewayAdapter as b, ACPClientAdapter as c, type ACPClientAdapterBaseOptions as d, type ACPClientAdapterOptions as e, type ACPClientStdioOptions as f, type ACPClientTcpOptions as g, type ACPConfigRequest as h, type ACPConfigSelections as i, AnthropicAdapter as j, type AnthropicAdapterOptions as k, CODEX_REASONING_SUMMARIES as l, CODEX_WEB_SEARCH_MODES as m, type ClaudePermissionMode as n, ClaudeSDKAdapter as o, type ClaudeSDKAdapterOptions as p, CodexAdapter as q, type CodexAdapterConfig as r, type CodexApprovalPolicy as s, type CodexReasoningEffort as t, type CodexReasoningSummary as u, type CodexSandboxMode as v, type CodexWebSearchMode as w, CopilotACPAdapter as x, type CopilotACPAdapterOptions as y, type CopilotACPStdioOptions as z };
+declare const DEFAULT_CURSOR_ACP_COMMAND: readonly ["agent", "acp"];
+type CursorApprovalMode = "manual" | "autoAccept" | "autoDecline";
+type CursorQuestionMode = "manual" | "autoFirst" | "autoCancel";
+type CursorPlanMode = "manual" | "autoAccept" | "autoDecline";
+interface CursorACPAdapterOptions extends Omit<ACPClientStdioOptions, "command" | "authMethod" | "env" | "extensionHandler" | "resolvePermission"> {
+    command?: string | string[];
+    env?: Record<string, string>;
+    apiKey?: string;
+    authToken?: string;
+    approvalMode?: CursorApprovalMode;
+    questionMode?: CursorQuestionMode;
+    planMode?: CursorPlanMode;
+    decisionTimeoutMs?: number;
+    maxPendingDecisions?: number;
+    decisionAuthorizedSenders?: readonly string[];
+}
+declare class CursorACPAdapter extends ACPClientAdapter {
+    protected readonly provider = "cursor-acp";
+    private readonly approvalMode;
+    private readonly questionMode;
+    private readonly planMode;
+    private readonly decisionTimeoutMs;
+    private readonly maxPendingDecisions;
+    private readonly authorizedSenders;
+    private readonly decisionLogger;
+    private readonly extensions;
+    private readonly turns;
+    private readonly pending;
+    private activeTurn;
+    private turnTail;
+    constructor(options?: CursorACPAdapterOptions);
+    onMessage(message: PlatformMessage, tools: AdapterToolsProtocol, history: ACPClientSessionState, participantsMessage: string | null, contactsMessage: string | null, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpTurnStarted(message: PlatformMessage, tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    protected onAcpSessionReady(message: PlatformMessage, _tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }, sessionId: string): Promise<void>;
+    protected onAcpTurnFinished(message: PlatformMessage, _tools: AdapterToolsProtocol, context: {
+        isSessionBootstrap: boolean;
+        roomId: string;
+    }): Promise<void>;
+    onCleanup(roomId: string): Promise<void>;
+    stop(): Promise<void>;
+    resolveExtension(method: string, params: Record<string, unknown>, sessionId: string | null): Promise<Record<string, unknown>>;
+    resolveCursorPermission(request: ACPPermissionRequest, signal: AbortSignal): Promise<string | undefined>;
+    extensionSessionId(): string | null;
+    private resolveQuestion;
+    private resolvePlan;
+    private waitForDecision;
+    private handleControl;
+    private cancelRoom;
+    private withCursorTurnLock;
+}
+
+export { OpenAIAdapter as $, A2AAdapter as A, type CopilotACPStdioOptions as B, CODEX_REASONING_EFFORTS as C, type CopilotACPTcpOptions as D, CursorACPAdapter as E, type CursorACPAdapterOptions as F, type CursorApprovalMode as G, type CursorPlanMode as H, type CursorQuestionMode as I, DEFAULT_COPILOT_ACP_COMMAND as J, DEFAULT_CURSOR_ACP_COMMAND as K, DEFAULT_OMP_ACP_COMMAND as L, FAILURE_CODE_SESSION_CONFIG as M, GeminiAdapter as N, type GeminiAdapterOptions as O, GenericAdapter as P, type GenericAdapterHandler as Q, GoogleADKAdapter as R, type GoogleADKAdapterOptions as S, LangGraphAdapter as T, type LangGraphAdapterOptions as U, type LangGraphGraph as V, LettaAdapter as W, type LettaAdapterOptions as X, MISSING_CONFIG_OPTIONS_REASON as Y, OmpACPAdapter as Z, type OmpACPAdapterOptions as _, type A2AAdapterOptions as a, type OpenAIAdapterOptions as a0, OpencodeAdapter as a1, type OpencodeAdapterConfig as a2, type OpencodeApprovalMode as a3, type OpencodeApprovalReply as a4, type OpencodeQuestionMode as a5, ParlantAdapter as a6, type ParlantAdapterOptions as a7, type ToolCallingModel as a8, VercelAISDKAdapter as a9, type LettaClientLike as aA, LettaHistoryConverter as aB, type LettaMessage as aC, type LettaMessageCreateParams as aD, type LettaMessages as aE, type LettaRequestOptions as aF, type LettaResponse as aG, type LettaResponseMessage as aH, type OpenAIClientFactory as aI, OpenAIToolCallingModel as aJ, type OpenAIToolCallingModelOptions as aK, type OpencodeClientLike as aL, type ParlantClientFactory as aM, type ParlantClientLike as aN, type ToolCall as aO, ToolCallingAdapter as aP, type ToolCallingAdapterOptions as aQ, type ToolCallingModelRequest as aR, type ToolCallingResponse as aS, type ToolResult as aT, type TurnStartParams as aU, VercelAISDKToolCallingModel as aV, type VercelAISDKToolCallingModelOptions as aW, runSingleToolRound as aX, type VercelAISDKAdapterOptions as aa, applySessionConfigSelections as ab, type A2AClientFactory as ac, type A2AClientLike as ad, type ACPPermissionAbandonReason as ae, type ACPPermissionEndReason as af, type ACPPermissionRequest as ag, type AnthropicClientFactory as ah, AnthropicToolCallingModel as ai, type AnthropicToolCallingModelOptions as aj, type ClaudeSDKQuery as ak, type ClaudeSDKQueryParams as al, CodexAppServerStdioClient as am, type CodexClientLike as an, CodexJsonRpcError as ao, type DynamicToolCallParams as ap, type DynamicToolCallResponse as aq, type DynamicToolSpec as ar, type GeminiClientFactory as as, GeminiToolCallingModel as at, type GeminiToolCallingModelOptions as au, HttpOpencodeClient as av, type HttpOpencodeClientOptions as aw, HttpStatusError as ax, type LettaAgentCreateParams as ay, type LettaClientFactory as az, A2AGatewayAdapter as b, ACPClientAdapter as c, type ACPClientAdapterBaseOptions as d, type ACPClientAdapterOptions as e, type ACPClientStdioOptions as f, type ACPClientTcpOptions as g, type ACPConfigRequest as h, type ACPConfigSelections as i, AcpSessionConfigError as j, AnthropicAdapter as k, type AnthropicAdapterOptions as l, CODEX_REASONING_SUMMARIES as m, CODEX_WEB_SEARCH_MODES as n, type ClaudePermissionMode as o, ClaudeSDKAdapter as p, type ClaudeSDKAdapterOptions as q, CodexAdapter as r, type CodexAdapterConfig as s, type CodexApprovalPolicy as t, type CodexReasoningEffort as u, type CodexReasoningSummary as v, type CodexSandboxMode as w, type CodexWebSearchMode as x, CopilotACPAdapter as y, type CopilotACPAdapterOptions as z };