@opengeni/sdk 0.20.0 → 0.23.0

package/src/types.ts

@@ -262,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 = {
@@ -288,15 +317,27 @@ 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";
 export type ConnectionStatus = "active" | "needs_reauth" | "revoked" | "error";
 
@@ -424,6 +465,8 @@ 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;
@@ -544,6 +587,7 @@ export type SessionTurn = {
   prompt: string;
   resources: ResourceRef[];
   tools: ToolRef[];
+  toolsProvided?: boolean | undefined;
   model: string;
   reasoningEffort: ReasoningEffort;
   sandboxBackend: SandboxBackend;
@@ -652,6 +696,7 @@ 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",
@@ -703,6 +748,7 @@ 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",
   // credential allocator metadata-only per-turn credential selection audit.
@@ -770,9 +816,11 @@ export type SessionEventSemanticClass =
   | "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;
@@ -782,6 +830,7 @@ type SessionEventListCommonOptions = {
   mode?: SessionEventReadMode;
   direction?: SessionEventReadDirection;
   payloadMode?: SessionEventPayloadMode;
+  resultMode?: "events";
 };
 
 export type SessionEventListOptions = SessionEventListCommonOptions &
@@ -795,7 +844,7 @@ export type SessionEventListOptions = SessionEventListCommonOptions &
       }
     | {
         /** Exclusive lookup for the newest event in exactly this semantic class. */
-        latest: SessionEventSemanticClass;
+        latest: SessionEventLatestClass;
         includeTypes?: never;
         excludeTypes?: never;
         includeClasses?: never;
@@ -803,6 +852,62 @@ export type SessionEventListOptions = SessionEventListCommonOptions &
       }
   );
 
+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;
@@ -1422,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
@@ -1436,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[];
 };
 
 /**
@@ -1487,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<{
@@ -1523,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. */
@@ -1866,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;
@@ -2249,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;
@@ -2680,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 = {