@opengeni/sdk 0.11.0 → 0.15.0

package/dist/index.js

@@ -9,6 +9,16 @@ var OpenGeniApiError = class extends Error {
     this.body = body;
   }
 };
+var OpenGeniApiContractMismatchError = class extends Error {
+  expected;
+  actual;
+  constructor(expected, actual) {
+    super(`OpenGeni API contract mismatch: client expects ${expected}, API serves ${actual}`);
+    this.name = "OpenGeniApiContractMismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
 var OpenGeniStreamError = class extends Error {
   constructor(message) {
     super(message);
@@ -105,7 +115,8 @@ async function* streamSessionEvents(transport, options = {}) {
   let failedAttempts = 0;
   let delayMs = baseDelayMs;
   let everConnected = false;
-  while (!signal?.aborted) {
+  while (true) {
+    if (signal?.aborted) break;
     options.onStateChange?.(everConnected || failedAttempts > 0 ? "reconnecting" : "connecting");
     const cursorAtOpen = cursor;
     try {
@@ -113,6 +124,7 @@ async function* streamSessionEvents(transport, options = {}) {
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
+      await options.beforeLive?.();
       options.onStateChange?.("live");
       for await (const message of parseSseStream(body)) {
         if (signal?.aborted) {
@@ -207,6 +219,246 @@ async function sleep(delayMs, signal) {
   });
 }
 
+// src/workspace-control-stream.ts
+async function* streamWorkspaceControlEvents(transport, options = {}) {
+  const signal = options.signal;
+  const reconnect = options.reconnect ?? true;
+  const baseDelayMs = options.reconnectDelayMs ?? 500;
+  const maxDelayMs = options.maxReconnectDelayMs ?? 1e4;
+  const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+  let cursor = options.after ?? 0;
+  let failures = 0;
+  let delayMs = baseDelayMs;
+  let everConnected = false;
+  for (; ; ) {
+    if (signal?.aborted) return;
+    options.onStateChange?.(everConnected || failures > 0 ? "reconnecting" : "connecting");
+    const cursorAtOpen = cursor;
+    try {
+      const body = await transport.openStream(cursor, signal);
+      everConnected = true;
+      failures = 0;
+      delayMs = baseDelayMs;
+      await options.beforeLive?.();
+      options.onStateChange?.("live");
+      for await (const message of parseSseStream(body)) {
+        if (signal?.aborted) return;
+        const event = parseWorkspaceControlEvent(message.data);
+        if (!event || event.sequence <= cursor) continue;
+        cursor = event.sequence;
+        yield event;
+      }
+      if (!reconnect) return;
+      if (cursor === cursorAtOpen) await sleep2(baseDelayMs, signal);
+      continue;
+    } catch (error) {
+      if (signal?.aborted || isAbortError(error)) return;
+      if (!reconnect || !isRetryableStreamError(error)) throw error;
+      failures += 1;
+      if (failures > maxAttempts) {
+        throw new OpenGeniStreamError(
+          `workspace control stream gave up after ${maxAttempts} reconnect attempts: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    await sleep2(delayMs, signal);
+    delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
+  }
+}
+function parseWorkspaceControlEvent(data) {
+  let value;
+  try {
+    value = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null || value.type !== "workspace.control.changed" || typeof value.id !== "string" || typeof value.sequence !== "number") {
+    return null;
+  }
+  return value;
+}
+async function sleep2(delayMs, signal) {
+  if (signal?.aborted || delayMs <= 0) return;
+  await new Promise((resolve) => {
+    const timer = setTimeout(done, delayMs);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+// src/types.ts
+var SESSION_EVENT_TYPES = [
+  "session.created",
+  "session.status.changed",
+  "session.requiresAction",
+  "session.context.compaction.requested",
+  "session.context.compacted",
+  "session.context.compaction.skipped",
+  "session.context.cleared",
+  "user.message",
+  "user.pause",
+  "user.approvalDecision",
+  "turn.queued",
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+  "turn.recovery.requested",
+  "turn.capacity_waiting",
+  "agent.message.delta",
+  "agent.message.completed",
+  "agent.reasoning.delta",
+  "agent.toolCall.created",
+  "agent.toolCall.output",
+  "agent.model.usage",
+  "tool.auth_needed",
+  "agent.updated",
+  "rig.setup.started",
+  "rig.setup.completed",
+  "rig.setup.skipped",
+  "rig.setup.failed",
+  "sandbox.operation.started",
+  "sandbox.operation.completed",
+  "sandbox.operation.failed",
+  "sandbox.command.output.delta",
+  "artifact.created",
+  "goal.set",
+  "goal.updated",
+  "goal.completed",
+  "goal.paused",
+  "goal.resumed",
+  "goal.cleared",
+  "goal.continuation",
+  "system.update.pending",
+  "system.update.delivered",
+  "session.control.paused",
+  "session.control.resumed",
+  "session.control.steer_requested",
+  "workspace.inference.paused",
+  "workspace.inference.resumed",
+  "session.queue.changed",
+  "session.queue.prompt.cancelled",
+  "session.queue.history",
+  "turn.event.rejected_late",
+  "memory.saved",
+  "memory.corrected",
+  // Channel-B desktop pixel-plane signals (mirror of contracts SessionEventType;
+  // the contract-parity test asserts sorted equality).
+  "stream.url.rotated",
+  "stream.opened",
+  "stream.closed",
+  "stream.revoked",
+  // Channel-B recording signals (P4.3 — "agent films itself proving the fix").
+  "recording.started",
+  "recording.available",
+  "recording.failed",
+  // Channel-A structured-service notifications (P4.4; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "fs.changed",
+  "git.changed",
+  "terminal.pty.started",
+  "terminal.pty.output.delta",
+  "terminal.pty.exited",
+  "session.title_set",
+  // Multi-account Codex (P1): the session's inference account changed.
+  "codex.account.switched",
+  // OPE-21 metadata-only per-turn credential selection audit.
+  "codex.credential.selected",
+  // OPE-21 durable zero-capacity wait lifecycle. These are system/runtime
+  // events, never synthetic user messages.
+  "codex.capacity.waiting",
+  "codex.capacity.resumed",
+  "codex.capacity.superseded",
+  // Sandbox durability observability (mirror of contracts SessionEventType):
+  // box lifecycle + manifest-env drift, attributable from the DB alone.
+  "sandbox.box.created",
+  "sandbox.box.lost",
+  "sandbox.box.terminated",
+  "sandbox.box.snapshot",
+  "sandbox.env.drift",
+  // Active-sandbox pointer reconcile (issue #341; announce-only; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "session.route.reconciled",
+  // Workbench v2 turn-end workspace capture (announce-only; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "workspace.revision.captured",
+  "workspace.revision.degraded",
+  // Connected Machine op-outcome observability (announce-only, quiet; mirror of
+  // contracts SessionEventType — the contract-parity test asserts sorted equality).
+  "machine.op.failed",
+  "machine.op.recovered",
+  // Connected Machine link-plane observability (announce-only, quiet; mirror of
+  // contracts SessionEventType — the contract-parity test asserts sorted equality).
+  "machine.link.lost",
+  "machine.link.restored",
+  "machine.runner.restarted"
+];
+var KNOWN_PERMISSIONS = [
+  "account:read",
+  "account:admin",
+  "members:manage",
+  "workspace:create",
+  "billing:read",
+  "billing:manage",
+  "workspace:read",
+  "workspace:admin",
+  "sessions:create",
+  "sessions:read",
+  "sessions:control",
+  // Sandbox-surfacing (mirror of @opengeni/contracts Permission). stream:view is
+  // strictly broader than sessions:read (un-redacted pixels); stream:control is
+  // the never-granted-v1 raw-input plane; stream:acknowledge is the secret-leak
+  // consent gate.
+  "stream:view",
+  "stream:control",
+  "stream:acknowledge",
+  "files:upload",
+  "files:read",
+  "files:write",
+  "terminal:attach",
+  "documents:manage",
+  "documents:search",
+  "scheduled_tasks:manage",
+  "scheduled_tasks:run",
+  "github:manage",
+  "github:use",
+  "api_keys:manage",
+  "connections:read",
+  "connections:write",
+  "environments:manage",
+  "environments:use",
+  "variable-sets:manage",
+  "variable-sets:use",
+  "mcp_servers:attach",
+  "toolspace:call",
+  "goals:manage",
+  "enrollments:read",
+  "enrollments:manage",
+  "rigs:use",
+  "rigs:manage"
+];
+var OPENGENI_API_CONTRACT_REVISION = "2026-07-session-control-v1";
+var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
+var KNOWN_USAGE_EVENT_TYPES = [
+  "agent_run.created",
+  "agent_run.completed",
+  "model.tokens",
+  "model.cost",
+  "file.uploaded",
+  "file.deleted",
+  "document.indexed",
+  "scheduled_task.fired",
+  "api_key.request",
+  // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
+  "sandbox.warm_seconds",
+  "sandbox.warm_cost"
+];
+
 // src/client.ts
 var OpenGeniClient = class {
   baseUrl;
@@ -219,23 +471,79 @@ var OpenGeniClient = class {
   }
   // --- Session lifecycle ---------------------------------------------------
   async createSession(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions`,
+      request
+    );
   }
   async getSession(workspaceId, sessionId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}`
+    );
   }
   async updateSession(workspaceId, sessionId, request) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/sessions/${sessionId}`, request);
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}`,
+      request
+    );
   }
   async listSessions(workspaceId, options = {}) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/sessions`, void 0, {
-      ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions`,
+      void 0,
+      {
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+        ...options.search?.trim() ? { search: options.search.trim() } : {},
+        ...Object.prototype.hasOwnProperty.call(options, "parentSessionId") && options.parentSessionId !== void 0 ? {
+          parentSessionId: options.parentSessionId === null ? "null" : String(options.parentSessionId)
+        } : {}
+      }
+    );
+  }
+  /** Pin-aware ordinary-session page with a stable keyset cursor. */
+  async listSessionPage(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions`,
+      void 0,
+      {
+        view: "page",
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+        ...options.cursor !== void 0 ? { cursor: options.cursor } : {},
+        ...options.search?.trim() ? { search: options.search.trim() } : {},
+        ...Object.prototype.hasOwnProperty.call(options, "parentSessionId") && options.parentSessionId !== void 0 ? {
+          parentSessionId: options.parentSessionId === null ? "null" : String(options.parentSessionId)
+        } : {}
+      }
+    );
+  }
+  /** Set this authenticated member's personal workspace pin for a session. */
+  async updateSessionPin(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/pin`,
+      request
+    );
+  }
+  async getSessionLineage(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/lineage`
+    );
   }
   async listTurns(workspaceId, sessionId, options = {}) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns`, void 0, {
-      ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns`,
+      void 0,
+      {
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }
+    );
   }
   // --- Bring-your-own-compute: Machines dashboard + metrics (M10) ------------
   /**
@@ -245,9 +553,14 @@ var OpenGeniClient = class {
    * session's synthetic Modal group box + the active-sandbox pointer.
    */
   async listMachines(workspaceId, options = {}) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/machines`, void 0, {
-      ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/machines`,
+      void 0,
+      {
+        ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
+      }
+    );
   }
   /**
    * Read the downsampled (~1/min) metrics series for ONE machine over a time
@@ -273,7 +586,11 @@ var OpenGeniClient = class {
    * the request.
    */
   async lookupDeviceEnrollment(userCode) {
-    return await this.requestJson("POST", "/v1/enrollments/device/lookup", { userCode });
+    return await this.requestJson(
+      "POST",
+      "/v1/enrollments/device/lookup",
+      { userCode }
+    );
   }
   /**
    * Approve a pending device-enrollment flow (the LOUD consent step). `allowScreenControl`
@@ -325,12 +642,20 @@ var OpenGeniClient = class {
   }
   // --- Scheduled tasks -------------------------------------------------------
   async listScheduledTasks(workspaceId, options = {}) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/scheduled-tasks`, void 0, {
-      ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      void 0,
+      {
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }
+    );
   }
   async getScheduledTask(workspaceId, taskId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`
+    );
   }
   // --- Events: replay, send, stream ----------------------------------------
   /**
@@ -340,16 +665,25 @@ var OpenGeniClient = class {
    * for resume cursors.
    */
   async listEvents(workspaceId, sessionId, options = {}) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, void 0, {
-      ...options.after !== void 0 ? { after: String(options.after) } : {},
-      ...options.before !== void 0 ? { before: String(options.before) } : {},
-      ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
-      ...options.compact ? { compact: "1" } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
+      void 0,
+      {
+        ...options.after !== void 0 ? { after: String(options.after) } : {},
+        ...options.before !== void 0 ? { before: String(options.before) } : {},
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+        ...options.compact ? { compact: "1" } : {}
+      }
+    );
   }
   /** POST a user/control event to the session. Returns the accepted event. */
   async sendEvent(workspaceId, sessionId, event) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, event);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`,
+      event
+    );
   }
   async sendMessage(workspaceId, sessionId, message) {
     const input = typeof message === "string" ? { text: message } : message;
@@ -360,11 +694,12 @@ var OpenGeniClient = class {
       payload
     });
   }
-  async interrupt(workspaceId, sessionId, options = {}) {
-    return await this.sendEvent(workspaceId, sessionId, {
-      type: "user.interrupt",
-      ...options.clientEventId !== void 0 ? { clientEventId: options.clientEventId } : {},
-      payload: options.reason !== void 0 ? { reason: options.reason } : {}
+  async pauseSession(workspaceId, sessionId, options = {}) {
+    return await this.controlSession(workspaceId, sessionId, {
+      action: "pause",
+      clientEventId: options.clientEventId ?? crypto.randomUUID(),
+      ...options.reason ? { reason: options.reason } : {},
+      ...options.expectedControlEtag ? { expectedControlEtag: options.expectedControlEtag } : {}
     });
   }
   async sendApprovalDecision(workspaceId, sessionId, decision) {
@@ -386,7 +721,10 @@ var OpenGeniClient = class {
   /** The transport `streamEvents` runs on; useful for custom streaming layers. */
   eventStreamTransport(workspaceId, sessionId) {
     return {
-      openStream: async (after, signal) => await this.openEventStream(workspaceId, sessionId, { after, ...signal ? { signal } : {} }),
+      openStream: async (after, signal) => await this.openEventStream(workspaceId, sessionId, {
+        after,
+        ...signal ? { signal } : {}
+      }),
       listEvents: async (after, limit) => await this.listEvents(workspaceId, sessionId, { after, limit })
     };
   }
@@ -400,6 +738,7 @@ var OpenGeniClient = class {
       headers: { ...this.headers(), Accept: "text/event-stream" },
       ...options.signal ? { signal: options.signal } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -409,87 +748,144 @@ var OpenGeniClient = class {
     return response.body;
   }
   // --- Turn queue ------------------------------------------------------------
-  /** Edit a still-queued turn (prompt, model, resources, tools, ...). */
-  async updateQueuedTurn(workspaceId, sessionId, turnId, update) {
+  async getQueue(workspaceId, sessionId) {
     return await this.requestJson(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/${turnId}`,
-      update
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`
     );
   }
-  /**
-   * Reorder the queued turns. `turnIds` must all reference queued turns; the
-   * server assigns positions in the given order and returns the queue.
-   */
-  async reorderQueuedTurns(workspaceId, sessionId, turnIds) {
+  async moveQueueItem(workspaceId, sessionId, turnId, request) {
     return await this.requestJson(
       "POST",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/reorder`,
-      { turnIds }
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/move`,
+      request
     );
   }
-  /** Cancel a queued turn before it is claimed. Returns the cancelled turn. */
-  async deleteQueuedTurn(workspaceId, sessionId, turnId) {
+  async editQueueItem(workspaceId, sessionId, turnId, request) {
     return await this.requestJson(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/${turnId}`
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/edit`,
+      request
     );
   }
-  /**
-   * Steer: deliver a message *now* instead of behind the queue. Sends the
-   * message, promotes its queued turn to the front, and interrupts the
-   * running turn so the session picks the steer turn up next. On a session
-   * that is not running this degrades gracefully to a plain queued message.
-   *
-   * The steer turn is located by `triggerEventId` across ALL turns (retried
-   * briefly in case the server is still materializing it) — not just the
-   * queued ones, because the worker can claim the steer turn before it is
-   * ever observed queued, and a claimed steer turn means the message is
-   * already being delivered: interrupting then would cancel the very message
-   * being steered. If the turn cannot be found while other turns are queued,
-   * the interrupt is also skipped — stopping the running turn would otherwise
-   * promote someone else's queued work over this message — and the call
-   * degrades to a plain queued send (`interrupted: false`).
-   */
-  async steerMessage(workspaceId, sessionId, message) {
-    const accepted = await this.sendMessage(workspaceId, sessionId, message);
-    let steerTurn = null;
-    let queued = [];
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-      if (attempt > 0) {
-        await delay(150 * attempt);
-      }
-      const turns = await this.listTurns(workspaceId, sessionId);
-      queued = turns.filter((turn) => turn.status === "queued").sort((a, b) => a.position - b.position || a.createdAt.localeCompare(b.createdAt));
-      steerTurn = turns.find((turn) => turn.triggerEventId === accepted.id) ?? null;
-      if (steerTurn) {
-        break;
-      }
-    }
-    const steerTurnQueued = steerTurn?.status === "queued";
-    if (steerTurn && steerTurnQueued && queued.length > 1) {
-      const front = steerTurn;
-      await this.reorderQueuedTurns(workspaceId, sessionId, [
-        front.id,
-        ...queued.filter((turn) => turn.id !== front.id).map((turn) => turn.id)
-      ]);
-    }
-    const canDeliverNext = steerTurnQueued || steerTurn === null && queued.length === 0;
-    const session = await this.getSession(workspaceId, sessionId);
-    const steerTurnAlreadyActive = steerTurn !== null && session.activeTurnId === steerTurn.id;
-    const interrupted = canDeliverNext && !steerTurnAlreadyActive && (session.status === "running" || session.status === "requires_action");
-    if (interrupted) {
-      await this.interrupt(workspaceId, sessionId, { reason: "steer" });
-    }
-    return { accepted, turn: steerTurn, interrupted };
-  }
-  // --- Goals -------------------------------------------------------------------
-  /** The session's goal. 404s when the session never had one. */
-  async getGoal(workspaceId, sessionId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`);
-  }
-  async updateGoal(workspaceId, sessionId, request) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`, request);
+  async steerQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/steer`,
+      request
+    );
+  }
+  async deleteQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/delete`,
+      request
+    );
+  }
+  async getComposerDraft(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`
+    );
+  }
+  async saveComposerDraft(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/composer-draft`,
+      request
+    );
+  }
+  async controlSession(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/control`,
+      request
+    );
+  }
+  async resumeSession(workspaceId, sessionId, options = {}) {
+    return await this.controlSession(workspaceId, sessionId, {
+      action: "resume",
+      clientEventId: options.clientEventId ?? crypto.randomUUID(),
+      ...options.reason ? { reason: options.reason } : {},
+      ...options.expectedControlEtag ? { expectedControlEtag: options.expectedControlEtag } : {}
+    });
+  }
+  async setWorkspaceInferenceState(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/inference-control`,
+      request
+    );
+  }
+  async listWorkspaceControlEvents(workspaceId, options = {}) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/control-events`,
+      void 0,
+      {
+        ...options.after !== void 0 ? { after: String(options.after) } : {},
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
+      }
+    );
+  }
+  streamWorkspaceControlEvents(workspaceId, options = {}) {
+    return streamWorkspaceControlEvents(this.workspaceControlStreamTransport(workspaceId), options);
+  }
+  workspaceControlStreamTransport(workspaceId) {
+    return {
+      openStream: async (after, signal) => await this.openWorkspaceControlEventStream(workspaceId, {
+        after,
+        ...signal ? { signal } : {}
+      })
+    };
+  }
+  async openWorkspaceControlEventStream(workspaceId, options = {}) {
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/control-events/stream`, {
+        after: String(options.after ?? 0)
+      }),
+      {
+        method: "GET",
+        headers: { ...this.headers(), Accept: "text/event-stream" },
+        ...options.signal ? { signal: options.signal } : {}
+      }
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    if (!response.body) {
+      throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
+    }
+    return response.body;
+  }
+  /**
+   * Steer: atomically put this prompt at the head and supersede the current
+   * inference. The client performs one request and renders server order.
+   */
+  async steerMessage(workspaceId, sessionId, message) {
+    const input = typeof message === "string" ? { text: message } : message;
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/steer`,
+      input
+    );
+  }
+  // --- Goals -------------------------------------------------------------------
+  /** The session's goal. 404s when the session never had one. */
+  async getGoal(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`
+    );
+  }
+  async updateGoal(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`,
+      request
+    );
+  }
+  async deleteGoal(workspaceId, sessionId) {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`);
   }
   /** Pause the goal loop: the session stops self-continuing until resumed. */
   async pauseGoal(workspaceId, sessionId, options = {}) {
@@ -511,16 +907,19 @@ var OpenGeniClient = class {
    * context — the destructive intent is explicit on the wire.
    */
   async clearSessionContext(workspaceId, sessionId) {
-    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/clear`, { confirm: true });
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/clear`,
+      { confirm: true }
+    );
   }
-  /**
-   * Trigger conversation compaction now. On the client-managed (Azure) path this
-   * queues a forced compaction the worker honors before the next turn
-   * (`status:"queued"`); on a server-managed provider or when compaction is off
-   * it is a no-op (`status:"noop"`) with an explanatory message.
-   */
+  /** Request one durable portable compaction at the next safe model boundary. */
   async compactSessionContext(workspaceId, sessionId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/compact`, {});
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/compact`,
+      {}
+    );
   }
   // --- Channel-A structured services (P4.4) ------------------------------------
   // FileSystem (Pierre tree), Git (Pierre diff), Terminal (exec + PTY). Each is a
@@ -528,64 +927,147 @@ var OpenGeniClient = class {
   // notifications + the PTY output stream arrive on the existing event SSE.
   /** FileSystem: list a directory tree (feeds the Pierre file tree). */
   async fsList(workspaceId, sessionId, request = {}) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`,
+      request
+    );
   }
   /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
   async fsRead(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`,
+      request
+    );
   }
   /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
   async fsWrite(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/write`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/write`,
+      request
+    );
   }
   /** FileSystem: delete a path (emits fs.changed). */
   async fsDelete(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/delete`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/delete`,
+      request
+    );
   }
   /** FileSystem: move/rename a path (emits fs.changed; 409 if destination exists and overwrite is false). */
   async fsMove(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/move`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/move`,
+      request
+    );
   }
   /** FileSystem: create a directory (emits fs.changed; recursive defaults to true). */
   async fsMkdir(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/mkdir`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/mkdir`,
+      request
+    );
   }
   /** Git: working-tree/index status (the Pierre file-status feed). */
   async gitStatus(workspaceId, sessionId, request = {}) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`,
+      request
+    );
   }
   /** Git: structured diff hunks (the Pierre diff feed). */
   async gitDiff(workspaceId, sessionId, request = {}) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`,
+      request
+    );
   }
   /** Git: commit log. */
   async gitLog(workspaceId, sessionId, request = {}) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/log`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/log`,
+      request
+    );
   }
   /** Git: show a commit (diff vs first parent) or fetch a raw blob at a ref. */
   async gitShow(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/show`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/show`,
+      request
+    );
+  }
+  /** Workspace capture: the latest turn-end snapshot of the session's workspace
+   *  (tree + per-repo diff + file after-image refs), served from durable storage
+   *  WITHOUT warming a machine — the workbench cold-paint source. Returns
+   *  `{available:false}` when no capture exists yet (fall back to the live path). */
+  async getWorkspaceCapture(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture`
+    );
+  }
+  /** Workspace capture: a single file's after-image from the capture (revision
+   *  pins a specific one; omitted → latest). Content is inline for small files,
+   *  else a short-TTL signed URL; a tooLarge file returns metadata only. */
+  async getWorkspaceCaptureFile(workspaceId, sessionId, path, revision) {
+    const query = { path };
+    if (revision !== void 0) query.revision = String(revision);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/workspace/capture/file`,
+      void 0,
+      query
+    );
   }
   /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
   async terminalExec(workspaceId, sessionId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/exec`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/exec`,
+      request
+    );
   }
   /** Terminal: open an interactive PTY. Output streams on the event SSE as
    *  terminal.pty.output.delta; drive it with terminalPtyWrite. */
   async terminalPtyOpen(workspaceId, sessionId, request = {}) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty`,
+      request
+    );
   }
   /** Terminal: send stdin to an open PTY (output rides A1). */
   async terminalPtyWrite(workspaceId, sessionId, request) {
-    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/write`, request);
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/write`,
+      request
+    );
   }
   /** Terminal: resize an open PTY. */
   async terminalPtyResize(workspaceId, sessionId, request) {
-    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/resize`, request);
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/resize`,
+      request
+    );
   }
   /** Terminal: close an open PTY (idempotent). */
   async terminalPtyClose(workspaceId, sessionId, request) {
-    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/close`, request);
+    await this.requestVoid(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/close`,
+      request
+    );
   }
   // --- Stream surfacing: capability negotiation + viewer lifecycle (Phase 5) ---
   // The capability doc is the single source of UI truth (degradation is always a
@@ -641,7 +1123,10 @@ var OpenGeniClient = class {
   }
   /** Detach a viewer (delete this holder; idempotent delete-my-row). */
   async detachViewer(workspaceId, sessionId, viewerId) {
-    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}`);
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}`
+    );
   }
   // --- Access + workspaces -----------------------------------------------------
   /**
@@ -652,7 +1137,14 @@ var OpenGeniClient = class {
    * knowledge of the host setup; safe to call before any auth is established.
    */
   async getClientConfig() {
-    return await this.requestJson("GET", "/v1/config/client");
+    const config = await this.requestJson("GET", "/v1/config/client");
+    if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
+      throw new OpenGeniApiContractMismatchError(
+        OPENGENI_API_CONTRACT_REVISION,
+        String(config.apiContractRevision || "(missing)")
+      );
+    }
+    return config;
   }
   /** The caller's access context: subject, account + workspace grants, defaults. */
   async getAccessContext() {
@@ -680,7 +1172,10 @@ var OpenGeniClient = class {
   // --- Members ("People with access") -------------------------------------------
   /** The workspace's members (user + api_key subjects). */
   async listWorkspaceMembers(workspaceId) {
-    const response = await this.requestJson("GET", `/v1/workspaces/${workspaceId}/members`);
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/members`
+    );
     return response.members;
   }
   /**
@@ -688,7 +1183,11 @@ var OpenGeniClient = class {
    * exists (email invites for unknown users are deferred).
    */
   async addWorkspaceMember(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/members`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/members`,
+      request
+    );
   }
   async updateWorkspaceMember(workspaceId, subjectId, request) {
     return await this.requestJson(
@@ -702,20 +1201,37 @@ var OpenGeniClient = class {
    * member who can still manage the workspace.
    */
   async removeWorkspaceMember(workspaceId, subjectId) {
-    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`);
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`
+    );
   }
   // --- Scheduled tasks (write + runs) -------------------------------------------
   async createScheduledTask(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/scheduled-tasks`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      request
+    );
   }
   async updateScheduledTask(workspaceId, taskId, request) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`, request);
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
+      request
+    );
   }
   async pauseScheduledTask(workspaceId, taskId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/pause`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/pause`
+    );
   }
   async resumeScheduledTask(workspaceId, taskId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/resume`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/resume`
+    );
   }
   /**
    * Fire the task immediately (manual trigger), independent of its schedule.
@@ -730,7 +1246,10 @@ var OpenGeniClient = class {
     );
   }
   async deleteScheduledTask(workspaceId, taskId) {
-    await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`);
+    await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`
+    );
   }
   async listScheduledTaskRuns(workspaceId, taskId, options = {}) {
     return await this.requestJson(
@@ -740,45 +1259,178 @@ var OpenGeniClient = class {
       { ...options.limit !== void 0 ? { limit: String(options.limit) } : {} }
     );
   }
-  // --- Environments --------------------------------------------------------------
+  // --- VariableSets --------------------------------------------------------------
   // Variable values are write-only: reads return name/version metadata only.
-  async listEnvironments(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/environments`);
+  async listVariableSets(workspaceId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets`
+    );
   }
-  async createEnvironment(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/environments`, request);
+  async createVariableSet(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/variable-sets`,
+      request
+    );
   }
-  async getEnvironment(workspaceId, environmentId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/environments/${environmentId}`);
+  async getVariableSet(workspaceId, variableSetId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
+    );
   }
-  async updateEnvironment(workspaceId, environmentId, request) {
+  async updateVariableSet(workspaceId, variableSetId, request) {
     return await this.requestJson(
       "PATCH",
-      `/v1/workspaces/${workspaceId}/environments/${environmentId}`,
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
       request
     );
   }
-  async deleteEnvironment(workspaceId, environmentId) {
-    await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/environments/${environmentId}`);
+  async deleteVariableSet(workspaceId, variableSetId) {
+    await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`
+    );
   }
   /** Create or rotate a variable. The value never comes back on any read. */
-  async setEnvironmentVariable(workspaceId, environmentId, name, value) {
+  async setVariableSetVariable(workspaceId, variableSetId, name, value) {
     return await this.requestJson(
       "PUT",
-      `/v1/workspaces/${workspaceId}/environments/${environmentId}/variables/${encodeURIComponent(name)}`,
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
       { value }
     );
   }
-  async deleteEnvironmentVariable(workspaceId, environmentId, name) {
+  async deleteVariableSetVariable(workspaceId, variableSetId, name) {
     await this.requestJson(
       "DELETE",
-      `/v1/workspaces/${workspaceId}/environments/${environmentId}/variables/${encodeURIComponent(name)}`
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`
     );
   }
+  // --- Rigs ------------------------------------------------------------------
+  // Workspace-scoped, versioned sandbox machine definitions. rigs:use gates read
+  // + proposeRigChange; rigs:manage gates create / update / delete / activate.
+  async listRigs(workspaceId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/rigs`);
+  }
+  async createRig(workspaceId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/rigs`, request);
+  }
+  async getRig(workspaceId, rigId) {
+    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+  async updateRig(workspaceId, rigId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}`,
+      request
+    );
+  }
+  async deleteRig(workspaceId, rigId) {
+    await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+  async listRigVersions(workspaceId, rigId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions`
+    );
+  }
+  /** Roll the active version to an existing one (rollback / promote-activate). */
+  async activateRigVersion(workspaceId, rigId, versionId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions/${versionId}/activate`
+    );
+  }
+  async listRigChanges(workspaceId, rigId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`
+    );
+  }
+  /** Propose a change against the rig's active version (rigs:use). */
+  async proposeRigChange(workspaceId, rigId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+      request
+    );
+  }
+  async getRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}`
+    );
+  }
+  /**
+   * Re-run verification for a change (rigs:use). Verification is asynchronous:
+   * this returns the change immediately with status `verifying`; poll
+   * `getRigChange`/`listRigChanges` for the terminal outcome + logs.
+   */
+  async verifyRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/verify`
+    );
+  }
+  /**
+   * Promote a verified `definition_edit` change into a new active rig version
+   * (rigs:manage). Only valid once the change's verification passed; returns the
+   * newly minted version.
+   */
+  async promoteRigChange(workspaceId, rigId, changeId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/promote`
+    );
+  }
+  /**
+   * Re-run the active version's checks in a clean throwaway sandbox (rigs:use).
+   * Asynchronous — returns the version id being verified; the outcome lands on
+   * the version's audit trail.
+   */
+  async verifyRig(workspaceId, rigId) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/verify`
+    );
+  }
+  /** @deprecated use listVariableSets */
+  async listEnvironments(workspaceId) {
+    return await this.listVariableSets(workspaceId);
+  }
+  /** @deprecated use createVariableSet */
+  async createEnvironment(workspaceId, request) {
+    return await this.createVariableSet(workspaceId, request);
+  }
+  /** @deprecated use getVariableSet */
+  async getEnvironment(workspaceId, environmentId) {
+    return await this.getVariableSet(workspaceId, environmentId);
+  }
+  /** @deprecated use updateVariableSet */
+  async updateEnvironment(workspaceId, environmentId, request) {
+    return await this.updateVariableSet(workspaceId, environmentId, request);
+  }
+  /** @deprecated use deleteVariableSet */
+  async deleteEnvironment(workspaceId, environmentId) {
+    await this.deleteVariableSet(workspaceId, environmentId);
+  }
+  /** @deprecated use setVariableSetVariable */
+  async setEnvironmentVariable(workspaceId, environmentId, name, value) {
+    return await this.setVariableSetVariable(workspaceId, environmentId, name, value);
+  }
+  /** @deprecated use deleteVariableSetVariable */
+  async deleteEnvironmentVariable(workspaceId, environmentId, name) {
+    await this.deleteVariableSetVariable(workspaceId, environmentId, name);
+  }
   // --- Files -----------------------------------------------------------------------
   /** Step 1 of the upload flow: returns the pre-signed PUT target. */
   async beginFileUpload(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/files/uploads`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/uploads`,
+      request
+    );
   }
   /** Step 3 of the upload flow: server verifies the object and marks it ready. */
   async completeFileUpload(workspaceId, uploadId) {
@@ -819,28 +1471,51 @@ var OpenGeniClient = class {
     return await this.completeFileUpload(workspaceId, upload.uploadId);
   }
   async getFile(workspaceId, fileId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/files/${fileId}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/files/${fileId}`
+    );
   }
   /** Mint a short-lived signed download URL for a ready file. */
   async createFileDownloadUrl(workspaceId, fileId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/files/${fileId}/download-url`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/${fileId}/download-url`
+    );
   }
   // --- Documents ----------------------------------------------------------------------
   async createDocumentBase(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/document-bases`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+      request
+    );
   }
   async listDocumentBases(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/document-bases`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases`
+    );
   }
   async getDocumentBase(workspaceId, baseId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/document-bases/${baseId}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}`
+    );
   }
   /** Index an uploaded file into the base. The file must be `ready`. */
   async addDocument(workspaceId, baseId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+      request
+    );
   }
   async listDocuments(workspaceId, baseId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`
+    );
   }
   /** Retry indexing for a failed document. */
   async reindexDocument(workspaceId, baseId, documentId) {
@@ -867,7 +1542,11 @@ var OpenGeniClient = class {
     );
   }
   async searchKnowledge(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/knowledge/search`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/search`,
+      request
+    );
   }
   async listKnowledgeMemories(workspaceId, request = {}) {
     const params = new URLSearchParams();
@@ -877,16 +1556,53 @@ var OpenGeniClient = class {
     if (request.scope) params.set("scope", request.scope);
     if (request.limit) params.set("limit", String(request.limit));
     const query = params.toString();
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`
+    );
   }
   async getKnowledgeMemory(workspaceId, memoryId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`
+    );
   }
   async createKnowledgeMemory(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/knowledge/memories`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories`,
+      request
+    );
   }
   async updateKnowledgeMemory(workspaceId, memoryId, request) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`, request);
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+      request
+    );
+  }
+  /** Hybrid (semantic + keyword) search over the workspace's agent-visible memory. */
+  async searchWorkspaceMemories(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/search`,
+      request
+    );
+  }
+  /** Deep-merge a settings patch into the workspace (preserves unknown keys). */
+  async updateWorkspaceSettings(workspaceId, request) {
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/settings`,
+      request
+    );
+  }
+  async setWorkspaceDefaultRig(workspaceId, request) {
+    return await this.requestJson(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/default-rig`,
+      request
+    );
   }
   // --- Capability packs ------------------------------------------------------------------
   /** Built-in + registered packs, with the workspace's installations. */
@@ -895,10 +1611,17 @@ var OpenGeniClient = class {
   }
   /** Register (or replace) a workspace-scoped pack from a manifest. */
   async registerPack(workspaceId, manifest) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/packs`, manifest);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/packs`,
+      manifest
+    );
   }
   async getPack(workspaceId, packId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`
+    );
   }
   async enablePack(workspaceId, packId, request = {}) {
     return await this.requestJson(
@@ -909,18 +1632,31 @@ var OpenGeniClient = class {
   }
   /** Unregister a workspace-scoped pack (built-in packs cannot be deleted). */
   async deletePack(workspaceId, packId) {
-    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`);
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`
+    );
   }
   async listPackInstallations(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/packs/installations`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/packs/installations`
+    );
   }
   // --- Capabilities -------------------------------------------------------------------------
   async listCapabilities(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/capabilities`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/capabilities`
+    );
   }
   /** Add a manual capability catalog item (e.g. a remote MCP server). */
   async createCapability(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/capabilities`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/capabilities`,
+      request
+    );
   }
   async enableCapability(workspaceId, capabilityId, request = {}) {
     return await this.requestJson(
@@ -947,6 +1683,49 @@ var OpenGeniClient = class {
       }
     );
   }
+  // --- Connections -------------------------------------------------------------------------------
+  async listConnections(workspaceId) {
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connections`
+    );
+    return response.connections;
+  }
+  async createConnection(workspaceId, request) {
+    const response = await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections`,
+      request
+    );
+    return response.connection;
+  }
+  async updateConnection(workspaceId, connectionId, request) {
+    const response = await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/connections/${connectionId}`,
+      request
+    );
+    return response.connection;
+  }
+  async deleteConnection(workspaceId, connectionId) {
+    const response = await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/connections/${connectionId}`
+    );
+    return response.connection;
+  }
+  /** Start an OAuth connection flow; redirect the user to the returned `authorizationUrl`. */
+  async startConnectionOAuth(workspaceId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/oauth/start`,
+      request
+    );
+  }
+  /** Public, immutably-cached URL for a catalog item's logo, or null when the item has none. */
+  catalogAssetUrl(logoAssetPath) {
+    return logoAssetPath ? `${this.baseUrl}/v1/${logoAssetPath}` : null;
+  }
   // --- GitHub ----------------------------------------------------------------------------------
   /** GitHub App configuration status + a signed install URL when configured. */
   async getGitHubApp(workspaceId) {
@@ -961,11 +1740,17 @@ var OpenGeniClient = class {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
   }
   async listGitHubRepositories(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/github/repositories`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/github/repositories`
+    );
   }
   /** Re-sync the installation's repository list from GitHub. */
   async syncGitHubRepositories(workspaceId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/github/repositories/sync`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/github/repositories/sync`
+    );
   }
   /** Build a GitHub App manifest + the GitHub URL to submit it to. */
   async createGitHubAppManifest(workspaceId, request = {}) {
@@ -977,16 +1762,26 @@ var OpenGeniClient = class {
   }
   // --- API keys ----------------------------------------------------------------------------------
   async listApiKeys(workspaceId) {
-    const response = await this.requestJson("GET", `/v1/workspaces/${workspaceId}/api-keys`);
+    const response = await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/api-keys`
+    );
     return response.apiKeys;
   }
   /** The returned `token` is shown once; only its prefix is stored. */
   async createApiKey(workspaceId, request) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/api-keys`, request);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/api-keys`,
+      request
+    );
   }
   /** Revoke an API key. Returns the revoked key. */
   async deleteApiKey(workspaceId, apiKeyId) {
-    return await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/api-keys/${apiKeyId}`);
+    return await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/api-keys/${apiKeyId}`
+    );
   }
   // --- Billing (account-scoped) --------------------------------------------------------------------
   async getBilling(options = {}) {
@@ -1001,9 +1796,14 @@ var OpenGeniClient = class {
     });
   }
   async getBillingEntitlements(options = {}) {
-    return await this.requestJson("GET", "/v1/billing/entitlements", void 0, {
-      ...options.accountId !== void 0 ? { accountId: options.accountId } : {}
-    });
+    return await this.requestJson(
+      "GET",
+      "/v1/billing/entitlements",
+      void 0,
+      {
+        ...options.accountId !== void 0 ? { accountId: options.accountId } : {}
+      }
+    );
   }
   /** Start a Stripe checkout for prepaid credits. */
   async createBillingCheckout(request) {
@@ -1014,7 +1814,8 @@ var OpenGeniClient = class {
     const extra = typeof this.options.headers === "function" ? this.options.headers() : this.options.headers;
     return {
       ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {},
-      ...extra
+      ...extra,
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION
     };
   }
   url(path, query = {}) {
@@ -1024,15 +1825,25 @@ var OpenGeniClient = class {
   // --- Codex (ChatGPT) subscription (workspace-scoped) --------------------------------------------
   /** Connection state + the codex models the workspace may select (empty until connected). */
   async codexStatus(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/codex/status`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/status`
+    );
   }
   /** Begin device-code login: show `userCode` at `verificationUri`, then poll with `state`. */
   async codexConnectStart(workspaceId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/codex/connect/start`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/connect/start`
+    );
   }
   /** Poll device-code authorization with the `state` from {@link codexConnectStart}. */
   async codexConnectPoll(workspaceId, state) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/codex/connect/poll`, { state });
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/connect/poll`,
+      { state }
+    );
   }
   /** Remaining usage / limits for the connected (ACTIVE) subscription. Back-compat. */
   async codexUsage(workspaceId) {
@@ -1040,39 +1851,69 @@ var OpenGeniClient = class {
   }
   /** Live per-account usage read (refreshes THIS account's bearer; writes the cache). */
   async codexAccountUsage(workspaceId, accountId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/usage`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/usage`
+    );
   }
   /** Batched live refresh across every connected account, keyed by credential id. */
   async refreshCodexUsage(workspaceId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/codex/usage/refresh`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/usage/refresh`
+    );
   }
   /** Disconnect ALL accounts (legacy workspace-wide). Prefer `disconnectCodexAccount`. */
   async codexDisconnect(workspaceId) {
-    return await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/codex`);
+    return await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/codex`
+    );
   }
   /** List every connected Codex account + the workspace active pointer + settings. */
   async listCodexAccounts(workspaceId) {
-    return await this.requestJson("GET", `/v1/workspaces/${workspaceId}/codex/accounts`);
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/codex/accounts`
+    );
   }
   /** Switch the workspace ACTIVE Codex account (the one unpinned sessions use). */
   async activateCodexAccount(workspaceId, accountId) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/activate`);
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}/activate`
+    );
   }
   /** P3: enable/disable Codex auto-rotation and/or pick the strategy. Returns the effective settings. */
   async setCodexRotationSettings(workspaceId, patch) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/codex/settings`, patch);
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/codex/settings`,
+      patch
+    );
   }
   /** Disconnect ONE Codex account by id (re-picks active when the removed one was active). */
   async disconnectCodexAccount(workspaceId, accountId) {
-    return await this.requestJson("DELETE", `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`);
+    return await this.requestJson(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`
+    );
   }
   /** Rename a Codex account (label only in P1). */
   async renameCodexAccount(workspaceId, accountId, label) {
-    return await this.requestJson("PATCH", `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`, { label });
+    return await this.requestJson(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/codex/accounts/${accountId}`,
+      { label }
+    );
   }
   /** Pin (or unpin via "auto") a session's Codex account. Applies on the next turn. */
   async pinSessionCodexAccount(workspaceId, sessionId, target) {
-    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/codex-account`, { target });
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/codex-account`,
+      { target }
+    );
   }
   async requestJson(method, path, body, query = {}) {
     const response = await this.fetchImpl(this.url(path, query), {
@@ -1084,6 +1925,7 @@ var OpenGeniClient = class {
       },
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
@@ -1100,11 +1942,18 @@ var OpenGeniClient = class {
       },
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     });
+    assertApiContractResponse(response);
     if (!response.ok) {
       throw new OpenGeniApiError(response.status, await safeText(response));
     }
   }
 };
+function assertApiContractResponse(response) {
+  const actual = response.headers.get(OPENGENI_API_CONTRACT_HEADER);
+  if (actual && actual !== OPENGENI_API_CONTRACT_REVISION) {
+    throw new OpenGeniApiContractMismatchError(OPENGENI_API_CONTRACT_REVISION, actual);
+  }
+}
 async function safeText(response) {
   try {
     return await response.text();
@@ -1112,9 +1961,6 @@ async function safeText(response) {
     return "";
   }
 }
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/proxy.ts
 function formatSseEvent(event) {
@@ -1298,120 +2144,12 @@ function ttydInputFrame(data) {
 function ttydResizeFrame(columns, rows) {
   return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
 }
-
-// src/types.ts
-var SESSION_EVENT_TYPES = [
-  "session.created",
-  "session.status.changed",
-  "session.requiresAction",
-  "session.context.compacted",
-  "session.context.cleared",
-  "user.message",
-  "user.interrupt",
-  "user.approvalDecision",
-  "turn.queued",
-  "turn.updated",
-  "turn.started",
-  "turn.completed",
-  "turn.failed",
-  "turn.cancelled",
-  "turn.preempted",
-  "agent.message.delta",
-  "agent.message.completed",
-  "agent.reasoning.delta",
-  "agent.toolCall.created",
-  "agent.toolCall.output",
-  "tool.auth_needed",
-  "agent.updated",
-  "sandbox.operation.started",
-  "sandbox.operation.completed",
-  "sandbox.operation.failed",
-  "sandbox.command.output.delta",
-  "artifact.created",
-  "goal.set",
-  "goal.updated",
-  "goal.completed",
-  "goal.paused",
-  "goal.resumed",
-  "goal.continuation",
-  // Channel-B desktop pixel-plane signals (mirror of contracts SessionEventType;
-  // the contract-parity test asserts sorted equality).
-  "stream.url.rotated",
-  "stream.opened",
-  "stream.closed",
-  "stream.revoked",
-  // Channel-B recording signals (P4.3 — "agent films itself proving the fix").
-  "recording.started",
-  "recording.available",
-  "recording.failed",
-  // Channel-A structured-service notifications (P4.4; mirror of contracts
-  // SessionEventType — the contract-parity test asserts sorted equality).
-  "fs.changed",
-  "git.changed",
-  "terminal.pty.started",
-  "terminal.pty.output.delta",
-  "terminal.pty.exited",
-  "session.title_set",
-  // Multi-account Codex (P1): the session's inference account changed.
-  "codex.account.switched"
-];
-var KNOWN_PERMISSIONS = [
-  "account:read",
-  "account:admin",
-  "members:manage",
-  "workspace:create",
-  "billing:read",
-  "billing:manage",
-  "workspace:read",
-  "workspace:admin",
-  "sessions:create",
-  "sessions:read",
-  "sessions:control",
-  // Sandbox-surfacing (mirror of @opengeni/contracts Permission). stream:view is
-  // strictly broader than sessions:read (un-redacted pixels); stream:control is
-  // the never-granted-v1 raw-input plane; stream:acknowledge is the secret-leak
-  // consent gate.
-  "stream:view",
-  "stream:control",
-  "stream:acknowledge",
-  "files:upload",
-  "files:read",
-  "files:write",
-  "terminal:attach",
-  "documents:manage",
-  "documents:search",
-  "scheduled_tasks:manage",
-  "scheduled_tasks:run",
-  "github:manage",
-  "github:use",
-  "api_keys:manage",
-  "connections:read",
-  "connections:write",
-  "environments:manage",
-  "environments:use",
-  "mcp_servers:attach",
-  "toolspace:call",
-  "goals:manage",
-  "enrollments:read",
-  "enrollments:manage"
-];
-var KNOWN_USAGE_EVENT_TYPES = [
-  "agent_run.created",
-  "agent_run.completed",
-  "model.tokens",
-  "model.cost",
-  "file.uploaded",
-  "file.deleted",
-  "document.indexed",
-  "scheduled_task.fired",
-  "api_key.request",
-  // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
-  "sandbox.warm_seconds",
-  "sandbox.warm_cost"
-];
 export {
   KNOWN_PERMISSIONS,
   KNOWN_USAGE_EVENT_TYPES,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  OpenGeniApiContractMismatchError,
   OpenGeniApiError,
   OpenGeniClient,
   OpenGeniStreamError,
@@ -1430,6 +2168,7 @@ export {
   sessionEventsToSseResponse,
   sessionEventsToSseStream,
   streamSessionEvents,
+  streamWorkspaceControlEvents,
   terminalSocketUrl,
   ttydAuthFrame,
   ttydInputFrame,