sandbox-agent 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/client.ts
 import {
   AcpHttpClient,
+  AcpRpcError,
   PROTOCOL_VERSION
 } from "acp-http-client";
 
@@ -82,7 +83,9 @@ var InMemorySessionPersistDriver = class {
 function cloneSessionRecord(session) {
   return {
     ...session,
-    sessionInit: session.sessionInit ? JSON.parse(JSON.stringify(session.sessionInit)) : void 0
+    sessionInit: session.sessionInit ? JSON.parse(JSON.stringify(session.sessionInit)) : void 0,
+    configOptions: session.configOptions ? JSON.parse(JSON.stringify(session.configOptions)) : void 0,
+    modes: session.modes ? JSON.parse(JSON.stringify(session.modes)) : session.modes
   };
 }
 function cloneSessionEvent(event) {
@@ -121,9 +124,16 @@ function parseCursor(cursor) {
 // src/client.ts
 var API_PREFIX = "/v1";
 var FS_PATH = `${API_PREFIX}/fs`;
+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 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 SandboxAgentError = class extends Error {
   status;
   problem;
@@ -136,6 +146,52 @@ var SandboxAgentError = class extends Error {
     this.response = response;
   }
 };
+var UnsupportedSessionCategoryError = class extends Error {
+  sessionId;
+  category;
+  availableCategories;
+  constructor(sessionId, category, availableCategories) {
+    super(
+      `Session '${sessionId}' does not support category '${category}'. Available categories: ${availableCategories.join(", ") || "(none)"}`
+    );
+    this.name = "UnsupportedSessionCategoryError";
+    this.sessionId = sessionId;
+    this.category = category;
+    this.availableCategories = availableCategories;
+  }
+};
+var UnsupportedSessionValueError = class extends Error {
+  sessionId;
+  category;
+  configId;
+  requestedValue;
+  allowedValues;
+  constructor(sessionId, category, configId, requestedValue, allowedValues) {
+    super(
+      `Session '${sessionId}' does not support value '${requestedValue}' for category '${category}' (configId='${configId}'). Allowed values: ${allowedValues.join(", ") || "(none)"}`
+    );
+    this.name = "UnsupportedSessionValueError";
+    this.sessionId = sessionId;
+    this.category = category;
+    this.configId = configId;
+    this.requestedValue = requestedValue;
+    this.allowedValues = allowedValues;
+  }
+};
+var UnsupportedSessionConfigOptionError = class extends Error {
+  sessionId;
+  configId;
+  availableConfigIds;
+  constructor(sessionId, configId, availableConfigIds) {
+    super(
+      `Session '${sessionId}' does not expose config option '${configId}'. Available configIds: ${availableConfigIds.join(", ") || "(none)"}`
+    );
+    this.name = "UnsupportedSessionConfigOptionError";
+    this.sessionId = sessionId;
+    this.configId = configId;
+    this.availableConfigIds = availableConfigIds;
+  }
+};
 var Session = class {
   record;
   sandbox;
@@ -178,6 +234,32 @@ var Session = class {
     const response = await this.send("session/prompt", { prompt });
     return response;
   }
+  async setMode(modeId) {
+    const updated = await this.sandbox.setSessionMode(this.id, modeId);
+    this.apply(updated.session.toRecord());
+    return updated.response;
+  }
+  async setConfigOption(configId, value) {
+    const updated = await this.sandbox.setSessionConfigOption(this.id, configId, value);
+    this.apply(updated.session.toRecord());
+    return updated.response;
+  }
+  async setModel(model) {
+    const updated = await this.sandbox.setSessionModel(this.id, model);
+    this.apply(updated.session.toRecord());
+    return updated.response;
+  }
+  async setThoughtLevel(thoughtLevel) {
+    const updated = await this.sandbox.setSessionThoughtLevel(this.id, thoughtLevel);
+    this.apply(updated.session.toRecord());
+    return updated.response;
+  }
+  async getConfigOptions() {
+    return this.sandbox.getSessionConfigOptions(this.id);
+  }
+  async getModes() {
+    return this.sandbox.getSessionModes(this.id);
+  }
   onEvent(listener) {
     return this.sandbox.onSessionEvent(this.id, listener);
   }
@@ -197,6 +279,8 @@ var LiveAcpConnection = class _LiveAcpConnection {
   pendingNewSessionLocals = [];
   pendingRequestSessionById = /* @__PURE__ */ new Map();
   pendingReplayByLocalSessionId = /* @__PURE__ */ new Map();
+  lastAdapterExit = null;
+  lastAdapterExitAt = 0;
   onObservedEnvelope;
   constructor(agent, connectionId, acp, onObservedEnvelope) {
     this.agent = agent;
@@ -218,6 +302,10 @@ var LiveAcpConnection = class _LiveAcpConnection {
       },
       client: {
         sessionUpdate: async (_notification) => {
+        },
+        extNotification: async (method, params) => {
+          if (!live) return;
+          live.handleAdapterNotification(method, params);
         }
       },
       onEnvelope: (envelope, direction) => {
@@ -265,6 +353,7 @@ var LiveAcpConnection = class _LiveAcpConnection {
     this.pendingReplayByLocalSessionId.set(localSessionId, replayText);
   }
   async createRemoteSession(localSessionId, sessionInit) {
+    const createStartedAt = Date.now();
     this.pendingNewSessionLocals.push(localSessionId);
     try {
       const response = await this.acp.newSession(sessionInit);
@@ -275,6 +364,11 @@ var LiveAcpConnection = class _LiveAcpConnection {
       if (index !== -1) {
         this.pendingNewSessionLocals.splice(index, 1);
       }
+      const adapterExit = this.lastAdapterExit;
+      if (adapterExit && this.lastAdapterExitAt >= createStartedAt) {
+        const suffix = adapterExit.code == null ? "" : ` (code ${adapterExit.code})`;
+        throw new Error(`Agent process exited while creating session${suffix}`);
+      }
       throw error;
     }
   }
@@ -316,6 +410,16 @@ var LiveAcpConnection = class _LiveAcpConnection {
     const localSessionId = this.resolveSessionId(envelope, direction);
     this.onObservedEnvelope(this, envelope, direction, localSessionId);
   }
+  handleAdapterNotification(method, params) {
+    if (method !== "_adapter/agent_exited") {
+      return;
+    }
+    this.lastAdapterExit = {
+      success: params.success === true,
+      code: typeof params.code === "number" ? params.code : null
+    };
+    this.lastAdapterExitAt = Date.now();
+  }
   resolveSessionId(envelope, direction) {
     const id = envelopeId(envelope);
     const method = envelopeMethod(envelope);
@@ -359,26 +463,39 @@ var SandboxAgent = class _SandboxAgent {
   token;
   fetcher;
   defaultHeaders;
+  healthWait;
+  healthWaitAbortController = new AbortController();
   persist;
   replayMaxEvents;
   replayMaxChars;
   spawnHandle;
+  healthPromise;
+  healthError;
+  disposed = false;
   liveConnections = /* @__PURE__ */ new Map();
+  pendingLiveConnections = /* @__PURE__ */ new Map();
   sessionHandles = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
   nextSessionEventIndexBySession = /* @__PURE__ */ new Map();
   seedSessionEventIndexBySession = /* @__PURE__ */ new Map();
   constructor(options) {
-    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    const baseUrl = options.baseUrl?.trim();
+    if (!baseUrl && !options.fetch) {
+      throw new Error("baseUrl is required unless fetch is provided.");
+    }
+    this.baseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.token = options.token;
-    this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const resolvedFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!resolvedFetch) {
+      throw new Error("Fetch API is not available; provide a fetch implementation.");
+    }
+    this.fetcher = resolvedFetch;
     this.defaultHeaders = options.headers;
+    this.healthWait = normalizeHealthWaitOptions(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);
-    if (!this.fetcher) {
-      throw new Error("Fetch API is not available; provide a fetch implementation.");
-    }
+    this.startHealthWait();
   }
   static async connect(options) {
     return new _SandboxAgent(options);
@@ -389,12 +506,14 @@ var SandboxAgent = class _SandboxAgent {
       throw new Error("SandboxAgent.start requires spawn to be enabled.");
     }
     const { spawnSandboxAgent } = await import("./spawn-BQVVCZX7.js");
-    const handle = await spawnSandboxAgent(spawnOptions, options.fetch ?? globalThis.fetch);
+    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
@@ -403,8 +522,18 @@ var SandboxAgent = class _SandboxAgent {
     return client;
   }
   async dispose() {
+    this.disposed = true;
+    this.healthWaitAbortController.abort(createAbortError("SandboxAgent was disposed."));
     const connections = [...this.liveConnections.values()];
     this.liveConnections.clear();
+    const pending = [...this.pendingLiveConnections.values()];
+    this.pendingLiveConnections.clear();
+    const pendingSettled = await Promise.allSettled(pending);
+    for (const item of pendingSettled) {
+      if (item.status === "fulfilled") {
+        connections.push(item.value);
+      }
+    }
     await Promise.all(
       connections.map(async (connection) => {
         await connection.close();
@@ -446,12 +575,32 @@ var SandboxAgent = class _SandboxAgent {
       agentSessionId: response.sessionId,
       lastConnectionId: live.connectionId,
       createdAt: nowMs(),
-      sessionInit
+      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);
-    return this.upsertSessionHandle(record);
+    let session = this.upsertSessionHandle(record);
+    try {
+      if (request.mode) {
+        session = (await this.setSessionMode(session.id, request.mode)).session;
+      }
+      if (request.model) {
+        session = (await this.setSessionModel(session.id, request.model)).session;
+      }
+      if (request.thoughtLevel) {
+        session = (await this.setSessionThoughtLevel(session.id, request.thoughtLevel)).session;
+      }
+    } catch (err) {
+      try {
+        await this.destroySession(session.id);
+      } catch {
+      }
+      throw err;
+    }
+    return session;
   }
   async resumeSession(id) {
     const existing = await this.persist.getSession(id);
@@ -469,7 +618,9 @@ var SandboxAgent = class _SandboxAgent {
       ...existing,
       agentSessionId: recreated.sessionId,
       lastConnectionId: live.connectionId,
-      destroyedAt: void 0
+      destroyedAt: void 0,
+      configOptions: cloneConfigOptions(recreated.configOptions),
+      modes: cloneModes(recreated.modes)
     };
     await this.persist.updateSession(updated);
     live.bindSession(updated.id, updated.agentSessionId);
@@ -479,15 +630,26 @@ var SandboxAgent = class _SandboxAgent {
   async resumeOrCreateSession(request) {
     const existing = await this.persist.getSession(request.id);
     if (existing) {
-      return this.resumeSession(existing.id);
+      let session = await this.resumeSession(existing.id);
+      if (request.mode) {
+        session = (await this.setSessionMode(session.id, request.mode)).session;
+      }
+      if (request.model) {
+        session = (await this.setSessionModel(session.id, request.model)).session;
+      }
+      if (request.thoughtLevel) {
+        session = (await this.setSessionThoughtLevel(session.id, request.thoughtLevel)).session;
+      }
+      return session;
     }
     return this.createSession(request);
   }
   async destroySession(id) {
-    const existing = await this.persist.getSession(id);
-    if (!existing) {
-      throw new Error(`session '${id}' not found`);
+    try {
+      await this.sendSessionMethodInternal(id, SESSION_CANCEL_METHOD, {}, {}, true);
+    } catch {
     }
+    const existing = await this.requireSessionRecord(id);
     const updated = {
       ...existing,
       destroyedAt: nowMs()
@@ -495,7 +657,132 @@ var SandboxAgent = class _SandboxAgent {
     await this.persist.updateSession(updated);
     return this.upsertSessionHandle(updated);
   }
+  async setSessionMode(sessionId, modeId) {
+    const mode = modeId.trim();
+    if (!mode) {
+      throw new Error("setSessionMode requires a non-empty modeId");
+    }
+    const record = await this.requireSessionRecord(sessionId);
+    const knownModeIds = extractKnownModeIds(record.modes);
+    if (knownModeIds.length > 0 && !knownModeIds.includes(mode)) {
+      throw new UnsupportedSessionValueError(sessionId, "mode", "mode", mode, knownModeIds);
+    }
+    try {
+      return await this.sendSessionMethodInternal(
+        sessionId,
+        "session/set_mode",
+        { modeId: mode },
+        {},
+        false
+      );
+    } catch (error) {
+      if (!(error instanceof AcpRpcError) || error.code !== -32601) {
+        throw error;
+      }
+      return this.setSessionCategoryValue(sessionId, "mode", mode);
+    }
+  }
+  async setSessionConfigOption(sessionId, configId, value) {
+    const resolvedConfigId = configId.trim();
+    if (!resolvedConfigId) {
+      throw new Error("setSessionConfigOption requires a non-empty configId");
+    }
+    const resolvedValue = value.trim();
+    if (!resolvedValue) {
+      throw new Error("setSessionConfigOption requires a non-empty value");
+    }
+    const options = await this.getSessionConfigOptions(sessionId);
+    const option = findConfigOptionById(options, resolvedConfigId);
+    if (!option) {
+      throw new UnsupportedSessionConfigOptionError(
+        sessionId,
+        resolvedConfigId,
+        options.map((item) => item.id)
+      );
+    }
+    const allowedValues = extractConfigValues(option);
+    if (allowedValues.length > 0 && !allowedValues.includes(resolvedValue)) {
+      throw new UnsupportedSessionValueError(
+        sessionId,
+        option.category ?? "uncategorized",
+        option.id,
+        resolvedValue,
+        allowedValues
+      );
+    }
+    return await this.sendSessionMethodInternal(
+      sessionId,
+      "session/set_config_option",
+      {
+        configId: resolvedConfigId,
+        value: resolvedValue
+      },
+      {},
+      false
+    );
+  }
+  async setSessionModel(sessionId, model) {
+    return this.setSessionCategoryValue(sessionId, "model", model);
+  }
+  async setSessionThoughtLevel(sessionId, thoughtLevel) {
+    return this.setSessionCategoryValue(sessionId, "thought_level", thoughtLevel);
+  }
+  async getSessionConfigOptions(sessionId) {
+    const record = await this.requireSessionRecord(sessionId);
+    const hydrated = await this.hydrateSessionConfigOptions(record.id, record);
+    return cloneConfigOptions(hydrated.configOptions) ?? [];
+  }
+  async getSessionModes(sessionId) {
+    const record = await this.requireSessionRecord(sessionId);
+    return cloneModes(record.modes);
+  }
+  async setSessionCategoryValue(sessionId, category, value) {
+    const resolvedValue = value.trim();
+    if (!resolvedValue) {
+      throw new Error(`setSession${toTitleCase(category)} requires a non-empty value`);
+    }
+    const options = await this.getSessionConfigOptions(sessionId);
+    const option = findConfigOptionByCategory(options, category);
+    if (!option) {
+      const categories = uniqueCategories(options);
+      throw new UnsupportedSessionCategoryError(sessionId, category, categories);
+    }
+    const allowedValues = extractConfigValues(option);
+    if (allowedValues.length > 0 && !allowedValues.includes(resolvedValue)) {
+      throw new UnsupportedSessionValueError(
+        sessionId,
+        category,
+        option.id,
+        resolvedValue,
+        allowedValues
+      );
+    }
+    return this.setSessionConfigOption(sessionId, option.id, resolvedValue);
+  }
+  async hydrateSessionConfigOptions(sessionId, snapshot) {
+    if (snapshot.configOptions !== void 0) {
+      return snapshot;
+    }
+    const info = await this.getAgent(snapshot.agent, { config: true });
+    const configOptions = normalizeSessionConfigOptions(info.configOptions) ?? [];
+    const record = await this.persist.getSession(sessionId);
+    if (!record) {
+      return { ...snapshot, configOptions };
+    }
+    const updated = {
+      ...record,
+      configOptions
+    };
+    await this.persist.updateSession(updated);
+    return updated;
+  }
   async sendSessionMethod(sessionId, method, params, options = {}) {
+    return this.sendSessionMethodInternal(sessionId, method, params, options, false);
+  }
+  async sendSessionMethodInternal(sessionId, method, params, options, allowManagedCancel) {
+    if (method === SESSION_CANCEL_METHOD && !allowManagedCancel) {
+      throw new Error(MANUAL_CANCEL_ERROR);
+    }
     const record = await this.persist.getSession(sessionId);
     if (!record) {
       throw new Error(`session '${sessionId}' not found`);
@@ -503,15 +790,73 @@ var SandboxAgent = class _SandboxAgent {
     const live = await this.getLiveConnection(record.agent);
     if (!live.hasBoundSession(record.id, record.agentSessionId)) {
       const restored = await this.resumeSession(record.id);
-      return this.sendSessionMethod(restored.id, method, params, options);
+      return this.sendSessionMethodInternal(restored.id, method, params, options, allowManagedCancel);
     }
     const response = await live.sendSessionMethod(record.id, method, params, options);
+    await this.persistSessionStateFromMethod(record.id, method, params, response);
     const refreshed = await this.requireSessionRecord(record.id);
     return {
       session: this.upsertSessionHandle(refreshed),
       response
     };
   }
+  async persistSessionStateFromMethod(sessionId, method, params, response) {
+    const record = await this.persist.getSession(sessionId);
+    if (!record) {
+      return;
+    }
+    if (method === "session/set_config_option") {
+      const configId = typeof params.configId === "string" ? params.configId : null;
+      const value = typeof params.value === "string" ? params.value : null;
+      const updates = {};
+      const serverConfigOptions = extractConfigOptionsFromSetResponse(response);
+      if (serverConfigOptions) {
+        updates.configOptions = cloneConfigOptions(serverConfigOptions);
+      } else if (record.configOptions && configId && value) {
+        const updated = applyConfigOptionValue(record.configOptions, configId, value);
+        if (updated) {
+          updates.configOptions = updated;
+        }
+      }
+      if (configId && value) {
+        const source = updates.configOptions ?? record.configOptions;
+        const option = source ? findConfigOptionById(source, configId) : null;
+        if (option?.category === "mode") {
+          const nextModes = applyCurrentMode(record.modes, value);
+          if (nextModes) {
+            updates.modes = nextModes;
+          }
+        }
+      }
+      if (Object.keys(updates).length > 0) {
+        await this.persist.updateSession({ ...record, ...updates });
+      }
+      return;
+    }
+    if (method === "session/set_mode") {
+      const modeId = typeof params.modeId === "string" ? params.modeId : null;
+      if (!modeId) {
+        return;
+      }
+      const updates = {};
+      const nextModes = applyCurrentMode(record.modes, modeId);
+      if (nextModes) {
+        updates.modes = nextModes;
+      }
+      if (record.configOptions) {
+        const modeOption = findConfigOptionByCategory(record.configOptions, "mode");
+        if (modeOption) {
+          const updated = applyConfigOptionValue(record.configOptions, modeOption.id, modeId);
+          if (updated) {
+            updates.configOptions = updated;
+          }
+        }
+      }
+      if (Object.keys(updates).length > 0) {
+        await this.persist.updateSession({ ...record, ...updates });
+      }
+    }
+  }
   onSessionEvent(sessionId, listener) {
     const listeners = this.eventListeners.get(sessionId) ?? /* @__PURE__ */ new Set();
     listeners.add(listener);
@@ -528,16 +873,16 @@ var SandboxAgent = class _SandboxAgent {
     };
   }
   async getHealth() {
-    return this.requestJson("GET", `${API_PREFIX}/health`);
+    return this.requestHealth();
   }
   async listAgents(options) {
     return this.requestJson("GET", `${API_PREFIX}/agents`, {
-      query: options?.config ? { config: "true" } : void 0
+      query: toAgentQuery(options)
     });
   }
   async getAgent(agent, options) {
     return this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}`, {
-      query: options?.config ? { config: "true" } : void 0
+      query: toAgentQuery(options)
     });
   }
   async installAgent(agent, request = {}) {
@@ -609,25 +954,141 @@ var SandboxAgent = class _SandboxAgent {
   async deleteSkillsConfig(query) {
     await this.requestRaw("DELETE", `${API_PREFIX}/config/skills`, { query });
   }
+  async getProcessConfig() {
+    return this.requestJson("GET", `${API_PREFIX}/processes/config`);
+  }
+  async setProcessConfig(config) {
+    return this.requestJson("POST", `${API_PREFIX}/processes/config`, {
+      body: config
+    });
+  }
+  async createProcess(request) {
+    return this.requestJson("POST", `${API_PREFIX}/processes`, {
+      body: request
+    });
+  }
+  async runProcess(request) {
+    return this.requestJson("POST", `${API_PREFIX}/processes/run`, {
+      body: request
+    });
+  }
+  async listProcesses() {
+    return this.requestJson("GET", `${API_PREFIX}/processes`);
+  }
+  async getProcess(id) {
+    return this.requestJson("GET", `${API_PREFIX}/processes/${encodeURIComponent(id)}`);
+  }
+  async stopProcess(id, query) {
+    return this.requestJson("POST", `${API_PREFIX}/processes/${encodeURIComponent(id)}/stop`, {
+      query
+    });
+  }
+  async killProcess(id, query) {
+    return this.requestJson("POST", `${API_PREFIX}/processes/${encodeURIComponent(id)}/kill`, {
+      query
+    });
+  }
+  async deleteProcess(id) {
+    await this.requestRaw("DELETE", `${API_PREFIX}/processes/${encodeURIComponent(id)}`);
+  }
+  async getProcessLogs(id, query = {}) {
+    return this.requestJson("GET", `${API_PREFIX}/processes/${encodeURIComponent(id)}/logs`, {
+      query
+    });
+  }
+  async followProcessLogs(id, listener, query = {}) {
+    const abortController = new AbortController();
+    const response = await this.requestRaw(
+      "GET",
+      `${API_PREFIX}/processes/${encodeURIComponent(id)}/logs`,
+      {
+        query: { ...query, follow: true },
+        accept: "text/event-stream",
+        signal: abortController.signal
+      }
+    );
+    if (!response.body) {
+      abortController.abort();
+      throw new Error("SSE stream is not readable in this environment.");
+    }
+    const closed = consumeProcessLogSse(response.body, listener, abortController.signal);
+    return {
+      close: () => abortController.abort(),
+      closed
+    };
+  }
+  async sendProcessInput(id, request) {
+    return this.requestJson("POST", `${API_PREFIX}/processes/${encodeURIComponent(id)}/input`, {
+      body: request
+    });
+  }
+  async resizeProcessTerminal(id, request) {
+    return this.requestJson(
+      "POST",
+      `${API_PREFIX}/processes/${encodeURIComponent(id)}/terminal/resize`,
+      {
+        body: request
+      }
+    );
+  }
+  buildProcessTerminalWebSocketUrl(id, options = {}) {
+    return toWebSocketUrl(
+      this.buildUrl(`${API_PREFIX}/processes/${encodeURIComponent(id)}/terminal/ws`, {
+        access_token: options.accessToken ?? this.token
+      })
+    );
+  }
+  connectProcessTerminalWebSocket(id, options = {}) {
+    const WebSocketCtor = options.WebSocket ?? globalThis.WebSocket;
+    if (!WebSocketCtor) {
+      throw new Error("WebSocket API is not available; provide a WebSocket implementation.");
+    }
+    return new WebSocketCtor(
+      this.buildProcessTerminalWebSocketUrl(id, {
+        accessToken: options.accessToken
+      }),
+      options.protocols
+    );
+  }
   async getLiveConnection(agent) {
+    await this.awaitHealthy();
     const existing = this.liveConnections.get(agent);
     if (existing) {
       return existing;
     }
-    const serverId = `sdk-${agent}-${randomId()}`;
-    const created = await LiveAcpConnection.create({
-      baseUrl: this.baseUrl,
-      token: this.token,
-      fetcher: this.fetcher,
-      headers: this.defaultHeaders,
-      agent,
-      serverId,
-      onObservedEnvelope: (connection, envelope, direction, localSessionId) => {
-        void this.persistObservedEnvelope(connection, envelope, direction, localSessionId);
+    const pending = this.pendingLiveConnections.get(agent);
+    if (pending) {
+      return pending;
+    }
+    const creating = (async () => {
+      const serverId = `sdk-${agent}-${randomId()}`;
+      const created = await LiveAcpConnection.create({
+        baseUrl: this.baseUrl,
+        token: this.token,
+        fetcher: this.fetcher,
+        headers: this.defaultHeaders,
+        agent,
+        serverId,
+        onObservedEnvelope: (connection, envelope, direction, localSessionId) => {
+          void this.persistObservedEnvelope(connection, envelope, direction, localSessionId);
+        }
+      });
+      const raced = this.liveConnections.get(agent);
+      if (raced) {
+        await created.close();
+        return raced;
       }
-    });
-    this.liveConnections.set(agent, created);
-    return created;
+      this.liveConnections.set(agent, created);
+      return created;
+    })();
+    this.pendingLiveConnections.set(agent, creating);
+    try {
+      return await creating;
+    } finally {
+      if (this.pendingLiveConnections.get(agent) === creating) {
+        this.pendingLiveConnections.delete(agent);
+      }
+    }
   }
   async persistObservedEnvelope(connection, envelope, direction, localSessionId) {
     if (!localSessionId) {
@@ -643,6 +1104,7 @@ var SandboxAgent = class _SandboxAgent {
       payload: cloneEnvelope(envelope)
     };
     await this.persist.insertEvent(event);
+    await this.persistSessionStateFromEvent(localSessionId, envelope, direction);
     const listeners = this.eventListeners.get(localSessionId);
     if (!listeners || listeners.size === 0) {
       return;
@@ -651,6 +1113,46 @@ var SandboxAgent = class _SandboxAgent {
       listener(event);
     }
   }
+  async persistSessionStateFromEvent(sessionId, envelope, direction) {
+    if (direction !== "inbound") {
+      return;
+    }
+    if (envelopeMethod(envelope) !== "session/update") {
+      return;
+    }
+    const update = envelopeSessionUpdate(envelope);
+    if (!update || typeof update.sessionUpdate !== "string") {
+      return;
+    }
+    const record = await this.persist.getSession(sessionId);
+    if (!record) {
+      return;
+    }
+    if (update.sessionUpdate === "config_option_update") {
+      const configOptions = normalizeSessionConfigOptions(update.configOptions);
+      if (configOptions) {
+        await this.persist.updateSession({
+          ...record,
+          configOptions
+        });
+      }
+      return;
+    }
+    if (update.sessionUpdate === "current_mode_update") {
+      const modeId = typeof update.currentModeId === "string" ? update.currentModeId : null;
+      if (!modeId) {
+        return;
+      }
+      const nextModes = applyCurrentMode(record.modes, modeId);
+      if (!nextModes) {
+        return;
+      }
+      await this.persist.updateSession({
+        ...record,
+        modes: nextModes
+      });
+    }
+  }
   async allocateSessionEventIndex(sessionId) {
     await this.ensureSessionEventIndexSeeded(sessionId);
     const nextIndex = this.nextSessionEventIndexBySession.get(sessionId) ?? 1;
@@ -736,7 +1238,8 @@ var SandboxAgent = class _SandboxAgent {
       body: options.body,
       headers: options.headers,
       accept: options.accept ?? "application/json",
-      signal: options.signal
+      signal: options.signal,
+      skipReadyWait: options.skipReadyWait
     });
     if (response.status === 204) {
       return void 0;
@@ -744,6 +1247,9 @@ var SandboxAgent = class _SandboxAgent {
     return await response.json();
   }
   async requestRaw(method, path, options = {}) {
+    if (!options.skipReadyWait) {
+      await this.awaitHealthy(options.signal);
+    }
     const url = this.buildUrl(path, options.query);
     const headers = this.buildHeaders(options.headers);
     if (options.accept) {
@@ -773,6 +1279,64 @@ var SandboxAgent = class _SandboxAgent {
     }
     return response;
   }
+  startHealthWait() {
+    if (!this.healthWait.enabled || this.healthPromise) {
+      return;
+    }
+    this.healthPromise = this.runHealthWait().catch((error) => {
+      this.healthError = error instanceof Error ? error : new Error(String(error));
+    });
+  }
+  async awaitHealthy(signal) {
+    if (!this.healthPromise) {
+      throwIfAborted(signal);
+      return;
+    }
+    await waitForAbortable(this.healthPromise, signal);
+    throwIfAborted(signal);
+    if (this.healthError) {
+      throw this.healthError;
+    }
+  }
+  async runHealthWait() {
+    const signal = this.healthWait.enabled ? anyAbortSignal([this.healthWait.signal, this.healthWaitAbortController.signal]) : void 0;
+    const startedAt = Date.now();
+    const deadline = typeof this.healthWait.timeoutMs === "number" ? startedAt + this.healthWait.timeoutMs : void 0;
+    let delayMs = HEALTH_WAIT_MIN_DELAY_MS;
+    let nextLogAt = startedAt + HEALTH_WAIT_LOG_AFTER_MS;
+    let lastError;
+    while (!this.disposed && (deadline === void 0 || Date.now() < deadline)) {
+      throwIfAborted(signal);
+      try {
+        const health = await this.requestHealth({ signal });
+        if (health.status === "ok") {
+          return;
+        }
+        lastError = new Error(`Unexpected health response: ${JSON.stringify(health)}`);
+      } catch (error) {
+        if (isAbortError(error)) {
+          throw error;
+        }
+        lastError = error;
+      }
+      const now = Date.now();
+      if (now >= nextLogAt) {
+        const details = formatHealthWaitError(lastError);
+        console.warn(
+          `sandbox-agent at ${this.baseUrl} is not healthy after ${now - startedAt}ms; still waiting (${details})`
+        );
+        nextLogAt = now + HEALTH_WAIT_LOG_EVERY_MS;
+      }
+      await sleep(delayMs, signal);
+      delayMs = Math.min(HEALTH_WAIT_MAX_DELAY_MS, delayMs * 2);
+    }
+    if (this.disposed) {
+      return;
+    }
+    throw new Error(
+      `Timed out waiting for sandbox-agent health after ${this.healthWait.timeoutMs}ms (${formatHealthWaitError(lastError)})`
+    );
+  }
   buildHeaders(extra) {
     const headers = new Headers(this.defaultHeaders ?? void 0);
     if (this.token) {
@@ -796,6 +1360,12 @@ var SandboxAgent = class _SandboxAgent {
     }
     return url.toString();
   }
+  async requestHealth(options = {}) {
+    return this.requestJson("GET", `${API_PREFIX}/health`, {
+      signal: options.signal,
+      skipReadyWait: true
+    });
+  }
 };
 async function autoAuthenticate(acp, methods) {
   const envBased = methods.find(
@@ -809,6 +1379,15 @@ async function autoAuthenticate(acp, methods) {
   } catch {
   }
 }
+function toAgentQuery(options) {
+  if (!options) {
+    return void 0;
+  }
+  return {
+    config: options.config,
+    no_cache: options.noCache
+  };
+}
 function normalizeSessionInit(value) {
   if (!value) {
     return {
@@ -916,6 +1495,20 @@ function normalizePositiveInt(value, fallback) {
   }
   return Math.floor(value);
 }
+function normalizeHealthWaitOptions(value, signal) {
+  if (value === false) {
+    return { enabled: false };
+  }
+  if (value === true || value === 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;
+  return {
+    enabled: true,
+    signal,
+    timeoutMs
+  };
+}
 function normalizeSpawnOptions(spawn, defaultEnabled) {
   if (spawn === false) {
     return { enabled: false };
@@ -939,9 +1532,282 @@ async function readProblem(response) {
     return void 0;
   }
 }
+function normalizeSessionConfigOptions(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const normalized = value.filter(isSessionConfigOption);
+  return cloneConfigOptions(normalized) ?? [];
+}
+function extractConfigOptionsFromSetResponse(response) {
+  if (!isRecord(response)) {
+    return void 0;
+  }
+  return normalizeSessionConfigOptions(response.configOptions);
+}
+function findConfigOptionByCategory(options, category) {
+  return options.find((option) => option.category === category);
+}
+function findConfigOptionById(options, configId) {
+  return options.find((option) => option.id === configId);
+}
+function uniqueCategories(options) {
+  return [...new Set(options.map((option) => option.category).filter((value) => !!value))].sort();
+}
+function extractConfigValues(option) {
+  if (!isRecord(option) || option.type !== "select" || !Array.isArray(option.options)) {
+    return [];
+  }
+  const values = [];
+  for (const entry of option.options) {
+    if (isRecord(entry) && typeof entry.value === "string") {
+      values.push(entry.value);
+      continue;
+    }
+    if (isRecord(entry) && Array.isArray(entry.options)) {
+      for (const nested of entry.options) {
+        if (isRecord(nested) && typeof nested.value === "string") {
+          values.push(nested.value);
+        }
+      }
+    }
+  }
+  return [...new Set(values)];
+}
+function extractKnownModeIds(modes) {
+  if (!modes || !Array.isArray(modes.availableModes)) {
+    return [];
+  }
+  return modes.availableModes.map((mode) => typeof mode.id === "string" ? mode.id : null).filter((value) => !!value);
+}
+function applyCurrentMode(modes, currentModeId) {
+  if (modes && Array.isArray(modes.availableModes)) {
+    return {
+      ...modes,
+      currentModeId
+    };
+  }
+  return {
+    currentModeId,
+    availableModes: []
+  };
+}
+function applyConfigOptionValue(configOptions, configId, value) {
+  const idx = configOptions.findIndex((o) => o.id === configId);
+  if (idx === -1) {
+    return null;
+  }
+  const updated = cloneConfigOptions(configOptions) ?? [];
+  updated[idx] = { ...updated[idx], currentValue: value };
+  return updated;
+}
+function envelopeSessionUpdate(message) {
+  if (!isRecord(message) || !("params" in message) || !isRecord(message.params)) {
+    return null;
+  }
+  if (!("update" in message.params) || !isRecord(message.params.update)) {
+    return null;
+  }
+  return message.params.update;
+}
+function cloneConfigOptions(value) {
+  if (!value) {
+    return void 0;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function cloneModes(value) {
+  if (!value) {
+    return null;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function isSessionConfigOption(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && typeof value.type === "string";
+}
+function toTitleCase(input) {
+  if (!input) {
+    return "";
+  }
+  return input.split(/[_\s-]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+}
+function formatHealthWaitError(error) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (error === void 0 || error === null) {
+    return "unknown error";
+  }
+  return String(error);
+}
+function anyAbortSignal(signals) {
+  const active = signals.filter((signal) => Boolean(signal));
+  if (active.length === 0) {
+    return void 0;
+  }
+  if (active.length === 1) {
+    return active[0];
+  }
+  const controller = new AbortController();
+  const onAbort = (event) => {
+    cleanup();
+    const signal = event.target;
+    controller.abort(signal.reason ?? createAbortError());
+  };
+  const cleanup = () => {
+    for (const signal of active) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  };
+  for (const signal of active) {
+    if (signal.aborted) {
+      controller.abort(signal.reason ?? createAbortError());
+      return controller.signal;
+    }
+  }
+  for (const signal of active) {
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+  return controller.signal;
+}
+function throwIfAborted(signal) {
+  if (!signal?.aborted) {
+    return;
+  }
+  throw signal.reason instanceof Error ? signal.reason : createAbortError(signal.reason);
+}
+async function waitForAbortable(promise, signal) {
+  if (!signal) {
+    return promise;
+  }
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(signal.reason instanceof Error ? signal.reason : createAbortError(signal.reason));
+    };
+    const cleanup = () => {
+      signal.removeEventListener("abort", onAbort);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+async function consumeProcessLogSse(body, listener, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) {
+        return;
+      }
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+      let separatorIndex = buffer.indexOf("\n\n");
+      while (separatorIndex !== -1) {
+        const chunk = buffer.slice(0, separatorIndex);
+        buffer = buffer.slice(separatorIndex + 2);
+        const entry = parseProcessLogSseChunk(chunk);
+        if (entry) {
+          listener(entry);
+        }
+        separatorIndex = buffer.indexOf("\n\n");
+      }
+    }
+  } catch (error) {
+    if (signal.aborted || isAbortError(error)) {
+      return;
+    }
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+}
+function parseProcessLogSseChunk(chunk) {
+  if (!chunk.trim()) {
+    return null;
+  }
+  let eventName = "message";
+  const dataLines = [];
+  for (const line of chunk.split("\n")) {
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      eventName = line.slice(6).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    }
+  }
+  if (eventName !== "log") {
+    return null;
+  }
+  const data = dataLines.join("\n");
+  if (!data.trim()) {
+    return null;
+  }
+  return JSON.parse(data);
+}
+function toWebSocketUrl(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol === "http:") {
+    parsed.protocol = "ws:";
+  } else if (parsed.protocol === "https:") {
+    parsed.protocol = "wss:";
+  }
+  return parsed.toString();
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+function createAbortError(reason) {
+  if (reason instanceof Error) {
+    return reason;
+  }
+  const message = typeof reason === "string" ? reason : "This operation was aborted.";
+  if (typeof DOMException !== "undefined") {
+    return new DOMException(message, "AbortError");
+  }
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+function sleep(ms, signal) {
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      cleanup();
+      reject(signal.reason instanceof Error ? signal.reason : createAbortError(signal.reason));
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 
 // src/index.ts
-import { AcpRpcError } from "acp-http-client";
+import { AcpRpcError as AcpRpcError2 } from "acp-http-client";
 
 // src/inspector.ts
 function buildInspectorUrl(options) {
@@ -957,12 +1823,15 @@ function buildInspectorUrl(options) {
   return `${normalized}/ui/${queryString ? `?${queryString}` : ""}`;
 }
 export {
-  AcpRpcError,
+  AcpRpcError2 as AcpRpcError,
   InMemorySessionPersistDriver,
   LiveAcpConnection,
   SandboxAgent,
   SandboxAgentError,
   Session,
+  UnsupportedSessionCategoryError,
+  UnsupportedSessionConfigOptionError,
+  UnsupportedSessionValueError,
   buildInspectorUrl
 };
 //# sourceMappingURL=index.js.map