@opengeni/runtime 0.14.1 → 0.14.15

package/dist/sandbox/stream-port.d.ts

@@ -0,0 +1,80 @@
+/** The provider-resolved endpoint for an exposed port. Mirrors the SDK's
+ *  `ExposedPortEndpoint` (host/port/tls/query/...) WITHOUT importing the
+ *  agent-loop barrel — the leaf stays agent-loop-free. */
+export type ExposedPortEndpoint = {
+    host: string;
+    port: number;
+    tls?: boolean;
+    query?: string;
+    protocol?: string;
+    url?: string;
+    /** The URL path the socket connects on. Modal/Daytona/Blaxel serve the edge at
+     *  the root (`/`, the default); the selfhosted relay serves it at `/stream`
+     *  (M8b). When set, buildStreamUrl uses it instead of the root. */
+    path?: string;
+    [key: string]: unknown;
+};
+/** Thrown when the provider cannot expose the stream port (no resolveExposedPort,
+ *  or the provider tunnel lookup failed). The caller degrades the desktop cell to
+ *  `transport:null` (a value, never a crash) — a headless-only provider or a
+ *  transient tunnel failure must not fail the whole handshake. */
+export declare class StreamPortUnavailableError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export type ExposeStreamPortInput = {
+    workspaceId: string;
+    sessionId: string;
+    /** The sandbox_lease_holders viewer row id the token is scoped to. */
+    viewerId: string;
+    /** The live lease epoch — the fence the token is pinned to. */
+    leaseEpoch: number;
+    /** The HMAC secret for the scoped stream token (resolveStreamTokenSecret). */
+    streamTokenSecret: string;
+    /** The exposed stream port; defaults to 6080. */
+    port?: number;
+    /** Token TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+    ttlSeconds?: number;
+    /** The framebuffer geometry to echo back to the client. */
+    resolution?: [number, number];
+    /** Override the issue clock (tests). Seconds since the epoch. */
+    nowSeconds?: number;
+};
+export type ExposeStreamPortResult = {
+    /** The direct-to-provider WS URL the viewer connects to (provider-scoped; the
+     *  OpenGeni token is NOT appended). */
+    url: string;
+    /** The scoped OpenGeni stream token — recorded against the holder, NEVER a URL
+     *  query param. */
+    token: string;
+    /** ISO absolute expiry of the token (the rotation hot-swap window backstop). */
+    expiresAt: string;
+    /** The pixel transport the client speaks. */
+    transport: "vnc-ws";
+    /** The reference noVNC client the SDK helper mounts. */
+    client: "novnc";
+    resolution: [number, number];
+    leaseEpoch: number;
+};
+/**
+ * Assemble the direct-to-provider WS URL from a resolved endpoint. The SDK's
+ * `urlForExposedPort(endpoint,'ws')` is the canonical tls-aware, IPv6-bracketing,
+ * provider-query-preserving assembler — we reimplement its exact logic here so
+ * the leaf stays agent-loop-free (the helper lives behind the bare
+ * `@openai/agents-core` root, which the import-discipline test forbids). The
+ * provider's own `endpoint.query` (Blaxel `bl_preview_token`, Daytona signed
+ * token) is preserved; the OpenGeni token is NOT appended (it is recorded against
+ * the holder + validated at the in-box websockify edge).
+ */
+export declare function buildStreamUrl(endpoint: ExposedPortEndpoint): string;
+/**
+ * Resolve the provider's scoped tunnel for the stream port and mint the scoped
+ * OpenGeni stream token. Returns a coherent `{url, token, expiresAt, transport,
+ * client, resolution}` cell the caller records on the lease (data_plane_url) and
+ * returns in the DesktopStream handshake.
+ *
+ * Throws `StreamPortUnavailableError` when the provider session cannot resolve
+ * the port (no `resolveExposedPort`, or the tunnel lookup failed) — the caller
+ * maps this to a `transport:null` degradation (a value, never a crash).
+ */
+export declare function exposeStreamPort(session: unknown, input: ExposeStreamPortInput): Promise<ExposeStreamPortResult>;

package/dist/sandbox/stream-token.d.ts

@@ -0,0 +1,44 @@
+import { type StreamTokenPayload as StreamTokenPayloadType } from "@opengeni/contracts";
+export declare const STREAM_TOKEN_DEFAULT_TTL_SECONDS = 120;
+export type MintStreamTokenInput = {
+    workspaceId: string;
+    sessionId: string;
+    /** The sandbox_lease_holders viewer row id. */
+    viewerId: string;
+    /** The epoch the token is fenced to. For a Modal box this is the live LEASE
+     *  epoch (re-minted on box rollover). For a SELFHOSTED relay stream (M8b) this is
+     *  the session's swap `active_epoch`: the relay tracks the highest epoch any
+     *  viewer presented per channel and REJECTS a token with a lower epoch, so a
+     *  viewer whose token predates a swap-away cannot reach the machine the session
+     *  swapped off of. One field, two fences — the relay/in-box edge reads it as the
+     *  stale-viewer floor either way. */
+    leaseEpoch: number;
+    /** v1 is always "view"; "control" is the never-granted raw-input plane. */
+    mode?: "view" | "control";
+    /** The exposed stream port (noVNC); defaults to 6080. */
+    port?: number;
+    /** TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+    ttlSeconds?: number;
+    /** Override the issue clock (tests). Seconds since the epoch. */
+    nowSeconds?: number;
+};
+/**
+ * Mint a scoped stream token for one viewer holder. Builds the hard-narrow
+ * StreamTokenPayload (the claim set the in-box edge / control plane validates)
+ * and signs it with the resolved stream-token secret via the contracts HMAC
+ * envelope (`ogs_` prefix). The token is RECORDED against the holder row by the
+ * caller and is NEVER appended to the data-plane URL as a query param.
+ */
+export declare function mintStreamToken(secret: string, input: MintStreamTokenInput): Promise<string>;
+/**
+ * Verify a scoped stream token. Returns the parsed claims on success, or null on
+ * a bad prefix / malformed envelope / bad HMAC signature / schema-invalid claims
+ * / expiry. Re-exports the contracts verify; the leaf is the agent-loop-free
+ * import surface the API uses.
+ *
+ * The epoch fence (claim.leaseEpoch vs the LIVE lease epoch) and the
+ * workspace+session scope are enforced at USE by the caller against the live
+ * lease + route params — verify proves authenticity + freshness only.
+ */
+export declare function verifyStreamToken(secret: string, token: string, nowSeconds?: number): Promise<StreamTokenPayloadType | null>;
+export { StreamTokenPayload, type StreamTokenPayload as StreamTokenPayloadType, } from "@opengeni/contracts";

package/dist/sandbox/terminal-server.d.ts

@@ -0,0 +1,67 @@
+import { TERMINAL_STREAM_PORT } from "@opengeni/contracts";
+export { TERMINAL_STREAM_PORT };
+export declare const TERMINAL_SERVER_TIMEOUT_MS = 60000;
+/** Thrown when the ttyd launch failed inside the box. exitCode 14 maps to the
+ *  up-script's "ttyd failed to come up" stage; any other non-zero is unknown.
+ *  Degradation is surfaced as a value to clients by the caller (Terminal
+ *  transport falls back to sse-events / null); this error is for diagnostics. */
+export declare class TerminalServerError extends Error {
+    readonly exitCode: number;
+    readonly stage: "ttyd" | "unknown";
+    constructor(exitCode: number, output: string);
+}
+/** Thrown when the provider session cannot run commands (a headless-only backend
+ *  with neither `exec` nor `execCommand`). The terminal tier degrades to the
+ *  Channel-A sse-events firehose — the caller maps this to a `transport:null`
+ *  pty-ws (the read-only firehose still works). */
+export declare class TerminalServerUnsupportedError extends Error {
+    constructor(message: string);
+}
+export type EnsureTerminalServerOptions = {
+    /** The exposed terminal port; defaults to 7681 (ttyd default). */
+    port?: number;
+    /** Per-exec timeout; defaults to TERMINAL_SERVER_TIMEOUT_MS. */
+    timeoutMs?: number;
+};
+export type EnsureTerminalServerResult = {
+    /** The exposed port ttyd listens on (PTY-over-websocket). */
+    port: number;
+    /** The raw `OPENGENI_TERMINAL_UP …` marker line, for diagnostics. Never
+     *  surfaced to clients. */
+    marker: string;
+};
+/**
+ * Build the shell command that runs the idempotent up-script under an in-box
+ * `flock`. The script is shipped in the image at /usr/local/bin/opengeni-terminal-up
+ * (the canonical desktop image, alongside opengeni-desktop-up); we set the port
+ * env and wrap the call in `flock` so two concurrent ensureTerminalServer callers
+ * (the API viewer op + the agent turn, both racing after a rollover) serialize
+ * without a double launch. The up-script's own curl readiness probe makes the
+ * second call a no-op.
+ *
+ * Exported (pure, side-effect-free) so the ensureTerminalServer unit test can
+ * assert the exact command sequence without a live box. Mirrors
+ * buildDisplayStackScript. A ttyd process is sandbox-group-global, not
+ * OpenGeni-session-specific, so it must never inherit the box-global legacy
+ * Toolspace pointer. Session-scoped interactive exec/PTY uses Channel A; the
+ * shared ttyd shell fails closed for Toolspace until that stream plane itself is
+ * session-isolated.
+ */
+export declare function buildTerminalServerScript(options?: EnsureTerminalServerOptions): string;
+/**
+ * Idempotently bring up the ttyd PTY-over-websocket server on the live box. Safe
+ * to call N times (the in-box flock + the up-script's curl readiness probe make a
+ * second call a no-op). Resolves with the exposed port on success; throws
+ * `TerminalServerError` on a launch failure and `TerminalServerUnsupportedError`
+ * when the session cannot run commands.
+ *
+ * `session` is the externally-owned provider session (the `established.session`
+ * from establishSandboxSessionFromEnvelope, or any SandboxSessionLike). We prefer
+ * `session.exec` (structured `{exitCode}`) and fall back to `session.execCommand`
+ * (bare string), inferring success from the up-script's marker line in the
+ * fallback case. Mirrors ensureDisplayStack exactly.
+ */
+export declare function ensureTerminalServer(session: unknown, options?: EnsureTerminalServerOptions): Promise<EnsureTerminalServerResult>;
+/** Tear the terminal server down (down-script). Best-effort; never throws on a
+ *  missing process. Mirrors tearDownDisplayStack. */
+export declare function tearDownTerminalServer(session: unknown): Promise<void>;

package/dist/sandbox/toolspace-token.d.ts

@@ -0,0 +1,23 @@
+import type { SandboxClient } from "@openai/agents/sandbox";
+export declare class ToolspaceTokenPathError extends Error {
+    constructor(message: string);
+}
+export declare function shellToolspacePath(value: string): string;
+/**
+ * Derive the per-session token file beside the legacy manifest pointer.
+ *
+ * The manifest pointer stays box-global so an already-warm shared sandbox does
+ * not receive an illegal environment delta. Every OpenGeni command overrides
+ * that pointer with this deterministic path. The hash is path hygiene and
+ * avoids disclosing host/session ids in filenames; filesystem paths are not an
+ * authorization boundary. The delegated bearer's session claim remains the
+ * authority boundary for Toolspace calls.
+ */
+export declare function toolspaceTokenFileForSession(manifestTokenFile: string, sessionId: string): string;
+export declare function toolspaceTokenFileFromEnvironment(environment: Readonly<Record<string, string>>, sessionId: string): string;
+/** Prefix one sandbox command with its session-specific Toolspace pointer. */
+export declare function withToolspaceTokenEnvironment(cmd: string, tokenFile: string): string;
+/** Preserve provider identity/capabilities while decorating command creation. */
+export declare function withToolspaceTokenSession<T extends object>(session: T, tokenFile: string): T;
+/** Decorate every client-created/resumed session with one session pointer. */
+export declare function withToolspaceTokenClient(client: SandboxClient, tokenFile: string): SandboxClient;

package/dist/sandbox/turn-tool-cancellation.d.ts

@@ -0,0 +1,72 @@
+type CommandCancellationSession = {
+    cancelExecCommand?(opId: string): Promise<boolean>;
+    supportsPty?(): boolean;
+    hasRetainedProcess?(providerSessionId: number): boolean;
+    writeStdinForProcessMutation?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    writeStdinForProcessControl?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    execCommandForProcessControl?(providerSessionId: number, args: TurnSandboxCommandArgs): Promise<string>;
+};
+export type TurnSandboxCommandArgs = {
+    cmd: string;
+    workdir?: string;
+    shell?: string;
+    login?: boolean;
+    tty?: boolean;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+    runAs?: string;
+};
+export type TurnSandboxCommandResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    wallTimeSeconds: number;
+};
+export type TurnSandboxCommandSession = CommandCancellationSession & {
+    exec?(args: TurnSandboxCommandArgs): Promise<unknown>;
+    execCommand?(args: TurnSandboxCommandArgs): Promise<string>;
+    writeStdin?(args: {
+        sessionId: number;
+        chars?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+};
+/**
+ * The worker may publish an attempt-quiesced receipt only after this fence
+ * resolves. `cancel()` prevents new turn-owned sandbox calls, actively stops
+ * shell processes, and `waitForQuiescence()` drains every capability call that
+ * was already in flight. Cleanup/telemetry outside the sandbox capability set
+ * remains independently attempt-fenced.
+ */
+export type TurnToolCancellationFence = {
+    cancel(reason?: unknown): void;
+    waitForQuiescence(): Promise<void>;
+    runSandboxCommand(session: TurnSandboxCommandSession, args: TurnSandboxCommandArgs): Promise<unknown>;
+    runSandboxCommandStructured(session: TurnSandboxCommandSession, args: TurnSandboxCommandArgs): Promise<TurnSandboxCommandResult>;
+};
+export type TurnToolCancellationController = TurnToolCancellationFence & {
+    wrapTools<T>(tools: T[], session?: CommandCancellationSession): T[];
+};
+export declare class TurnSandboxCommandCancelledError extends Error {
+    readonly name = "TurnSandboxCommandCancelledError";
+    constructor(reason: unknown);
+}
+export declare function cancellableShellCommand(command: string, markerPath: string): string;
+export declare function createTurnToolCancellationController(signal?: AbortSignal): TurnToolCancellationController;
+/** Wrap a capability instance without depending on SDK-private subclasses. */
+export declare function wrapCapabilityToolsForTurnCancellation(capability: {
+    tools(): unknown[];
+    _session?: CommandCancellationSession;
+}, controller: TurnToolCancellationController): void;
+export {};

package/dist/sandbox/workspace-archive.d.ts

@@ -0,0 +1,39 @@
+import { type NativeSnapshotDescriptor, type NativeSnapshotRef, type WorkspaceArchiveDescriptor, type WorkspaceTreeFingerprint } from "@opengeni/contracts";
+export { WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION, decodeNativeSnapshotRef, parseWorkspaceArchiveDescriptor, type NativeSnapshotDescriptor, type NativeSnapshotProvider, type NativeSnapshotRef, type TarWorkspaceArchiveDescriptor, type WorkspaceArchiveDescriptor, type WorkspaceTreeFingerprint, } from "@opengeni/contracts";
+export type VerifiedWorkspaceArchive = {
+    bytes: Uint8Array;
+    base64: string;
+    descriptor: WorkspaceArchiveDescriptor;
+    kind: "tar" | "provider_snapshot";
+    nativeSnapshot?: NativeSnapshotRef;
+};
+export type WorkspaceArchiveIntegrityCode = "archive_metadata_missing" | "archive_metadata_invalid" | "archive_base64_invalid" | "archive_hash_mismatch" | "archive_hydration_failed" | "workspace_fingerprint_unavailable" | "workspace_changed_during_capture" | "workspace_fingerprint_mismatch" | "native_snapshot_reference_invalid" | "native_snapshot_fallback_unverified";
+export declare class WorkspaceArchiveIntegrityError extends Error {
+    readonly code: WorkspaceArchiveIntegrityCode;
+    readonly name = "WorkspaceArchiveIntegrityError";
+    readonly retryable: boolean;
+    constructor(code: WorkspaceArchiveIntegrityCode, message: string, options?: {
+        retryable?: boolean;
+    });
+}
+export declare function describeNativeSnapshotArchive(bytes: Uint8Array, capturedAtMs?: number): NativeSnapshotDescriptor | null;
+export declare function describeLegacyNativeSnapshotArchive(base64: unknown, observedAtMs?: number): {
+    archiveBase64: string;
+    descriptor: NativeSnapshotDescriptor;
+} | null;
+export declare function readVerifiedWorkspaceArchive(base64: unknown, metadata: unknown): VerifiedWorkspaceArchive | null;
+/** Hashes names, kinds, modes, symlink targets and all file bytes through one
+ * deterministic GNU tar stream. Hardlinks are dereferenced deliberately:
+ * content-preserving providers may restore them as independent files, and inode
+ * topology is not part of OpenGeni's workspace contract. Manifest paths that
+ * the provider's tar persistence deliberately excludes are pruned from both the
+ * digest and counters, so verification covers the exact persistent projection.
+ * Only the aggregate is returned; paths and file contents never enter logs or
+ * durable metadata. */
+export declare function fingerprintSandboxWorkspace(session: unknown): Promise<WorkspaceTreeFingerprint>;
+/** Provider-native persistence returns an opaque receipt and is accepted under
+ * the provider/artifact publication fence. A real tar capture is accepted only
+ * when the complete persistent tree is byte-identical immediately before and
+ * after serialization; a concurrent mutation makes that candidate unusable. */
+export declare function captureVerifiedWorkspaceArchive(session: unknown, capturedAtMs?: number): Promise<VerifiedWorkspaceArchive>;
+export declare function verifyRestoredWorkspace(session: unknown, descriptor: WorkspaceArchiveDescriptor): Promise<WorkspaceTreeFingerprint | null>;

package/dist/sandbox-computer.d.ts

@@ -0,0 +1,227 @@
+import { type Computer, type Tool } from "@openai/agents";
+import { Capability, type SandboxSessionLike } from "@openai/agents/sandbox";
+import { type DesktopInputRequest } from "@opengeni/agent-proto";
+type ComputerButton = "left" | "right" | "wheel" | "back" | "forward";
+export type SandboxComputerOptions = {
+    display?: string;
+    dimensions?: [number, number];
+    runAs?: string;
+    typeDelayMs?: number;
+    readOnly?: boolean;
+    screenshotTmpDir?: string;
+    screenshotWarmupBudgetMs?: number;
+    screenshotRetryDelayMs?: number;
+    /**
+     * One turn-scoped preparation hook, invoked by the first real computer action.
+     * The agent may advertise computer-use on every turn, but merely advertising the
+     * tool must not boot Xvfb/XFCE or start a recording. The runtime capability owns
+     * this hook and uses it to bring up :0 (and optionally notify the worker) only
+     * after the model actually chooses a computer tool.
+     */
+    prepare?: (session: SandboxSessionLike) => Promise<void>;
+};
+/** No exec/execCommand on the session, or the display is not up. */
+export declare class ComputerUnavailableError extends Error {
+    constructor(message: string);
+}
+/** The screenshot file read back SHORT of its on-box byte size — a chunk was truncated
+ *  by the provider's exec-output cap. This is deterministic, NOT a warm-up transient, so
+ *  it fails LOUD immediately with the byte counts (never a silent blank the model would
+ *  read as a real empty screen) and is not retried. */
+export declare class ScreenshotReadError extends Error {
+    constructor(message: string);
+}
+/** A write action attempted while readOnly. */
+export declare class ComputerReadOnlyError extends Error {
+    constructor();
+}
+/** A nonzero xdotool/scrot exit, OR a command that did not finish before the
+ *  yield window (F3 — "still running" is a failure, not a silent success). */
+export declare class ComputerActionError extends Error {
+    cmd: string;
+    exitCode: number;
+    stderr: string;
+    constructor(cmd: string, exitCode: number, stderr: string);
+}
+/**
+ * The Computer the agent drives. Every action issues ONE shell line through the
+ * externally-owned session (exec ?? execCommand, F1), prefixed with the display.
+ * screenshot() scrots to a /tmp file and reads the RAW bytes by running
+ * `base64 <path>` over the SAME command primitive and stripping the banner — NOT
+ * `session.readFile` (Modal's readFile path-validates against /workspace and rejects
+ * /tmp with "escapes the workspace root", which would yield an empty frame and 400
+ * the model). The base64-over-exec path is /tmp-readable and binary-safe.
+ */
+export declare class SandboxComputer implements Computer {
+    readonly environment: "ubuntu";
+    readonly dimensions: [number, number];
+    private session;
+    private readonly display;
+    private readonly runAs?;
+    private readonly typeDelayMs;
+    private readonly readOnly;
+    private readonly tmp;
+    private readonly screenshotWarmupBudgetMs;
+    private readonly screenshotRetryDelayMs;
+    private readonly prepare;
+    private prepared;
+    private preparation;
+    constructor(session: SandboxSessionLike, opts?: SandboxComputerOptions);
+    /** Rebind to a freshly resumed-by-id session after a box rollover / re-establish. */
+    rebind(session: SandboxSessionLike): void;
+    private prepareOnce;
+    private x;
+    private guardWrite;
+    private shq;
+    screenshot(): Promise<string>;
+    private readCmdRaw;
+    private readScreenshotBytes;
+    click(xp: number, yp: number, button: ComputerButton): Promise<void>;
+    doubleClick(xp: number, yp: number): Promise<void>;
+    move(xp: number, yp: number): Promise<void>;
+    scroll(xp: number, yp: number, sx: number, sy: number): Promise<void>;
+    type(text: string): Promise<void>;
+    keypress(keys: string[]): Promise<void>;
+    drag(path: [number, number][]): Promise<void>;
+    wait(): Promise<void>;
+}
+/** The structural slice of a self-hosted session the native computer drives — the
+ *  two control-plane ops added in session.ts. Kept structural (NOT an import of
+ *  `SelfhostedSession`) so this agent-loop file never hard-couples to the sandbox
+ *  leaf; the duck-typed `isNativeDesktopSession` probe (below) selects on it. */
+export type NativeDesktopSession = {
+    desktopInput(event: DesktopInputRequest["event"]): Promise<void>;
+    screenshot(): Promise<{
+        png: Uint8Array;
+        width: number;
+        height: number;
+        nativeWidth: number;
+        nativeHeight: number;
+    }>;
+};
+export type NativeDesktopComputerOptions = {
+    dimensions?: [number, number];
+    environment?: NonNullable<Computer["environment"]>;
+    readOnly?: boolean;
+    screenshotWarmupBudgetMs?: number;
+    screenshotRetryDelayMs?: number;
+};
+/**
+ * A `Computer` that drives a SELF-HOSTED machine's OWN desktop NATIVELY over the
+ * control plane (`desktopInput` inject + `screenshot` capture on the bound
+ * `SelfhostedSession`) instead of xdotool/scrot over `exec`. Consent + epoch are
+ * enforced AGENT-side, so an unconsented inject surfaces the session's mapped
+ * control error.
+ *
+ * screenshot() returns raw base64 with NO data-URL prefix — the EXACT contract of
+ * `SandboxComputer.screenshot`: the Agents SDK wraps it as
+ * `data:image/png;base64,${output}`, so an empty string would become
+ * `image_url: ''` and 400 the model turn. An empty PNG therefore THROWS
+ * `ComputerUnavailableError` (mirroring SandboxComputer's empty-guard) — the model
+ * never receives an empty image_url.
+ */
+export declare class NativeDesktopComputer implements Computer {
+    readonly environment: NonNullable<Computer["environment"]>;
+    readonly dimensions: [number, number];
+    private session;
+    private readonly readOnly;
+    private readonly screenshotWarmupBudgetMs;
+    private readonly screenshotRetryDelayMs;
+    private lastEncoded;
+    private lastNative;
+    constructor(session: NativeDesktopSession, opts?: NativeDesktopComputerOptions);
+    /** Rebind to a freshly resumed-by-id session after a box rollover / re-establish. */
+    rebind(session: NativeDesktopSession): void;
+    private guardWrite;
+    /** Scale a coordinate the model expressed in the MOST RECENT screenshot's
+     *  ENCODED pixel space back to NATIVE pixels. When the last frame was not
+     *  downscaled (encoded == native), or no screenshot has been taken yet, this is a
+     *  1:1 identity — the byte-identical current behavior. The agent then applies its
+     *  own platform mapping (macOS divides native pixels by the backing scale to reach
+     *  CGEvent points; Linux XTEST is 1:1) exactly as it did pre-downscale. */
+    private toNative;
+    private pointer;
+    screenshot(): Promise<string>;
+    click(x: number, y: number, button: ComputerButton): Promise<void>;
+    doubleClick(x: number, y: number): Promise<void>;
+    move(x: number, y: number): Promise<void>;
+    scroll(x: number, y: number, sx: number, sy: number): Promise<void>;
+    type(text: string): Promise<void>;
+    keypress(keys: string[]): Promise<void>;
+    drag(path: [number, number][]): Promise<void>;
+    wait(): Promise<void>;
+}
+/**
+ * Backend-aware SELECTION discriminator: a SELF-HOSTED session exposes the two
+ * native control-plane ops (`desktopInput` + `screenshot`); a MODAL session does
+ * not (it drives the desktop via xdotool/scrot over `exec`). Duck-typing on those
+ * two methods keeps this file from hard-importing `SelfhostedSession` (avoiding an
+ * agent-loop ↔ sandbox-leaf import coupling) and is future-proof: any backend that
+ * grows native inject/capture is picked up automatically.
+ */
+export declare function isNativeDesktopSession(session: SandboxSessionLike): session is SandboxSessionLike & NativeDesktopSession;
+/**
+ * The FUNCTION-transport computer tools for the codex / text backend, each routing
+ * to the SAME bound `Computer` the hosted `computer_use_preview` tool would drive.
+ * `computer_screenshot` hands the model the desktop two ways, selected by
+ * `imageFunctionResults`:
+ *   • false (chat-completions providers, the default) → the text-transport
+ *     `data:image/png;base64,…` URL (imageOutputFromBytes → renderImageForTextTransport,
+ *     the SDK's text `view_image` path) — those backends can't read structured image
+ *     tool results.
+ *   • true (the codex/ChatGPT backend) → the structured `{type:'image'}` tool output,
+ *     which agents-core normalizes into an `input_image` content item inside the
+ *     function_call_output — the codex /responses backend accepts and SEES it (a text
+ *     data-URL there is just unreadable text). See index.ts for why it's on there.
+ * Write tools return a concise confirmation; when read-only they return
+ * {@link COMPUTER_READ_ONLY_MESSAGE} instead of throwing, and any action error is
+ * returned as a string so a failed action never kills the turn. Exported so it can be
+ * unit-tested against a fake `Computer`.
+ */
+export declare function computerFunctionTools(computer: Computer, readOnly: boolean, needsApproval?: ComputerUseArgs["needsApproval"], imageFunctionResults?: boolean): Tool<unknown>[];
+/**
+ * EXPLICIT tool-transport selection, decided by the caller that knows the
+ * provider's true wire identity (the worker's model resolution — see agent-turn.ts),
+ * never inferred from the bound model instance's constructor name:
+ *   • "hosted"         → the single hosted `computer_use_preview` tool (Responses backends).
+ *   • "function-image" → the FUNCTION `computer_*` tools with screenshots delivered as a
+ *                        structured `{type:'image'}` output (the codex/ChatGPT backend,
+ *                        which rejects hosted tool types but SEES structured image results).
+ *   • "disabled"       → no computer tools. Providers without a proven visual image
+ *                        transport fail closed instead of receiving base64 as text.
+ *   • "function-text"  → deprecated fail-closed alias retained for source compatibility.
+ *   • omitted           → fail closed exactly like "disabled"; public runtime callers must
+ *                        prove the transport explicitly before computer tools are exposed.
+ */
+export type ComputerToolMode = "hosted" | "function-image" | "disabled" | "function-text";
+export type ComputerUseArgs = {
+    dimensions?: [number, number];
+    readOnly?: boolean;
+    display?: string;
+    needsApproval?: boolean | ((ctx: unknown, action: unknown) => boolean | Promise<boolean>);
+    /** @deprecated Use `toolMode: "function-image"`. Omitted transport now fails closed. */
+    imageFunctionResults?: boolean;
+    toolMode?: ComputerToolMode;
+    /** Called after the display is ready on the first actual computer action. */
+    onReady?: (session: SandboxSessionLike) => Promise<void>;
+};
+export declare function computerUse(args?: ComputerUseArgs): ComputerUseCapability;
+/**
+ * A `Capability` subclass merged into the agent's tool set by SandboxAgent
+ * (`tools = [...agent.tools, ...capability.tools()]`). `bind(session)` hands it
+ * the LIVE externally-owned session, so the agent's actions and the viewers'
+ * pixels are one display.
+ *
+ * `tools()` is transport-aware only through `ComputerUseArgs.toolMode`. The bound
+ * model instance is intentionally ignored: a constructor name cannot prove whether
+ * screenshots travel as hosted computer output or structured function images.
+ */
+export declare class ComputerUseCapability extends Capability {
+    private args;
+    readonly type = "computer-use";
+    constructor(args?: ComputerUseArgs);
+    tools(): Tool<unknown>[];
+    /** The single HOSTED `computer_use_preview` tool bound to `computer`. */
+    private hostedComputerTool;
+}
+export {};

package/dist/screenshot-error-card.d.ts

@@ -0,0 +1 @@
+export declare const SCREENSHOT_FAILURE_CARD_IMAGE_URL = "data:image/png;base64,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";

package/dist/skill-library.d.ts

@@ -6,7 +6,7 @@
  * Entries are immutable in the runtime. A new artifact gets a new version and
  * content hash; callers must not mutate the returned records.
  */
-type SkillLibraryEntry = Readonly<{
+export type SkillLibraryEntry = Readonly<{
     id: string;
     name: string;
     version: string;
@@ -30,32 +30,32 @@ type SkillLibraryEntry = Readonly<{
     }>;
     relativePath: string;
 }>;
-type SkillLibraryFile = Readonly<{
+export type SkillLibraryFile = Readonly<{
     path: string;
     content: string;
 }>;
-type SkillLibraryArtifact = Readonly<{
+export type SkillLibraryArtifact = Readonly<{
     files: readonly SkillLibraryFile[];
     /** SHA-256 over the complete canonical artifact manifest, not just SKILL.md. */
     contentSha256: string;
 }>;
-type SkillLibrarySkill = Readonly<{
+export type SkillLibrarySkill = Readonly<{
     name: string;
     description: string;
     files: readonly SkillLibraryFile[];
 }>;
 /** Return only entries whose reviewed artifact is present in this deployment. */
-declare function listSkillLibraryEntries(): readonly SkillLibraryEntry[];
+export declare function listSkillLibraryEntries(): readonly SkillLibraryEntry[];
 /** Return whether an id belongs to the immutable library, even if its artifact is unavailable. */
-declare function isSkillLibraryEntryId(id: string): boolean;
+export declare function isSkillLibraryEntryId(id: string): boolean;
 /** Resolve an exact immutable library entry by id and version. */
-declare function getSkillLibraryEntry(id: string, version?: string): SkillLibraryEntry | null;
+export declare function getSkillLibraryEntry(id: string, version?: string): SkillLibraryEntry | null;
 /**
  * Load a selected curated entry into the SDK's in-memory skill shape.
  * Selection is guidance-only: this function has no access to settings,
  * credentials, MCP declarations, or model-provider configuration.
  */
-declare function loadSkillLibrarySkill(id: string, version?: string): {
+export declare function loadSkillLibrarySkill(id: string, version?: string): {
     entry: SkillLibraryEntry;
     skill: SkillLibrarySkill;
 };
@@ -67,8 +67,6 @@ declare function loadSkillLibrarySkill(id: string, version?: string): {
  * a lossy UTF-8 string round-trip. Files are decoded only after the digest
  * input has been captured because the SDK skill surface is text-based.
  */
-declare function readSkillLibraryArtifact(root: string): SkillLibraryArtifact;
+export declare function readSkillLibraryArtifact(root: string): SkillLibraryArtifact;
 /** Verify a reviewed artifact against its immutable catalog digest. */
-declare function verifySkillLibraryArtifact(root: string, expectedSha256: string, entry?: Pick<SkillLibraryEntry, "id" | "version">): SkillLibraryArtifact;
-
-export { type SkillLibraryArtifact, type SkillLibraryEntry, type SkillLibraryFile, type SkillLibrarySkill, getSkillLibraryEntry, isSkillLibraryEntryId, listSkillLibraryEntries, loadSkillLibrarySkill, readSkillLibraryArtifact, verifySkillLibraryArtifact };
+export declare function verifySkillLibraryArtifact(root: string, expectedSha256: string, entry?: Pick<SkillLibraryEntry, "id" | "version">): SkillLibraryArtifact;