@opengeni/api-router 0.12.12 → 0.14.4

package/dist/sandbox/access.d.ts

@@ -0,0 +1,21 @@
+import type { Settings } from "@opengeni/config";
+export type { ApiSandboxSession, ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession, } from "@opengeni/core";
+import type { ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession } from "@opengeni/core";
+export declare class SandboxResumeError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Construct the API process's own sandbox client from settings, agent-loop-free.
+ * Returns undefined when `sandboxBackend=none` (no box to touch). The Modal
+ * token + app name are read from settings (already parsed by getSettings and
+ * present in the API runtime env), so the client can resume Modal boxes by id.
+ */
+export declare function createApiSandboxClient(settings: Settings): ApiSandboxClient | undefined;
+/**
+ * Build the `resumeBoxById` helper bound to the API's sandbox client. Given a
+ * backend + a serialized resume_state envelope, it resumes the box and returns
+ * a live session for one in-process op. The caller drives exec/readFile and then
+ * drops the handle (resume → use → drop); it does NOT own the box.
+ */
+export declare function makeResumeBoxById(client: ApiSandboxClient | undefined): (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;

package/dist/sandbox/auth-callout.d.ts

@@ -0,0 +1,30 @@
+import { type NatsCalloutConfig, type Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+import { type ResponderConnection } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+/** The NATS subject nats-server publishes authorization requests on (ADR-26). */
+export declare const AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+export interface AuthCalloutDeps {
+    db: Database;
+    settings: Settings;
+    callout: NatsCalloutConfig;
+    observability?: Observability;
+}
+/**
+ * The pure validate→scoped-JWT decision, isolated from the NATS transport so it is
+ * unit-testable. Given the raw authorization-request JWT bytes, returns the signed
+ * authorization-response JWT bytes to reply with — a GRANT (embedding a scoped user
+ * JWT) on success, a DENIAL (carrying `nats.error`, no user JWT) otherwise. NEVER
+ * throws on a bad/invalid request: every failure becomes a signed denial (the
+ * server then refuses the connection cleanly).
+ */
+export declare function handleAuthorizationRequest(deps: AuthCalloutDeps, requestBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Start the auth-callout responder: open a SEPARATE NATS connection authenticated
+ * as the callout `auth_users` user, subscribe $SYS.REQ.USER.AUTH, and answer every
+ * authorization request via {@link handleAuthorizationRequest}. Returns a handle
+ * whose `close()` drains the connection. Gated by the caller (sandboxSelfhostedEnabled
+ * + a resolvable callout config); a deployment without the callout plane never starts
+ * it.
+ */
+export declare function startAuthCalloutResponder(deps: AuthCalloutDeps, natsUrl: string): Promise<ResponderConnection>;

package/dist/sandbox/channel-a.d.ts

@@ -0,0 +1,37 @@
+import { type Settings } from "@opengeni/config";
+import type { Session } from "@opengeni/contracts";
+import { type Database, type LeaseSnapshot } from "@opengeni/db";
+import { type EventBus } from "@opengeni/events";
+import { SandboxChannelAService, type RoutingSandboxSession } from "@opengeni/runtime/sandbox";
+export type ChannelAServices = {
+    db: Database;
+    settings: Settings;
+    bus: EventBus;
+};
+export type ChannelAContext = {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+    subjectId: string;
+};
+export type ChannelAHandle = {
+    service: SandboxChannelAService;
+    /** Connected Machine homes deliberately have no cloud lease. Durable PTYs
+     * require a real home-provider lease and reject this null case. */
+    lease: LeaseSnapshot | null;
+    routingSession: RoutingSandboxSession;
+    requestId: string;
+};
+/**
+ * Run a Channel-A op against a live box, API-direct. Acquires an exact direct holder
+ * (warming the box when cold), resumes by id, builds the service, runs `fn`, and
+ * ALWAYS releases the holder + drops the handle in `finally`. Maps the service's
+ * typed errors to HTTP status (the route never sees a raw ChannelA*Error).
+ *
+ * Gated behind sandboxOwnershipEnabled at the route (the lease is dormant
+ * otherwise). A `backend:none` session has no box -> 409 before touching it.
+ */
+export declare function withChannelA<T>(services: ChannelAServices, ctx: ChannelAContext, fn: (handle: ChannelAHandle) => Promise<T>): Promise<T>;
+/** Map the service's typed errors to HTTP status (the §5.3 matrix). Re-throws an
+ *  already-HTTPException unchanged. */
+export declare function mapChannelAError(error: unknown): unknown;

package/dist/sandbox/enrollment.d.ts

@@ -0,0 +1,120 @@
+import { type Settings } from "@opengeni/config";
+import { type DeviceEnrollmentLookupResponse, type DeviceEnrollmentPollResponse, type DeviceEnrollmentStartResponse, type EnrollTokenExchangeResponse, type MintEnrollTokenResponse } from "@opengeni/contracts";
+import { type Database, type DeviceEnrollmentRequestRecord, type EnrollmentOs } from "@opengeni/db";
+export declare const DEVICE_CODE_TTL_SECONDS = 600;
+export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
+export declare const ENROLLMENT_BEARER_TTL_SECONDS: number;
+export declare const RELAY_TOKEN_TTL_SECONDS: number;
+export declare const ENROLL_TOKEN_TTL_SECONDS = 3600;
+export type EnrollmentServices = {
+    db: Database;
+    settings: Settings;
+};
+/** A workspace-scoped flow START context (the route resolves the workspace the
+ *  agent's flow binds to from the deployment edge / a workspace hint). */
+export type DeviceStartInput = {
+    accountId: string;
+    workspaceId: string;
+    publicKey: string;
+    os: EnrollmentOs;
+    arch: string;
+    machineName?: string | null;
+    canOfferDisplay: boolean;
+    requestsScreenControl: boolean;
+    verificationOrigin: string;
+};
+/**
+ * START a device-flow: persist a short-TTL single-use pending request + return the
+ * DeviceAuthStart. Retries the user_code mint on the (astronomically rare) partial-
+ * unique collision among live pending rows.
+ */
+export declare function startDeviceEnrollment(services: EnrollmentServices, input: DeviceStartInput): Promise<DeviceEnrollmentStartResponse>;
+/** APPROVE a flow by user_code (the LOUD consent step). Returns the resulting
+ *  enrollment + sandbox ids, or null when no LIVE pending request matches the code
+ *  in this workspace (an unknown/expired/already-terminal code). */
+export declare function approveDeviceEnrollment(services: EnrollmentServices, input: {
+    accountId: string;
+    workspaceId: string;
+    userCode: string;
+    allowScreenControl: boolean;
+    approvedBySubjectId: string;
+    approvedBySubjectLabel?: string | null;
+}): Promise<{
+    enrollmentId: string;
+    sandboxId: string;
+    allowScreenControl: boolean;
+} | null>;
+/** LOOK UP a pending flow by user_code GLOBALLY (the click-Grant approve page;
+ *  design 11 §B.1). Returns the resolved pending record (carrying its workspaceId)
+ *  or null when no live pending row matches the code. The ROUTE authorizes the
+ *  caller against the resolved workspaceId (enrollments:read) BEFORE exposing
+ *  anything — a failed grant OR a null here both surface as 404 so cross-workspace
+ *  existence is never revealed. This does NOT consume the request. */
+export declare function lookupDeviceEnrollment(services: EnrollmentServices, input: {
+    userCode: string;
+}): Promise<DeviceEnrollmentRequestRecord | null>;
+/** Project a resolved pending record to the presentational lookup response (no
+ *  secrets, no device_code) the approve screen (EnrollmentConsent) renders. */
+export declare function toLookupResponse(record: DeviceEnrollmentRequestRecord): DeviceEnrollmentLookupResponse;
+/** DENY a flow by user_code (the explicit "no" at the approve page; design 11
+ *  §B.2). Workspace-scoped (the route asserts the grant). Returns whether a pending
+ *  row was flipped to denied (false for an unknown / already-terminal code). */
+export declare function denyDeviceEnrollment(services: EnrollmentServices, input: {
+    accountId: string;
+    workspaceId: string;
+    userCode: string;
+}): Promise<{
+    denied: boolean;
+}>;
+/** MINT a headless enroll token (design 11 §A2.2). Signs an `oget_` token bound to
+ *  the workspace + account + the screen-control consent, with a 1h TTL. Returns
+ *  null when the credential plane is disabled (no signing secret) so the route can
+ *  mirror poll's "disabled" handling. The token value is NEVER logged. */
+export declare function mintEnrollToken(services: EnrollmentServices, input: {
+    accountId: string;
+    workspaceId: string;
+    allowScreenControl: boolean;
+}): Promise<MintEnrollTokenResponse | null>;
+/** Distinguishes the two exchange failure modes for the route. */
+export type ExchangeEnrollTokenResult = {
+    ok: true;
+    credentials: EnrollTokenExchangeResponse["credentials"];
+} | {
+    ok: false;
+    reason: "disabled";
+} | {
+    ok: false;
+    reason: "invalid";
+};
+/** EXCHANGE a headless enroll token (design 11 §A2.3) — the UNAUTHENTICATED path
+ *  where the token IS the auth. Verifies the `oget_` token, then performs the SAME
+ *  finalize as approve (upsert enrollment + ensure selfhosted sandbox,
+ *  consentedWholeMachine=true, consentedScreenControl=token.allowScreenControl) and
+ *  builds the IDENTICAL EnrollmentCredentials the poll authorized branch returns.
+ *  Returns reason "disabled" when no signing secret (mirror poll), "invalid" when
+ *  the token fails verification (the route 401s). */
+export declare function exchangeEnrollToken(services: EnrollmentServices, input: {
+    token: string;
+    publicKey: string;
+    os: EnrollmentOs;
+    arch: string;
+    machineName?: string | null;
+    canOfferDisplay: boolean;
+}): Promise<ExchangeEnrollTokenResult>;
+/**
+ * POLL a flow by device_code. Resolves the state machine:
+ *   - unknown code              → "expired" (do not leak existence; an unknown code
+ *                                  behaves like an expired one to the agent).
+ *   - pending + within TTL      → "pending".
+ *   - pending + past TTL        → "expired".
+ *   - denied                    → "denied".
+ *   - approved | consumed       → "authorized" + the EnrollmentCredentials (the
+ *                                  approved row is flipped to consumed; a legitimate
+ *                                  re-poll of a consumed row still returns the creds).
+ * When the credential plane is disabled (no resolvable signing secret), an
+ * otherwise-authorized poll returns "disabled" so the agent surfaces a clear reason
+ * rather than half-enrolling.
+ */
+export declare function pollDeviceEnrollment(services: EnrollmentServices, input: {
+    deviceCode: string;
+}): Promise<DeviceEnrollmentPollResponse>;

package/dist/sandbox/machines.d.ts

@@ -0,0 +1,29 @@
+import type { Settings } from "@opengeni/config";
+import { type Database, type MachineMetricsRow } from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import { MetricSample, type MachinesResponse } from "@opengeni/contracts";
+export type MachinesServices = {
+    db: Database;
+    settings: Settings;
+    bus?: EventBus;
+};
+/**
+ * Project a stored `machine_metrics_latest` row to the contract `MetricSample`.
+ * The DB carries `gpuUtilPercent` + `gpuMemUsedBytes`/`gpuMemTotalBytes`; the wire
+ * `MetricSample` exposes the single `gpuUtilPct` + `gpuMemBytes` (USED bytes — the
+ * "how much VRAM is in use" the dashboard reads). A null any-numeric stays null
+ * (the not-reported contract); the byte/load fields default to 0 when a sample
+ * carried no value (the agent reports 0 == not-reported for those).
+ */
+export declare function metricRowToSample(row: MachineMetricsRow): MetricSample;
+/**
+ * Build the Machines dashboard response for a workspace. When `sessionId` is
+ * supplied (an in-session view) the session's synthetic Modal group box is
+ * prepended (`isSessionGroup:true`) and the active-sandbox pointer is echoed;
+ * without it (the pure workspace dashboard) `activeSandboxId` is null and only
+ * the enrolled machines are listed.
+ */
+export declare function listMachines(services: MachinesServices, input: {
+    workspaceId: string;
+    sessionId?: string | null;
+}): Promise<MachinesResponse>;

package/dist/sandbox/metrics-ingestion.d.ts

@@ -0,0 +1,128 @@
+import { type Database, type MachineMetricsSample } from "@opengeni/db";
+import { type EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+import { Hello, type MetricsSample } from "@opengeni/agent-proto";
+/** The wildcard subject the agent event plane publishes heartbeats on. */
+export declare const AGENT_EVENTS_SUBJECT = "agent.*.*.events";
+/** The wildcard subject the agent publishes its connect Hello on. */
+export declare const AGENT_HELLO_SUBJECT = "agent.*.*.hello";
+/** Parse `agent.<ws>.<id>.events` → `{ workspaceId, agentId }` (heartbeat plane). */
+export declare function parseAgentEventSubject(subject: string): {
+    workspaceId: string;
+    agentId: string;
+} | null;
+/** Parse `agent.<ws>.<id>.hello` → `{ workspaceId, agentId }` (connect plane). */
+export declare function parseAgentHelloSubject(subject: string): {
+    workspaceId: string;
+    agentId: string;
+} | null;
+/**
+ * Project a wire `MetricsSample` (proto, ms-stamped, GPU as a repeated list) to
+ * the DB `MachineMetricsSample`. The proto byte/count fields are protobuf-encoded
+ * as decimal strings (uint64) on the TS side (ts-proto `string`); coerce to
+ * numbers. The DB carries a single `gpuUtilPercent` + `gpuMemUsedBytes`/Total —
+ * we take the FIRST GPU (the dashboard surfaces the primary accelerator); absent
+ * GPUs stay null (the not-reported contract). A zero on a non-GPU field is the
+ * agent's "not reported" (we keep it null-friendly via `nullIfZero` only for the
+ * GPU plane; cpu/mem/disk 0 is a legitimate reading the dashboard shows as 0).
+ */
+export declare function wireSampleToDbSample(wire: MetricsSample): MachineMetricsSample;
+/**
+ * Ingest ONE decoded heartbeat for an enrolled machine. Resolves the enrollment's
+ * accountId (needed for the RLS-scoped writes) from the enrollment row; an
+ * unknown/cross-workspace agentId is ignored (no row → no write). Touches
+ * last-seen + upserts latest + downsamples the series.
+ */
+export declare function ingestHeartbeat(db: Database, input: {
+    workspaceId: string;
+    agentId: string;
+    sample: MetricsSample;
+}): Promise<{
+    ingested: boolean;
+    seriesAppended: boolean;
+}>;
+/**
+ * Decode a raw `AgentEvent` payload + ingest it (the per-message handler). A
+ * heartbeat carrying a metrics sample is ingested; a going-offline records the
+ * machine-plane marker + fans out the link-plane session events. Decode failures
+ * are reported + swallowed. `bus` (when present) enables the session-event
+ * fan-out; the live consumer always supplies it, pure unit tests may omit it.
+ */
+export declare function handleAgentEventPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus): Promise<void>;
+/**
+ * Start the metrics-ingestion consumer: subscribe `agent.*.*.events` and ingest
+ * every heartbeat. Gated by sandboxSelfhostedEnabled (the caller checks the flag;
+ * a disabled deployment never starts the consumer). Returns the unsubscribe fn.
+ */
+export declare function startMetricsIngestion(deps: {
+    db: Database;
+    bus: EventBus;
+    observability?: Observability;
+}): () => void;
+/**
+ * The LIVE display presence the agent's Hello reports: a desktop framebuffer is
+ * available (`capabilities.desktop`, which the agent sets true only when a display
+ * probes AND it can stream it) OR a `Display` detail is present. An unset
+ * Capabilities (or a headless machine) → false. This is what `has_display` should
+ * track, replacing the enroll-time snapshot.
+ */
+export declare function helloReportsDisplay(hello: Hello): boolean;
+/**
+ * The human, actionable reason a display is present but UNUSABLE (macOS Screen
+ * Recording / TCC not granted), or null when capture is permitted / the machine is
+ * headless. Normalizes the proto's non-optional "" empty string to null so the DB
+ * carries a clean tri-state (a real reason vs. no reason) — the Machines dashboard
+ * shows "display: capture not granted" only when this is non-null.
+ */
+export declare function helloDesktopUnavailableReason(hello: Hello): string | null;
+/** Whether the runner's current Hello advertises the op-stream engine. */
+export declare function helloReportsOpStream(hello: Hello): boolean;
+/**
+ * Reconcile `enrollments.has_display` (+ the capture-blocked reason) to what a Hello
+ * reports. Resolves the enrollment (the accountId is the RLS principal + the
+ * existence check + the current values). A no-change Hello short-circuits BEFORE
+ * issuing any write (and the DB writer is itself change-guarded on BOTH fields as a
+ * backstop), so a steady state never churns. An unknown/cross-workspace agentId is a
+ * no-op.
+ */
+export declare function refreshEnrollmentDisplay(db: Database, input: {
+    workspaceId: string;
+    agentId: string;
+    hasDisplay: boolean;
+    desktopUnavailableReason?: string | null;
+}): Promise<{
+    updated: boolean;
+}>;
+/**
+ * Reconcile `enrollments.op_stream` to what a Hello reports. Resolves the
+ * enrollment first so the accountId remains the RLS principal and so a no-change
+ * Hello short-circuits BEFORE issuing any write (the DB writer is itself
+ * change-guarded as a backstop). An unknown/cross-workspace agentId is a no-op.
+ */
+export declare function refreshEnrollmentOpStream(db: Database, input: {
+    workspaceId: string;
+    agentId: string;
+    opStream: boolean;
+}): Promise<{
+    updated: boolean;
+}>;
+/**
+ * Decode a raw `Hello` payload + refresh the enrollment's display cursor + clear
+ * any pending clean going-offline marker and, when the reconnect actually cleared
+ * one, fan out machine.link.restored to the sessions with an active op on the
+ * machine (the per-message handler for the hello plane). Decode failures + write
+ * failures are reported + swallowed — a Hello must NEVER break the agent's connect.
+ * `bus` (when present) enables the link.restored fan-out.
+ */
+export declare function handleHelloPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus): Promise<void>;
+/**
+ * Start the Hello display-refresh consumer: subscribe `agent.*.*.hello` and
+ * reconcile `has_display` to the live capability the agent reports on every
+ * connect. Gated by sandboxSelfhostedEnabled (the caller checks the flag). Returns
+ * the unsubscribe fn.
+ */
+export declare function startHelloIngestion(deps: {
+    db: Database;
+    bus: EventBus;
+    observability?: Observability;
+}): () => void;

package/dist/sandbox/rematerialize.d.ts

@@ -0,0 +1,24 @@
+import type { Settings } from "@opengeni/config";
+import { type Database, type LeaseSnapshot } from "@opengeni/db";
+import { type EstablishedSandboxSession } from "@opengeni/runtime/sandbox";
+/** The sole API-direct cold->warming owner path used by Channel A and viewer
+ * attach. It never publishes warm until archive identity, hydrated tree, command
+ * routing, provider identity, and the selected rematerialization attempt all
+ * agree under one lease epoch. */
+export declare function establishApiSandboxSpawner(input: {
+    db: Database;
+    settings: Settings;
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    sessionId: string;
+    backend: string;
+    environment: Record<string, string>;
+    expectedEpoch: number;
+    acquiredLease: LeaseSnapshot;
+    fallbackEnvelope: Record<string, unknown> | null;
+    dataPlaneUrl: string | null;
+}): Promise<{
+    established: EstablishedSandboxSession;
+    lease: LeaseSnapshot;
+}>;

package/dist/sandbox/viewer.d.ts

@@ -0,0 +1,251 @@
+import type { Settings } from "@opengeni/config";
+import { type Session } from "@opengeni/contracts";
+import { type Database, type LeaseSnapshot, type SandboxRecord } from "@opengeni/db";
+import { type EventBus } from "@opengeni/events";
+import { establishSandboxSessionFromEnvelope, type EstablishedSandboxSession } from "@opengeni/runtime/sandbox";
+/** The minimal services a viewer op needs: the DB + settings (lease cadence +
+ *  the sandbox client construction the leaf reads from settings). The bus is
+ *  optional — only the rotation path (emitting stream.url.rotated to OTHER
+ *  viewers) needs it. */
+export type ViewerServices = {
+    db: Database;
+    settings: Settings;
+    bus?: EventBus;
+    /** Provider-establish dependency used by API-direct readiness and stream
+     *  operations. Production uses the runtime leaf; isolated tests may supply a
+     *  deterministic provider without replacing a process-global module. */
+    establishSandboxSession?: typeof establishSandboxSessionFromEnvelope;
+};
+/** A coherent snapshot the routes echo back: the holder id (the viewer's fence-
+ *  carrying handle), the lease liveness/epoch, and the recorded data-plane URL
+ *  (null until P4 mints the desktop tunnel). */
+export type ViewerAttachResult = {
+    viewerId: string;
+    liveness: LeaseSnapshot["liveness"];
+    leaseEpoch: number;
+    workspaceGeneration: number | null;
+    archiveGeneration: number | null;
+    archiveComplete: boolean;
+    sandboxGroupId: string;
+    viewerHeartbeatIntervalMs: number;
+    dataPlaneUrl: string | null;
+};
+/**
+ * The STABLE run-scoped sandbox environment a COLD box must be created with so
+ * that — whether the box is first warmed by an API-direct ATTACH (here) or by the
+ * worker TURN — its manifest environment matches the environment the agent later
+ * declares for a turn. Without this, an attach-warmed box was created with the
+ * BASE allowlist env only (establishSandboxSessionFromEnvelope's
+ * collectSandboxEnvironment default), so the next turn's fuller env (git identity
+ * + workspace environment + HOME) introduced a delta and the SDK's
+ * `validateNoEnvironmentDelta` threw "Live sandbox sessions cannot change manifest
+ * environment variables" — the BLOCKING error this fixes.
+ *
+ * Mirrors the worker turn's STABLE env (config.stableSandboxEnvironmentForRun +
+ * the session's attached, decrypted workspace environment + — for a repo-attached
+ * session — the stable git-auth POINTERS the turn declares since the token-broker:
+ * GIT_ASKPASS / GIT_TERMINAL_PROMPT / bot identity). The pointers carry NO rotating
+ * value (the token lives in the box FILE the clone hook seeds), so they are
+ * attach-reproducible; omitting them cold-created a box whose env lacked keys the
+ * next repo turn's manifest declares → the SDK guard threw "Live sandbox sessions
+ * cannot change manifest environment variables" whenever a viewer attach (an open
+ * session page) won the cold-create race against the first turn.
+ */
+export declare function sessionAttachEnvironment(services: ViewerServices, workspaceId: string, session: Session): Promise<Record<string, string>>;
+/**
+ * Acquire a `viewer` holder on the group lease, spinning up the box IN-PROCESS
+ * when cold. Mirrors the worker's resumeBoxForTurn spawner/attached branches,
+ * but with kind:'viewer' and run by the API process — no Temporal, no worker.
+ *
+ * `viewerId` is the unique-per-connection holder id (a uuid the client carries
+ * through heartbeats + detach); generated when absent.
+ */
+export declare function attachViewer(services: ViewerServices, input: {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+    viewerId?: string;
+}): Promise<ViewerAttachResult>;
+export type SessionGroupReadinessHold = {
+    lease: LeaseSnapshot;
+    /** Idempotently release the viewer holder after route publication settles. */
+    release: () => Promise<void>;
+};
+/** Readiness callback for fleet attach/swap. It acquires one disposable viewer
+ * holder through the same provider-verifying path as the UI and RETURNS that
+ * holder to the swap owner. The holder must remain live until route publication
+ * settles, otherwise the reaper can drain the just-verified target between the
+ * readiness probe and the route CAS. A first 409 may have fenced a missing warm
+ * provider; one bounded retry lets the normal cold->warming election rematerialize
+ * it. */
+export declare function ensureSessionGroupReady(services: ViewerServices, input: {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+}): Promise<SessionGroupReadinessHold>;
+/**
+ * Refresh a viewer holder's TTL (the app-level viewer heartbeat). Epoch-fenced:
+ * a stale-epoch heartbeat (a box re-established under a newer epoch) returns
+ * false and the client must re-attach. Returns whether the holder is still live.
+ */
+export declare function heartbeatViewer(services: ViewerServices, input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    viewerId: string;
+    expectedEpoch: number;
+}): Promise<boolean>;
+/**
+ * Release a viewer holder (the client disconnected). Idempotent: a double
+ * detach (or a detach after the reaper already TTL-reaped the holder) is a
+ * no-op. The box drains/stops only when no turn AND no viewer holds it.
+ */
+export declare function detachViewer(services: ViewerServices, input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    viewerId: string;
+}): Promise<{
+    liveness: LeaseSnapshot["liveness"];
+    refcount: number;
+} | null>;
+/** Non-locking lease snapshot for the capability-negotiation read. */
+export declare function readGroupLease(services: ViewerServices, input: {
+    workspaceId: string;
+    sandboxGroupId: string;
+}): Promise<LeaseSnapshot | null>;
+export declare function viewerHeartbeatIntervalMs(settings: Settings): number;
+/**
+ * The desktop WIRE transport for the session's ACTIVE sandbox — the single
+ * invariant that keeps the advertised transport in lockstep with where
+ * mintDesktopStream routed the pixels. It MUST be derived from the ACTIVE sandbox
+ * (not the session's HOME backend that negotiateCapabilities keys on): a selfhosted
+ * machine serves the RELAY framebuffer (PNG-per-frame → "relay-frames"/"frames",
+ * view-only in v1), and a Modal group box serves noVNC/RFB over the 6080 tunnel
+ * (→ "vnc-ws"/"novnc", take-control unless the deployment disabled it). Advertising
+ * relay-frames for a Modal box (the swap-away case) hands the client a dead relay
+ * socket → "desktop stream closed before it opened"; the reverse hands a machine's
+ * relay URL to the noVNC renderer. `selfhostedActive` == (activeSandboxId set AND the
+ * active sandbox kind is "selfhosted") — EXACTLY mintDesktopStream's routing predicate.
+ */
+export declare function resolveActiveDesktopTransport(selfhostedActive: boolean, interactive: boolean): {
+    transport: "relay-frames" | "vnc-ws";
+    client: "frames" | "novnc";
+    mode: "read-only" | "interactive";
+};
+/** The minted pixel cell the handshake/attach folds into the DesktopStream
+ *  capability. Null when degraded (no secret, headless backend, display-stack
+ *  failure, provider tunnel failure) — degradation is a value, never a throw. */
+export type DesktopStreamMint = {
+    url: string;
+    token: string;
+    expiresAt: string;
+    resolution: [number, number];
+    leaseEpoch: number;
+};
+export type MintDesktopStreamInput = {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+    /** The viewer holder id the scoped token is minted for. */
+    viewerId: string;
+    /** The live lease (must be warm/draining — the box is up). A selfhosted-active
+     *  session may have no Modal group lease; omit and the selfhosted branch handles it. */
+    lease?: LeaseSnapshot;
+    /** The epoch the CALLER last observed the URL minted under. When the live
+     *  lease epoch is greater, the box rolled over → emit stream.url.rotated to the
+     *  other viewers. Omit on a first mint (no prior URL to rotate from). */
+    previousEpoch?: number;
+    /** Test seam: override how the box is re-established by id. Defaults to the
+     *  real leaf `establishSandboxSessionFromEnvelope`. Production NEVER passes
+     *  this; it exists so a real-lease integration test can inject a fake provider
+     *  session carrying `resolveExposedPort` without a live cloud box. */
+    establish?: (envelope: Record<string, unknown> | null) => Promise<EstablishedSandboxSession>;
+    /** Test seam: inject a fake relay-resolving session for the selfhosted-active
+     *  branch. Production NEVER passes this. */
+    resolveSelfhostedSession?: (sandbox: SandboxRecord) => Promise<{
+        resolveExposedPort?: (port: number) => Promise<unknown>;
+    }>;
+};
+/**
+ * Mint (or re-mint) the desktop pixel cell for a viewer against a WARM box,
+ * IN-PROCESS. Returns the minted cell, or null when the desktop tier degrades
+ * (no resolvable stream-token secret, a headless backend, a display-stack
+ * failure, or a provider-tunnel failure) — the caller surfaces transport:null,
+ * never an exception to the user.
+ *
+ * Idempotent display-stack + resolveExposedPort are safe to call N times. The
+ * resolved URL is recorded on the lease (data_plane_url) under the epoch fence; a
+ * stale-epoch write (the box re-established under a newer epoch mid-call) is a
+ * no-op and the mint returns null rather than disclosing a capability for the
+ * superseded provider epoch.
+ */
+export declare function mintDesktopStream(services: ViewerServices, input: MintDesktopStreamInput): Promise<DesktopStreamMint | null>;
+/** The minted terminal cell the handshake/attach folds into the Terminal
+ *  capability (pty-ws). Null when degraded — the caller surfaces transport
+ *  "sse-events" (the read-only firehose), never an exception. */
+export type TerminalStreamMint = {
+    url: string;
+    token: string;
+    expiresAt: string;
+    leaseEpoch: number;
+};
+export type MintTerminalStreamInput = {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+    /** The viewer holder / principal id the scoped token is minted for. */
+    viewerId: string;
+    /** The live lease (must be warm/draining — the box is up). A selfhosted-active
+     *  session may have no Modal group lease; omit and the selfhosted branch handles it. */
+    lease?: LeaseSnapshot;
+    /** Test seam: override how the box is re-established by id (see
+     *  MintDesktopStreamInput.establish). Production NEVER passes this. */
+    establish?: (envelope: Record<string, unknown> | null) => Promise<EstablishedSandboxSession>;
+    /** Test seam: inject a fake relay-resolving session for the selfhosted-active
+     *  branch. Production NEVER passes this. */
+    resolveSelfhostedSession?: (sandbox: SandboxRecord) => Promise<{
+        resolveExposedPort?: (port: number) => Promise<unknown>;
+    }>;
+};
+/**
+ * Mint (or re-mint) the REAL PTY (ttyd pty-ws) terminal cell for a viewer against
+ * a WARM box, IN-PROCESS. Returns the minted cell, or null when the terminal tier
+ * degrades (terminal off, no resolvable stream-token secret, a headless backend,
+ * a ttyd-launch failure, or a provider-tunnel failure) — the caller surfaces the
+ * sse-events firehose, never an exception to the user. Mirrors mintDesktopStream.
+ */
+export declare function mintTerminalStream(services: ViewerServices, input: MintTerminalStreamInput): Promise<TerminalStreamMint | null>;
+/** The structural slice of a selfhosted session the relay stream mint needs. */
+type RelayResolvableSession = {
+    resolveExposedPort?: (port: number) => Promise<unknown>;
+};
+export type MintSelfhostedStreamInput = {
+    workspaceId: string;
+    sessionId: string;
+    /** The viewer holder / principal id the scoped token is minted for. */
+    viewerId: string;
+    /** The swap fence: the session's `active_epoch`. The minted `ogs_` token carries
+     *  THIS as its leaseEpoch claim so the relay rejects a stale-epoch (swapped-away)
+     *  viewer. */
+    activeEpoch: number;
+    /** The exposed stream port (6080 desktop / 7681 terminal). */
+    port: number;
+    /** The resolvable selfhosted session (the routing proxy resolves the active
+     *  selfhosted backend; its `resolveExposedPort` returns the relay endpoint). */
+    session: RelayResolvableSession;
+};
+/**
+ * Mint the selfhosted relay stream cell for a viewer against the session's ACTIVE
+ * selfhosted machine, IN-PROCESS. Resolves the relay endpoint via the selfhosted
+ * session's `resolveExposedPort` and mints the scoped `ogs_` token FENCED BY THE
+ * SWAP `active_epoch`. Returns null when the stream tier degrades (no stream-token
+ * secret, the agent is offline / cannot ensure a channel) — the caller surfaces
+ * transport:null, never an exception.
+ *
+ * The token is RECORDED against the viewer holder by the caller and is NEVER a URL
+ * query param (the relay validates the in-band token); the relay's stale-viewer
+ * fence uses the token's leaseEpoch claim (== activeEpoch here).
+ */
+export declare function mintSelfhostedStream(services: ViewerServices, input: MintSelfhostedStreamInput): Promise<TerminalStreamMint | null>;
+export {};

package/dist/transcription/providers/azure-openai.d.ts

@@ -0,0 +1,9 @@
+import type { TranscriptionProvider } from "@opengeni/core";
+export declare function createAzureOpenAiTranscriptionProvider(input: {
+    endpoint: string;
+    deployment: string;
+    apiVersion: string;
+    apiKey: string | null;
+    adToken: string | null;
+    fetch?: typeof fetch;
+}): TranscriptionProvider;

package/dist/transcription/providers/codex-subscription.d.ts

@@ -0,0 +1,9 @@
+import type { Settings } from "@opengeni/config";
+import { type TranscriptionAvailabilityContext, type TranscriptionProvider } from "@opengeni/core";
+import { type Database } from "@opengeni/db";
+export declare function createCodexSubscriptionTranscriptionProvider(input: {
+    settings: Settings;
+    db: Database;
+    fetch?: typeof fetch;
+    probe?: (context?: TranscriptionAvailabilityContext) => boolean | Promise<boolean>;
+}): TranscriptionProvider;