@opengeni/runtime 0.14.1 → 0.14.15

package/dist/sandbox/selfhosted/session.d.ts

@@ -0,0 +1,552 @@
+import { ControlResponse, type DesktopInputRequest } from "@opengeni/agent-proto";
+import { Manifest } from "@openai/agents/sandbox";
+import type { ExposedPortEndpoint } from "../stream-port";
+import { type ControlRpc } from "./control-rpc";
+import { type SelfhostedRetryClock } from "./retry-policy";
+import type { SelfhostedOpObserver } from "./op-observer";
+import { type OpStreamJournal } from "./op-stream";
+import { type OpStreamTransport } from "./op-transport";
+/** 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. */
+export 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. */
+export 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`. */
+export 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). */
+export 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. */
+export 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`. */
+export 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). */
+export 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.
+ */
+export 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;
+}
+export 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). */
+export 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). */
+export 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`).
+ */
+export 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.
+ */
+export 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 effective clamped exec process deadline (ms): the exec-specific budget
+     *  when threaded, else the control timeout. Public so adapters that project a
+     *  structured command receipt can report the exact deadline the agent enforces
+     *  instead of repeating (and potentially drifting from) this normalization. */
+    get effectiveExecDeadlineMs(): number;
+    /** 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.
+ */
+export 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).
+ */
+export 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).
+ */
+export 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.
+ */
+export declare function isSelfhostedProviderNotFoundError(_error: unknown): false;

package/dist/sandbox/selfhosted/testing.d.ts

@@ -0,0 +1,48 @@
+import { ControlRequest, ControlResponse, type ExecRequest, type ExecResponse } from "@opengeni/agent-proto";
+import type { ControlRpc } from "./control-rpc";
+/** A pluggable exec handler — given an ExecRequest, return an ExecResponse (or
+ *  throw to surface a synthesized error). Defaults to a trivial echo. */
+export type MockExecHandler = (req: ExecRequest) => ExecResponse | Promise<ExecResponse>;
+export 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.
+ */
+export 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>;
+}