@opengeni/runtime 0.14.1 → 0.14.15

package/dist/index-BraazrAO.d.ts

@@ -1,2931 +0,0 @@
-import { Settings } from '@opengeni/config';
-import { SandboxBackend, CapabilityDescriptor, SandboxOs, SessionCapabilities, StreamTokenPayload, RunCredentialFile, RunCredentialAuthNeeded, RunCredentialRedaction, RunCredentialsResolution, 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';
-import { SandboxSessionLike, ExecCommandArgs, SandboxClient, Manifest, SandboxSessionState } from '@openai/agents/sandbox';
-import * as modal from 'modal';
-import { ControlRequest, ControlResponse, ErrorCode, AgentError, ExecResponse, DesktopInputRequest, ExecRequest } from '@opengeni/agent-proto';
-
-declare const WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION: 1;
-type WorkspaceTreeFingerprint = {
-    algorithm: "sha256";
-    sha256: string;
-    entryCount: number;
-    fileCount: number;
-    totalFileBytes: number;
-};
-type WorkspaceArchiveDescriptor = {
-    version: typeof WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION;
-    revision: string;
-    archiveSha256: string;
-    archiveBytes: number;
-    capturedAt: string;
-    workspace: WorkspaceTreeFingerprint;
-};
-type VerifiedWorkspaceArchive = {
-    bytes: Uint8Array;
-    base64: string;
-    descriptor: WorkspaceArchiveDescriptor;
-};
-type WorkspaceArchiveIntegrityCode = "archive_metadata_missing" | "archive_metadata_invalid" | "archive_base64_invalid" | "archive_hash_mismatch" | "archive_hydration_failed" | "workspace_fingerprint_unavailable" | "workspace_changed_during_capture" | "workspace_fingerprint_mismatch";
-declare class WorkspaceArchiveIntegrityError extends Error {
-    readonly code: WorkspaceArchiveIntegrityCode;
-    readonly name = "WorkspaceArchiveIntegrityError";
-    readonly retryable: boolean;
-    constructor(code: WorkspaceArchiveIntegrityCode, message: string, options?: {
-        retryable?: boolean;
-    });
-}
-declare function parseWorkspaceArchiveDescriptor(value: unknown): WorkspaceArchiveDescriptor | null;
-declare function readVerifiedWorkspaceArchive(base64: unknown, metadata: unknown): VerifiedWorkspaceArchive | null;
-/** Hashes names, kinds, modes, symlink targets and all file bytes through one
- * deterministic GNU tar stream. Only the aggregate is returned; paths and file
- * contents never enter logs or durable metadata. */
-declare function fingerprintSandboxWorkspace(session: unknown): Promise<WorkspaceTreeFingerprint>;
-/** Capture is accepted only when the complete tree is byte-identical immediately
- * before and after the provider snapshot. A concurrent mutation makes the
- * candidate non-durable and it is never folded onto the lease. */
-declare function captureVerifiedWorkspaceArchive(session: unknown, capturedAtMs?: number): Promise<VerifiedWorkspaceArchive>;
-declare function verifyRestoredWorkspace(session: unknown, descriptor: WorkspaceArchiveDescriptor): Promise<WorkspaceTreeFingerprint>;
-
-type RuntimeMetricsHooks = {
-    onModelCall?: (input: {
-        provider: string;
-        outcome: "completed" | "failed";
-        durationSeconds: number;
-    }) => void;
-    onSandboxCreate?: (input: {
-        backend: string;
-        outcome: "completed" | "failed";
-        durationSeconds: number;
-    }) => void;
-    onSandboxWarmingTimeout?: (input: {
-        backend: string;
-    }) => void;
-    /**
-     * One completed Connected Machine (selfhosted) control op — the out-of-band
-     * telemetry twin of the in-band fault rendering. `code` is the typed wire-code
-     * NAME on a failure (bounded label cardinality); `healed` marks a success that
-     * only landed after ≥1 retry (the leading indicator of the next unhealed fault);
-     * `replyBytes` is set only on a payload-wall fault. Wired from the runtime's
-     * `SelfhostedOpObserver` seam.
-     */
-    onSandboxOp?: (input: {
-        backend: string;
-        op: string;
-        outcome: "ok" | "failed";
-        code?: string;
-        healed: boolean;
-        retries: number;
-        durationSeconds: number;
-        replyBytes?: number;
-    }) => void;
-};
-
-/**
- * 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);
-}
-/** A resume-only caller was handed a warm lease without a provider identity it
- * can resume. The lease-aware caller must retire that exact epoch and re-enter
- * admission; silently creating here would bypass the single-spawner guard. */
-declare class SandboxResumeStateUnavailableError extends Error {
-    readonly backend: SandboxBackend | string;
-    constructor(backend: SandboxBackend | 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;
-
-/**
- * Provider sandbox failure classification.
- *
- * This is deliberately structural and fail-closed. DNS failures often contain
- * the word "not found" (`ENOTFOUND`) while gRPC status values are also used by
- * unrelated SDKs and command routers. A bare numeric status (including gRPC's
- * numeric 5) is therefore not enough to retire a provider instance. Only
- * authoritative, non-transient evidence may retire a provider instance and
- * license lease recovery.
- */
-type ProviderSandboxFailureKind = "not_found" | "transient_transport" | "other";
-type ProviderSandboxFailure = {
-    kind: ProviderSandboxFailureKind;
-    /** Bounded, non-secret diagnostic suitable for logs and lifecycle events. */
-    diagnostic: string;
-};
-/** Typed transport evidence always dominates nested/string NotFound text. */
-declare function classifyProviderSandboxFailure(backendId: string, error: unknown): ProviderSandboxFailure;
-declare function isProviderSandboxNotFoundError(backendId: string, error: unknown): boolean;
-/**
- * Whether a failure from an operation routed through an already-established
- * sandbox proves that exact provider sandbox disappeared.
- *
- * Routed operations can legitimately return HTTP 404 / `NOT_FOUND` for paths,
- * files, ports, processes, and other subresources. Those generic signals are
- * sufficient for provider create/resume APIs, but they must never retire the
- * live sandbox identity after an arbitrary operation. Only an explicit
- * sandbox-scoped provider code or Modal's exact terminal sandbox grammar is
- * authoritative on this path. Transient transport evidence still dominates.
- */
-declare function isProviderSandboxGoneDuringRoutedOperation(backendId: string, error: unknown): boolean;
-declare function isProviderSandboxTransientError(backendId: string, error: unknown): boolean;
-
-type ModalSandboxAttribution = {
-    leaseId: string;
-    workspaceId: string;
-    sandboxGroupId: string;
-};
-type LiveModalSandboxLeaseAttribution = ModalSandboxAttribution & {
-    instanceId: string | null;
-    liveness?: string;
-};
-type ModalOrphanSweepTermination = {
-    sandboxId: string;
-    reason: "stale_attribution" | "unattributed";
-    tags: Record<string, string>;
-};
-type ModalOrphanSweepResult = {
-    examined: number;
-    terminated: ModalOrphanSweepTermination[];
-    skipped: number;
-};
-type RevalidateModalOrphanTermination = (candidate: ModalOrphanSweepTermination) => Promise<boolean>;
-declare function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string>;
-declare function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string>;
-type ModalModule = typeof modal;
-type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
-/** Loader seam so unit tests can inject a fake modal module. */
-type ModalModuleLoader = () => Promise<Pick<ModalModule, "ModalClient">>;
-/**
- * Resolve + cache the private-registry Modal image. No-op unless BOTH
- * `modalImageRef` and `modalImageRegistrySecret` are set. Memoized per
- * (imageRef, secret, environment) so it runs once per worker process. Awaited at
- * worker boot for the deployment-global image and at turn time for pack-scoped
- * images BEFORE the first sandbox using that ref is created; `build` then reads the
- * resolved image and otherwise falls back to the public `fromTag` path.
- */
-declare function ensureModalRegistryImage(settings: Settings, loadModal?: ModalModuleLoader): Promise<void>;
-declare function tagModalSandbox(settings: Settings, sandboxId: string, attribution: ModalSandboxAttribution): Promise<boolean>;
-declare function terminateModalSandboxById(settings: Settings, sandboxId: string): Promise<boolean>;
-declare function sweepModalOrphanSandboxes(settings: Settings, liveLeases: LiveModalSandboxLeaseAttribution[], options?: {
-    now?: Date;
-    maxTerminations?: number;
-    unattributedGraceMs?: number;
-    client?: ModalClientLike;
-    /** Re-read durable ownership immediately before provider termination. A
-     * false result or callback failure skips the destructive action. */
-    revalidateTermination?: RevalidateModalOrphanTermination;
-}): Promise<ModalOrphanSweepResult>;
-
-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;
-    /** Numeric/boolean archive completeness truth. Non-persistable targets use
-     * null/null/false; archive locations and provider details are never exposed. */
-    workspaceGeneration?: number | null;
-    archiveGeneration?: number | null;
-    archiveComplete?: boolean;
-    /** 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 (stream-token availability contract). 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 = 90000;
-/** 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); 14 is the
- *  PAINTABLE-FRAME gate (ports listening but scrot still yields an empty frame —
- *  the display is up but not actually painting). 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" | "paint" | "lock" | "timeout" | "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 DisplayStackCallerKind = "viewer" | "computer" | "unknown";
-type DisplayStackClassification = "cold" | "already_ready" | "contention" | "unknown";
-type DisplayStackTelemetryStatus = "started" | "waiting" | "completed" | "failed";
-/** Secret-free, bounded-cardinality stage observation. Provider/sandbox IDs are
- * log correlation fields, never metric labels. */
-type DisplayStackTelemetryEvent = {
-    type: "display_stack.stage";
-    requestId: string;
-    stage: string;
-    status: DisplayStackTelemetryStatus;
-    elapsedMs: number;
-    source: "host" | "sandbox";
-    classification: DisplayStackClassification;
-    callerKind: DisplayStackCallerKind;
-    sandboxId?: string;
-    leaseEpoch?: number;
-    providerSessionId?: number;
-};
-type DisplayStackTelemetryContext = {
-    callerKind: DisplayStackCallerKind;
-    sandboxId?: string;
-    leaseEpoch?: number;
-};
-type EnsureDisplayStackOptions = {
-    geometry?: DesktopGeometry;
-    /** The exposed stream port; defaults to 6080. */
-    port?: number;
-    /** Whole-operation wall-clock timeout; defaults to DISPLAY_STACK_TIMEOUT_MS. */
-    timeoutMs?: number;
-    /** Caller correlation. Supplying it enables the default structured log sink. */
-    telemetryContext?: DisplayStackTelemetryContext;
-    /** Optional non-blocking telemetry sink (tests/embedders may replace logging). */
-    onTelemetry?: (event: DisplayStackTelemetryEvent) => void | Promise<void>;
-};
-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. A ttyd process is sandbox-group-global, not
- * OpenGeni-session-specific, so it must never inherit the box-global legacy
- * Toolspace pointer. Session-scoped interactive exec/PTY uses Channel A; the
- * shared ttyd shell fails closed for Toolspace until that stream plane itself is
- * session-isolated.
- */
-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>;
-
-type RunCredentialExpectedScope = {
-    accountId: string;
-    workspaceId: string;
-    sessionId: string;
-};
-type NormalizedRunCredentialMaterial = {
-    environment: Record<string, string>;
-    files: RunCredentialFile[];
-    fileEnvironment: Record<string, string>;
-    expiresAt: Date | null;
-    authNeeded: RunCredentialAuthNeeded[];
-    redactions: RunCredentialRedaction[];
-};
-type RunCredentialCommandSession = Pick<SandboxSessionLike, "exec" | "execCommand">;
-type RunCredentialCommandRunner = (session: RunCredentialCommandSession, args: ExecCommandArgs) => Promise<unknown>;
-type RunCredentialSessionReady = (session: RunCredentialCommandSession) => Promise<void> | void;
-declare class RunCredentialValidationError extends Error {
-    constructor(message: string);
-}
-/**
- * Validate the untrusted host-port response before any secret is written to a
- * box. The host owns credential selection; OpenGeni owns scope checks, bounds,
- * path safety, and the transport lifecycle.
- */
-declare function normalizeRunCredentialsResolution(resolution: Extract<RunCredentialsResolution, {
-    status: "not_applicable";
-}>, expected: RunCredentialExpectedScope, now?: Date): null;
-declare function normalizeRunCredentialsResolution(resolution: Exclude<RunCredentialsResolution, {
-    status: "not_applicable";
-}>, expected: RunCredentialExpectedScope, now?: Date): NormalizedRunCredentialMaterial;
-declare function normalizeRunCredentialsResolution(resolution: RunCredentialsResolution, expected: RunCredentialExpectedScope, now?: Date): NormalizedRunCredentialMaterial | null;
-declare function runCredentialRoot(sessionId: string): string;
-declare function runCredentialPointerFile(sessionId: string): string;
-type MaterializeRunCredentialsOptions = {
-    sessionId: string;
-    attemptId: string;
-    executionGeneration: number;
-    /** Initial provision after recovery may prune generations from older attempts. */
-    pruneOtherAttempts?: boolean;
-    /** An all-auth-needed replacement removes every prior readable generation. */
-    prunePreviousGenerations?: boolean;
-    /** Renewal keeps the active and immediately prior same-attempt generations. */
-    pruneSupersededGenerations?: boolean;
-    commandRunner?: RunCredentialCommandRunner;
-};
-/** Materialize one complete immutable generation, then atomically flip current. */
-declare function materializeRunCredentials(session: RunCredentialCommandSession, material: NormalizedRunCredentialMaterial, options: MaterializeRunCredentialsOptions): Promise<void>;
-declare function clearRunCredentials(session: RunCredentialCommandSession, sessionId: string, commandRunner?: RunCredentialCommandRunner): Promise<void>;
-/**
- * Remove only generations owned by one attempt. A successor may already have
- * atomically activated its own pointer after queue admission; this cleanup must
- * never clear or overwrite that newer generation.
- */
-declare function clearRunCredentialsForAttempt(session: RunCredentialCommandSession, options: Pick<MaterializeRunCredentialsOptions, "sessionId" | "attemptId" | "executionGeneration">, commandRunner?: RunCredentialCommandRunner): Promise<void>;
-/** Prefix one sandbox command so every new process observes the active generation. */
-declare function withRunCredentialEnvironment(cmd: string, sessionId: string): string;
-/**
- * Preserve the provider session identity/capabilities while decorating only
- * command creation. Non-command methods stay bound to the original instance.
- */
-declare function withRunCredentialsSession<T extends object>(session: T, sessionId: string): T;
-/** Decorate every client-created/resumed session after the host seeds it. */
-declare function withRunCredentialsClient(client: SandboxClient, sessionId: string, onSessionReady?: RunCredentialSessionReady): SandboxClient;
-
-declare class ToolspaceTokenPathError extends Error {
-    constructor(message: string);
-}
-/**
- * Derive the per-session token file beside the legacy manifest pointer.
- *
- * The manifest pointer stays box-global so an already-warm shared sandbox does
- * not receive an illegal environment delta. Every OpenGeni command overrides
- * that pointer with this deterministic path. The hash is path hygiene and
- * avoids disclosing host/session ids in filenames; filesystem paths are not an
- * authorization boundary. The delegated bearer's session claim remains the
- * authority boundary for Toolspace calls.
- */
-declare function toolspaceTokenFileForSession(manifestTokenFile: string, sessionId: string): string;
-declare function toolspaceTokenFileFromEnvironment(environment: Readonly<Record<string, string>>, sessionId: string): string;
-/** Prefix one sandbox command with its session-specific Toolspace pointer. */
-declare function withToolspaceTokenEnvironment(cmd: string, tokenFile: string): string;
-/** Preserve provider identity/capabilities while decorating command creation. */
-declare function withToolspaceTokenSession<T extends object>(session: T, tokenFile: string): T;
-/** Decorate every client-created/resumed session with one session pointer. */
-declare function withToolspaceTokenClient(client: SandboxClient, tokenFile: string): SandboxClient;
-
-/** 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 artifact is over its size limit. */
-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 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.
- */
-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.
- */
-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.
- */
-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;
-
-declare function parseExecBannerSessionId(raw: string): number | null;
-declare function parseExecBannerExitCode(raw: string): number | null;
-declare function isExecSessionLostBanner(out: string, execSessionId: number): boolean;
-
-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>;
-    writeStdinForProcessMutation?(args: {
-        sessionId: number;
-        chars?: string;
-        yieldTimeMs?: number;
-        maxOutputTokens?: number;
-    }): Promise<string>;
-    writeStdinForProcessControl?(args: {
-        sessionId: number;
-        chars?: string;
-        yieldTimeMs?: number;
-        maxOutputTokens?: number;
-    }): Promise<string>;
-    cancelExecCommand?(opId: string): Promise<boolean>;
-    hasRetainedProcess?(providerSessionId: number): boolean;
-    execCommandForProcessControl?(providerSessionId: number, args: ChannelAExecArgs): Promise<string>;
-    createEditor?(runAs?: string): ChannelAEditor;
-    supportsPty?(): boolean;
-};
-declare class ChannelAValidationError extends Error {
-    constructor(message: string);
-}
-/** A structurally valid Channel-A request could not be completed because the
- * sandbox/provider control plane was temporarily unavailable. Callers may retry
- * this class; it must never be presented as a bad user path. */
-declare class ChannelAUnavailableError 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 const REPOSITORY_DISCOVERY_LIMIT = 256;
-type RepositoryDiscoveryDegradedReason = "command_failed" | "command_timed_out" | "result_limit_exceeded";
-type RepositoryDiscoveryResult = {
-    repos: string[];
-    complete: boolean;
-    degradedReason: RepositoryDiscoveryDegradedReason | null;
-};
-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>;
-    /**
-     * Worker-only fast path for a bounded whole-workspace index. Matching
-     * directory nodes are emitted but pruned by `find` before descent, so residue
-     * such as node_modules cannot consume the result budget. The public fs/list
-     * wire remains unchanged; interactive callers still expand every directory
-     * they explicitly request.
-     */
-    fsListPruned(req: FsListRequest, pruneDirectoryNames: readonly string[]): Promise<FsListResponse>;
-    private fsListInternal;
-    fsRead(req: FsReadRequest): Promise<FsReadResponse>;
-    private assertConfinedExistingDirectory;
-    private assertConfinedMutationParent;
-    private assertConfinementResult;
-    /** Binary-safe fallback for sessions without native reads. The file is opened
-     *  before checking `/proc/.../fd/3`, so a symlink swap cannot redirect the
-     *  subsequent read after confinement has been established. */
-    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>;
-    /** Measure one Git command without returning its potentially large or
-     * NUL-bearing output through the provider's text transport. */
-    private measureConfinedCommandBytes;
-    /** Read an exact prefix of a command's output in chunks that remain below
-     * every supported execCommand retained-output ceiling. The producer is
-     * intentionally rerun per chunk; turn-end capture calls this only after the
-     * durable mutation authority has quiesced the workspace. */
-    private readConfinedCommandPrefix;
-    private readConfinedCommandBytes;
-    /** Read a regular untracked file without routing its body through one large
-     * execCommand response. Native provider reads are binary-safe; providers
-     * without that surface use the same bounded chunk protocol as Git patches. */
-    private readUntrackedRegularFile;
-    gitStatus(req: GitStatusRequest): Promise<GitStatusResponse>;
-    gitDiff(req: GitDiffRequest): Promise<GitDiffResponse>;
-    gitLog(req: GitLogRequest): Promise<GitLogResponse>;
-    gitShow(req: GitShowRequest): Promise<GitShowResponse>;
-    /**
-     * Detect repo roots within every supported workspace layout.
-     *
-     * The platform normally seeds repositories at
-     * `repos/<encoded-host>/<owner>/<repo>`, while explicit mount paths and
-     * connected-machine layouts can be deeper. Do not reintroduce a fixed
-     * maxdepth here. Traversal is
-     * bounded instead by pruning known machine/build residue, a wall-clock
-     * timeout, and a result limit. `.git` may be either a directory (ordinary
-     * clone/submodule) or a file (linked worktree).
-     *
-     * Callers that persist an authoritative snapshot must use this detailed
-     * result and surface an incomplete discovery. The compact `detectRepos()`
-     * wrapper remains for capability negotiation, where the best available list
-     * is preferable to failing the whole capabilities document.
-     */
-    detectReposDetailed(): Promise<RepositoryDiscoveryResult>;
-    /** Detect repo roots within the workspace (for the Git.repos capability). */
-    detectRepos(): Promise<string[]>;
-    /** Run a bounded command to physical completion and return buffered output.
-     *  A deadline cancels the exact provider operation, proves its process group
-     *  absent, and settles any retained-process admission before returning 124. */
-    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>;
-    /** Ask an open PTY to exit and return the exact provider banner. The routing
-     * session settles durable process authority only when that banner proves this
-     * locator exited or was lost; callers must keep metadata open otherwise. */
-    ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<string>;
-    /** The current FS revision (for the caller to persist/seed). */
-    currentRevision(): number;
-    private joinRoot;
-    /** Validate and enter an FS/Git directory in the same remote command that
-     * performs the operation. This preserves confinement without adding a full
-     * provider round-trip to every tree expansion or Git query. */
-    private runInConfinedDirectory;
-    private repoWorkdir;
-    private terminalWorkdir;
-    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 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;
-    /** The reply exceeded the transport's max payload (a distinguishing flag so the
-     *  fault renderer can name the size wall + recovery instead of a generic OS error). */
-    readonly payloadTooLarge: boolean;
-    /** The transport synthesized this fault PRE-SEND — it KNOWS the request never
-     *  reached the machine (no connection, or no responder on the subject), so the op
-     *  provably did not execute. Only such a fault is safe to re-issue for ANY op kind
-     *  (a post-send timeout is ambiguous — at-least-once — and must not be re-sent
-     *  unless the op is read-only). Never set for an agent-returned error. */
-    readonly neverSent: 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;
-        payloadTooLarge?: boolean;
-        neverSent?: 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.)
- *   - PAYLOAD_TOO_LARGE     → the reply exceeded the transport's max payload;
- *                             non-retryable, with actionable copy (the sizes + a
- *                             redirect-to-file workaround).
- *   - OS / UNSUPPORTED / STREAM / PROTOCOL / UNSPECIFIED → op-level error, no
- *                             reason, non-retryable.
- */
-declare function agentErrorToControlError(err: AgentError): SelfhostedControlError;
-/**
- * PAYLOAD_TOO_LARGE copy: state the actual sizes (from the agent's `detail` map —
- * `encoded_bytes` / `max_payload`) and tell the caller how to get the data anyway:
- * redirect the output to a file and read it back in ranges/chunks.
- */
-declare function payloadTooLargeMessage(detail: Record<string, string>): string;
-/**
- * DRAINING copy: the machine is at its concurrent-work capacity. `retries` is the
- * number of times `SelfhostedSession.call` already re-tried before giving up (0 at
- * the mapping layer, the final count when it surfaces after exhausting retries).
- */
-declare function drainingMessage(retries: number): string;
-/** Rebuild a DRAINING error with the final retry count folded into its message —
- *  used by `SelfhostedSession.call` when the bounded DRAINING retries are exhausted. */
-declare function drainingExhaustedError(base: SelfhostedControlError, retries: number): SelfhostedControlError;
-/**
- * exec-deadline copy: the command was terminated at the exec time limit. Advise
- * running long jobs in the background and polling their output rather than blocking
- * the turn on one long command. Surfaced on a timed-out exec result's stderr.
- */
-declare function execDeadlineHint(seconds: number): string;
-/** The reserved `detail` key the transport sets to "1" when it KNOWS a synthesized
- *  AGENT_OFFLINE fault occurred pre-send (no connection / no responder) — so the op
- *  provably never reached the machine. `agentErrorToControlError` reads it into
- *  `SelfhostedControlError.neverSent`. Reserved (never sent by the agent). */
-declare const NEVER_SENT_DETAIL_KEY = "_never_sent";
-/** Build a synthesized AGENT_OFFLINE `AgentError` — the control plane uses this
- *  when no agent responds on the subject at all. `neverSent` marks that the request
- *  provably never reached the machine (no connection / no responder), which makes it
- *  safe to re-issue for ANY op kind; leave it false for an AMBIGUOUS transport error
- *  (a connection torn mid-request may have delivered the op). */
-declare function offlineAgentError(message?: string, neverSent?: boolean): 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;
-    private connecting;
-    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. `neverSent` marks
- *  a pre-send synthesis (no connection / no responder) — the op provably never
- *  reached the machine, so it is safe to re-issue for any op kind. */
-declare function offlineControlResponse(requestId: string, neverSent?: boolean): ControlResponse;
-/** A `ControlResponse` carrying a synthesized TIMEOUT error (→ reconnecting). */
-declare function timeoutControlResponse(requestId: string): ControlResponse;
-
-/**
- * One completed control-op observation. `outcome` is the terminal result AFTER any
- * in-call retries: `ok` (the op succeeded) or `failed` (a terminal fault surfaced).
- * `healed` marks a success that only landed after ≥1 retry — the doctrine's
- * "healed and invisible in-band, always out-of-band" breadcrumb (drives
- * `machine.op.recovered`). Every field is derivable at the `SelfhostedSession.call`
- * exit points with no extra round-trip.
- */
-interface SelfhostedOpObservation {
-    /** The control-op kind (`ControlRequest["op"].$case`): exec / fsRead / ping / … */
-    op: string;
-    outcome: "ok" | "failed";
-    /** True when `outcome==="ok"` only after ≥1 in-call retry (draining/timeout/never-sent). */
-    healed: boolean;
-    /** Total in-call retries before this outcome (summed across the retry classes). */
-    retries: number;
-    /** Wall time from the first attempt to the terminal outcome, in ms. */
-    durationMs: number;
-    /** The typed wire code — present on `failed`. */
-    code?: ErrorCode;
-    /** The negotiated capability reason (agent_offline / agent_reconnecting / …), if any. */
-    reason?: SelfhostedUnavailableReason | null;
-    /** Whether a failed fault provably never reached the machine (a pre-send synthesis). */
-    neverSent?: boolean;
-    /** The enrolled machine (agent) id the op addressed — for machine-scoped fan-out. */
-    machineId?: string;
-    /** A stable fault-class string (`selfhostedFaultClass`): the fault class on a
-     *  `failed` op, or the class of retries that a `healed` op recovered from. Absent
-     *  on a clean success. Drives the `machine.op.*` event mapping + its infra filter. */
-    faultClass?: string;
-    /** The reply size in bytes when known — set on a PAYLOAD_TOO_LARGE fault (from the
-     *  agent's `encoded_bytes` detail). The op-stream client fills the success-reply
-     *  size once it owns the framed transport; today's request/reply does not surface it. */
-    replyBytes?: number;
-}
-/** A fire-and-forget observer of completed control ops. It MUST NOT throw (the
- *  session guards the call) and MUST NOT block the op — it is a telemetry tap. */
-type SelfhostedOpObserver = (observation: SelfhostedOpObservation) => void;
-
-/**
- * A stable, low-cardinality fault-class string for a `SelfhostedControlError` — the
- * out-of-band twin of the in-band renderer's class taxonomy (single-sourced here).
- * Used for the `machine.op.*` event class + the metrics label + the infra filter.
- */
-declare function selfhostedFaultClass(error: SelfhostedControlError): string;
-/**
- * The fault classes that count as an INFRASTRUCTURE fault (a `machine.op.failed`
- * event). A semantic miss the model asked about — a missing path (`not_found`), a
- * consent gate (`consent`), a nonzero exit (never a fault at all) — is an OUTCOME,
- * not an infra fault, and is DELIBERATELY excluded; `fenced` is a routing/session
- * condition, not a machine fault. (Doctrine two-planes / the team ruling.)
- */
-declare const SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES: ReadonlySet<string>;
-/** The four mandatory field labels (exported so tests can assert their presence). */
-declare const FAULT_FIELD_WHAT_HAPPENED = "What happened:";
-declare const FAULT_FIELD_WHICH_LAYER = "Which layer:";
-declare const FAULT_FIELD_WHAT_PRESERVED = "What was preserved:";
-declare const FAULT_FIELD_WHAT_TO_TRY = "What to try:";
-/**
- * Render a `SelfhostedControlError` into the doctrine's four in-band fields with a
- * correct retry verdict. The fault CLASS is read from the typed flags (never the
- * message prose), so each class gets the right "which layer" and "what to try":
- *
- *  - PAYLOAD_TOO_LARGE → the command ran but its reply was too big to return; the
- *    fix is to bound the output, not to retry.
- *  - DRAINING → pre-admission backpressure; nothing ran; safe to retry shortly.
- *  - CONSENT_REQUIRED → a machine-side consent gate; retrying cannot help.
- *  - AGENT_OFFLINE → the machine link is down. If the transport KNOWS the request
- *    never left (`neverSent`), nothing ran; otherwise the effect is ambiguous and
- *    the model must check before re-running. Either way "try again" is wrong until
- *    the machine reconnects.
- *  - agent_reconnecting (TIMEOUT) → a transient link blip AFTER send: ambiguous, so
- *    a state-changing command must be checked before re-running (at-least-once).
- *  - NOT_FOUND → a command/filesystem miss, not a link fault.
- *  - FENCED → the active machine session changed (a swap); re-run.
- *  - default (OS/UNSUPPORTED/STREAM/PROTOCOL) → the command/op failed on the machine.
- */
-declare function renderSelfhostedFault(error: SelfhostedControlError): string;
-
-/**
- * The read-only, idempotent-safe control ops that MAY be retried after a TIMEOUT
- * / `agent_reconnecting` blip.
- *
- * A timed-out request is AT-LEAST-ONCE on the wire: the agent may have RECEIVED
- * and fully EXECUTED the op before its reply was lost, so re-issuing it is only
- * safe when a second execution is observably identical to one — i.e. a pure read.
- * Every MUTATING op (`exec`, `git`, `fsWrite`/`fsMove`/`fsMkdir`/`fsRemove`, and
- * the pty/desktop input ops) is DELIBERATELY EXCLUDED: re-running a mutation that
- * already ran on the machine is a real correctness hazard (a duplicated write, a
- * second `git push`, a re-applied command). Only DRAINING (a pre-admission
- * rejection — see `decideSelfhostedRetry`) is safe to retry for those.
- */
-declare const SELFHOSTED_IDEMPOTENT_READONLY_OPS: ReadonlySet<string>;
-/**
- * DRAINING is a pre-admission backpressure rejection (the op never started), so it
- * is safe to retry for ANY op kind. The budget is split by op class:
- *
- *  - NON-EXEC control ops (fs/git/desktop/pty) keep a SHORT budget — 3 retries,
- *    worst-case backoff 500+1000+2000 = 3.5s (≤5s). Their start latency matters
- *    (fs/git ops gate the model's next step), so a saturated machine should surface
- *    quickly rather than stall.
- *  - EXEC gets a LONG, patient budget — 10 retries, worst-case ≈55.5s (<60s). exec
- *    start is not latency-critical, and the agent-side admission pool is (until a
- *    later agent release) a FLAT 8 permits with no per-class split: a burst of slow
- *    execs can hold every permit and blanket-DRAIN all fs/git ops. A patient exec
- *    retry converts those DRAINING storms into mild queueing instead of a wall of
- *    failed tool calls, and pairs with the deliberately modest exec deadline (which,
- *    for the same 8-permit reason, defaults to 2min, not 5).
- */
-declare const SELFHOSTED_DRAINING_MAX_RETRIES = 3;
-declare const SELFHOSTED_EXEC_DRAINING_MAX_RETRIES = 10;
-/** A read-only op that timed out is retried at most once (see the at-least-once
- *  note above — even a read gets a single re-issue, not an unbounded loop). */
-declare const SELFHOSTED_TIMEOUT_MAX_RETRIES = 1;
-/** A fault the transport synthesized PRE-SEND (no connection / no responder) — the
- *  op provably never reached the machine, so it is safe to re-issue for ANY op kind.
- *  Short bounded budget (≈3.5s summed): enough to ride out a NATS reconnect blip
- *  quietly, not so long it stalls the model on a machine that is genuinely down. */
-declare const SELFHOSTED_NEVER_SENT_MAX_RETRIES = 3;
-/** Full-jitter backoff base (ms). Delay N is sampled in `[0, base * factor^N)`. */
-declare const SELFHOSTED_RETRY_BACKOFF_BASE_MS = 500;
-declare const SELFHOSTED_RETRY_BACKOFF_FACTOR = 2;
-/** Per-delay ceiling: 500 → 1s → 2s → 4s → 8s, then flat at 8s. Bounds the summed
- *  backoff — non-exec (3 retries) ≈3.5s ≤5s; exec (10 retries) ≈55.5s <60s. */
-declare const SELFHOSTED_RETRY_BACKOFF_CAP_MS = 8000;
-type SelfhostedRetryDecision = {
-    readonly action: "fail";
-} | {
-    readonly action: "retry";
-    readonly delayMs: number;
-};
-/**
- * Full-jitter exponential backoff. Returns a delay in
- * `[0, min(cap, base * factor^attempt))`. `jitter` is an injected sample in
- * `[0, 1)` so the delay is fully deterministic under test.
- */
-declare function selfhostedRetryBackoffMs(attempt: number, jitter: number): number;
-/**
- * PURE retry policy for one selfhosted control-op reply.
- *
- *  - `error.draining` (DRAINING — pre-admission host-work backpressure; the op was
- *    rejected at the pool gate and NEVER started) → retry for ANY op kind, since
- *    nothing executed. exec gets the long `SELFHOSTED_EXEC_DRAINING_MAX_RETRIES`
- *    budget (≈60s of patient queueing under the flat 8-permit pool); every other op
- *    keeps the short `SELFHOSTED_DRAINING_MAX_RETRIES` budget (≤5s).
- *  - `error.neverSent` (a pre-send AGENT_OFFLINE synthesis — no connection / no
- *    responder; the op provably never reached the machine) → retry for ANY op kind
- *    up to `SELFHOSTED_NEVER_SENT_MAX_RETRIES`. At-least-once does NOT apply (nothing
- *    executed), so even a mutation is safe to re-issue; this heals a NATS reconnect
- *    blip quietly. A truly-offline machine surfaces honestly after the short budget.
- *  - `error.reason === "agent_reconnecting"` (a TIMEOUT / transient blip AFTER send)
- *    → retry at most `SELFHOSTED_TIMEOUT_MAX_RETRIES`, and ONLY for a read-only
- *    idempotent-safe op (`SELFHOSTED_IDEMPOTENT_READONLY_OPS`). A timed-out
- *    MUTATION is never retried here — it may already have run (at-least-once).
- *  - Everything else → no retry at this layer:
- *      · FENCED is retried by the routing proxy against a RE-RESOLVED backend
- *        (retrying here under the same stale epoch would just re-fence);
- *      · AGENT_OFFLINE / OS / PROTOCOL / PAYLOAD_TOO_LARGE / CONSENT_REQUIRED are
- *        not transient and must surface to the caller.
- *
- * The draining and timeout budgets are SEPARATE counters so a read that first hit
- * backpressure still keeps its single timeout re-issue (and vice versa); both are
- * bounded, so the total number of attempts — and the summed backoff — is bounded.
- */
-declare function decideSelfhostedRetry(input: {
-    opKind: string;
-    error: SelfhostedControlError;
-    drainingRetries: number;
-    timeoutRetries: number;
-    /** Prior never-sent retries. Optional (default 0) — only the pre-send AGENT_OFFLINE
-     *  branch reads it, so callers that cannot hit that class may omit it. */
-    neverSentRetries?: number;
-    jitter: number;
-}): SelfhostedRetryDecision;
-/**
- * The injected clock the retry loop drives — real in production, a deterministic
- * fake in tests. `jitter()` returns a full-jitter sample in `[0, 1)`.
- */
-interface SelfhostedRetryClock {
-    sleep(ms: number): Promise<void>;
-    jitter(): number;
-}
-/** The production clock: a real timer + `Math.random()` jitter. */
-declare const defaultSelfhostedRetryClock: SelfhostedRetryClock;
-
-/** The per-op frame subject (runner→server, fire-and-forget). Mirrors the
- *  runner's wire constant: `agent.<ws>.<id>.op.<op_id>`. */
-declare function opFrameSubject(workspaceId: string, agentId: string, opId: string): string;
-/** The per-agent ack subject (server→runner, fire-and-forget). Mirrors the
- *  runner's wire constant: `agent.<ws>.<id>.ack`. */
-declare function opAckSubject(workspaceId: string, agentId: string): string;
-/** A live subscription handle. `unsubscribe` is idempotent and never throws. */
-interface OpStreamSubscription {
-    unsubscribe(): void;
-}
-/**
- * The op-stream transport seam. `subscribe` MUST be established before the
- * OpStart that makes frames flow (subscription-before-start is a protocol
- * invariant: no frame is published before the consumer exists on a healthy
- * path; a missed frame is healed via OpAttach replay regardless). `onMessage`
- * is invoked in arrival order; a decode failure inside the handler must be
- * contained by the caller (a torn frame must never kill the subscription).
- */
-interface OpStreamTransport {
-    subscribe(subject: string, onMessage: (payload: Uint8Array) => void): Promise<OpStreamSubscription>;
-    publish(subject: string, payload: Uint8Array): Promise<void>;
-}
-/** Thrown when the transport has no live connection: the op-stream path is
- *  UNAVAILABLE (never silently degraded). The session catches this pre-start
- *  and falls back to the legacy exec — the op provably never started. */
-declare class OpStreamUnavailableError extends Error {
-    readonly name = "OpStreamUnavailableError";
-}
-/**
- * The minimal NATS surface the transport needs — mirrors the `nats`
- * `NatsConnection` subscribe/publish WITHOUT importing `nats` into the
- * agent-loop-free runtime leaf (the worker injects the live `@opengeni/events`
- * bus connection, exactly like `NatsRequestConnection` in control-rpc.ts).
- * `subscribe` returns the nats.js Subscription shape: an async iterable of
- * messages plus `unsubscribe()`.
- */
-interface NatsOpStreamConnection {
-    subscribe(subject: string): AsyncIterable<{
-        data: Uint8Array;
-    }> & {
-        unsubscribe(): void;
-    };
-    publish(subject: string, payload: Uint8Array): void;
-}
-/**
- * The NATS-backed transport. Lazy memoized factory (identical discipline to
- * `NatsControlRpc`): the connection resolves on first use; a null factory
- * result or a dial failure surfaces `OpStreamUnavailableError` — the caller
- * (the session) falls back to the LEGACY exec path rather than failing the op,
- * so a NATS-less boot or a torn bus never strands a turn on a dead transport.
- */
-declare class NatsOpStreamTransport implements OpStreamTransport {
-    private readonly connect;
-    private connection;
-    private connecting;
-    constructor(connect: () => Promise<NatsOpStreamConnection | null>);
-    private resolveConnection;
-    subscribe(subject: string, onMessage: (payload: Uint8Array) => void): Promise<OpStreamSubscription>;
-    publish(subject: string, payload: Uint8Array): Promise<void>;
-}
-
-/** Initial send-credit window (bytes) when the caller does not size it. Matches
- *  the wire default OpStart advertises (~4 MiB). */
-declare const OP_STREAM_DEFAULT_WINDOW_BYTES: number;
-/** Cumulative-ack repetition cadence while an op is live (ruling M1: acks are
- *  best-effort and healed by repetition). */
-declare const OP_STREAM_ACK_INTERVAL_MS = 5000;
-/** Frame-silence threshold before the client starts probing with OpQuery. The
- *  runner emits Progress every 5s while an op is alive and quiet, so 30s of
- *  TOTAL silence means frames are not reaching us (or the op is gone). */
-declare const OP_STREAM_SILENCE_TIMEOUT_MS = 30000;
-/** How long a silent op is held open across a machine reconnect window before
- *  the client fails it typed (PROTOCOL liveness rule: hold ≤120s, then only a
- *  definitive answer fails the op). */
-declare const OP_STREAM_RECONNECT_HOLD_MS = 120000;
-/**
- * The durable-resume journal the worker adapts onto Temporal (design delta Δ1:
- * the attach generation is `Info.currentAttemptScheduledTimestampMs` — strictly
- * monotonic across worker-death redispatches, which `Info.attempt` is NOT under
- * `maximumAttempts: 1`). `persistSettled` folds the op's settled frontier into
- * the activity heartbeat details and MUST complete before the wire final ack
- * (the durable-before-wire-ack gate); the default no-journal client (tests,
- * non-activity callers) uses generation "1" and skips persistence.
- */
-interface OpStreamJournal {
-    /** The consumer's attach generation (u64 decimal string). */
-    attachGeneration(): string;
-    /** Durably record `opId` as settled at `exitSeq` BEFORE its final ack. */
-    persistSettled(opId: string, exitSeq: string): void | Promise<void>;
-}
-/** A completed op-stream exec: the legacy-shaped response plus the healing
- *  telemetry the session folds into its op observation. */
-interface OpStreamExecOutcome {
-    response: ExecResponse;
-    /** Attach/query heals that occurred after streaming began (gap replays,
-     *  silence probes that re-attached). >0 marks the op `healed`. */
-    heals: number;
-    /** OpStart-level retries (draining/blip) before the op was accepted. */
-    startRetries: number;
-    /** Total reassembled Data payload bytes (the observer's replyBytes). */
-    replyBytes: number;
-}
-
-/** 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";
-/**
- * The op-stream injection (op-stream protocol v1.1 — see op-stream.ts). PRESENT
- * = the streaming exec transport is enabled for this session (the worker
- * injects it only when the runner advertised `Capabilities.op_stream` AND the
- * server flag is on — the leaf carries no flag logic). ABSENT = the legacy
- * monolithic exec, byte-identical to before. The timing knobs exist for tests.
- */
-interface SelfhostedOpStreamDeps {
-    transport: OpStreamTransport;
-    /** The durable-resume journal (attach generation + settled-frontier persist).
-     *  Absent (tests, non-activity callers) ⇒ generation "1", no persistence. */
-    journal?: OpStreamJournal;
-    windowBytes?: number;
-    ackIntervalMs?: number;
-    silenceTimeoutMs?: number;
-    reconnectHoldMs?: number;
-}
-interface SelfhostedSessionDeps {
-    workspaceId: string;
-    agentId: string;
-    controlRpc: ControlRpc;
-    relay: SelfhostedRelayConfig;
-    /** Op-stream exec transport (present = enabled; see SelfhostedOpStreamDeps). */
-    opStream?: SelfhostedOpStreamDeps;
-    /** 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;
-    /** The CONTROL-op timeout (ping/fs/desktop/pty and the exec wire fallback). The
-     *  agent's own control liveness must stay responsive, so this is short (the 30s
-     *  default). Override for tests or per-deployment tuning. */
-    timeoutMs?: number;
-    /**
-     * The EXEC process deadline — distinct from `timeoutMs`. A real command
-     * (compile, test run, install) routinely outlives the short control timeout, so
-     * exec gets its own, much larger budget: the agent kills the child at this wall,
-     * and the wire waits `execTimeoutMs + SELFHOSTED_EXEC_REPLY_GRACE_MS`. Omitted ⇒
-     * falls back to `timeoutMs` (byte-identical to before this split), so any caller
-     * that does not opt in keeps today's behavior.
-     */
-    execTimeoutMs?: number;
-    /** The clock the bounded control-op retry loop drives (sleep + jitter). Injected
-     *  so tests are deterministic; defaults to a real timer + `Math.random()`. */
-    retryClock?: SelfhostedRetryClock;
-    /** A fire-and-forget observer invoked once per completed control op (out-of-band
-     *  telemetry — metrics + `machine.*` events). The worker/api wire it to the sinks;
-     *  the leaf only invokes it (guarded so it can never break an op). Omitted ⇒ no-op. */
-    onOp?: SelfhostedOpObserver;
-    /**
-     * 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 this env wholesale (the
-     * machine owns its own shell), EXCEPT the allowlisted toolspace pointers it
-     * exports per exec so `ogtool` works — see SELFHOSTED_EXEC_ENV_ALLOWLIST. The
-     * manifest carries the full env for parity. Omitted → `{}` (the negotiation-only
-     * / test path, which never applies a turn manifest, so there is no delta).
-     */
-    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;
-    /** True when the agent killed the child at the exec deadline. Additive to the
-     *  Channel-A superset (consumers that don't read it are unaffected); `execCommand`
-     *  reads it to surface the deadline hint on the stdout-only SDK path. */
-    timedOut?: boolean;
-}
-/** 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;
-    /** The exec process deadline (falls back to `timeoutMs` when unset). */
-    private readonly execTimeoutMs;
-    private readonly retryClock;
-    private readonly onOp;
-    private readonly subject;
-    /** The op-stream exec client — constructed iff `deps.opStream` was injected
-     *  (= the streaming transport is enabled for this session). */
-    private readonly opStreamClient;
-    /** 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);
-    /** Invoke the injected per-op observer, guarded: a telemetry tap must NEVER break
-     *  an op (a throwing sink is swallowed). No-op when no observer is wired. */
-    private emitOp;
-    /**
-     * 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).
-     *
-     * Two failure modes are retried in-place (the decision is the pure
-     * `decideSelfhostedRetry` policy):
-     *   - DRAINING — a pre-admission host-work backpressure rejection; the op never
-     *     started, so it is safe to re-issue for ANY op kind (bounded).
-     *   - a TIMEOUT / `agent_reconnecting` blip — re-issued ONCE, and ONLY for a
-     *     read-only idempotent-safe op. A timed-out MUTATION is NEVER re-issued: it
-     *     may already have executed on the machine (at-least-once), which would
-     *     duplicate the write/command. FENCED is intentionally NOT retried here — the
-     *     routing proxy retries it against a re-resolved backend under a fresh epoch.
-     * Each attempt carries a FRESH `requestId` (a retry is a distinct request).
-     */
-    private call;
-    /** The clamped exec process deadline (ms): the exec-specific budget when threaded,
-     *  else the control timeout. Shared by `exec()` (the wire deadline) and
-     *  `execCommand()` (the timed-out hint's "N-second limit"), so the two never drift. */
-    private execDeadlineMs;
-    /** Channel-A `exec`: run a command on the machine and return its output. */
-    exec(args: SelfhostedExecArgs): Promise<SelfhostedExecResult>;
-    /** The legacy monolithic exec request/reply — the permanent fallback wire
-     *  form (and the only form for runners without `op_stream`). */
-    private execLegacy;
-    /**
-     * The op-stream exec path: the SAME `ExecRequest`, streamed (see
-     * op-stream.ts). The durable op id comes from the tool-call correlation
-     * context (`{callId}:{ordinal}` — B1) when this exec runs inside an SDK tool
-     * invocation; a non-tool caller falls back to a random unique id (never
-     * collides, merely not stable across a turn re-dispatch). Emits the SAME
-     * per-op observation the legacy path does, with `replyBytes` filled from the
-     * reassembled stream (the field the framed transport was designed to own).
-     */
-    private execViaOpStream;
-    /**
-     * The turn-end op-stream durability hook: persists each settled op's frontier
-     * to the journal, then final-acks it on the wire (licensing the runner to GC
-     * its retained frames). The WORKER calls this after the turn's results are
-     * durably recorded — never mid-turn (the durable-before-wire-ack ordering).
-     * A no-op for sessions without the op-stream transport.
-     */
-    finalizeOpStreamOps(): Promise<void>;
-    /** 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.
-     *
-     *  On a DEADLINE timeout the SDK path is stdout-only (the model sees `result.output`
-     *  and nothing else), so the deadline hint that `exec()` puts on stderr would be
-     *  invisible — a >deadline command would return `{"output":""}` and the model would
-     *  conclude "no output" with no idea it was killed. So when the result timed out we
-     *  surface the hint HERE, on stdout: the hint alone when stdout is empty, or appended
-     *  after a newline when there is partial output (a timed-out result is already not
-     *  cleanly parseable — silence is worse than an explanatory suffix). The structured
-     *  `exec()` result is left untouched for the Channel-A parsers. */
-    execCommand(args: {
-        cmd: string;
-        workdir?: string;
-        runAs?: string;
-    }): Promise<string>;
-    /**
-     * Physical turn-cancellation seam used by the runtime tool fence. Only the
-     * op-stream transport has a process-tree cancellation protocol; a legacy
-     * runner returns false and the caller remains fail-closed until its exec
-     * deadline rather than claiming the machine is quiescent.
-     */
-    cancelExecCommand(opId: string): Promise<boolean>;
-    /** 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 + the ENCODED width/height, plus the
-     *  NATIVE (pre-downscale) geometry: when the agent had to downscale the PNG to fit
-     *  the transport's max payload, `nativeWidth`/`nativeHeight` carry the original
-     *  capture size so the computer-use layer can scale model clicks (in encoded-pixel
-     *  space) back to native pixels. An older agent leaves them 0 → read as "same as
-     *  width/height" (no downscale). */
-    screenshot(): Promise<{
-        png: Uint8Array;
-        width: number;
-        height: number;
-        nativeWidth: number;
-        nativeHeight: 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): 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 execTimeoutMs;
-    private readonly environment;
-    private readonly workingDir;
-    private readonly onOp;
-    private readonly opStream;
-    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;
-        /** The control-op timeout threaded into every bound session. */
-        timeoutMs?: number;
-        /** The exec process deadline threaded into every bound session (distinct from
-         *  `timeoutMs`; falls back to it when unset). See SelfhostedSessionDeps.execTimeoutMs. */
-        execTimeoutMs?: 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;
-        /** The per-op observer threaded into every bound session (out-of-band telemetry). */
-        onOp?: SelfhostedOpObserver;
-        /** The op-stream exec transport threaded into every bound session (present
-         *  = enabled; see SelfhostedOpStreamDeps). */
-        opStream?: SelfhostedOpStreamDeps;
-    });
-    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;
-    /** The control-op timeout (ping/fs/desktop/pty). Absent ⇒ the 30s default. */
-    timeoutMs?: number;
-    /** The exec process deadline, distinct from `timeoutMs`. Absent ⇒ falls back to
-     *  `timeoutMs` (a real turn threads the long exec budget here). */
-    execTimeoutMs?: number;
-    /** The per-op observer (out-of-band telemetry). Absent ⇒ no-op. */
-    onOp?: SelfhostedOpObserver;
-    /** The op-stream exec transport (present = enabled for the session; the
-     *  worker injects it only when the runner advertised the capability AND the
-     *  server flag is on). Absent ⇒ the legacy exec, byte-identical to before. */
-    opStream?: SelfhostedOpStreamDeps;
-}
-/**
- * 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
- *: 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;
-
-/**
- * Sanitize a tool call id into a legal NATS subject TOKEN fragment. The op id
- * is interpolated into the per-op frame subject, whose tokens must not contain
- * whitespace/control characters or the subject-structure characters (`.`,
- * `*`, `>`); the runner refuses illegal ids loudly. The mapping is INJECTIVE
- * (each disallowed char becomes `_<hex>_`), so two distinct call ids can never
- * collide into one op id — a collision would merge two different execs through
- * the idempotent-OpStart dedup and return the wrong result.
- */
-declare function sanitizeOpIdToken(raw: string): string;
-/**
- * Bind a tool-call correlation context around `fn` (the tool's execute). Every
- * durable op id minted inside — however deep in the transport — is
- * `{callId}:{ordinal}` with ordinals starting at 0 per invocation.
- */
-declare function runWithToolCallCorrelation<T>(callId: string, fn: () => T): T;
-/**
- * Mint the next durable op id for the current tool invocation, or null when no
- * correlation context is bound (a non-tool caller, e.g. Channel-A structural
- * exec). Callers fall back to a random unique id — safe (never collides, never
- * wrongly dedups), merely not stable across a turn re-dispatch, which degrades
- * that one op to today's at-least-once semantics.
- */
-declare function nextDurableOpId(): string | null;
-
-/**
- * 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;
-    /** An un-cleared clean going-offline marker (the machine announced a typed
-     *  GoingOffline). When set, the derivation reads the machine OFFLINE immediately,
-     *  regardless of a still-fresh `lastSeenAt`. NULL ⇒ no pending goodbye. */
-    wentOfflineAt: string | null;
-    /** The typed reason string of the pending goodbye (rides alongside
-     *  `wentOfflineAt`; NULL when there is no un-cleared marker). */
-    wentOfflineReason: 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).
- *   - un-cleared clean goodbye        → offline (an announced GoingOffline beats
- *                                       last_seen aging AND a lingering probe).
- *   - 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>;
-    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. */
-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. */
-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. */
-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. */
-type RoutingRetainedProcessAdoption = {
-    process: RoutingRetainedProcess;
-    backend: {
-        sandboxId: string | null;
-        leaseEpoch?: number;
-        providerInstanceId?: string;
-        activeEpoch: number;
-    };
-};
-type RoutingRetainedProcessTerminalProof = {
-    outcome: "exited";
-    exitCode: number;
-    reason: "provider_exit_banner";
-} | {
-    outcome: "lost";
-    exitCode: null;
-    reason: "provider_session_lost_banner";
-};
-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>;
-}
-type DefaultBackendLossResult = {
-    leaseEpoch: number;
-    recovery: "pending" | "degraded" | "unrecoverable" | "superseded";
-};
-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);
-}
-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. */
-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. */
-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.
- */
-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>;
-}
-
-/** 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;
-    /**
-     * 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). */
-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. */
-declare class ActiveBackendUnresolvableError extends Error {
-    readonly name = "ActiveBackendUnresolvableError";
-    readonly code: BackendUnresolvableCode;
-    constructor(code: BackendUnresolvableCode, message: string);
-}
-/** The outcome of {@link swapTargetEstablishability}. */
-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.
- */
-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.
- */
-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;
-    /** How this establish reached a live box: warm reattach by id ("resumed"),
-     *  fresh create ("created"), or fresh create + archive hydration
-     *  ("restored"). Callers use it to emit the durable sandbox.box.* lifecycle
-     *  events — box transitions were previously unrecorded, which made both
-     *  2026-07-06 incidents near-unattributable. Optional so external/legacy
-     *  constructors of this shape stay valid. */
-    origin?: "resumed" | "created" | "restored";
-    /** Set when a create-authorized reattach found the envelope's box GONE
-     *  (provider NotFound) and fell through to cold-restore. */
-    lostInstanceId?: string;
-    /** Exact durable archive revision verified byte-for-byte after hydration. */
-    restoredArchive?: WorkspaceArchiveDescriptor;
-};
-declare class SandboxExecReadinessError extends Error {
-    readonly backend: string;
-    readonly code: "exec_probe_unavailable" | "exec_probe_timeout" | "exec_probe_failed";
-    readonly timeoutMs: number;
-    readonly exitCode: number | null;
-    readonly name = "SandboxExecReadinessError";
-    constructor(backend: string, code: "exec_probe_unavailable" | "exec_probe_timeout" | "exec_probe_failed", timeoutMs: number, exitCode?: number | null);
-}
-/** A provider handle is not workspace readiness. Modal can return a handle
- * before its command router accepts exec, so every create path must pass this
- * bounded probe before atomically publishing the lease warm/ready. */
-declare function verifySandboxExecReadiness(established: EstablishedSandboxSession, timeoutMs?: number): Promise<void>;
-type SandboxCreatedCallback = (established: EstablishedSandboxSession) => Promise<void>;
-/**
- * Establish from one recovery envelope under an explicit creation policy. The
- * envelope is the lease's box-identity descriptor (the same per-turn `_sandbox`
- * envelope upserted by the turn activity).
- *
- *  - `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). `resume-only` propagates provider NotFound.
- *  - `create-or-restore`: the elected owner may replace a missing warm instance,
- *    or create directly from a cold/null envelope.
- */
-declare function establishSandboxSessionFromEnvelope(settings: Settings, envelope: Record<string, unknown> | null, opts: {
-    sessionId: string;
-    recovery: "create-or-restore" | "resume-only";
-    backendOverride?: SandboxBackend;
-    environment?: Record<string, string>;
-    onSandboxCreated?: SandboxCreatedCallback;
-    /** Called after archive hydration but immediately before the exact workspace
-     * fingerprint probe. Lease-aware callers persist `verifying` here so a box
-     * is never observable as ready while verification is in flight. */
-    onWorkspaceRestoreVerifying?: (descriptor: WorkspaceArchiveDescriptor) => Promise<void>;
-    metrics?: RuntimeMetricsHooks;
-}): 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>;
-/**
- * Whether a replacement envelope contains a provider-resumable identity. An
- * archive-only envelope is intentionally valid recovery metadata, but it is
- * never proof that the newly-created provider box can be resumed or attached.
- */
-declare function hasPersistableSandboxProviderIdentity(envelope: Record<string, unknown> | null | undefined): envelope is Record<string, unknown>;
-/** A replacement provider may not be published warm without a resumable
- * identity. Archive-only state is retained only when the caller rolls back to
- * cold and needs the verified workspace bytes for the next attempt. */
-declare class SandboxReplacementProviderStateError extends Error {
-    readonly backend: string;
-    readonly code: "replacement_provider_state_unpersistable";
-    constructor(backend: string);
-}
-declare function requirePersistableReplacementSandboxEnvelope(envelope: Record<string, unknown> | null, backend: string): Record<string, unknown>;
-/**
- * Build the only resume envelope that may be published for a newly-created
- * replacement sandbox. Historical state contributes durable archive pointers
- * only; it can never substitute for serialization of the replacement's provider
- * identity. If replacement serialization is unavailable or fails, publication
- * keeps an archive-only envelope (when one exists) or null. The new instance id
- * remains separately fenced on the lease, while later attach/resume fails closed
- * rather than targeting the dead provider that initiated rematerialization.
- */
-declare function serializeReplacementSandboxEnvelope(established: EstablishedSandboxSession, archiveSource: Record<string, unknown> | null): Promise<Record<string, unknown> | null>;
-
-export { type NatsRequestConnection as $, type ActiveBackendResolverDeps as A, type BackendUnresolvableCode as B, ChannelAConflictError as C, DEFAULT_DESKTOP_GEOMETRY as D, type EnsureDisplayStackOptions as E, type ExposeStreamPortInput as F, type ExposeStreamPortResult as G, type ExposedPortEndpoint as H, FAULT_FIELD_WHAT_HAPPENED as I, FAULT_FIELD_WHAT_PRESERVED as J, FAULT_FIELD_WHAT_TO_TRY as K, FAULT_FIELD_WHICH_LAYER as L, type LiveModalSandboxLeaseAttribution as M, type MaterializeRunCredentialsOptions as N, type MintStreamTokenInput as O, MockAgentResponder as P, type MockAgentResponderOptions as Q, type RunCredentialSessionReady as R, type MockExecHandler as S, type ModalModuleLoader as T, type ModalOrphanSweepResult as U, type ModalOrphanSweepTermination as V, type ModalSandboxAttribution as W, NEVER_SENT_DETAIL_KEY as X, NatsControlRpc as Y, type NatsOpStreamConnection as Z, NatsOpStreamTransport as _, type RuntimeMetricsHooks as a, SandboxExecReadinessError as a$, type NegotiationContext as a0, type NormalizedRunCredentialMaterial as a1, type NumstatEntry as a2, OP_STREAM_ACK_INTERVAL_MS as a3, OP_STREAM_DEFAULT_WINDOW_BYTES as a4, OP_STREAM_RECONNECT_HOLD_MS as a5, OP_STREAM_SILENCE_TIMEOUT_MS as a6, type OpStreamExecOutcome as a7, type OpStreamJournal as a8, type OpStreamSubscription as a9, type RoutingRetainedProcessTerminalProof as aA, RoutingSandboxSession as aB, type RoutingSandboxSessionDeps as aC, type RoutingTransitionEvent as aD, RoutingUnsupportedError as aE, type RunCredentialCommandRunner as aF, type RunCredentialCommandSession as aG, type RunCredentialExpectedScope as aH, RunCredentialValidationError as aI, SELFHOSTED_DEFAULT_TIMEOUT_MS as aJ, SELFHOSTED_DRAINING_MAX_RETRIES as aK, SELFHOSTED_EXEC_DRAINING_MAX_RETRIES as aL, SELFHOSTED_IDEMPOTENT_READONLY_OPS as aM, SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES as aN, SELFHOSTED_NEVER_SENT_MAX_RETRIES as aO, SELFHOSTED_RECONNECT_WINDOW_MS as aP, SELFHOSTED_RELAY_STREAM_PATH as aQ, SELFHOSTED_RETRY_BACKOFF_BASE_MS as aR, SELFHOSTED_RETRY_BACKOFF_CAP_MS as aS, SELFHOSTED_RETRY_BACKOFF_FACTOR as aT, SELFHOSTED_TIMEOUT_MAX_RETRIES as aU, STREAM_PORT as aV, STREAM_TOKEN_DEFAULT_TTL_SECONDS as aW, SandboxChannelAService as aX, type SandboxChannelAServiceOptions as aY, SandboxConfigError as aZ, type SandboxCreatedCallback as a_, type OpStreamTransport as aa, OpStreamUnavailableError as ab, PROVIDER_REGISTRY as ac, type ProviderConstructionContext as ad, type ProviderRegistration as ae, type ProviderSandboxFailure as af, type ProviderSandboxFailureKind as ag, REPOSITORY_DISCOVERY_LIMIT as ah, type RecordingArtifactMetadata as ai, type RecordingCodec as aj, type RecordingContentType as ak, RecordingError as al, type RecordingProcess as am, RecordingUnavailableError as an, type RepositoryDiscoveryDegradedReason as ao, type RepositoryDiscoveryResult as ap, type ResolvedActiveBackend as aq, type RevalidateModalOrphanTermination as ar, type RoutableBackendSession as as, type RoutableSandbox as at, RoutingBackendRecoveryRequiredError as au, RoutingMutationOutcomeUnknownError as av, type RoutingMutationSettlementResult as aw, type RoutingRetainedProcess as ax, type RoutingRetainedProcessAdoption as ay, RoutingRetainedProcessNotFoundError as az, ActiveBackendUnresolvableError as b, ensureModalRegistryImage as b$, SandboxProviderUnavailableError as b0, SandboxReplacementProviderStateError as b1, SandboxResumeStateUnavailableError as b2, type SelfhostedApplyDiff as b3, SelfhostedControlError as b4, type SelfhostedEditor as b5, type SelfhostedEnrollment as b6, type SelfhostedExecArgs as b7, type SelfhostedExecResult as b8, type SelfhostedImageOutput as b9, type WorkspaceTreeFingerprint as bA, agentErrorToControlError as bB, assertDescriptorRegistryInvariants as bC, assertProviderRegistryInvariants as bD, assertSafeRelPath as bE, backendSupportsOs as bF, buildDisplayStackScript as bG, buildSelfhostedBackendSession as bH, buildStreamUrl as bI, buildTerminalServerScript as bJ, captureVerifiedWorkspaceArchive as bK, classifyProviderSandboxFailure as bL, clearRunCredentials as bM, clearRunCredentialsForAttempt as bN, contentTypeForCodec as bO, createSandboxClient as bP, createSandboxClientForBackend as bQ, decideSelfhostedRetry as bR, decodeModalSnapshotId as bS, defaultSelfhostedRetryClock as bT, deletePriorPersistedSnapshot as bU, deleteRecordingArtifacts as bV, deserializeSandboxSessionStateEnvelope as bW, desktopCapableBackend as bX, drainingExhaustedError as bY, drainingMessage as bZ, ensureDisplayStack as b_, type SelfhostedLivenessState as ba, type SelfhostedNegotiationInput as bb, type SelfhostedOpObservation as bc, type SelfhostedOpObserver as bd, type SelfhostedOpStreamDeps as be, type SelfhostedRelayConfig as bf, type SelfhostedRetryClock as bg, type SelfhostedRetryDecision as bh, SelfhostedSandboxClient as bi, SelfhostedSession as bj, type SelfhostedSessionBuild as bk, type SelfhostedSessionDeps as bl, type SelfhostedSessionState as bm, type SelfhostedUnavailableReason as bn, type StartRecordingInput as bo, StreamPortUnavailableError as bp, type SwapTargetEstablishability as bq, TERMINAL_SERVER_TIMEOUT_MS as br, TerminalServerError as bs, TerminalServerUnsupportedError as bt, ToolspaceTokenPathError as bu, type VerifiedWorkspaceArchive as bv, WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION as bw, type WorkspaceArchiveDescriptor as bx, type WorkspaceArchiveIntegrityCode as by, WorkspaceArchiveIntegrityError as bz, type ActivePointer as c, toolspaceTokenFileForSession as c$, ensureTerminalServer as c0, establishSandboxSessionFromEnvelope as c1, execDeadlineHint as c2, exposeStreamPort as c3, extForCodec as c4, fingerprintSandboxWorkspace as c5, hasPersistableSandboxProviderIdentity as c6, inspectRecordingArtifact as c7, isExecSessionLostBanner as c8, isProviderSandboxGoneDuringRoutedOperation as c9, renderSelfhostedFault as cA, requirePersistableReplacementSandboxEnvelope as cB, restoredSandboxSessionStateFromEntry as cC, runCredentialPointerFile as cD, runCredentialRoot as cE, runWithToolCallCorrelation as cF, sandboxStateEntryFromRunState as cG, sanitizeOpIdToken as cH, selectBackend as cI, selfhostedFaultClass as cJ, selfhostedLiveness as cK, selfhostedRetryBackoffMs as cL, serializeEstablishedSandboxEnvelope as cM, serializeReplacementSandboxEnvelope as cN, setSelfhostedApplyDiff as cO, startRecording as cP, stopRecording as cQ, stripExecBanner as cR, subjectFor as cS, swapTargetEstablishability as cT, sweepModalOrphanSandboxes as cU, tagModalSandbox as cV, tearDownDisplayStack as cW, tearDownTerminalServer as cX, terminateModalSandboxById as cY, timeoutAgentError as cZ, timeoutControlResponse as c_, isProviderSandboxNotFoundError as ca, isProviderSandboxTransientError as cb, isSelfhostedProviderNotFoundError as cc, makeActiveBackendResolver as cd, materializeRunCredentials as ce, mintStreamToken as cf, modalSandboxAttributionEnvironment as cg, modalSandboxAttributionTags as ch, negotiateCapabilities as ci, negotiateSelfhostedCapabilities as cj, nextDurableOpId as ck, normalizeRunCredentialsResolution as cl, offlineAgentError as cm, offlineControlResponse as cn, opAckSubject as co, opFrameSubject as cp, parseExecBannerExitCode as cq, parseExecBannerSessionId as cr, parseNumstatZ as cs, parsePorcelainV2 as ct, parseUnifiedPatch as cu, parseWorkspaceArchiveDescriptor as cv, payloadTooLargeMessage as cw, readVerifiedWorkspaceArchive as cx, readWorkspaceArchiveFromEnvelopeSessionState as cy, recordingStorageKey as cz, type ChannelAEmitter as d, toolspaceTokenFileFromEnvironment as d0, uploadRecordingArtifact as d1, verifyRestoredWorkspace as d2, verifySandboxExecReadiness as d3, verifyStreamToken as d4, withRunCredentialEnvironment as d5, withRunCredentialsClient as d6, withRunCredentialsSession as d7, withToolspaceTokenClient as d8, withToolspaceTokenEnvironment as d9, withToolspaceTokenSession as da, type ChannelAExecArgs as e, type ChannelAExecResult as f, ChannelANotFoundError as g, type ChannelASession as h, ChannelAUnavailableError as i, ChannelAUnsupportedError as j, ChannelAValidationError as k, type ControlRpc as l, DISPLAY_STACK_TIMEOUT_MS as m, type DefaultBackendLossResult as n, type DesktopGeometry as o, type DisplayStackCallerKind as p, type DisplayStackClassification as q, DisplayStackError as r, type DisplayStackTelemetryContext as s, type DisplayStackTelemetryEvent as t, type DisplayStackTelemetryStatus as u, DisplayStackUnsupportedError as v, type EnsureDisplayStackResult as w, type EnsureTerminalServerOptions as x, type EnsureTerminalServerResult as y, type EstablishedSandboxSession as z };