@solarisdk/core 0.3.1 → 0.4.0

package/dist/http.d.ts

@@ -17,6 +17,8 @@ export interface HttpRequestOptions {
 }
 /** A fresh idempotency key (UUID where available). */
 export declare function newIdempotencyKey(): string;
+/** The production gateway. Every client defaults to it when no `baseUrl` is given. */
+export declare const DEFAULT_BASE_URL = "https://api.getsolari.com";
 export declare class HttpTransport {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -32,4 +34,3 @@ export declare class HttpTransport {
     request<T>(method: string, path: string, body?: unknown, opts?: HttpRequestOptions): Promise<T>;
     private backoffMs;
 }
-//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -1,19 +1,10 @@
-// Shared HTTP transport for the SDK ⇆ Gateway REST API. Both `DesktopClient`
-// and `SandboxClient` delegate here, so there is ONE place that owns auth
-// headers, error mapping, retries/backoff, idempotency keys, and timeouts.
-//
-// Retry policy: idempotent requests (GET, DELETE, or any request carrying an
-// Idempotency-Key) are retried on network errors, HTTP 5xx, 429, and bodies
-// flagged `retryable`, with exponential backoff + jitter. Non-idempotent writes
-// are never silently retried (could double-create) — pass an idempotencyKey to
-// opt a create into safe retries.
 import { ConnectionError, mapGatewayError, SolariError } from "./errors.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** A fresh idempotency key (UUID where available). */
 export function newIdempotencyKey() {
     const c = globalThis.crypto;
     return c?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2, 12)}`;
 }
+export const DEFAULT_BASE_URL = "https://api.getsolari.com";
 export class HttpTransport {
     apiKey;
     baseUrl;
@@ -37,11 +28,9 @@ export class HttpTransport {
         this.requestTimeoutMs = o.requestTimeoutMs ?? 300_000;
         this.retryDelayMs = o.retryDelayMs;
     }
-    /** `Authorization` header for handles + WS upgrades. */
     authHeaders() {
         return { Authorization: `Bearer ${this.apiKey}` };
     }
-    /** ws:// (or wss://) origin derived from the gateway base URL. */
     wsOrigin() {
         return this.baseUrl.replace(/^http/, "ws");
     }
@@ -81,38 +70,6 @@ export class HttpTransport {
                 catch {
                     errBody = undefined;
                 }
-                // 🚨 AN ALLOWLIST, NOT `>= 500`. A 5xx IS NOT AUTOMATICALLY TRANSIENT.
-                //
-                // `status >= 500` retried PERMANENT refusals. The gateway has seven 501
-                // sites — every /volumes route, refusing because volumes cannot work on
-                // GCP at all — and this retried each one five times with backoff before
-                // the caller saw anything. Measured on prod 2026-09-22, the backoff curve
-                // is visible in the LB logs:
-                //
-                //     04:47:11  GET /volumes  501
-                //     04:47:35  (+24s)        501
-                //     04:48:22  (+47s)        501
-                //
-                // Intervals roughly double, which is what distinguishes a retry loop from
-                // a polling client: a poll is evenly spaced. So this was real traffic
-                // hammering a "not implemented" on a customer's behalf.
-                //
-                // 🪤 507 IS IN THE LIST DELIBERATELY, AND NOT VIA THE HINT. The gateway's
-                // InsufficientCapacity 507 does carry `retryable: true`, so the hint alone
-                // would cover it today — but that makes this SDK's correctness depend on
-                // which gateway build the caller is talking to. A rollback, or an older
-                // self-hosted gateway, would silently stop retrying a refusal that IS
-                // transient by construction (every admissible size fits an empty host;
-                // the 507 reports the host's residual budget at that instant). Naming it
-                // here removes the deploy-order dependency entirely.
-                //
-                // 500 is excluded on purpose: an unhandled server error is not
-                // known-transient, and the gateway has exactly one such site
-                // ("Internal error"). 429 stays excluded as before — that is
-                // ConcurrencyLimitError, the org at its cap, and retrying cannot help.
-                //
-                // The `retryable` hint stays, and is the ONLY route by which a non-5xx
-                // can be retried (e.g. a 404 ReplayPending on the browser gateway).
                 const RETRYABLE_STATUSES = new Set([502, 503, 504, 507]);
                 const retryable = RETRYABLE_STATUSES.has(res.status) || errBody?.retryable === true;
                 if (idempotent && retryable && attempt < this.maxRetries) {
@@ -121,7 +78,6 @@ export class HttpTransport {
                 }
                 throw mapGatewayError(res.status, errBody);
             }
-            // DELETE / empty bodies have no JSON.
             const text = await res.text();
             if (text.length === 0)
                 return undefined;
@@ -131,10 +87,6 @@ export class HttpTransport {
     backoffMs(attempt) {
         if (this.retryDelayMs !== undefined)
             return this.retryDelayMs;
-        // Base 150ms (was 1000): a create bounced by a transient host no_capacity
-        // during a burst should re-pick a different host in ~150ms, not idle a full
-        // second before its first retry. 150·2^n → 150, 300, 600, 1200, 2400 (cap 8s).
         return Math.min(150 * 2 ** attempt, 8000) + Math.floor(Math.random() * 250);
     }
 }
-//# sourceMappingURL=http.js.map

package/dist/ids.d.ts

@@ -4,4 +4,3 @@
  * never carries a whole one: the first 8 characters identify it well enough.
  */
 export declare function shortId(id: string): string;
-//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -1,9 +1,3 @@
-/**
- * Shorten a sandbox/desktop session id for logs and warnings. Session ids are
- * capability tokens (anyone holding one can drive the machine), so SDK output
- * never carries a whole one: the first 8 characters identify it well enough.
- */
 export function shortId(id) {
     return id.length > 8 ? `${id.slice(0, 8)}…` : id;
 }
-//# sourceMappingURL=ids.js.map

package/dist/image.d.ts

@@ -95,4 +95,3 @@ export declare class Image {
     /** Compile to the build-context inputs. Pure + offline. */
     compile(): CompiledImage;
 }
-//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -1,26 +1,6 @@
-// Declarative Image builder (Daytona-style). A fluent chain that compiles to
-// the inputs our golden pipeline (`build-rootfs.sh`) already consumes per
-// template: an apt `packages` list, a `Dockerfile.fragment`, and local files
-// staged into `template-files/` (which the base Dockerfile COPYs to `/`).
-//
-//   const img = Image.base("ubuntu:22.04")
-//     .aptInstall(["ffmpeg"])
-//     .pipInstall(["pandas", "matplotlib"])
-//     .runCommands("curl -fsSL https://example.com/i.sh | sh")
-//     .addLocalDir("./assets", "/opt/assets")
-//     .env({ TZ: "UTC" })
-//     .workdir("/work");
-//   const tpl = await pt.templates.build(img, { name: "data-sci", kind: "sandbox" });
-//
-// `.compile()` emits a structured `steps[]` (typed ops the snapshot
-// exec-orchestrator runs directly) plus a byte-identical `Dockerfile.fragment`
-// (the Docker rebuild path). NOTE: `.compile()` is pure + offline (unit-tested);
-// actually BUILDING a template (pt.templates.build) requires the gateway
-// `/templates` backend — Phases 2-6 in docs/TEMPLATE-BUILD-PIPELINE.md.
 function envValue(v) {
     return /\s/.test(v) ? JSON.stringify(v) : v;
 }
-/** Render one structured step to its Dockerfile line (approach B). */
 function renderDockerfile(step) {
     switch (step.op) {
         case "pip":
@@ -46,83 +26,64 @@ export class Image {
     _steps = [];
     _localFiles = [];
     constructor() { }
-    /** Start from a base OS image (e.g. `"ubuntu:22.04"`). */
     static base(image) {
         const i = new Image();
         i._base = image;
         return i;
     }
-    /** Start from an existing Solari template (e.g. `"workstation"`). */
     static fromTemplate(name) {
         const i = new Image();
         i._fromTemplate = name;
         return i;
     }
-    /**
-     * Start from an OCI image (`"python:3.12-alpine"`, `"ghcr.io/org/app:1.2"`). The image's own
-     * filesystem becomes the sandbox's root: exec and file paths are relative to it. Public registries
-     * only (docker.io, ghcr.io, public.ecr.aws, gcr.io, quay.io); sandbox templates only; install
-     * packages with `runCommands` (not `aptInstall`).
-     */
     static fromImage(ref) {
         const i = new Image();
         i._fromImage = ref;
         return i;
     }
-    /** Set the session kind this image is for (`"sandbox"` headless or `"desktop"` GUI). */
     kind(k) {
         this._kind = k;
         return this;
     }
-    /** apt packages installed by the pipeline's apt step. */
     aptInstall(pkgs) {
         this._packages.push(...pkgs);
         return this;
     }
-    /** `RUN pip3 install …`. */
     pipInstall(pkgs) {
         if (pkgs.length)
             this._steps.push({ op: "pip", packages: [...pkgs] });
         return this;
     }
-    /** One `RUN` per command. */
     runCommands(...cmds) {
         for (const c of cmds)
             this._steps.push({ op: "run", command: c });
         return this;
     }
-    /** `ENV` vars. */
     env(vars) {
         for (const [k, v] of Object.entries(vars))
             this._steps.push({ op: "env", key: k, value: v });
         return this;
     }
-    /** `WORKDIR`. */
     workdir(dir) {
         this._steps.push({ op: "workdir", dir });
         return this;
     }
-    /** `ENTRYPOINT` (exec form). */
     entrypoint(cmd) {
         this._steps.push({ op: "entrypoint", command: [...cmd] });
         return this;
     }
-    /** `CMD` (exec form). */
     cmd(cmd) {
         this._steps.push({ op: "cmd", command: [...cmd] });
         return this;
     }
-    /** Stage a local file into the guest at `dest` (copied via `template-files/`). */
     addLocalFile(src, dest) {
         this._localFiles.push({ src, dest });
         return this;
     }
-    /** Stage a local directory into the guest at `dest`. */
     addLocalDir(src, dest) {
         this._localFiles.push({ src, dest });
         return this;
     }
-    /** Compile to the build-context inputs. Pure + offline. */
     compile() {
         return {
             kind: this._kind,
@@ -136,4 +97,3 @@ export class Image {
         };
     }
 }
-//# sourceMappingURL=image.js.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { SessionHandle } from "./handle.js";
+export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
 export type { SessionConfig, SessionHooks } from "./handle.js";
 export { Desktop } from "./desktop.js";
@@ -10,7 +10,6 @@ export { TemplateClient } from "./template-client.js";
 export type { TemplateClientOptions } from "./template-client.js";
 export { VolumeClient } from "./volume-client.js";
 export type { VolumeClientOptions } from "./volume-client.js";
-export { HttpTransport, newIdempotencyKey } from "./http.js";
-export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, } from "./errors.js";
+export { DEFAULT_BASE_URL, HttpTransport, newIdempotencyKey } from "./http.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";
 export type * from "./types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,11 +1,9 @@
-// @solarisdk/core — shared runtime for @solarisdk/desktop and @solarisdk/sandbox.
-export { SessionHandle } from "./handle.js";
+export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
 export { Desktop } from "./desktop.js";
 export { Sandbox } from "./sandbox.js";
 export { Image } from "./image.js";
 export { TemplateClient } from "./template-client.js";
 export { VolumeClient } from "./volume-client.js";
-export { HttpTransport, newIdempotencyKey } from "./http.js";
-export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, } from "./errors.js";
-//# sourceMappingURL=index.js.map
+export { DEFAULT_BASE_URL, HttpTransport, newIdempotencyKey } from "./http.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";

package/dist/sandbox.d.ts

@@ -5,4 +5,3 @@ export declare class Sandbox extends SessionHandle {
     get sandboxId(): string;
     constructor(session: CreateSandboxResponse, config?: SessionConfig);
 }
-//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -1,10 +1,5 @@
-// `Sandbox` — a handle to one live headless session. All of its surface lives
-// on the shared {@link SessionHandle} base (commands, pty, runCode, files,
-// volumes, metrics, snapshot, revert, pause/resume, setTimeout, env,
-// kill). Construct via {@link SandboxClient}.
 import { SessionHandle } from "./handle.js";
 export class Sandbox extends SessionHandle {
-    /** The sandbox id (alias of {@link SessionHandle.id}). */
     get sandboxId() {
         return this.id;
     }
@@ -12,4 +7,3 @@ export class Sandbox extends SessionHandle {
         super(session.sandboxId, session.controlUrl, session.expiresAt, config);
     }
 }
-//# sourceMappingURL=sandbox.js.map

package/dist/template-client.d.ts

@@ -32,4 +32,3 @@ export declare class TemplateClient {
      */
     waitUntilReady(templateId: string, opts: BuildTemplateOptions): Promise<TemplateView>;
 }
-//# sourceMappingURL=template-client.d.ts.map

package/dist/template-client.js

@@ -1,16 +1,7 @@
-// `TemplateClient` — talks the SDK ⇆ Gateway `/templates` HTTP API and turns a
-// declarative {@link Image} into a reusable template a session can launch:
-//
-//   const img = Image.base("ubuntu:22.04").aptInstall(["ffmpeg"]).kind("sandbox");
-//   const tpl = await pt.templates.build(img, { name: "media" });
-//   const sbx = await pt.sandboxes.create({ template: tpl.templateId });
-//
-// `build()` POSTs the compiled recipe (async build on the gateway) and then
-// polls to completion. See docs/TEMPLATE-BUILD-PIPELINE.md.
 import { SolariError } from "./errors.js";
 import { HttpTransport, newIdempotencyKey } from "./http.js";
 import { Image } from "./image.js";
-const DEFAULT_BUILD_TIMEOUT_MS = 900_000; // 15 min
+const DEFAULT_BUILD_TIMEOUT_MS = 900_000;
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class TemplateClient {
@@ -28,19 +19,13 @@ export class TemplateClient {
             ...(options.fetch ? { fetch: options.fetch } : {}),
         });
     }
-    /**
-     * Build a custom template from an {@link Image} (or a pre-{@link CompiledImage}).
-     * Kicks off the async gateway build then waits until it is `ready` (or throws
-     * on `failed`/timeout). Returns the final template view.
-     */
     async build(image, opts) {
         if (!opts?.name)
             throw new SolariError("templates.build requires a name");
         const { buildId, templateId } = await this.buildRaw(image, opts);
-        void buildId; // reserved for future log-stream correlation
+        void buildId;
         return this.waitUntilReady(templateId, opts);
     }
-    /** Start a build without waiting (`POST /templates`). Returns ids immediately. */
     async buildRaw(image, opts) {
         const compiled = image instanceof Image ? image.compile() : image;
         const body = {
@@ -54,28 +39,20 @@ export class TemplateClient {
             idempotencyKey: newIdempotencyKey(),
         });
     }
-    /** List templates — built-ins + this org's custom templates (`GET /templates`). */
     async list() {
         const res = await this.http.request("GET", "/templates");
         return res.templates;
     }
-    /** Get one template's status/metadata (`GET /templates/:id`). */
     get(templateId) {
         return this.http.request("GET", `/templates/${encodeURIComponent(templateId)}`);
     }
-    /** Delete a custom template (`DELETE /templates/:id`; refused while live sessions depend on it). */
     async delete(templateId) {
         await this.http.request("DELETE", `/templates/${encodeURIComponent(templateId)}`);
     }
-    /**
-     * Poll `GET /templates/:id` until it leaves `building`. Resolves on `ready`,
-     * throws on `failed`, throws on timeout. `onLog` is invoked best-effort as the
-     * gateway exposes build logs (a no-op until the log stream ships).
-     */
     async waitUntilReady(templateId, opts) {
         const timeoutMs = opts.timeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS;
         const pollMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        const deadline = timeoutMs; // relative budget; decremented per poll (clock-free for tests)
+        const deadline = timeoutMs;
         let waited = 0;
         for (;;) {
             const view = await this.get(templateId);
@@ -92,4 +69,3 @@ export class TemplateClient {
         }
     }
 }
-//# sourceMappingURL=template-client.js.map

package/dist/transport.d.ts

@@ -23,6 +23,12 @@ export interface ControlChannelConfig {
     callTimeoutMs?: number;
     /** Extra headers for the control WS upgrade (Node only). */
     headers?: Record<string, string>;
+    /**
+     * Close the WebSocket after this many milliseconds with nothing using it (no call in flight, no running command,
+     * no open PTY); the next call reopens it by itself. Lets a script that ends without `kill()`/`close()` exit instead of
+     * hanging on the socket. Default 3000; `0` keeps the connection open for good.
+     */
+    idleCloseMs?: number;
 }
 /** The shared control-WS transport. Construct one per live session handle. */
 export declare class ControlChannel {
@@ -55,6 +61,8 @@ export declare class ControlChannel {
      */
     private readonly streamClosers;
     private readonly callTimeoutMs;
+    private readonly idleCloseMs;
+    private idleTimer;
     private readonly headers;
     private closed;
     constructor(controlUrl: string, config?: ControlChannelConfig);
@@ -96,7 +104,7 @@ export declare class ControlChannel {
     private onMessage;
     private dispatch;
     private onClose;
-    /** Allocate the next opaque request id (string, per CONTRACTS §4). */
+    /** Allocate the next opaque request id (a string). */
     newId(): string;
     /**
      * Send one JSON-RPC call and await its correlated reply. `onStream` (v1)
@@ -114,4 +122,3 @@ export declare class ControlChannel {
 export declare function base64ToBytes(b64: string): Uint8Array;
 /** Bytes → base64, working in both Node and the browser. */
 export declare function bytesToBase64(bytes: Uint8Array): string;
-//# sourceMappingURL=transport.d.ts.map