sandbox-agent 0.3.2 → 0.4.0-rc.2

package/dist/chunk-LSO36KRX.js

@@ -0,0 +1,15 @@
+// src/providers/shared.ts
+var DEFAULT_SANDBOX_AGENT_IMAGE = "rivetdev/sandbox-agent:0.4.0-rc.2-full";
+var SANDBOX_AGENT_INSTALL_SCRIPT = "https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh";
+var DEFAULT_AGENTS = ["claude", "codex"];
+function buildServerStartCommand(port) {
+  return `nohup sandbox-agent server --no-token --host 0.0.0.0 --port ${port} >/tmp/sandbox-agent.log 2>&1 &`;
+}
+
+export {
+  DEFAULT_SANDBOX_AGENT_IMAGE,
+  SANDBOX_AGENT_INSTALL_SCRIPT,
+  DEFAULT_AGENTS,
+  buildServerStartCommand
+};
+//# sourceMappingURL=chunk-LSO36KRX.js.map

package/dist/chunk-LSO36KRX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/shared.ts"],"sourcesContent":["export const DEFAULT_SANDBOX_AGENT_IMAGE = \"rivetdev/sandbox-agent:0.4.0-rc.2-full\";\nexport const SANDBOX_AGENT_INSTALL_SCRIPT = \"https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh\";\nexport const DEFAULT_AGENTS = [\"claude\", \"codex\"] as const;\n\nexport function buildServerStartCommand(port: number): string {\n  return `nohup sandbox-agent server --no-token --host 0.0.0.0 --port ${port} >/tmp/sandbox-agent.log 2>&1 &`;\n}\n"],"mappings":";AAAO,IAAM,8BAA8B;AACpC,IAAM,+BAA+B;AACrC,IAAM,iBAAiB,CAAC,UAAU,OAAO;AAEzC,SAAS,wBAAwB,MAAsB;AAC5D,SAAO,+DAA+D,IAAI;AAC5E;","names":[]}

package/dist/index.d.ts

@@ -1,17 +1,7 @@
 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";
-type SandboxAgentSpawnOptions = {
-    enabled?: boolean;
-    host?: string;
-    port?: number;
-    token?: string;
-    binaryPath?: string;
-    timeoutMs?: number;
-    log?: SandboxAgentSpawnLogMode;
-    env?: Record<string, string>;
-};
+import { S as SandboxProvider } from './types-DLlJOfyX.js';
+export { S as SandboxAgentSpawnLogMode, a as SandboxAgentSpawnOptions } from './spawn-76JDF5d3.js';
 
 interface components {
     schemas: {
@@ -1368,6 +1358,7 @@ interface SessionRecord {
     lastConnectionId: string;
     createdAt: number;
     destroyedAt?: number;
+    sandboxId?: string;
     sessionInit?: Omit<NewSessionRequest, "_meta">;
     configOptions?: SessionConfigOption[];
     modes?: SessionModeState | null;
@@ -1394,11 +1385,11 @@ interface ListEventsRequest extends ListPageRequest {
     sessionId: string;
 }
 interface SessionPersistDriver {
-    getSession(id: string): Promise<SessionRecord | null>;
+    getSession(id: string): Promise<SessionRecord | undefined>;
     listSessions(request?: ListPageRequest): Promise<ListPage<SessionRecord>>;
     updateSession(session: SessionRecord): Promise<void>;
     listEvents(request: ListEventsRequest): Promise<ListPage<SessionEvent>>;
-    insertEvent(event: SessionEvent): Promise<void>;
+    insertEvent(sessionId: string, event: SessionEvent): Promise<void>;
 }
 interface InMemorySessionPersistDriverOptions {
     maxSessions?: number;
@@ -1410,11 +1401,11 @@ declare class InMemorySessionPersistDriver implements SessionPersistDriver {
     private readonly sessions;
     private readonly eventsBySession;
     constructor(options?: InMemorySessionPersistDriverOptions);
-    getSession(id: string): Promise<SessionRecord | null>;
+    getSession(id: string): Promise<SessionRecord | undefined>;
     listSessions(request?: ListPageRequest): Promise<ListPage<SessionRecord>>;
     updateSession(session: SessionRecord): Promise<void>;
     listEvents(request: ListEventsRequest): Promise<ListPage<SessionEvent>>;
-    insertEvent(event: SessionEvent): Promise<void>;
+    insertEvent(sessionId: string, event: SessionEvent): Promise<void>;
 }
 type ResponsesOf<T> = T extends {
     responses: infer R;
@@ -1451,6 +1442,8 @@ interface SandboxAgentConnectCommonOptions {
     replayMaxChars?: number;
     signal?: AbortSignal;
     token?: string;
+    skipHealthCheck?: boolean;
+    /** @deprecated Use skipHealthCheck instead. */
     waitForHealth?: boolean | SandboxAgentHealthWaitOptions;
 }
 type SandboxAgentConnectOptions = (SandboxAgentConnectCommonOptions & {
@@ -1461,16 +1454,23 @@ type SandboxAgentConnectOptions = (SandboxAgentConnectCommonOptions & {
     baseUrl?: string;
 });
 interface SandboxAgentStartOptions {
+    sandbox: SandboxProvider;
+    sandboxId?: string;
+    skipHealthCheck?: boolean;
     fetch?: typeof fetch;
     headers?: HeadersInit;
     persist?: SessionPersistDriver;
     replayMaxEvents?: number;
     replayMaxChars?: number;
-    spawn?: SandboxAgentSpawnOptions | boolean;
+    signal?: AbortSignal;
+    token?: string;
 }
 interface SessionCreateRequest {
     id?: string;
     agent: string;
+    /** Shorthand for `sessionInit.cwd`. Ignored when `sessionInit` is provided. */
+    cwd?: string;
+    /** Full session init. When omitted, built from `cwd` (or default) with empty `mcpServers`. */
     sessionInit?: Omit<NewSessionRequest, "_meta">;
     model?: string;
     mode?: string;
@@ -1479,6 +1479,9 @@ interface SessionCreateRequest {
 interface SessionResumeOrCreateRequest {
     id: string;
     agent: string;
+    /** Shorthand for `sessionInit.cwd`. Ignored when `sessionInit` is provided. */
+    cwd?: string;
+    /** Full session init. When omitted, built from `cwd` (or default) with empty `mcpServers`. */
     sessionInit?: Omit<NewSessionRequest, "_meta">;
     model?: string;
     mode?: string;
@@ -1647,10 +1650,12 @@ declare class SandboxAgent {
     private readonly defaultHeaders?;
     private readonly healthWait;
     private readonly healthWaitAbortController;
+    private sandboxProvider?;
+    private sandboxProviderId?;
+    private sandboxProviderRawId?;
     private readonly persist;
     private readonly replayMaxEvents;
     private readonly replayMaxChars;
-    private spawnHandle?;
     private healthPromise?;
     private healthError?;
     private disposed;
@@ -1662,10 +1667,15 @@ declare class SandboxAgent {
     private readonly pendingPermissionRequests;
     private readonly nextSessionEventIndexBySession;
     private readonly seedSessionEventIndexBySession;
+    private readonly pendingObservedEnvelopePersistenceBySession;
     constructor(options: SandboxAgentConnectOptions);
     static connect(options: SandboxAgentConnectOptions): Promise<SandboxAgent>;
-    static start(options?: SandboxAgentStartOptions): Promise<SandboxAgent>;
+    static start(options: SandboxAgentStartOptions): Promise<SandboxAgent>;
+    get sandboxId(): string | undefined;
+    get sandbox(): SandboxProvider | undefined;
+    get inspectorUrl(): string;
     dispose(): Promise<void>;
+    destroySandbox(): Promise<void>;
     listSessions(request?: ListPageRequest): Promise<ListPage<Session>>;
     getSession(id: string): Promise<Session | null>;
     getEvents(request: ListEventsRequest): Promise<ListPage<SessionEvent>>;
@@ -1740,6 +1750,7 @@ declare class SandboxAgent {
     connectProcessTerminal(id: string, options?: ProcessTerminalSessionOptions): ProcessTerminalSession;
     private getLiveConnection;
     private persistObservedEnvelope;
+    private enqueueObservedEnvelopePersistence;
     private persistSessionStateFromEvent;
     private allocateSessionEventIndex;
     private ensureSessionEventIndexSeeded;
@@ -1781,4 +1792,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 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 };
+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 SandboxAgentStartOptions, SandboxProvider, 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

@@ -20,7 +20,7 @@ var InMemorySessionPersistDriver = class {
   }
   async getSession(id) {
     const session = this.sessions.get(id);
-    return session ? cloneSessionRecord(session) : null;
+    return session ? cloneSessionRecord(session) : void 0;
   }
   async listSessions(request = {}) {
     const sorted = [...this.sessions.values()].sort((a, b) => {
@@ -68,13 +68,13 @@ var InMemorySessionPersistDriver = class {
       nextCursor: page.nextCursor
     };
   }
-  async insertEvent(event) {
-    const events = this.eventsBySession.get(event.sessionId) ?? [];
+  async insertEvent(sessionId, event) {
+    const events = this.eventsBySession.get(sessionId) ?? [];
     events.push(cloneSessionEvent(event));
     if (events.length > this.maxEventsPerSession) {
       events.splice(0, events.length - this.maxEventsPerSession);
     }
-    this.eventsBySession.set(event.sessionId, events);
+    this.eventsBySession.set(sessionId, events);
   }
 };
 function cloneSessionRecord(session) {
@@ -125,12 +125,14 @@ var DEFAULT_BASE_URL = "http://sandbox-agent";
 var DEFAULT_REPLAY_MAX_EVENTS = 50;
 var DEFAULT_REPLAY_MAX_CHARS = 12e3;
 var EVENT_INDEX_SCAN_EVENTS_LIMIT = 500;
+var MAX_EVENT_INDEX_INSERT_RETRIES = 3;
 var SESSION_CANCEL_METHOD = "session/cancel";
 var MANUAL_CANCEL_ERROR = "Manual session/cancel calls are not allowed. Use destroySession(sessionId) instead.";
 var HEALTH_WAIT_MIN_DELAY_MS = 500;
 var HEALTH_WAIT_MAX_DELAY_MS = 15e3;
 var HEALTH_WAIT_LOG_AFTER_MS = 5e3;
 var HEALTH_WAIT_LOG_EVERY_MS = 1e4;
+var HEALTH_WAIT_ENSURE_SERVER_AFTER_FAILURES = 3;
 var SandboxAgentError = class extends Error {
   status;
   problem;
@@ -638,10 +640,12 @@ var SandboxAgent = class _SandboxAgent {
   defaultHeaders;
   healthWait;
   healthWaitAbortController = new AbortController();
+  sandboxProvider;
+  sandboxProviderId;
+  sandboxProviderRawId;
   persist;
   replayMaxEvents;
   replayMaxChars;
-  spawnHandle;
   healthPromise;
   healthError;
   disposed = false;
@@ -653,6 +657,7 @@ var SandboxAgent = class _SandboxAgent {
   pendingPermissionRequests = /* @__PURE__ */ new Map();
   nextSessionEventIndexBySession = /* @__PURE__ */ new Map();
   seedSessionEventIndexBySession = /* @__PURE__ */ new Map();
+  pendingObservedEnvelopePersistenceBySession = /* @__PURE__ */ new Map();
   constructor(options) {
     const baseUrl = options.baseUrl?.trim();
     if (!baseUrl && !options.fetch) {
@@ -666,7 +671,7 @@ var SandboxAgent = class _SandboxAgent {
     }
     this.fetcher = resolvedFetch;
     this.defaultHeaders = options.headers;
-    this.healthWait = normalizeHealthWaitOptions(options.waitForHealth, options.signal);
+    this.healthWait = normalizeHealthWaitOptions(options.skipHealthCheck, options.waitForHealth, options.signal);
     this.persist = options.persist ?? new InMemorySessionPersistDriver();
     this.replayMaxEvents = normalizePositiveInt(options.replayMaxEvents, DEFAULT_REPLAY_MAX_EVENTS);
     this.replayMaxChars = normalizePositiveInt(options.replayMaxChars, DEFAULT_REPLAY_MAX_CHARS);
@@ -675,26 +680,66 @@ var SandboxAgent = class _SandboxAgent {
   static async connect(options) {
     return new _SandboxAgent(options);
   }
-  static async start(options = {}) {
-    const spawnOptions = normalizeSpawnOptions(options.spawn, true);
-    if (!spawnOptions.enabled) {
-      throw new Error("SandboxAgent.start requires spawn to be enabled.");
+  static async start(options) {
+    const provider = options.sandbox;
+    if (!provider.getUrl && !provider.getFetch) {
+      throw new Error(`Sandbox provider '${provider.name}' must implement getUrl() or getFetch().`);
     }
-    const { spawnSandboxAgent } = await import("./spawn-ROM6CN74.js");
-    const resolvedFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
-    const handle = await spawnSandboxAgent(spawnOptions, resolvedFetch);
-    const client = new _SandboxAgent({
-      baseUrl: handle.baseUrl,
-      token: handle.token,
-      fetch: options.fetch,
-      headers: options.headers,
-      waitForHealth: false,
-      persist: options.persist,
-      replayMaxEvents: options.replayMaxEvents,
-      replayMaxChars: options.replayMaxChars
-    });
-    client.spawnHandle = handle;
-    return client;
+    const existingSandbox = options.sandboxId ? parseSandboxProviderId(options.sandboxId) : null;
+    if (existingSandbox && existingSandbox.provider !== provider.name) {
+      throw new Error(
+        `SandboxAgent.start received sandboxId '${options.sandboxId}' for provider '${existingSandbox.provider}', but the configured provider is '${provider.name}'.`
+      );
+    }
+    const rawSandboxId = existingSandbox?.rawId ?? await provider.create();
+    const prefixedSandboxId = `${provider.name}/${rawSandboxId}`;
+    const createdSandbox = !existingSandbox;
+    if (existingSandbox) {
+      await provider.ensureServer?.(rawSandboxId);
+    }
+    try {
+      const fetcher = await resolveProviderFetch(provider, rawSandboxId);
+      const baseUrl = provider.getUrl ? await provider.getUrl(rawSandboxId) : void 0;
+      const providerFetch = options.fetch ?? fetcher;
+      const commonConnectOptions = {
+        headers: options.headers,
+        persist: options.persist,
+        replayMaxEvents: options.replayMaxEvents,
+        replayMaxChars: options.replayMaxChars,
+        signal: options.signal,
+        skipHealthCheck: options.skipHealthCheck,
+        token: options.token ?? await resolveProviderToken(provider, rawSandboxId)
+      };
+      const client = providerFetch ? new _SandboxAgent({
+        ...commonConnectOptions,
+        baseUrl,
+        fetch: providerFetch
+      }) : new _SandboxAgent({
+        ...commonConnectOptions,
+        baseUrl: requireSandboxBaseUrl(baseUrl, provider.name)
+      });
+      client.sandboxProvider = provider;
+      client.sandboxProviderId = prefixedSandboxId;
+      client.sandboxProviderRawId = rawSandboxId;
+      return client;
+    } catch (error) {
+      if (createdSandbox) {
+        try {
+          await provider.destroy(rawSandboxId);
+        } catch {
+        }
+      }
+      throw error;
+    }
+  }
+  get sandboxId() {
+    return this.sandboxProviderId;
+  }
+  get sandbox() {
+    return this.sandboxProvider;
+  }
+  get inspectorUrl() {
+    return `${this.baseUrl.replace(/\/+$/, "")}/ui/`;
   }
   async dispose() {
     this.disposed = true;
@@ -707,6 +752,7 @@ var SandboxAgent = class _SandboxAgent {
     this.liveConnections.clear();
     const pending = [...this.pendingLiveConnections.values()];
     this.pendingLiveConnections.clear();
+    this.pendingObservedEnvelopePersistenceBySession.clear();
     const pendingSettled = await Promise.allSettled(pending);
     for (const item of pendingSettled) {
       if (item.status === "fulfilled") {
@@ -718,9 +764,21 @@ var SandboxAgent = class _SandboxAgent {
         await connection.close();
       })
     );
-    if (this.spawnHandle) {
-      await this.spawnHandle.dispose();
-      this.spawnHandle = void 0;
+  }
+  async destroySandbox() {
+    const provider = this.sandboxProvider;
+    const rawSandboxId = this.sandboxProviderRawId;
+    try {
+      if (provider && rawSandboxId) {
+        await provider.destroy(rawSandboxId);
+      } else if (!provider || !rawSandboxId) {
+        throw new Error("SandboxAgent is not attached to a provisioned sandbox.");
+      }
+    } finally {
+      await this.dispose();
+      this.sandboxProvider = void 0;
+      this.sandboxProviderId = void 0;
+      this.sandboxProviderRawId = void 0;
     }
   }
   async listSessions(request = {}) {
@@ -746,7 +804,7 @@ var SandboxAgent = class _SandboxAgent {
     }
     const localSessionId = request.id?.trim() || randomId();
     const live = await this.getLiveConnection(request.agent.trim());
-    const sessionInit = normalizeSessionInit(request.sessionInit);
+    const sessionInit = normalizeSessionInit(request.sessionInit, request.cwd);
     const response = await live.createRemoteSession(localSessionId, sessionInit);
     const record = {
       id: localSessionId,
@@ -754,12 +812,12 @@ var SandboxAgent = class _SandboxAgent {
       agentSessionId: response.sessionId,
       lastConnectionId: live.connectionId,
       createdAt: nowMs(),
+      sandboxId: this.sandboxProviderId,
       sessionInit,
       configOptions: cloneConfigOptions(response.configOptions),
       modes: cloneModes(response.modes)
     };
     await this.persist.updateSession(record);
-    this.nextSessionEventIndexBySession.set(record.id, 1);
     live.bindSession(record.id, record.agentSessionId);
     let session = this.upsertSessionHandle(record);
     try {
@@ -1299,7 +1357,9 @@ var SandboxAgent = class _SandboxAgent {
         agent,
         serverId,
         onObservedEnvelope: (connection, envelope, direction, localSessionId) => {
-          void this.persistObservedEnvelope(connection, envelope, direction, localSessionId);
+          void this.enqueueObservedEnvelopePersistence(connection, envelope, direction, localSessionId).catch((error) => {
+            console.error("Failed to persist observed sandbox-agent envelope", error);
+          });
         },
         onPermissionRequest: async (connection, localSessionId, agentSessionId, request) => this.enqueuePermissionRequest(connection, localSessionId, agentSessionId, request)
       });
@@ -1324,16 +1384,29 @@ var SandboxAgent = class _SandboxAgent {
     if (!localSessionId) {
       return;
     }
-    const event = {
-      id: randomId(),
-      eventIndex: await this.allocateSessionEventIndex(localSessionId),
-      sessionId: localSessionId,
-      createdAt: nowMs(),
-      connectionId: connection.connectionId,
-      sender: direction === "outbound" ? "client" : "agent",
-      payload: cloneEnvelope(envelope)
-    };
-    await this.persist.insertEvent(event);
+    let event = null;
+    for (let attempt = 0; attempt < MAX_EVENT_INDEX_INSERT_RETRIES; attempt += 1) {
+      event = {
+        id: randomId(),
+        eventIndex: await this.allocateSessionEventIndex(localSessionId),
+        sessionId: localSessionId,
+        createdAt: nowMs(),
+        connectionId: connection.connectionId,
+        sender: direction === "outbound" ? "client" : "agent",
+        payload: cloneEnvelope(envelope)
+      };
+      try {
+        await this.persist.insertEvent(localSessionId, event);
+        break;
+      } catch (error) {
+        if (!isSessionEventIndexConflict(error) || attempt === MAX_EVENT_INDEX_INSERT_RETRIES - 1) {
+          throw error;
+        }
+      }
+    }
+    if (!event) {
+      return;
+    }
     await this.persistSessionStateFromEvent(localSessionId, envelope, direction);
     const listeners = this.eventListeners.get(localSessionId);
     if (!listeners || listeners.size === 0) {
@@ -1343,6 +1416,22 @@ var SandboxAgent = class _SandboxAgent {
       listener(event);
     }
   }
+  async enqueueObservedEnvelopePersistence(connection, envelope, direction, localSessionId) {
+    if (!localSessionId) {
+      return;
+    }
+    const previous = this.pendingObservedEnvelopePersistenceBySession.get(localSessionId) ?? Promise.resolve();
+    const current = previous.catch(() => {
+    }).then(() => this.persistObservedEnvelope(connection, envelope, direction, localSessionId));
+    this.pendingObservedEnvelopePersistenceBySession.set(localSessionId, current);
+    try {
+      await current;
+    } finally {
+      if (this.pendingObservedEnvelopePersistenceBySession.get(localSessionId) === current) {
+        this.pendingObservedEnvelopePersistenceBySession.delete(localSessionId);
+      }
+    }
+  }
   async persistSessionStateFromEvent(sessionId, envelope, direction) {
     if (direction !== "inbound") {
       return;
@@ -1586,6 +1675,7 @@ var SandboxAgent = class _SandboxAgent {
     let delayMs = HEALTH_WAIT_MIN_DELAY_MS;
     let nextLogAt = startedAt + HEALTH_WAIT_LOG_AFTER_MS;
     let lastError;
+    let consecutiveFailures = 0;
     while (!this.disposed && (deadline === void 0 || Date.now() < deadline)) {
       throwIfAborted(signal);
       try {
@@ -1594,11 +1684,20 @@ var SandboxAgent = class _SandboxAgent {
           return;
         }
         lastError = new Error(`Unexpected health response: ${JSON.stringify(health)}`);
+        consecutiveFailures++;
       } catch (error) {
         if (isAbortError(error)) {
           throw error;
         }
         lastError = error;
+        consecutiveFailures++;
+      }
+      if (consecutiveFailures >= HEALTH_WAIT_ENSURE_SERVER_AFTER_FAILURES && this.sandboxProvider?.ensureServer && this.sandboxProviderRawId) {
+        try {
+          await this.sandboxProvider.ensureServer(this.sandboxProviderRawId);
+        } catch {
+        }
+        consecutiveFailures = 0;
       }
       const now = Date.now();
       if (now >= nextLogAt) {
@@ -1644,6 +1743,12 @@ var SandboxAgent = class _SandboxAgent {
     });
   }
 };
+function isSessionEventIndexConflict(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /UNIQUE constraint failed: .*session_id, .*event_index/.test(error.message);
+}
 function parseProcessTerminalServerFrame(payload) {
   try {
     const parsed = JSON.parse(payload);
@@ -1725,16 +1830,16 @@ function toAgentQuery(options) {
     no_cache: options.noCache
   };
 }
-function normalizeSessionInit(value) {
+function normalizeSessionInit(value, cwdShorthand) {
   if (!value) {
     return {
-      cwd: defaultCwd(),
+      cwd: cwdShorthand ?? defaultCwd(),
       mcpServers: []
     };
   }
   return {
     ...value,
-    cwd: value.cwd ?? defaultCwd(),
+    cwd: value.cwd ?? cwdShorthand ?? defaultCwd(),
     mcpServers: value.mcpServers ?? []
   };
 }
@@ -1848,32 +1953,50 @@ function normalizePositiveInt(value, fallback) {
   }
   return Math.floor(value);
 }
-function normalizeHealthWaitOptions(value, signal) {
-  if (value === false) {
+function normalizeHealthWaitOptions(skipHealthCheck, waitForHealth, signal) {
+  if (skipHealthCheck === true || waitForHealth === false) {
     return { enabled: false };
   }
-  if (value === true || value === void 0) {
+  if (waitForHealth === true || waitForHealth === void 0) {
     return { enabled: true, signal };
   }
-  const timeoutMs = typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs) && value.timeoutMs > 0 ? Math.floor(value.timeoutMs) : void 0;
+  const timeoutMs = typeof waitForHealth.timeoutMs === "number" && Number.isFinite(waitForHealth.timeoutMs) && waitForHealth.timeoutMs > 0 ? Math.floor(waitForHealth.timeoutMs) : void 0;
   return {
     enabled: true,
     signal,
     timeoutMs
   };
 }
-function normalizeSpawnOptions(spawn, defaultEnabled) {
-  if (spawn === false) {
-    return { enabled: false };
-  }
-  if (spawn === true || spawn === void 0) {
-    return { enabled: defaultEnabled };
+function parseSandboxProviderId(sandboxId) {
+  const slashIndex = sandboxId.indexOf("/");
+  if (slashIndex < 1 || slashIndex === sandboxId.length - 1) {
+    throw new Error(`Sandbox IDs must be prefixed as "{provider}/{id}". Received '${sandboxId}'.`);
   }
   return {
-    ...spawn,
-    enabled: spawn.enabled ?? defaultEnabled
+    provider: sandboxId.slice(0, slashIndex),
+    rawId: sandboxId.slice(slashIndex + 1)
   };
 }
+function requireSandboxBaseUrl(baseUrl, providerName) {
+  if (!baseUrl) {
+    throw new Error(`Sandbox provider '${providerName}' did not return a base URL.`);
+  }
+  return baseUrl;
+}
+async function resolveProviderFetch(provider, rawSandboxId) {
+  if (provider.getFetch) {
+    return await provider.getFetch(rawSandboxId);
+  }
+  return void 0;
+}
+async function resolveProviderToken(provider, rawSandboxId) {
+  const maybeGetToken = provider.getToken;
+  if (typeof maybeGetToken !== "function") {
+    return void 0;
+  }
+  const token = await maybeGetToken.call(provider, rawSandboxId);
+  return typeof token === "string" && token ? token : void 0;
+}
 async function readProblem(response) {
   try {
     const text = await response.clone().text();
@@ -1938,7 +2061,7 @@ function deriveModesFromConfigOptions(configOptions) {
     return null;
   }
   const modeOption = findConfigOptionByCategory(configOptions, "mode");
-  if (!modeOption || !Array.isArray(modeOption.options)) {
+  if (!modeOption || modeOption.type !== "select" || !Array.isArray(modeOption.options)) {
     return null;
   }
   const availableModes = modeOption.options.flatMap((entry) => flattenConfigOptions(entry)).map((entry) => ({