sandbox-agent 0.1.11 → 0.2.0

package/dist/index.js

@@ -1,5 +1,129 @@
+// src/client.ts
+import {
+  AcpHttpClient,
+  PROTOCOL_VERSION
+} from "acp-http-client";
+
+// src/types.ts
+var DEFAULT_MAX_SESSIONS = 1024;
+var DEFAULT_MAX_EVENTS_PER_SESSION = 500;
+var DEFAULT_LIST_LIMIT = 100;
+var InMemorySessionPersistDriver = class {
+  maxSessions;
+  maxEventsPerSession;
+  sessions = /* @__PURE__ */ new Map();
+  eventsBySession = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.maxSessions = normalizeCap(options.maxSessions, DEFAULT_MAX_SESSIONS);
+    this.maxEventsPerSession = normalizeCap(
+      options.maxEventsPerSession,
+      DEFAULT_MAX_EVENTS_PER_SESSION
+    );
+  }
+  async getSession(id) {
+    const session = this.sessions.get(id);
+    return session ? cloneSessionRecord(session) : null;
+  }
+  async listSessions(request = {}) {
+    const sorted = [...this.sessions.values()].sort((a, b) => {
+      if (a.createdAt !== b.createdAt) {
+        return a.createdAt - b.createdAt;
+      }
+      return a.id.localeCompare(b.id);
+    });
+    const page = paginate(sorted, request);
+    return {
+      items: page.items.map(cloneSessionRecord),
+      nextCursor: page.nextCursor
+    };
+  }
+  async updateSession(session) {
+    this.sessions.set(session.id, { ...session });
+    if (!this.eventsBySession.has(session.id)) {
+      this.eventsBySession.set(session.id, []);
+    }
+    if (this.sessions.size <= this.maxSessions) {
+      return;
+    }
+    const overflow = this.sessions.size - this.maxSessions;
+    const removable = [...this.sessions.values()].sort((a, b) => {
+      if (a.createdAt !== b.createdAt) {
+        return a.createdAt - b.createdAt;
+      }
+      return a.id.localeCompare(b.id);
+    }).slice(0, overflow).map((sessionToRemove) => sessionToRemove.id);
+    for (const sessionId of removable) {
+      this.sessions.delete(sessionId);
+      this.eventsBySession.delete(sessionId);
+    }
+  }
+  async listEvents(request) {
+    const all = [...this.eventsBySession.get(request.sessionId) ?? []].sort((a, b) => {
+      if (a.eventIndex !== b.eventIndex) {
+        return a.eventIndex - b.eventIndex;
+      }
+      return a.id.localeCompare(b.id);
+    });
+    const page = paginate(all, request);
+    return {
+      items: page.items.map(cloneSessionEvent),
+      nextCursor: page.nextCursor
+    };
+  }
+  async insertEvent(event) {
+    const events = this.eventsBySession.get(event.sessionId) ?? [];
+    events.push(cloneSessionEvent(event));
+    if (events.length > this.maxEventsPerSession) {
+      events.splice(0, events.length - this.maxEventsPerSession);
+    }
+    this.eventsBySession.set(event.sessionId, events);
+  }
+};
+function cloneSessionRecord(session) {
+  return {
+    ...session,
+    sessionInit: session.sessionInit ? JSON.parse(JSON.stringify(session.sessionInit)) : void 0
+  };
+}
+function cloneSessionEvent(event) {
+  return {
+    ...event,
+    payload: JSON.parse(JSON.stringify(event.payload))
+  };
+}
+function normalizeCap(value, fallback) {
+  if (!Number.isFinite(value) || (value ?? 0) < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+function paginate(items, request) {
+  const offset = parseCursor(request.cursor);
+  const limit = normalizeCap(request.limit, DEFAULT_LIST_LIMIT);
+  const slice = items.slice(offset, offset + limit);
+  const nextOffset = offset + slice.length;
+  return {
+    items: slice,
+    nextCursor: nextOffset < items.length ? String(nextOffset) : void 0
+  };
+}
+function parseCursor(cursor) {
+  if (!cursor) {
+    return 0;
+  }
+  const parsed = Number.parseInt(cursor, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return 0;
+  }
+  return parsed;
+}
+
 // src/client.ts
 var API_PREFIX = "/v1";
+var FS_PATH = `${API_PREFIX}/fs`;
+var DEFAULT_REPLAY_MAX_EVENTS = 50;
+var DEFAULT_REPLAY_MAX_CHARS = 12e3;
+var EVENT_INDEX_SCAN_EVENTS_LIMIT = 500;
 var SandboxAgentError = class extends Error {
   status;
   problem;
@@ -12,17 +136,246 @@ var SandboxAgentError = class extends Error {
     this.response = response;
   }
 };
+var Session = class {
+  record;
+  sandbox;
+  constructor(sandbox, record) {
+    this.sandbox = sandbox;
+    this.record = { ...record };
+  }
+  get id() {
+    return this.record.id;
+  }
+  get agent() {
+    return this.record.agent;
+  }
+  get agentSessionId() {
+    return this.record.agentSessionId;
+  }
+  get lastConnectionId() {
+    return this.record.lastConnectionId;
+  }
+  get createdAt() {
+    return this.record.createdAt;
+  }
+  get destroyedAt() {
+    return this.record.destroyedAt;
+  }
+  async refresh() {
+    const latest = await this.sandbox.getSession(this.id);
+    if (!latest) {
+      throw new Error(`session '${this.id}' no longer exists`);
+    }
+    this.apply(latest.toRecord());
+    return this;
+  }
+  async send(method, params = {}, options = {}) {
+    const updated = await this.sandbox.sendSessionMethod(this.id, method, params, options);
+    this.apply(updated.session.toRecord());
+    return updated.response;
+  }
+  async prompt(prompt) {
+    const response = await this.send("session/prompt", { prompt });
+    return response;
+  }
+  onEvent(listener) {
+    return this.sandbox.onSessionEvent(this.id, listener);
+  }
+  toRecord() {
+    return { ...this.record };
+  }
+  apply(record) {
+    this.record = { ...record };
+  }
+};
+var LiveAcpConnection = class _LiveAcpConnection {
+  connectionId;
+  agent;
+  acp;
+  sessionByLocalId = /* @__PURE__ */ new Map();
+  localByAgentSessionId = /* @__PURE__ */ new Map();
+  pendingNewSessionLocals = [];
+  pendingRequestSessionById = /* @__PURE__ */ new Map();
+  pendingReplayByLocalSessionId = /* @__PURE__ */ new Map();
+  onObservedEnvelope;
+  constructor(agent, connectionId, acp, onObservedEnvelope) {
+    this.agent = agent;
+    this.connectionId = connectionId;
+    this.acp = acp;
+    this.onObservedEnvelope = onObservedEnvelope;
+  }
+  static async create(options) {
+    const connectionId = randomId();
+    let live = null;
+    const acp = new AcpHttpClient({
+      baseUrl: options.baseUrl,
+      token: options.token,
+      fetch: options.fetcher,
+      headers: options.headers,
+      transport: {
+        path: `${API_PREFIX}/acp/${encodeURIComponent(options.serverId)}`,
+        bootstrapQuery: { agent: options.agent }
+      },
+      client: {
+        sessionUpdate: async (_notification) => {
+        }
+      },
+      onEnvelope: (envelope, direction) => {
+        if (!live) {
+          return;
+        }
+        live.handleEnvelope(envelope, direction);
+      }
+    });
+    live = new _LiveAcpConnection(options.agent, connectionId, acp, options.onObservedEnvelope);
+    const initResult = await acp.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientInfo: {
+        name: "sandbox-agent-sdk",
+        version: "v1"
+      }
+    });
+    if (initResult.authMethods && initResult.authMethods.length > 0) {
+      await autoAuthenticate(acp, initResult.authMethods);
+    }
+    return live;
+  }
+  async close() {
+    await this.acp.disconnect();
+  }
+  hasBoundSession(localSessionId, agentSessionId) {
+    const bound = this.sessionByLocalId.get(localSessionId);
+    if (!bound) {
+      return false;
+    }
+    if (agentSessionId && bound !== agentSessionId) {
+      return false;
+    }
+    return true;
+  }
+  bindSession(localSessionId, agentSessionId) {
+    this.sessionByLocalId.set(localSessionId, agentSessionId);
+    this.localByAgentSessionId.set(agentSessionId, localSessionId);
+  }
+  queueReplay(localSessionId, replayText) {
+    if (!replayText) {
+      this.pendingReplayByLocalSessionId.delete(localSessionId);
+      return;
+    }
+    this.pendingReplayByLocalSessionId.set(localSessionId, replayText);
+  }
+  async createRemoteSession(localSessionId, sessionInit) {
+    this.pendingNewSessionLocals.push(localSessionId);
+    try {
+      const response = await this.acp.newSession(sessionInit);
+      this.bindSession(localSessionId, response.sessionId);
+      return response;
+    } catch (error) {
+      const index = this.pendingNewSessionLocals.indexOf(localSessionId);
+      if (index !== -1) {
+        this.pendingNewSessionLocals.splice(index, 1);
+      }
+      throw error;
+    }
+  }
+  async sendSessionMethod(localSessionId, method, params, options) {
+    const agentSessionId = this.sessionByLocalId.get(localSessionId);
+    if (!agentSessionId) {
+      throw new Error(`session '${localSessionId}' is not bound to live ACP connection '${this.connectionId}'`);
+    }
+    const mappedParams = mapSessionParams(params, agentSessionId);
+    if (method === "session/prompt") {
+      const replayText = this.pendingReplayByLocalSessionId.get(localSessionId);
+      if (replayText) {
+        this.pendingReplayByLocalSessionId.delete(localSessionId);
+        injectReplayPrompt(mappedParams, replayText);
+      }
+      if (options.notification) {
+        await this.acp.extNotification(method, mappedParams);
+        return void 0;
+      }
+      return this.acp.prompt(mappedParams);
+    }
+    if (method === "session/cancel") {
+      await this.acp.cancel(mappedParams);
+      return void 0;
+    }
+    if (method === "session/set_mode") {
+      return this.acp.setSessionMode(mappedParams);
+    }
+    if (method === "session/set_config_option") {
+      return this.acp.setSessionConfigOption(mappedParams);
+    }
+    if (options.notification) {
+      await this.acp.extNotification(method, mappedParams);
+      return void 0;
+    }
+    return this.acp.extMethod(method, mappedParams);
+  }
+  handleEnvelope(envelope, direction) {
+    const localSessionId = this.resolveSessionId(envelope, direction);
+    this.onObservedEnvelope(this, envelope, direction, localSessionId);
+  }
+  resolveSessionId(envelope, direction) {
+    const id = envelopeId(envelope);
+    const method = envelopeMethod(envelope);
+    if (direction === "outbound") {
+      if (id && method === "session/new") {
+        const localSessionId = this.pendingNewSessionLocals.shift() ?? null;
+        if (localSessionId) {
+          this.pendingRequestSessionById.set(id, localSessionId);
+        }
+        return localSessionId;
+      }
+      const localFromParams = this.localFromEnvelopeParams(envelope);
+      if (id && localFromParams) {
+        this.pendingRequestSessionById.set(id, localFromParams);
+      }
+      return localFromParams;
+    }
+    if (id) {
+      const pending = this.pendingRequestSessionById.get(id) ?? null;
+      if (pending) {
+        this.pendingRequestSessionById.delete(id);
+        const sessionIdFromResult = envelopeSessionIdFromResult(envelope);
+        if (sessionIdFromResult) {
+          this.bindSession(pending, sessionIdFromResult);
+        }
+        return pending;
+      }
+    }
+    return this.localFromEnvelopeParams(envelope);
+  }
+  localFromEnvelopeParams(envelope) {
+    const agentSessionId = envelopeSessionIdFromParams(envelope);
+    if (!agentSessionId) {
+      return null;
+    }
+    return this.localByAgentSessionId.get(agentSessionId) ?? null;
+  }
+};
 var SandboxAgent = class _SandboxAgent {
   baseUrl;
   token;
   fetcher;
   defaultHeaders;
+  persist;
+  replayMaxEvents;
+  replayMaxChars;
   spawnHandle;
+  liveConnections = /* @__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(/\/$/, "");
     this.token = options.token;
     this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.defaultHeaders = options.headers;
+    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.");
     }
@@ -41,97 +394,167 @@ var SandboxAgent = class _SandboxAgent {
       baseUrl: handle.baseUrl,
       token: handle.token,
       fetch: options.fetch,
-      headers: options.headers
+      headers: options.headers,
+      persist: options.persist,
+      replayMaxEvents: options.replayMaxEvents,
+      replayMaxChars: options.replayMaxChars
     });
     client.spawnHandle = handle;
     return client;
   }
-  async listAgents() {
-    return this.requestJson("GET", `${API_PREFIX}/agents`);
-  }
-  async getHealth() {
-    return this.requestJson("GET", `${API_PREFIX}/health`);
-  }
-  async installAgent(agent, request = {}) {
-    await this.requestJson("POST", `${API_PREFIX}/agents/${encodeURIComponent(agent)}/install`, {
-      body: request
-    });
+  async dispose() {
+    const connections = [...this.liveConnections.values()];
+    this.liveConnections.clear();
+    await Promise.all(
+      connections.map(async (connection) => {
+        await connection.close();
+      })
+    );
+    if (this.spawnHandle) {
+      await this.spawnHandle.dispose();
+      this.spawnHandle = void 0;
+    }
   }
-  async getAgentModes(agent) {
-    return this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}/modes`);
+  async listSessions(request = {}) {
+    const page = await this.persist.listSessions(request);
+    return {
+      items: page.items.map((record) => this.upsertSessionHandle(record)),
+      nextCursor: page.nextCursor
+    };
+  }
+  async getSession(id) {
+    const record = await this.persist.getSession(id);
+    if (!record) {
+      return null;
+    }
+    return this.upsertSessionHandle(record);
   }
-  async getAgentModels(agent) {
-    return this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}/models`);
+  async getEvents(request) {
+    return this.persist.listEvents(request);
   }
-  async createSession(sessionId, request) {
-    return this.requestJson("POST", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}`, {
-      body: request
-    });
+  async createSession(request) {
+    if (!request.agent.trim()) {
+      throw new Error("createSession requires a non-empty agent");
+    }
+    const localSessionId = request.id?.trim() || randomId();
+    const live = await this.getLiveConnection(request.agent.trim());
+    const sessionInit = normalizeSessionInit(request.sessionInit);
+    const response = await live.createRemoteSession(localSessionId, sessionInit);
+    const record = {
+      id: localSessionId,
+      agent: request.agent.trim(),
+      agentSessionId: response.sessionId,
+      lastConnectionId: live.connectionId,
+      createdAt: nowMs(),
+      sessionInit
+    };
+    await this.persist.updateSession(record);
+    this.nextSessionEventIndexBySession.set(record.id, 1);
+    live.bindSession(record.id, record.agentSessionId);
+    return this.upsertSessionHandle(record);
+  }
+  async resumeSession(id) {
+    const existing = await this.persist.getSession(id);
+    if (!existing) {
+      throw new Error(`session '${id}' not found`);
+    }
+    const live = await this.getLiveConnection(existing.agent);
+    if (existing.lastConnectionId === live.connectionId && live.hasBoundSession(id, existing.agentSessionId)) {
+      return this.upsertSessionHandle(existing);
+    }
+    const replaySource = await this.collectReplayEvents(existing.id, this.replayMaxEvents);
+    const replayText = buildReplayText(replaySource, this.replayMaxChars);
+    const recreated = await live.createRemoteSession(existing.id, normalizeSessionInit(existing.sessionInit));
+    const updated = {
+      ...existing,
+      agentSessionId: recreated.sessionId,
+      lastConnectionId: live.connectionId,
+      destroyedAt: void 0
+    };
+    await this.persist.updateSession(updated);
+    live.bindSession(updated.id, updated.agentSessionId);
+    live.queueReplay(updated.id, replayText);
+    return this.upsertSessionHandle(updated);
+  }
+  async resumeOrCreateSession(request) {
+    const existing = await this.persist.getSession(request.id);
+    if (existing) {
+      return this.resumeSession(existing.id);
+    }
+    return this.createSession(request);
   }
-  async listSessions() {
-    return this.requestJson("GET", `${API_PREFIX}/sessions`);
+  async destroySession(id) {
+    const existing = await this.persist.getSession(id);
+    if (!existing) {
+      throw new Error(`session '${id}' not found`);
+    }
+    const updated = {
+      ...existing,
+      destroyedAt: nowMs()
+    };
+    await this.persist.updateSession(updated);
+    return this.upsertSessionHandle(updated);
+  }
+  async sendSessionMethod(sessionId, method, params, options = {}) {
+    const record = await this.persist.getSession(sessionId);
+    if (!record) {
+      throw new Error(`session '${sessionId}' not found`);
+    }
+    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);
+    }
+    const response = await live.sendSessionMethod(record.id, method, params, options);
+    const refreshed = await this.requireSessionRecord(record.id);
+    return {
+      session: this.upsertSessionHandle(refreshed),
+      response
+    };
+  }
+  onSessionEvent(sessionId, listener) {
+    const listeners = this.eventListeners.get(sessionId) ?? /* @__PURE__ */ new Set();
+    listeners.add(listener);
+    this.eventListeners.set(sessionId, listeners);
+    return () => {
+      const set = this.eventListeners.get(sessionId);
+      if (!set) {
+        return;
+      }
+      set.delete(listener);
+      if (set.size === 0) {
+        this.eventListeners.delete(sessionId);
+      }
+    };
   }
-  async postMessage(sessionId, request) {
-    await this.requestJson("POST", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/messages`, {
-      body: request
-    });
+  async getHealth() {
+    return this.requestJson("GET", `${API_PREFIX}/health`);
   }
-  async getEvents(sessionId, query) {
-    return this.requestJson("GET", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/events`, {
-      query
+  async listAgents(options) {
+    return this.requestJson("GET", `${API_PREFIX}/agents`, {
+      query: options?.config ? { config: "true" } : void 0
     });
   }
-  async getEventsSse(sessionId, query, signal) {
-    return this.requestRaw("GET", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/events/sse`, {
-      query,
-      accept: "text/event-stream",
-      signal
+  async getAgent(agent, options) {
+    return this.requestJson("GET", `${API_PREFIX}/agents/${encodeURIComponent(agent)}`, {
+      query: options?.config ? { config: "true" } : void 0
     });
   }
-  async postMessageStream(sessionId, request, query, signal) {
-    return this.requestRaw("POST", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/messages/stream`, {
-      query,
-      body: request,
-      accept: "text/event-stream",
-      signal
+  async installAgent(agent, request = {}) {
+    return this.requestJson("POST", `${API_PREFIX}/agents/${encodeURIComponent(agent)}/install`, {
+      body: request
     });
   }
-  async *streamEvents(sessionId, query, signal) {
-    const response = await this.getEventsSse(sessionId, query, signal);
-    yield* this.parseSseStream(response);
+  async listAcpServers() {
+    return this.requestJson("GET", `${API_PREFIX}/acp`);
   }
-  async *streamTurn(sessionId, request, query, signal) {
-    const response = await this.postMessageStream(sessionId, request, query, signal);
-    yield* this.parseSseStream(response);
-  }
-  async replyQuestion(sessionId, questionId, request) {
-    await this.requestJson(
-      "POST",
-      `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/questions/${encodeURIComponent(questionId)}/reply`,
-      { body: request }
-    );
-  }
-  async rejectQuestion(sessionId, questionId) {
-    await this.requestJson(
-      "POST",
-      `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/questions/${encodeURIComponent(questionId)}/reject`
-    );
-  }
-  async replyPermission(sessionId, permissionId, request) {
-    await this.requestJson(
-      "POST",
-      `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/permissions/${encodeURIComponent(permissionId)}/reply`,
-      { body: request }
-    );
-  }
-  async terminateSession(sessionId) {
-    await this.requestJson("POST", `${API_PREFIX}/sessions/${encodeURIComponent(sessionId)}/terminate`);
-  }
-  async listFsEntries(query) {
-    return this.requestJson("GET", `${API_PREFIX}/fs/entries`, { query });
+  async listFsEntries(query = {}) {
+    return this.requestJson("GET", `${FS_PATH}/entries`, {
+      query
+    });
   }
   async readFsFile(query) {
-    const response = await this.requestRaw("GET", `${API_PREFIX}/fs/file`, {
+    const response = await this.requestRaw("GET", `${FS_PATH}/file`, {
       query,
       accept: "application/octet-stream"
     });
@@ -139,69 +562,198 @@ var SandboxAgent = class _SandboxAgent {
     return new Uint8Array(buffer);
   }
   async writeFsFile(query, body) {
-    const response = await this.requestRaw("PUT", `${API_PREFIX}/fs/file`, {
+    const response = await this.requestRaw("PUT", `${FS_PATH}/file`, {
       query,
       rawBody: body,
       contentType: "application/octet-stream",
       accept: "application/json"
     });
-    const text = await response.text();
-    return text ? JSON.parse(text) : { path: "", bytesWritten: 0 };
+    return await response.json();
   }
   async deleteFsEntry(query) {
-    return this.requestJson("DELETE", `${API_PREFIX}/fs/entry`, { query });
+    return this.requestJson("DELETE", `${FS_PATH}/entry`, { query });
   }
   async mkdirFs(query) {
-    return this.requestJson("POST", `${API_PREFIX}/fs/mkdir`, { query });
+    return this.requestJson("POST", `${FS_PATH}/mkdir`, { query });
   }
-  async moveFs(request, query) {
-    return this.requestJson("POST", `${API_PREFIX}/fs/move`, { query, body: request });
+  async moveFs(request) {
+    return this.requestJson("POST", `${FS_PATH}/move`, { body: request });
   }
   async statFs(query) {
-    return this.requestJson("GET", `${API_PREFIX}/fs/stat`, { query });
+    return this.requestJson("GET", `${FS_PATH}/stat`, { query });
   }
   async uploadFsBatch(body, query) {
-    const response = await this.requestRaw("POST", `${API_PREFIX}/fs/upload-batch`, {
+    const response = await this.requestRaw("POST", `${FS_PATH}/upload-batch`, {
       query,
       rawBody: body,
       contentType: "application/x-tar",
       accept: "application/json"
     });
-    const text = await response.text();
-    return text ? JSON.parse(text) : { paths: [], truncated: false };
+    return await response.json();
   }
-  async dispose() {
-    if (this.spawnHandle) {
-      await this.spawnHandle.dispose();
-      this.spawnHandle = void 0;
+  async getMcpConfig(query) {
+    return this.requestJson("GET", `${API_PREFIX}/config/mcp`, { query });
+  }
+  async setMcpConfig(query, config) {
+    await this.requestRaw("PUT", `${API_PREFIX}/config/mcp`, { query, body: config });
+  }
+  async deleteMcpConfig(query) {
+    await this.requestRaw("DELETE", `${API_PREFIX}/config/mcp`, { query });
+  }
+  async getSkillsConfig(query) {
+    return this.requestJson("GET", `${API_PREFIX}/config/skills`, { query });
+  }
+  async setSkillsConfig(query, config) {
+    await this.requestRaw("PUT", `${API_PREFIX}/config/skills`, { query, body: config });
+  }
+  async deleteSkillsConfig(query) {
+    await this.requestRaw("DELETE", `${API_PREFIX}/config/skills`, { query });
+  }
+  async getLiveConnection(agent) {
+    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);
+      }
+    });
+    this.liveConnections.set(agent, created);
+    return created;
+  }
+  async persistObservedEnvelope(connection, envelope, direction, localSessionId) {
+    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);
+    const listeners = this.eventListeners.get(localSessionId);
+    if (!listeners || listeners.size === 0) {
+      return;
     }
+    for (const listener of listeners) {
+      listener(event);
+    }
+  }
+  async allocateSessionEventIndex(sessionId) {
+    await this.ensureSessionEventIndexSeeded(sessionId);
+    const nextIndex = this.nextSessionEventIndexBySession.get(sessionId) ?? 1;
+    this.nextSessionEventIndexBySession.set(sessionId, nextIndex + 1);
+    return nextIndex;
+  }
+  async ensureSessionEventIndexSeeded(sessionId) {
+    if (this.nextSessionEventIndexBySession.has(sessionId)) {
+      return;
+    }
+    if (!this.seedSessionEventIndexBySession.has(sessionId)) {
+      const pending2 = (async () => {
+        const maxPersistedIndex = await this.findMaxPersistedSessionEventIndex(sessionId);
+        this.nextSessionEventIndexBySession.set(sessionId, Math.max(1, maxPersistedIndex + 1));
+      })().finally(() => {
+        this.seedSessionEventIndexBySession.delete(sessionId);
+      });
+      this.seedSessionEventIndexBySession.set(sessionId, pending2);
+    }
+    const pending = this.seedSessionEventIndexBySession.get(sessionId);
+    if (pending) {
+      await pending;
+    }
+  }
+  async findMaxPersistedSessionEventIndex(sessionId) {
+    let maxIndex = 0;
+    let eventCursor;
+    while (true) {
+      const eventsPage = await this.persist.listEvents({
+        sessionId,
+        cursor: eventCursor,
+        limit: EVENT_INDEX_SCAN_EVENTS_LIMIT
+      });
+      for (const event of eventsPage.items) {
+        if (Number.isFinite(event.eventIndex) && event.eventIndex > maxIndex) {
+          maxIndex = Math.floor(event.eventIndex);
+        }
+      }
+      if (!eventsPage.nextCursor) {
+        break;
+      }
+      eventCursor = eventsPage.nextCursor;
+    }
+    return maxIndex;
+  }
+  async collectReplayEvents(sessionId, maxEvents) {
+    const all = [];
+    let cursor;
+    while (true) {
+      const page = await this.persist.listEvents({
+        sessionId,
+        cursor,
+        limit: Math.max(100, maxEvents)
+      });
+      all.push(...page.items);
+      if (!page.nextCursor) {
+        break;
+      }
+      cursor = page.nextCursor;
+    }
+    return all.slice(-maxEvents);
+  }
+  upsertSessionHandle(record) {
+    const existing = this.sessionHandles.get(record.id);
+    if (existing) {
+      existing.apply(record);
+      return existing;
+    }
+    const created = new Session(this, record);
+    this.sessionHandles.set(record.id, created);
+    return created;
+  }
+  async requireSessionRecord(id) {
+    const record = await this.persist.getSession(id);
+    if (!record) {
+      throw new Error(`session '${id}' not found`);
+    }
+    return record;
   }
   async requestJson(method, path, options = {}) {
     const response = await this.requestRaw(method, path, {
       query: options.query,
       body: options.body,
       headers: options.headers,
-      accept: options.accept ?? "application/json"
+      accept: options.accept ?? "application/json",
+      signal: options.signal
     });
     if (response.status === 204) {
       return void 0;
     }
-    const text = await response.text();
-    if (!text) {
-      return void 0;
-    }
-    return JSON.parse(text);
+    return await response.json();
   }
   async requestRaw(method, path, options = {}) {
     const url = this.buildUrl(path, options.query);
-    const headers = new Headers(this.defaultHeaders ?? void 0);
-    if (this.token) {
-      headers.set("Authorization", `Bearer ${this.token}`);
-    }
+    const headers = this.buildHeaders(options.headers);
     if (options.accept) {
       headers.set("Accept", options.accept);
     }
-    const init = { method, headers, signal: options.signal };
+    const init = {
+      method,
+      headers,
+      signal: options.signal
+    };
     if (options.rawBody !== void 0 && options.body !== void 0) {
       throw new Error("requestRaw received both rawBody and body");
     }
@@ -214,17 +766,24 @@ var SandboxAgent = class _SandboxAgent {
       headers.set("Content-Type", "application/json");
       init.body = JSON.stringify(options.body);
     }
-    if (options.headers) {
-      const extra = new Headers(options.headers);
-      extra.forEach((value, key) => headers.set(key, value));
-    }
     const response = await this.fetcher(url, init);
     if (!response.ok) {
-      const problem = await this.readProblem(response);
+      const problem = await readProblem(response);
       throw new SandboxAgentError(response.status, problem, response);
     }
     return response;
   }
+  buildHeaders(extra) {
+    const headers = new Headers(this.defaultHeaders ?? void 0);
+    if (this.token) {
+      headers.set("Authorization", `Bearer ${this.token}`);
+    }
+    if (extra) {
+      const merged = new Headers(extra);
+      merged.forEach((value, key) => headers.set(key, value));
+    }
+    return headers;
+  }
   buildUrl(path, query) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (query) {
@@ -237,55 +796,152 @@ var SandboxAgent = class _SandboxAgent {
     }
     return url.toString();
   }
-  async readProblem(response) {
-    try {
-      const text = await response.clone().text();
-      if (!text) {
-        return void 0;
-      }
-      return JSON.parse(text);
-    } catch {
-      return void 0;
-    }
+};
+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"
+  );
+  if (!envBased) {
+    return;
   }
-  async *parseSseStream(response) {
-    if (!response.body) {
-      throw new Error("SSE stream is not readable in this environment.");
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) {
-        break;
-      }
-      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
-      let index = buffer.indexOf("\n\n");
-      while (index !== -1) {
-        const chunk = buffer.slice(0, index);
-        buffer = buffer.slice(index + 2);
-        const dataLines = chunk.split("\n").filter((line) => line.startsWith("data:"));
-        if (dataLines.length > 0) {
-          const payload = dataLines.map((line) => line.slice(5).trim()).join("\n");
-          if (payload) {
-            yield JSON.parse(payload);
-          }
-        }
-        index = buffer.indexOf("\n\n");
-      }
+  try {
+    await acp.authenticate({ methodId: envBased.id });
+  } catch {
+  }
+}
+function normalizeSessionInit(value) {
+  if (!value) {
+    return {
+      cwd: defaultCwd(),
+      mcpServers: []
+    };
+  }
+  return {
+    ...value,
+    cwd: value.cwd ?? defaultCwd(),
+    mcpServers: value.mcpServers ?? []
+  };
+}
+function mapSessionParams(params, agentSessionId) {
+  return {
+    ...params,
+    sessionId: agentSessionId
+  };
+}
+function injectReplayPrompt(params, replayText) {
+  const prompt = Array.isArray(params.prompt) ? [...params.prompt] : [];
+  prompt.unshift({
+    type: "text",
+    text: replayText
+  });
+  params.prompt = prompt;
+}
+function buildReplayText(events, maxChars) {
+  if (events.length === 0) {
+    return null;
+  }
+  const prefix = "Previous session history is replayed below as JSON-RPC envelopes. Use it as context before responding to the latest user prompt.\n";
+  let text = prefix;
+  for (const event of events) {
+    const line = JSON.stringify({
+      createdAt: event.createdAt,
+      sender: event.sender,
+      payload: event.payload
+    });
+    if (text.length + line.length + 1 > maxChars) {
+      text += "\n[history truncated]";
+      break;
     }
+    text += `${line}
+`;
   }
-};
-var normalizeSpawnOptions = (spawn, defaultEnabled) => {
-  if (typeof spawn === "boolean") {
-    return { enabled: spawn };
+  return text;
+}
+function envelopeMethod(message) {
+  if (!isRecord(message) || !("method" in message) || typeof message["method"] !== "string") {
+    return null;
   }
-  if (spawn) {
-    return { enabled: spawn.enabled ?? defaultEnabled, ...spawn };
+  return message["method"];
+}
+function envelopeId(message) {
+  if (!isRecord(message) || !("id" in message) || message["id"] === void 0 || message["id"] === null) {
+    return null;
   }
-  return { enabled: defaultEnabled };
-};
+  return String(message["id"]);
+}
+function envelopeSessionIdFromParams(message) {
+  if (!isRecord(message) || !("params" in message) || !isRecord(message["params"])) {
+    return null;
+  }
+  const params = message["params"];
+  if (typeof params.sessionId === "string" && params.sessionId.length > 0) {
+    return params.sessionId;
+  }
+  return null;
+}
+function envelopeSessionIdFromResult(message) {
+  if (!isRecord(message) || !("result" in message) || !isRecord(message["result"])) {
+    return null;
+  }
+  const result = message["result"];
+  if (typeof result.sessionId === "string" && result.sessionId.length > 0) {
+    return result.sessionId;
+  }
+  return null;
+}
+function cloneEnvelope(envelope) {
+  return JSON.parse(JSON.stringify(envelope));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function randomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function nowMs() {
+  return Date.now();
+}
+function defaultCwd() {
+  if (typeof process !== "undefined" && typeof process.cwd === "function") {
+    return process.cwd();
+  }
+  return "/";
+}
+function normalizePositiveInt(value, fallback) {
+  if (!Number.isFinite(value) || (value ?? 0) < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+function normalizeSpawnOptions(spawn, defaultEnabled) {
+  if (spawn === false) {
+    return { enabled: false };
+  }
+  if (spawn === true || spawn === void 0) {
+    return { enabled: defaultEnabled };
+  }
+  return {
+    ...spawn,
+    enabled: spawn.enabled ?? defaultEnabled
+  };
+}
+async function readProblem(response) {
+  try {
+    const text = await response.clone().text();
+    if (!text) {
+      return void 0;
+    }
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/index.ts
+import { AcpRpcError } from "acp-http-client";
 
 // src/inspector.ts
 function buildInspectorUrl(options) {
@@ -301,8 +957,12 @@ function buildInspectorUrl(options) {
   return `${normalized}/ui/${queryString ? `?${queryString}` : ""}`;
 }
 export {
+  AcpRpcError,
+  InMemorySessionPersistDriver,
+  LiveAcpConnection,
   SandboxAgent,
   SandboxAgentError,
+  Session,
   buildInspectorUrl
 };
 //# sourceMappingURL=index.js.map