@opengeni/runtime 0.14.1 → 0.14.15

package/dist/sandbox/run-credentials.d.ts

@@ -0,0 +1,65 @@
+import type { RunCredentialAuthNeeded, RunCredentialFile, RunCredentialRedaction, RunCredentialsResolution } from "@opengeni/contracts";
+import type { ExecCommandArgs, SandboxClient, SandboxSessionLike } from "@openai/agents/sandbox";
+export type RunCredentialExpectedScope = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+};
+export type NormalizedRunCredentialMaterial = {
+    environment: Record<string, string>;
+    files: RunCredentialFile[];
+    fileEnvironment: Record<string, string>;
+    expiresAt: Date | null;
+    authNeeded: RunCredentialAuthNeeded[];
+    redactions: RunCredentialRedaction[];
+};
+export type RunCredentialCommandSession = Pick<SandboxSessionLike, "exec" | "execCommand">;
+export type RunCredentialCommandRunner = (session: RunCredentialCommandSession, args: ExecCommandArgs) => Promise<unknown>;
+export type RunCredentialSessionReady = (session: RunCredentialCommandSession) => Promise<void> | void;
+export 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.
+ */
+export declare function normalizeRunCredentialsResolution(resolution: Extract<RunCredentialsResolution, {
+    status: "not_applicable";
+}>, expected: RunCredentialExpectedScope, now?: Date): null;
+export declare function normalizeRunCredentialsResolution(resolution: Exclude<RunCredentialsResolution, {
+    status: "not_applicable";
+}>, expected: RunCredentialExpectedScope, now?: Date): NormalizedRunCredentialMaterial;
+export declare function normalizeRunCredentialsResolution(resolution: RunCredentialsResolution, expected: RunCredentialExpectedScope, now?: Date): NormalizedRunCredentialMaterial | null;
+export declare function runCredentialRoot(sessionId: string): string;
+export declare function runCredentialPointerFile(sessionId: string): string;
+export 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. */
+export declare function materializeRunCredentials(session: RunCredentialCommandSession, material: NormalizedRunCredentialMaterial, options: MaterializeRunCredentialsOptions): Promise<void>;
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export declare function withRunCredentialsSession<T extends object>(session: T, sessionId: string): T;
+/** Decorate every client-created/resumed session after the host seeds it. */
+export declare function withRunCredentialsClient(client: SandboxClient, sessionId: string, onSessionReady?: RunCredentialSessionReady): SandboxClient;

package/dist/sandbox/select.d.ts

@@ -0,0 +1,120 @@
+import { type CapabilityDescriptor, type SandboxBackend, type SandboxOs, type SessionCapabilities } from "@opengeni/contracts";
+export 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).
+ */
+export declare function selectBackend(backend: SandboxBackend): CapabilityDescriptor;
+/** True iff the descriptor lists the requested OS as supported. */
+export 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.
+ */
+export 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.
+ */
+export declare function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilities;

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

@@ -0,0 +1,91 @@
+import type { SandboxOs, SessionCapabilities } from "@opengeni/contracts";
+import type { SelfhostedSession } from "./session";
+/**
+ * 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).
+ */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export 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;
+export 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.
+ */
+export declare function negotiateSelfhostedCapabilities(input: SelfhostedNegotiationInput): Promise<SessionCapabilities>;

package/dist/sandbox/selfhosted/control-rpc.d.ts

@@ -0,0 +1,175 @@
+import { AgentError, ControlRequest, ControlResponse, ErrorCode } from "@opengeni/agent-proto";
+import type { CapabilityUnavailableReason } from "@opengeni/contracts";
+export 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).
+ */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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. */
+export 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.
+ */
+export 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). */
+export 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). */
+export 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). */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export declare function offlineControlResponse(requestId: string, neverSent?: boolean): ControlResponse;
+/** A `ControlResponse` carrying a synthesized TIMEOUT error (→ reconnecting). */
+export declare function timeoutControlResponse(requestId: string): ControlResponse;

package/dist/sandbox/selfhosted/fault-rendering.d.ts

@@ -0,0 +1,40 @@
+import { SelfhostedControlError } from "./control-rpc";
+/**
+ * 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.
+ */
+export 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.)
+ */
+export declare const SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES: ReadonlySet<string>;
+/** The four mandatory field labels (exported so tests can assert their presence). */
+export declare const FAULT_FIELD_WHAT_HAPPENED = "What happened:";
+export declare const FAULT_FIELD_WHICH_LAYER = "Which layer:";
+export declare const FAULT_FIELD_WHAT_PRESERVED = "What was preserved:";
+export 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.
+ */
+export declare function renderSelfhostedFault(error: SelfhostedControlError): string;

package/dist/sandbox/selfhosted/op-observer.d.ts

@@ -0,0 +1,40 @@
+import type { ErrorCode } from "@opengeni/agent-proto";
+import type { SelfhostedUnavailableReason } from "./control-rpc";
+/**
+ * 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.
+ */
+export 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. */
+export type SelfhostedOpObserver = (observation: SelfhostedOpObservation) => void;

package/dist/sandbox/selfhosted/op-stream.d.ts

@@ -0,0 +1,104 @@
+import { type ExecRequest, type ExecResponse } from "@opengeni/agent-proto";
+import { type ControlRpc } from "./control-rpc";
+import { type SelfhostedRetryClock } from "./retry-policy";
+import { type OpStreamTransport } from "./op-transport";
+/** Initial send-credit window (bytes) when the caller does not size it. Matches
+ *  the wire default OpStart advertises (~4 MiB). */
+export 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). */
+export 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). */
+export 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). */
+export 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.
+ */
+export 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>;
+}
+export interface OpStreamExecClientDeps {
+    workspaceId: string;
+    agentId: string;
+    /** The lease/active epoch every ControlRequest is fenced under. */
+    epoch: number;
+    /** The rpc request/reply seam (OpStart/OpQuery/OpAttach ride here). */
+    controlRpc: ControlRpc;
+    /** The rpc subject (`agent.<ws>.<id>.rpc`). */
+    rpcSubject: string;
+    /** The frame/ack seam (subscribe + publish). */
+    transport: OpStreamTransport;
+    journal?: OpStreamJournal;
+    windowBytes?: number;
+    /** Control-op round-trip timeout for OpStart/OpQuery/OpAttach (the SHORT
+     *  control budget, not the exec deadline). */
+    controlTimeoutMs: number;
+    /** The retry clock (sleep + jitter), injected for deterministic tests. */
+    retryClock: SelfhostedRetryClock;
+    ackIntervalMs?: number;
+    silenceTimeoutMs?: number;
+    reconnectHoldMs?: number;
+}
+/** A completed op-stream exec: the legacy-shaped response plus the healing
+ *  telemetry the session folds into its op observation. */
+export 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 per-session op-stream exec client. One instance per `SelfhostedSession`;
+ * `exec()` runs one op end-to-end; `finalizeSettledOps()` is the turn-end hook
+ * that advances the acked frontier durably (journal) and then on the wire.
+ */
+export declare class OpStreamExecClient {
+    private readonly deps;
+    private readonly settled;
+    private readonly inFlight;
+    constructor(deps: OpStreamExecClientDeps);
+    private generation;
+    /**
+     * Cancel an exec by its durable op id. OpCancel is idempotent and also acts
+     * as a cancel-before-start tombstone, so calling this while OpStart is still
+     * racing is safe: the runner either kills the accepted process tree or
+     * refuses the later start without spawning it.
+     */
+    cancel(opId: string): Promise<void>;
+    /**
+     * Run one exec over the op stream. `opId` is the durable id (B1) — a re-issue
+     * with the same id attaches instead of re-running. `deadlineMs` is the exec
+     * process budget (relative); the runner's enforcement is authoritative.
+     * `wallMs` is the client-side give-up wall (deadline + reply grace).
+     */
+    exec(opId: string, exec: ExecRequest, deadlineMs: number, wallMs: number): Promise<OpStreamExecOutcome>;
+    /**
+     * The turn-end durability hook (the hard gate's ordering): for every op whose
+     * result the turn has durably consumed — (1) already true when this runs —
+     * (2) persist the settled frontier to the journal, then (3) publish the wire
+     * final ack (`acked_seq = exit_seq, final = true`), which licenses the runner
+     * to GC the op. A kill between (2) and (3) is safe: the re-dispatched turn
+     * does not re-execute a durably-recorded call, and the runner's retention TTL
+     * reaps the never-final-acked op — no loss, bounded residue. Publish failures
+     * are swallowed for the same reason.
+     */
+    finalizeSettledOps(): Promise<void>;
+}