@opengeni/sdk 0.5.0 → 0.6.0

package/src/types.ts

@@ -11,8 +11,9 @@ export type SessionStatus =
   | "failed"
   | "cancelled";
 
-// Mirror of `@opengeni/contracts` SandboxBackend (10 values; existing four keep
-// position). 3-way enum parity is pinned by `test/contract-parity.test.ts`.
+// Mirror of `@opengeni/contracts` SandboxBackend (11 values; every member is
+// additive at the end). 3-way enum parity is pinned by
+// `test/contract-parity.test.ts`.
 export type SandboxBackend =
   | "docker"
   | "modal"
@@ -23,7 +24,8 @@ export type SandboxBackend =
   | "e2b"
   | "blaxel"
   | "cloudflare"
-  | "vercel";
+  | "vercel"
+  | "selfhosted";
 
 // Mirror of `@opengeni/contracts` SandboxOs. Only "linux" is reachable in v1.
 export type SandboxOs = "linux" | "macos" | "windows";
@@ -43,7 +45,12 @@ export type CapabilityUnavailableReason =
   | "not_provisioned"
   | "disabled_by_policy"
   | "lease_cold"
-  | "tier_headless";
+  | "tier_headless"
+  // selfhosted (bring-your-own-compute) negotiation states:
+  | "agent_offline"
+  | "agent_reconnecting"
+  | "consent_required"
+  | "display_unavailable";
 
 // Mirror of `@opengeni/contracts` SessionCapabilities (the negotiated handshake
 // document). The descriptor table itself is NOT mirrored — it lives in
@@ -77,8 +84,10 @@ export type SessionCapabilities = {
     reason: CapabilityUnavailableReason | null;
   };
   DesktopStream: {
-    transport: "vnc-ws" | "rdp-ws" | "webrtc" | null;
-    client: "novnc" | "web-rdp" | null;
+    // "relay-frames" + "frames": the selfhosted framebuffer stream — PNG-per-frame
+    // protobuf datagrams over the relay, painted by a canvas client (NOT RFB).
+    transport: "vnc-ws" | "rdp-ws" | "webrtc" | "relay-frames" | null;
+    client: "novnc" | "web-rdp" | "frames" | null;
     mode: "read-only" | "interactive";
     url: string | null;
     token: string | null;
@@ -249,6 +258,10 @@ export type Session = {
   temporalWorkflowId: string | null;
   activeTurnId: string | null;
   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;
   createdAt: string;
   updatedAt: string;
 };
@@ -336,6 +349,8 @@ export const SESSION_EVENT_TYPES = [
   "terminal.pty.output.delta",
   "terminal.pty.exited",
   "session.title_set",
+  // Multi-account Codex (P1): the session's inference account changed.
+  "codex.account.switched",
 ] as const;
 
 export type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
@@ -578,6 +593,12 @@ export type CreateSessionRequest = {
   model?: string | undefined;
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
+  // The enrolled machine (a sandbox id) to run this session on; seeds the
+  // active-sandbox pointer at creation so the first turn lands on it.
+  targetSandboxId?: string | undefined;
+  // 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;
   environmentId?: string | undefined;
   goal?: GoalSpec | undefined;
   clientEventId?: string | undefined;
@@ -586,6 +607,13 @@ export type CreateSessionRequest = {
   // Distinct from the per-call clientEventId.
   idempotencyKey?: string | undefined;
   firstPartyMcpPermissions?: string[] | undefined;
+  // Shared-sandbox placement (mirror of `@opengeni/contracts` CreateSessionRequest.sandbox,
+  // addendum 05 §D.1). Three-way union; OMITTED ⇒ the context-dependent server default
+  // (from inside a session → "shared" with the creator's box, top-level → "new").
+  //   - "shared":  join the CREATOR's box (requires a parent session; top-level → 422).
+  //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
+  //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager fan-out).
+  sandbox?: "shared" | "new" | { groupId: string } | undefined;
 };
 
 // --- Access, workspaces, API keys -------------------------------------------
@@ -623,6 +651,8 @@ export const KNOWN_PERMISSIONS = [
   "environments:manage",
   "environments:use",
   "goals:manage",
+  "enrollments:read",
+  "enrollments:manage",
 ] as const;
 
 export type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
@@ -651,6 +681,124 @@ export type ClientModel = {
   contextWindowTokens?: number | undefined;
 };
 
+/**
+ * Connection state of a workspace's Codex (ChatGPT) subscription, returned by
+ * `GET /v1/workspaces/:id/codex/status`. `models` are the codex models the
+ * workspace can select (projected as ClientModel under their own "no credits"
+ * provider group), present only while connected.
+ */
+export type CodexConnectionStatus = {
+  connected: boolean;
+  plan?: string | null;
+  valid?: boolean;
+  expiresAt?: string | null;
+  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;
+  /** How many Codex accounts the workspace has connected. */
+  accountCount?: number;
+};
+
+/**
+ * One normalized Codex usage window (5h or weekly), camelCase end-to-end (the
+ * route normalizes server-side; the web layer never re-hand-types snake_case).
+ * `percent` is authoritative; used/limit/remaining are a synthesized 0–100 scale
+ * (limit = 100) because the provider gives only a percentage. `remaining =
+ * 100 - percent` is the P3 rotation key. Identify the window by `limitWindowSeconds`
+ * (18000 ⇒ 5h, 604800 ⇒ weekly), never by position.
+ */
+export type CodexUsageWindow = {
+  used: number;
+  limit: number;
+  remaining: number;
+  percent: number;
+  resetAt: string | null;
+  resetAfterSeconds: number | null;
+  limitWindowSeconds: number;
+};
+
+/** The normalized usage payload for one account — the P2/P3 contract. */
+export type CodexUsagePayload = {
+  status: "ok" | "limit_reached" | "error" | "no-data";
+  planType: string | null;
+  fiveHour: CodexUsageWindow | null;
+  weekly: CodexUsageWindow | null;
+  limitReached: boolean;
+  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 };
+};
+
+/** One connected Codex (ChatGPT) account in a workspace (multi-account P1). Metadata only. */
+export type CodexAccount = {
+  id: string;
+  chatgptAccountId?: string | null;
+  label?: string | null;
+  email?: string | null;
+  plan?: string | null;
+  status: "active" | "needs_relogin" | "error";
+  active: boolean;
+  expiresAt?: string | null;
+  lastRefreshAt?: string | null;
+  lastError?: string | null;
+  // P2 CACHED usage (built from the persisted columns; renders bars off
+  // listCodexAccounts with no second call). null until the first live refresh.
+  fiveHour?: CodexUsageWindow | null;
+  weekly?: CodexUsageWindow | null;
+  usageCheckedAt?: string | null;
+  // 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;
+};
+
+/** Per-workspace Codex rotation/active settings. P1: rotation inert, only activeCredentialId loads. */
+export type CodexRotationSettings = {
+  rotationEnabled: boolean;
+  rotationStrategy: "most_remaining" | "round_robin" | "drain_then_next";
+  activeCredentialId: string | null;
+};
+
+/** GET /codex/accounts — the accounts list + the workspace active pointer + settings. */
+export type CodexAccountsResponse = {
+  accounts: CodexAccount[];
+  activeAccountId: string | null;
+  settings: CodexRotationSettings;
+};
+
+/** Payload of a `codex.account.switched` session event. */
+export type CodexAccountSwitchedPayload = {
+  fromAccountId: string | null;
+  toAccountId: string;
+  reason: "manual" | "exhausted" | "rotation";
+  // P4 connector-aware rotation: the session's used connectors that the new account
+  // does NOT cover (a prefer-not-require failover that dropped a connector). Present
+  // only on such a switch; the UI renders a "dropped <connector>" badge on the pill.
+  droppedConnectors?: string[];
+};
+
+/** Device-code start: show `userCode` at `verificationUri`, then poll with `state`. */
+export type CodexConnectStart = {
+  userCode: string;
+  verificationUri: string;
+  intervalSeconds: number;
+  state: string;
+};
+
+/** Poll result: keep polling on `pending`, restart on `expired`, done on `connected`. */
+export type CodexConnectPoll =
+  | { status: "pending" }
+  | { status: "expired" }
+  | { 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 };
+
+/** Batched live-refresh response, keyed by credential id; each entry independently statused. */
+export type CodexUsageMap = Record<string, CodexUsage>;
+
 /**
  * How a deployment expects clients to authenticate to it, surfaced so a UI can
  * wire up the right header/cookie without prior knowledge of the host setup.
@@ -1472,3 +1620,187 @@ export type ClientSessionEventInput =
   | UserMessageEventInput
   | UserInterruptEventInput
   | UserApprovalDecisionEventInput;
+
+// ── Bring-your-own-compute: Machines dashboard + per-machine metrics (M10) ────
+// Hand-written mirrors of the `@opengeni/contracts` MetricSample / MachineView /
+// MachinesResponse / MachineMetricsSeriesResponse (pinned by contract-parity).
+// M9 imports THESE so the dashboard UI never drifts from the API.
+
+/** A point-in-time machine metrics sample. `gpuUtilPct`/`gpuMemBytes` are null
+ *  when no GPU was present (not-reported, never a real zero); the bytes/load are
+ *  numbers; `sampledAt` is an ISO-8601 instant. */
+export type MetricSample = {
+  cpuPct: number;
+  load1: number;
+  load5: number;
+  load15: number;
+  memUsedBytes: number;
+  memTotalBytes: number;
+  diskUsedBytes: number;
+  diskTotalBytes: number;
+  gpuUtilPct: number | null;
+  gpuMemBytes: number | null;
+  runQueue: number;
+  sampledAt: string;
+};
+
+/** The derived dashboard state of a machine (M3 liveness + consent/display
+ *  reasons + the in-flight device-flow). */
+export type MachineState =
+  | "online"
+  | "reconnecting"
+  | "offline"
+  | "consent_required"
+  | "display_unavailable"
+  | "enrolling";
+
+export type MachineKind = "modal" | "selfhosted";
+
+/** A machine as the Machines dashboard renders it (an enrolled selfhosted machine
+ *  or the session's synthetic Modal group box, `isSessionGroup: true`). */
+export type MachineView = {
+  sandboxId: string;
+  enrollmentId: string | null;
+  name: string;
+  kind: MachineKind;
+  state: MachineState;
+  active: boolean;
+  isSessionGroup: boolean;
+  os: string;
+  arch: string;
+  hasDisplay: boolean;
+  allowScreenControl: boolean;
+  sharedSessionCount: number;
+  lastSeenAt: string | null;
+  metrics: MetricSample | null;
+};
+
+/** GET /v1/workspaces/:ws/machines — the dashboard list + the active-sandbox
+ *  pointer (null activeSandboxId == the session's own group box is active). */
+export type MachinesResponse = {
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  machines: MachineView[];
+};
+
+/** GET /v1/workspaces/:ws/machines/:enrollmentId/metrics/series — the downsampled
+ *  (~1/min) history the dashboard time-range reads. */
+export type MachineMetricsSeriesResponse = {
+  samples: MetricSample[];
+};
+
+/** POST /v1/workspaces/:ws/sessions/:sessionId/active-sandbox — swap a session's
+ *  active sandbox. `target` is a `MachineView.sandboxId`, or "session"/"default"
+ *  to swap back to the session's own group box. */
+export type SwapActiveSandboxRequest = {
+  target: string;
+};
+
+/** The swap outcome (mirrors the server `FleetSwapResult`). `swapped` is true on a
+ *  successful repoint OR a no-op (already there); `reason` carries the failure
+ *  detail (unowned/offline target, or a lost epoch fence) when false. */
+export type SwapActiveSandboxResponse = {
+  swapped: boolean;
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  reason?: string;
+};
+
+// ── Self-hosted enrollment UX (design 11) ────────────────────────────────────
+// Hand-written mirrors of the `@opengeni/contracts` enrollment-UX request/response
+// shapes (the SDK keeps zero runtime deps). The click-Grant approve-page
+// lookup/deny + the headless enroll-token mint/exchange.
+
+/** Mirror of `@opengeni/contracts` EnrollmentOs. */
+export type EnrollmentOs = "linux" | "macos" | "windows";
+
+/** POST /v1/enrollments/device/lookup body. */
+export type DeviceEnrollmentLookupRequest = {
+  userCode: string;
+};
+
+/** The presentational machine details the consent screen renders. */
+export type DeviceEnrollmentLookupMachine = {
+  machineName: string | null;
+  os: EnrollmentOs;
+  arch: string;
+  canOfferDisplay: boolean;
+  requestsScreenControl: boolean;
+};
+
+/** POST /v1/enrollments/device/lookup response (no secrets, no device_code). */
+export type DeviceEnrollmentLookupResponse = {
+  workspaceId: string;
+  userCode: string;
+  machine: DeviceEnrollmentLookupMachine;
+  expiresAt: string;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/device/approve body. */
+export type DeviceEnrollmentApproveRequest = {
+  userCode: string;
+  allowScreenControl?: boolean;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/device/approve response. */
+export type DeviceEnrollmentApproveResponse = {
+  approved: boolean;
+  enrollmentId: string;
+  sandboxId: string;
+  allowScreenControl: boolean;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/device/deny body. */
+export type DeviceEnrollmentDenyRequest = {
+  userCode: string;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/device/deny response. */
+export type DeviceEnrollmentDenyResponse = {
+  denied: boolean;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/token body. */
+export type MintEnrollTokenRequest = {
+  allowScreenControl?: boolean;
+};
+
+/** POST /v1/workspaces/:ws/enrollments/token response. The `token` is SECRET. */
+export type MintEnrollTokenResponse = {
+  token: string;
+  expiresAt: string;
+  expiresInSeconds: number;
+};
+
+/** The credential payload the headless exchange returns (a subset of the agent's
+ *  EnrollmentCredentials — IDENTICAL to the device-flow poll authorized branch). */
+export type EnrollmentCredentials = {
+  agentId: string;
+  workspaceId: string;
+  bearer: string;
+  subjectPrefix: string;
+  natsUrls: string[];
+  relayUrl: string;
+  relayToken: string;
+  natsAccountCreds: string;
+  updatePublicKey: string;
+  consentedWholeMachine: boolean;
+  consentedScreenControl: boolean;
+};
+
+/** POST /v1/enrollments/token/exchange body (the headless / fleet enroll path). */
+export type EnrollTokenExchangeRequest = {
+  token: string;
+  publicKey: string;
+  os?: EnrollmentOs;
+  arch?: string;
+  machineName?: string;
+  exposure?: "whole-machine";
+  canOfferDisplay?: boolean;
+  requestsScreenControl?: boolean;
+};
+
+/** POST /v1/enrollments/token/exchange response (wraps the credential shape). */
+export type EnrollTokenExchangeResponse = {
+  credentials: EnrollmentCredentials;
+};