@opengeni/sdk 0.11.0 → 0.15.0

package/src/types.ts

@@ -8,6 +8,8 @@ export type SessionStatus =
   | "running"
   | "idle"
   | "requires_action"
+  | "recovering"
+  | "waiting_capacity"
   | "failed"
   | "cancelled";
 
@@ -209,6 +211,7 @@ export type ViewerHeartbeatRequest = { leaseEpoch: number };
 export type ViewerHeartbeatResponse = { alive: boolean };
 
 export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type GitCredentialProvider = "github" | "gitlab" | "azure_devops";
 
 export type RepositoryResourceRef = {
   kind: "repository";
@@ -216,6 +219,11 @@ export type RepositoryResourceRef = {
   ref: string;
   mountPath?: string | undefined;
   subpath?: string | undefined;
+  provider?: GitCredentialProvider | undefined;
+  repositoryId?: number | string | undefined;
+  installationId?: number | string | undefined;
+  projectId?: number | string | undefined;
+  connectionId?: string | undefined;
   githubInstallationId?: number | undefined;
   githubRepositoryId?: number | undefined;
 };
@@ -331,6 +339,13 @@ export type OAuthStartRequest = {
   requestedScopes?: string[] | undefined;
   returnPath?: string | undefined;
   connectionId?: string | undefined;
+  oauthClient?:
+    | {
+        clientId: string;
+        clientSecret?: string | undefined;
+        tokenEndpointAuthMethod?: "none" | "client_secret_post" | "client_secret_basic" | undefined;
+      }
+    | undefined;
 };
 
 export type OAuthStartResponse = {
@@ -364,30 +379,98 @@ export type Session = {
   metadata: Record<string, unknown>;
   model: string;
   sandboxBackend: SandboxBackend;
+  sandboxOs: SandboxOs;
+  sandboxGroupId: string;
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  variableSetId: string | null;
+  /** @deprecated use variableSetId */
   environmentId: string | null;
+  // The rig + frozen rig version this session rides (M3). Both null for a
+  // rig-less session. Frozen at create; a later rig promote never moves them.
+  rigId: string | null;
+  rigVersionId: string | null;
   firstPartyMcpPermissions: string[] | null;
   mcpServers: SessionMcpServerMetadata[];
+  parentSessionId: string | null;
   createIdempotencyKey: string | null;
   temporalWorkflowId: string | null;
   activeTurnId: string | null;
+  queueVersion: number;
+  queueHeadPosition: number;
+  queueTailPosition: number;
+  effectiveControl: EffectiveSessionControl;
   lastSequence: number;
   /** Multi-account Codex (P1): the account this session is pinned to (null ⇒ follow workspace active). */
   codexPinnedCredentialId?: string | null;
   /** Multi-account Codex (P1): the account the most recent turn ran on (the "Running on:" indicator). */
   codexLastCredentialId?: string | null;
+  /** Personal (authenticated subject) workspace pin state, never workspace-global. */
+  pinned?: boolean;
+  /** Stable pin ordering key; null when this subject has not pinned the session. */
+  pinnedAt?: string | null;
+  /** Optimistic pin-state revision; zero represents an absent pin relation. */
+  pinVersion?: number;
+  /** Server-authoritative descendant counts populated by session-list reads. */
+  treeStats?:
+    | {
+        directChildren: number;
+        totalDescendants: number;
+        runningDescendants: number;
+        queuedDescendants: number;
+        attentionDescendants: number;
+        pausedDescendants: number;
+        failedDescendants: number;
+      }
+    | undefined;
   createdAt: string;
   updatedAt: string;
 };
 
+export type SessionSummary = Session;
+
+/** Canonical session-list page; pinned rows are excluded from ordinary pages. */
+export type SessionListResponse = {
+  pinned: Session[];
+  sessions: Session[];
+  nextCursor: string | null;
+};
+
+export type UpdateSessionPinRequest = {
+  pinned: boolean;
+  expectedVersion?: number;
+};
+
+export type LineageNode = {
+  session: SessionSummary;
+  children: LineageNode[];
+};
+
+export type SessionLineageResponse = {
+  ancestors: SessionSummary[];
+  children: LineageNode[];
+  truncated: boolean;
+};
+
 export type SessionTurnStatus =
   | "queued"
   | "running"
   | "requires_action"
+  | "recovering"
+  | "waiting_capacity"
   | "completed"
   | "failed"
-  | "cancelled";
-
-export type SessionTurnSource = "user" | "scheduled_task" | "api" | "goal";
+  | "cancelled"
+  | "superseded"
+  | "withdrawn_for_edit";
+
+export type SessionTurnSource =
+  | "user"
+  | "scheduled_task"
+  | "api"
+  | "goal"
+  | "system"
+  | "compaction";
 
 export type SessionTurn = {
   id: string;
@@ -404,7 +487,14 @@ export type SessionTurn = {
   model: string;
   reasoningEffort: ReasoningEffort;
   sandboxBackend: SandboxBackend;
+  sandboxOs: SandboxOs | null;
   metadata: Record<string, unknown>;
+  version: number;
+  executionGeneration: number;
+  activeAttemptId: string | null;
+  lineage: Record<string, unknown>;
+  cancelledBy?: string | null;
+  cancelReason?: string | null;
   startedAt: string | null;
   finishedAt: string | null;
   createdAt: string;
@@ -415,25 +505,33 @@ export const 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.interrupt",
+  "user.pause",
   "user.approvalDecision",
   "turn.queued",
-  "turn.updated",
   "turn.started",
   "turn.completed",
   "turn.failed",
   "turn.cancelled",
-  "turn.preempted",
+  "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",
@@ -444,7 +542,21 @@ export const SESSION_EVENT_TYPES = [
   "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",
@@ -465,6 +577,36 @@ export const SESSION_EVENT_TYPES = [
   "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",
 ] as const;
 
 export type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
@@ -486,6 +628,11 @@ export type SessionEvent = {
   occurredAt: string;
   clientEventId?: string | null | undefined;
   turnId?: string | null | undefined;
+  turnGeneration?: number | null | undefined;
+  turnAttemptId?: string | null | undefined;
+  turnAssociation?: "current" | "late_rejected" | "duplicate" | null | undefined;
+  duplicateOfEventId?: string | null | undefined;
+  duplicateReason?: string | null | undefined;
 };
 
 export type ToolAuthNeededPayload = {
@@ -565,7 +712,13 @@ export type SandboxCommandOutputDeltaPayload = {
 };
 export type FsChangeKind = "created" | "modified" | "deleted" | "renamed";
 export type FsChangedPayload = {
-  changes: { path: string; kind: FsChangeKind; isDir: boolean; sizeBytes: number | null; oldPath?: string | undefined }[];
+  changes: {
+    path: string;
+    kind: FsChangeKind;
+    isDir: boolean;
+    sizeBytes: number | null;
+    oldPath?: string | undefined;
+  }[];
   source: "write" | "watch" | "agent";
   revision: number;
   leaseEpoch: number;
@@ -580,9 +733,24 @@ export type GitChangedPayload = {
   revision: number;
   leaseEpoch: number;
 };
-export type TerminalPtyStartedPayload = { ptyId: string; cols: number; rows: number; shell: string; cwd: string };
-export type TerminalPtyOutputDeltaPayload = { ptyId: string; stream: "stdout" | "stderr"; chunk: string; seq: number };
-export type TerminalPtyExitedPayload = { ptyId: string; exitCode: number | null; reason: "exit" | "killed" | "owner_gone" | "timeout" };
+export type TerminalPtyStartedPayload = {
+  ptyId: string;
+  cols: number;
+  rows: number;
+  shell: string;
+  cwd: string;
+};
+export type TerminalPtyOutputDeltaPayload = {
+  ptyId: string;
+  stream: "stdout" | "stderr";
+  chunk: string;
+  seq: number;
+};
+export type TerminalPtyExitedPayload = {
+  ptyId: string;
+  exitCode: number | null;
+  reason: "exit" | "killed" | "owner_gone" | "timeout";
+};
 
 // A2 FileSystem request/response.
 export type FsNodeType = "file" | "dir" | "symlink" | "other";
@@ -597,31 +765,115 @@ export type FsTreeNode = {
   truncated: boolean;
 };
 export type FsEncoding = "utf8" | "base64";
-export type FsListRequest = { path?: string; depth?: number; maxEntries?: number; includeHidden?: boolean };
+export type FsListRequest = {
+  path?: string;
+  depth?: number;
+  maxEntries?: number;
+  includeHidden?: boolean;
+};
 export type FsListResponse = { root: FsTreeNode; revision: number; truncated: boolean };
 export type FsReadRequest = { path: string; encoding?: FsEncoding; maxBytes?: number };
-export type FsReadResponse = { path: string; encoding: FsEncoding; content: string; sizeBytes: number; truncated: boolean; isBinary: boolean; revision: number };
-export type FsWriteRequest = { path: string; encoding?: FsEncoding; content: string; overwrite?: boolean; createParents?: boolean };
+export type FsReadResponse = {
+  path: string;
+  encoding: FsEncoding;
+  content: string;
+  sizeBytes: number;
+  truncated: boolean;
+  isBinary: boolean;
+  revision: number;
+};
+export type FsWriteRequest = {
+  path: string;
+  encoding?: FsEncoding;
+  content: string;
+  overwrite?: boolean;
+  createParents?: boolean;
+};
 export type FsWriteResponse = { path: string; sizeBytes: number; revision: number };
 export type FsDeleteRequest = { path: string; recursive?: boolean };
 export type FsDeleteResponse = { revision: number };
-export type FsMoveRequest = { path: string; newPath: string; overwrite?: boolean; createParents?: boolean };
+export type FsMoveRequest = {
+  path: string;
+  newPath: string;
+  overwrite?: boolean;
+  createParents?: boolean;
+};
 export type FsMoveResponse = { path: string; newPath: string; revision: number };
 export type FsMkdirRequest = { path: string; recursive?: boolean };
 export type FsMkdirResponse = { path: string; revision: number };
 
 // A2 Git request/response (the Pierre-diff feed).
-export type GitFileStatusCode = "added" | "modified" | "deleted" | "renamed" | "copied" | "untracked" | "ignored" | "conflicted" | "typechange";
-export type GitFileStatus = { path: string; oldPath: string | null; index: GitFileStatusCode | null; worktree: GitFileStatusCode | null; isConflicted: boolean };
+export type GitFileStatusCode =
+  | "added"
+  | "modified"
+  | "deleted"
+  | "renamed"
+  | "copied"
+  | "untracked"
+  | "ignored"
+  | "conflicted"
+  | "typechange";
+export type GitFileStatus = {
+  path: string;
+  oldPath: string | null;
+  index: GitFileStatusCode | null;
+  worktree: GitFileStatusCode | null;
+  isConflicted: boolean;
+};
 export type GitStatusRequest = { path?: string };
-export type GitStatusResponse = { isRepo: boolean; head: string | null; detached: boolean; upstream: string | null; ahead: number; behind: number; files: GitFileStatus[]; revision: number };
+export type GitStatusResponse = {
+  isRepo: boolean;
+  head: string | null;
+  detached: boolean;
+  upstream: string | null;
+  ahead: number;
+  behind: number;
+  files: GitFileStatus[];
+  revision: number;
+};
 export type GitDiffLineType = "context" | "add" | "del" | "meta";
-export type GitDiffLine = { type: GitDiffLineType; oldNo: number | null; newNo: number | null; text: string };
-export type GitDiffHunk = { oldStart: number; oldLines: number; newStart: number; newLines: number; header: string; lines: GitDiffLine[] };
-export type GitFileDiff = { path: string; oldPath: string | null; status: GitFileStatusCode; isBinary: boolean; isImage: boolean; additions: number; deletions: number; hunks: GitDiffHunk[]; truncated: boolean };
-export type GitDiffRequest = { path?: string; staged?: boolean; fromRef?: string; toRef?: string; pathspec?: string[]; contextLines?: number; maxBytesPerFile?: number };
+export type GitDiffLine = {
+  type: GitDiffLineType;
+  oldNo: number | null;
+  newNo: number | null;
+  text: string;
+};
+export type GitDiffHunk = {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  header: string;
+  lines: GitDiffLine[];
+};
+export type GitFileDiff = {
+  path: string;
+  oldPath: string | null;
+  status: GitFileStatusCode;
+  isBinary: boolean;
+  isImage: boolean;
+  additions: number;
+  deletions: number;
+  hunks: GitDiffHunk[];
+  truncated: boolean;
+};
+export type GitDiffRequest = {
+  path?: string;
+  staged?: boolean;
+  fromRef?: string;
+  toRef?: string;
+  pathspec?: string[];
+  contextLines?: number;
+  maxBytesPerFile?: number;
+};
 export type GitDiffResponse = { files: GitFileDiff[]; revision: number };
-export type GitLogRequest = { path?: string; ref?: string; maxCount?: number; skip?: number; pathspec?: string[] };
+export type GitLogRequest = {
+  path?: string;
+  ref?: string;
+  maxCount?: number;
+  skip?: number;
+  pathspec?: string[];
+};
 export type GitCommit = {
   sha: string;
   shortSha: string;
@@ -633,12 +885,139 @@ export type GitCommit = {
   refs: string[];
 };
 export type GitLogResponse = { commits: GitCommit[]; hasMore: boolean };
-export type GitShowRequest = { path?: string; ref: string; filePath?: string; encoding?: FsEncoding; maxBytesPerFile?: number };
-export type GitShowResponse = { commit: GitCommit | null; files: GitFileDiff[]; blob: { content: string; encoding: FsEncoding; sizeBytes: number; truncated: boolean } | null; revision: number };
+export type GitShowRequest = {
+  path?: string;
+  ref: string;
+  filePath?: string;
+  encoding?: FsEncoding;
+  maxBytesPerFile?: number;
+};
+export type GitShowResponse = {
+  commit: GitCommit | null;
+  files: GitFileDiff[];
+  blob: { content: string; encoding: FsEncoding; sizeBytes: number; truncated: boolean } | null;
+  revision: number;
+};
+
+// Workbench v2 turn-end capture (mirror of `@opengeni/contracts` WorkspaceCapture*
+// + the M2 read-API response shapes, dossier §10.3). Reuses FsTreeNode /
+// GitFileStatus / GitFileDiff / GitFileStatusCode / FsEncoding above.
+export type WorkspaceCaptureFile = {
+  path: string;
+  status: GitFileStatusCode;
+  hash: string | null;
+  baseHash: string | null;
+  contentRef: string | null;
+  sizeBytes: number;
+  isBinary: boolean;
+  tooLarge: boolean;
+  deleted: boolean;
+};
+export type WorkspaceCaptureRepo = {
+  root: string;
+  head: string | null;
+  detached: boolean;
+  upstream: string | null;
+  ahead: number;
+  behind: number;
+  status: GitFileStatus[];
+  diff: GitFileDiff[];
+};
+export type WorkspaceCaptureDegradedReason =
+  | "repository_discovery_command_failed"
+  | "repository_discovery_timed_out"
+  | "repository_discovery_result_limit_exceeded";
+export type WorkspaceCaptureStats = {
+  repoCount: number;
+  fileCount: number;
+  additions: number;
+  deletions: number;
+  totalBytes: number;
+  tooLargeCount: number;
+  binaryCount: number;
+  treeEntryCount: number;
+  treeTruncated: boolean;
+  durationMs: number;
+  fingerprint?: string;
+};
+export type WorkspaceCaptureManifest = {
+  version: 1;
+  revision: number;
+  capturedAt: string;
+  turnId: string | null;
+  leaseEpoch: number;
+  treeIndex: FsTreeNode;
+  treeTruncated: boolean;
+  repos: WorkspaceCaptureRepo[];
+  files: WorkspaceCaptureFile[];
+  stats: WorkspaceCaptureStats;
+};
+export type WorkspaceRevisionCapturedPayload = {
+  revision: number;
+  turnId: string | null;
+  capturedAt: string;
+  leaseEpoch: number;
+  stats: WorkspaceCaptureStats;
+};
+export type WorkspaceRevisionDegradedPayload = {
+  revision: number;
+  turnId: string | null;
+  capturedAt: string;
+  leaseEpoch: number;
+  reason: WorkspaceCaptureDegradedReason;
+};
+export type WorkspaceCaptureSignedUrl = { url: string; expiresAt: string };
+// GET …/workspace/capture. Exactly one of manifest/manifestUrl is non-null.
+export type GetWorkspaceCaptureResponse =
+  | {
+      available: false;
+      degradedReason?: WorkspaceCaptureDegradedReason | null;
+      revision?: number | null;
+      capturedAt?: string | null;
+      turnId?: string | null;
+      leaseEpoch?: number | null;
+    }
+  | {
+      available: true;
+      revision: number;
+      capturedAt: string;
+      turnId: string | null;
+      leaseEpoch: number;
+      sizeBytes: number;
+      stats: WorkspaceCaptureStats;
+      manifest: WorkspaceCaptureManifest | null;
+      manifestUrl: WorkspaceCaptureSignedUrl | null;
+    };
+// GET …/workspace/capture/file. content inline (≤256KB) OR contentUrl OR marker
+// only (tooLarge / missing blob).
+export type GetWorkspaceCaptureFileResponse = {
+  path: string;
+  revision: number;
+  status: GitFileStatusCode;
+  hash: string | null;
+  baseHash: string | null;
+  sizeBytes: number;
+  isBinary: boolean;
+  tooLarge: boolean;
+  encoding: FsEncoding | null;
+  content: string | null;
+  contentUrl: WorkspaceCaptureSignedUrl | null;
+};
 
 // A2 Terminal exec + PTY.
-export type TerminalExecRequest = { command: string; cwd?: string; timeoutMs?: number; emitStream?: boolean };
-export type TerminalExecResponse = { stdout: string; stderr: string; exitCode: number | null; running: boolean; wallTimeSeconds: number };
+export type TerminalExecRequest = {
+  command: string;
+  cwd?: string;
+  timeoutMs?: number;
+  emitStream?: boolean;
+};
+export type TerminalExecResponse = {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  running: boolean;
+  wallTimeSeconds: number;
+};
 export type PtyOpenRequest = { cols?: number; rows?: number; cwd?: string; shell?: string };
 export type PtyOpenResponse = { ptyId: string; streamVia: "sse-events"; supportsInput: boolean };
 export type PtyWriteRequest = { ptyId: string; data: string };
@@ -705,7 +1084,11 @@ export type ScheduledTask = {
   overlapPolicy: ScheduledTaskOverlapPolicy;
   agentConfig: ScheduledTaskAgentConfig;
   reusableSessionId: string | null;
+  variableSetId: string | null;
+  /** @deprecated use variableSetId */
   environmentId: string | null;
+  // The rig each run binds to (M3); active version resolved per fire. Null ⇒ rig-less.
+  rigId: string | null;
   metadata: Record<string, unknown>;
   createdAt: string;
   updatedAt: string;
@@ -730,7 +1113,12 @@ export type CreateSessionRequest = {
   // Host working directory for a connected-machine target (the agent runs here;
   // default = the machine's launch dir). Ignored for managed sandboxes.
   workingDir?: string | undefined;
+  variableSetId?: string | undefined;
+  /** @deprecated use variableSetId */
   environmentId?: string | undefined;
+  // The rig to bind this session to (M3). Its active version is frozen onto the
+  // session at create. Omitted ⇒ the workspace default rig when set, else rig-less.
+  rigId?: string | undefined;
   goal?: GoalSpec | undefined;
   clientEventId?: string | undefined;
   // Workspace-scoped CREATE idempotency key: forward a STABLE value to make a
@@ -784,11 +1172,15 @@ export const KNOWN_PERMISSIONS = [
   "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",
 ] as const;
 
 export type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
@@ -864,8 +1256,18 @@ export type CodexUsagePayload = {
   fetchedAt: string;
   /** Present only on an auth/refresh failure path. */
   reason?: "needs_relogin";
-  additionalLimits?: Array<{ limitName: string; meteredFeature: string; fiveHour: CodexUsageWindow | null; weekly: CodexUsageWindow | null }>;
-  credits?: { hasCredits: boolean; unlimited: boolean; overageLimitReached: boolean; balance: string };
+  additionalLimits?: Array<{
+    limitName: string;
+    meteredFeature: string;
+    fiveHour: CodexUsageWindow | null;
+    weekly: CodexUsageWindow | null;
+  }>;
+  credits?: {
+    hasCredits: boolean;
+    unlimited: boolean;
+    overageLimitReached: boolean;
+    balance: string;
+  };
 };
 
 /** One connected Codex (ChatGPT) account in a workspace (multi-account P1). Metadata only. */
@@ -930,7 +1332,10 @@ export type CodexConnectPoll =
   | { status: "connected"; plan?: string | null; accountId?: string; isActive?: boolean };
 
 /** Remaining usage/limits for one account. `usage` is the normalized P2 payload. */
-export type CodexUsage = { status: "ok" | "limit_reached" | "error" | "no-data"; usage: CodexUsagePayload | null };
+export type CodexUsage = {
+  status: "ok" | "limit_reached" | "error" | "no-data";
+  usage: CodexUsagePayload | null;
+};
 
 /** Batched live-refresh response, keyed by credential id; each entry independently statused. */
 export type CodexUsageMap = Record<string, CodexUsage>;
@@ -946,6 +1351,11 @@ export type ClientAuthConfig =
   | { mode: "configuredToken"; headerName: "authorization"; scheme: "bearer" }
   | { mode: "managedSession"; session: "cookie" };
 
+// Kept value-identical to @opengeni/contracts and pinned by the SDK contract
+// parity suite. The SDK has no runtime dependency on the Zod contracts package.
+export const OPENGENI_API_CONTRACT_REVISION = "2026-07-session-control-v1" as const;
+export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+
 /**
  * Public, unauthenticated-by-default client bootstrap config returned by
  * `GET /v1/config/client`: which models + reasoning efforts are exposed, the
@@ -955,6 +1365,8 @@ export type ClientAuthConfig =
  */
 export type ClientConfig = {
   deploymentRevision: string;
+  apiContractRevision: typeof OPENGENI_API_CONTRACT_REVISION;
+  serverVersion?: string | undefined;
   defaultModel: string;
   allowedModels: string[];
   models: ClientModel[];
@@ -1009,10 +1421,33 @@ export type Workspace = {
   externalSource: string | null;
   externalId: string | null;
   agentInstructions: string | null;
+  settings: Record<string, unknown>;
+  inferenceControl: {
+    state: "active" | "paused";
+    revision: number;
+    reason: string | null;
+    changedBy: string | null;
+    changedAt: string | null;
+  };
+  defaultRigId?: string | null;
   createdAt: string;
   updatedAt: string;
 };
 
+export type WorkspaceSettings = {
+  memoryEnabled?: boolean | undefined;
+  [key: string]: unknown;
+};
+
+export type UpdateWorkspaceSettingsRequest = {
+  memoryEnabled?: boolean | undefined;
+  [key: string]: unknown;
+};
+
+export type SetWorkspaceDefaultRigRequest = {
+  rigId: string | null;
+};
+
 export type CreateWorkspaceRequest = {
   accountId?: string | undefined;
   name: string;
@@ -1124,26 +1559,175 @@ export type UpdateSessionRequest = {
 
 /** Outcome of a manual /compact trigger. */
 export type CompactSessionContextResult = {
-  /**
-   * queued: a client-side (Azure) compaction will run before the next turn.
-   * noop:   nothing to do (server-managed provider, mode off, or no history).
-   */
-  status: "queued" | "noop";
+  /** pending waits for the current safe boundary; completed ran while idle. */
+  status: "pending" | "completed" | "noop";
   message: string;
 };
 
 // --- Turn queue --------------------------------------------------------------
 
-export type UpdateSessionTurnRequest = {
-  prompt?: string | undefined;
-  resources?: ResourceRef[] | undefined;
-  tools?: ToolRef[] | undefined;
-  model?: string | undefined;
-  reasoningEffort?: ReasoningEffort | undefined;
-  sandboxBackend?: SandboxBackend | undefined;
-  metadata?: Record<string, unknown> | undefined;
+export type EffectiveControlBlocker = {
+  kind: "session" | "workspace";
+  sessionId?: string | undefined;
+  displayName: string;
+  actor: string | null;
+  reason: string | null;
+  changedAt: string | null;
+  revision: number;
+};
+
+export type EffectiveControlResumeOption = {
+  scope: "selected" | "session" | "workspace";
+  targetId?: string | undefined;
+  selectedStateAfter: "active" | "paused";
+  remainingPrimaryBlocker?: EffectiveControlBlocker | undefined;
+  impactCopy: string;
+};
+
+export type EffectiveSessionControl = {
+  state: "active" | "paused";
+  controlVersion: number;
+  controlEtag: string;
+  directState: "active" | "paused";
+  primaryBlocker: EffectiveControlBlocker | null;
+  additionalBlockerCount: number;
+  blockers: EffectiveControlBlocker[];
+  resumeOptions: EffectiveControlResumeOption[];
+  override: { rootSessionId: string; revision: number } | null;
+  settlement: { state: "stopping"; attemptCount: number } | null;
+};
+
+export type SessionCommandReceipt = {
+  id: string;
+  action: string;
+  operationKey: string;
+  targetSessionId: string | null;
+  targetTurnId: string | null;
+  appliedControlRevision: number | null;
+  appliedQueueVersion: number | null;
+  appliedTurnVersion: number | null;
+  appliedDraftRevision: number | null;
+  createdAt: string;
+};
+
+export type ComposerDraft = {
+  revision: number;
+  text: string;
+  resources: ResourceRef[];
+  tools: ToolRef[];
+  model: string;
+  reasoningEffort: ReasoningEffort;
+  sourceTurnId: string | null;
+  sourceTurnVersion: number | null;
+  updatedAt: string | null;
+};
+
+export type SessionQueueSnapshot = {
+  version: number;
+  effectiveControl: EffectiveSessionControl;
+  items: SessionTurn[];
+};
+
+export type SystemUpdateClassification = "success" | "failure" | "action_required" | "info";
+
+export type SessionSystemUpdateKind =
+  | "scheduled_occurrence"
+  | "goal_continuation"
+  | "agent_message"
+  | "agent_steer_instruction"
+  | "child_terminal_result";
+
+export type SessionSystemUpdateState =
+  | "pending"
+  | "deferred"
+  | "delivered"
+  | "cancelled"
+  | "superseded"
+  | "failed";
+
+export type SessionSystemUpdate = {
+  id: string;
+  sessionId: string;
+  kind: SessionSystemUpdateKind;
+  classification: SystemUpdateClassification;
+  sourceId: string;
+  dedupeKey: string;
+  summary: string;
+  payload: Record<string, unknown>;
+  lineage: Record<string, unknown>;
+  state: SessionSystemUpdateState;
+  deliveredTurnId: string | null;
+  deliveredAt: string | null;
+  createdAt: string;
+};
+
+export type SessionControlResponse = {
+  receipt: SessionCommandReceipt;
+  effectiveControl: EffectiveSessionControl;
+  interruptionCount: number;
+  wakeCount: number;
+};
+
+export type WorkspaceInferenceControlResponse = {
+  receipt: SessionCommandReceipt;
+  state: "active" | "paused";
+  revision: number;
+  interruptionCount: number;
+  wakeCount: number;
+};
+
+export type WorkspaceControlEvent = {
+  id: string;
+  workspaceId: string;
+  /** Same monotonic value as revision; named sequence for SSE resume cursors. */
+  sequence: number;
+  revision: number;
+  type: "workspace.control.changed";
+  scope: "workspace" | "session";
+  rootSessionId: string | null;
+  action: "pause" | "resume";
+  automatic: boolean;
+  reason: string | null;
+  actor: string;
+  occurredAt: string;
+};
+
+export type SessionQueueMutationResponse = {
+  receipt: SessionCommandReceipt;
+  snapshot: SessionQueueSnapshot;
+  draft?: ComposerDraft;
+};
+
+export type MoveSessionQueueItemRequest = {
+  clientEventId: string;
+  expectedQueueVersion: number;
+  beforeTurnId: string | null;
+};
+
+export type EditSessionQueueItemRequest = {
+  clientEventId: string;
+  expectedTurnVersion: number;
+  expectedDraftRevision: number;
+  replaceDraft: boolean;
+};
+
+export type SteerSessionQueueItemRequest = {
+  clientEventId: string;
+  expectedTurnVersion: number;
+  controlEtag?: string;
 };
 
+export type DeleteSessionQueueItemRequest = {
+  clientEventId: string;
+  expectedTurnVersion: number;
+  reason?: string;
+};
+
+export type SaveComposerDraftRequest = Omit<
+  ComposerDraft,
+  "revision" | "sourceTurnId" | "sourceTurnVersion" | "updatedAt"
+> & { expectedRevision: number };
+
 // --- Scheduled tasks: requests + runs ----------------------------------------
 
 /** Input shape for agent config on create/update (server applies defaults). */
@@ -1165,7 +1749,11 @@ export type CreateScheduledTaskRequest = {
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig: ScheduledTaskAgentConfigInput;
   status?: ScheduledTaskStatus | undefined;
+  variableSetId?: string | null | undefined;
+  /** @deprecated use variableSetId */
   environmentId?: string | null | undefined;
+  // The rig each run binds to (M3); active version resolved per fire.
+  rigId?: string | null | undefined;
   metadata?: Record<string, unknown> | undefined;
 };
 
@@ -1176,7 +1764,11 @@ export type UpdateScheduledTaskRequest = {
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig?: ScheduledTaskAgentConfigInput | undefined;
   status?: ScheduledTaskStatus | undefined;
+  variableSetId?: string | null | undefined;
+  /** @deprecated use variableSetId */
   environmentId?: string | null | undefined;
+  // The rig each run binds to (M3); active version resolved per fire.
+  rigId?: string | null | undefined;
   metadata?: Record<string, unknown> | undefined;
 };
 
@@ -1200,43 +1792,171 @@ export type ScheduledTaskRun = {
   updatedAt: string;
 };
 
-// --- Environments -------------------------------------------------------------
+// --- VariableSets -------------------------------------------------------------
 
 /**
  * Variable values are write-only by design: the API never returns a value, so
  * reads expose name + version metadata only. Values are decrypted exclusively
  * inside the worker at sandbox materialization time.
  */
-export type WorkspaceEnvironmentVariableMetadata = {
+export type VariableSetVariableMetadata = {
   name: string;
   version: number;
   createdAt: string;
   updatedAt: string;
 };
 
-export type WorkspaceEnvironment = {
+export type VariableSet = {
   id: string;
   accountId: string;
   workspaceId: string;
   name: string;
   description: string | null;
-  variables: WorkspaceEnvironmentVariableMetadata[];
+  variables: VariableSetVariableMetadata[];
   createdAt: string;
   updatedAt: string;
 };
 
-export type CreateWorkspaceEnvironmentRequest = {
+/** @deprecated use VariableSetVariableMetadata */
+export type WorkspaceEnvironmentVariableMetadata = VariableSetVariableMetadata;
+
+/** @deprecated use VariableSet */
+export type WorkspaceEnvironment = VariableSet;
+
+export type CreateVariableSetRequest = {
   name: string;
   description?: string | undefined;
   /** Initial variables. Values are write-only: they never come back on reads. */
   variables?: { name: string; value: string }[] | undefined;
 };
 
-export type UpdateWorkspaceEnvironmentRequest = {
+/** @deprecated use CreateVariableSetRequest */
+export type CreateWorkspaceEnvironmentRequest = CreateVariableSetRequest;
+
+export type UpdateVariableSetRequest = {
+  name?: string | undefined;
+  description?: string | null | undefined;
+};
+
+/** @deprecated use UpdateVariableSetRequest */
+export type UpdateWorkspaceEnvironmentRequest = UpdateVariableSetRequest;
+
+export type SetVariableSetVariableRequest = {
+  value: string;
+};
+
+/** @deprecated use SetVariableSetVariableRequest */
+export type SetWorkspaceEnvironmentVariableRequest = SetVariableSetVariableRequest;
+
+// --- Rigs ---------------------------------------------------------------------
+// Workspace-scoped, versioned sandbox machine definitions. Versions are
+// append-only and content-immutable; exactly one is active per rig.
+
+export type RigCheck = {
+  name: string;
+  command: string;
+};
+
+export type RigVersion = {
+  id: string;
+  rigId: string;
+  version: number;
+  image: string | null;
+  setupScript: string | null;
+  checks: RigCheck[];
+  credentialHooks: string[];
+  defaultVariableSetIds: string[];
+  changelog: string | null;
+  createdBy: string | null;
+  active: boolean;
+  createdAt: string;
+};
+
+export type RigVerificationHealth = {
+  checkHealth: "passing" | "failing" | "unknown";
+  lastVerifiedAt: string | null;
+};
+
+export type Rig = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  name: string;
+  description: string | null;
+  createdBy: string | null;
+  activeVersion: RigVersion | null;
+  activeVersionHealth?: RigVerificationHealth | null;
+  versionCount: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type RigChangeKind = "setup_append" | "definition_edit";
+
+export type RigChangeStatus = "proposed" | "verifying" | "merged" | "rejected" | "failed";
+
+export type RigCheckResult = {
+  name: string;
+  command: string;
+  exitCode: number | null;
+  output?: string | undefined;
+};
+
+export type RigChangeVerification = {
+  startedAt?: string | undefined;
+  finishedAt?: string | undefined;
+  log?: string | undefined;
+  checkResults?: RigCheckResult[] | undefined;
+  [key: string]: unknown;
+};
+
+export type RigChange = {
+  id: string;
+  rigId: string;
+  baseVersionId: string | null;
+  kind: RigChangeKind;
+  payload: Record<string, unknown>;
+  status: RigChangeStatus;
+  proposedBy: string | null;
+  verification: RigChangeVerification | null;
+  resultVersionId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CreateRigRequest = {
+  name: string;
+  description?: string | undefined;
+  image?: string | undefined;
+  setupScript?: string | undefined;
+  checks?: RigCheck[] | undefined;
+  credentialHooks?: string[] | undefined;
+  defaultVariableSetIds?: string[] | undefined;
+};
+
+export type UpdateRigRequest = {
   name?: string | undefined;
   description?: string | null | undefined;
 };
 
+export type RigSetupAppendPayload = {
+  command: string;
+  note?: string | undefined;
+};
+
+export type RigDefinitionEditPayload = {
+  image?: string | null | undefined;
+  setupScript?: string | null | undefined;
+  checks?: RigCheck[] | undefined;
+  credentialHooks?: string[] | undefined;
+  defaultVariableSetIds?: string[] | undefined;
+  changelog?: string | null | undefined;
+};
+
+export type ProposeRigChangeRequest =
+  | { kind: "setup_append"; payload: RigSetupAppendPayload }
+  | { kind: "definition_edit"; payload: RigDefinitionEditPayload };
+
 // --- Files ---------------------------------------------------------------------
 
 export type FileStatus = "pending_upload" | "ready" | "failed" | "expired" | "deleted";
@@ -1296,7 +2016,15 @@ export type UploadFileInput = {
 // --- Documents -------------------------------------------------------------------
 
 export type DocumentStatus = "queued" | "indexing" | "ready" | "failed";
-export type KnowledgeSourceKind = "manual_upload" | "meeting_transcript" | "repository" | "email" | "chat" | "document" | "web" | "other";
+export type KnowledgeSourceKind =
+  | "manual_upload"
+  | "meeting_transcript"
+  | "repository"
+  | "email"
+  | "chat"
+  | "document"
+  | "web"
+  | "other";
 export type DocumentSearchMode = "hybrid" | "vector" | "keyword";
 
 export type DocumentBase = {
@@ -1388,8 +2116,19 @@ export type DocumentSearchResponse = {
   results: DocumentSearchResult[];
 };
 
-export type KnowledgeMemoryStatus = "proposed" | "approved" | "rejected";
-export type KnowledgeMemoryKind = "semantic" | "episodic" | "procedural" | "decision" | "preference";
+export type KnowledgeMemoryStatus =
+  | "proposed"
+  | "approved"
+  | "rejected"
+  | "active"
+  | "superseded"
+  | "archived";
+export type KnowledgeMemoryKind =
+  | "semantic"
+  | "episodic"
+  | "procedural"
+  | "decision"
+  | "preference";
 
 export type KnowledgeSourceRef = {
   kind: "document_chunk" | "document" | "session_event" | "memory" | "external";
@@ -1412,6 +2151,13 @@ export type KnowledgeMemory = {
   createdBySessionId: string | null;
   reviewedBy: string | null;
   reviewedAt: string | null;
+  pinned: boolean;
+  usageCount: number;
+  lastUsedAt: string | null;
+  supersedesId: string | null;
+  supersededById: string | null;
+  validFrom: string;
+  validUntil: string | null;
   createdAt: string;
   updatedAt: string;
 };
@@ -1425,6 +2171,8 @@ export type CreateKnowledgeMemoryRequest = {
   confidence?: number | undefined;
   metadata?: Record<string, unknown> | undefined;
   createdBySessionId?: string | undefined;
+  pinned?: boolean | undefined;
+  replacesId?: string | undefined;
 };
 
 export type UpdateKnowledgeMemoryRequest = {
@@ -1436,6 +2184,7 @@ export type UpdateKnowledgeMemoryRequest = {
   confidence?: number | undefined;
   metadata?: Record<string, unknown> | undefined;
   reviewedBy?: string | undefined;
+  pinned?: boolean | undefined;
 };
 
 export type KnowledgeMemorySearchRequest = {
@@ -1446,6 +2195,27 @@ export type KnowledgeMemorySearchRequest = {
   limit?: number | undefined;
 };
 
+export type WorkspaceMemorySearchMode = "hybrid" | "vector" | "keyword";
+
+export type WorkspaceMemorySearchRequest = {
+  query: string;
+  kind?: KnowledgeMemoryKind | undefined;
+  limit?: number | undefined;
+  mode?: WorkspaceMemorySearchMode | undefined;
+};
+
+export type WorkspaceMemorySearchResult = {
+  memory: KnowledgeMemory;
+  score: number;
+  matchType: WorkspaceMemorySearchMode;
+  vectorScore: number | null;
+  keywordScore: number | null;
+};
+
+export type WorkspaceMemorySearchResponse = {
+  results: WorkspaceMemorySearchResult[];
+};
+
 // --- Capability packs ---------------------------------------------------------
 
 export type CapabilityPackConnectorAuthModel =
@@ -1494,7 +2264,7 @@ export type CapabilityPackSkill = {
   files: CapabilityPackSkillFile[];
 };
 
-export type CapabilityPackEnvironmentSpec = {
+export type CapabilityPackVariableSetSpec = {
   description: string;
   requiredVariables: string[];
   required: boolean;
@@ -1513,7 +2283,7 @@ export type CapabilityPack = {
   connectors: CapabilityPackConnector[];
   knowledge: CapabilityPackKnowledge[];
   scheduledTaskTemplates: CapabilityPackScheduledTaskTemplate[];
-  environment?: CapabilityPackEnvironmentSpec | undefined;
+  variableSet?: CapabilityPackVariableSetSpec | undefined;
   metadata: Record<string, unknown>;
 };
 
@@ -1526,43 +2296,53 @@ export type RegisterCapabilityPackRequest = {
   category: string;
   version: string;
   sandboxImage?: string | undefined;
-  skills?: {
-    name: string;
-    description?: string | undefined;
-    files: CapabilityPackSkillFile[];
-  }[] | undefined;
+  skills?:
+    | {
+        name: string;
+        description?: string | undefined;
+        files: CapabilityPackSkillFile[];
+      }[]
+    | undefined;
   tools?: ToolRef[] | undefined;
-  connectors?: {
-    id: string;
-    name: string;
-    category: string;
-    authModel: CapabilityPackConnectorAuthModel;
-    providers?: string[] | undefined;
-    scopes?: string[] | undefined;
-    required?: boolean | undefined;
-    metadata?: Record<string, unknown> | undefined;
-  }[] | undefined;
-  knowledge?: {
-    type: "document_base";
-    id: string;
-    name: string;
-    description?: string | null | undefined;
-    required?: boolean | undefined;
-  }[] | undefined;
-  scheduledTaskTemplates?: {
-    id: string;
-    name: string;
-    description: string;
-    defaultSchedule: ScheduledTaskScheduleSpec;
-    defaultRunMode?: ScheduledTaskRunMode | undefined;
-    defaultOverlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
-    prompt?: string | undefined;
-  }[] | undefined;
-  environment?: {
-    description: string;
-    requiredVariables?: string[] | undefined;
-    required?: boolean | undefined;
-  } | undefined;
+  connectors?:
+    | {
+        id: string;
+        name: string;
+        category: string;
+        authModel: CapabilityPackConnectorAuthModel;
+        providers?: string[] | undefined;
+        scopes?: string[] | undefined;
+        required?: boolean | undefined;
+        metadata?: Record<string, unknown> | undefined;
+      }[]
+    | undefined;
+  knowledge?:
+    | {
+        type: "document_base";
+        id: string;
+        name: string;
+        description?: string | null | undefined;
+        required?: boolean | undefined;
+      }[]
+    | undefined;
+  scheduledTaskTemplates?:
+    | {
+        id: string;
+        name: string;
+        description: string;
+        defaultSchedule: ScheduledTaskScheduleSpec;
+        defaultRunMode?: ScheduledTaskRunMode | undefined;
+        defaultOverlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
+        prompt?: string | undefined;
+      }[]
+    | undefined;
+  variableSet?:
+    | {
+        description: string;
+        requiredVariables?: string[] | undefined;
+        required?: boolean | undefined;
+      }
+    | undefined;
   metadata?: Record<string, unknown> | undefined;
 };
 
@@ -1588,6 +2368,8 @@ export type PackInstallation = {
 };
 
 export type EnablePackRequest = {
+  variableSetId?: string | undefined;
+  /** @deprecated use variableSetId */
   environmentId?: string | undefined;
   metadata?: Record<string, unknown> | undefined;
 };
@@ -1606,7 +2388,12 @@ export type GetPackResponse = {
 
 export type CapabilityKind = "pack" | "mcp" | "api" | "skill" | "plugin";
 
-export type CapabilitySource = "built_in" | "configured" | "public_registry" | "registry" | "manual";
+export type CapabilitySource =
+  | "built_in"
+  | "configured"
+  | "public_registry"
+  | "registry"
+  | "manual";
 
 export type CapabilityInstallationStatus = "active" | "disabled";
 
@@ -1651,6 +2438,8 @@ export type CapabilityCatalogItem = {
   runtime: CapabilityRuntime;
   enabled: boolean;
   enabledReason: string | null;
+  /** The connection backing this enabled installation, or null when none is involved. */
+  connectionRef: { connectionId: string; providerDomain: string; kind: string } | null;
   metadata: Record<string, unknown>;
   createdAt?: string | undefined;
   updatedAt?: string | undefined;
@@ -1700,10 +2489,12 @@ export type EnableCapabilityRequest = {
    */
   headers?: Record<string, string> | undefined;
   /**
-   * Initial environment attachment for kind=pack capabilities — mirrors the
+   * Initial variableSet attachment for kind=pack capabilities — mirrors the
    * dedicated POST /packs/:id/enable body. Required to enable an
-   * environment.required pack through this unified path; ignored otherwise.
+   * variableSet.required pack through this unified path; ignored otherwise.
    */
+  variableSetId?: string | undefined;
+  /** @deprecated use variableSetId */
   environmentId?: string | undefined;
 };
 
@@ -1852,12 +2643,6 @@ export type UserMessageEventInput = {
   };
 };
 
-export type UserInterruptEventInput = {
-  type: "user.interrupt";
-  clientEventId?: string | undefined;
-  payload?: { reason?: string | undefined } | undefined;
-};
-
 export type UserApprovalDecisionEventInput = {
   type: "user.approvalDecision";
   clientEventId?: string | undefined;
@@ -1869,10 +2654,7 @@ export type UserApprovalDecisionEventInput = {
 };
 
 /** Control/user events a client may POST to a session's event log. */
-export type ClientSessionEventInput =
-  | UserMessageEventInput
-  | UserInterruptEventInput
-  | UserApprovalDecisionEventInput;
+export type ClientSessionEventInput = UserMessageEventInput | UserApprovalDecisionEventInput;
 
 // ── Bring-your-own-compute: Machines dashboard + per-machine metrics (M10) ────
 // Hand-written mirrors of the `@opengeni/contracts` MetricSample / MachineView /
@@ -1961,6 +2743,14 @@ export type SwapActiveSandboxResponse = {
   activeSandboxId: string | null;
   activeEpoch: number;
   reason?: string;
+  // Typed rejection discriminant (issue #341); present only when swapped is false.
+  // Mirror of the `@opengeni/contracts` SwapActiveSandboxResponse.code enum.
+  code?:
+    | "stale_pointer"
+    | "offline_enrollment"
+    | "unsupported_backend_context"
+    | "transient_establishment"
+    | "concurrent_swap";
 };
 
 // ── Self-hosted enrollment UX (design 11) ────────────────────────────────────