@opengeni/sdk 0.13.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);
@@ -114,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) {
@@ -208,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;
@@ -255,7 +506,7 @@ var OpenGeniClient = class {
   }
   /** Pin-aware ordinary-session page with a stable keyset cursor. */
   async listSessionPage(workspaceId, options = {}) {
-    const response = await this.requestJson(
+    return await this.requestJson(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       void 0,
@@ -269,16 +520,6 @@ var OpenGeniClient = class {
         } : {}
       }
     );
-    if (Array.isArray(response)) {
-      if (options.cursor) {
-        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
-      }
-      if (options.search?.trim()) {
-        throw new Error("The connected OpenGeni API does not support session search");
-      }
-      return { pinned: [], sessions: response, nextCursor: null };
-    }
-    return response;
   }
   /** Set this authenticated member's personal workspace pin for a session. */
   async updateSessionPin(workspaceId, sessionId, request) {
@@ -454,10 +695,12 @@ var OpenGeniClient = class {
     });
   }
   async pauseSession(workspaceId, sessionId, options = {}) {
-    return (await this.controlSession(workspaceId, sessionId, {
-      mode: "pause",
-      ...options
-    })).event;
+    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) {
     const { clientEventId, ...payload } = decision;
@@ -495,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));
     }
@@ -510,10 +754,44 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue`
     );
   }
-  async cancelQueueItem(workspaceId, sessionId, turnId, request) {
+  async moveQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/move`,
+      request
+    );
+  }
+  async editQueueItem(workspaceId, sessionId, turnId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/queue/${turnId}/edit`,
+      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}/cancel`,
+      `/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
     );
   }
@@ -525,7 +803,12 @@ var OpenGeniClient = class {
     );
   }
   async resumeSession(workspaceId, sessionId, options = {}) {
-    return await this.controlSession(workspaceId, sessionId, { mode: "resume", ...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(
@@ -534,13 +817,46 @@ var OpenGeniClient = class {
       request
     );
   }
-  /** Cancel a queued turn before it is claimed. Returns the cancelled turn. */
-  async deleteQueuedTurn(workspaceId, sessionId, turnId) {
+  async listWorkspaceControlEvents(workspaceId, options = {}) {
     return await this.requestJson(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/turns/${turnId}`
+      "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.
@@ -821,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() {
@@ -1491,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 = {}) {
@@ -1601,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));
     }
@@ -1617,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();
@@ -1812,175 +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.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.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 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,
@@ -1999,6 +2168,7 @@ export {
   sessionEventsToSseResponse,
   sessionEventsToSseStream,
   streamSessionEvents,
+  streamWorkspaceControlEvents,
   terminalSocketUrl,
   ttydAuthFrame,
   ttydInputFrame,