@opengeni/sdk 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {

package/src/client.ts

@@ -1,4 +1,8 @@
-import { OpenGeniApiContractMismatchError, OpenGeniApiError } from "./errors";
+import {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniSessionListCursorError,
+} from "./errors";
 import {
   streamSessionEvents,
   type SessionEventStreamTransport,
@@ -112,7 +116,9 @@ import type {
   DeleteSessionQueueItemRequest,
   EditSessionQueueItemRequest,
   MoveSessionQueueItemRequest,
+  NewSessionDraft,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   SteerSessionQueueItemRequest,
   SessionControlResponse,
   WorkspaceInferenceControlResponse,
@@ -193,6 +199,17 @@ import {
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
 } from "./types";
 
+function sessionListQuery(options: {
+  limit?: number;
+  parentSessionId?: string | null;
+}): Record<string, string> {
+  const { limit, parentSessionId } = options;
+  return {
+    ...(limit === undefined ? {} : { limit: String(limit) }),
+    ...(parentSessionId === undefined ? {} : { parentSessionId: parentSessionId ?? "null" }),
+  };
+}
+
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
 export type WorkspaceControlEventPage = {
@@ -269,6 +286,24 @@ export class OpenGeniClient {
     );
   }
 
+  async getNewSessionDraft(workspaceId: string): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+    );
+  }
+
+  async saveNewSessionDraft(
+    workspaceId: string,
+    request: SaveNewSessionDraftRequest,
+  ): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+      request,
+    );
+  }
+
   async getSession(workspaceId: string, sessionId: string): Promise<Session> {
     return await this.requestJson<Session>(
       "GET",
@@ -314,21 +349,21 @@ export class OpenGeniClient {
       search?: string;
     } = {},
   ): Promise<Session[]> {
+    // Search was added with the pin-aware page endpoint. An older API silently
+    // ignores unknown query parameters on the historical array endpoint, which
+    // would turn a search into a plausible-looking unfiltered result. Route
+    // searches through listSessionPage so its rolling-version shape check can
+    // fail explicitly on an older server; retain the array endpoint for every
+    // pre-existing call shape.
+    if (options.search?.trim()) {
+      const page = await this.listSessionPage(workspaceId, options);
+      return [...page.pinned, ...page.sessions];
+    }
     return await this.requestJson<Session[]>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       undefined,
-      {
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
+      sessionListQuery(options),
     );
   }
 
@@ -340,26 +375,51 @@ export class OpenGeniClient {
       parentSessionId?: string | null;
       cursor?: string;
       search?: string;
+      /** Return only the complete personal pinned projection. */
+      pinsOnly?: boolean;
     } = {},
   ): Promise<SessionListResponse> {
-    return await this.requestJson<SessionListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions`,
-      undefined,
-      {
-        view: "page",
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
-    );
+    const search = options.search?.trim();
+    let response: SessionListResponse | Session[];
+    try {
+      response = await this.requestJson<SessionListResponse | Session[]>(
+        "GET",
+        `/v1/workspaces/${workspaceId}/sessions`,
+        undefined,
+        {
+          view: "page",
+          ...sessionListQuery(options),
+          ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
+          ...(search ? { search } : {}),
+          ...(options.pinsOnly ? { pinsOnly: "true" } : {}),
+        },
+      );
+    } catch (error) {
+      if (error instanceof OpenGeniApiError && error.status === 410) {
+        throw new OpenGeniSessionListCursorError(error.status, error.body);
+      }
+      throw error;
+    }
+    if (Array.isArray(response)) {
+      // Rolling/same-major compatibility: an older API ignores `view=page` and
+      // returns the historical array. That is an honest one-page projection;
+      // never pretend it honored a cursor supplied directly by a caller.
+      if (options.cursor) {
+        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
+      }
+      // Older APIs ignore unknown query parameters. Treating their unfiltered
+      // array as a successful search would be worse than an explicit rolling-
+      // upgrade error (and client-side filtering cannot recover matches beyond
+      // the old endpoint's bounded first page).
+      if (search) {
+        throw new Error("The connected OpenGeni API does not support session search");
+      }
+      if (options.pinsOnly) {
+        throw new Error("The connected OpenGeni API does not support pins-only session lists");
+      }
+      return { pinned: [], sessions: response, nextCursor: null };
+    }
+    return response;
   }
 
   /** Set this authenticated member's personal workspace pin for a session. */
@@ -1919,21 +1979,27 @@ export class OpenGeniClient {
    * -> complete. Returns the ready `FileAsset`.
    */
   async uploadFile(workspaceId: string, input: UploadFileInput): Promise<FileAsset> {
-    // Copy Uint8Array views into a Blob so byte offsets/shared buffers can't
-    // leak surrounding bytes into the PUT body.
+    // Snapshot mutable inputs before hashing so the digest always describes the
+    // exact bytes later sent to object storage. Copy Uint8Array views into a
+    // Blob so byte offsets/shared buffers can't leak surrounding bytes.
     const body: Blob | ArrayBuffer | string =
-      input.data instanceof Uint8Array ? new Blob([input.data.slice()]) : input.data;
+      input.data instanceof Uint8Array
+        ? new Blob([input.data.slice()])
+        : input.data instanceof ArrayBuffer
+          ? input.data.slice(0)
+          : input.data;
     const sizeBytes =
       typeof body === "string"
         ? new TextEncoder().encode(body).byteLength
         : body instanceof Blob
           ? body.size
           : body.byteLength;
+    const sha256 = input.sha256 ?? (await sha256ForUpload(body));
     const upload = await this.beginFileUpload(workspaceId, {
       filename: input.filename,
       contentType: input.contentType,
       sizeBytes,
-      ...(input.sha256 !== undefined ? { sha256: input.sha256 } : {}),
+      sha256,
     });
     const putResponse = await this.fetchImpl(upload.putUrl, {
       method: "PUT",
@@ -2720,6 +2786,17 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
+async function sha256ForUpload(body: Blob | ArrayBuffer | string): Promise<string> {
+  const bytes =
+    typeof body === "string"
+      ? new TextEncoder().encode(body)
+      : body instanceof Blob
+        ? new Uint8Array(await body.arrayBuffer())
+        : new Uint8Array(body);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
 async function safeText(response: Response): Promise<string> {
   try {
     return await response.text();

package/src/errors.ts

@@ -1,16 +1,37 @@
 /** Error for a non-2xx OpenGeni API response. */
 export class OpenGeniApiError extends Error {
   readonly status: number;
+  readonly code: string | undefined;
   readonly body: string;
 
   constructor(status: number, body: string) {
-    super(`OpenGeni API ${status}: ${body || "(empty body)"}`);
+    const decoded = decodeApiErrorBody(body);
+    super(`OpenGeni API ${status}: ${decoded.message ?? (body || "(empty body)")}`);
     this.name = "OpenGeniApiError";
     this.status = status;
+    this.code = decoded.code;
     this.body = body;
   }
 }
 
+function decodeApiErrorBody(body: string): { code?: string; message?: string } {
+  if (!body) return {};
+  try {
+    const decoded: unknown = JSON.parse(body);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return {};
+    const record = decoded as Record<string, unknown>;
+    return {
+      ...(typeof record.code === "string" && record.code ? { code: record.code } : {}),
+      ...(typeof record.message === "string" && record.message ? { message: record.message } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** A short-lived session-list snapshot cursor can no longer be continued. */
+export class OpenGeniSessionListCursorError extends OpenGeniApiError {}
+
 /** The browser bundle and API disagree about their state-changing wire contract. */
 export class OpenGeniApiContractMismatchError extends Error {
   readonly expected: string;

package/src/index.ts

@@ -10,6 +10,7 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSessionListCursorError,
   OpenGeniStreamError,
   isRetryableStreamError,
 } from "./errors";
@@ -142,6 +143,11 @@ export type {
   CodexConnectionStatus,
   CodexConnectStart,
   CodexConnectPoll,
+  CodexFleetConfidence,
+  CodexFleetCacheState,
+  CodexFleetDecisionEventPayload,
+  CodexFleetDecisionScore,
+  CodexFleetShadowComparison,
   CodexOverviewResponse,
   CodexResetCredit,
   CodexResetRedemptionRecovery,
@@ -276,7 +282,10 @@ export type {
   EffectiveControlResumeOption,
   EffectiveSessionControl,
   MoveSessionQueueItemRequest,
+  NewSessionDraft,
+  NewSessionDraftOptions,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   SessionCommandReceipt,
   SteerSessionQueueItemRequest,
   WorkspaceInferenceControlResponse,

package/src/types.ts

@@ -65,6 +65,9 @@ export type SessionCapabilities = {
   os: SandboxOs;
   liveness: "cold" | "warming" | "warm" | "draining";
   leaseEpoch: number;
+  workspaceGeneration: number | null;
+  archiveGeneration: number | null;
+  archiveComplete: boolean;
   viewerHeartbeatIntervalMs: number;
   FileSystem: {
     available: boolean;
@@ -182,6 +185,9 @@ export type ViewerHolder = {
   sandboxGroupId: string;
   liveness: "cold" | "warming" | "warm" | "draining";
   leaseEpoch: number;
+  workspaceGeneration: number | null;
+  archiveGeneration: number | null;
+  archiveComplete: boolean;
   viewerHeartbeatIntervalMs: number;
   dataPlaneUrl: string | null;
 };
@@ -487,6 +493,13 @@ export type Session = {
   firstPartyMcpPermissions: string[] | null;
   mcpServers: SessionMcpServerMetadata[];
   parentSessionId: string | null;
+  /** Immutable server-authored nested-agent lineage and policy snapshot. */
+  rootSessionId: string;
+  nestedAgentDepth: number;
+  maxNestedAgentDepthOverride: number | null;
+  effectiveMaxNestedAgentDepth: number;
+  nestedAgentDepthPolicySource: "session" | "workspace" | "deployment" | "default";
+  nestedAgentDepthPolicySessionId: string | null;
   createIdempotencyKey: string | null;
   temporalWorkflowId: string | null;
   activeTurnId: string | null;
@@ -753,6 +766,8 @@ export const SESSION_EVENT_TYPES = [
   "codex.account.switched",
   // credential allocator metadata-only per-turn credential selection audit.
   "codex.credential.selected",
+  // Bounded, identity-free deterministic shadow/replay decision.
+  "codex.fleet.decision",
   // credential allocator durable zero-capacity wait lifecycle. These are system/runtime
   // events, never synthetic user messages.
   "codex.capacity.waiting",
@@ -957,6 +972,89 @@ export type AgentToolCallCreatedPayload = {
 export type AgentToolCallOutputPayload = { id: string | null; output: unknown };
 export type SessionStatusChangedPayload = { status: SessionStatus };
 
+// Adaptive-fleet shadow event. This is the typed, identity-free view
+// consumed by UI/manager tooling; the durable replay record also contains the
+// complete normalized policy/input needed for offline deterministic replay.
+export type CodexFleetConfidence = "unknown" | "low" | "medium" | "high";
+export type CodexFleetCacheState = "unknown" | "healthy" | "collapsed";
+export type CodexFleetShadowComparison =
+  | "match"
+  | "different_candidate"
+  | "different_outcome"
+  | "not_comparable_truncated";
+export type CodexFleetDecisionScore = {
+  candidateKey: string;
+  eligible: boolean;
+  rejectionReason:
+    | "allocator_disabled"
+    | "unavailable"
+    | "cooling"
+    | "quota_ceiling"
+    | "overlay_isolation"
+    | null;
+  quotaPressure: number;
+  leasePressure: number;
+  observedBurnPressure: number;
+  inferredBurnPressure: number;
+  runwayPressure: number;
+  uncertaintyPressure: number;
+  cacheAffinityBenefit: number;
+  cacheState: CodexFleetCacheState;
+  overlayPreferenceBenefit: number;
+  total: number;
+  confidence: CodexFleetConfidence;
+};
+export type CodexFleetDecisionEventPayload = {
+  schemaVersion: 1;
+  mode: "shadow";
+  actual: {
+    outcome: "selected" | "waiting" | "none";
+    candidateKey: string | null;
+    reason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+  };
+  comparison: CodexFleetShadowComparison;
+  replay: {
+    schemaVersion: 1;
+    policyVersion: "adaptive-shadow-v1";
+    mode: "shadow";
+    input: { candidates: Array<{ key: string }> } & Record<string, unknown>;
+    truncatedCandidateCount: number;
+    inputFingerprint: string;
+    decisionFingerprint: string;
+    decision: {
+      outcome: "selected" | "paced" | "none";
+      selectedCandidateKey: string | null;
+      reason:
+        | "fenced_in_flight"
+        | "fenced_candidate_missing"
+        | "admission_paced"
+        | "no_eligible_candidate"
+        | "overlay_isolated_empty"
+        | "best_score"
+        | "affinity_best"
+        | "hysteresis_hold";
+      admission: {
+        outcome: "admit" | "pace";
+        reason:
+          | "fenced_in_flight"
+          | "pacing_disabled"
+          | "capacity_unknown"
+          | "capacity_available"
+          | "work_conserving_borrow"
+          | "manager_priority"
+          | "standard_starvation_bound"
+          | "capacity_saturated"
+          | "emergency_fuse";
+        borrowedIdleCapacity: boolean;
+      };
+      borrowedOverlayCapacity: boolean;
+      strandedEligibleCount: number;
+      confidence: CodexFleetConfidence;
+      scores: CodexFleetDecisionScore[];
+    };
+  } & Record<string, unknown>;
+};
+
 // Recording payloads (P4.3 — plain TS mirror of the contracts Zod schemas; the
 // SDK is zero-runtime-dep so these are TYPES, not Zod, F15). The contract-parity
 // test asserts the event-type literals; these shapes document the wire payloads.
@@ -1046,7 +1144,7 @@ export type TerminalPtyOutputDeltaPayload = {
 export type TerminalPtyExitedPayload = {
   ptyId: string;
   exitCode: number | null;
-  reason: "exit" | "killed" | "owner_gone" | "timeout";
+  reason: "exit" | "killed" | "owner_gone" | "timeout" | "lost";
 };
 
 // A2 FileSystem request/response.
@@ -1333,8 +1431,8 @@ export type TerminalExecRequest = {
 export type TerminalExecResponse = {
   stdout: string;
   stderr: string;
-  exitCode: number | null;
-  running: boolean;
+  exitCode: number;
+  running: false;
   wallTimeSeconds: number;
 };
 export type PtyOpenRequest = {
@@ -1398,6 +1496,7 @@ export type ScheduledTaskAgentConfig = {
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
   goal?: GoalSpec | undefined;
+  maxNestedAgentDepth?: number | undefined;
 };
 
 export type ScheduledTask = {
@@ -1459,6 +1558,10 @@ export type CreateSessionRequest = {
   // double-submit/retry of the same logical create collapse to one session.
   // Distinct from the per-call clientEventId.
   idempotencyKey?: string | undefined;
+  // Exact actor-private pre-session draft revision represented by this create.
+  // The server consumes only this revision after durable initialization.
+  expectedNewSessionDraftRevision?: number | undefined;
+  maxNestedAgentDepth?: number | undefined;
   firstPartyMcpPermissions?: string[] | undefined;
   mcpServers?: SessionMcpServerInput[] | undefined;
   // Shared-sandbox placement (mirror of `@opengeni/contracts` CreateSessionRequest.sandbox,
@@ -1978,12 +2081,14 @@ export type Workspace = {
 export type WorkspaceSettings = {
   memoryEnabled?: boolean | undefined;
   transcription?: WorkspaceTranscriptionPolicy | undefined;
+  maxNestedAgentDepth?: number | null | undefined;
   [key: string]: unknown;
 };
 
 export type UpdateWorkspaceSettingsRequest = {
   memoryEnabled?: boolean | undefined;
   transcription?: WorkspaceTranscriptionPolicy | undefined;
+  maxNestedAgentDepth?: number | null | undefined;
   [key: string]: unknown;
 };
 
@@ -2068,6 +2173,36 @@ export type SessionGoalStatus = "active" | "paused" | "completed";
 
 export type SessionGoalCreatedBy = "api" | "agent" | "scheduled_task";
 
+export type SessionGoalContinuationState =
+  | "inactive"
+  | "scheduled"
+  | "running"
+  | "blocked"
+  | "invariant_broken";
+
+export type SessionGoalContinuationReason =
+  | "goal_inactive"
+  | "wake_pending"
+  | "continuation_pending"
+  | "human_work_pending"
+  | "goal_turn_running"
+  | "human_turn_running"
+  | "workstream_paused"
+  | "approval_required"
+  | "provider_backpressure"
+  | "session_cancelled"
+  | "system_work_pending"
+  | "missing_obligation";
+
+export type SessionGoalContinuation = {
+  state: SessionGoalContinuationState;
+  reason: SessionGoalContinuationReason;
+  wakeRevision: number;
+  observedRevision: number;
+  nextAttemptAt: string | null;
+  lastError: string | null;
+};
+
 export type SessionGoal = {
   id: string;
   accountId: string;
@@ -2085,6 +2220,8 @@ export type SessionGoal = {
   noProgressStreak: number;
   maxAutoContinuations: number | null;
   metadata: Record<string, unknown>;
+  /** Optional for source compatibility; the API always supplies this projection. */
+  continuation?: SessionGoalContinuation | undefined;
   createdAt: string;
   updatedAt: string;
 };
@@ -2172,6 +2309,27 @@ export type ComposerDraft = {
   updatedAt: string | null;
 };
 
+export type NewSessionDraftOptions = {
+  sandboxBackend?: SandboxBackend | undefined;
+  targetSandboxId?: string | undefined;
+  workingDir?: string | undefined;
+  variableSetId?: string | undefined;
+  rigId?: string | undefined;
+  goal?: GoalSpec | undefined;
+  firstPartyMcpPermissions?: Permission[] | undefined;
+};
+
+export type NewSessionDraft = {
+  revision: number;
+  text: string;
+  resources: ResourceRef[];
+  tools: ToolRef[];
+  model: string;
+  reasoningEffort: ReasoningEffort;
+  options: NewSessionDraftOptions;
+  updatedAt: string | null;
+};
+
 export type SessionQueueSnapshot = {
   version: number;
   effectiveControl: EffectiveSessionControl;
@@ -2300,6 +2458,10 @@ export type SaveComposerDraftRequest = Omit<
   "revision" | "sourceTurnId" | "sourceTurnVersion" | "updatedAt"
 > & { expectedRevision: number };
 
+export type SaveNewSessionDraftRequest = Omit<NewSessionDraft, "revision" | "updatedAt"> & {
+  expectedRevision: number;
+};
+
 // --- Scheduled tasks: requests + runs ----------------------------------------
 
 /** Input shape for agent config on create/update (server applies defaults). */
@@ -2312,6 +2474,7 @@ export type ScheduledTaskAgentConfigInput = {
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
   goal?: GoalSpec | undefined;
+  maxNestedAgentDepth?: number | undefined;
 };
 
 export type CreateScheduledTaskRequest = {
@@ -3379,6 +3542,9 @@ export type MachineView = {
   state: MachineState;
   active: boolean;
   isSessionGroup: boolean;
+  workspaceGeneration: number | null;
+  archiveGeneration: number | null;
+  archiveComplete: boolean;
   os: string;
   arch: string;
   hasDisplay: boolean;
@@ -3428,7 +3594,10 @@ export type SwapActiveSandboxResponse = {
     | "offline_enrollment"
     | "unsupported_backend_context"
     | "transient_establishment"
-    | "concurrent_swap";
+    | "concurrent_swap"
+    | "recovery_in_progress"
+    | "recovery_degraded"
+    | "recovery_unrecoverable";
 };
 
 // ── Self-hosted enrollment UX (design 11) ────────────────────────────────────