sandbox-agent 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NewSessionRequest, SessionConfigOption, SessionModeState, AnyMessage, AcpEnvelopeDirection, NewSessionResponse, PromptRequest, PromptResponse, SetSessionModeResponse, SetSessionConfigOptionResponse } from 'acp-http-client';
+import { NewSessionRequest, SessionConfigOption, SessionModeState, AnyMessage, AcpEnvelopeDirection, RequestPermissionRequest, RequestPermissionResponse, NewSessionResponse, PermissionOptionKind, PromptRequest, PromptResponse, SetSessionModeResponse, SetSessionConfigOptionResponse } from 'acp-http-client';
 export { AcpRpcError } from 'acp-http-client';
 
 type SandboxAgentSpawnLogMode = "inherit" | "pipe" | "silent";
@@ -1488,8 +1488,25 @@ interface SessionSendOptions {
     notification?: boolean;
 }
 type SessionEventListener = (event: SessionEvent) => void;
+type PermissionReply = "once" | "always" | "reject";
+type PermissionRequestListener = (request: SessionPermissionRequest) => void;
 type ProcessLogListener = (entry: ProcessLogEntry) => void;
 type ProcessLogFollowQuery = Omit<ProcessLogsQuery, "follow">;
+interface SessionPermissionRequestOption {
+    optionId: string;
+    name: string;
+    kind: PermissionOptionKind;
+}
+interface SessionPermissionRequest {
+    id: string;
+    createdAt: number;
+    sessionId: string;
+    agentSessionId: string;
+    availableReplies: PermissionReply[];
+    options: SessionPermissionRequestOption[];
+    toolCall: RequestPermissionRequest["toolCall"];
+    rawRequest: RequestPermissionRequest;
+}
 interface AgentQueryOptions {
     config?: boolean;
     noCache?: boolean;
@@ -1532,6 +1549,12 @@ declare class UnsupportedSessionConfigOptionError extends Error {
     readonly availableConfigIds: string[];
     constructor(sessionId: string, configId: string, availableConfigIds: string[]);
 }
+declare class UnsupportedPermissionReplyError extends Error {
+    readonly permissionId: string;
+    readonly requestedReply: PermissionReply;
+    readonly availableReplies: PermissionReply[];
+    constructor(permissionId: string, requestedReply: PermissionReply, availableReplies: PermissionReply[]);
+}
 declare class Session {
     private record;
     private readonly sandbox;
@@ -1543,7 +1566,7 @@ declare class Session {
     get createdAt(): number;
     get destroyedAt(): number | undefined;
     refresh(): Promise<Session>;
-    send(method: string, params?: Record<string, unknown>, options?: SessionSendOptions): Promise<unknown>;
+    rawSend(method: string, params?: Record<string, unknown>, options?: SessionSendOptions): Promise<unknown>;
     prompt(prompt: PromptRequest["prompt"]): Promise<PromptResponse>;
     setMode(modeId: string): Promise<SetSessionModeResponse | void>;
     setConfigOption(configId: string, value: string): Promise<SetSessionConfigOptionResponse>;
@@ -1552,6 +1575,9 @@ declare class Session {
     getConfigOptions(): Promise<SessionConfigOption[]>;
     getModes(): Promise<SessionModeState | null>;
     onEvent(listener: SessionEventListener): () => void;
+    onPermissionRequest(listener: PermissionRequestListener): () => void;
+    respondPermission(permissionId: string, reply: PermissionReply): Promise<void>;
+    rawRespondPermission(permissionId: string, response: RequestPermissionResponse): Promise<void>;
     toRecord(): SessionRecord;
     apply(record: SessionRecord): void;
 }
@@ -1567,6 +1593,7 @@ declare class LiveAcpConnection {
     private lastAdapterExit;
     private lastAdapterExitAt;
     private readonly onObservedEnvelope;
+    private readonly onPermissionRequest;
     private constructor();
     static create(options: {
         baseUrl: string;
@@ -1576,6 +1603,7 @@ declare class LiveAcpConnection {
         agent: string;
         serverId: string;
         onObservedEnvelope: (connection: LiveAcpConnection, envelope: AnyMessage, direction: AcpEnvelopeDirection, localSessionId: string | null) => void;
+        onPermissionRequest: (connection: LiveAcpConnection, localSessionId: string, agentSessionId: string, request: RequestPermissionRequest) => Promise<RequestPermissionResponse>;
     }): Promise<LiveAcpConnection>;
     close(): Promise<void>;
     hasBoundSession(localSessionId: string, agentSessionId?: string): boolean;
@@ -1585,6 +1613,7 @@ declare class LiveAcpConnection {
     sendSessionMethod(localSessionId: string, method: string, params: Record<string, unknown>, options: SessionSendOptions): Promise<unknown>;
     private handleEnvelope;
     private handleAdapterNotification;
+    private handlePermissionRequest;
     private resolveSessionId;
     private localFromEnvelopeParams;
 }
@@ -1629,6 +1658,8 @@ declare class SandboxAgent {
     private readonly pendingLiveConnections;
     private readonly sessionHandles;
     private readonly eventListeners;
+    private readonly permissionListeners;
+    private readonly pendingPermissionRequests;
     private readonly nextSessionEventIndexBySession;
     private readonly seedSessionEventIndexBySession;
     constructor(options: SandboxAgentConnectOptions);
@@ -1662,13 +1693,16 @@ declare class SandboxAgent {
     getSessionModes(sessionId: string): Promise<SessionModeState | null>;
     private setSessionCategoryValue;
     private hydrateSessionConfigOptions;
-    sendSessionMethod(sessionId: string, method: string, params: Record<string, unknown>, options?: SessionSendOptions): Promise<{
+    rawSendSessionMethod(sessionId: string, method: string, params: Record<string, unknown>, options?: SessionSendOptions): Promise<{
         session: Session;
         response: unknown;
     }>;
     private sendSessionMethodInternal;
     private persistSessionStateFromMethod;
     onSessionEvent(sessionId: string, listener: SessionEventListener): () => void;
+    onPermissionRequest(sessionId: string, listener: PermissionRequestListener): () => void;
+    respondPermission(permissionId: string, reply: PermissionReply): Promise<void>;
+    rawRespondPermission(permissionId: string, response: RequestPermissionResponse): Promise<void>;
     getHealth(): Promise<HealthResponse>;
     listAgents(options?: AgentQueryOptions): Promise<AgentListResponse>;
     getAgent(agent: string, options?: AgentQueryOptions): Promise<AgentInfo>;
@@ -1713,6 +1747,9 @@ declare class SandboxAgent {
     private collectReplayEvents;
     private upsertSessionHandle;
     private requireSessionRecord;
+    private enqueuePermissionRequest;
+    private resolvePendingPermission;
+    private cancelPendingPermissionsForSession;
     private requestJson;
     private requestRaw;
     private startHealthWait;
@@ -1744,4 +1781,4 @@ interface InspectorUrlOptions {
  */
 declare function buildInspectorUrl(options: InspectorUrlOptions): string;
 
-export { type AcpEnvelope, type AcpServerInfo, type AcpServerListResponse, type AgentInfo, type AgentInstallRequest, type AgentInstallResponse, type AgentListResponse, type AgentQuery, type AgentQueryOptions, type FsActionResponse, type FsDeleteQuery, type FsEntriesQuery, type FsEntry, type FsMoveRequest, type FsMoveResponse, type FsPathQuery, type FsStat, type FsUploadBatchQuery, type FsUploadBatchResponse, type FsWriteResponse, type HealthResponse, InMemorySessionPersistDriver, type InMemorySessionPersistDriverOptions, type InspectorUrlOptions, type ListEventsRequest, type ListPage, type ListPageRequest, LiveAcpConnection, type McpConfigQuery, type McpServerConfig, type ProblemDetails, type ProcessConfig, type ProcessCreateRequest, type ProcessInfo, type ProcessInputRequest, type ProcessInputResponse, type ProcessListResponse, type ProcessLogEntry, type ProcessLogFollowQuery, type ProcessLogListener, type ProcessLogSubscription, type ProcessLogsQuery, type ProcessLogsResponse, type ProcessLogsStream, type ProcessRunRequest, type ProcessRunResponse, type ProcessSignalQuery, type ProcessState, type ProcessTerminalClientFrame, type ProcessTerminalConnectOptions, type ProcessTerminalErrorFrame, type ProcessTerminalExitFrame, type ProcessTerminalReadyFrame, type ProcessTerminalResizeRequest, type ProcessTerminalResizeResponse, type ProcessTerminalServerFrame, ProcessTerminalSession, type ProcessTerminalSessionOptions, type ProcessTerminalWebSocketUrlOptions, SandboxAgent, type SandboxAgentConnectOptions, SandboxAgentError, type SandboxAgentHealthWaitOptions, type SandboxAgentSpawnLogMode, type SandboxAgentSpawnOptions, type SandboxAgentStartOptions, Session, type SessionCreateRequest, type SessionEvent, type SessionEventListener, type SessionPersistDriver, type SessionRecord, type SessionResumeOrCreateRequest, type SessionSendOptions, type SkillsConfig, type SkillsConfigQuery, type TerminalErrorStatus, type TerminalExitStatus, type TerminalReadyStatus, type TerminalResizePayload, type TerminalStatusMessage, UnsupportedSessionCategoryError, UnsupportedSessionConfigOptionError, UnsupportedSessionValueError, buildInspectorUrl };
+export { type AcpEnvelope, type AcpServerInfo, type AcpServerListResponse, type AgentInfo, type AgentInstallRequest, type AgentInstallResponse, type AgentListResponse, type AgentQuery, type AgentQueryOptions, type FsActionResponse, type FsDeleteQuery, type FsEntriesQuery, type FsEntry, type FsMoveRequest, type FsMoveResponse, type FsPathQuery, type FsStat, type FsUploadBatchQuery, type FsUploadBatchResponse, type FsWriteResponse, type HealthResponse, InMemorySessionPersistDriver, type InMemorySessionPersistDriverOptions, type InspectorUrlOptions, type ListEventsRequest, type ListPage, type ListPageRequest, LiveAcpConnection, type McpConfigQuery, type McpServerConfig, type PermissionReply, type PermissionRequestListener, type ProblemDetails, type ProcessConfig, type ProcessCreateRequest, type ProcessInfo, type ProcessInputRequest, type ProcessInputResponse, type ProcessListResponse, type ProcessLogEntry, type ProcessLogFollowQuery, type ProcessLogListener, type ProcessLogSubscription, type ProcessLogsQuery, type ProcessLogsResponse, type ProcessLogsStream, type ProcessRunRequest, type ProcessRunResponse, type ProcessSignalQuery, type ProcessState, type ProcessTerminalClientFrame, type ProcessTerminalConnectOptions, type ProcessTerminalErrorFrame, type ProcessTerminalExitFrame, type ProcessTerminalReadyFrame, type ProcessTerminalResizeRequest, type ProcessTerminalResizeResponse, type ProcessTerminalServerFrame, ProcessTerminalSession, type ProcessTerminalSessionOptions, type ProcessTerminalWebSocketUrlOptions, SandboxAgent, type SandboxAgentConnectOptions, SandboxAgentError, type SandboxAgentHealthWaitOptions, type SandboxAgentSpawnLogMode, type SandboxAgentSpawnOptions, type SandboxAgentStartOptions, Session, type SessionCreateRequest, type SessionEvent, type SessionEventListener, type SessionPermissionRequest, type SessionPermissionRequestOption, type SessionPersistDriver, type SessionRecord, type SessionResumeOrCreateRequest, type SessionSendOptions, type SkillsConfig, type SkillsConfigQuery, type TerminalErrorStatus, type TerminalExitStatus, type TerminalReadyStatus, type TerminalResizePayload, type TerminalStatusMessage, UnsupportedPermissionReplyError, UnsupportedSessionCategoryError, UnsupportedSessionConfigOptionError, UnsupportedSessionValueError, buildInspectorUrl };

package/dist/index.js

@@ -192,6 +192,20 @@ var UnsupportedSessionConfigOptionError = class extends Error {
     this.availableConfigIds = availableConfigIds;
   }
 };
+var UnsupportedPermissionReplyError = class extends Error {
+  permissionId;
+  requestedReply;
+  availableReplies;
+  constructor(permissionId, requestedReply, availableReplies) {
+    super(
+      `Permission '${permissionId}' does not support reply '${requestedReply}'. Available replies: ${availableReplies.join(", ") || "(none)"}`
+    );
+    this.name = "UnsupportedPermissionReplyError";
+    this.permissionId = permissionId;
+    this.requestedReply = requestedReply;
+    this.availableReplies = availableReplies;
+  }
+};
 var Session = class {
   record;
   sandbox;
@@ -225,13 +239,13 @@ var Session = class {
     this.apply(latest.toRecord());
     return this;
   }
-  async send(method, params = {}, options = {}) {
-    const updated = await this.sandbox.sendSessionMethod(this.id, method, params, options);
+  async rawSend(method, params = {}, options = {}) {
+    const updated = await this.sandbox.rawSendSessionMethod(this.id, method, params, options);
     this.apply(updated.session.toRecord());
     return updated.response;
   }
   async prompt(prompt) {
-    const response = await this.send("session/prompt", { prompt });
+    const response = await this.rawSend("session/prompt", { prompt });
     return response;
   }
   async setMode(modeId) {
@@ -263,6 +277,15 @@ var Session = class {
   onEvent(listener) {
     return this.sandbox.onSessionEvent(this.id, listener);
   }
+  onPermissionRequest(listener) {
+    return this.sandbox.onPermissionRequest(this.id, listener);
+  }
+  async respondPermission(permissionId, reply) {
+    await this.sandbox.respondPermission(permissionId, reply);
+  }
+  async rawRespondPermission(permissionId, response) {
+    await this.sandbox.rawRespondPermission(permissionId, response);
+  }
   toRecord() {
     return { ...this.record };
   }
@@ -282,11 +305,13 @@ var LiveAcpConnection = class _LiveAcpConnection {
   lastAdapterExit = null;
   lastAdapterExitAt = 0;
   onObservedEnvelope;
-  constructor(agent, connectionId, acp, onObservedEnvelope) {
+  onPermissionRequest;
+  constructor(agent, connectionId, acp, onObservedEnvelope, onPermissionRequest) {
     this.agent = agent;
     this.connectionId = connectionId;
     this.acp = acp;
     this.onObservedEnvelope = onObservedEnvelope;
+    this.onPermissionRequest = onPermissionRequest;
   }
   static async create(options) {
     const connectionId = randomId();
@@ -301,6 +326,12 @@ var LiveAcpConnection = class _LiveAcpConnection {
         bootstrapQuery: { agent: options.agent }
       },
       client: {
+        requestPermission: async (request) => {
+          if (!live) {
+            return cancelledPermissionResponse();
+          }
+          return live.handlePermissionRequest(request);
+        },
         sessionUpdate: async (_notification) => {
         },
         extNotification: async (method, params) => {
@@ -315,7 +346,13 @@ var LiveAcpConnection = class _LiveAcpConnection {
         live.handleEnvelope(envelope, direction);
       }
     });
-    live = new _LiveAcpConnection(options.agent, connectionId, acp, options.onObservedEnvelope);
+    live = new _LiveAcpConnection(
+      options.agent,
+      connectionId,
+      acp,
+      options.onObservedEnvelope,
+      options.onPermissionRequest
+    );
     const initResult = await acp.initialize({
       protocolVersion: PROTOCOL_VERSION,
       clientInfo: {
@@ -420,6 +457,19 @@ var LiveAcpConnection = class _LiveAcpConnection {
     };
     this.lastAdapterExitAt = Date.now();
   }
+  async handlePermissionRequest(request) {
+    const agentSessionId = request.sessionId;
+    const localSessionId = this.localByAgentSessionId.get(agentSessionId);
+    if (!localSessionId) {
+      return cancelledPermissionResponse();
+    }
+    return this.onPermissionRequest(
+      this,
+      localSessionId,
+      agentSessionId,
+      clonePermissionRequest(request)
+    );
+  }
   resolveSessionId(envelope, direction) {
     const id = envelopeId(envelope);
     const method = envelopeMethod(envelope);
@@ -619,6 +669,8 @@ var SandboxAgent = class _SandboxAgent {
   pendingLiveConnections = /* @__PURE__ */ new Map();
   sessionHandles = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
+  permissionListeners = /* @__PURE__ */ new Map();
+  pendingPermissionRequests = /* @__PURE__ */ new Map();
   nextSessionEventIndexBySession = /* @__PURE__ */ new Map();
   seedSessionEventIndexBySession = /* @__PURE__ */ new Map();
   constructor(options) {
@@ -667,6 +719,10 @@ var SandboxAgent = class _SandboxAgent {
   async dispose() {
     this.disposed = true;
     this.healthWaitAbortController.abort(createAbortError("SandboxAgent was disposed."));
+    for (const [permissionId, pending2] of this.pendingPermissionRequests) {
+      this.pendingPermissionRequests.delete(permissionId);
+      pending2.resolve(cancelledPermissionResponse());
+    }
     const connections = [...this.liveConnections.values()];
     this.liveConnections.clear();
     const pending = [...this.pendingLiveConnections.values()];
@@ -788,6 +844,7 @@ var SandboxAgent = class _SandboxAgent {
     return this.createSession(request);
   }
   async destroySession(id) {
+    this.cancelPendingPermissionsForSession(id);
     try {
       await this.sendSessionMethodInternal(id, SESSION_CANCEL_METHOD, {}, {}, true);
     } catch {
@@ -877,7 +934,23 @@ var SandboxAgent = class _SandboxAgent {
   }
   async getSessionModes(sessionId) {
     const record = await this.requireSessionRecord(sessionId);
-    return cloneModes(record.modes);
+    if (record.modes && record.modes.availableModes.length > 0) {
+      return cloneModes(record.modes);
+    }
+    const hydrated = await this.hydrateSessionConfigOptions(record.id, record);
+    if (hydrated.modes && hydrated.modes.availableModes.length > 0) {
+      return cloneModes(hydrated.modes);
+    }
+    const derived = deriveModesFromConfigOptions(hydrated.configOptions);
+    if (!derived) {
+      return cloneModes(hydrated.modes);
+    }
+    const updated = {
+      ...hydrated,
+      modes: derived
+    };
+    await this.persist.updateSession(updated);
+    return cloneModes(derived);
   }
   async setSessionCategoryValue(sessionId, category, value) {
     const resolvedValue = value.trim();
@@ -919,7 +992,7 @@ var SandboxAgent = class _SandboxAgent {
     await this.persist.updateSession(updated);
     return updated;
   }
-  async sendSessionMethod(sessionId, method, params, options = {}) {
+  async rawSendSessionMethod(sessionId, method, params, options = {}) {
     return this.sendSessionMethodInternal(sessionId, method, params, options, false);
   }
   async sendSessionMethodInternal(sessionId, method, params, options, allowManagedCancel) {
@@ -1015,6 +1088,42 @@ var SandboxAgent = class _SandboxAgent {
       }
     };
   }
+  onPermissionRequest(sessionId, listener) {
+    const listeners = this.permissionListeners.get(sessionId) ?? /* @__PURE__ */ new Set();
+    listeners.add(listener);
+    this.permissionListeners.set(sessionId, listeners);
+    return () => {
+      const set = this.permissionListeners.get(sessionId);
+      if (!set) {
+        return;
+      }
+      set.delete(listener);
+      if (set.size === 0) {
+        this.permissionListeners.delete(sessionId);
+      }
+    };
+  }
+  async respondPermission(permissionId, reply) {
+    const pending = this.pendingPermissionRequests.get(permissionId);
+    if (!pending) {
+      throw new Error(`permission '${permissionId}' not found`);
+    }
+    let response;
+    try {
+      response = permissionReplyToResponse(permissionId, pending.request, reply);
+    } catch (error) {
+      pending.reject(error instanceof Error ? error : new Error(String(error)));
+      this.pendingPermissionRequests.delete(permissionId);
+      throw error;
+    }
+    this.resolvePendingPermission(permissionId, response);
+  }
+  async rawRespondPermission(permissionId, response) {
+    if (!this.pendingPermissionRequests.has(permissionId)) {
+      throw new Error(`permission '${permissionId}' not found`);
+    }
+    this.resolvePendingPermission(permissionId, clonePermissionResponse(response));
+  }
   async getHealth() {
     return this.requestHealth();
   }
@@ -1024,9 +1133,21 @@ var SandboxAgent = class _SandboxAgent {
     });
   }
   async getAgent(agent, options) {
-    return this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}`, {
-      query: toAgentQuery(options)
-    });
+    try {
+      return await this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}`, {
+        query: toAgentQuery(options)
+      });
+    } catch (error) {
+      if (!(error instanceof SandboxAgentError) || error.status !== 404) {
+        throw error;
+      }
+      const listed = await this.listAgents(options);
+      const match = listed.agents.find((entry) => entry.id === agent);
+      if (match) {
+        return match;
+      }
+      throw error;
+    }
   }
   async installAgent(agent, request = {}) {
     return this.requestJson("POST", `${API_PREFIX}/agents/${encodeURIComponent(agent)}/install`, {
@@ -1217,7 +1338,8 @@ var SandboxAgent = class _SandboxAgent {
         serverId,
         onObservedEnvelope: (connection, envelope, direction, localSessionId) => {
           void this.persistObservedEnvelope(connection, envelope, direction, localSessionId);
-        }
+        },
+        onPermissionRequest: async (connection, localSessionId, agentSessionId, request) => this.enqueuePermissionRequest(connection, localSessionId, agentSessionId, request)
       });
       const raced = this.liveConnections.get(agent);
       if (raced) {
@@ -1378,6 +1500,57 @@ var SandboxAgent = class _SandboxAgent {
     }
     return record;
   }
+  async enqueuePermissionRequest(_connection, localSessionId, agentSessionId, request) {
+    const listeners = this.permissionListeners.get(localSessionId);
+    if (!listeners || listeners.size === 0) {
+      return cancelledPermissionResponse();
+    }
+    const pendingId = randomId();
+    const permissionRequest = {
+      id: pendingId,
+      createdAt: nowMs(),
+      sessionId: localSessionId,
+      agentSessionId,
+      availableReplies: availablePermissionReplies(request.options),
+      options: request.options.map(clonePermissionOption),
+      toolCall: clonePermissionToolCall(request.toolCall),
+      rawRequest: clonePermissionRequest(request)
+    };
+    return await new Promise((resolve, reject) => {
+      this.pendingPermissionRequests.set(pendingId, {
+        id: pendingId,
+        sessionId: localSessionId,
+        request: clonePermissionRequest(request),
+        resolve,
+        reject
+      });
+      try {
+        for (const listener of listeners) {
+          listener(permissionRequest);
+        }
+      } catch (error) {
+        this.pendingPermissionRequests.delete(pendingId);
+        reject(error);
+      }
+    });
+  }
+  resolvePendingPermission(permissionId, response) {
+    const pending = this.pendingPermissionRequests.get(permissionId);
+    if (!pending) {
+      throw new Error(`permission '${permissionId}' not found`);
+    }
+    this.pendingPermissionRequests.delete(permissionId);
+    pending.resolve(response);
+  }
+  cancelPendingPermissionsForSession(sessionId) {
+    for (const [permissionId, pending] of this.pendingPermissionRequests) {
+      if (pending.sessionId !== sessionId) {
+        continue;
+      }
+      this.pendingPermissionRequests.delete(permissionId);
+      pending.resolve(cancelledPermissionResponse());
+    }
+  }
   async requestJson(method, path, options = {}) {
     const response = await this.requestRaw(method, path, {
       query: options.query,
@@ -1679,6 +1852,22 @@ function envelopeSessionIdFromResult(message) {
 function cloneEnvelope(envelope) {
   return JSON.parse(JSON.stringify(envelope));
 }
+function clonePermissionRequest(request) {
+  return JSON.parse(JSON.stringify(request));
+}
+function clonePermissionResponse(response) {
+  return JSON.parse(JSON.stringify(response));
+}
+function clonePermissionOption(option) {
+  return {
+    optionId: option.optionId,
+    name: option.name,
+    kind: option.kind
+  };
+}
+function clonePermissionToolCall(toolCall) {
+  return JSON.parse(JSON.stringify(toolCall));
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1788,6 +1977,24 @@ function extractKnownModeIds(modes) {
   }
   return modes.availableModes.map((mode) => typeof mode.id === "string" ? mode.id : null).filter((value) => !!value);
 }
+function deriveModesFromConfigOptions(configOptions) {
+  if (!configOptions || configOptions.length === 0) {
+    return null;
+  }
+  const modeOption = findConfigOptionByCategory(configOptions, "mode");
+  if (!modeOption || !Array.isArray(modeOption.options)) {
+    return null;
+  }
+  const availableModes = modeOption.options.flatMap((entry) => flattenConfigOptions(entry)).map((entry) => ({
+    id: entry.value,
+    name: entry.name,
+    description: entry.description ?? null
+  }));
+  return {
+    currentModeId: typeof modeOption.currentValue === "string" && modeOption.currentValue.length > 0 ? modeOption.currentValue : availableModes[0]?.id ?? "",
+    availableModes
+  };
+}
 function applyCurrentMode(modes, currentModeId) {
   if (modes && Array.isArray(modes.availableModes)) {
     return {
@@ -1809,6 +2016,24 @@ function applyConfigOptionValue(configOptions, configId, value) {
   updated[idx] = { ...updated[idx], currentValue: value };
   return updated;
 }
+function flattenConfigOptions(entry) {
+  if (!isRecord(entry)) {
+    return [];
+  }
+  if (typeof entry.value === "string" && typeof entry.name === "string") {
+    return [
+      {
+        value: entry.value,
+        name: entry.name,
+        description: typeof entry.description === "string" ? entry.description : void 0
+      }
+    ];
+  }
+  if (!Array.isArray(entry.options)) {
+    return [];
+  }
+  return entry.options.flatMap((nested) => flattenConfigOptions(nested));
+}
 function envelopeSessionUpdate(message) {
   if (!isRecord(message) || !("params" in message) || !isRecord(message.params)) {
     return null;
@@ -1830,6 +2055,43 @@ function cloneModes(value) {
   }
   return JSON.parse(JSON.stringify(value));
 }
+function availablePermissionReplies(options) {
+  const replies = /* @__PURE__ */ new Set();
+  for (const option of options) {
+    if (option.kind === "allow_once") {
+      replies.add("once");
+    } else if (option.kind === "allow_always") {
+      replies.add("always");
+    } else if (option.kind === "reject_once" || option.kind === "reject_always") {
+      replies.add("reject");
+    }
+  }
+  return [...replies];
+}
+function permissionReplyToResponse(permissionId, request, reply) {
+  const preferredKinds = reply === "once" ? ["allow_once"] : reply === "always" ? ["allow_always", "allow_once"] : ["reject_once", "reject_always"];
+  const selected = preferredKinds.map((kind) => request.options.find((option) => option.kind === kind)).find((option) => Boolean(option));
+  if (!selected) {
+    throw new UnsupportedPermissionReplyError(
+      permissionId,
+      reply,
+      availablePermissionReplies(request.options)
+    );
+  }
+  return {
+    outcome: {
+      outcome: "selected",
+      optionId: selected.optionId
+    }
+  };
+}
+function cancelledPermissionResponse() {
+  return {
+    outcome: {
+      outcome: "cancelled"
+    }
+  };
+}
 function isSessionConfigOption(value) {
   return isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && typeof value.type === "string";
 }
@@ -2038,6 +2300,7 @@ export {
   SandboxAgent,
   SandboxAgentError,
   Session,
+  UnsupportedPermissionReplyError,
   UnsupportedSessionCategoryError,
   UnsupportedSessionConfigOptionError,
   UnsupportedSessionValueError,