@opengeni/sdk 0.13.0 → 0.20.0

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { WorkspaceTranscriptionPolicy } from "./transcription";
+
 // Hand-written mirrors of the public wire shapes in `@opengeni/contracts`.
 // The SDK keeps zero runtime dependencies so it stays framework-agnostic and
 // publishable on its own; `test/contract-parity.test.ts` pins these types to
@@ -10,7 +12,6 @@ export type SessionStatus =
   | "requires_action"
   | "recovering"
   | "waiting_capacity"
-  | "paused"
   | "failed"
   | "cancelled";
 
@@ -149,7 +150,11 @@ export type StreamUrlRotatedPayload = {
   transport: "vnc-ws";
   viewerId: string | null;
 };
-export type StreamOpenedPayload = { viewerId: string; shared: boolean; viewerCount: number };
+export type StreamOpenedPayload = {
+  viewerId: string;
+  shared: boolean;
+  viewerCount: number;
+};
 export type StreamClosedPayload = {
   viewerId: string;
   reason: "client-disconnect" | "reaped" | "revoked" | "box-rollover";
@@ -165,7 +170,10 @@ export type StreamRevokedPayload = {
 // `desktop:true` opts into the un-redacted pixel plane (the consent-gated noVNC
 // stream); a terminal/files-only warm attach omits it (defaults false) so it
 // warms the box + mints the pty-ws terminal cell WITHOUT tripping the consent 409.
-export type AttachViewerRequest = { viewerId?: string | undefined; desktop?: boolean | undefined };
+export type AttachViewerRequest = {
+  viewerId?: string | undefined;
+  desktop?: boolean | undefined;
+};
 
 // Mirror of `@opengeni/contracts` ViewerHolder + the P4.2 desktop-stream fields
 // the POST /viewers handler folds in when the pixel plane is minted in-process.
@@ -203,7 +211,10 @@ export type AcknowledgeStreamRequest = {
   acknowledgeUnredacted?: boolean | undefined;
   acknowledgeShared?: boolean | undefined;
 };
-export type AcknowledgeStreamResponse = { acknowledged: boolean; acknowledgedShared: boolean };
+export type AcknowledgeStreamResponse = {
+  acknowledged: boolean;
+  acknowledgedShared: boolean;
+};
 
 // Mirror of `@opengeni/contracts` ViewerHeartbeatRequest/Response — the
 // Channel-A viewer-liveness ping, epoch-fenced (a stale-epoch beat → alive:false
@@ -213,14 +224,24 @@ export type ViewerHeartbeatResponse = { alive: boolean };
 
 export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 export type GitCredentialProvider = "github" | "gitlab" | "azure_devops";
+export type GitCredentialBindingId = string;
+export type GitRepositoryAccess = "read" | "write";
 
 export type RepositoryResourceRef = {
   kind: "repository";
   uri: string;
   ref: string;
+  /**
+   * Optional workspace-relative override. When omitted, OpenGeni persists
+   * `repos/<encoded-host>/<owner>/<repo>` so equal names on different Git
+   * providers do not collide. Explicit paths are portable, traversal-free, and
+   * collision-checked case-insensitively before sandbox execution.
+   */
   mountPath?: string | undefined;
   subpath?: string | undefined;
   provider?: GitCredentialProvider | undefined;
+  credentialBindingId?: GitCredentialBindingId | undefined;
+  access?: GitRepositoryAccess | undefined;
   repositoryId?: number | string | undefined;
   installationId?: number | string | undefined;
   projectId?: number | string | undefined;
@@ -232,6 +253,7 @@ export type RepositoryResourceRef = {
 export type FileResourceRef = {
   kind: "file";
   fileId: string;
+  /** Optional workspace-relative override; defaults to `files/<file-id>`. */
   mountPath?: string | undefined;
 };
 
@@ -255,7 +277,10 @@ export type SessionMcpServerInput = {
   allowedTools?: string[] | undefined;
   timeoutMs?: number | undefined;
   cacheToolsList?: boolean | undefined;
+  /** Require human approval for every tool, or only the listed unprefixed tool names. */
+  requireApproval?: boolean | string[] | undefined;
   headers?: Record<string, string> | undefined;
+  connectionRef?: McpServerConnectionRef | undefined;
 };
 
 export type SessionMcpCredentialUpdateInput = {
@@ -269,6 +294,7 @@ export type SessionMcpServerMetadata = {
   url: string;
   headerNames: string[];
   credentialVersion: number;
+  connectionRef: McpServerConnectionRef | null;
 };
 
 export type ConnectionKind = "oauth2" | "api_key" | "app_install" | "delegated";
@@ -276,10 +302,17 @@ export type ConnectionStatus = "active" | "needs_reauth" | "revoked" | "error";
 
 export type McpServerConnectionRef = {
   connectionId?: string | undefined;
+  provider?: string | undefined;
   providerDomain: string;
   kind?: ConnectionKind | undefined;
   scopes?: string[] | undefined;
   resource?: string | undefined;
+  selectedResources?:
+    | Array<{
+        id: string;
+        kind: "repository";
+      }>
+    | undefined;
   subjectScope?: "workspace" | "subject" | undefined;
 };
 
@@ -355,6 +388,20 @@ export type OAuthStartResponse = {
   expiresAt: string;
 };
 
+/** The immutable principal whose authority accepted a session or turn. */
+export type TurnInitiator = {
+  kind: "subject" | "service";
+  subjectId: string;
+  /** Display-only snapshot; never an authorization input. */
+  label?: string | undefined;
+};
+
+/** A trusted embedding host's causal machine/service principal. */
+export type ServiceTurnInitiator = TurnInitiator & { kind: "service" };
+
+/** Bounded host provenance; OpenGeni-owned lineage keys are reserved. */
+export type ServiceTurnInitiatorContext = Record<string, unknown>;
+
 export type IntegrationClientMetadata = {
   client_id: string;
   client_name: "OpenGeni";
@@ -378,6 +425,9 @@ export type Session = {
   resources: ResourceRef[];
   tools: ToolRef[];
   metadata: Record<string, unknown>;
+  /** Frozen creator fact; later turns carry their own independent initiator. */
+  createdBy: TurnInitiator;
+  createdByContext: Record<string, unknown>;
   model: string;
   sandboxBackend: SandboxBackend;
   sandboxOs: SandboxOs;
@@ -400,12 +450,7 @@ export type Session = {
   queueVersion: number;
   queueHeadPosition: number;
   queueTailPosition: number;
-  controlState: "active" | "paused";
-  controlGeneration: number;
-  controlReason: string | null;
-  controlChangedBy: string | null;
-  controlChangedAt: string | null;
-  workspaceRunExceptionGeneration: number | null;
+  effectiveControl: EffectiveSessionControl;
   lastSequence: number;
   /** Multi-account Codex (P1): the account this session is pinned to (null ⇒ follow workspace active). */
   codexPinnedCredentialId?: string | null;
@@ -427,17 +472,26 @@ export type Session = {
         attentionDescendants: number;
         pausedDescendants: number;
         failedDescendants: number;
+        /** Counts are lower bounds rather than exact totals when true. */
+        truncated: boolean;
       }
     | undefined;
   createdAt: string;
   updatedAt: string;
 };
 
+/** Additive receipt returned by POST /sessions. */
+export type CreateSessionResponse = Session & {
+  initialTurnId: string | null;
+};
+
 export type SessionSummary = Session;
 
 /** Canonical session-list page; pinned rows are excluded from ordinary pages. */
 export type SessionListResponse = {
   pinned: Session[];
+  /** True when the server omitted older pins from its bounded pinned section. */
+  pinnedTruncated?: boolean;
   sessions: Session[];
   nextCursor: string | null;
 };
@@ -467,7 +521,8 @@ export type SessionTurnStatus =
   | "completed"
   | "failed"
   | "cancelled"
-  | "superseded";
+  | "superseded"
+  | "withdrawn_for_edit";
 
 export type SessionTurnSource =
   | "user"
@@ -498,6 +553,8 @@ export type SessionTurn = {
   executionGeneration: number;
   activeAttemptId: string | null;
   lineage: Record<string, unknown>;
+  initiator: TurnInitiator;
+  initiatorContext: Record<string, unknown>;
   cancelledBy?: string | null;
   cancelReason?: string | null;
   startedAt: string | null;
@@ -506,10 +563,74 @@ export type SessionTurn = {
   updatedAt: string;
 };
 
+export type HumanInputQuestionKind = "text" | "single_select" | "multi_select";
+
+export type HumanInputOption = {
+  id: string;
+  label: string;
+  description?: string | null | undefined;
+};
+
+export type HumanInputQuestion = {
+  id: string;
+  kind: HumanInputQuestionKind;
+  prompt: string;
+  label?: string | null | undefined;
+  helpText?: string | null | undefined;
+  options: HumanInputOption[];
+  required: boolean;
+  allowOther: boolean;
+  validation?:
+    | {
+        minLength?: number | null | undefined;
+        maxLength?: number | null | undefined;
+        minSelections?: number | null | undefined;
+        maxSelections?: number | null | undefined;
+      }
+    | null
+    | undefined;
+};
+
+export type HumanInputAnswer = {
+  questionId: string;
+  values: string[];
+  other?: string | null | undefined;
+};
+
+export type HumanInputResponse =
+  | { outcome: "answered"; answers: HumanInputAnswer[] }
+  | { outcome: "skipped" | "expired" | "cancelled" };
+
+export type SubmitHumanInputResponseRequest =
+  | { outcome: "answered"; answers: HumanInputAnswer[] }
+  | { outcome: "skipped" };
+
+export type SessionHumanInputRequest = {
+  id: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  turnGeneration: number;
+  creationAttemptId: string;
+  toolCallId: string;
+  status: "pending" | "answered" | "skipped" | "expired" | "cancelled";
+  questions: HumanInputQuestion[];
+  allowSkip: boolean;
+  response: HumanInputResponse | null;
+  respondedBy: string | null;
+  respondedAt: string | null;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
 export const SESSION_EVENT_TYPES = [
   "session.created",
+  // Defensive bounded projection for malformed/legacy oversized envelopes.
+  "session.event.envelope_omitted",
   "session.status.changed",
   "session.requiresAction",
+  "session.humanInput.requested",
   "session.context.compaction.requested",
   "session.context.compacted",
   "session.context.compaction.skipped",
@@ -517,6 +638,7 @@ export const SESSION_EVENT_TYPES = [
   "user.message",
   "user.pause",
   "user.approvalDecision",
+  "user.humanInputResponse",
   "turn.queued",
   "turn.started",
   "turn.completed",
@@ -532,6 +654,7 @@ export const SESSION_EVENT_TYPES = [
   "agent.toolCall.output",
   "agent.model.usage",
   "tool.auth_needed",
+  "credential.auth_needed",
   "agent.updated",
   "rig.setup.started",
   "rig.setup.completed",
@@ -556,6 +679,7 @@ export const SESSION_EVENT_TYPES = [
   "session.control.steer_requested",
   "workspace.inference.paused",
   "workspace.inference.resumed",
+  "session.queue.changed",
   "session.queue.prompt.cancelled",
   "session.queue.history",
   "turn.event.rejected_late",
@@ -581,9 +705,9 @@ 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.
+  // credential allocator metadata-only per-turn credential selection audit.
   "codex.credential.selected",
-  // OPE-21 durable zero-capacity wait lifecycle. These are system/runtime
+  // credential allocator durable zero-capacity wait lifecycle. These are system/runtime
   // events, never synthetic user messages.
   "codex.capacity.waiting",
   "codex.capacity.resumed",
@@ -639,14 +763,78 @@ export type SessionEvent = {
   duplicateReason?: string | null | undefined;
 };
 
+export type SessionEventSemanticClass =
+  | "control"
+  | "terminal"
+  | "failure"
+  | "checkpoint"
+  | "tool_receipt"
+  | "provider_account";
+export type SessionEventPayloadMode = "none" | "summary" | "full";
+export type SessionEventReadMode = "monitoring" | "forensic";
+export type SessionEventReadDirection = "after" | "before";
+
+type SessionEventListCommonOptions = {
+  after?: number;
+  before?: number;
+  limit?: number;
+  compact?: boolean;
+  mode?: SessionEventReadMode;
+  direction?: SessionEventReadDirection;
+  payloadMode?: SessionEventPayloadMode;
+};
+
+export type SessionEventListOptions = SessionEventListCommonOptions &
+  (
+    | {
+        latest?: never;
+        includeTypes?: SessionEventType[];
+        excludeTypes?: SessionEventType[];
+        includeClasses?: SessionEventSemanticClass[];
+        excludeClasses?: SessionEventSemanticClass[];
+      }
+    | {
+        /** Exclusive lookup for the newest event in exactly this semantic class. */
+        latest: SessionEventSemanticClass;
+        includeTypes?: never;
+        excludeTypes?: never;
+        includeClasses?: never;
+        excludeClasses?: never;
+      }
+  );
+
+export type SessionEventPage = {
+  events: SessionEvent[];
+  mode: SessionEventReadMode;
+  payloadMode: SessionEventPayloadMode;
+  direction: SessionEventReadDirection;
+  bytes: number;
+  maxBytes: number;
+  truncated: boolean;
+  hasMore: boolean;
+  truncatedBy: "count" | "bytes" | "http_bytes" | null;
+  coveredSequence: { first: number; last: number } | null;
+  nextAfter: number | null;
+  nextBefore: number | null;
+  forensicExact: boolean;
+};
+
 export type ToolAuthNeededPayload = {
   serverId: string;
   toolName?: string | null | undefined;
   providerDomain: string;
+  provider?: string | undefined;
   connectionId?: string | null | undefined;
-  reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed";
+  reason:
+    | "missing_connection"
+    | "expired"
+    | "insufficient_scope"
+    | "refresh_failed"
+    | "unsupported_auth"
+    | "resource_scope_unavailable";
   scopes?: string[] | undefined;
   resource?: string | undefined;
+  selectedResources?: Array<{ id: string; kind: "repository" }> | undefined;
   authorizationUrl?: string | undefined;
   subjectId?: string | null | undefined;
 };
@@ -775,8 +963,16 @@ export type FsListRequest = {
   maxEntries?: number;
   includeHidden?: boolean;
 };
-export type FsListResponse = { root: FsTreeNode; revision: number; truncated: boolean };
-export type FsReadRequest = { path: string; encoding?: FsEncoding; maxBytes?: number };
+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;
@@ -793,7 +989,11 @@ export type FsWriteRequest = {
   overwrite?: boolean;
   createParents?: boolean;
 };
-export type FsWriteResponse = { path: string; sizeBytes: number; revision: number };
+export type FsWriteResponse = {
+  path: string;
+  sizeBytes: number;
+  revision: number;
+};
 export type FsDeleteRequest = { path: string; recursive?: boolean };
 export type FsDeleteResponse = { revision: number };
 export type FsMoveRequest = {
@@ -802,7 +1002,11 @@ export type FsMoveRequest = {
   overwrite?: boolean;
   createParents?: boolean;
 };
-export type FsMoveResponse = { path: string; newPath: string; revision: number };
+export type FsMoveResponse = {
+  path: string;
+  newPath: string;
+  revision: number;
+};
 export type FsMkdirRequest = { path: string; recursive?: boolean };
 export type FsMkdirResponse = { path: string; revision: number };
 
@@ -864,6 +1068,7 @@ export type GitFileDiff = {
 export type GitDiffRequest = {
   path?: string;
   staged?: boolean;
+  includeUntracked?: boolean;
   fromRef?: string;
   toRef?: string;
   pathspec?: string[];
@@ -899,12 +1104,17 @@ export type GitShowRequest = {
 export type GitShowResponse = {
   commit: GitCommit | null;
   files: GitFileDiff[];
-  blob: { content: string; encoding: FsEncoding; sizeBytes: number; truncated: boolean } | null;
+  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 /
+// + the M2 read-API response shapes). Reuses FsTreeNode /
 // GitFileStatus / GitFileDiff / GitFileStatusCode / FsEncoding above.
 export type WorkspaceCaptureFile = {
   path: string;
@@ -1022,8 +1232,17 @@ export type TerminalExecResponse = {
   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 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 };
 export type PtyResizeRequest = { ptyId: string; cols: number; rows: number };
 export type PtyCloseRequest = { ptyId: string };
@@ -1099,7 +1318,13 @@ export type ScheduledTask = {
 };
 
 export type CreateSessionRequest = {
+  // Optional UUID preallocated by an embedding host so it can durably link its
+  // projection before OpenGeni admits the initial turn. Replays must retain the
+  // same UUID and idempotency key.
+  requestedSessionId?: string | undefined;
   initialMessage: string;
+  /** System instructions scoped to the initial turn; never visible timeline text. */
+  turnInstructions?: string | undefined;
   // Per-session agent persona/system instructions (org-visible metadata, not a
   // secret). Delivered system-level, composed AFTER the per-workspace persona —
   // how a host supplies per-agent-type prompts without leaking them into the
@@ -1154,7 +1379,7 @@ export const KNOWN_PERMISSIONS = [
   "sessions:create",
   "sessions:read",
   "sessions:control",
-  // Sandbox-surfacing (mirror of @opengeni/contracts Permission). stream:view is
+  // sandbox workspace (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.
@@ -1227,7 +1452,11 @@ export type CodexConnectionStatus = {
   lastError?: string | null;
   models?: ClientModel[];
   /** The account a session runs on when unpinned (label for the in-session indicator). */
-  activeAccount?: { id: string; label?: string | null; chatgptAccountId?: string | null } | null;
+  activeAccount?: {
+    id: string;
+    label?: string | null;
+    chatgptAccountId?: string | null;
+  } | null;
   /** How many Codex accounts the workspace has connected. */
   accountCount?: number;
 };
@@ -1333,7 +1562,12 @@ export type CodexConnectStart = {
 export type CodexConnectPoll =
   | { status: "pending" }
   | { status: "expired" }
-  | { status: "connected"; plan?: string | null; accountId?: string; isActive?: boolean };
+  | {
+      status: "connected";
+      plan?: string | null;
+      accountId?: string;
+      isActive?: boolean;
+    };
 
 /** Remaining usage/limits for one account. `usage` is the normalized P2 payload. */
 export type CodexUsage = {
@@ -1355,6 +1589,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-turn-instructions-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
@@ -1364,6 +1603,8 @@ export type ClientAuthConfig =
  */
 export type ClientConfig = {
   deploymentRevision: string;
+  apiContractRevision: typeof OPENGENI_API_CONTRACT_REVISION;
+  serverVersion?: string | undefined;
   defaultModel: string;
   allowedModels: string[];
   models: ClientModel[];
@@ -1377,7 +1618,11 @@ export type ClientConfig = {
   // at all (P4.4). Per-session availability is negotiated on /stream-capabilities;
   // this is the coarse on/off the client uses to decide whether to even attempt
   // the fs/git/terminal panels.
-  structuredServices: { fileSystem: boolean; git: boolean; terminalEvents: boolean };
+  structuredServices: {
+    fileSystem: boolean;
+    git: boolean;
+    terminalEvents: boolean;
+  };
 };
 
 export type AccountRole = "owner" | "admin" | "member";
@@ -1398,6 +1643,8 @@ export type AccessGrant = {
   subjectLabel?: string | undefined;
   permissions: Permission[];
   metadata?: Record<string, unknown> | undefined;
+  serviceInitiator?: ServiceTurnInitiator | undefined;
+  serviceInitiatorContext?: ServiceTurnInitiatorContext | undefined;
 };
 
 export type AccessContext = {
@@ -1419,11 +1666,13 @@ export type Workspace = {
   externalId: string | null;
   agentInstructions: string | null;
   settings: Record<string, unknown>;
-  inferenceState?: "active" | "paused";
-  inferenceGeneration?: number;
-  inferenceReason?: string | null;
-  inferenceChangedBy?: string | null;
-  inferenceChangedAt?: string | null;
+  inferenceControl: {
+    state: "active" | "paused";
+    revision: number;
+    reason: string | null;
+    changedBy: string | null;
+    changedAt: string | null;
+  };
   defaultRigId?: string | null;
   createdAt: string;
   updatedAt: string;
@@ -1431,11 +1680,13 @@ export type Workspace = {
 
 export type WorkspaceSettings = {
   memoryEnabled?: boolean | undefined;
+  transcription?: WorkspaceTranscriptionPolicy | undefined;
   [key: string]: unknown;
 };
 
 export type UpdateWorkspaceSettingsRequest = {
   memoryEnabled?: boolean | undefined;
+  transcription?: WorkspaceTranscriptionPolicy | undefined;
   [key: string]: unknown;
 };
 
@@ -1561,29 +1812,90 @@ export type CompactSessionContextResult = {
 
 // --- Turn queue --------------------------------------------------------------
 
+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;
+    interruptionPendingCount: number;
+    quiescencePendingCount: 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;
-  controlState: "active" | "paused";
-  controlGeneration: number;
-  workspaceInferenceState: "active" | "paused";
-  workspaceInferenceGeneration: number;
-  workspaceRunExceptionGeneration: number | null;
+  effectiveControl: EffectiveSessionControl;
+  /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+  stoppingPreviousAttempt: boolean;
   items: SessionTurn[];
 };
 
 export type SystemUpdateClassification = "success" | "failure" | "action_required" | "info";
 
 export type SessionSystemUpdateKind =
-  | "child_session_update"
-  | "scheduled_wake"
-  | "lifecycle_event"
-  | "runtime_notice";
+  | "scheduled_occurrence"
+  | "goal_continuation"
+  | "agent_message"
+  | "agent_steer_instruction"
+  | "child_terminal_result";
 
 export type SessionSystemUpdateState =
   | "pending"
   | "deferred"
   | "delivered"
   | "cancelled"
+  | "superseded"
   | "failed";
 
 export type SessionSystemUpdate = {
@@ -1603,33 +1915,92 @@ export type SessionSystemUpdate = {
 };
 
 export type SessionControlResponse = {
-  operationId: string;
-  event: SessionEvent;
-  controlState: "active" | "paused";
-  controlGeneration: number;
-  expectedActiveTurnId: string | null;
-  expectedExecutionGeneration: number | null;
-  expectedAttemptId: string | null;
-  deliveryEventId: string | null;
-  shouldSignalControl: boolean;
-  shouldWake: boolean;
+  receipt: SessionCommandReceipt;
+  effectiveControl: EffectiveSessionControl;
+  interruptionCount: number;
+  wakeCount: number;
 };
 
 export type WorkspaceInferenceControlResponse = {
-  operationId: string;
+  receipt: SessionCommandReceipt;
   state: "active" | "paused";
-  generation: number;
-  affectedSessionIds: string[];
-  controlSessionIds: string[];
-  exceptionSessionIds: string[];
+  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;
+  truncation?: {
+    truncated: true;
+    surface:
+      | "durable_control"
+      | "database_guard"
+      | "http_projection"
+      | "nats_legacy_guard"
+      | "sse_legacy_guard";
+    deliveredBytes: number;
+    fields: Array<{
+      field: "reason" | "actor";
+      originalBytes: number;
+      deliveredBytes: number;
+      omittedBytes: number;
+    }>;
+    fullEvidence: {
+      available: false;
+      reason: "not_retained";
+    };
+  } | null;
 };
 
 export type SessionQueueMutationResponse = {
+  receipt: SessionCommandReceipt;
   snapshot: SessionQueueSnapshot;
-  events: SessionEvent[];
-  shouldWake: boolean;
+  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). */
@@ -2292,6 +2663,7 @@ export type CapabilityKind = "pack" | "mcp" | "api" | "skill" | "plugin";
 
 export type CapabilitySource =
   | "built_in"
+  | "library"
   | "configured"
   | "public_registry"
   | "registry"
@@ -2341,7 +2713,11 @@ export type CapabilityCatalogItem = {
   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;
+  connectionRef: {
+    connectionId: string;
+    providerDomain: string;
+    kind: string;
+  } | null;
   metadata: Record<string, unknown>;
   createdAt?: string | undefined;
   updatedAt?: string | undefined;
@@ -2421,13 +2797,29 @@ export type GitHubRepository = {
   accountType: string | null;
 };
 
+export type GitHubRepositoryScope = "all" | "selected";
+
+export type GitHubInstallationBinding = {
+  installationId: number;
+  accountLogin: string | null;
+  accountType: string | null;
+  repositoryScope: GitHubRepositoryScope;
+  repositoryCount: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
 export type GitHubAppInfo = {
   configured: boolean;
   appId: string | null;
   clientId: string | null;
   appSlug: string | null;
-  /** Ready-to-open GitHub install URL (carries the signed state), if configured. */
+  /** Reserved compatibility field; null while new installation binding is disabled. */
   installUrl: string | null;
+  /** Reserved compatibility field; null while new installation binding is disabled. */
+  linkUrl: string | null;
+  /** Installation bindings owned independently by this workspace. */
+  installations: GitHubInstallationBinding[];
   /** Setting names still missing when `configured` is false. */
   missing: string[];
 };
@@ -2537,6 +2929,7 @@ export type UserMessageEventInput = {
   clientEventId?: string | undefined;
   payload: {
     text: string;
+    turnInstructions?: string | undefined;
     resources?: ResourceRef[] | undefined;
     tools?: ToolRef[] | undefined;
     model?: string | undefined;
@@ -2555,8 +2948,20 @@ export type UserApprovalDecisionEventInput = {
   };
 };
 
+export type UserHumanInputResponseEventInput = {
+  type: "user.humanInputResponse";
+  clientEventId?: string | undefined;
+  payload: {
+    requestId: string;
+    response: SubmitHumanInputResponseRequest;
+  };
+};
+
 /** Control/user events a client may POST to a session's event log. */
-export type ClientSessionEventInput = UserMessageEventInput | UserApprovalDecisionEventInput;
+export type ClientSessionEventInput =
+  | UserMessageEventInput
+  | UserApprovalDecisionEventInput
+  | UserHumanInputResponseEventInput;
 
 // ── Bring-your-own-compute: Machines dashboard + per-machine metrics (M10) ────
 // Hand-written mirrors of the `@opengeni/contracts` MetricSample / MachineView /