@opengeni/sdk 0.23.0 → 0.25.5

package/src/errors.ts

@@ -1,16 +1,101 @@
 /** Error for a non-2xx OpenGeni API response. */
 export class OpenGeniApiError extends Error {
   readonly status: number;
+  readonly code: string | undefined;
+  readonly retryable: boolean;
+  readonly correlationId: string | undefined;
+  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+  readonly outcomeUnknown: boolean;
   readonly body: string;
 
-  constructor(status: number, body: string) {
-    super(`OpenGeni API ${status}: ${body || "(empty body)"}`);
+  constructor(
+    status: number,
+    body: string,
+    options: {
+      code?: string | undefined;
+      retryable?: boolean | undefined;
+      correlationId?: string | undefined;
+      outcomeUnknown?: boolean | undefined;
+      displayMessage?: string | undefined;
+      mutation?: boolean | undefined;
+    } = {},
+  ) {
+    const decoded = decodeApiErrorBody(body);
+    const correlationId = decoded?.requestId ?? boundedCorrelationId(options.correlationId);
+    const gatewayFailure = status >= 502 && status <= 504;
+    const fromResponse = options.mutation !== undefined;
+    const message = decoded?.message ?? (fromResponse ? "Request failed." : body || "(empty body)");
+    const displayMessage =
+      options.displayMessage ??
+      (gatewayFailure && fromResponse
+        ? "OpenGeni is temporarily unavailable — retry."
+        : `OpenGeni API ${status}: ${message}`);
+    super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
     this.name = "OpenGeniApiError";
     this.status = status;
-    this.body = body;
+    this.code =
+      options.code ??
+      decoded?.code ??
+      (gatewayFailure && fromResponse ? "upstream_unavailable" : undefined);
+    this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
+    this.correlationId = correlationId;
+    this.outcomeUnknown =
+      options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+    this.body = !fromResponse || decoded ? body : "";
   }
 }
 
+function decodeApiErrorBody(body: string): {
+  code: string | undefined;
+  message: string | undefined;
+  requestId: string | undefined;
+  retryable: boolean | undefined;
+} | null {
+  if (!body) return null;
+  try {
+    const decoded: unknown = JSON.parse(body);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
+    const record = decoded as Record<string, unknown>;
+    const nested =
+      record.error && typeof record.error === "object" && !Array.isArray(record.error)
+        ? (record.error as Record<string, unknown>)
+        : record;
+    const code = boundedApiField(nested.code);
+    const message = boundedApiField(nested.message);
+    const requestId = boundedCorrelationId(nested.requestId);
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : undefined;
+    if (!code && !message && !requestId && retryable === undefined) return null;
+    return {
+      code,
+      message,
+      requestId,
+      retryable,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function boundedApiField(value: unknown): string | undefined {
+  if (typeof value !== "string") return;
+  const bytes = new TextEncoder().encode(value);
+  return bytes.byteLength <= 512 ? value : new TextDecoder().decode(bytes.slice(0, 512));
+}
+
+function retryableApiStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+function boundedCorrelationId(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 128 || !/^[\w.:-]+$/.test(value)) {
+    return;
+  }
+  return value;
+}
+
+/** 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;
@@ -46,14 +131,6 @@ export function isAbortError(error: unknown): boolean {
  * permanent and surface to the caller instead.
  */
 export function isRetryableStreamError(error: unknown): boolean {
-  if (error instanceof OpenGeniApiError) {
-    return (
-      error.status === 408 ||
-      error.status === 409 ||
-      error.status === 425 ||
-      error.status === 429 ||
-      error.status >= 500
-    );
-  }
+  if (error instanceof OpenGeniApiError) return error.retryable;
   return error instanceof TypeError;
 }

package/src/index.ts

@@ -10,6 +10,7 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSessionListCursorError,
   OpenGeniStreamError,
   isRetryableStreamError,
 } from "./errors";
@@ -85,6 +86,7 @@ export {
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES,
@@ -142,6 +144,11 @@ export type {
   CodexConnectionStatus,
   CodexConnectStart,
   CodexConnectPoll,
+  CodexFleetConfidence,
+  CodexFleetCacheState,
+  CodexFleetDecisionEventPayload,
+  CodexFleetDecisionScore,
+  CodexFleetShadowComparison,
   CodexOverviewResponse,
   CodexResetCredit,
   CodexResetRedemptionRecovery,
@@ -169,6 +176,7 @@ export type {
   CreateFileUploadResponse,
   CreateGitHubAppManifestRequest,
   CreateGitHubAppManifestResponse,
+  CreateKnowledgeDropRequest,
   CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
@@ -178,11 +186,15 @@ export type {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentCuration,
+  DocumentCurationStatus,
   DocumentSearchMode,
   DocumentSearchRequest,
   DocumentSearchResponse,
   DocumentSearchResult,
   DocumentStatus,
+  DocumentVisibility,
+  MoveDocumentRequest,
   EnableCapabilityRequest,
   EnablePackRequest,
   Entitlements,
@@ -200,7 +212,9 @@ export type {
   FileUploadData,
   GetPackResponse,
   GitHubAppInfo,
+  GitHubBindingStatus,
   GitHubInstallationBinding,
+  GitHubInstallationLifecycle,
   GitHubRepositoriesResponse,
   GitHubRepository,
   GitHubRepositoryScope,
@@ -276,7 +290,10 @@ export type {
   EffectiveControlResumeOption,
   EffectiveSessionControl,
   MoveSessionQueueItemRequest,
+  NewSessionDraft,
+  NewSessionDraftOptions,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   SessionCommandReceipt,
   SteerSessionQueueItemRequest,
   WorkspaceInferenceControlResponse,
@@ -402,6 +419,7 @@ export type {
   UpdateSessionMcpApprovalPolicyResponse,
   UpdateSessionPinRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,

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;
 };
@@ -270,6 +276,18 @@ export type SessionToolPolicy = {
   inheritedFromSessionId: string | null;
 };
 
+export type UpdateSessionToolPolicyRequest =
+  | {
+      mode: "workspace_default";
+      expectedVersion: number;
+    }
+  | {
+      /** Omitted for compatibility with the original explicit-only API. */
+      mode?: "explicit" | undefined;
+      tools: ToolRef[];
+      expectedVersion: number;
+    };
+
 export type SessionEffectiveToolPolicy = {
   mode: SessionToolPolicy["mode"];
   inheritedFromSessionId: string | null;
@@ -466,6 +484,7 @@ export type Session = {
   resources: ResourceRef[];
   tools: ToolRef[];
   toolPolicy?: SessionToolPolicy | undefined;
+  toolPolicyVersion?: number | undefined;
   effectiveToolPolicy?: SessionEffectiveToolPolicy | undefined;
   metadata: Record<string, unknown>;
   /** Frozen creator fact; later turns carry their own independent initiator. */
@@ -487,6 +506,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;
@@ -749,10 +775,13 @@ export const SESSION_EVENT_TYPES = [
   "terminal.pty.exited",
   "session.title_set",
   "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
   // Multi-account Codex (P1): the session's inference account changed.
   "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 +986,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 +1158,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 +1445,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 +1510,7 @@ export type ScheduledTaskAgentConfig = {
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
   goal?: GoalSpec | undefined;
+  maxNestedAgentDepth?: number | undefined;
 };
 
 export type ScheduledTask = {
@@ -1459,6 +1572,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,
@@ -1890,6 +2007,8 @@ export type ClientAuthConfig =
 // parity suite. The SDK has no runtime dependency on the Zod contracts package.
 export const OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+/** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
+export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
 
 /**
  * Public, unauthenticated-by-default client bootstrap config returned by
@@ -1978,12 +2097,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 +2189,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 +2236,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 +2325,29 @@ 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[];
+  /** False inherits the workspace-default MCP policy; true preserves an explicit array. */
+  toolsProvided: boolean;
+  model: string;
+  reasoningEffort: ReasoningEffort;
+  options: NewSessionDraftOptions;
+  updatedAt: string | null;
+};
+
 export type SessionQueueSnapshot = {
   version: number;
   effectiveControl: EffectiveSessionControl;
@@ -2300,6 +2476,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 +2492,7 @@ export type ScheduledTaskAgentConfigInput = {
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
   goal?: GoalSpec | undefined;
+  maxNestedAgentDepth?: number | undefined;
 };
 
 export type CreateScheduledTaskRequest = {
@@ -2660,6 +2841,19 @@ export type KnowledgeSourceKind =
   | "other";
 export type DocumentSearchMode = "hybrid" | "vector" | "keyword";
 
+export type DocumentVisibility = "workspace" | "private";
+
+export type DocumentCurationStatus = "none" | "pending" | "suggested" | "auto_filed" | "failed";
+
+export type DocumentCuration = {
+  suggestedBaseId: string | null;
+  suggestedBaseName: string | null;
+  confidence: number;
+  reason: string | null;
+  originalTitle: string | null;
+  model: string | null;
+};
+
 export type DocumentBase = {
   id: string;
   workspaceId: string;
@@ -2688,6 +2882,13 @@ export type Document = {
   sourceUpdatedAt: string | null;
   sourceVersion: string | null;
   aclTags: string[];
+  visibility: DocumentVisibility;
+  createdBy: string | null;
+  agentAccess: boolean;
+  summary: string | null;
+  topics: string[];
+  curationStatus: DocumentCurationStatus;
+  curation: DocumentCuration | null;
   createdAt: string;
   updatedAt: string;
 };
@@ -2734,6 +2935,21 @@ export type AddDocumentRequest = {
   sourceUpdatedAt?: string | undefined;
   sourceVersion?: string | undefined;
   aclTags?: string[] | undefined;
+  visibility?: DocumentVisibility | undefined;
+  agentAccess?: boolean | undefined;
+};
+
+export type CreateKnowledgeDropRequest = {
+  text?: string | undefined;
+  fileId?: string | undefined;
+  filename?: string | undefined;
+  title?: string | undefined;
+  visibility?: DocumentVisibility | undefined;
+  agentAccess?: boolean | undefined;
+};
+
+export type MoveDocumentRequest = {
+  targetBaseId?: string | undefined;
 };
 
 export type DocumentSearchRequest = {
@@ -3170,10 +3386,16 @@ export type GitHubRepository = {
 
 export type GitHubRepositoryScope = "all" | "selected";
 
+export type GitHubBindingStatus = "disabled" | "unbound" | "bound";
+
+export type GitHubInstallationLifecycle = "active" | "suspended" | "deleted" | "unverified";
+
 export type GitHubInstallationBinding = {
   installationId: number;
+  githubAccountId: number | null;
   accountLogin: string | null;
   accountType: string | null;
+  lifecycle: GitHubInstallationLifecycle;
   repositoryScope: GitHubRepositoryScope;
   repositoryCount: number;
   createdAt: string;
@@ -3182,12 +3404,14 @@ export type GitHubInstallationBinding = {
 
 export type GitHubAppInfo = {
   configured: boolean;
+  /** Truthful workspace binding state; server App credentials alone are not a binding. */
+  status: GitHubBindingStatus;
   appId: string | null;
   clientId: string | null;
   appSlug: string | null;
-  /** Reserved compatibility field; null while new installation binding is disabled. */
+  /** Fresh GitHub-controlled installation/configuration consent entry point. */
   installUrl: string | null;
-  /** Reserved compatibility field; null while new installation binding is disabled. */
+  /** Compatibility alias for installUrl; no repository-admin chooser is exposed. */
   linkUrl: string | null;
   /** Installation bindings owned independently by this workspace. */
   installations: GitHubInstallationBinding[];
@@ -3379,6 +3603,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 +3655,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) ────────────────────────────────────