@band-ai/sdk 0.3.0 → 0.3.1

package/dist/adapters.cjs

@@ -2167,8 +2167,8 @@ var ACPClientAdapter = class extends SimpleAdapter {
   bootstrappedSessions = /* @__PURE__ */ new Set();
   pendingPermissions = /* @__PURE__ */ new Map();
   resolvePermission;
+  resolveSessionMode;
   permissionTimeoutMs;
-  requestedPermissionMode;
   logger;
   backend = null;
   backendPromise = null;
@@ -2197,13 +2197,10 @@ var ACPClientAdapter = class extends SimpleAdapter {
     this.clientCapabilities = options.clientCapabilities;
     this.connectionFactory = options.connectionFactory ?? createSubprocessConnection;
     this.resolvePermission = options.resolvePermission;
+    this.resolveSessionMode = options.resolveSessionMode;
     this.logger = options.logger ?? new NoopLogger();
     this.permissionTimeoutMs = options.permissionTimeoutMs ?? DEFAULT_PERMISSION_TIMEOUT_MS;
-    this.requestedPermissionMode = options.requestedPermissionMode;
-    if (this.requestedPermissionMode !== void 0 && this.requestedPermissionMode.length === 0) {
-      throw new ValidationError("requestedPermissionMode must be a non-empty mode id, got an empty string");
-    }
-    if (this.resolvePermission && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
+    if ((this.resolvePermission || this.resolveSessionMode) && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
       throw new ValidationError(`permissionTimeoutMs must be a positive finite number, got ${options.permissionTimeoutMs}`);
     }
   }
@@ -2367,7 +2364,7 @@ ${messageWithContext}`;
       if (restored.ok) {
         this.activeSessions.add(existingSessionId);
         this.bootstrappedSessions.add(existingSessionId);
-        await this.applyRequestedPermissionMode(connection, existingSessionId, restored.modes);
+        await this.configureSessionMode(roomId, existingSessionId, restored.modes, connection);
         return existingSessionId;
       }
     }
@@ -2377,53 +2374,93 @@ ${messageWithContext}`;
     });
     this.roomToSession.set(roomId, created.sessionId);
     this.activeSessions.add(created.sessionId);
-    await this.applyRequestedPermissionMode(connection, created.sessionId, created.modes);
+    await this.configureSessionMode(roomId, created.sessionId, created.modes, connection);
     return created.sessionId;
   }
-  async tryRestoreSession(connection, sessionId, mcpServers) {
-    const capabilities = this.connectionState?.agentCapabilities;
-    const params = { cwd: this.cwd, mcpServers, sessionId };
-    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
-    if (!restore) {
-      return { ok: false };
-    }
-    try {
-      const restored = await restore();
-      return { ok: true, modes: restored?.modes };
-    } catch {
-      return { ok: false };
-    }
-  }
   // Best-effort: never throws, so a mode switch going wrong can't take a
   // session establishment down with it.
-  async applyRequestedPermissionMode(connection, sessionId, modes) {
-    const requestedModeId = this.requestedPermissionMode;
-    if (!requestedModeId || !modes || modes.currentModeId === requestedModeId) {
+  async configureSessionMode(roomId, sessionId, modes, connection) {
+    if (!this.resolveSessionMode || !modes) {
       return;
     }
     const availableModes = Array.isArray(modes.availableModes) ? modes.availableModes : [];
-    if (!availableModes.some((mode) => mode?.id === requestedModeId)) {
-      this.safeWarn("requested permission mode is not advertised by this session", {
+    if (availableModes.length === 0) {
+      return;
+    }
+    const selectedModeId = await this.resolveSessionModeManually(
+      (signal) => this.resolveSessionMode({
+        roomId,
         sessionId,
-        requestedModeId,
+        currentModeId: modes.currentModeId,
+        modes: availableModes
+      }, signal),
+      connection.signal
+    );
+    if (!selectedModeId || selectedModeId === modes.currentModeId) {
+      return;
+    }
+    if (!availableModes.some((mode) => mode?.id === selectedModeId)) {
+      this.safeWarn("resolveSessionMode selected a mode id this session does not advertise", {
+        sessionId,
+        selectedModeId,
         availableModeIds: availableModes.map((mode) => mode?.id)
       });
       return;
     }
     try {
       await withTimeout(
-        connection.setSessionMode({ sessionId, modeId: requestedModeId }),
+        connection.setSessionMode({ sessionId, modeId: selectedModeId }),
         SET_SESSION_MODE_TIMEOUT_MS,
         `setSessionMode did not respond within ${SET_SESSION_MODE_TIMEOUT_MS}ms`
       );
     } catch (error) {
-      this.safeWarn("failed to switch session into the requested permission mode", {
+      this.safeWarn("failed to switch session into the selected mode", {
         sessionId,
-        requestedModeId,
+        selectedModeId,
         error: String(error)
       });
     }
   }
+  async resolveSessionModeManually(resolver, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener("abort", abort, { once: true });
+    let timer;
+    try {
+      const cancelled = new Promise((resolve) => {
+        controller.signal.addEventListener("abort", () => resolve(void 0), { once: true });
+      });
+      const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), this.permissionTimeoutMs);
+      });
+      return await Promise.race([
+        Promise.resolve().then(() => resolver(controller.signal)).catch((error) => {
+          this.safeWarn("resolveSessionMode threw; preserving the harness default", { error: String(error) });
+          return void 0;
+        }),
+        timeout,
+        cancelled
+      ]);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+  async tryRestoreSession(connection, sessionId, mcpServers) {
+    const capabilities = this.connectionState?.agentCapabilities;
+    const params = { cwd: this.cwd, mcpServers, sessionId };
+    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
+    if (!restore) {
+      return { ok: false };
+    }
+    try {
+      const restored = await restore();
+      return { ok: true, modes: restored?.modes };
+    } catch {
+      return { ok: false };
+    }
+  }
   async buildSessionMcpServers() {
     const mcpServers = [...this.mcpServers];
     if (!this.enableMcpTools) {

package/dist/adapters.d.cts

@@ -1,6 +1,6 @@
 export { A as A2AAdapter, a as A2AAdapterOptions, K as A2AClientFactory, M as A2AClientLike, b as A2AGatewayAdapter, c as AnthropicAdapter, d as AnthropicAdapterOptions, N as AnthropicClientFactory, Q as AnthropicToolCallingModel, R as AnthropicToolCallingModelOptions, C as CODEX_REASONING_EFFORTS, e as CODEX_REASONING_SUMMARIES, f as CODEX_WEB_SEARCH_MODES, g as ClaudePermissionMode, h as ClaudeSDKAdapter, i as ClaudeSDKAdapterOptions, S as ClaudeSDKQuery, U as ClaudeSDKQueryParams, j as CodexAdapter, k as CodexAdapterConfig, W as CodexAppServerStdioClient, l as CodexApprovalPolicy, X as CodexClientLike, Y as CodexJsonRpcError, m as CodexReasoningEffort, n as CodexReasoningSummary, o as CodexSandboxMode, p as CodexWebSearchMode, Z as DynamicToolCallParams, _ as DynamicToolCallResponse, $ as DynamicToolSpec, G as GeminiAdapter, q as GeminiAdapterOptions, a0 as GeminiClientFactory, a1 as GeminiToolCallingModel, a2 as GeminiToolCallingModelOptions, r as GenericAdapter, s as GenericAdapterHandler, t as GoogleADKAdapter, u as GoogleADKAdapterOptions, a3 as HttpOpencodeClient, a4 as HttpOpencodeClientOptions, a5 as HttpStatusError, L as LangGraphAdapter, v as LangGraphAdapterOptions, w as LangGraphGraph, x as LettaAdapter, y as LettaAdapterOptions, a6 as LettaAgentCreateParams, a7 as LettaClientFactory, a8 as LettaClientLike, a9 as LettaHistoryConverter, aa as LettaMessage, ab as LettaMessageCreateParams, ac as LettaMessages, ad as LettaRequestOptions, ae as LettaResponse, af as LettaResponseMessage, O as OpenAIAdapter, z as OpenAIAdapterOptions, ag as OpenAIClientFactory, ah as OpenAIToolCallingModel, ai as OpenAIToolCallingModelOptions, B as OpencodeAdapter, D as OpencodeAdapterConfig, E as OpencodeApprovalMode, F as OpencodeApprovalReply, aj as OpencodeClientLike, H as OpencodeQuestionMode, P as ParlantAdapter, I as ParlantAdapterOptions, ak as ParlantClientFactory, al as ParlantClientLike, am as ToolCall, an as ToolCallingAdapter, ao as ToolCallingAdapterOptions, T as ToolCallingModel, ap as ToolCallingModelRequest, aq as ToolCallingResponse, ar as ToolResult, as as TurnStartParams, V as VercelAISDKAdapter, J as VercelAISDKAdapterOptions, at as VercelAISDKToolCallingModel, au as VercelAISDKToolCallingModelOptions, av as runSingleToolRound } from './ClaudeSDKAdapter-Cx6zhSaG.cjs';
 import * as _agentclientprotocol_sdk from '@agentclientprotocol/sdk';
-import { Client, ClientSideConnection, McpServer, ClientCapabilities, RequestPermissionRequest, SessionModeId, SessionMode, AgentSideConnection, SessionModeState, Agent, InitializeResponse, Implementation, Stream, InitializeRequest, LoadSessionRequest, LoadSessionResponse, ListSessionsRequest, ListSessionsResponse, ForkSessionRequest, ForkSessionResponse, ResumeSessionRequest, ResumeSessionResponse, SetSessionModeRequest, SetSessionModeResponse, SetSessionModelRequest, SetSessionModelResponse, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, AuthenticateRequest, AuthenticateResponse, PromptRequest, PromptResponse } from '@agentclientprotocol/sdk';
+import { Client, ClientSideConnection, McpServer, ClientCapabilities, RequestPermissionRequest, SessionMode, AgentSideConnection, SessionModeState, Agent, InitializeResponse, Implementation, Stream, InitializeRequest, LoadSessionRequest, LoadSessionResponse, ListSessionsRequest, ListSessionsResponse, ForkSessionRequest, ForkSessionResponse, ResumeSessionRequest, ResumeSessionResponse, SetSessionModeRequest, SetSessionModeResponse, SetSessionModelRequest, SetSessionModelResponse, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, AuthenticateRequest, AuthenticateResponse, PromptRequest, PromptResponse } from '@agentclientprotocol/sdk';
 import { A as ACPClientSessionState, a as ACPServerSessionState } from './acp-server-Dlj7D563.cjs';
 export { G as GatewayHistoryConverter } from './acp-server-Dlj7D563.cjs';
 import { S as SimpleAdapter } from './simpleAdapter-BpT4XbZC.cjs';
@@ -41,6 +41,12 @@ type ACPClientConnectionFactory = (client: Client, options: {
     env?: Record<string, string>;
 }) => Promise<ACPClientConnectionHandle>;
 
+interface ACPModeRequest {
+    roomId: string;
+    sessionId: string;
+    currentModeId: string;
+    modes: readonly SessionMode[];
+}
 interface ACPClientAdapterOptions {
     command: string | string[];
     cwd?: string;
@@ -54,7 +60,7 @@ interface ACPClientAdapterOptions {
     connectionFactory?: ACPClientConnectionFactory;
     resolvePermission?: (request: RequestPermissionRequest, signal: AbortSignal) => Promise<string | undefined>;
     permissionTimeoutMs?: number;
-    requestedPermissionMode?: SessionModeId;
+    resolveSessionMode?: (request: ACPModeRequest, signal: AbortSignal) => Promise<string | undefined>;
     logger?: Logger;
 }
 declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, AdapterToolsProtocol> {
@@ -74,8 +80,8 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly bootstrappedSessions;
     private readonly pendingPermissions;
     private readonly resolvePermission?;
+    private readonly resolveSessionMode?;
     private readonly permissionTimeoutMs;
-    private readonly requestedPermissionMode?;
     private readonly logger;
     private backend;
     private backendPromise;
@@ -99,8 +105,9 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private ensureConnection;
     private spawnConnection;
     private getOrCreateSession;
+    private configureSessionMode;
+    private resolveSessionModeManually;
     private tryRestoreSession;
-    private applyRequestedPermissionMode;
     private buildSessionMcpServers;
     private getOrCreateBackend;
     private createBackend;

package/dist/adapters.d.ts

@@ -1,6 +1,6 @@
 export { A as A2AAdapter, a as A2AAdapterOptions, K as A2AClientFactory, M as A2AClientLike, b as A2AGatewayAdapter, c as AnthropicAdapter, d as AnthropicAdapterOptions, N as AnthropicClientFactory, Q as AnthropicToolCallingModel, R as AnthropicToolCallingModelOptions, C as CODEX_REASONING_EFFORTS, e as CODEX_REASONING_SUMMARIES, f as CODEX_WEB_SEARCH_MODES, g as ClaudePermissionMode, h as ClaudeSDKAdapter, i as ClaudeSDKAdapterOptions, S as ClaudeSDKQuery, U as ClaudeSDKQueryParams, j as CodexAdapter, k as CodexAdapterConfig, W as CodexAppServerStdioClient, l as CodexApprovalPolicy, X as CodexClientLike, Y as CodexJsonRpcError, m as CodexReasoningEffort, n as CodexReasoningSummary, o as CodexSandboxMode, p as CodexWebSearchMode, Z as DynamicToolCallParams, _ as DynamicToolCallResponse, $ as DynamicToolSpec, G as GeminiAdapter, q as GeminiAdapterOptions, a0 as GeminiClientFactory, a1 as GeminiToolCallingModel, a2 as GeminiToolCallingModelOptions, r as GenericAdapter, s as GenericAdapterHandler, t as GoogleADKAdapter, u as GoogleADKAdapterOptions, a3 as HttpOpencodeClient, a4 as HttpOpencodeClientOptions, a5 as HttpStatusError, L as LangGraphAdapter, v as LangGraphAdapterOptions, w as LangGraphGraph, x as LettaAdapter, y as LettaAdapterOptions, a6 as LettaAgentCreateParams, a7 as LettaClientFactory, a8 as LettaClientLike, a9 as LettaHistoryConverter, aa as LettaMessage, ab as LettaMessageCreateParams, ac as LettaMessages, ad as LettaRequestOptions, ae as LettaResponse, af as LettaResponseMessage, O as OpenAIAdapter, z as OpenAIAdapterOptions, ag as OpenAIClientFactory, ah as OpenAIToolCallingModel, ai as OpenAIToolCallingModelOptions, B as OpencodeAdapter, D as OpencodeAdapterConfig, E as OpencodeApprovalMode, F as OpencodeApprovalReply, aj as OpencodeClientLike, H as OpencodeQuestionMode, P as ParlantAdapter, I as ParlantAdapterOptions, ak as ParlantClientFactory, al as ParlantClientLike, am as ToolCall, an as ToolCallingAdapter, ao as ToolCallingAdapterOptions, T as ToolCallingModel, ap as ToolCallingModelRequest, aq as ToolCallingResponse, ar as ToolResult, as as TurnStartParams, V as VercelAISDKAdapter, J as VercelAISDKAdapterOptions, at as VercelAISDKToolCallingModel, au as VercelAISDKToolCallingModelOptions, av as runSingleToolRound } from './ClaudeSDKAdapter-CXud2DBE.js';
 import * as _agentclientprotocol_sdk from '@agentclientprotocol/sdk';
-import { Client, ClientSideConnection, McpServer, ClientCapabilities, RequestPermissionRequest, SessionModeId, SessionMode, AgentSideConnection, SessionModeState, Agent, InitializeResponse, Implementation, Stream, InitializeRequest, LoadSessionRequest, LoadSessionResponse, ListSessionsRequest, ListSessionsResponse, ForkSessionRequest, ForkSessionResponse, ResumeSessionRequest, ResumeSessionResponse, SetSessionModeRequest, SetSessionModeResponse, SetSessionModelRequest, SetSessionModelResponse, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, AuthenticateRequest, AuthenticateResponse, PromptRequest, PromptResponse } from '@agentclientprotocol/sdk';
+import { Client, ClientSideConnection, McpServer, ClientCapabilities, RequestPermissionRequest, SessionMode, AgentSideConnection, SessionModeState, Agent, InitializeResponse, Implementation, Stream, InitializeRequest, LoadSessionRequest, LoadSessionResponse, ListSessionsRequest, ListSessionsResponse, ForkSessionRequest, ForkSessionResponse, ResumeSessionRequest, ResumeSessionResponse, SetSessionModeRequest, SetSessionModeResponse, SetSessionModelRequest, SetSessionModelResponse, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, AuthenticateRequest, AuthenticateResponse, PromptRequest, PromptResponse } from '@agentclientprotocol/sdk';
 import { A as ACPClientSessionState, a as ACPServerSessionState } from './acp-server-CiUqN3G3.js';
 export { G as GatewayHistoryConverter } from './acp-server-CiUqN3G3.js';
 import { S as SimpleAdapter } from './simpleAdapter--wznuoOw.js';
@@ -41,6 +41,12 @@ type ACPClientConnectionFactory = (client: Client, options: {
     env?: Record<string, string>;
 }) => Promise<ACPClientConnectionHandle>;
 
+interface ACPModeRequest {
+    roomId: string;
+    sessionId: string;
+    currentModeId: string;
+    modes: readonly SessionMode[];
+}
 interface ACPClientAdapterOptions {
     command: string | string[];
     cwd?: string;
@@ -54,7 +60,7 @@ interface ACPClientAdapterOptions {
     connectionFactory?: ACPClientConnectionFactory;
     resolvePermission?: (request: RequestPermissionRequest, signal: AbortSignal) => Promise<string | undefined>;
     permissionTimeoutMs?: number;
-    requestedPermissionMode?: SessionModeId;
+    resolveSessionMode?: (request: ACPModeRequest, signal: AbortSignal) => Promise<string | undefined>;
     logger?: Logger;
 }
 declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, AdapterToolsProtocol> {
@@ -74,8 +80,8 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private readonly bootstrappedSessions;
     private readonly pendingPermissions;
     private readonly resolvePermission?;
+    private readonly resolveSessionMode?;
     private readonly permissionTimeoutMs;
-    private readonly requestedPermissionMode?;
     private readonly logger;
     private backend;
     private backendPromise;
@@ -99,8 +105,9 @@ declare class ACPClientAdapter extends SimpleAdapter<ACPClientSessionState, Adap
     private ensureConnection;
     private spawnConnection;
     private getOrCreateSession;
+    private configureSessionMode;
+    private resolveSessionModeManually;
     private tryRestoreSession;
-    private applyRequestedPermissionMode;
     private buildSessionMcpServers;
     private getOrCreateBackend;
     private createBackend;

package/dist/adapters.js

@@ -387,8 +387,8 @@ var ACPClientAdapter = class extends SimpleAdapter {
   bootstrappedSessions = /* @__PURE__ */ new Set();
   pendingPermissions = /* @__PURE__ */ new Map();
   resolvePermission;
+  resolveSessionMode;
   permissionTimeoutMs;
-  requestedPermissionMode;
   logger;
   backend = null;
   backendPromise = null;
@@ -417,13 +417,10 @@ var ACPClientAdapter = class extends SimpleAdapter {
     this.clientCapabilities = options.clientCapabilities;
     this.connectionFactory = options.connectionFactory ?? createSubprocessConnection;
     this.resolvePermission = options.resolvePermission;
+    this.resolveSessionMode = options.resolveSessionMode;
     this.logger = options.logger ?? new NoopLogger();
     this.permissionTimeoutMs = options.permissionTimeoutMs ?? DEFAULT_PERMISSION_TIMEOUT_MS;
-    this.requestedPermissionMode = options.requestedPermissionMode;
-    if (this.requestedPermissionMode !== void 0 && this.requestedPermissionMode.length === 0) {
-      throw new ValidationError("requestedPermissionMode must be a non-empty mode id, got an empty string");
-    }
-    if (this.resolvePermission && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
+    if ((this.resolvePermission || this.resolveSessionMode) && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
       throw new ValidationError(`permissionTimeoutMs must be a positive finite number, got ${options.permissionTimeoutMs}`);
     }
   }
@@ -587,7 +584,7 @@ ${messageWithContext}`;
       if (restored.ok) {
         this.activeSessions.add(existingSessionId);
         this.bootstrappedSessions.add(existingSessionId);
-        await this.applyRequestedPermissionMode(connection, existingSessionId, restored.modes);
+        await this.configureSessionMode(roomId, existingSessionId, restored.modes, connection);
         return existingSessionId;
       }
     }
@@ -597,53 +594,93 @@ ${messageWithContext}`;
     });
     this.roomToSession.set(roomId, created.sessionId);
     this.activeSessions.add(created.sessionId);
-    await this.applyRequestedPermissionMode(connection, created.sessionId, created.modes);
+    await this.configureSessionMode(roomId, created.sessionId, created.modes, connection);
     return created.sessionId;
   }
-  async tryRestoreSession(connection, sessionId, mcpServers) {
-    const capabilities = this.connectionState?.agentCapabilities;
-    const params = { cwd: this.cwd, mcpServers, sessionId };
-    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
-    if (!restore) {
-      return { ok: false };
-    }
-    try {
-      const restored = await restore();
-      return { ok: true, modes: restored?.modes };
-    } catch {
-      return { ok: false };
-    }
-  }
   // Best-effort: never throws, so a mode switch going wrong can't take a
   // session establishment down with it.
-  async applyRequestedPermissionMode(connection, sessionId, modes) {
-    const requestedModeId = this.requestedPermissionMode;
-    if (!requestedModeId || !modes || modes.currentModeId === requestedModeId) {
+  async configureSessionMode(roomId, sessionId, modes, connection) {
+    if (!this.resolveSessionMode || !modes) {
       return;
     }
     const availableModes = Array.isArray(modes.availableModes) ? modes.availableModes : [];
-    if (!availableModes.some((mode) => mode?.id === requestedModeId)) {
-      this.safeWarn("requested permission mode is not advertised by this session", {
+    if (availableModes.length === 0) {
+      return;
+    }
+    const selectedModeId = await this.resolveSessionModeManually(
+      (signal) => this.resolveSessionMode({
+        roomId,
         sessionId,
-        requestedModeId,
+        currentModeId: modes.currentModeId,
+        modes: availableModes
+      }, signal),
+      connection.signal
+    );
+    if (!selectedModeId || selectedModeId === modes.currentModeId) {
+      return;
+    }
+    if (!availableModes.some((mode) => mode?.id === selectedModeId)) {
+      this.safeWarn("resolveSessionMode selected a mode id this session does not advertise", {
+        sessionId,
+        selectedModeId,
         availableModeIds: availableModes.map((mode) => mode?.id)
       });
       return;
     }
     try {
       await withTimeout(
-        connection.setSessionMode({ sessionId, modeId: requestedModeId }),
+        connection.setSessionMode({ sessionId, modeId: selectedModeId }),
         SET_SESSION_MODE_TIMEOUT_MS,
         `setSessionMode did not respond within ${SET_SESSION_MODE_TIMEOUT_MS}ms`
       );
     } catch (error) {
-      this.safeWarn("failed to switch session into the requested permission mode", {
+      this.safeWarn("failed to switch session into the selected mode", {
         sessionId,
-        requestedModeId,
+        selectedModeId,
         error: String(error)
       });
     }
   }
+  async resolveSessionModeManually(resolver, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener("abort", abort, { once: true });
+    let timer;
+    try {
+      const cancelled = new Promise((resolve) => {
+        controller.signal.addEventListener("abort", () => resolve(void 0), { once: true });
+      });
+      const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), this.permissionTimeoutMs);
+      });
+      return await Promise.race([
+        Promise.resolve().then(() => resolver(controller.signal)).catch((error) => {
+          this.safeWarn("resolveSessionMode threw; preserving the harness default", { error: String(error) });
+          return void 0;
+        }),
+        timeout,
+        cancelled
+      ]);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+  async tryRestoreSession(connection, sessionId, mcpServers) {
+    const capabilities = this.connectionState?.agentCapabilities;
+    const params = { cwd: this.cwd, mcpServers, sessionId };
+    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
+    if (!restore) {
+      return { ok: false };
+    }
+    try {
+      const restored = await restore();
+      return { ok: true, modes: restored?.modes };
+    } catch {
+      return { ok: false };
+    }
+  }
   async buildSessionMcpServers() {
     const mcpServers = [...this.mcpServers];
     if (!this.enableMcpTools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Band TypeScript SDK core runtime",
   "license": "MIT",
   "repository": {