@opengeni/runtime 0.14.1 → 0.14.15

package/dist/sandbox/recording.d.ts

@@ -0,0 +1,80 @@
+import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
+export { DESKTOP_STREAM_PORT };
+export type RecordingCodec = "h264-mp4" | "vp9-webm";
+export type RecordingContentType = "video/mp4" | "video/webm";
+export declare function contentTypeForCodec(codec: RecordingCodec): RecordingContentType;
+export declare function extForCodec(codec: RecordingCodec): string;
+/** No exec/execCommand on the session — the box cannot run ffmpeg. */
+export declare class RecordingUnavailableError extends Error {
+    constructor(message: string);
+}
+/** ffmpeg failed, the file is missing, or the artifact is over its size limit. */
+export 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");
+}
+export type StartRecordingInput = {
+    recordingId: string;
+    codec?: RecordingCodec;
+    framerate?: number;
+    maxSeconds?: number;
+    dimensions?: [number, number];
+    display?: string;
+    runAs?: string;
+    tmpDir?: string;
+};
+export 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.
+ */
+export 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.
+ */
+export declare function stopRecording(session: unknown, proc: RecordingProcess): Promise<void>;
+export type RecordingArtifactMetadata = {
+    contentType: RecordingContentType;
+    sizeBytes: number;
+    durationSeconds: number;
+};
+/**
+ * Inspect and size-gate the finalized recording while it is still on the box.
+ * No recording bytes cross into the worker process.
+ */
+export declare function inspectRecordingArtifact(session: unknown, proc: RecordingProcess, maxBytes?: number): Promise<RecordingArtifactMetadata>;
+/**
+ * Upload the finalized artifact directly from the sandbox to a scoped object-
+ * storage URL. The worker carries only the short URL/headers and metadata; it
+ * never materializes a base64 string or Uint8Array for a recording that may be
+ * hundreds of megabytes. curl's success marker makes an exec transport that
+ * returns non-zero command output instead of throwing still fail closed.
+ */
+export declare function uploadRecordingArtifact(session: unknown, proc: RecordingProcess, input: {
+    url: string;
+    requiredHeaders: Record<string, string>;
+    maxBytes?: number;
+    maxSeconds?: number;
+}): Promise<RecordingArtifactMetadata>;
+/**
+ * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
+ * and the `available` row committed — never before. Best-effort; never throws.
+ */
+export declare function deleteRecordingArtifacts(session: unknown, proc: RecordingProcess): Promise<void>;
+/** The storage object key for a recording artifact (parallels the file-asset layout). */
+export declare function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string;

package/dist/sandbox/routing/backend-resolver.d.ts

@@ -0,0 +1,173 @@
+import { type SelfhostedRelayConfig } from "../selfhosted/session";
+import type { SelfhostedOpObserver } from "../selfhosted/op-observer";
+import type { ControlRpc } from "../selfhosted/control-rpc";
+import type { ActivePointer, RoutableBackendSession, ResolvedActiveBackend } from "./routing-session";
+/** 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). */
+export 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;
+}
+export 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;
+    /**
+     * Re-resolve the session's HOME backend after the route cache is fenced.
+     *
+     * The normal path returns `defaultBackend` (the turn's already-established
+     * handle), but an API-side same-target repair can rematerialize that lease
+     * while a worker turn is still alive. Such a repair advances the route epoch
+     * without changing the null pointer; callers that can resume the current
+     * lease-owned identity may provide this callback so the next epoch does not
+     * keep dispatching to the dead pre-repair object. This callback must never
+     * create a provider or replay an operation.
+     */
+    resolveDefaultBackend?: (pointer: ActivePointer) => Promise<ResolvedActiveBackend>;
+    /** 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>;
+    /** The selfhosted CONTROL-op timeout (ping/fs/desktop/pty) for a swap/pin target.
+     *  Absent ⇒ the session's 30s default. */
+    selfhostedTimeoutMs?: number;
+    /** The selfhosted EXEC process deadline for a swap/pin target, distinct from the
+     *  control timeout (a swapped-to machine runs real commands too). Absent ⇒ falls
+     *  back to the control timeout, as in the session leaf. */
+    selfhostedExecTimeoutMs?: number;
+    /** The per-op observer threaded into a selfhosted swap/pin target (out-of-band
+     *  telemetry — metrics + machine.* events). Absent ⇒ no-op. */
+    selfhostedOnOp?: SelfhostedOpObserver;
+    /**
+     * 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;
+    };
+    /**
+     * Whether `defaultBackend` IS the session's home box — i.e. whether the null pointer
+     * (== home) may resolve to it. Defaults to TRUE (omitted): a genuine machine-HOME turn
+     * (home IS the machine) and a Modal-home turn established on its group box both pass/omit
+     * true, so null resolves to `defaultBackend` as before. Set explicitly FALSE only for a
+     * machine-primary turn of a Modal-HOME session (pinned to a machine, group box never
+     * established this turn): the null pointer then has nothing to resolve to THIS turn, so
+     * rather than silently keep serving the pinned machine as if the detach never happened,
+     * the null branch throws a typed `home_unavailable_this_turn` error — the detach's pointer
+     * commit stands and takes effect on the NEXT turn, which starts null and establishes the
+     * home box normally. Lazily establishing the home box mid-turn on such a clear is a
+     * deferred follow-up (issue #341); until then this makes the gap fail typed-and-specific,
+     * never silent.
+     */
+    defaultIsHome?: boolean;
+}
+/** Why a persisted pointer / swap target cannot be turned into a live backend. A
+ *  typed discriminant so callers (turn-start reconcile, the swap tool, future
+ *  reports) can distinguish a stale pointer from an unaddressable enrollment from a
+ *  backend the turn context simply cannot establish — instead of string-matching
+ *  one opaque message (issue #341: "typed diagnostics that distinguish stale
+ *  pointer, offline enrollment, unsupported backend context, transient failure").
+ *   - `stale_pointer`               — the pointed-at sandbox row is gone (deleted/orphaned).
+ *   - `offline_enrollment`          — a selfhosted target carries no enrollment/agent id to address.
+ *   - `unsupported_backend_context` — a target no turn routing context can establish
+ *                                     (a non-group Modal sibling; an unknown kind).
+ *   - `transient_establishment`     — a momentary establish failure worth a retry (reserved;
+ *                                     control-plane timeouts surface as their own typed error).
+ *   - `home_unavailable_this_turn`  — the pointer was cleared to the session default (home)
+ *                                     mid-turn, but this turn started pinned to a machine and
+ *                                     never established the home box, so null has nothing to
+ *                                     resolve to THIS turn (the detach takes effect next turn). */
+export type BackendUnresolvableCode = "stale_pointer" | "offline_enrollment" | "unsupported_backend_context" | "transient_establishment" | "home_unavailable_this_turn";
+/** 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.
+ *  Carries a typed {@link BackendUnresolvableCode} in addition to the message. */
+export declare class ActiveBackendUnresolvableError extends Error {
+    readonly name = "ActiveBackendUnresolvableError";
+    readonly code: BackendUnresolvableCode;
+    constructor(code: BackendUnresolvableCode, message: string);
+}
+/** The outcome of {@link swapTargetEstablishability}. */
+export type SwapTargetEstablishability = {
+    ok: true;
+} | {
+    ok: false;
+    code: BackendUnresolvableCode;
+    reason: string;
+};
+/**
+ * THE SINGLE SOURCE OF TRUTH for "can a turn's routing context ESTABLISH this swap
+ * target?" — shared by swap/seed ADMISSION (`fleet.resolveTarget`, before the CAS
+ * pointer commit) and turn-time ESTABLISHMENT (this resolver + `wrapTurnBoxWithRouting`).
+ * Admission MUST reject any target this predicate calls unestablishable, so the
+ * pointer is never committed to a backend no turn can resume (issue #341 Shape 1:
+ * a Modal-sibling swap was admitted + epoch-bumped, then every following op
+ * stranded because no context wires an establisher for it).
+ *
+ *  - the session's OWN group box (`isSessionGroup`) is the null/home target and is
+ *    always establishable (it IS the default backend);
+ *  - a `selfhosted` machine target is establishable (`buildSelfhostedBackendSession`);
+ *    admission's separate liveness probe — not this predicate — gates online-ness;
+ *  - a NON-group `modal` target is NOT establishable: no turn context wires
+ *    `establishModalTarget` (cross-group Modal resume-by-id is a future, billing-
+ *    touching feature — sandbox-routing.ts). Wiring that establisher is the ONE
+ *    toggle that flips this branch; keep admission and the resolver in lockstep.
+ */
+export declare function swapTargetEstablishability(target: {
+    kind: string;
+    isSessionGroup: boolean;
+}): SwapTargetEstablishability;
+/**
+ * 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.
+ */
+export declare function makeActiveBackendResolver(deps: ActiveBackendResolverDeps): (pointer: ActivePointer) => Promise<ResolvedActiveBackend>;

package/dist/sandbox/routing/routing-session.d.ts

@@ -0,0 +1,401 @@
+import type { ExposedPortEndpoint } from "../stream-port";
+/** 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). */
+export 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.
+ */
+export interface RoutableBackendSession {
+    state?: unknown;
+    exec?(args: unknown): Promise<unknown>;
+    execCommand?(args: unknown): Promise<string>;
+    writeStdin?(args: unknown): Promise<string>;
+    cancelExecCommand?(opId: string): Promise<boolean>;
+    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;
+        nativeWidth: number;
+        nativeHeight: 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. */
+export 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;
+    /** Exact durable home-lease epoch for a persistable provider. Absent for
+     * connected-machine and other non-persistable route targets. */
+    leaseEpoch?: number;
+    /** Exact durable provider identity paired with `leaseEpoch`. This is internal
+     * routing metadata only; it is never projected to an agent or public API. */
+    providerInstanceId?: string;
+    /** Active-pointer epoch observed when this route was resolved. The proxy fills
+     * this internally even when a resolver omits it. */
+    activeEpoch?: number;
+}
+/** Durable identity assigned to a provider exec that yielded instead of
+ * exiting. The UUID is OpenGeni authority; the numeric provider session id is
+ * only a locator within the exact copied backend route. */
+export type RoutingRetainedProcess = {
+    id: string;
+    providerSessionId: number;
+};
+/** A yielded process was durably promoted, but the mutable authority checked
+ * after that commit was stale. The provider output must still be rejected;
+ * this result carries only the safe process identity needed to drain the exact
+ * original backend without replaying the mutation. */
+export type RoutingMutationSettlementResult = {
+    status: "retained_process_durable_output_rejected";
+    retainedProcess: RoutingRetainedProcess;
+};
+/** Exact copied route identity required to reconstruct an already-durable
+ * retained process after the request/runtime object that opened it is gone.
+ * The live session is deliberately not caller-supplied: adoption may bind only
+ * to this proxy's construction-time default backend, so it cannot resolve or
+ * follow the current active pointer. */
+export type RoutingRetainedProcessAdoption = {
+    process: RoutingRetainedProcess;
+    backend: {
+        sandboxId: string | null;
+        leaseEpoch?: number;
+        providerInstanceId?: string;
+        activeEpoch: number;
+    };
+};
+export type RoutingRetainedProcessTerminalProof = {
+    outcome: "exited";
+    exitCode: number;
+    reason: "provider_exit_banner";
+} | {
+    outcome: "lost";
+    exitCode: null;
+    reason: "provider_session_lost_banner";
+};
+export 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;
+    /** Admit a filesystem-writing operation after resolving its exact route but
+     * before invoking the provider. A rejection fails closed and is deliberately
+     * outside provider fence-retry/error handling, so it can never replay the op
+     * against a rival backend. */
+    beforeMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+    }) => Promise<unknown>;
+    /** Mark a mutation physically settled after its provider promise resolves OR
+     * rejects. A resolved result is also revalidated against the same durable
+     * route and attempt fence before its output is accepted. Settlement rejection
+     * leaves a fail-closed blocker and the mutation must never be replayed. */
+    afterMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        admission: unknown;
+        outcome: "resolved" | "rejected";
+        /** Provider result for a resolved call. Never present for rejection. */
+        result?: unknown;
+        /** Stable candidate generated before durable promotion is attempted. It is
+         * supplied only when the provider returned a positive yielded-session id. */
+        retainedProcess?: RoutingRetainedProcess;
+    }) => Promise<void | RoutingMutationSettlementResult>;
+    /** Admit one model/user-visible stdin mutation under the already-durable
+     * retained process authority. Control polling and helper execs never call it. */
+    beforeProcessMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+    }) => Promise<unknown>;
+    /** Physically settle one process-scoped stdin admission. */
+    afterProcessMutation?: (input: {
+        op: string;
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+        admission: unknown;
+        outcome: "resolved" | "rejected";
+        result?: unknown;
+    }) => Promise<void>;
+    /** Close the durable parent admission/process holder only after exact exit or
+     * matching provider-loss proof. Tracking is removed only after this resolves. */
+    settleProcess?: (input: {
+        backend: ResolvedActiveBackend;
+        process: RoutingRetainedProcess;
+        proof: RoutingRetainedProcessTerminalProof;
+    }) => Promise<void>;
+    /** Called only when an operation against the default/home backend throws a
+     * non-fence error. Wiring may classify definitive provider disappearance and
+     * atomically retire the exact lease epoch. Returning a result makes dispatch
+     * throw a typed recovery-required error WITHOUT replaying the operation (the
+     * original mutation may have reached the provider). */
+    onDefaultBackendError?: (input: {
+        op: string;
+        error: unknown;
+        kind: string;
+        backend: ResolvedActiveBackend;
+    }) => Promise<DefaultBackendLossResult | null>;
+}
+export type DefaultBackendLossResult = {
+    leaseEpoch: number;
+    recovery: "pending" | "degraded" | "unrecoverable" | "superseded";
+};
+export 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). */
+export declare class RoutingUnsupportedError extends Error {
+    readonly name = "RoutingUnsupportedError";
+    constructor(op: string, kind: string);
+}
+export declare class RoutingBackendRecoveryRequiredError extends Error {
+    readonly op: string;
+    readonly leaseEpoch: number;
+    readonly recovery: DefaultBackendLossResult["recovery"];
+    readonly name = "RoutingBackendRecoveryRequiredError";
+    readonly retryable: boolean;
+    constructor(op: string, leaseEpoch: number, recovery: DefaultBackendLossResult["recovery"]);
+}
+/** A mutating provider call was admitted but could not be settled against the
+ * exact route that admitted it. The provider may have applied the effect, so the
+ * proxy rejects the output and explicitly forbids an automatic replay. */
+export declare class RoutingMutationOutcomeUnknownError extends Error {
+    readonly op: string;
+    readonly name = "RoutingMutationOutcomeUnknownError";
+    readonly retryable = false;
+    readonly retainedProcess: RoutingRetainedProcess | null;
+    constructor(op: string, message: string, options?: {
+        cause?: unknown;
+        retainedProcess?: RoutingRetainedProcess;
+    });
+}
+/** An explicit process-aware operation named a numeric provider locator that
+ * is not retained by this routing session. Callers must never fall back to the
+ * current active pointer for such an operation. */
+export declare class RoutingRetainedProcessNotFoundError extends Error {
+    readonly providerSessionId: number;
+    readonly name = "RoutingRetainedProcessNotFoundError";
+    readonly retryable = false;
+    constructor(providerSessionId: number);
+}
+/**
+ * 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.
+ */
+export declare class RoutingSandboxSession implements RoutableBackendSession {
+    private readonly deps;
+    private readonly maxFenceRetries;
+    private cachedEpoch;
+    private cachedSandboxId;
+    private cached;
+    private lastResolved;
+    /** Provider session ids are scoped to one backend instance. Each entry copies
+     * that exact resolved route so pointer movement can never redirect stdin,
+     * polling, or process-group helpers to another box. */
+    private readonly retainedProcesses;
+    desktopInput?: (event: unknown) => Promise<void>;
+    screenshot?: () => Promise<{
+        png: Uint8Array;
+        width: number;
+        height: number;
+        nativeWidth: number;
+        nativeHeight: 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;
+    private invalidate;
+    private registerRetainedProcess;
+    private retainedProcess;
+    /** Reconstruct one process that was already promoted durably by an earlier
+     * request. Adoption never reads the active pointer and never repeats parent
+     * promotion. It can bind only to the exact construction-time default backend;
+     * callers must reject non-default routes until they can independently rebuild
+     * that provider session from its copied durable identity. */
+    adoptRetainedProcess(input: RoutingRetainedProcessAdoption): void;
+    private ensureParentPromotion;
+    private confirmDurableRejectedPromotion;
+    private settleRetainedProcess;
+    private flushPendingProcessMutation;
+    private dispatchProcessMutation;
+    private dispatchProcessControl;
+    /**
+     * 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;
+    /**
+     * The failure-visibility boundary for the `exec_command` SDK capability tool — the
+     * dominant fault surface, and the one whose thrown `SelfhostedControlError` reaches
+     * the model wrapped by the SDK's generic tool-error function as
+     * "…Please try again. Error: …" — actively wrong for a machine that is offline, a
+     * consent that is not granted, or an oversized reply. Since the SDK closure-captures
+     * its `errorFunction` (there is no seam to attach one to its internally-built tools),
+     * we render the fault into the doctrine's four fields HERE and return it as the
+     * tool's string result — legible, in-band, and free of the misleading wrapper.
+     * (`apply_patch` already surfaces `error.message` via the SDK's own catch; the
+     * skills / `view_image` tools consume their session methods internally, so they are
+     * rendered elsewhere or left to their own SDK renderers — not this string boundary.)
+     *
+     * A FENCE error is re-thrown, NEVER rendered: `dispatch` already retries it against
+     * a re-resolved backend, and a fence that escapes retries is a routing condition the
+     * turn handles, not a model-facing fault. Any non-selfhosted error (a Modal fault, a
+     * `RoutingUnsupportedError`) is re-thrown unchanged.
+     */
+    private renderSelfhostedFaultOrThrow;
+    exec(args: unknown): Promise<unknown>;
+    execCommand(args: unknown): Promise<string>;
+    writeStdin(args: unknown): Promise<string>;
+    /** Whether a positive provider session locator is still pinned to the exact
+     * backend that yielded it. This synchronous probe is used only to select the
+     * process-aware routing surface; it is not itself durable authority. */
+    hasRetainedProcess(providerSessionId: number): boolean;
+    /** Return only OpenGeni's durable UUID + provider locator. Backend/session
+     * objects remain private so a caller cannot forge route authority from this
+     * diagnostic handoff. */
+    retainedProcessIdentity(providerSessionId: number): RoutingRetainedProcess | null;
+    /** Model/user-visible stdin is a distinct workspace mutation admission under
+     * the durable retained-process holder. It never re-reads the active pointer. */
+    writeStdinForProcessMutation(args: unknown): Promise<string>;
+    /** Cancellation and drain polling are control operations. They stay pinned to
+     * the process backend and may prove terminal state, but never advance the
+     * workspace generation. */
+    writeStdinForProcessControl(args: unknown): Promise<string>;
+    /** Run a PID/PGID marker or signal helper on the retained process's exact
+     * backend. The helper is control-plane work and therefore has no workspace
+     * mutation admission of its own. */
+    execCommandForProcessControl(providerSessionId: number, args: unknown): Promise<string>;
+    cancelExecCommand(opId: string): Promise<boolean>;
+    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. The SDK's filesystem
+     *  capability calls it ONCE at tool-BIND time — `FilesystemCapability.tools()`,
+     *  every turn, before any tool runs — and throws "Filesystem sandbox sessions must
+     *  provide createEditor()" if it returns falsy. When a backend is already resolved
+     *  (eager/selfhosted routing) we bind to its editor directly, byte-for-byte as
+     *  before. But under LAZY provisioning the backend is not established yet
+     *  (defaultResolved is the synthetic unprovisioned session with no editor), so a
+     *  direct delegate returns undefined and every lazy turn would die at bind. Return a
+     *  LAZY EDITOR PROXY instead: a non-null editor whose async ops resolve the active
+     *  backend (establishing the box on first use, via `dispatch`) and delegate to its
+     *  real editor — mirroring how this proxy defers exec/readFile. Even when an
+     *  eager editor already exists, returning it directly would bypass per-edit
+     *  route resolution and mutation-generation admission, so every editor is
+     *  represented by this dispatching proxy. */
+    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>;
+}