@opengeni/runtime 0.14.1 → 0.14.15

package/dist/{localSources-T3HZ6KY4.js → localSources-BXHBKGF4.js}

@@ -3,7 +3,7 @@ import {
   applyLocalSourceManifestToState,
   materializeLocalSourceManifest,
   materializeLocalSourceManifestEntry
-} from "./chunk-4YJ5Z52Z.js";
+} from "./chunk-7E2ZSCZK.js";
 import "./chunk-K4V4QYCL.js";
 import "./chunk-PZ5AY32C.js";
 export {
@@ -12,4 +12,4 @@ export {
   materializeLocalSourceManifest,
   materializeLocalSourceManifestEntry
 };
-//# sourceMappingURL=localSources-T3HZ6KY4.js.map
+//# sourceMappingURL=localSources-BXHBKGF4.js.map

package/dist/mcp-network.d.ts

@@ -1,33 +1,32 @@
-import { Settings } from '@opengeni/config';
-import { DnsLookup, isNonPublicAddress } from '@opengeni/network';
-export { undiciFetch } from '@opengeni/network';
-
-declare const MCP_MAX_RESPONSE_BYTES: number;
-declare const MCP_MAX_INBOUND_REQUEST_BYTES: number;
-declare const MCP_MAX_TOOL_DEFINITION_BYTES: number;
-declare const MCP_MAX_TOOL_LIST_BYTES: number;
-declare const MCP_MAX_TOOL_LIST_ENTRIES = 1000;
-declare const MCP_MAX_TOOL_RESULT_BYTES: number;
-declare const MCP_MAX_TOOL_SEARCH_DISCLOSURE_BYTES: number;
-declare const MCP_MAX_SELECTED_SERVERS = 64;
-declare const MCP_MAX_CONCURRENT_SERVER_OPERATIONS = 8;
-declare const MCP_DEFAULT_OUTER_CONNECT_TIMEOUT_MS = 10000;
-declare const MCP_MAX_AGGREGATE_TOOL_LIST_ENTRIES = 4096;
-declare const MCP_MAX_AGGREGATE_TOOL_LIST_BYTES: number;
-declare const MCP_MAX_TOOL_SEARCH_SOURCES = 64;
-declare const MCP_MAX_TOOL_SEARCH_SOURCE_LABEL_LENGTH = 120;
-declare const MCP_MAX_TOOL_SEARCH_DESCRIPTION_BYTES: number;
-declare class McpPayloadTooLargeError extends Error {
+import type { Settings } from "@opengeni/config";
+import { isNonPublicAddress, type DnsLookup } from "@opengeni/network";
+export { undiciFetch } from "@opengeni/network";
+export declare const MCP_MAX_RESPONSE_BYTES: number;
+export declare const MCP_MAX_INBOUND_REQUEST_BYTES: number;
+export declare const MCP_MAX_TOOL_DEFINITION_BYTES: number;
+export declare const MCP_MAX_TOOL_LIST_BYTES: number;
+export declare const MCP_MAX_TOOL_LIST_ENTRIES = 1000;
+export declare const MCP_MAX_TOOL_RESULT_BYTES: number;
+export declare const MCP_MAX_TOOL_SEARCH_DISCLOSURE_BYTES: number;
+export declare const MCP_MAX_SELECTED_SERVERS = 64;
+export declare const MCP_MAX_CONCURRENT_SERVER_OPERATIONS = 8;
+export declare const MCP_DEFAULT_OUTER_CONNECT_TIMEOUT_MS = 10000;
+export declare const MCP_MAX_AGGREGATE_TOOL_LIST_ENTRIES = 4096;
+export declare const MCP_MAX_AGGREGATE_TOOL_LIST_BYTES: number;
+export declare const MCP_MAX_TOOL_SEARCH_SOURCES = 64;
+export declare const MCP_MAX_TOOL_SEARCH_SOURCE_LABEL_LENGTH = 120;
+export declare const MCP_MAX_TOOL_SEARCH_DESCRIPTION_BYTES: number;
+export declare class McpPayloadTooLargeError extends Error {
     readonly label: string;
     readonly actualBytes: number;
     readonly maxBytes: number;
     constructor(label: string, actualBytes: number, maxBytes: number);
 }
-declare function mcpSerializedSizeBytes(value: unknown): number;
-declare function assertMcpPayloadWithinBytes(value: unknown, maxBytes: number, label: string): void;
-declare function assertMcpToolListWithinBounds<T>(tools: readonly T[]): readonly T[];
-declare function assertMcpServerSelectionWithinBounds<T>(servers: readonly T[]): readonly T[];
-declare function mcpOuterConnectTimeoutMs(configuredTimeouts: readonly (number | undefined)[]): number;
+export declare function mcpSerializedSizeBytes(value: unknown): number;
+export declare function assertMcpPayloadWithinBytes(value: unknown, maxBytes: number, label: string): void;
+export declare function assertMcpToolListWithinBounds<T>(tools: readonly T[]): readonly T[];
+export declare function assertMcpServerSelectionWithinBounds<T>(servers: readonly T[]): readonly T[];
+export declare function mcpOuterConnectTimeoutMs(configuredTimeouts: readonly (number | undefined)[]): number;
 type McpToolListContribution = {
     entries: number;
     bytes: number;
@@ -38,7 +37,7 @@ type McpToolListContribution = {
  * cache invalidation/relisting cannot ratchet the budget upward. Failed
  * replacements leave the previous accounting intact.
  */
-declare class McpAggregateToolListBudget {
+export declare class McpAggregateToolListBudget {
     private readonly label;
     private readonly maxEntries;
     private readonly maxBytes;
@@ -51,7 +50,7 @@ declare class McpAggregateToolListBudget {
     snapshot(): Readonly<McpToolListContribution>;
 }
 /** Stable-order parallel map with a hard in-flight ceiling and fail-stop drain. */
-declare function boundedParallelMap<T, R>(values: readonly T[], concurrency: number, mapper: (value: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function boundedParallelMap<T, R>(values: readonly T[], concurrency: number, mapper: (value: T, index: number) => Promise<R>): Promise<R[]>;
 /**
  * Guard normal MCP traffic with the same deployment policy as OAuth traffic.
  * The pinned transport resolves and policy-checks the destination after the
@@ -63,19 +62,17 @@ declare function boundedParallelMap<T, R>(values: readonly T[], concurrency: num
  * This module is deliberately agent-loop-free. API code imports the explicit
  * `@opengeni/runtime/mcp-network` leaf rather than the runtime root barrel.
  */
-declare function guardedMcpFetch<TInput extends string | URL | Request>(settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">, fetchImpl: (input: TInput, init?: RequestInit) => Promise<Response>, options?: {
+export declare function guardedMcpFetch<TInput extends string | URL | Request>(settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">, fetchImpl: (input: TInput, init?: RequestInit) => Promise<Response>, options?: {
     maxResponseBytes?: number;
     dnsLookup?: DnsLookup;
     pinResolvedDestination?: boolean;
     requireHttpsOutsideLocalTest?: boolean;
 }): (input: TInput, init?: RequestInit) => Promise<Response>;
-declare function boundMcpResponseBody(response: Response, maxBytes: number): Response;
-declare function cancelMcpResponseBody(response: Response): Promise<void>;
+export declare function boundMcpResponseBody(response: Response, maxBytes: number): Response;
+export declare function cancelMcpResponseBody(response: Response): Promise<void>;
 /** Read and rebuild an inbound MCP request before the SDK parses it. */
-declare function boundedMcpRequest(request: Request, maxBytes?: number): Promise<Request>;
-declare function assertMcpDestinationAllowed(rawUrl: string, settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">, options?: {
+export declare function boundedMcpRequest(request: Request, maxBytes?: number): Promise<Request>;
+export declare function assertMcpDestinationAllowed(rawUrl: string, settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">, options?: {
     dnsLookup?: DnsLookup;
 }): Promise<void>;
-declare const isNonPublicMcpAddress: typeof isNonPublicAddress;
-
-export { MCP_DEFAULT_OUTER_CONNECT_TIMEOUT_MS, MCP_MAX_AGGREGATE_TOOL_LIST_BYTES, MCP_MAX_AGGREGATE_TOOL_LIST_ENTRIES, MCP_MAX_CONCURRENT_SERVER_OPERATIONS, MCP_MAX_INBOUND_REQUEST_BYTES, MCP_MAX_RESPONSE_BYTES, MCP_MAX_SELECTED_SERVERS, MCP_MAX_TOOL_DEFINITION_BYTES, MCP_MAX_TOOL_LIST_BYTES, MCP_MAX_TOOL_LIST_ENTRIES, MCP_MAX_TOOL_RESULT_BYTES, MCP_MAX_TOOL_SEARCH_DESCRIPTION_BYTES, MCP_MAX_TOOL_SEARCH_DISCLOSURE_BYTES, MCP_MAX_TOOL_SEARCH_SOURCES, MCP_MAX_TOOL_SEARCH_SOURCE_LABEL_LENGTH, McpAggregateToolListBudget, McpPayloadTooLargeError, assertMcpDestinationAllowed, assertMcpPayloadWithinBytes, assertMcpServerSelectionWithinBounds, assertMcpToolListWithinBounds, boundMcpResponseBody, boundedMcpRequest, boundedParallelMap, cancelMcpResponseBody, guardedMcpFetch, isNonPublicMcpAddress, mcpOuterConnectTimeoutMs, mcpSerializedSizeBytes };
+export declare const isNonPublicMcpAddress: typeof isNonPublicAddress;

package/dist/metrics.d.ts

@@ -0,0 +1,33 @@
+export 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;
+};

package/dist/sandbox/capabilities.d.ts

@@ -0,0 +1,11 @@
+import { CAPABILITY_DESCRIPTORS, DESKTOP_STREAM_PORT, type CapabilityDescriptor } from "@opengeni/contracts";
+export { CAPABILITY_DESCRIPTORS, DESKTOP_STREAM_PORT };
+export type { CapabilityDescriptor };
+/**
+ * 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.
+ */
+export declare function assertDescriptorRegistryInvariants(): void;

package/dist/sandbox/channel-a.d.ts

@@ -0,0 +1,226 @@
+import type { FsDeleteRequest, FsDeleteResponse, FsListRequest, FsListResponse, FsMkdirRequest, FsMkdirResponse, FsMoveRequest, FsMoveResponse, FsReadRequest, FsReadResponse, FsWriteRequest, FsWriteResponse, GitChangedPayload, GitDiffHunk, GitDiffRequest, GitDiffResponse, GitFileStatusCode, GitLogRequest, GitLogResponse, GitShowRequest, GitShowResponse, GitStatusRequest, GitStatusResponse, PtyCloseRequest, PtyOpenRequest, PtyOpenResponse, PtyResizeRequest, PtyWriteRequest, SessionEventType, SessionStructuredCapabilities, TerminalExecRequest, TerminalExecResponse } from "@opengeni/contracts";
+export { isExecSessionLostBanner, parseExecBannerExitCode, parseExecBannerSessionId, } from "./exec-banner";
+export type ChannelAExecResult = {
+    output?: string;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    sessionId?: number;
+    wallTimeSeconds?: number;
+};
+export 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;
+};
+export type ChannelAEditor = {
+    createFile?(op: unknown): Promise<unknown>;
+    updateFile?(op: unknown): Promise<unknown>;
+    deleteFile?(op: unknown): Promise<unknown>;
+};
+export 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;
+};
+export 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. */
+export declare class ChannelAUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class ChannelAConflictError extends Error {
+    constructor(message: string);
+}
+export declare class ChannelANotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class ChannelAUnsupportedError extends Error {
+    constructor(message: string);
+}
+export type ChannelAEmitter = (events: {
+    type: SessionEventType;
+    payload: unknown;
+}[]) => Promise<void>;
+export type SandboxChannelAServiceOptions = {
+    session: ChannelASession;
+    workspaceRoot?: string;
+    leaseEpoch?: number;
+    revision?: number;
+    emit?: ChannelAEmitter;
+    runAs?: string;
+};
+export declare const REPOSITORY_DISCOVERY_LIMIT = 256;
+export type RepositoryDiscoveryDegradedReason = "command_failed" | "command_timed_out" | "result_limit_exceeded";
+export type RepositoryDiscoveryResult = {
+    repos: string[];
+    complete: boolean;
+    degradedReason: RepositoryDiscoveryDegradedReason | null;
+};
+export 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;
+    /** Bind an untracked regular-file descriptor to its repository root and its
+     * lstat identity before producing bytes. The final producer reads fd 3 rather
+     * than reopening the path, so a check→read symlink swap cannot disclose a
+     * target outside the repository (or substitute another in-repository inode). */
+    private confinedUntrackedRegularFileCommand;
+    /** 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>;
+}
+export declare function stripExecBanner(raw: string): string;
+export declare function assertSafeRelPath(p: string): string;
+export declare function parsePorcelainV2(z: string): Omit<GitStatusResponse, "revision">;
+export type NumstatEntry = {
+    additions: number;
+    deletions: number;
+    binary: boolean;
+    oldPath: string | null;
+    newPath: string;
+};
+export declare function parseNumstatZ(z: string): NumstatEntry[];
+export declare function parseUnifiedPatch(patch: string): {
+    hunks: GitDiffHunk[];
+    status: GitFileStatusCode;
+};

package/dist/sandbox/display-stack.d.ts

@@ -0,0 +1,99 @@
+import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
+export { DESKTOP_STREAM_PORT };
+export declare const STREAM_PORT = 6080;
+export 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). */
+export type DesktopGeometry = {
+    width: number;
+    height: number;
+    dpi: number;
+};
+export 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. */
+export 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`. */
+export declare class DisplayStackUnsupportedError extends Error {
+    constructor(message: string);
+}
+export type DisplayStackCallerKind = "viewer" | "computer" | "unknown";
+export type DisplayStackClassification = "cold" | "already_ready" | "contention" | "unknown";
+export type DisplayStackTelemetryStatus = "started" | "waiting" | "completed" | "failed";
+/** Secret-free, bounded-cardinality stage observation. Provider/sandbox IDs are
+ * log correlation fields, never metric labels. */
+export 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;
+};
+export type DisplayStackTelemetryContext = {
+    callerKind: DisplayStackCallerKind;
+    sandboxId?: string;
+    leaseEpoch?: number;
+};
+export 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>;
+};
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export declare function tearDownDisplayStack(session: unknown): Promise<void>;

package/dist/sandbox/errors.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxBackend } from "@opengeni/contracts";
+export 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. */
+export declare class SandboxResumeStateUnavailableError extends Error {
+    readonly backend: SandboxBackend | string;
+    constructor(backend: SandboxBackend | string);
+}
+export declare class SandboxProviderUnavailableError extends Error {
+    readonly backend: SandboxBackend | string;
+    constructor(backend: SandboxBackend | string);
+}

package/dist/sandbox/exec-banner.d.ts

@@ -0,0 +1,19 @@
+export type ExecResponseBanner = {
+    kind: "absent";
+} | {
+    kind: "invalid";
+} | {
+    kind: "running";
+    sessionId: number;
+} | {
+    kind: "exited";
+    exitCode: number;
+};
+/** Parse exactly one terminal status from the SDK metadata header. Responses
+ * that resemble SDK output but lack a complete delimiter/header are invalid,
+ * while raw provider output without SDK metadata remains `absent` so callers
+ * may use their provider-specific body markers. */
+export declare function parseExecResponseBanner(raw: string): ExecResponseBanner;
+export declare function parseExecBannerSessionId(raw: string): number | null;
+export declare function parseExecBannerExitCode(raw: string): number | null;
+export declare function isExecSessionLostBanner(out: string, execSessionId: number): boolean;