@opengeni/sdk 0.4.0 → 0.6.0

package/README.md

@@ -101,6 +101,40 @@ const file = await client.uploadFile(workspaceId, {
 const { url } = await client.createFileDownloadUrl(workspaceId, file.id);
 ```
 
+## Connected Machines (bring-your-own-compute)
+
+A session can run on an enrolled **Connected Machine** — a user's own computer —
+instead of a platform-managed sandbox. Two `createSession` fields target one:
+
+- **`targetSandboxId`** (uuid) — the machine to run on (a `MachineView.sandboxId`
+  from `listMachines`). It seeds the session's active-sandbox pointer at
+  creation, so the first turn lands on that machine.
+- **`workingDir`** (host path) — the directory the agent runs under on that
+  machine. **Only valid together with `targetSandboxId`** — `workingDir` alone is
+  a **422**. Omit it and the session runs under the machine's default workspace
+  root. Repos attached to a machine session are **not cloned** (the machine uses
+  its own git auth).
+
+```ts
+const { machines } = await client.listMachines(workspaceId);
+const box = machines.find((m) => m.kind === "selfhosted" && m.state === "online");
+
+const session = await client.createSession(workspaceId, {
+  initialMessage: "Run the test suite and fix what's red",
+  targetSandboxId: box!.sandboxId, // seeds the active-sandbox pointer at create
+  workingDir: "/home/me/projects/app", // requires targetSandboxId, else 422
+});
+
+// Re-point a running session's active sandbox (or "session"/"default" to swap
+// back to its own managed box):
+await client.swapActiveSandbox(workspaceId, session.id, { target: box!.sandboxId });
+```
+
+Discovery (`listMachines`, `machineMetricsSeries`), the active-sandbox swap, and
+the enrollment methods (`mintEnrollToken`, `lookupDeviceEnrollment`,
+`approveDeviceEnrollment`, `denyDeviceEnrollment`) are covered in the
+[Connected Machines guide](../../docs/connected-machines.md).
+
 ## Full API coverage
 
 Every public endpoint group has typed methods:
@@ -108,7 +142,8 @@ Every public endpoint group has typed methods:
 | Group | Methods |
 | --- | --- |
 | Access + workspaces | `getAccessContext`, `listWorkspaces`, `createWorkspace`, `getWorkspace`, `updateWorkspace` |
-| Sessions + events | `createSession`, `listSessions`, `getSession`, `listEvents`, `sendEvent`, `sendMessage`, `steerMessage`, `interrupt`, `sendApprovalDecision`, `streamEvents`, `openEventStream` |
+| Sessions + events | `createSession`, `listSessions`, `getSession`, `updateSession`, `listEvents`, `sendEvent`, `sendMessage`, `steerMessage`, `interrupt`, `sendApprovalDecision`, `streamEvents`, `openEventStream` |
+| Machines (bring-your-own-compute) | `listMachines`, `machineMetricsSeries`, `swapActiveSandbox`, `mintEnrollToken`, `lookupDeviceEnrollment`, `approveDeviceEnrollment`, `denyDeviceEnrollment` |
 | Turn queue | `listTurns`, `updateQueuedTurn`, `reorderQueuedTurns`, `deleteQueuedTurn` |
 | Goal | `getGoal`, `updateGoal`, `pauseGoal`, `resumeGoal` |
 | Scheduled tasks | `createScheduledTask`, `listScheduledTasks`, `getScheduledTask`, `updateScheduledTask`, `pauseScheduledTask`, `resumeScheduledTask`, `triggerScheduledTask`, `deleteScheduledTask`, `listScheduledTaskRuns` |

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 type SessionStatus = "queued" | "running" | "idle" | "requires_action" | "failed" | "cancelled";
-type SandboxBackend = "docker" | "modal" | "local" | "none" | "daytona" | "runloop" | "e2b" | "blaxel" | "cloudflare" | "vercel";
+type SandboxBackend = "docker" | "modal" | "local" | "none" | "daytona" | "runloop" | "e2b" | "blaxel" | "cloudflare" | "vercel" | "selfhosted";
 type SandboxOs = "linux" | "macos" | "windows";
 type SandboxCapabilityName = "FileSystem" | "Terminal" | "Git" | "DesktopStream" | "Recording";
-type CapabilityUnavailableReason = "backend_unsupported" | "os_unsupported" | "not_provisioned" | "disabled_by_policy" | "lease_cold" | "tier_headless";
+type CapabilityUnavailableReason = "backend_unsupported" | "os_unsupported" | "not_provisioned" | "disabled_by_policy" | "lease_cold" | "tier_headless" | "agent_offline" | "agent_reconnecting" | "consent_required" | "display_unavailable";
 type SessionCapabilities = {
     sessionId: string;
     backend: SandboxBackend;
@@ -32,8 +32,8 @@ type SessionCapabilities = {
         reason: CapabilityUnavailableReason | null;
     };
     DesktopStream: {
-        transport: "vnc-ws" | "rdp-ws" | "webrtc" | null;
-        client: "novnc" | "web-rdp" | null;
+        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;
@@ -154,6 +154,8 @@ type Session = {
     accountId: string;
     status: SessionStatus;
     initialMessage: string;
+    title: string | null;
+    titleSource: "user" | "agent" | null;
     resources: ResourceRef[];
     tools: ToolRef[];
     metadata: Record<string, unknown>;
@@ -165,6 +167,10 @@ 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;
 };
@@ -191,7 +197,7 @@ type SessionTurn = {
     createdAt: string;
     updatedAt: string;
 };
-declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.status.changed", "session.requiresAction", "session.context.compacted", "session.context.cleared", "user.message", "user.interrupt", "user.approvalDecision", "turn.queued", "turn.updated", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.preempted", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.updated", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.continuation", "stream.url.rotated", "stream.opened", "stream.closed", "stream.revoked", "recording.started", "recording.available", "recording.failed", "fs.changed", "git.changed", "terminal.pty.started", "terminal.pty.output.delta", "terminal.pty.exited"];
+declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.status.changed", "session.requiresAction", "session.context.compacted", "session.context.cleared", "user.message", "user.interrupt", "user.approvalDecision", "turn.queued", "turn.updated", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.preempted", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.updated", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.continuation", "stream.url.rotated", "stream.opened", "stream.closed", "stream.revoked", "recording.started", "recording.available", "recording.failed", "fs.changed", "git.changed", "terminal.pty.started", "terminal.pty.output.delta", "terminal.pty.exited", "session.title_set", "codex.account.switched"];
 type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
 /**
  * Event types the SDK knows about today, kept open so a newer OpenGeni server
@@ -597,13 +603,18 @@ type CreateSessionRequest = {
     model?: string | undefined;
     reasoningEffort?: ReasoningEffort | undefined;
     sandboxBackend?: SandboxBackend | undefined;
+    targetSandboxId?: string | undefined;
+    workingDir?: string | undefined;
     environmentId?: string | undefined;
     goal?: GoalSpec | undefined;
     clientEventId?: string | undefined;
     idempotencyKey?: string | undefined;
     firstPartyMcpPermissions?: string[] | undefined;
+    sandbox?: "shared" | "new" | {
+        groupId: string;
+    } | undefined;
 };
-declare const KNOWN_PERMISSIONS: readonly ["account:read", "account:admin", "members:manage", "workspace:create", "billing:read", "billing:manage", "workspace:read", "workspace:admin", "sessions:create", "sessions:read", "sessions:control", "stream:view", "stream:control", "stream:acknowledge", "files:upload", "files:read", "files:write", "terminal:attach", "documents:manage", "documents:search", "scheduled_tasks:manage", "scheduled_tasks:run", "github:manage", "github:use", "api_keys:manage", "environments:manage", "environments:use", "goals:manage"];
+declare const KNOWN_PERMISSIONS: readonly ["account:read", "account:admin", "members:manage", "workspace:create", "billing:read", "billing:manage", "workspace:read", "workspace:admin", "sessions:create", "sessions:read", "sessions:control", "stream:view", "stream:control", "stream:acknowledge", "files:upload", "files:read", "files:write", "terminal:attach", "documents:manage", "documents:search", "scheduled_tasks:manage", "scheduled_tasks:run", "github:manage", "github:use", "api_keys:manage", "environments:manage", "environments:use", "goals:manage", "enrollments:read", "enrollments:manage"];
 type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
 /**
  * Permissions the SDK knows about today, kept open so a newer OpenGeni server
@@ -626,6 +637,129 @@ type ClientModel = {
     api: "responses" | "chat";
     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.
+ */
+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.
+ */
+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. */
+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. */
+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;
+    fiveHour?: CodexUsageWindow | null;
+    weekly?: CodexUsageWindow | null;
+    usageCheckedAt?: string | null;
+    exhaustedUntil?: string | null;
+};
+/** Per-workspace Codex rotation/active settings. P1: rotation inert, only activeCredentialId loads. */
+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. */
+type CodexAccountsResponse = {
+    accounts: CodexAccount[];
+    activeAccountId: string | null;
+    settings: CodexRotationSettings;
+};
+/** Payload of a `codex.account.switched` session event. */
+type CodexAccountSwitchedPayload = {
+    fromAccountId: string | null;
+    toAccountId: string;
+    reason: "manual" | "exhausted" | "rotation";
+    droppedConnectors?: string[];
+};
+/** Device-code start: show `userCode` at `verificationUri`, then poll with `state`. */
+type CodexConnectStart = {
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds: number;
+    state: string;
+};
+/** Poll result: keep polling on `pending`, restart on `expired`, done on `connected`. */
+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. */
+type CodexUsage = {
+    status: "ok" | "limit_reached" | "error" | "no-data";
+    usage: CodexUsagePayload | null;
+};
+/** Batched live-refresh response, keyed by credential id; each entry independently statused. */
+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.
@@ -795,6 +929,9 @@ type UpdateSessionGoalRequest = {
     status: "paused" | "active";
     rationale?: string | undefined;
 };
+type UpdateSessionRequest = {
+    title: string;
+};
 /** Outcome of a manual /compact trigger. */
 type CompactSessionContextResult = {
     /**
@@ -1322,6 +1459,153 @@ type UserApprovalDecisionEventInput = {
 };
 /** Control/user events a client may POST to a session's event log. */
 type ClientSessionEventInput = UserMessageEventInput | UserInterruptEventInput | UserApprovalDecisionEventInput;
+/** 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. */
+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). */
+type MachineState = "online" | "reconnecting" | "offline" | "consent_required" | "display_unavailable" | "enrolling";
+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`). */
+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). */
+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. */
+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. */
+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. */
+type SwapActiveSandboxResponse = {
+    swapped: boolean;
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    reason?: string;
+};
+/** Mirror of `@opengeni/contracts` EnrollmentOs. */
+type EnrollmentOs = "linux" | "macos" | "windows";
+/** POST /v1/enrollments/device/lookup body. */
+type DeviceEnrollmentLookupRequest = {
+    userCode: string;
+};
+/** The presentational machine details the consent screen renders. */
+type DeviceEnrollmentLookupMachine = {
+    machineName: string | null;
+    os: EnrollmentOs;
+    arch: string;
+    canOfferDisplay: boolean;
+    requestsScreenControl: boolean;
+};
+/** POST /v1/enrollments/device/lookup response (no secrets, no device_code). */
+type DeviceEnrollmentLookupResponse = {
+    workspaceId: string;
+    userCode: string;
+    machine: DeviceEnrollmentLookupMachine;
+    expiresAt: string;
+};
+/** POST /v1/workspaces/:ws/enrollments/device/approve body. */
+type DeviceEnrollmentApproveRequest = {
+    userCode: string;
+    allowScreenControl?: boolean;
+};
+/** POST /v1/workspaces/:ws/enrollments/device/approve response. */
+type DeviceEnrollmentApproveResponse = {
+    approved: boolean;
+    enrollmentId: string;
+    sandboxId: string;
+    allowScreenControl: boolean;
+};
+/** POST /v1/workspaces/:ws/enrollments/device/deny body. */
+type DeviceEnrollmentDenyRequest = {
+    userCode: string;
+};
+/** POST /v1/workspaces/:ws/enrollments/device/deny response. */
+type DeviceEnrollmentDenyResponse = {
+    denied: boolean;
+};
+/** POST /v1/workspaces/:ws/enrollments/token body. */
+type MintEnrollTokenRequest = {
+    allowScreenControl?: boolean;
+};
+/** POST /v1/workspaces/:ws/enrollments/token response. The `token` is SECRET. */
+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). */
+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). */
+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). */
+type EnrollTokenExchangeResponse = {
+    credentials: EnrollmentCredentials;
+};
 
 /**
  * Transport boundary for the streaming core. The client implements it with
@@ -1412,12 +1696,70 @@ declare class OpenGeniClient {
     constructor(options: OpenGeniClientOptions);
     createSession(workspaceId: string, request: CreateSessionRequest): Promise<Session>;
     getSession(workspaceId: string, sessionId: string): Promise<Session>;
+    updateSession(workspaceId: string, sessionId: string, request: UpdateSessionRequest): Promise<Session>;
     listSessions(workspaceId: string, options?: {
         limit?: number;
     }): Promise<Session[]>;
     listTurns(workspaceId: string, sessionId: string, options?: {
         limit?: number;
     }): Promise<SessionTurn[]>;
+    /**
+     * List the workspace's machines (the Machines dashboard). Each enrolled
+     * selfhosted machine carries its derived state + latest metrics +
+     * sharedSessionCount. Pass `sessionId` for an in-session view, which adds the
+     * session's synthetic Modal group box + the active-sandbox pointer.
+     */
+    listMachines(workspaceId: string, options?: {
+        sessionId?: string;
+    }): Promise<MachinesResponse>;
+    /**
+     * Read the downsampled (~1/min) metrics series for ONE machine over a time
+     * window (default 1h). The samples are oldest-first (a left-to-right chart).
+     */
+    machineMetricsSeries(workspaceId: string, enrollmentId: string, options?: {
+        window?: "15m" | "1h" | "6h" | "24h";
+    }): Promise<MetricSample[]>;
+    /**
+     * Resolve a pending device-enrollment flow by its user_code for the click-Grant
+     * approve page (EnrollmentConsent). NO workspace in the path — the server
+     * resolves the workspace from the (globally-unique-among-pending) code, then
+     * authorizes the caller against it (enrollments:read). Rejects (404) when the
+     * code is unknown/expired OR the caller lacks the grant — the two are
+     * indistinguishable by design (no cross-workspace disclosure). Does not consume
+     * the request.
+     */
+    lookupDeviceEnrollment(userCode: string): Promise<DeviceEnrollmentLookupResponse>;
+    /**
+     * Approve a pending device-enrollment flow (the LOUD consent step). `allowScreenControl`
+     * is the authoritative screen-control consent (whole-machine is mandatory/implicit).
+     * Lands an enrollment + a selfhosted sandbox and unblocks the agent's poll.
+     */
+    approveDeviceEnrollment(workspaceId: string, request: {
+        userCode: string;
+        allowScreenControl?: boolean;
+    }): Promise<DeviceEnrollmentApproveResponse>;
+    /** Deny a pending device-enrollment flow (the explicit "no" at the approve page). */
+    denyDeviceEnrollment(workspaceId: string, request: {
+        userCode: string;
+    }): Promise<DeviceEnrollmentDenyResponse>;
+    /**
+     * Mint a short-TTL headless enroll token (the `oget_` token) for the fleet /
+     * non-interactive enroll path. The returned `token` is SECRET — surface it once
+     * with a copy-now warning; it cannot be re-read. `allowScreenControl` bakes the
+     * screen-control consent into the token.
+     */
+    mintEnrollToken(workspaceId: string, request?: {
+        allowScreenControl?: boolean;
+    }): Promise<MintEnrollTokenResponse>;
+    /**
+     * Swap a session's active sandbox (the user-authenticated equivalent of the
+     * M7 `sandbox_swap` MCP tool). `target` is a `MachineView.sandboxId` from
+     * `listMachines`, or "session"/"default" to swap back to the session's own
+     * group box. Validation (ownership/liveness/epoch fence) is server-side; the
+     * result echoes the resulting pointer (`swapped: false` + `reason` on a
+     * rejected target or a lost epoch fence).
+     */
+    swapActiveSandbox(workspaceId: string, sessionId: string, request: SwapActiveSandboxRequest): Promise<SwapActiveSandboxResponse>;
     listScheduledTasks(workspaceId: string, options?: {
         limit?: number;
     }): Promise<ScheduledTask[]>;
@@ -1699,6 +2041,47 @@ declare class OpenGeniClient {
     createBillingCheckout(request: CreateCheckoutRequest): Promise<CreateCheckoutResponse>;
     private headers;
     private url;
+    /** Connection state + the codex models the workspace may select (empty until connected). */
+    codexStatus(workspaceId: string): Promise<CodexConnectionStatus>;
+    /** Begin device-code login: show `userCode` at `verificationUri`, then poll with `state`. */
+    codexConnectStart(workspaceId: string): Promise<CodexConnectStart>;
+    /** Poll device-code authorization with the `state` from {@link codexConnectStart}. */
+    codexConnectPoll(workspaceId: string, state: string): Promise<CodexConnectPoll>;
+    /** Remaining usage / limits for the connected (ACTIVE) subscription. Back-compat. */
+    codexUsage(workspaceId: string): Promise<CodexUsage>;
+    /** Live per-account usage read (refreshes THIS account's bearer; writes the cache). */
+    codexAccountUsage(workspaceId: string, accountId: string): Promise<CodexUsage>;
+    /** Batched live refresh across every connected account, keyed by credential id. */
+    refreshCodexUsage(workspaceId: string): Promise<{
+        usage: CodexUsageMap;
+    }>;
+    /** Disconnect ALL accounts (legacy workspace-wide). Prefer `disconnectCodexAccount`. */
+    codexDisconnect(workspaceId: string): Promise<{
+        disconnected: boolean;
+    }>;
+    /** List every connected Codex account + the workspace active pointer + settings. */
+    listCodexAccounts(workspaceId: string): Promise<CodexAccountsResponse>;
+    /** Switch the workspace ACTIVE Codex account (the one unpinned sessions use). */
+    activateCodexAccount(workspaceId: string, accountId: string): Promise<{
+        activated: boolean;
+        accountId: string;
+    }>;
+    /** P3: enable/disable Codex auto-rotation and/or pick the strategy. Returns the effective settings. */
+    setCodexRotationSettings(workspaceId: string, patch: {
+        rotationEnabled?: boolean;
+        rotationStrategy?: CodexRotationSettings["rotationStrategy"];
+    }): Promise<CodexRotationSettings>;
+    /** Disconnect ONE Codex account by id (re-picks active when the removed one was active). */
+    disconnectCodexAccount(workspaceId: string, accountId: string): Promise<{
+        disconnected: boolean;
+        newActiveId: string | null;
+    }>;
+    /** Rename a Codex account (label only in P1). */
+    renameCodexAccount(workspaceId: string, accountId: string, label: string | null): Promise<CodexAccount>;
+    /** Pin (or unpin via "auto") a session's Codex account. Applies on the next turn. */
+    pinSessionCodexAccount(workspaceId: string, sessionId: string, target: string): Promise<{
+        pinned: string;
+    }>;
     private requestJson;
     /** Like `requestJson` for endpoints that respond with no body (204). */
     private requestVoid;
@@ -1919,4 +2302,4 @@ declare function ttydInputFrame(data: string): string;
 /** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
 declare function ttydResizeFrame(columns: number, rows: number): string;
 
-export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AcknowledgeStreamRequest, type AcknowledgeStreamResponse, type AddWorkspaceMemberRequest, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type AttachViewerRequest, type AttachViewerResponse, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackEnvironmentSpec, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityRuntime, type CapabilitySource, type CapabilityUnavailableReason, type ClientAuthConfig, type ClientConfig, type ClientModel, type ClientSessionEventInput, type CompactSessionContextResult, type CompleteFileUploadResponse, type ComputerUseCapability, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceRequest, type DesktopConnectionState, type DesktopRfbFactory, type DesktopRfbLike, type DesktopStreamCapability, type DesktopStreamEvent, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type EnableCapabilityRequest, type EnablePackRequest, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileSystemCapability, type FileUploadData, type FsChangeKind, type FsChangedPayload, type FsDeleteRequest, type FsDeleteResponse, type FsEncoding, type FsListRequest, type FsListResponse, type FsMkdirRequest, type FsMkdirResponse, type FsMoveRequest, type FsMoveResponse, type FsNodeType, type FsReadRequest, type FsReadResponse, type FsTreeNode, type FsWriteRequest, type FsWriteResponse, type GetPackResponse, type GitCapability, type GitChangedPayload, type GitCommit, type GitDiffHunk, type GitDiffLine, type GitDiffLineType, type GitDiffRequest, type GitDiffResponse, type GitFileDiff, type GitFileStatus, type GitFileStatusCode, type GitHubAppInfo, type GitHubRepositoriesResponse, type GitHubRepository, type GitLogRequest, type GitLogResponse, type GitShowRequest, type GitShowResponse, type GitStatusRequest, type GitStatusResponse, type GoalSpec, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type ListApiKeysResponse, type ListPacksResponse, type ListWorkspaceMembersResponse, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProxySessionEventStreamOptions, type PtyCloseRequest, type PtyOpenRequest, type PtyOpenResponse, type PtyResizeRequest, type PtyWriteRequest, type ReasoningEffort, type RecordingAvailablePayload, type RecordingCapability, type RecordingCodec, type RecordingContentType, type RecordingFailedPayload, type RecordingFailedReason, type RecordingMode, type RecordingStartedPayload, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, SESSION_EVENT_TYPES, type SandboxBackend, type SandboxCapabilityName, type SandboxCommandOutputDeltaPayload, type SandboxOs, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type Session, type SessionCapabilities, type SessionEvent, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionStatus, type SessionStatusChangedPayload, type SessionStructuredCapabilities, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type StreamClosedPayload, type StreamConnectionState, type StreamOpenedPayload, type StreamRevokedPayload, type StreamSessionEventsOptions, type StreamUrlRotatedPayload, TTYD_SUBPROTOCOL, type TerminalCapability, type TerminalExecRequest, type TerminalExecResponse, type TerminalPtyExitedPayload, type TerminalPtyOutputDeltaPayload, type TerminalPtyStartedPayload, type ToolRef, TtydClientCommand, TtydServerCommand, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionTurnRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceMemberRequest, type UpdateWorkspaceRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserInterruptEventInput, type UserMessageEventInput, type ViewerHeartbeatRequest, type ViewerHeartbeatResponse, type ViewerHolder, type Workspace, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceMember, type WorkspaceRegisteredPack, applyUrlRotation, desktopSocketUrl, formatSseEvent, isRetryableStreamError, nextDesktopState, parseSseStream, proxySessionEventStream, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents, terminalSocketUrl, ttydAuthFrame, ttydInputFrame, ttydResizeFrame };
+export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AcknowledgeStreamRequest, type AcknowledgeStreamResponse, type AddWorkspaceMemberRequest, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type AttachViewerRequest, type AttachViewerResponse, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackEnvironmentSpec, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityRuntime, type CapabilitySource, type CapabilityUnavailableReason, type ClientAuthConfig, type ClientConfig, type ClientModel, type ClientSessionEventInput, type CodexAccount, type CodexAccountSwitchedPayload, type CodexAccountsResponse, type CodexConnectPoll, type CodexConnectStart, type CodexConnectionStatus, type CodexRotationSettings, type CodexUsage, type CodexUsageMap, type CodexUsagePayload, type CodexUsageWindow, type CompactSessionContextResult, type CompleteFileUploadResponse, type ComputerUseCapability, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceRequest, type DesktopConnectionState, type DesktopRfbFactory, type DesktopRfbLike, type DesktopStreamCapability, type DesktopStreamEvent, type DeviceEnrollmentApproveRequest, type DeviceEnrollmentApproveResponse, type DeviceEnrollmentDenyRequest, type DeviceEnrollmentDenyResponse, type DeviceEnrollmentLookupMachine, type DeviceEnrollmentLookupRequest, type DeviceEnrollmentLookupResponse, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type EnableCapabilityRequest, type EnablePackRequest, type EnrollTokenExchangeRequest, type EnrollTokenExchangeResponse, type EnrollmentCredentials, type EnrollmentOs, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileSystemCapability, type FileUploadData, type FsChangeKind, type FsChangedPayload, type FsDeleteRequest, type FsDeleteResponse, type FsEncoding, type FsListRequest, type FsListResponse, type FsMkdirRequest, type FsMkdirResponse, type FsMoveRequest, type FsMoveResponse, type FsNodeType, type FsReadRequest, type FsReadResponse, type FsTreeNode, type FsWriteRequest, type FsWriteResponse, type GetPackResponse, type GitCapability, type GitChangedPayload, type GitCommit, type GitDiffHunk, type GitDiffLine, type GitDiffLineType, type GitDiffRequest, type GitDiffResponse, type GitFileDiff, type GitFileStatus, type GitFileStatusCode, type GitHubAppInfo, type GitHubRepositoriesResponse, type GitHubRepository, type GitLogRequest, type GitLogResponse, type GitShowRequest, type GitShowResponse, type GitStatusRequest, type GitStatusResponse, type GoalSpec, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type ListApiKeysResponse, type ListPacksResponse, type ListWorkspaceMembersResponse, type MachineKind, type MachineMetricsSeriesResponse, type MachineState, type MachineView, type MachinesResponse, type MetricSample, type MintEnrollTokenRequest, type MintEnrollTokenResponse, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProxySessionEventStreamOptions, type PtyCloseRequest, type PtyOpenRequest, type PtyOpenResponse, type PtyResizeRequest, type PtyWriteRequest, type ReasoningEffort, type RecordingAvailablePayload, type RecordingCapability, type RecordingCodec, type RecordingContentType, type RecordingFailedPayload, type RecordingFailedReason, type RecordingMode, type RecordingStartedPayload, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, SESSION_EVENT_TYPES, type SandboxBackend, type SandboxCapabilityName, type SandboxCommandOutputDeltaPayload, type SandboxOs, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type Session, type SessionCapabilities, type SessionEvent, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionStatus, type SessionStatusChangedPayload, type SessionStructuredCapabilities, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type StreamClosedPayload, type StreamConnectionState, type StreamOpenedPayload, type StreamRevokedPayload, type StreamSessionEventsOptions, type StreamUrlRotatedPayload, type SwapActiveSandboxRequest, type SwapActiveSandboxResponse, TTYD_SUBPROTOCOL, type TerminalCapability, type TerminalExecRequest, type TerminalExecResponse, type TerminalPtyExitedPayload, type TerminalPtyOutputDeltaPayload, type TerminalPtyStartedPayload, type ToolRef, TtydClientCommand, TtydServerCommand, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionRequest, type UpdateSessionTurnRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceMemberRequest, type UpdateWorkspaceRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserInterruptEventInput, type UserMessageEventInput, type ViewerHeartbeatRequest, type ViewerHeartbeatResponse, type ViewerHolder, type Workspace, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceMember, type WorkspaceRegisteredPack, applyUrlRotation, desktopSocketUrl, formatSseEvent, isRetryableStreamError, nextDesktopState, parseSseStream, proxySessionEventStream, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents, terminalSocketUrl, ttydAuthFrame, ttydInputFrame, ttydResizeFrame };