sandbox-agent 0.2.1 → 0.3.0

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) {
@@ -125,6 +128,12 @@ 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;
@@ -137,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;
@@ -179,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);
   }
@@ -377,15 +458,163 @@ var LiveAcpConnection = class _LiveAcpConnection {
     return this.localByAgentSessionId.get(agentSessionId) ?? null;
   }
 };
+var ProcessTerminalSession = class {
+  socket;
+  closed;
+  readyListeners = /* @__PURE__ */ new Set();
+  dataListeners = /* @__PURE__ */ new Set();
+  exitListeners = /* @__PURE__ */ new Set();
+  errorListeners = /* @__PURE__ */ new Set();
+  closeListeners = /* @__PURE__ */ new Set();
+  closeSignalSent = false;
+  closedResolve;
+  constructor(socket) {
+    this.socket = socket;
+    this.socket.binaryType = "arraybuffer";
+    this.closed = new Promise((resolve) => {
+      this.closedResolve = resolve;
+    });
+    this.socket.addEventListener("message", (event) => {
+      void this.handleMessage(event.data);
+    });
+    this.socket.addEventListener("error", () => {
+      this.emitError(new Error("Terminal websocket connection failed."));
+    });
+    this.socket.addEventListener("close", () => {
+      this.closedResolve();
+      for (const listener of this.closeListeners) {
+        listener();
+      }
+    });
+  }
+  onReady(listener) {
+    this.readyListeners.add(listener);
+    return () => {
+      this.readyListeners.delete(listener);
+    };
+  }
+  onData(listener) {
+    this.dataListeners.add(listener);
+    return () => {
+      this.dataListeners.delete(listener);
+    };
+  }
+  onExit(listener) {
+    this.exitListeners.add(listener);
+    return () => {
+      this.exitListeners.delete(listener);
+    };
+  }
+  onError(listener) {
+    this.errorListeners.add(listener);
+    return () => {
+      this.errorListeners.delete(listener);
+    };
+  }
+  onClose(listener) {
+    this.closeListeners.add(listener);
+    return () => {
+      this.closeListeners.delete(listener);
+    };
+  }
+  sendInput(data) {
+    const payload = encodeTerminalInput(data);
+    this.sendFrame({
+      type: "input",
+      data: payload.data,
+      encoding: payload.encoding
+    });
+  }
+  resize(payload) {
+    this.sendFrame({
+      type: "resize",
+      cols: payload.cols,
+      rows: payload.rows
+    });
+  }
+  close() {
+    if (this.socket.readyState === WS_READY_STATE_CONNECTING) {
+      this.socket.addEventListener(
+        "open",
+        () => {
+          this.close();
+        },
+        { once: true }
+      );
+      return;
+    }
+    if (this.socket.readyState === WS_READY_STATE_OPEN) {
+      if (!this.closeSignalSent) {
+        this.closeSignalSent = true;
+        this.sendFrame({ type: "close" });
+      }
+      this.socket.close();
+      return;
+    }
+    if (this.socket.readyState !== WS_READY_STATE_CLOSED) {
+      this.socket.close();
+    }
+  }
+  async handleMessage(data) {
+    try {
+      if (typeof data === "string") {
+        const frame = parseProcessTerminalServerFrame(data);
+        if (!frame) {
+          this.emitError(new Error("Received invalid terminal control frame."));
+          return;
+        }
+        if (frame.type === "ready") {
+          for (const listener of this.readyListeners) {
+            listener(frame);
+          }
+          return;
+        }
+        if (frame.type === "exit") {
+          for (const listener of this.exitListeners) {
+            listener(frame);
+          }
+          return;
+        }
+        this.emitError(frame);
+        return;
+      }
+      const bytes = await decodeTerminalBytes(data);
+      for (const listener of this.dataListeners) {
+        listener(bytes);
+      }
+    } catch (error) {
+      this.emitError(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  sendFrame(frame) {
+    if (this.socket.readyState !== WS_READY_STATE_OPEN) {
+      return;
+    }
+    this.socket.send(JSON.stringify(frame));
+  }
+  emitError(error) {
+    for (const listener of this.errorListeners) {
+      listener(error);
+    }
+  }
+};
+var WS_READY_STATE_CONNECTING = 0;
+var WS_READY_STATE_OPEN = 1;
+var WS_READY_STATE_CLOSED = 3;
 var SandboxAgent = class _SandboxAgent {
   baseUrl;
   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();
@@ -405,9 +634,11 @@ var SandboxAgent = class _SandboxAgent {
     }
     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);
+    this.startHealthWait();
   }
   static async connect(options) {
     return new _SandboxAgent(options);
@@ -425,6 +656,7 @@ var SandboxAgent = class _SandboxAgent {
       token: handle.token,
       fetch: options.fetch,
       headers: options.headers,
+      waitForHealth: false,
       persist: options.persist,
       replayMaxEvents: options.replayMaxEvents,
       replayMaxChars: options.replayMaxChars
@@ -433,6 +665,8 @@ 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()];
@@ -484,12 +718,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);
@@ -507,7 +761,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);
@@ -517,15 +773,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()
@@ -533,7 +800,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`);
@@ -541,15 +933,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);
@@ -566,16 +1016,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 = {}) {
@@ -647,7 +1097,107 @@ 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
+    );
+  }
+  connectProcessTerminal(id, options = {}) {
+    return new ProcessTerminalSession(this.connectProcessTerminalWebSocket(id, options));
+  }
   async getLiveConnection(agent) {
+    await this.awaitHealthy();
     const existing = this.liveConnections.get(agent);
     if (existing) {
       return existing;
@@ -700,6 +1250,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;
@@ -708,6 +1259,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;
@@ -793,7 +1384,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;
@@ -801,6 +1393,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) {
@@ -830,6 +1425,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) {
@@ -853,7 +1506,75 @@ var SandboxAgent = class _SandboxAgent {
     }
     return url.toString();
   }
+  async requestHealth(options = {}) {
+    return this.requestJson("GET", `${API_PREFIX}/health`, {
+      signal: options.signal,
+      skipReadyWait: true
+    });
+  }
 };
+function parseProcessTerminalServerFrame(payload) {
+  try {
+    const parsed = JSON.parse(payload);
+    if (!isRecord(parsed) || typeof parsed.type !== "string") {
+      return null;
+    }
+    if (parsed.type === "ready" && typeof parsed.processId === "string") {
+      return parsed;
+    }
+    if (parsed.type === "exit" && (parsed.exitCode === void 0 || parsed.exitCode === null || typeof parsed.exitCode === "number")) {
+      return parsed;
+    }
+    if (parsed.type === "error" && typeof parsed.message === "string") {
+      return parsed;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function encodeTerminalInput(data) {
+  if (typeof data === "string") {
+    return { data };
+  }
+  const bytes = encodeTerminalBytes(data);
+  return {
+    data: bytesToBase64(bytes),
+    encoding: "base64"
+  };
+}
+function encodeTerminalBytes(data) {
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+}
+async function decodeTerminalBytes(data) {
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+  }
+  if (typeof Blob !== "undefined" && data instanceof Blob) {
+    return new Uint8Array(await data.arrayBuffer());
+  }
+  throw new Error(`Unsupported terminal frame payload: ${String(data)}`);
+}
+function bytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  if (typeof btoa === "function") {
+    let binary = "";
+    const chunkSize = 32768;
+    for (let index = 0; index < bytes.length; index += chunkSize) {
+      binary += String.fromCharCode(...bytes.subarray(index, index + chunkSize));
+    }
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoding is not available in this environment.");
+}
 async function autoAuthenticate(acp, methods) {
   const envBased = methods.find(
     (m) => m.id === "codex-api-key" || m.id === "openai-api-key" || m.id === "anthropic-api-key"
@@ -866,6 +1587,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 {
@@ -973,6 +1703,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 };
@@ -996,9 +1740,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) {
@@ -1014,12 +2031,16 @@ function buildInspectorUrl(options) {
   return `${normalized}/ui/${queryString ? `?${queryString}` : ""}`;
 }
 export {
-  AcpRpcError,
+  AcpRpcError2 as AcpRpcError,
   InMemorySessionPersistDriver,
   LiveAcpConnection,
+  ProcessTerminalSession,
   SandboxAgent,
   SandboxAgentError,
   Session,
+  UnsupportedSessionCategoryError,
+  UnsupportedSessionConfigOptionError,
+  UnsupportedSessionValueError,
   buildInspectorUrl
 };
 //# sourceMappingURL=index.js.map