@opengeni/sdk 0.15.0 → 0.23.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
@@ -148,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";
@@ -164,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.
@@ -202,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
@@ -212,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;
@@ -231,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;
 };
 
@@ -239,6 +262,35 @@ export type ResourceRef = RepositoryResourceRef | FileResourceRef;
 export type ToolRef = {
   kind: "mcp";
   id: string;
+  optional?: boolean | undefined;
+};
+
+export type SessionToolPolicy = {
+  mode: "workspace_default" | "explicit" | "inherited" | "legacy";
+  inheritedFromSessionId: string | null;
+};
+
+export type SessionEffectiveToolPolicy = {
+  mode: SessionToolPolicy["mode"];
+  inheritedFromSessionId: string | null;
+  selectedIds: string[];
+  effectiveIds: string[];
+  mandatoryIds: string[];
+  lazyRouter: {
+    state: "required" | "disabled";
+    deferredIds: string[];
+  };
+  configuredIds: string[];
+  droppedIds: string[];
+  counts: {
+    selected: number;
+    effective: number;
+    mandatory: number;
+    deferred: number;
+    configured: number;
+    dropped: number;
+  };
+  idsTruncated: boolean;
 };
 
 export type GoalSpec = {
@@ -254,7 +306,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 = {
@@ -262,12 +317,25 @@ export type SessionMcpCredentialUpdateInput = {
   headers: Record<string, string>;
 };
 
+export type SessionMcpApprovalPolicy = boolean | string[];
+
 export type SessionMcpServerMetadata = {
   id: string;
   name: string | null;
   url: string;
   headerNames: string[];
   credentialVersion: number;
+  requireApproval: SessionMcpApprovalPolicy;
+  connectionRef: McpServerConnectionRef | null;
+};
+
+export type UpdateSessionMcpApprovalPolicyRequest = {
+  requireApproval: SessionMcpApprovalPolicy;
+};
+
+export type UpdateSessionMcpApprovalPolicyResponse = {
+  server: SessionMcpServerMetadata;
+  effectiveFrom: "next_attempt";
 };
 
 export type ConnectionKind = "oauth2" | "api_key" | "app_install" | "delegated";
@@ -275,10 +343,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;
 };
 
@@ -354,6 +429,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";
@@ -376,7 +465,12 @@ export type Session = {
   instructions: string | null;
   resources: ResourceRef[];
   tools: ToolRef[];
+  toolPolicy?: SessionToolPolicy | undefined;
+  effectiveToolPolicy?: SessionEffectiveToolPolicy | undefined;
   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;
@@ -421,17 +515,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;
 };
@@ -484,6 +587,7 @@ export type SessionTurn = {
   prompt: string;
   resources: ResourceRef[];
   tools: ToolRef[];
+  toolsProvided?: boolean | undefined;
   model: string;
   reasoningEffort: ReasoningEffort;
   sandboxBackend: SandboxBackend;
@@ -493,6 +597,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;
@@ -501,10 +607,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",
@@ -512,6 +682,7 @@ export const SESSION_EVENT_TYPES = [
   "user.message",
   "user.pause",
   "user.approvalDecision",
+  "user.humanInputResponse",
   "turn.queued",
   "turn.started",
   "turn.completed",
@@ -525,8 +696,10 @@ export const SESSION_EVENT_TYPES = [
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "agent.model.request",
   "agent.model.usage",
   "tool.auth_needed",
+  "credential.auth_needed",
   "agent.updated",
   "rig.setup.started",
   "rig.setup.completed",
@@ -575,11 +748,12 @@ export const SESSION_EVENT_TYPES = [
   "terminal.pty.output.delta",
   "terminal.pty.exited",
   "session.title_set",
+  "session.mcp.approval_policy.updated",
   // 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",
@@ -635,14 +809,137 @@ export type SessionEvent = {
   duplicateReason?: string | null | undefined;
 };
 
+export type SessionEventSemanticClass =
+  | "control"
+  | "terminal"
+  | "failure"
+  | "checkpoint"
+  | "tool_receipt"
+  | "provider_account";
+export type SessionEventLatestClass = SessionEventSemanticClass | "receipt";
+export type SessionEventPayloadMode = "none" | "summary" | "full";
+export type SessionEventReadMode = "monitoring" | "forensic";
+export type SessionEventReadDirection = "after" | "before";
+export type SessionEventResultMode = "events" | "compact";
+
+type SessionEventListCommonOptions = {
+  after?: number;
+  before?: number;
+  limit?: number;
+  compact?: boolean;
+  mode?: SessionEventReadMode;
+  direction?: SessionEventReadDirection;
+  payloadMode?: SessionEventPayloadMode;
+  resultMode?: "events";
+};
+
+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: SessionEventLatestClass;
+        includeTypes?: never;
+        excludeTypes?: never;
+        includeClasses?: never;
+        excludeClasses?: never;
+      }
+  );
+
+export type SessionEventCompactResult = {
+  version: 1;
+  semanticClass: SessionEventSemanticClass;
+  source: {
+    id: string;
+    type: SessionEventType;
+    sequence: number;
+    occurredAt: string;
+    turnId: string | null;
+    turnGeneration: number | null;
+    turnAttemptId: string | null;
+    turnAssociation: SessionEvent["turnAssociation"];
+  };
+  id: string;
+  type: SessionEventType;
+  sequence: number;
+  occurredAt: string;
+  turnId: string | null;
+  turnGeneration: number | null;
+  turnAttemptId: string | null;
+  turnAssociation: SessionEvent["turnAssociation"];
+  coveredSequence: { first: number; last: number };
+  status:
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "superseded"
+    | "checkpoint"
+    | "receipt"
+    | "unknown";
+  text: string | null;
+  output: unknown;
+  result: unknown;
+  failure: {
+    error: string | null;
+    code: string | null;
+    retryable: boolean | null;
+    recovery: string | null;
+  } | null;
+  checkpoint: unknown;
+  receipt: unknown;
+  truncation: {
+    truncated: boolean;
+    fields: string[];
+    originalBytes: number | null;
+    deliveredBytes: number;
+  };
+};
+
+export type SessionEventCompactResultOptions = {
+  latest: SessionEventLatestClass;
+  resultMode: "compact";
+  mode?: SessionEventReadMode;
+  payloadMode?: SessionEventPayloadMode;
+};
+
+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;
 };
@@ -771,8 +1068,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;
@@ -789,7 +1094,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 = {
@@ -798,7 +1107,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 };
 
@@ -860,6 +1173,7 @@ export type GitFileDiff = {
 export type GitDiffRequest = {
   path?: string;
   staged?: boolean;
+  includeUntracked?: boolean;
   fromRef?: string;
   toRef?: string;
   pathspec?: string[];
@@ -895,12 +1209,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;
@@ -1018,8 +1337,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 };
@@ -1095,7 +1423,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
@@ -1150,7 +1484,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.
@@ -1193,6 +1527,68 @@ export type Permission = KnownPermission | (string & {});
 
 export type ProductAccessMode = "local" | "configured" | "managed";
 
+export type ModelCapabilitySupportV1 = "supported" | "unsupported" | "unknown";
+
+export type ModelCapabilityStateV1 = {
+  upstream: ModelCapabilitySupportV1;
+  runnable: boolean;
+};
+
+export type ModelCapabilitiesV1 = {
+  reasoning: ModelCapabilityStateV1 & {
+    efforts: ReasoningEffort[];
+    defaultEffort: ReasoningEffort | null;
+    required: boolean;
+  };
+  functionCalling: ModelCapabilityStateV1;
+  structuredOutput: ModelCapabilityStateV1;
+  hostedTools: {
+    webSearch: ModelCapabilityStateV1;
+    xSearch: ModelCapabilityStateV1;
+    codeExecution: ModelCapabilityStateV1;
+  };
+  inputModalities: Array<"text" | "image" | "audio">;
+  outputModalities: Array<"text" | "image" | "audio">;
+  transports: {
+    sse: ModelCapabilityStateV1;
+    responsesWebSocket: ModelCapabilityStateV1;
+    realtimeAudio: ModelCapabilityStateV1;
+  };
+  latencyModes: Array<{
+    id: "standard" | "priority" | "fast";
+    upstream: ModelCapabilitySupportV1;
+    runnable: boolean;
+    billingMultiplierBps?: number | undefined;
+  }>;
+};
+
+export type ModelCredentialSourceV1 =
+  | { kind: "deployment"; mechanism: "api_key" | "azure_ad_bearer" }
+  | { kind: "connected_subscription"; provider: "codex" }
+  | { kind: "workspace_connection"; mechanism: "api_key" };
+
+export type ModelBillingAttributionV1 = {
+  upstreamPayer: "deployment" | "workspace" | "connected_subscription";
+  metering: "opengeni_credits" | "external";
+};
+
+export type ModelPricingV1 = {
+  inputMicrosPerMillionTokens: number;
+  cachedInputMicrosPerMillionTokens?: number | undefined;
+  outputMicrosPerMillionTokens: number;
+  marginBps?: number | undefined;
+};
+
+export type ModelPricingScheduleV1 = {
+  default: ModelPricingV1;
+  inputTokenTiers?:
+    | Array<{
+        minimumInputTokens: number;
+        pricing: ModelPricingV1;
+      }>
+    | undefined;
+};
+
 /**
  * One model a client may select at send time, plus the provider that serves it.
  * The wire API (`responses` | `chat`) lets a client reason about provider
@@ -1207,6 +1603,64 @@ export type ClientModel = {
   providerLabel: string;
   api: "responses" | "chat";
   contextWindowTokens?: number | undefined;
+  schemaVersion?: 1 | undefined;
+  aliases?: string[] | undefined;
+  deployment?:
+    | {
+        upstreamModelId: string;
+        wireApi: "responses" | "chat";
+      }
+    | undefined;
+  executionLimits?:
+    | {
+        contextWindowTokens: number | null;
+        effectiveContextWindowTokens: number | null;
+        autoCompactTokenLimit: number | null;
+        toolOutputTruncationTokens: number | null;
+      }
+    | undefined;
+  credentialSource?: ModelCredentialSourceV1 | undefined;
+  billing?: ModelBillingAttributionV1 | undefined;
+  capabilities?: ModelCapabilitiesV1 | undefined;
+  pricing?: ModelPricingScheduleV1 | undefined;
+  definitionVersion?: string | undefined;
+};
+
+export type ModelAvailabilityV1 = {
+  status: "available" | "unavailable" | "degraded" | "unknown";
+  selectable: boolean;
+  reason:
+    | "missing_credential"
+    | "needs_reauth"
+    | "credential_not_ready"
+    | "not_entitled"
+    | "provider_unhealthy"
+    | "policy_blocked"
+    | "unsupported"
+    | null;
+  checkedAt: string | null;
+};
+
+export type ModelCredentialReadinessV1 = {
+  status: "ready" | "not_ready" | "error";
+  reason:
+    | "missing_credential"
+    | "needs_reauth"
+    | "prerequisites_missing"
+    | "resolver_error"
+    | "observation_stale"
+    | null;
+  basis: "configuration" | "connection" | "resolver";
+  checkedAt: string | null;
+};
+
+export type WorkspaceModelCatalogModel = ClientModel & {
+  credentialReadiness: ModelCredentialReadinessV1;
+  availability: ModelAvailabilityV1;
+};
+
+export type WorkspaceModelCatalogResponse = {
+  models: WorkspaceModelCatalogModel[];
 };
 
 /**
@@ -1223,7 +1677,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;
 };
@@ -1254,6 +1712,8 @@ export type CodexUsagePayload = {
   weekly: CodexUsageWindow | null;
   limitReached: boolean;
   fetchedAt: string;
+  /** Authoritative count-only summary from /wham/usage; never synthesized rows. */
+  rateLimitResetCredits?: { availableCount: number; credits: null } | null;
   /** Present only on an auth/refresh failure path. */
   reason?: "needs_relogin";
   additionalLimits?: Array<{
@@ -1290,6 +1750,76 @@ export type CodexAccount = {
   // P3 rotation cooldown: ISO timestamp until which this account is cooling-down
   // (rotated-off after a usage cap). null/absent ⇒ not cooling.
   exhaustedUntil?: string | null;
+  /** Controls only NEW automatic allocations. */
+  allocatorEnabled: boolean;
+  /** Independent OCC sequence; credential/token `version` is never exposed. */
+  allocatorVersion: number;
+  allocatorUpdatedAt?: string | null;
+  /** Cached authoritative summary count, never detailed redemption authority. */
+  resetCreditAvailableCount?: number | null;
+  resetCreditsCheckedAt?: string | null;
+};
+
+export type CodexResetCredit = {
+  id: string;
+  resetType: "codexRateLimits" | "unknown";
+  status: "available" | "redeeming" | "redeemed" | "unknown";
+  /** Unix seconds from the provider contract. */
+  grantedAt: number;
+  /** Unix seconds, or null when the provider reports no expiry. */
+  expiresAt: number | null;
+  title: string | null;
+  description: string | null;
+  /** True only for fresh, complete, owning-human provider detail. */
+  actionable: boolean;
+};
+
+/** Owning-human recovery metadata. It contains no token, browser-session hash, or provider key. */
+export type CodexResetRedemptionRecovery = {
+  attemptId: string;
+  creditId: string;
+  status: "provider_started" | "completed";
+  outcome: "reset" | "nothingToReset" | "noCredit" | "alreadyRedeemed" | null;
+  providerStartedAt: string | null;
+  completedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CodexAccountOverview = {
+  accountId: string;
+  usage: {
+    source: "provider" | "cache" | "none";
+    fetchedAt: string | null;
+    stale: boolean;
+    error: string | null;
+    value: CodexUsagePayload | null;
+  };
+  resetCredits: {
+    source: "provider" | "cache" | "none";
+    fetchedAt: string | null;
+    stale: boolean;
+    error: string | null;
+    detailState: "detailed" | "count_only" | "capped" | "unsupported" | "unknown" | "error";
+    detailsComplete: boolean;
+    availableCount: number | null;
+    credits: CodexResetCredit[];
+  };
+  canRedeem: boolean;
+  /** Owning managed-cookie human may replay durable completion without a healthy provider token. */
+  canResumeRedemption: boolean;
+  /** Durable owner-scoped ambiguity/completion discovery; never redemption authority for agents. */
+  redemptions: CodexResetRedemptionRecovery[];
+};
+
+/** Independently settled live overview keyed by workspace credential id. */
+export type CodexOverviewResponse = { accounts: Record<string, CodexAccountOverview> };
+
+export type CodexAllocatorUpdate = {
+  allocatorEnabled: boolean;
+  allocatorVersion: number;
+  allocatorUpdatedAt: string | null;
+  changed: boolean;
 };
 
 /** Per-workspace Codex rotation/active settings. P1: rotation inert, only activeCredentialId loads. */
@@ -1329,7 +1859,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 = {
@@ -1353,7 +1888,7 @@ export type ClientAuthConfig =
 
 // 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_REVISION = "2026-07-turn-instructions-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
 
 /**
@@ -1380,7 +1915,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";
@@ -1401,6 +1940,8 @@ export type AccessGrant = {
   subjectLabel?: string | undefined;
   permissions: Permission[];
   metadata?: Record<string, unknown> | undefined;
+  serviceInitiator?: ServiceTurnInitiator | undefined;
+  serviceInitiatorContext?: ServiceTurnInitiatorContext | undefined;
 };
 
 export type AccessContext = {
@@ -1436,11 +1977,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;
 };
 
@@ -1594,7 +2137,12 @@ export type EffectiveSessionControl = {
   blockers: EffectiveControlBlocker[];
   resumeOptions: EffectiveControlResumeOption[];
   override: { rootSessionId: string; revision: number } | null;
-  settlement: { state: "stopping"; attemptCount: number } | null;
+  settlement: {
+    state: "stopping";
+    attemptCount: number;
+    interruptionPendingCount: number;
+    quiescencePendingCount: number;
+  } | null;
 };
 
 export type SessionCommandReceipt = {
@@ -1615,6 +2163,8 @@ export type ComposerDraft = {
   text: string;
   resources: ResourceRef[];
   tools: ToolRef[];
+  /** False inherits the session policy; true preserves an explicit array. */
+  toolsProvided: boolean;
   model: string;
   reasoningEffort: ReasoningEffort;
   sourceTurnId: string | null;
@@ -1625,6 +2175,8 @@ export type ComposerDraft = {
 export type SessionQueueSnapshot = {
   version: number;
   effectiveControl: EffectiveSessionControl;
+  /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+  stoppingPreviousAttempt: boolean;
   items: SessionTurn[];
 };
 
@@ -1690,6 +2242,26 @@ export type WorkspaceControlEvent = {
   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 = {
@@ -1976,6 +2548,67 @@ export type FileAsset = {
   updatedAt: string;
 };
 
+/** Mirrors the closed, provider-neutral retained-output contract. */
+export const RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
+export const RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
+
+export type RetainedOutputKind =
+  | "tool_result"
+  | "assistant_completion"
+  | "internal_update"
+  | "event_media"
+  | "file";
+
+export type RetainedOutputUnavailableReason =
+  | "not_retained"
+  | "pending"
+  | "failed"
+  | "expired"
+  | "deleted"
+  | "missing_storage"
+  | "storage_write_failed"
+  | "unsupported";
+
+export type RetainedArtifactReference = {
+  available: true;
+  artifactId: string;
+  kind: RetainedOutputKind;
+  contentType: string;
+  originalBytes: number;
+  sha256: string;
+  retainedAt: string;
+  retention: { policy: "workspace_file"; expiresAt: null };
+  retrieval: {
+    method: "GET";
+    path: string;
+    acceptRanges: "bytes";
+    maxRangeBytes: number;
+  };
+};
+
+export type RetainedArtifactUnavailable = {
+  available: false;
+  artifactId: string;
+  reason: RetainedOutputUnavailableReason;
+};
+
+export type RetainedArtifactMetadata = RetainedArtifactReference | RetainedArtifactUnavailable;
+
+export type RetainedArtifactContentOptions = {
+  /** One RFC-style bytes range, for example `bytes=1048576-2097151`. */
+  range?: string | undefined;
+  signal?: AbortSignal | undefined;
+};
+
+export type RetainedArtifactContent = {
+  bytes: Uint8Array;
+  status: 200 | 206;
+  contentType: string;
+  contentLength: number;
+  contentRange: string | null;
+  acceptRanges: "bytes";
+};
+
 export type CreateFileUploadRequest = {
   filename: string;
   contentType: string;
@@ -2390,6 +3023,7 @@ export type CapabilityKind = "pack" | "mcp" | "api" | "skill" | "plugin";
 
 export type CapabilitySource =
   | "built_in"
+  | "library"
   | "configured"
   | "public_registry"
   | "registry"
@@ -2406,6 +3040,17 @@ export type CapabilityRuntime = {
   mcpServerId?: string | undefined;
   transport?: string | undefined;
   notes: string | null;
+  /** Secret-safe server-derived registry exposure state. */
+  catalogTrust?:
+    | {
+        state: "trusted" | "legacy_active" | "unverified";
+        reason:
+          | "trusted_source"
+          | "verified_probe"
+          | "active_installation_compatibility"
+          | "missing_verification";
+      }
+    | undefined;
 };
 
 export type CapabilityCatalogItem = {
@@ -2439,7 +3084,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;
@@ -2519,13 +3168,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[];
 };
@@ -2635,6 +3300,7 @@ export type UserMessageEventInput = {
   clientEventId?: string | undefined;
   payload: {
     text: string;
+    turnInstructions?: string | undefined;
     resources?: ResourceRef[] | undefined;
     tools?: ToolRef[] | undefined;
     model?: string | undefined;
@@ -2653,8 +3319,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 /