@opengeni/runtime 0.2.0

package/dist/sandbox/index.d.ts

@@ -0,0 +1,1738 @@
+import { Settings } from '@opengeni/config';
+export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
+import { SandboxBackend, CapabilityDescriptor, SandboxOs, SessionCapabilities, StreamTokenPayload, SessionEventType, SessionStructuredCapabilities, FsListRequest, FsListResponse, FsReadRequest, FsReadResponse, FsWriteRequest, FsWriteResponse, FsDeleteRequest, FsDeleteResponse, FsMoveRequest, FsMoveResponse, FsMkdirRequest, FsMkdirResponse, GitStatusRequest, GitStatusResponse, GitDiffRequest, GitDiffResponse, GitLogRequest, GitLogResponse, GitShowRequest, GitShowResponse, TerminalExecRequest, TerminalExecResponse, PtyOpenRequest, PtyOpenResponse, PtyWriteRequest, PtyResizeRequest, PtyCloseRequest, GitChangedPayload, GitDiffHunk, GitFileStatusCode, CapabilityUnavailableReason } from '@opengeni/contracts';
+export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
+import { Manifest, SandboxClient, SandboxSessionState } from '@openai/agents/sandbox';
+import { ControlRequest, ControlResponse, ErrorCode, AgentError, DesktopInputRequest, ExecRequest, ExecResponse } from '@opengeni/agent-proto';
+
+/**
+ * Descriptor-table invariants, asserted once at registry build (and from a unit
+ * test). This is the guardrail that keeps the static matrix internally coherent.
+ * It validates the descriptor data only; the descriptor.backendId === SDK
+ * client.backendId assertion (the deferred-from-P0.1 check) lives in
+ * providers/index.ts because it must construct the real SDK clients.
+ */
+declare function assertDescriptorRegistryInvariants(): void;
+
+declare class SandboxConfigError extends Error {
+    readonly backend: SandboxBackend | string;
+    constructor(backend: SandboxBackend | string, message: string);
+}
+declare class SandboxProviderUnavailableError extends Error {
+    readonly backend: SandboxBackend | string;
+    constructor(backend: SandboxBackend | string);
+}
+
+interface ProviderConstructionContext {
+    settings: Settings;
+    /** The env map for the box (collectSandboxEnvironment / per-run environment). */
+    environment: Record<string, string>;
+    /**
+     * Parsed exposed ports (config string -> number[]); already includes the
+     * desktop stream port (6080) when this is a desktop tier with desktop enabled
+     * and the provider cannot expose ports on demand (the merge happens in
+     * createSandboxClient before build()).
+     */
+    exposedPorts: number[];
+}
+interface ProviderRegistration {
+    backend: SandboxBackend;
+    descriptor: CapabilityDescriptor;
+    /**
+     * Validate that the settings carry the credentials/config this provider
+     * REQUIRES. Throw SandboxConfigError on any missing/contradictory field.
+     * Pure — no network. Called by both the factory and a deploy-time preflight.
+     * The factory calls this before build(), so build() may assume valid settings.
+     */
+    validateCredentials(settings: Settings): void;
+    /**
+     * Build the raw SDK SandboxClient. Returns undefined ONLY for "none".
+     * The factory calls validateCredentials() first, so build() can assume valid.
+     */
+    build(ctx: ProviderConstructionContext): unknown;
+}
+
+declare const PROVIDER_REGISTRY: Record<SandboxBackend, ProviderRegistration>;
+/**
+ * Assert the descriptor table AND that each registered provider's SDK client
+ * reports the backendId its descriptor claims. The latter is the
+ * deferred-from-P0.1 invariant — it can only run here because it constructs the
+ * real clients. Called once at registry build (and from a unit test).
+ */
+declare function assertProviderRegistryInvariants(): void;
+
+interface NegotiationContext {
+    sessionId: string;
+    backend: SandboxBackend;
+    os: SandboxOs;
+    /** Current lease liveness; cold means nothing is provisioned yet. */
+    liveness: "cold" | "warming" | "warm" | "draining";
+    /** The lease epoch echoed on viewer heartbeats (the split-brain fence). */
+    leaseEpoch: number;
+    /** The deployment desktop toggle (settings.sandboxDesktopEnabled). */
+    desktopEnabled: boolean;
+    /**
+     * The HUMAN take-control toggle (settings.sandboxDesktopInteractive). When true
+     * (default) and the desktop cell is available, the negotiated DesktopStream.mode
+     * is "interactive" — the noVNC viewer can drive mouse+keyboard into :0 (the box's
+     * x11vnc runs without -viewonly). When false the cell reports mode "read-only"
+     * and the client disables the "Take control" affordance (a genuinely read-only
+     * deployment). Independent of `computerUseReadOnly`, which gates the AGENT
+     * driver, not the human viewer plane. Defaults to true so a caller that never
+     * threads it (e.g. headless tests) still gets the interactive plane when the
+     * desktop is available.
+     */
+    desktopInteractive?: boolean;
+    /** The deployment computer-use toggle (settings.computerUseEnabled). The agent
+     *  drives :0 via xdotool/scrot; availability tracks desktop. Defaults to true. */
+    computerUseEnabled?: boolean;
+    /** Whether the agent computer-use driver is gated to no-op input
+     *  (settings.computerUseReadOnly). v1 default false (the agent clicks/types). */
+    computerUseReadOnly?: boolean;
+    /**
+     * Whether a scoped-stream-token secret is resolvable (I8/OD-8). When desktop
+     * is enabled but this is false (no streamTokenSecret AND no delegationSecret),
+     * the desktop plane GRACEFULLY DEGRADES to transport:null — the deployment
+     * boots, but the pixel plane cannot mint scoped tokens. Defaults to true so a
+     * caller that never threads it (e.g. headless tests) is unaffected.
+     */
+    streamTokenSecretAvailable?: boolean;
+    /** Whether the calling principal has acknowledged the un-redacted desktop
+     *  pixels (and, for a shared box, the shared-exposure disclosure). When the
+     *  box is shared this must be the SHARED acknowledgment; a bare un-redacted ack
+     *  does not satisfy a shared box. */
+    desktopAcknowledged?: boolean;
+    /** True when the box's group has >1 session: watching this desktop also shows
+     *  the sibling sessions' agents on the one :0 framebuffer (addendum E.1). */
+    shared?: boolean;
+    /** The OTHER sessions whose agents may appear on the shared desktop — IDS
+     *  ONLY, never their conversation/metadata (stress g). Empty for a solo box. */
+    sharedSessionIds?: string[];
+    /**
+     * The minted pixel-plane endpoint (P4.2): the direct-to-provider WS URL + the
+     * scoped stream token + its expiry + the framebuffer geometry. Threaded by the
+     * API-direct handshake AFTER it has resumed the box, ensured the display stack,
+     * and resolved the provider tunnel. When ABSENT (the negotiation-only read, a
+     * cold lease, or a degraded desktop) the DesktopStream cell reports url/token/
+     * expiresAt as null — the capability is advertised, the live address is not yet
+     * minted (the caller POSTs to /viewers to mint it). Presence does NOT override
+     * the gates: a degraded/cold/unacked desktop still reports transport:null and
+     * the minted endpoint is dropped.
+     */
+    desktopStream?: {
+        url: string;
+        token: string;
+        expiresAt: string;
+        resolution: [number, number];
+    };
+    /** The deployment terminal toggle (settings.sandboxTerminalEnabled). The REAL
+     *  PTY (ttyd pty-ws) is gated on this + a real-PTY backend; when off the
+     *  Terminal cell still advertises the read-only sse-events firehose. Defaults to
+     *  true so a caller that never threads it is unaffected. */
+    terminalEnabled?: boolean;
+    /**
+     * The minted terminal-plane endpoint (P5.t): the direct-to-provider ttyd
+     * PTY-over-websocket URL + the scoped stream token + its expiry. Threaded by the
+     * API-direct handshake AFTER it has resumed the box, ensured the terminal
+     * server, and resolved the provider tunnel (mintTerminalStream) — SYMMETRIC with
+     * `desktopStream`. When ABSENT (the negotiation-only read, a cold lease, or a
+     * degraded terminal) the Terminal cell reports url/token/expiresAt as null and
+     * falls back to transport "sse-events" (the read-only firehose) — the caller
+     * POSTs to /viewers to mint the live pty-ws address.
+     */
+    terminalStream?: {
+        url: string;
+        token: string;
+        expiresAt: string;
+    };
+    /** Override the negotiation clock (tests). */
+    now?: Date;
+}
+/**
+ * Resolve the descriptor for a backend. Throws on an unknown backend rather than
+ * returning a half-formed default (the registry is the single source of truth).
+ */
+declare function selectBackend(backend: SandboxBackend): CapabilityDescriptor;
+/** True iff the descriptor lists the requested OS as supported. */
+declare function backendSupportsOs(descriptor: CapabilityDescriptor, os: SandboxOs): boolean;
+/**
+ * True iff the backend can serve the Channel-B desktop pixel plane at all — i.e.
+ * its static descriptor advertises DesktopStream as available. The gate the
+ * worker / API use before launching the display stack (so a headless-only
+ * backend like cloudflare/vercel/none never tries). This is the STATIC
+ * feasibility only; the runtime `sandboxDesktopEnabled` policy toggle and the
+ * stream-token-secret gate are layered on by the caller / negotiateCapabilities.
+ *
+ * Accepts EITHER the SandboxBackend enum value (e.g. "local") OR the SDK
+ * client backendId (e.g. "unix_local") — they diverge for the local backend —
+ * so a caller holding only `established.backendId` resolves correctly.
+ */
+declare function desktopCapableBackend(backend: SandboxBackend | string): boolean;
+/**
+ * Negotiate a coherent SessionCapabilities document for (backend, os). Every
+ * capability is reported with availability + a reason-when-unavailable; nothing
+ * is ever absent. The reason precedence is: os_unsupported (the OS axis can't be
+ * served at all) > the per-capability static feasibility > policy/liveness gates.
+ */
+declare function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilities;
+
+declare const STREAM_TOKEN_DEFAULT_TTL_SECONDS = 120;
+type MintStreamTokenInput = {
+    workspaceId: string;
+    sessionId: string;
+    /** The sandbox_lease_holders viewer row id. */
+    viewerId: string;
+    /** The epoch the token is fenced to. For a Modal box this is the live LEASE
+     *  epoch (re-minted on box rollover). For a SELFHOSTED relay stream (M8b) this is
+     *  the session's swap `active_epoch`: the relay tracks the highest epoch any
+     *  viewer presented per channel and REJECTS a token with a lower epoch, so a
+     *  viewer whose token predates a swap-away cannot reach the machine the session
+     *  swapped off of. One field, two fences — the relay/in-box edge reads it as the
+     *  stale-viewer floor either way. */
+    leaseEpoch: number;
+    /** v1 is always "view"; "control" is the never-granted raw-input plane. */
+    mode?: "view" | "control";
+    /** The exposed stream port (noVNC); defaults to 6080. */
+    port?: number;
+    /** TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+    ttlSeconds?: number;
+    /** Override the issue clock (tests). Seconds since the epoch. */
+    nowSeconds?: number;
+};
+/**
+ * Mint a scoped stream token for one viewer holder. Builds the hard-narrow
+ * StreamTokenPayload (the claim set the in-box edge / control plane validates)
+ * and signs it with the resolved stream-token secret via the contracts HMAC
+ * envelope (`ogs_` prefix). The token is RECORDED against the holder row by the
+ * caller and is NEVER appended to the data-plane URL as a query param.
+ */
+declare function mintStreamToken(secret: string, input: MintStreamTokenInput): Promise<string>;
+/**
+ * Verify a scoped stream token. Returns the parsed claims on success, or null on
+ * a bad prefix / malformed envelope / bad HMAC signature / schema-invalid claims
+ * / expiry. Re-exports the contracts verify; the leaf is the agent-loop-free
+ * import surface the API uses.
+ *
+ * The epoch fence (claim.leaseEpoch vs the LIVE lease epoch) and the
+ * workspace+session scope are enforced at USE by the caller against the live
+ * lease + route params — verify proves authenticity + freshness only.
+ */
+declare function verifyStreamToken(secret: string, token: string, nowSeconds?: number): Promise<StreamTokenPayload | null>;
+
+declare const STREAM_PORT = 6080;
+declare const DISPLAY_STACK_TIMEOUT_MS = 60000;
+/** Desktop geometry for the framebuffer. v1 has no live RANDR: a resolution
+ *  change is a full down -> up restart (a separate op). */
+type DesktopGeometry = {
+    width: number;
+    height: number;
+    dpi: number;
+};
+declare const DEFAULT_DESKTOP_GEOMETRY: DesktopGeometry;
+/** Thrown when a stage of the launch script failed. exitCode 11/12/13 map to
+ *  Xvfb / x11vnc / websockify respectively (the stage that died). Degradation is
+ *  surfaced as a value to viewers by the caller; this error is for diagnostics. */
+declare class DisplayStackError extends Error {
+    readonly exitCode: number;
+    readonly stage: "xvfb" | "x11vnc" | "websockify" | "unknown";
+    constructor(exitCode: number, output: string);
+}
+/** Thrown when the provider session cannot run commands (a headless-only
+ *  backend with neither `exec` nor `execCommand`). The desktop tier degrades to
+ *  Channel-A-only — the caller maps this to `DesktopStream.transport: null`. */
+declare class DisplayStackUnsupportedError extends Error {
+    constructor(message: string);
+}
+type EnsureDisplayStackOptions = {
+    geometry?: DesktopGeometry;
+    /** The exposed stream port; defaults to 6080. */
+    port?: number;
+    /** Per-exec timeout; defaults to DISPLAY_STACK_TIMEOUT_MS. */
+    timeoutMs?: number;
+};
+type EnsureDisplayStackResult = {
+    /** The exposed port the stack listens on (websockify/noVNC). */
+    port: number;
+    geometry: DesktopGeometry;
+    /** The raw `OPENGENI_DESKTOP_UP …` marker line, for diagnostics. Never
+     *  surfaced to viewers. */
+    marker: string;
+};
+/**
+ * Build the shell command that runs the idempotent up-script under an in-box
+ * `flock`. The script is shipped in the image at /usr/local/bin/opengeni-desktop-up
+ * (the canonical desktop image); we set the geometry/port env and wrap the call
+ * in `flock` so two concurrent ensureDisplayStack callers (the API viewer op +
+ * the agent turn, both racing after a rollover) serialize without a double
+ * launch. The up-script's own per-stage PID guards make the second call a no-op.
+ *
+ * Exported (pure, side-effect-free) so the ensureDisplayStack unit test can
+ * assert the exact command sequence without a live box.
+ */
+declare function buildDisplayStackScript(options?: EnsureDisplayStackOptions): string;
+/**
+ * Idempotently bring up the desktop display stack on the live box. Safe to call
+ * N times (the in-box flock + the up-script's PID guards make a second call a
+ * no-op). Resolves with the exposed port + geometry on success; throws
+ * `DisplayStackError` on a stage failure and `DisplayStackUnsupportedError` when
+ * the session cannot run commands.
+ *
+ * `session` is the externally-owned provider session (the `established.session`
+ * from establishSandboxSessionFromEnvelope, or any SandboxSessionLike). We
+ * prefer `session.exec` (structured `{exitCode}`) and fall back to
+ * `session.execCommand` (bare string), inferring success from the up-script's
+ * marker line in the fallback case.
+ */
+declare function ensureDisplayStack(session: unknown, options?: EnsureDisplayStackOptions): Promise<EnsureDisplayStackResult>;
+/** Tear the stack down (down-script). Best-effort; never throws on a missing
+ *  process. Used by the geometry-change restart and cold/drain. */
+declare function tearDownDisplayStack(session: unknown): Promise<void>;
+
+declare const TERMINAL_SERVER_TIMEOUT_MS = 60000;
+/** Thrown when the ttyd launch failed inside the box. exitCode 14 maps to the
+ *  up-script's "ttyd failed to come up" stage; any other non-zero is unknown.
+ *  Degradation is surfaced as a value to clients by the caller (Terminal
+ *  transport falls back to sse-events / null); this error is for diagnostics. */
+declare class TerminalServerError extends Error {
+    readonly exitCode: number;
+    readonly stage: "ttyd" | "unknown";
+    constructor(exitCode: number, output: string);
+}
+/** Thrown when the provider session cannot run commands (a headless-only backend
+ *  with neither `exec` nor `execCommand`). The terminal tier degrades to the
+ *  Channel-A sse-events firehose — the caller maps this to a `transport:null`
+ *  pty-ws (the read-only firehose still works). */
+declare class TerminalServerUnsupportedError extends Error {
+    constructor(message: string);
+}
+type EnsureTerminalServerOptions = {
+    /** The exposed terminal port; defaults to 7681 (ttyd default). */
+    port?: number;
+    /** Per-exec timeout; defaults to TERMINAL_SERVER_TIMEOUT_MS. */
+    timeoutMs?: number;
+};
+type EnsureTerminalServerResult = {
+    /** The exposed port ttyd listens on (PTY-over-websocket). */
+    port: number;
+    /** The raw `OPENGENI_TERMINAL_UP …` marker line, for diagnostics. Never
+     *  surfaced to clients. */
+    marker: string;
+};
+/**
+ * Build the shell command that runs the idempotent up-script under an in-box
+ * `flock`. The script is shipped in the image at /usr/local/bin/opengeni-terminal-up
+ * (the canonical desktop image, alongside opengeni-desktop-up); we set the port
+ * env and wrap the call in `flock` so two concurrent ensureTerminalServer callers
+ * (the API viewer op + the agent turn, both racing after a rollover) serialize
+ * without a double launch. The up-script's own curl readiness probe makes the
+ * second call a no-op.
+ *
+ * Exported (pure, side-effect-free) so the ensureTerminalServer unit test can
+ * assert the exact command sequence without a live box. Mirrors
+ * buildDisplayStackScript.
+ */
+declare function buildTerminalServerScript(options?: EnsureTerminalServerOptions): string;
+/**
+ * Idempotently bring up the ttyd PTY-over-websocket server on the live box. Safe
+ * to call N times (the in-box flock + the up-script's curl readiness probe make a
+ * second call a no-op). Resolves with the exposed port on success; throws
+ * `TerminalServerError` on a launch failure and `TerminalServerUnsupportedError`
+ * when the session cannot run commands.
+ *
+ * `session` is the externally-owned provider session (the `established.session`
+ * from establishSandboxSessionFromEnvelope, or any SandboxSessionLike). We prefer
+ * `session.exec` (structured `{exitCode}`) and fall back to `session.execCommand`
+ * (bare string), inferring success from the up-script's marker line in the
+ * fallback case. Mirrors ensureDisplayStack exactly.
+ */
+declare function ensureTerminalServer(session: unknown, options?: EnsureTerminalServerOptions): Promise<EnsureTerminalServerResult>;
+/** Tear the terminal server down (down-script). Best-effort; never throws on a
+ *  missing process. Mirrors tearDownDisplayStack. */
+declare function tearDownTerminalServer(session: unknown): Promise<void>;
+
+/** The provider-resolved endpoint for an exposed port. Mirrors the SDK's
+ *  `ExposedPortEndpoint` (host/port/tls/query/...) WITHOUT importing the
+ *  agent-loop barrel — the leaf stays agent-loop-free. */
+type ExposedPortEndpoint = {
+    host: string;
+    port: number;
+    tls?: boolean;
+    query?: string;
+    protocol?: string;
+    url?: string;
+    /** The URL path the socket connects on. Modal/Daytona/Blaxel serve the edge at
+     *  the root (`/`, the default); the selfhosted relay serves it at `/stream`
+     *  (M8b). When set, buildStreamUrl uses it instead of the root. */
+    path?: string;
+    [key: string]: unknown;
+};
+/** Thrown when the provider cannot expose the stream port (no resolveExposedPort,
+ *  or the provider tunnel lookup failed). The caller degrades the desktop cell to
+ *  `transport:null` (a value, never a crash) — a headless-only provider or a
+ *  transient tunnel failure must not fail the whole handshake. */
+declare class StreamPortUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+type ExposeStreamPortInput = {
+    workspaceId: string;
+    sessionId: string;
+    /** The sandbox_lease_holders viewer row id the token is scoped to. */
+    viewerId: string;
+    /** The live lease epoch — the fence the token is pinned to. */
+    leaseEpoch: number;
+    /** The HMAC secret for the scoped stream token (resolveStreamTokenSecret). */
+    streamTokenSecret: string;
+    /** The exposed stream port; defaults to 6080. */
+    port?: number;
+    /** Token TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+    ttlSeconds?: number;
+    /** The framebuffer geometry to echo back to the client. */
+    resolution?: [number, number];
+    /** Override the issue clock (tests). Seconds since the epoch. */
+    nowSeconds?: number;
+};
+type ExposeStreamPortResult = {
+    /** The direct-to-provider WS URL the viewer connects to (provider-scoped; the
+     *  OpenGeni token is NOT appended). */
+    url: string;
+    /** The scoped OpenGeni stream token — recorded against the holder, NEVER a URL
+     *  query param. */
+    token: string;
+    /** ISO absolute expiry of the token (the rotation hot-swap window backstop). */
+    expiresAt: string;
+    /** The pixel transport the client speaks. */
+    transport: "vnc-ws";
+    /** The reference noVNC client the SDK helper mounts. */
+    client: "novnc";
+    resolution: [number, number];
+    leaseEpoch: number;
+};
+/**
+ * Assemble the direct-to-provider WS URL from a resolved endpoint. The SDK's
+ * `urlForExposedPort(endpoint,'ws')` is the canonical tls-aware, IPv6-bracketing,
+ * provider-query-preserving assembler — we reimplement its exact logic here so
+ * the leaf stays agent-loop-free (the helper lives behind the bare
+ * `@openai/agents-core` root, which the import-discipline test forbids). The
+ * provider's own `endpoint.query` (Blaxel `bl_preview_token`, Daytona signed
+ * token) is preserved; the OpenGeni token is NOT appended (it is recorded against
+ * the holder + validated at the in-box websockify edge).
+ */
+declare function buildStreamUrl(endpoint: ExposedPortEndpoint): string;
+/**
+ * Resolve the provider's scoped tunnel for the stream port and mint the scoped
+ * OpenGeni stream token. Returns a coherent `{url, token, expiresAt, transport,
+ * client, resolution}` cell the caller records on the lease (data_plane_url) and
+ * returns in the DesktopStream handshake.
+ *
+ * Throws `StreamPortUnavailableError` when the provider session cannot resolve
+ * the port (no `resolveExposedPort`, or the tunnel lookup failed) — the caller
+ * maps this to a `transport:null` degradation (a value, never a crash).
+ */
+declare function exposeStreamPort(session: unknown, input: ExposeStreamPortInput): Promise<ExposeStreamPortResult>;
+
+type RecordingCodec = "h264-mp4" | "vp9-webm";
+type RecordingContentType = "video/mp4" | "video/webm";
+declare function contentTypeForCodec(codec: RecordingCodec): RecordingContentType;
+declare function extForCodec(codec: RecordingCodec): string;
+/** No exec/execCommand on the session — the box cannot run ffmpeg. */
+declare class RecordingUnavailableError extends Error {
+    constructor(message: string);
+}
+/** ffmpeg failed, the file is missing, or the byte read failed. */
+declare class RecordingError extends Error {
+    readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable";
+    constructor(message: string, reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable");
+}
+type StartRecordingInput = {
+    recordingId: string;
+    codec?: RecordingCodec;
+    framerate?: number;
+    maxSeconds?: number;
+    dimensions?: [number, number];
+    display?: string;
+    runAs?: string;
+    tmpDir?: string;
+};
+type RecordingProcess = {
+    recordingId: string;
+    codec: RecordingCodec;
+    boxPath: string;
+    pidFile: string;
+    dimensions: [number, number];
+    framerate: number;
+    /** epoch-ms when ffmpeg was launched (for duration computation, F14). */
+    startedAt: number;
+    display: string;
+    runAs?: string;
+};
+/**
+ * Launch ffmpeg x11grab on :0 → an mp4/webm file on the box. Backgrounded with
+ * `nohup … & echo $!` so the launch returns immediately (F12 — the exec does not
+ * block on the recording). A hard `-t <maxSeconds>` ceiling bounds a runaway file
+ * across a multi-day turn. Returns the handle the caller carries to stop+finalize.
+ */
+declare function startRecording(session: unknown, input: StartRecordingInput): Promise<RecordingProcess>;
+/**
+ * SIGINT ffmpeg (so it writes a clean moov atom / webm trailer) and wait for the
+ * pid to exit. Bounded well under the yield window (F3). Idempotent: a missing
+ * pid file is a no-op.
+ */
+declare function stopRecording(session: unknown, proc: RecordingProcess): Promise<void>;
+type FinalizeRecordingResult = {
+    bytes: Uint8Array;
+    contentType: RecordingContentType;
+    sizeBytes: number;
+    durationSeconds: number;
+};
+/**
+ * Read the finalized recording bytes off the box.
+ *
+ * TRANSPORT: the bytes are read via a DIRECT exec (`base64 <path>` over stdout),
+ * NOT via session.readFile(). The recording artifact lives at an absolute /tmp
+ * path on purpose — recordings must never be written inside the user's workspace
+ * /git tree — but session.readFile() resolves every path against the manifest
+ * workspace root and rejects anything outside it ("Sandbox path … escapes the
+ * workspace root"), which fataled finalize. Raw exec runs unrestricted shell, so
+ * `base64` reads the /tmp file directly; we decode the base64 back to bytes here.
+ * The byte-read exec passes `maxOutputTokens: null` so the provider never
+ * truncates a large recording's base64.
+ *
+ * F8: we DO NOT assume any over-limit behavior. First `stat` the file size on the
+ * box; if it exceeds maxBytes, fail `max-bytes-exceeded` (never upload a truncated
+ * video). Otherwise read the raw bytes.
+ *
+ * F9: this does NOT delete the box file. The caller deletes it (deleteRecordingArtifacts)
+ * ONLY after the storage PUT + `available` commit — so a failed upload leaves the
+ * bytes recoverable on the box for a retry.
+ *
+ * F14: duration is wall-clock (now − startedAt), a close approximation of the
+ * SIGINT-flushed video length.
+ */
+declare function readRecordingBytes(session: unknown, proc: RecordingProcess, maxBytes?: number): Promise<FinalizeRecordingResult>;
+/**
+ * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
+ * and the `available` row committed — never before. Best-effort; never throws.
+ */
+declare function deleteRecordingArtifacts(session: unknown, proc: RecordingProcess): Promise<void>;
+/** The storage object key for a recording artifact (parallels the file-asset layout). */
+declare function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string;
+
+type ChannelAExecResult = {
+    output?: string;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    sessionId?: number;
+    wallTimeSeconds?: number;
+};
+type ChannelAExecArgs = {
+    cmd: string;
+    workdir?: string | undefined;
+    shell?: string | undefined;
+    login?: boolean | undefined;
+    tty?: boolean | undefined;
+    yieldTimeMs?: number | undefined;
+    maxOutputTokens?: number | undefined;
+    runAs?: string | undefined;
+};
+type ChannelAEditor = {
+    createFile?(op: unknown): Promise<unknown>;
+    updateFile?(op: unknown): Promise<unknown>;
+    deleteFile?(op: unknown): Promise<unknown>;
+};
+type ChannelASession = {
+    exec?(args: ChannelAExecArgs): Promise<ChannelAExecResult>;
+    execCommand?(args: ChannelAExecArgs): Promise<string>;
+    readFile?(args: {
+        path: string;
+        runAs?: string;
+        maxBytes?: number;
+    }): Promise<string | Uint8Array>;
+    writeStdin?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    createEditor?(runAs?: string): ChannelAEditor;
+    supportsPty?(): boolean;
+};
+declare class ChannelAValidationError extends Error {
+    constructor(message: string);
+}
+declare class ChannelAConflictError extends Error {
+    constructor(message: string);
+}
+declare class ChannelANotFoundError extends Error {
+    constructor(message: string);
+}
+declare class ChannelAUnsupportedError extends Error {
+    constructor(message: string);
+}
+type ChannelAEmitter = (events: {
+    type: SessionEventType;
+    payload: unknown;
+}[]) => Promise<void>;
+type SandboxChannelAServiceOptions = {
+    session: ChannelASession;
+    workspaceRoot?: string;
+    leaseEpoch?: number;
+    revision?: number;
+    emit?: ChannelAEmitter;
+    runAs?: string;
+};
+declare class SandboxChannelAService {
+    private readonly session;
+    private readonly workspaceRoot;
+    private readonly leaseEpoch;
+    private revision;
+    private readonly emit?;
+    private readonly runAs?;
+    constructor(opts: SandboxChannelAServiceOptions);
+    /** Capability probe — the compact Channel-A projection. */
+    capabilities(repos?: string[]): SessionStructuredCapabilities;
+    private run;
+    fsList(req: FsListRequest): Promise<FsListResponse>;
+    fsRead(req: FsReadRequest): Promise<FsReadResponse>;
+    /** Read a file by base64-ing it through exec. Binary-safe and — crucially —
+     *  NOT subject to the provider's native-readFile workspace-escape validation,
+     *  so it can render a symlink whose target lives outside /workspace (the link
+     *  node itself is in-workspace). `base64 <path>` follows the symlink. */
+    private fsReadViaExec;
+    private shapeRead;
+    fsWrite(req: FsWriteRequest): Promise<FsWriteResponse>;
+    private tryEditorWrite;
+    fsDelete(req: FsDeleteRequest): Promise<FsDeleteResponse>;
+    fsMove(req: FsMoveRequest): Promise<FsMoveResponse>;
+    fsMkdir(req: FsMkdirRequest): Promise<FsMkdirResponse>;
+    gitStatus(req: GitStatusRequest): Promise<GitStatusResponse>;
+    gitDiff(req: GitDiffRequest): Promise<GitDiffResponse>;
+    gitLog(req: GitLogRequest): Promise<GitLogResponse>;
+    gitShow(req: GitShowRequest): Promise<GitShowResponse>;
+    /** Detect repo roots within the workspace (for the Git.repos capability). */
+    detectRepos(): Promise<string[]>;
+    /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
+     *  long-running tail (when the process hasn't exited within timeoutMs) keeps
+     *  running in-box; if emitStream is set the buffered output is also published as
+     *  the agent firehose so other viewers see it. */
+    terminalExec(req: TerminalExecRequest): Promise<TerminalExecResponse>;
+    /** Open an interactive PTY: exec the shell with tty:true, yielding the numeric
+     *  exec-session id the caller persists (ptyId<->execSessionId) so subsequent
+     *  writeStdin can drive it. Returns the supportsInput gate (false when the
+     *  backend has no writeStdin). The caller emits terminal.pty.started after it
+     *  persists the row. */
+    ptyOpen(req: PtyOpenRequest, ptyId: string): Promise<{
+        response: PtyOpenResponse;
+        execSessionId: number | null;
+        shell: string;
+        initialOutput: string;
+    }>;
+    /** Drive an open PTY's stdin. Returns the drained output (the caller publishes
+     *  it as terminal.pty.output.delta). Throws ChannelAUnsupportedError when the
+     *  backend has no writeStdin. */
+    ptyWrite(_req: PtyWriteRequest, execSessionId: number, data: string): Promise<string>;
+    /** Resize an open PTY (SIGWINCH via stty against the exec-session). The SDK has
+     *  no resize method; stty in the same tty session updates the geometry. */
+    ptyResize(req: PtyResizeRequest, execSessionId: number): Promise<void>;
+    /** Close an open PTY: write exit/EOF. The caller marks the row closed + emits
+     *  terminal.pty.exited. */
+    ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<void>;
+    /** The current FS revision (for the caller to persist/seed). */
+    currentRevision(): number;
+    private joinRoot;
+    private repoWorkdir;
+    private emitEvents;
+    private emitFsChanged;
+    /** Re-probe git after a mutation and emit git.changed (best-effort, used by the
+     *  worker agent-turn side after FS-mutating tools). */
+    emitGitChanged(repoPath: string, reason: GitChangedPayload["reason"]): Promise<void>;
+}
+declare function stripExecBanner(raw: string): string;
+declare function isWorkspaceEscapeError(error: unknown): boolean;
+declare function isExecSessionLostBanner(out: string, execSessionId: number): boolean;
+declare function parseExecBannerSessionId(raw: string): number | null;
+declare function assertSafeRelPath(p: string): string;
+declare function parsePorcelainV2(z: string): Omit<GitStatusResponse, "revision">;
+type NumstatEntry = {
+    additions: number;
+    deletions: number;
+    binary: boolean;
+    oldPath: string | null;
+    newPath: string;
+};
+declare function parseNumstatZ(z: string): NumstatEntry[];
+declare function parseUnifiedPatch(patch: string): {
+    hunks: GitDiffHunk[];
+    status: GitFileStatusCode;
+};
+
+type SelfhostedUnavailableReason = Extract<CapabilityUnavailableReason, "agent_offline" | "agent_reconnecting" | "consent_required" | "display_unavailable">;
+/**
+ * The selfhosted control-plane transport seam. ONE method: `request` — send a
+ * `ControlRequest` to the agent addressed by subject and await its
+ * `ControlResponse`. The subject is `subjectFor(workspaceId, agentId)`.
+ *
+ * The CONTRACT every implementor MUST honour (the M3 ruling): a
+ * no-responder / request-timeout is NOT an exception that means "not found" — it
+ * is surfaced as a `ControlResponse` carrying an `AgentError` with code
+ * `AGENT_OFFLINE` (no responder at all) or, when the caller can distinguish a
+ * transient blip, `TIMEOUT` (→ `agent_reconnecting`). The session maps these to
+ * the runtime error taxonomy; it NEVER lets agent-offline look like a provider
+ * NotFound (which would cold-create a rival box for a user's real machine).
+ */
+interface ControlRpc {
+    request(subject: string, req: ControlRequest, opts: {
+        timeoutMs: number;
+    }): Promise<ControlResponse>;
+}
+/** The control-plane RPC subject for an enrolled agent — its subscription IS the
+ *  registry (the binding two-plane decision). */
+declare function subjectFor(workspaceId: string, agentId: string): string;
+/**
+ * The runtime-level error a `SelfhostedSession` op throws when the agent returns
+ * an `AgentError` (or no responder / timeout maps to one). It carries:
+ *   - `code`     — the wire `ErrorCode` (single-source-of-truth);
+ *   - `reason`   — the negotiated `CapabilityUnavailableReason` the capability /
+ *                  liveness surface uses (`agent_offline` / `agent_reconnecting`
+ *                  / `consent_required`), or null for op-level errors
+ *                  (OS/NOT_FOUND/UNSUPPORTED/STREAM/PROTOCOL) that are not a
+ *                  machine-liveness condition;
+ *   - `retryable`— whether the caller should re-resolve + retry (DRAINING /
+ *                  FENCED / a reconnecting blip);
+ *   - `notFound` — ALWAYS the provider-NotFound discriminator value: for
+ *                  selfhosted this is true ONLY for an OS-level NOT_FOUND of a
+ *                  path/ref (a real "the file does not exist"), and is FALSE for
+ *                  AGENT_OFFLINE (the machine isn't recreatable — never let the
+ *                  lease cold-create a rival). `isProviderSandboxNotFoundError`
+ *                  reads this.
+ */
+declare class SelfhostedControlError extends Error {
+    readonly name = "SelfhostedControlError";
+    readonly code: ErrorCode;
+    readonly reason: SelfhostedUnavailableReason | null;
+    readonly retryable: boolean;
+    readonly fenced: boolean;
+    readonly draining: boolean;
+    readonly agentOffline: boolean;
+    readonly osNotFound: boolean;
+    readonly detail: Record<string, string>;
+    constructor(input: {
+        message: string;
+        code: ErrorCode;
+        reason: SelfhostedUnavailableReason | null;
+        retryable: boolean;
+        fenced?: boolean;
+        draining?: boolean;
+        agentOffline?: boolean;
+        osNotFound?: boolean;
+        detail?: Record<string, string>;
+    });
+}
+/**
+ * Map an `AgentError` (from a `ControlResponse`) to the runtime
+ * `SelfhostedControlError`. THE load-bearing mapping (the M3 ruling):
+ *   - AGENT_OFFLINE         → reason `agent_offline`, agentOffline=true,
+ *                             osNotFound=FALSE (NEVER a provider NotFound).
+ *   - TIMEOUT (a transient missed-window / no-responder blip the caller marked
+ *                             retryable) → reason `agent_reconnecting`.
+ *   - CONSENT_REQUIRED      → reason `consent_required`.
+ *   - DRAINING              → no capability reason; retryable (turn pauses + retries).
+ *   - FENCED                → no capability reason; retryable (the existing
+ *                             epoch-fence retry; the caller re-resolves + retries).
+ *   - NOT_FOUND             → an OS-level path/ref NotFound — osNotFound=true (a
+ *                             real "file does not exist"), no machine-liveness
+ *                             reason. (This is the ONLY NotFound; it is NOT the
+ *                             box-gone NotFound that licenses a cold restore.)
+ *   - OS / UNSUPPORTED / STREAM / PROTOCOL / UNSPECIFIED → op-level error, no
+ *                             reason, non-retryable.
+ */
+declare function agentErrorToControlError(err: AgentError): SelfhostedControlError;
+/** Build a synthesized AGENT_OFFLINE `AgentError` — the control plane uses this
+ *  when no agent responds on the subject at all. */
+declare function offlineAgentError(message?: string): AgentError;
+/** Build a synthesized TIMEOUT `AgentError` — the control plane uses this when a
+ *  responder existed but the request timed out (a transient blip → reconnecting). */
+declare function timeoutAgentError(message?: string): AgentError;
+/**
+ * The minimal NATS request/reply surface `NatsControlRpc` needs. It mirrors the
+ * `nats` `NatsConnection.request` signature WITHOUT importing `nats` into the
+ * agent-loop-free runtime leaf: the API/worker injects the live connection (the
+ * SAME `@opengeni/events` bus connection). A factory may return `null` when NATS
+ * is not configured (boot must not require a live NATS) — `NatsControlRpc` then
+ * surfaces `agent_offline` for every request rather than throwing.
+ */
+interface NatsRequestConnection {
+    request(subject: string, payload: Uint8Array, opts: {
+        timeout: number;
+    }): Promise<{
+        data: Uint8Array;
+    }>;
+}
+/**
+ * A thin `ControlRpc` over a NATS request/reply connection. Constructed with a
+ * LAZY factory: the connection is resolved on first `request` (so boot never
+ * requires a live NATS). A null factory result, a no-responder error, or a
+ * request timeout each yield a `ControlResponse` carrying a synthesized
+ * `AgentError` (AGENT_OFFLINE / TIMEOUT) — NEVER a thrown transport error and
+ * NEVER a NotFound.
+ *
+ * The factory is async and memoized; it may itself dial the bus. M4 replaces the
+ * factory's body with the Accounts-scoped, hardened connection — this class's
+ * shape does not change.
+ */
+declare class NatsControlRpc implements ControlRpc {
+    private readonly connect;
+    private connection;
+    constructor(connect: () => Promise<NatsRequestConnection | null>);
+    private resolveConnection;
+    request(subject: string, req: ControlRequest, opts: {
+        timeoutMs: number;
+    }): Promise<ControlResponse>;
+}
+/** A `ControlResponse` carrying a synthesized AGENT_OFFLINE error. */
+declare function offlineControlResponse(requestId: string): ControlResponse;
+/** A `ControlResponse` carrying a synthesized TIMEOUT error (→ reconnecting). */
+declare function timeoutControlResponse(requestId: string): ControlResponse;
+
+/** The V4A-diff applier the SDK's apply_patch editor uses. The leaf cannot import
+ *  `@openai/agents`'s `applyDiff` (the agent-loop root the leaf forbids), so the
+ *  runtime barrel (`packages/runtime/src/index.ts`, which DOES import that root)
+ *  injects it via `setSelfhostedApplyDiff` at module load. Until injected,
+ *  `createEditor()` surfaces a clear error rather than a silent wrong-edit. */
+type SelfhostedApplyDiff = (input: string, diff: string, mode?: "default" | "create") => string;
+/** Register the SDK's `applyDiff` so `SelfhostedSession.createEditor()` can apply
+ *  V4A diffs over the NATS fs ops. Called once by the runtime barrel. */
+declare function setSelfhostedApplyDiff(fn: SelfhostedApplyDiff): void;
+/** The structural Editor surface the SDK's filesystem capability consumes (the
+ *  three apply_patch operations). Mirrors `@openai/agents-core`'s `Editor`. */
+interface SelfhostedEditor {
+    createFile(operation: {
+        path: string;
+        diff: string;
+    }, context?: unknown): Promise<{
+        output?: string;
+    } | void>;
+    updateFile(operation: {
+        path: string;
+        diff: string;
+        moveTo?: string;
+    }, context?: unknown): Promise<{
+        output?: string;
+    } | void>;
+    deleteFile(operation: {
+        path: string;
+    }, context?: unknown): Promise<{
+        output?: string;
+    } | void>;
+}
+/** The image tool-output shape the SDK's view_image tool expects (mirror of
+ *  `ToolOutputImage` — not re-exported by `@openai/agents/sandbox`, so structural). */
+interface SelfhostedImageOutput {
+    type: "image";
+    image: {
+        data: Uint8Array;
+        mediaType: string;
+    };
+}
+/** Default control-op timeout. A transient miss surfaces as `agent_reconnecting`
+ *  (the turn pauses + retries); it is NOT a hard failure. */
+declare const SELFHOSTED_DEFAULT_TIMEOUT_MS = 30000;
+/** The relay-URL shape config the session needs to build a stream endpoint. M8b
+ *  wires the real relay deployment behind THIS seam so `buildStreamUrl` works
+ *  unchanged behind `resolveExposedPort`. */
+interface SelfhostedRelayConfig {
+    /** The relay edge host (no scheme), e.g. "relay.opengeni.ai". */
+    host: string;
+    /** The relay port. Defaults to 443 (the relay terminates TLS). */
+    port?: number;
+    /** Whether the relay endpoint is TLS (wss/https). Defaults true. */
+    tls?: boolean;
+    /** The relay's stream-dial path (the `opengeni-relay` wss route). Defaults to
+     *  "/stream" — the route the relay listens on (M8b). */
+    path?: string;
+}
+/** The relay's default wss dial path (the `opengeni-relay` server route). */
+declare const SELFHOSTED_RELAY_STREAM_PATH = "/stream";
+interface SelfhostedSessionDeps {
+    workspaceId: string;
+    agentId: string;
+    controlRpc: ControlRpc;
+    relay: SelfhostedRelayConfig;
+    /** The lease/active epoch this session is fenced under (echoed on every
+     *  ControlRequest so the agent can reject a stale op with ERROR_CODE_FENCED).
+     *  Defaults to 0 (no fence) for the negotiation-only / test path. */
+    epoch?: number;
+    /** Override the control-op timeout (tests). */
+    timeoutMs?: number;
+    /**
+     * The run's declared sandbox environment — the SAME `Record<string,string>` the
+     * worker turn passes to `runtime.buildAgent`'s `sandboxEnvironment` (and that the
+     * agent's TARGET manifest, `buildManifest`, carries). The SDK injects this
+     * selfhosted session NON-OWNED and applies the agent's manifest as a provided-
+     * session delta; `validateNoEnvironmentDelta` throws "Live sandbox sessions cannot
+     * change manifest environment variables" on ANY env mismatch. So `state.manifest`'s
+     * `environment` MUST EQUAL the turn's environment for the delta to be empty. The
+     * selfhosted exec routes over NATS and does NOT consume the env, but the manifest
+     * must carry it for parity. Omitted → `{}` (the negotiation-only / test path,
+     * which never applies a turn manifest, so there is no delta to validate).
+     */
+    environment?: Record<string, string>;
+    /**
+     * The session's working directory — the BASE every path/cwd is rooted under (see
+     * `toMachinePath` / SELFHOSTED_VIRTUAL_ROOT). A launch-workspace_root-relative
+     * subdir (resolved under workspace_root by the agent's `resolve_cwd`) or an
+     * absolute machine path. Omitted/empty (the default) ⇒ "" ⇒ today's behavior
+     * exactly (an empty cwd lets the agent substitute its workspace_root).
+     */
+    workingDir?: string;
+}
+/** The Channel-A `exec` result shape (a structural superset of the SDK's). */
+interface SelfhostedExecResult {
+    output: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+/** The `exec` args the structural surface accepts (mirrors ChannelAExecArgs). */
+interface SelfhostedExecArgs {
+    cmd: string;
+    workdir?: string | undefined;
+    shell?: string | undefined;
+    login?: boolean | undefined;
+    tty?: boolean | undefined;
+    runAs?: string | undefined;
+}
+/**
+ * The persistable session state. For selfhosted this is `{agentId}` ONLY — there
+ * is NO provider box id, no snapshot, no manifest. Resume re-addresses the live
+ * subject; the machine itself is the persistence (`persistable:false`).
+ */
+interface SelfhostedSessionState {
+    agentId: string;
+}
+/**
+ * A live selfhosted session — the structural `SandboxSessionLike` surface over a
+ * `ControlRpc`. Mirrors Modal's session shape so Channel-A/viewer/computer-use
+ * consume it unchanged.
+ */
+declare class SelfhostedSession {
+    readonly backendId: "selfhosted";
+    readonly workspaceId: string;
+    readonly agentId: string;
+    private readonly controlRpc;
+    private readonly relay;
+    private readonly epoch;
+    private readonly timeoutMs;
+    private readonly subject;
+    /** The session working directory — the path/cwd base every op is rooted under
+     *  (see `toMachinePath`). "" by default ⇒ today's workspace_root behavior. */
+    private readonly workingDir;
+    /**
+     * The structural `state` slice consumers read. `agentId`/`instanceId` serve the
+     * channel-a `readInstanceId` + docker-network decoration (the agentId IS the
+     * identity). `manifest` is the slice the @openai/agents SDK reads AND writes per
+     * turn (serializeManifestEnvironment / validateProvidedSessionManifestUpdate read
+     * `manifest.root` + iterate `manifest.environment`; providedSessionManifest WRITES
+     * `state.manifest = next`). It must be a real, MUTABLE Manifest field — when the
+     * RoutingSandboxSession proxy resolves THIS as the active backend it returns
+     * `session.state` BY REFERENCE, so the SDK's read and write must both land on a
+     * well-formed Manifest here (defined `root`, object `environment`). Without it the
+     * SDK crashes with `undefined is not an object (evaluating 'current.root')`.
+     *
+     * `manifest` is intentionally a plain mutable field (not `readonly`) so the SDK's
+     * `state.manifest = next` write succeeds. It is NOT part of the persistable state
+     * (`serializeSessionState` round-trips `{agentId}` only).
+     *
+     * `environment` is the SDK `SandboxSessionState.environment` (a `Record<string,
+     * string>`). It MUST be present because the GROUP box's client serializes THIS
+     * (the active backend's) state at end-of-turn — the non-owned injected session is
+     * serialized via the CONFIGURED client (modal in prod), NOT the selfhosted client.
+     * Modal's `serializeRemoteSandboxSessionState` does `Object.entries(state.environment)`;
+     * an absent field crashes the post-turn RunState serialize with "Object.entries
+     * requires that input parameter not be null or undefined". It carries the run's
+     * threaded environment (or `{}`). The resulting modal-tagged envelope is inert for
+     * selfhosted (resume re-addresses the machine by agentId via the lease pointer,
+     * never from this SDK envelope), so its only job is to not crash the serialize.
+     */
+    readonly state: {
+        agentId: string;
+        instanceId: string;
+        manifest: Manifest;
+        environment: Record<string, string>;
+    };
+    constructor(deps: SelfhostedSessionDeps);
+    /** Issue a control op, decoding the agent's reply or throwing the mapped
+     *  `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
+     *  timeout error from the transport). */
+    private call;
+    /** Channel-A `exec`: run a command on the machine and return its output. */
+    exec(args: SelfhostedExecArgs): Promise<SelfhostedExecResult>;
+    /** SDK shell capability `execCommand`: run a command and return its stdout (the
+     *  `exec_command` tool). Selfhosted exec is non-interactive (no PTY) — `tty` is
+     *  ignored; `supportsPty()` is false so the SDK never offers a stdin session. */
+    execCommand(args: {
+        cmd: string;
+        workdir?: string;
+        runAs?: string;
+    }): Promise<string>;
+    /** SDK shell capability never calls this (gated on `supportsPty()` which is
+     *  false), but the surface advertises it. Selfhosted exec has no interactive PTY
+     *  session over the structured RPC, so a stdin write is unsupported. */
+    supportsPty(): boolean;
+    /** SDK filesystem capability `view_image`: read the image bytes off the machine
+     *  and wrap them in the tool-output image shape (magic-byte sniff + path fallback,
+     *  mirroring the SDK's `imageOutputFromBytes`). */
+    viewImage(args: {
+        path: string;
+        runAs?: string;
+    }): Promise<SelfhostedImageOutput>;
+    /** SDK skills/filesystem `pathExists`: whether a path exists on the machine. */
+    pathExists(path: string, _runAs?: string): Promise<boolean>;
+    /** SDK skills `listDir`: list a directory as `{name, path, type}[]`. */
+    listDir(args: {
+        path: string;
+        runAs?: string;
+    }): Promise<Array<{
+        name: string;
+        path: string;
+        type: "file" | "dir" | "other";
+    }>>;
+    /** SDK manifest-delta `materializeEntry`: a NO-OP for selfhosted. Source
+     *  materialization (cloning repos / staging files into the box) is how cloud
+     *  providers prepare a fresh box; a bring-your-own machine already owns its
+     *  filesystem and is prepared by the agent itself, so there is nothing to stage.
+     *  Present (not absent) so the SDK's provided-session manifest apply path — which
+     *  requires `applyManifest()` OR `materializeEntry()` when the agent declares
+     *  entries — is satisfied without error. The selfhosted manifest declares no
+     *  entries, so in practice this is never invoked with a real entry. */
+    materializeEntry(_args: {
+        path: string;
+        entry: unknown;
+        runAs?: string;
+    }): Promise<void>;
+    /** SDK filesystem capability `createEditor`: the apply_patch host. Applies V4A
+     *  diffs over the NATS fs ops (read → applyDiff → write). `applyDiff` is the SDK's
+     *  own parser, injected by the runtime barrel (the leaf cannot import it). */
+    createEditor(runAs?: string): SelfhostedEditor;
+    /** Channel-A `readFile`: read a file off the machine (binary-safe). */
+    readFile(args: {
+        path: string;
+        runAs?: string;
+        maxBytes?: number;
+    }): Promise<Uint8Array>;
+    /** Write a file onto the machine (the fs surface the descriptor advertises). */
+    writeFile(args: {
+        path: string;
+        content: string | Uint8Array;
+        createParents?: boolean;
+        append?: boolean;
+    }): Promise<number>;
+    /** List a directory on the machine. */
+    listFiles(args: {
+        path: string;
+        recursive?: boolean;
+    }): Promise<NonNullable<ControlResponse["result"]> & {
+        $case: "fsList";
+    }>;
+    /** Stat a path on the machine. */
+    statFile(args: {
+        path: string;
+    }): Promise<{
+        exists: boolean;
+    }>;
+    /** Computer-use WRITE op: inject one synthetic desktop input event (pointer/key/
+     *  scroll) on the machine's OWN display. The agent injects via CGEvent (macOS) /
+     *  XTEST (Linux) and CONSENT-GATES it — an unconsented call never touches the OS
+     *  and surfaces the mapped control error (ERROR_CODE_CONSENT_REQUIRED) via `call()`. */
+    desktopInput(event: DesktopInputRequest["event"]): Promise<void>;
+    /** Computer-use VIEW op: capture a single PNG screenshot of the machine's desktop
+     *  plus its geometry (via ScreenCaptureKit / x11). NOT consent-gated (a view op —
+     *  the view/control decoupling), so it works with a display but no screen-control
+     *  consent. Returns the raw encoded bytes + width/height. */
+    screenshot(): Promise<{
+        png: Uint8Array;
+        width: number;
+        height: number;
+    }>;
+    /** A cheap liveness probe — request a Ping on the subject; returns true iff a
+     *  responder answered (no AgentError). Used by `negotiateSelfhostedCapabilities`.
+     *  The wire `nonce` is a uint64 (a numeric string), so the default is a random
+     *  numeric value — NOT a UUID (which would fail proto uint64 encoding). */
+    ping(nonce?: string): Promise<boolean>;
+    /**
+     * Resolve an exposed port to a relay stream endpoint (the viewer/pty plane).
+     * Returns the relay URL SHAPE — `{host:relay, port, tls, query:channel-key}` —
+     * after asking the agent to ensure a stream channel for the port. M8b wires the
+     * real relay tier (the byte pump) behind THIS seam.
+     *
+     * THE CHANNEL-KEY QUERY (the M8b relay-dial contract, dossier §10.5): the relay
+     * routes by `{workspaceId, agentId, port}` — the EXACT `ChannelKey::query` the
+     * agent's relay client (`opengeni-agent-stream`) appends when it registers the
+     * producer side: `ws=<workspaceId>&agent=<agentId>&port=<port>`. We append the
+     * agent-registered `channel=<channelId>` as a correlation hint. So the viewer
+     * dials `wss://<relay>/stream?ws=&agent=&port=&channel=` and presents the minted
+     * `ogs_` token in-band (NEVER as a URL param) — the relay pairs it with the
+     * producer by the routing key.
+     */
+    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
+    /** Round-trip the persistable state — `{agentId}` ONLY (resume = re-address). */
+    serializeSessionState(): Promise<SelfhostedSessionState>;
+}
+/**
+ * The selfhosted SDK-client surface the registry builds. `backendId:"selfhosted"`
+ * (the resume-fence field asserted against the descriptor). `create()`/`resume()`
+ * return a `SelfhostedSession` bound to `{workspaceId, agentId, controlRpc}`.
+ *
+ * `create()` and `resume()` are IDENTICAL for selfhosted — there is no box to
+ * provision (the machine already exists); both just bind a session to the live
+ * subject. `serializeSessionState`/`deserializeSessionState` round-trip
+ * `{agentId}` only.
+ *
+ * The `controlRpc` is constructed LAZILY via an injected factory (defaulting to
+ * `NatsControlRpc`); a session built before NATS is configured surfaces
+ * `agent_offline` on its first op rather than failing at construction.
+ */
+declare class SelfhostedSandboxClient {
+    readonly backendId: "selfhosted";
+    readonly supportsDefaultOptions = false;
+    private readonly workspaceId;
+    private readonly relay;
+    private readonly controlRpcFactory;
+    private readonly defaultAgentId;
+    private readonly epoch;
+    private readonly timeoutMs;
+    private readonly environment;
+    private readonly workingDir;
+    private controlRpcMemo;
+    constructor(opts: {
+        workspaceId: string;
+        relay: SelfhostedRelayConfig;
+        /** Lazily build the ControlRpc (defaults to NatsControlRpc in the provider). */
+        controlRpcFactory: () => ControlRpc;
+        /** The agentId a bare create()/resume() (no state) binds to. Optional: the
+         *  resume path supplies it via deserializeSessionState. */
+        agentId?: string;
+        epoch?: number;
+        timeoutMs?: number;
+        /** The run's declared sandbox environment, threaded into every bound session's
+         *  `state.manifest.environment` so the SDK's per-turn manifest-env delta is
+         *  empty (validateNoEnvironmentDelta). See SelfhostedSessionDeps.environment.
+         *  Omitted → `{}` (the negotiation-only path; no turn manifest is applied). */
+        environment?: Record<string, string>;
+        /** The session working directory threaded into every bound session (the path/
+         *  cwd base; see SelfhostedSessionDeps.workingDir). Omitted/empty ⇒ the default
+         *  workspace_root behavior. */
+        workingDir?: string;
+    });
+    private controlRpc;
+    private bind;
+    /** Bind a session to the live agent subject. There is no box to provision. */
+    create(_manifest?: unknown, _options?: unknown): Promise<SelfhostedSession>;
+    /** Resume = re-address the subject. Identical to create — no provider state. */
+    resume(state: SelfhostedSessionState | Record<string, unknown>, _options?: unknown): Promise<SelfhostedSession>;
+    /** Serialize a live session's state → `{agentId}` ONLY. */
+    serializeSessionState(state: SelfhostedSessionState | {
+        agentId?: string;
+    } | unknown): Promise<SelfhostedSessionState>;
+    /** Deserialize `{agentId}` from the persisted envelope. */
+    deserializeSessionState(state: Record<string, unknown>): Promise<SelfhostedSessionState>;
+    /** selfhosted is NOT persistable — there is no owned session state to preserve
+     *  (the machine is the persistence). The lease never snapshots it. */
+    canPersistOwnedSessionState(): Promise<boolean>;
+    private requireAgentId;
+}
+/**
+ * The dependency shape `buildSelfhostedBackendSession` needs to bind a live
+ * selfhosted session to a target machine. A structural superset of the fields the
+ * routing resolver (backend-resolver.ts) reads off its deps + pointer, and the
+ * fields the WORKER turn's machine-primary establish branch threads in — so a
+ * SINGLE build shape is shared by both (never two divergent constructions of the
+ * same SelfhostedSandboxClient/resume pair).
+ */
+interface SelfhostedSessionBuild {
+    /** The workspace the machine's control-plane subject is scoped to. */
+    workspaceId: string;
+    /** The enrollment id == the agent id `agent.<ws>.<id>.rpc` addresses. */
+    agentId: string;
+    /** The relay-URL shape for stream endpoints. */
+    relay: SelfhostedRelayConfig;
+    /** Lazily build the live ControlRpc (the request-scoped NATS connection). */
+    controlRpcFactory: () => ControlRpc;
+    /** The lease/active epoch the session is fenced under (echoed on every op). */
+    epoch: number;
+    /** The run's declared sandbox environment → the session manifest.environment
+     *  (env-parity; see SelfhostedSessionDeps.environment). */
+    environment?: Record<string, string>;
+    /** The session working directory (the path/cwd base). Null/absent ⇒ workspace_root. */
+    workingDir?: string | null;
+    /** Override the control-op timeout (tests). */
+    timeoutMs?: number;
+}
+/**
+ * Build a live selfhosted session bound to a target machine: construct a request-
+ * scoped `SelfhostedSandboxClient` (fenced under `epoch`, carrying the run's env +
+ * working dir) and `resume()` it (= re-address the live subject — no provider box
+ * is created). Returns BOTH the client (the OWNED-sandbox client the turn injects,
+ * whose `serializeSessionState` round-trips `{agentId}`) and the live session.
+ *
+ * Shared by:
+ *   - the routing resolver (backend-resolver.ts) — a swap target, where only the
+ *     session is needed; and
+ *   - the worker turn's machine-primary establish branch — where the client is the
+ *     owned-sandbox client AND the session is the pinned routing default.
+ * Factoring it here keeps the two builds identical (no divergence in the fence
+ * epoch, env threading, or working-dir base).
+ */
+declare function buildSelfhostedBackendSession(deps: SelfhostedSessionBuild): Promise<{
+    client: SelfhostedSandboxClient;
+    session: SelfhostedSession;
+}>;
+/**
+ * The selfhosted NotFound discriminator — THE load-bearing safety property
+ * (dossier §10.2/§19): for selfhosted, `agent-offline` (no responder) is NEVER a
+ * provider NotFound. A user's real machine is not recreatable; if the lease saw
+ * agent-offline as NotFound it would cold-create a RIVAL box (a Modal box) for
+ * the user's machine. So this ALWAYS returns FALSE for selfhosted — there is no
+ * "box gone, recreate it" condition. An OS-level file NotFound is an op-level
+ * error the fs layer 404s; it is likewise NOT a session-recreate condition.
+ *
+ * `establishSandboxSessionFromEnvelope` cold-restores ONLY when the per-backend
+ * NotFound discriminator returns true; returning false here guarantees the
+ * selfhosted path never cold-creates a rival — the op surfaces agent_offline and
+ * the caller backs off / retries.
+ */
+declare function isSelfhostedProviderNotFoundError(_error: unknown): false;
+
+/**
+ * The structural slice of the M2 `@opengeni/db` `EnrollmentRecord` the selfhosted
+ * negotiation reads. Defined STRUCTURALLY (not imported from `@opengeni/db`) so
+ * the agent-loop-free sandbox leaf does not couple to the DB package's graph —
+ * the API/worker pass an `EnrollmentRecord`, which satisfies this shape. The
+ * fields: `status` (active gates reachability), `exposure` +
+ * `allowScreenControl` (whole-machine + screen-control consent),`hasDisplay`
+ * (the display plane), `lastSeenAt` (the reconnecting-window disambiguator).
+ */
+interface SelfhostedEnrollment {
+    status: string;
+    exposure: string;
+    allowScreenControl: boolean;
+    hasDisplay: boolean;
+    lastSeenAt: string | null;
+}
+/** The derived liveness state of a selfhosted machine (the online/offline/
+ *  reconnecting/consent/display matrix). */
+interface SelfhostedLivenessState {
+    /** The dominant machine state. */
+    state: "online" | "reconnecting" | "offline";
+    /** Whole-machine + screen-control consent acknowledged (gates desktop input). */
+    consented: boolean;
+    /** A display (real or Xvfb) is present (gates the desktop pixel plane). */
+    hasDisplay: boolean;
+}
+/**
+ * The window after `lastSeenAt` within which a missed liveness probe is read as a
+ * transient BLIP (`reconnecting`) rather than a hard `offline`. Mirrors the
+ * resiliency model (§10.6: reconnecting after 1 missed window, offline after
+ * ~30s). A probe miss with a lastSeenAt inside this window → reconnecting.
+ */
+declare const SELFHOSTED_RECONNECT_WINDOW_MS = 30000;
+/**
+ * Derive the selfhosted liveness state from the enrollment row + a liveness probe
+ * outcome. The probe is the authoritative "is the agent answering NOW" signal;
+ * `lastSeenAt` disambiguates a probe-miss into reconnecting (recent) vs offline
+ * (stale / never seen).
+ *
+ *   - no enrollment / revoked         → offline (the machine isn't enrolled).
+ *   - probe responded                 → online.
+ *   - probe missed, lastSeenAt recent → reconnecting (a transient blip).
+ *   - probe missed, lastSeenAt stale  → offline.
+ */
+declare function selfhostedLiveness(input: {
+    enrollment: SelfhostedEnrollment | null;
+    /** The ControlRpc Ping outcome: true iff a responder answered. */
+    probeResponded: boolean;
+    /** Override the clock (tests). */
+    now?: Date;
+}): SelfhostedLivenessState;
+interface SelfhostedNegotiationInput {
+    sessionId: string;
+    os?: SandboxOs;
+    leaseEpoch: number;
+    /** The M2 enrollment row for the machine (null → never enrolled → offline). */
+    enrollment: SelfhostedEnrollment | null;
+    /** A live liveness probe — typically `session.ping()`. When a session is
+     *  provided this is called; otherwise pass `probeResponded` explicitly. */
+    session?: Pick<SelfhostedSession, "ping">;
+    /** Explicit probe outcome (when no session is given, e.g. a pure read). */
+    probeResponded?: boolean;
+    /** The deployment desktop/terminal/computer-use policy toggles (threaded
+     *  through to the base negotiation). */
+    desktopEnabled?: boolean;
+    terminalEnabled?: boolean;
+    computerUseEnabled?: boolean;
+    /** Whether the calling principal acknowledged the un-redacted desktop. */
+    desktopAcknowledged?: boolean;
+    shared?: boolean;
+    sharedSessionIds?: string[];
+    /** Override the clock (tests). */
+    now?: Date;
+}
+/**
+ * Negotiate the full `SessionCapabilities` document for a selfhosted machine,
+ * with the online/offline/reconnecting/consent_required/display_unavailable cells
+ * correctly decided. Async because it issues the liveness probe.
+ */
+declare function negotiateSelfhostedCapabilities(input: SelfhostedNegotiationInput): Promise<SessionCapabilities>;
+
+/** A pluggable exec handler — given an ExecRequest, return an ExecResponse (or
+ *  throw to surface a synthesized error). Defaults to a trivial echo. */
+type MockExecHandler = (req: ExecRequest) => ExecResponse | Promise<ExecResponse>;
+interface MockAgentResponderOptions {
+    /** Whether a responder exists at all. When false EVERY request yields an
+     *  AGENT_OFFLINE error (the "machine is offline" condition) — used to drive the
+     *  agent_offline capability + the isProviderSandboxNotFoundError test. */
+    online?: boolean;
+    /** Whether the agent has acknowledged whole-machine / screen-control consent.
+     *  When false, an op gated on consent yields CONSENT_REQUIRED. Defaults true. */
+    consented?: boolean;
+    /** Force the agent into a draining posture (every op → DRAINING). */
+    draining?: boolean;
+    /** Seed files (path → string|Uint8Array) into the virtual filesystem. */
+    files?: Record<string, string | Uint8Array>;
+    /** A custom exec handler; defaults to an echo of argv. */
+    exec?: MockExecHandler;
+    /** The hostname the mock reports (so PTY/exec `$HOSTNAME`-style asserts work). */
+    hostname?: string;
+}
+/**
+ * An in-process `ControlRpc` answering the agent op table against an in-memory
+ * virtual filesystem. Drive a `SelfhostedSession` with this to test exec /
+ * readFile / writeFile / list / stat round-trips without any NATS.
+ */
+declare class MockAgentResponder implements ControlRpc {
+    private online;
+    private readonly consented;
+    private readonly draining;
+    private readonly files;
+    private readonly execHandler;
+    readonly hostname: string;
+    /** Every request seen, for assertion (subject + decoded ControlRequest). */
+    readonly requests: Array<{
+        subject: string;
+        req: ControlRequest;
+    }>;
+    constructor(opts?: MockAgentResponderOptions);
+    /** Flip the responder offline mid-test (a deliberate stop / blip). */
+    setOnline(online: boolean): void;
+    /** Read a file the session wrote (test assertion helper). */
+    fileText(path: string): string | undefined;
+    request(subject: string, req: ControlRequest, _opts: {
+        timeoutMs: number;
+    }): Promise<ControlResponse>;
+}
+
+/** The per-session active-sandbox pointer the proxy re-reads on every op. Mirror
+ *  of `@opengeni/db`'s `ActiveSandboxPointer` (structural, so the leaf does not
+ *  import the DB package). `activeSandboxId === null` == "use the session's own
+ *  group sandbox" (the default/backward-compat target). */
+interface ActivePointer {
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    /** The session's working directory — the path/cwd base for a selfhosted backend
+     *  (threaded into the SelfhostedSession via the resolver). `null`/absent ⇒ the
+     *  default workspace_root behavior. Optional so the default-pointer fallback
+     *  (`{ activeSandboxId: null, activeEpoch: 0 }`) the readPointer wiring synthesizes
+     *  when no row exists needs no extra field. Only the selfhosted branch reads it;
+     *  the modal/default branches ignore it. */
+    workingDir?: string | null;
+}
+/**
+ * The structural slice of a backend session the routing proxy forwards to. It is
+ * a superset-by-optionality of every backend's surface (Modal's `SandboxSession`
+ * AND the `SelfhostedSession`): each method is optional because a heterogeneous
+ * target may or may not implement it, and the proxy reflects that at call-time.
+ */
+interface RoutableBackendSession {
+    state?: unknown;
+    exec?(args: unknown): Promise<unknown>;
+    execCommand?(args: unknown): Promise<string>;
+    writeStdin?(args: unknown): Promise<string>;
+    readFile?(args: unknown): Promise<string | Uint8Array>;
+    writeFile?(args: unknown): Promise<unknown>;
+    createEditor?(runAs?: string): unknown;
+    listDir?(args: unknown): Promise<unknown>;
+    pathExists?(path: string, runAs?: string): Promise<boolean>;
+    viewImage?(args: unknown): Promise<unknown>;
+    materializeEntry?(args: unknown): Promise<void>;
+    supportsPty?(): boolean;
+    resolveExposedPort?(port: number): Promise<ExposedPortEndpoint>;
+    serializeSessionState?(): Promise<unknown>;
+    desktopInput?(event: unknown): Promise<void>;
+    screenshot?(): Promise<{
+        png: Uint8Array;
+        width: number;
+        height: number;
+    }>;
+}
+/** The resolved active backend for an epoch: the live session + the sandbox id it
+ *  belongs to (`null` == the group sandbox) so a fence-retry can detect a move. */
+interface ResolvedActiveBackend {
+    session: RoutableBackendSession;
+    /** The sandbox id this backend serves (`null` == the session's group sandbox). */
+    sandboxId: string | null;
+    /** A label for diagnostics ("modal" | "selfhosted" | the sandbox name). */
+    kind: string;
+}
+interface RoutingSandboxSessionDeps {
+    /**
+     * The DEFAULT backend resolved at construction time (the same shape `resolve()`
+     * caches as `lastResolved`). This seeds `session.state` BEFORE the first op so a
+     * consumer that reads `session.state.manifest` at turn START — the @openai/agents
+     * SDK does, before any tool runs — sees the real default backend's state object
+     * (and writes to `session.state.manifest = …` land on it by reference), instead
+     * of an empty `{}` that crashes serializeManifestEnvironment /
+     * validateProvidedSessionManifestUpdate. The default-pointer case
+     * (`activeSandboxId === null`) resolves synchronously to this same backend, so
+     * seeding it here is byte-identical to what the first `resolve()` would produce.
+     */
+    defaultResolved?: ResolvedActiveBackend;
+    /** Re-read the per-session active pointer. Called on EVERY op (the per-call
+     *  re-resolve that makes a mid-turn swap visible to the next tool call). */
+    readPointer(): Promise<ActivePointer>;
+    /**
+     * Resolve the active backend session for a pointer. The proxy memoizes the
+     * result by `activeEpoch`, so this is called at most once per epoch (per op the
+     * pointer is re-read, but the heavy resolve only re-runs when the epoch moved).
+     * For `pointer.activeSandboxId === null` this returns the default/group backend
+     * (typically the already-established turn box); for a non-null target it builds
+     * the target backend (a sibling Modal box or a selfhosted machine session).
+     */
+    resolveActiveBackend(pointer: ActivePointer): Promise<ResolvedActiveBackend>;
+    /** Max fence/stale retries within a single op before surfacing the error.
+     *  Defaults to 3 — enough to absorb a couple of concurrent swaps, bounded so a
+     *  swap-storm cannot loop forever. */
+    maxFenceRetries?: number;
+    /** Optional structured-log sink for swap/fence transitions (diagnostics). */
+    onTransition?: (event: RoutingTransitionEvent) => void;
+}
+interface RoutingTransitionEvent {
+    type: "resolved" | "fenced-retry" | "epoch-changed";
+    fromEpoch: number;
+    toEpoch: number;
+    sandboxId: string | null;
+    kind: string;
+}
+/** Thrown when the active backend does not implement the requested op (a
+ *  heterogeneous target whose surface lacks the method the caller reached for). */
+declare class RoutingUnsupportedError extends Error {
+    readonly name = "RoutingUnsupportedError";
+    constructor(op: string, kind: string);
+}
+/**
+ * ONE stable session-shaped object the SDK binds to. Every method re-reads the
+ * pointer, resolves the active backend (cached by epoch), and dispatches. A
+ * stale-epoch fence (the pointer moved mid-op) re-resolves and retries.
+ *
+ * The proxy implements ALL of the consumed surface so the SDK (which binds method
+ * presence ONCE) always sees `exec`/`readFile`/`resolveExposedPort`/… present. If
+ * the CURRENTLY-active backend lacks a method, the proxy applies the natural
+ * fallback (`exec`→`execCommand`) or throws `RoutingUnsupportedError` — degrade is
+ * a value, not a crash.
+ *
+ * `state` is a STABLE getter so a consumer reading `session.state` (channel-a's
+ * `readInstanceId`, the docker-network decoration) gets a coherent snapshot of the
+ * currently-active backend without a method call.
+ */
+declare class RoutingSandboxSession implements RoutableBackendSession {
+    private readonly deps;
+    private readonly maxFenceRetries;
+    private cachedEpoch;
+    private cached;
+    private lastResolved;
+    desktopInput?: (event: unknown) => Promise<void>;
+    screenshot?: () => Promise<{
+        png: Uint8Array;
+        width: number;
+        height: number;
+    }>;
+    constructor(deps: RoutingSandboxSessionDeps);
+    /**
+     * A method-free read of the active backend's `state` (best-effort: the last
+     * resolved backend, falling back to the default backend resolved at construction
+     * so this is non-empty BEFORE the first op). Consumers that read `session.state`
+     * (instanceId/decoration) get the active backend's state.
+     *
+     * CRITICAL: this returns the underlying backend's `state` OBJECT BY REFERENCE
+     * (never a fresh `{}` when a backend exists). The @openai/agents SDK both READS
+     * `session.state.manifest` and WRITES `session.state.manifest = nextManifest`
+     * (providedSessionManifest); returning the live object by reference means those
+     * property writes land on the real backend state and persist. Only when NO
+     * backend has been resolved yet (no default seeded, no op dispatched) do we
+     * return an empty object — and that path no longer occurs in the turn wiring,
+     * which always seeds `defaultResolved`.
+     */
+    get state(): unknown;
+    /**
+     * Re-read the pointer and resolve the active backend, using the per-epoch cache.
+     * The cache is keyed by `activeEpoch`: if the epoch is unchanged we return the
+     * cached backend; if it moved (a swap) we re-resolve and update the cache. This
+     * is THE per-call re-read that makes a mid-turn swap land on the next op.
+     */
+    private resolve;
+    /**
+     * Dispatch an op to the currently-active backend, retrying on a stale-epoch
+     * fence. The sequence per attempt:
+     *   1. re-read the pointer + resolve the active backend (cached by epoch),
+     *   2. run `fn(activeSession)`,
+     *   3. on a FENCE error (the pointer moved under us / the backend rejected a
+     *      stale epoch), INVALIDATE the cache and retry against the re-resolved
+     *      active sandbox — up to `maxFenceRetries`.
+     * A non-fence error propagates immediately (it is a real op failure, not a swap
+     * race).
+     */
+    private dispatch;
+    exec(args: unknown): Promise<unknown>;
+    execCommand(args: unknown): Promise<string>;
+    writeStdin(args: unknown): Promise<string>;
+    readFile(args: unknown): Promise<string | Uint8Array>;
+    writeFile(args: unknown): Promise<unknown>;
+    listDir(args: unknown): Promise<unknown>;
+    pathExists(path: string, runAs?: string): Promise<boolean>;
+    viewImage(args: unknown): Promise<unknown>;
+    materializeEntry(args: unknown): Promise<void>;
+    /** PTY support reflects the LAST-resolved backend (a synchronous probe; the SDK
+     *  reads it to decide if the terminal is interactive). It cannot re-read the
+     *  pointer (synchronous), so it answers from the last resolve — coherent with
+     *  the resolve the surrounding op already performed. Defaults false before the
+     *  first resolve. */
+    supportsPty(): boolean;
+    /** createEditor is a synchronous factory in the SDK surface; it binds to the
+     *  last-resolved backend's editor (or the default backend before the first op).
+     *  Returns undefined when the active backend has no editor (channel-a falls back
+     *  to its exec-based write path). */
+    createEditor(runAs?: string): unknown;
+    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
+    /** Serialize the active backend's session state. Used by the resume-by-id seam
+     *  to fold the live box onto the lease. Dispatches to the active backend. */
+    serializeSessionState(): Promise<unknown>;
+    /** Force a resolve (priming the proxy before the first op so `state`/`supportsPty`
+     *  read a real backend). Optional — every op resolves lazily anyway. */
+    prime(): Promise<ResolvedActiveBackend>;
+}
+
+/** The structural slice of a first-class sandbox the resolver reads (mirror of
+ *  `@opengeni/db`'s `SandboxRecord`; structural so the leaf does not import DB). */
+interface RoutableSandbox {
+    id: string;
+    kind: "modal" | "selfhosted" | string;
+    name: string;
+    /** For a selfhosted sandbox this is its enrollment id (== the agent id the
+     *  control-plane subject `agent.<ws>.<id>.rpc` addresses). Null for modal. */
+    enrollmentId: string | null;
+}
+interface ActiveBackendResolverDeps {
+    /** The workspace the session belongs to (the control-plane subject scope). */
+    workspaceId: string;
+    /** The session's own group sandbox session — the DEFAULT target
+     *  (`activeSandboxId === null`). Already established (lease-owned); the proxy
+     *  never re-establishes it. */
+    defaultBackend: RoutableBackendSession;
+    /** A label for the default backend (its backend id: "modal"/"selfhosted"/…). */
+    defaultKind: string;
+    /** Look up a first-class sandbox by id (the swap target). Returns null when the
+     *  id is unknown or not in this workspace (the caller 409s the swap). */
+    getSandbox(sandboxId: string): Promise<RoutableSandbox | null>;
+    /** Build a live `ControlRpc` for the selfhosted control plane (the request-
+     *  scoped NATS connection). Returns a ControlRpc whose offline/timeout maps to
+     *  agent_offline/agent_reconnecting (never a NotFound). */
+    controlRpcFactory(): ControlRpc;
+    /** The relay-URL shape config for selfhosted stream endpoints. */
+    relay: SelfhostedRelayConfig;
+    /** Establish (resume-by-id) a NON-DEFAULT modal target's box session for a swap.
+     *  Supplied by the API/worker (a closure over the sibling sandbox's lease). When
+     *  absent, a modal swap target surfaces as unsupported (the caller validated
+     *  liveness, so this is the "modal swap not wired in this context" guard). */
+    establishModalTarget?: (sandbox: RoutableSandbox) => Promise<RoutableBackendSession>;
+    /** Override the selfhosted control-op timeout (tests). */
+    selfhostedTimeoutMs?: number;
+    /**
+     * The run's declared sandbox environment — the SAME `Record<string,string>` the
+     * worker turn threads into the agent's TARGET manifest (and into the group box at
+     * create). Threaded into a selfhosted swap target's session so its
+     * `state.manifest.environment` EQUALS the turn's, making the SDK's per-turn
+     * provided-session manifest-env delta empty (validateNoEnvironmentDelta).
+     * WITHOUT this a pin-to-vm turn throws "Live sandbox sessions cannot change
+     * manifest environment variables". Omitted → `{}` (the test/negotiation path).
+     */
+    environment?: Record<string, string>;
+    /**
+     * A pre-established selfhosted session to PIN for the STEADY-STATE machine
+     * pointer (the worker turn's machine-primary path, Stage D). When the pointer
+     * targets THIS sandbox at THIS epoch, the resolver returns this SAME instance
+     * instead of building a fresh `SelfhostedSession`. This is the instance-identity
+     * pin: the SDK reads/writes `state.manifest` at turn START via the proxy's `state`
+     * getter (which reads the default/last-resolved backend's state) and then reads it
+     * per op via this resolver — those MUST land on ONE SelfhostedSession/manifest, or
+     * a turn-start manifest write is invisible to the per-op reads (two-instance
+     * divergence). A swap AWAY (a different sandbox id, or the same id at a moved epoch)
+     * falls through to a fresh build under the new epoch. Omitted for the API/live-swap
+     * path (which always builds fresh — it has no pre-established turn session).
+     */
+    pinnedSelfhosted?: {
+        sandboxId: string;
+        epoch: number;
+        session: RoutableBackendSession;
+    };
+}
+/** Thrown when a swap target cannot be resolved (unknown sandbox, or a modal
+ *  target with no establisher in this context). The caller maps it to a 409. */
+declare class ActiveBackendUnresolvableError extends Error {
+    readonly name = "ActiveBackendUnresolvableError";
+    constructor(message: string);
+}
+/**
+ * Build the `resolveActiveBackend(pointer)` closure for a `RoutingSandboxSession`.
+ * The returned closure is re-invoked by the proxy whenever the active_epoch moves
+ * (the per-epoch cache miss), so it must be cheap-and-correct for the steady-state
+ * (default pointer → the already-established group box) and build a fresh backend
+ * for a swap target.
+ *
+ *  - `activeSandboxId === null` → the default group backend (no re-establish).
+ *  - a selfhosted target → a `SelfhostedSession` bound to the enrollment agentId,
+ *    fenced under `pointer.activeEpoch` (echoed on every ControlRequest so the
+ *    agent can reject a stale op with ERROR_CODE_FENCED — the swap-race fence).
+ *  - a modal target → `establishModalTarget` (the resume-by-id closure), else
+ *    unresolvable.
+ */
+declare function makeActiveBackendResolver(deps: ActiveBackendResolverDeps): (pointer: ActivePointer) => Promise<ResolvedActiveBackend>;
+
+/**
+ * Construct the raw provider SandboxClient for the configured backend. Registry-
+ * driven (the old flat if/else is gone): the backend's ProviderRegistration owns
+ * validateCredentials + build, with per-provider units/field-names. Returns
+ * undefined for "none".
+ *
+ * The desktop stream port (6080) is merged into exposedPorts for every desktop-
+ * capable (backend, os) when desktop is enabled AND the provider cannot expose
+ * ports on demand (modal/runloop/e2b pre-declare; blaxel resolves on demand).
+ * Existing modal/docker/local construction is behavior-preserved.
+ */
+declare function createSandboxClient(settings: Settings, environment?: Record<string, string>): unknown;
+/**
+ * Construct the raw provider SandboxClient for an EXPLICIT backend, independent
+ * of settings.sandboxBackend. This is the resume-by-id builder the per-turn
+ * resume path (and the API-direct control plane) call: a lease's box was created
+ * on a specific backend (the envelope's backendId / the lease's
+ * resume_backend_id), and the client that reattaches to it must be built for
+ * THAT backend, not the process's currently-configured default. When the backend
+ * equals settings.sandboxBackend this is identical to createSandboxClient
+ * (behavior-preserved). Returns undefined for "none".
+ */
+declare function createSandboxClientForBackend(backend: SandboxBackend, settings: Settings, environment?: Record<string, string>): unknown;
+/**
+ * Extract the sandbox recovery entry from a run state as a plain JSON record,
+ * for storage decoupled from the RunState blob (issue #35). Encapsulates the
+ * underscore-internal `_sandbox` read in exactly one place.
+ */
+declare function sandboxStateEntryFromRunState(state: unknown): Record<string, unknown> | null;
+/**
+ * Items-mode counterpart of restoredSandboxSessionState: rebuild the live
+ * sandbox session state from a stored entry (as produced by
+ * sandboxStateEntryFromRunState) instead of from a RunState blob.
+ */
+declare function restoredSandboxSessionStateFromEntry(entry: Record<string, unknown>, client: unknown): Promise<SandboxSessionState | undefined>;
+/**
+ * Read the persisted /workspace snapshot archive off a lease envelope's
+ * `sessionState` (sandbox-file-persistence). The reaper (persistDrainSnapshot)
+ * folds the base64 archive — a Modal native snapshot-ref or a tar archive, the
+ * exact bytes `session.persistWorkspace()` returned — at
+ * `sessionState.workspaceArchive`. Cold-restore decodes it and replays it via
+ * `session.hydrateWorkspace(archive)` on the freshly-created box so /workspace is
+ * restored. Returns undefined when the envelope carries no archive (a box that
+ * was never drain-persisted, or a non-persistence config that stored none).
+ *
+ * It is deliberately read SEPARATELY from deserializeSandboxSessionStateEnvelope:
+ * the archive does NOT ride serializeSessionState (it originates at reaper time),
+ * and the SDK's deserializeSessionState must NOT receive it (it is an opaque
+ * runtime-level field, not provider state).
+ */
+declare function readWorkspaceArchiveFromEnvelopeSessionState(sessionState: unknown): Uint8Array | undefined;
+/** Decode the Modal snapshot id out of a persisted base64 archive ref, or
+ *  undefined when the archive is a tar payload (no provider snapshot to GC) or
+ *  is unparseable. Used only for keep-latest-per-lease snapshot GC. */
+declare function decodeModalSnapshotId(archive: Uint8Array): string | undefined;
+/**
+ * Best-effort GC of a SUPERSEDED Modal filesystem/directory snapshot
+ * (sandbox-file-persistence). restoreSnapshotFilesystem terminates the previous
+ * SANDBOX but never deletes the prior SNAPSHOT image, so snapshots accumulate
+ * unbounded across warm/cold cycles. The reaper keeps only the latest per lease:
+ * when it writes a NEW archive it passes the PRIOR archive here to delete its
+ * image via the live session's Modal client (`session.modal.images.delete(id)` —
+ * the same API the SDK uses for directory images). Never throws (GC is a
+ * best-effort backstop; a leaked snapshot is a cost issue, not a correctness one).
+ * A tar archive (no snapshot id) is a no-op. Returns the deleted snapshot id (or
+ * undefined when nothing was deleted) for observability.
+ */
+declare function deletePriorPersistedSnapshot(session: unknown, priorArchiveBase64: string | null | undefined): Promise<string | undefined>;
+declare function deserializeSandboxSessionStateEnvelope(client: SandboxClient, envelope: unknown): Promise<SandboxSessionState | undefined>;
+/** A live, externally-owned sandbox session re-established from the group lease
+ *  envelope. The caller injects `{client, session, sessionState}` NON-OWNED into
+ *  the run (or drives session.exec/readFile/resolveExposedPort directly) and
+ *  drops the handle when done — the lease, not this handle, owns the box. */
+type EstablishedSandboxSession = {
+    client: unknown;
+    session: unknown;
+    sessionState: unknown;
+    instanceId: string;
+    backendId: string;
+};
+/**
+ * Per-provider NotFound discriminator. The @openai/agents-extensions
+ * `isProviderSandboxNotFoundError` / `assertResumeRecreateAllowed` helpers live
+ * under `@openai/agents-extensions/sandbox/shared`, which is NOT an exported
+ * subpath (the package `exports` map only exposes `./sandbox/<provider>`), so we
+ * re-implement the discrimination here by inspecting the thrown error shape.
+ *
+ * "Box no longer running" (the box was reaped / idled out / 24h-ceiling) is the
+ * ONLY error that licenses a cold-restore via create(). Every other resume
+ * failure (transient provider error, auth, network) must propagate so the caller
+ * backs off — never spawns a rival box. We err on the side of NOT recreating:
+ * an unrecognized error is treated as "not NotFound" (propagate), because a
+ * false-positive recreate is the dangerous direction (double-spawn).
+ */
+declare function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean;
+/**
+ * Resume the one box by id from its recovery envelope, or cold-restore from the
+ * snapshot when the provider reports it gone. The envelope is the lease's
+ * box-identity descriptor (the same per-turn `_sandbox` envelope upserted by the
+ * turn activity). A null envelope means a cold session that was never warmed →
+ * create() directly.
+ *
+ *  - `opts.backendOverride ?? envelope.backendId ?? settings.sandboxBackend`
+ *    selects the backend; the client is built for THAT backend (resume-by-id is
+ *    fenced to the original provider).
+ *  - warm reattach: deserialize the envelope sessionState → client.resume(state)
+ *    (no lock; R4-safe). On a provider NotFound, cold-restore via create().
+ *  - cold restore / cold session: client.create() — the ONLY create() site.
+ */
+declare function establishSandboxSessionFromEnvelope(settings: Settings, envelope: Record<string, unknown> | null, opts: {
+    sessionId: string;
+    backendOverride?: SandboxBackend;
+    environment?: Record<string, string>;
+}): Promise<EstablishedSandboxSession>;
+/**
+ * Fold a freshly-established (or resumed) sandbox session into the persistable
+ * `resume_state` envelope the lease stores — the SAME `{ backendId, sessionState }`
+ * shape `establishSandboxSessionFromEnvelope` consumes to RESUME BY ID. The
+ * API-direct control plane (viewer attach / Channel-A) MUST persist this onto the
+ * lease at warm-commit time, or a later op (which reads the lease's resume_state)
+ * has nothing to resume from and COLD-CREATES A RIVAL BOX — the box-churn the
+ * prove-it surfaced (fs.write then fs.read 404'd on a different box; N Channel-A
+ * ops leaked N boxes). Returns null when the client cannot serialize (the caller
+ * stores null and the box rides the provider idle-timeout — no rival spawn, just
+ * no warm-reattach).
+ */
+declare function serializeEstablishedSandboxEnvelope(established: EstablishedSandboxSession): Promise<Record<string, unknown> | null>;
+
+export { type ActiveBackendResolverDeps, ActiveBackendUnresolvableError, type ActivePointer, ChannelAConflictError, type ChannelAEmitter, type ChannelAExecArgs, type ChannelAExecResult, ChannelANotFoundError, type ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, type ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, type DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, type EnsureDisplayStackOptions, type EnsureDisplayStackResult, type EnsureTerminalServerOptions, type EnsureTerminalServerResult, type EstablishedSandboxSession, type ExposeStreamPortInput, type ExposeStreamPortResult, type ExposedPortEndpoint, type FinalizeRecordingResult, type MintStreamTokenInput, MockAgentResponder, type MockAgentResponderOptions, type MockExecHandler, NatsControlRpc, type NatsRequestConnection, type NegotiationContext, type NumstatEntry, PROVIDER_REGISTRY, type ProviderConstructionContext, type ProviderRegistration, type RecordingCodec, type RecordingContentType, RecordingError, type RecordingProcess, RecordingUnavailableError, type ResolvedActiveBackend, type RoutableBackendSession, type RoutableSandbox, RoutingSandboxSession, type RoutingSandboxSessionDeps, type RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, type SandboxChannelAServiceOptions, SandboxConfigError, SandboxProviderUnavailableError, type SelfhostedApplyDiff, SelfhostedControlError, type SelfhostedEditor, type SelfhostedEnrollment, type SelfhostedExecArgs, type SelfhostedExecResult, type SelfhostedImageOutput, type SelfhostedLivenessState, type SelfhostedNegotiationInput, type SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, type SelfhostedSessionBuild, type SelfhostedSessionDeps, type SelfhostedSessionState, type SelfhostedUnavailableReason, type StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, tearDownDisplayStack, tearDownTerminalServer, timeoutAgentError, timeoutControlResponse, verifyStreamToken };