@solarisdk/core 0.3.1 → 0.4.0

package/README.md

@@ -16,6 +16,10 @@ npm install @solarisdk/sdk       # unified client + `solari` CLI
 
 `@solarisdk/core` is a dependency of all three and is installed automatically.
 
+## Requirements
+
+Node 18+ (or a browser with `WebSocket` and `fetch`). The type declarations need TypeScript 5.0 or newer; `await using` needs TypeScript 5.2+ and a runtime with `Symbol.asyncDispose` (Node 24, or a polyfill).
+
 ## License
 
 MIT

package/dist/chunked-download.d.ts

@@ -20,4 +20,3 @@ export declare function downloadAll(call: (method: string, params: Record<string
     maxBytes?: number;
 }): Promise<Uint8Array>;
 export {};
-//# sourceMappingURL=chunked-download.d.ts.map

package/dist/chunked-download.js

@@ -1,17 +1,7 @@
 import { SolariError } from "./errors.js";
 import { base64ToBytes } from "./transport.js";
-/** Default ceiling for one download: the whole file is held in memory. */
 export const DEFAULT_MAX_DOWNLOAD_BYTES = 2 * 1024 * 1024 * 1024;
 const MAX_CHUNKS = 20_000;
-/**
- * Download a whole in-guest file. `fs.download` returns at most one chunk (1 MiB by default) per call and says
- * where the next one starts, so a single call silently truncates anything bigger. This follows `nextOffset` until
- * `eof`. An agent that does not report `eof` sent the whole file in one reply, as before.
- *
- * Guards: the result is capped at `maxBytes` (default 2 GiB) and at a fixed chunk count, so an agent that never
- * says `eof` cannot loop forever or exhaust memory; a `nextOffset` that is not exactly where the chunk ended would
- * silently skip or repeat bytes, so it is an error; a file whose reported size changes mid-read is an error.
- */
 export async function downloadAll(call, path, opts = {}) {
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_DOWNLOAD_BYTES;
     const fail = (why) => new SolariError(`fs.download ${JSON.stringify(path)}: ${why}`);
@@ -52,4 +42,3 @@ export async function downloadAll(call, path, opts = {}) {
     }
     return out;
 }
-//# sourceMappingURL=chunked-download.js.map

package/dist/desktop.d.ts

@@ -110,4 +110,3 @@ export declare class Desktop extends SessionHandle {
         stop: () => Promise<RecordStopResult>;
     };
 }
-//# sourceMappingURL=desktop.d.ts.map

package/dist/desktop.js

@@ -1,22 +1,5 @@
-// `Desktop` — a handle to one live GUI session. Extends the shared
-// {@link SessionHandle} (commands, pty, runCode, files, metrics, snapshot,
-// revert, pause/resume, setTimeout, env, volumes, kill) and adds the
-// computer-use GUI surface (CONTRACTS §4 + CONTRACTS-V2 §4): screenshot,
-// mouse.*, keyboard.*, display.*, clipboard.*, open, stream.*, record.*.
-//
-// Back-compat: the v1 `DesktopClient` constructs `new Desktop(session, config)`
-// where `config.onPause(sessionId)` calls `POST /desktops/:id/pause`. That path
-// is preserved; the older convenience methods (`exec`, `execStream`, `health`,
-// `process`, `ports`, `pkg`) are kept too.
 import { SessionHandle } from "./handle.js";
 import { base64ToBytes } from "./transport.js";
-/**
- * Map a named {@link MouseButton} to the X11/xdotool button code the guest
- * agent expects (`mouseParams.button` is an `int`): left=1, middle=2, right=3.
- * `undefined` is passed through so the guest applies its own default (left).
- * Without this the wire would carry a raw string and the guest's JSON decode
- * fails with `cannot unmarshal string into ... button of type int`.
- */
 function buttonToCode(button) {
     if (button === undefined)
         return undefined;
@@ -29,22 +12,13 @@ function buttonToCode(button) {
             return 3;
     }
 }
-/** A live desktop session. Construct via {@link DesktopClient}. */
 export class Desktop extends SessionHandle {
     streamUrl;
-    /**
-     * Presigned playback URL for the session recording — set when the session was
-     * created with `record: true`, `undefined` otherwise. The guest uploads the
-     * mp4 on `record.stop()`, so the URL only resolves once a recording has been
-     * started and stopped.
-     */
     recordingUrl;
-    /** The session id (alias of {@link SessionHandle.id}; back-compat). */
     get sessionId() {
         return this.id;
     }
     constructor(session, config = {}) {
-        // Fold the legacy onPause shim into the unified hooks.pause.
         const hooks = { ...(config.hooks ?? {}) };
         if (config.onPause && !hooks.pause) {
             const onPause = config.onPause;
@@ -57,16 +31,12 @@ export class Desktop extends SessionHandle {
         this.streamUrl = session.streamUrl;
         this.recordingUrl = session.recordingUrl;
     }
-    // GUI RPCs go over the shared control channel via the protected `rpc` hook.
     guiCall(method, params) {
         return this.rpc(method, params);
     }
-    // --- readiness ------------------------------------------------------------
-    /** `health` — readiness probe (display + VNC + agent). */
     health() {
         return this.guiCall("health", {});
     }
-    // --- exec (v1 convenience; prefer `commands.run`) -------------------------
     exec(cmd, opts = {}) {
         return this.guiCall("exec", {
             cmd,
@@ -82,7 +52,6 @@ export class Desktop extends SessionHandle {
             onChunk({ stream: c.stream, text: new TextDecoder().decode(bytes), bytes });
         });
     }
-    // --- fs (v1 alias kept; `files` is the canonical surface) -----------------
     fs = {
         read: (path) => this.files.read(path),
         readText: (path) => this.files.readText(path),
@@ -92,7 +61,6 @@ export class Desktop extends SessionHandle {
         remove: (path, recursive = false) => this.files.remove(path, recursive),
         mkdir: (path) => this.files.mkdir(path),
     };
-    // --- mouse ----------------------------------------------------------------
     mouse = {
         move: (x, y, opts = {}) => this.mouseCall(x, y, "move", undefined, opts.humanize),
         click: (x, y, opts = {}) => this.mouseCall(x, y, "click", opts.button, opts.humanize),
@@ -115,11 +83,9 @@ export class Desktop extends SessionHandle {
             humanize,
         }).then(() => undefined);
     }
-    // --- keyboard -------------------------------------------------------------
     keyboard = {
         type: (text) => this.keyCall({ text, action: "press" }),
         press: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "press" }),
-        /** Press a chord (alias of `press` for an array, e.g. `hotkey("ctrl","c")`). */
         hotkey: (...keys) => this.keyCall({ keys, action: "press" }),
         down: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "down" }),
         up: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "up" }),
@@ -127,7 +93,6 @@ export class Desktop extends SessionHandle {
     keyCall(params) {
         return this.guiCall("input.key", params).then(() => undefined);
     }
-    // --- screenshot -----------------------------------------------------------
     async screenshot(opts = {}) {
         const r = await this.guiCall("screenshot", {
             format: opts.format ?? "png",
@@ -135,15 +100,11 @@ export class Desktop extends SessionHandle {
         });
         return base64ToBytes(r.base64);
     }
-    // --- display --------------------------------------------------------------
     display = {
         set: (w, h) => this.guiCall("display.set", { w, h }).then(() => undefined),
-        /** Current display size. */
         size: () => this.guiCall("display.size", {}),
-        /** Current cursor position. */
         cursor: () => this.guiCall("display.cursor", {}),
     };
-    // --- clipboard ------------------------------------------------------------
     clipboard = {
         get: async () => {
             const r = await this.guiCall("clipboard.get", {});
@@ -151,26 +112,17 @@ export class Desktop extends SessionHandle {
         },
         set: (text) => this.guiCall("clipboard.set", { text }).then(() => undefined),
     };
-    // --- open an app ----------------------------------------------------------
-    /** Launch a GUI app by name (`app.open`); returns its pid. */
     async open(name, args) {
         const r = await this.guiCall("app.open", { name, args });
         return r.pid;
     }
-    // --- live stream ----------------------------------------------------------
     stream = {
-        /** Start/obtain the live VNC stream; returns the embeddable URL + token. */
         start: async () => {
-            // The stream URL is minted at create time; expose it (+ any token) here so
-            // callers have a single `stream.start()` entry point.
             return { streamUrl: this.streamUrl };
         },
-        /** Stop the live stream (best-effort; the channel stays up). */
         stop: async () => {
-            /* the RFB stream is a separate socket the caller owns; nothing to tear down here */
         },
     };
-    // --- process (v1 convenience) ---------------------------------------------
     process = {
         list: async () => {
             const r = await this.guiCall("process.list", {});
@@ -187,21 +139,17 @@ export class Desktop extends SessionHandle {
         },
         signal: (pid, signal) => this.guiCall("process.signal", { pid, signal }).then(() => undefined),
     };
-    // --- ports (v1 convenience) -----------------------------------------------
     ports = {
         list: async () => {
             const r = await this.guiCall("ports.list", {});
             return r.ports;
         },
     };
-    // --- packages -------------------------------------------------------------
     pkg = {
         install: (manager, packages) => this.guiCall("pkg.install", { manager, packages }),
     };
-    // --- recording ------------------------------------------------------------
     record = {
         start: (opts = {}) => this.guiCall("record.start", opts),
         stop: () => this.guiCall("record.stop", {}),
     };
 }
-//# sourceMappingURL=desktop.js.map

package/dist/errors.d.ts

@@ -8,8 +8,18 @@ export declare class GatewayError extends SolariError {
     readonly status: number;
     readonly code?: string;
     readonly body?: GatewayErrorBody;
+    /** The gateway's hint that retrying may help (`body.retryable`), on every gateway error. */
+    readonly retryable?: boolean;
     constructor(status: number, message: string, body?: GatewayErrorBody);
 }
+/** `404` — the sandbox, desktop, snapshot, template or volume does not exist (or is not yours). */
+export declare class NotFoundError extends GatewayError {
+    constructor(message?: string, body?: GatewayErrorBody);
+}
+/** `400` — the request was refused as invalid (a bad field, a limit exceeded); `body.code` / `message` say which. */
+export declare class ValidationError extends GatewayError {
+    constructor(message?: string, body?: GatewayErrorBody);
+}
 /** `401` — the API key was missing, malformed, or rejected. */
 export declare class AuthError extends GatewayError {
     constructor(message?: string, body?: GatewayErrorBody);
@@ -71,4 +81,3 @@ export declare class ConnectionError extends SolariError {
  * Falls back to a generic {@link GatewayError} for unrecognized statuses.
  */
 export declare function mapGatewayError(status: number, body: GatewayErrorBody | undefined): GatewayError;
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -1,76 +1,59 @@
-// Typed errors. Gateway HTTP status codes (§1) and control-channel RPC
-// failures (§4) are mapped onto these so callers can branch on `instanceof`.
-/** Base class for every error thrown by the SDK. */
 export class SolariError extends Error {
     constructor(message) {
         super(message);
         this.name = new.target.name;
     }
 }
-/** Any non-2xx response from the gateway that isn't otherwise specialized. */
 export class GatewayError extends SolariError {
     status;
     code;
     body;
+    retryable;
     constructor(status, message, body) {
         super(message);
         this.status = status;
         this.code = body?.code;
         this.body = body;
+        this.retryable = body?.retryable;
+    }
+}
+export class NotFoundError extends GatewayError {
+    constructor(message = "Not found", body) {
+        super(404, message, body);
+    }
+}
+export class ValidationError extends GatewayError {
+    constructor(message = "Invalid request", body) {
+        super(400, message, body);
     }
 }
-/** `401` — the API key was missing, malformed, or rejected. */
 export class AuthError extends GatewayError {
     constructor(message = "Invalid or missing API key", body) {
         super(401, message, body);
     }
 }
-/**
- * The plan doesn't allow this: `402` (`FeatureRequiresPlan`, `InsufficientCredit`) or `403 {code:"NotEntitled"}` (the plan
- * does not include sandboxes/desktops). `status` is the status the gateway really sent.
- */
 export class PlanError extends GatewayError {
     constructor(message = "This feature requires a different plan", body, status = 402) {
         super(status, message, body);
     }
 }
-/**
- * `429 {code:"ConcurrencyLimitExceeded"}` — the org is at its cap of live sessions. Other 429s (for example
- * `TooManyExecutions`, a per-sandbox limit that can be retried) are plain {@link GatewayError}s with the gateway's `code`.
- */
 export class ConcurrencyLimitError extends GatewayError {
     constructor(message = "Concurrency limit exceeded", body) {
         super(429, message, body);
     }
 }
-/**
- * `503 {code:"NoCapacity"|"StartTimeout"}` (or a `503` with no code) — no desktop host currently available to serve the
- * request. Other 503s (`SandboxUnavailable`, `StoreUnavailable`, `AdmissionUnavailable`, `DependencyUnavailable`) are plain
- * {@link GatewayError}s: the sandbox, store or admission service is unavailable, which is not a capacity problem.
- */
 export class NoCapacityError extends GatewayError {
     constructor(message = "No desktop host available", body) {
         super(503, message, body);
     }
 }
-/**
- * `409 {code:"NotStopped"}` or `409 {code:"StartInProgress"}` from
- * `POST /sandboxes/:id/start`. `NotStopped` means the sandbox is in another
- * state (use `resume()` for a paused one); `StartInProgress` means a start is
- * already under way, so poll until the sandbox is running. Not retryable as-is.
- * Host refusals (`StoppedDiskMissing`, `StoppedDiskUnsafe`, `GoldenMismatch`, `DiskPlatformMismatch`,
- * `DiskShaMismatch`, `DiskExceedsSpec`, `DiskOwnerMismatch`) and `HostCapabilityMissing` (host pool not armed
- * for start; `body.missingCapabilities`) stay plain {@link GatewayError}s with the host's `code`.
- */
 export class SandboxNotStoppedError extends GatewayError {
-    /** The sandbox's current state as reported by the gateway, when present. */
     state;
     constructor(message = "Sandbox is not stopped", body) {
         super(409, message, body);
         this.state = body?.state;
     }
 }
-/** A computer-use RPC returned `{ok:false}`. */
 export class ActionError extends SolariError {
     method;
     code;
@@ -80,7 +63,6 @@ export class ActionError extends SolariError {
         this.code = code;
     }
 }
-/** An RPC did not receive a reply within the per-call timeout. */
 export class TimeoutError extends SolariError {
     method;
     timeoutMs;
@@ -90,28 +72,24 @@ export class TimeoutError extends SolariError {
         this.timeoutMs = timeoutMs;
     }
 }
-/** The control WebSocket is not open (never connected, or closed). */
 export class ConnectionError extends SolariError {
     constructor(message = "Control channel is not connected") {
         super(message);
     }
 }
-/**
- * Map a gateway HTTP response onto the appropriate typed error.
- * Falls back to a generic {@link GatewayError} for unrecognized statuses.
- */
 export function mapGatewayError(status, body) {
     const msg = body?.message ?? body?.error ?? body?.code;
-    // `code` is the discriminator (sdk/PROTOCOL.md section 4); the status alone is not enough because one status carries
-    // several meanings. A response with no code keeps the type its status has always had.
     const code = body?.code;
     switch (status) {
+        case 400:
+            return new ValidationError(msg, body);
+        case 404:
+            return new NotFoundError(msg, body);
         case 401:
             return new AuthError(msg, body);
         case 402:
             return new PlanError(msg, body);
         case 403:
-            // The gateway's only JSON 403 is NotEntitled (the plan does not include sandboxes/desktops).
             if (code === "NotEntitled")
                 return new PlanError(msg, body, 403);
             return new GatewayError(403, msg ?? "Forbidden", body);
@@ -132,4 +110,3 @@ export function mapGatewayError(status, body) {
             return new GatewayError(status, msg ?? `Gateway request failed with status ${status}`, body);
     }
 }
-//# sourceMappingURL=errors.js.map

package/dist/handle.d.ts

@@ -54,6 +54,8 @@ export interface SessionHooks {
 export interface SessionConfig extends ControlChannelConfig {
     hooks?: SessionHooks;
 }
+/** The longest `timeoutMs` the gateway accepts for a command (600 000 ms), and the default for `commands.run`. */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 600000;
 /** Cap on PTY output held before the first onData() subscriber (bytes, total). */
 export declare const PTY_EARLY_BUFFER_MAX: number;
 export declare class SessionHandle {
@@ -66,6 +68,8 @@ export declare class SessionHandle {
     /** Set by {@link kill} so {@link close} doesn't warn about a machine we
      *  have just released. */
     private killed;
+    /** Key of this handle in the exit-reminder list (see `unreleased`). */
+    private readonly releaseToken;
     constructor(id: string, controlUrl: string, expiresAt: string, config?: SessionConfig);
     /** Whether the control channel is open. */
     get connected(): boolean;
@@ -257,6 +261,9 @@ export declare class SessionHandle {
      * Resolve a public preview URL for an in-guest port (e.g. a dev server on
      * `:3000`). Returns the routable `https://` URL and, when the gateway signs
      * one, an access `token`.
+     *
+     * The URL can carry that token as `?slr_token=…`: it is a credential for the port, so don't print or log the whole
+     * URL and avoid opening it in a shared browser profile, where it lands in history.
      */
     previewUrl(port: number): Promise<{
         url: string;
@@ -268,4 +275,3 @@ export declare class SessionHandle {
 /** Local helper type for `createCodeContext` to avoid a hard import cycle. */
 type CodeLanguageArg = "python" | "javascript" | "typescript" | "bash" | "r";
 export {};
-//# sourceMappingURL=handle.d.ts.map