@solarisdk/core 0.4.1 → 0.4.3

package/README.md

@@ -18,7 +18,7 @@ npm install @solarisdk/sdk       # unified client + `solari` CLI
 
 ## 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).
+Node 18+ (or a browser with `WebSocket` and `fetch`). The type declarations need TypeScript 5.0 or newer; `await using` works in compiled TypeScript 5.2+ on Node 18.18+ (which provide `Symbol.asyncDispose`); running the syntax uncompiled needs Node 24.
 
 ## License
 

package/dist/desktop.js

@@ -46,11 +46,19 @@ export class Desktop extends SessionHandle {
             stream: opts.stream,
         });
     }
-    execStream(cmd, onChunk, opts = {}) {
-        return this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
+    async execStream(cmd, onChunk, opts = {}) {
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const result = await this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
             const bytes = c.data ? base64ToBytes(c.data) : new Uint8Array();
-            onChunk({ stream: c.stream, text: new TextDecoder().decode(bytes), bytes });
+            const dec = decoders[c.stream] ?? decoders.stdout;
+            onChunk({ stream: c.stream, text: dec.decode(bytes, { stream: true }), bytes });
         });
+        for (const stream of ["stdout", "stderr"]) {
+            const rest = decoders[stream].decode();
+            if (rest)
+                onChunk({ stream, text: rest, bytes: new Uint8Array() });
+        }
+        return result;
     }
     fs = {
         read: (path) => this.files.read(path),
@@ -126,7 +134,18 @@ export class Desktop extends SessionHandle {
     process = {
         list: async () => {
             const r = await this.guiCall("process.list", {});
-            return r.processes;
+            return (r.processes ?? []).map((p) => {
+                const info = {
+                    pid: Number(p.pid),
+                    name: String(p.name ?? p.comm ?? ""),
+                };
+                const cmd = p.cmd ?? p.cmdline;
+                if (typeof cmd === "string")
+                    info.cmd = cmd;
+                if (typeof p.state === "string")
+                    info.state = p.state;
+                return info;
+            });
         },
         kill: (pid) => this.guiCall("process.kill", { pid }).then(() => undefined),
         start: async (cmd, opts = {}) => {

package/dist/errors.d.ts

@@ -10,6 +10,12 @@ export declare class GatewayError extends SolariError {
     readonly body?: GatewayErrorBody;
     /** The gateway's hint that retrying may help (`body.retryable`), on every gateway error. */
     readonly retryable?: boolean;
+    /** The gateway's request id (`x-request-id`); include it when reporting a problem. */
+    readonly requestId?: string;
+    /** On a `429`: `"rate_limited"` (transient, honour {@link retryAfterMs}) or `"quota_exceeded"` (a cap; do not retry). */
+    readonly errorType?: "rate_limited" | "quota_exceeded";
+    /** How long the gateway asked callers to wait (`Retry-After`), in ms; only set on retryable errors. */
+    readonly retryAfterMs?: number;
     constructor(status: number, message: string, body?: GatewayErrorBody);
 }
 /** `404` — the sandbox, desktop, snapshot, template or volume does not exist (or is not yours). */
@@ -60,6 +66,20 @@ export declare class SandboxNotStoppedError extends GatewayError {
     readonly state?: string;
     constructor(message?: string, body?: GatewayErrorBody);
 }
+/**
+ * `409 {code:"SnapshotNotRestorable"}` — a restore (create from a snapshot, resume of a paused sandbox, revert)
+ * the platform knows cannot succeed, so it is refused at once instead of timing out as a capacity error.
+ * Never retryable (`retryable === false`). `reason` says why when known: `"golden_mismatch"` means the snapshot
+ * was taken on a different template build (`golden.imageKey`) than the fleet runs, and `snapshotImageKey` /
+ * `hostImageKey` name the two. Take a fresh snapshot from a new sandbox instead.
+ */
+export declare class SnapshotNotRestorableError extends GatewayError {
+    /** Why it cannot be restored, when the gateway says (`"golden_mismatch"`). */
+    readonly reason?: string;
+    readonly snapshotImageKey?: string;
+    readonly hostImageKey?: string;
+    constructor(message?: string, body?: GatewayErrorBody);
+}
 /** A computer-use RPC returned `{ok:false}`. */
 export declare class ActionError extends SolariError {
     readonly method: string;

package/dist/errors.js

@@ -9,12 +9,20 @@ export class GatewayError extends SolariError {
     code;
     body;
     retryable;
+    requestId;
+    errorType;
+    retryAfterMs;
     constructor(status, message, body) {
         super(message);
         this.status = status;
         this.code = body?.code;
         this.body = body;
         this.retryable = body?.retryable;
+        this.requestId = body?.requestId;
+        this.errorType = body?.errorType;
+        if (body?.retryable === true && typeof body.retryAfterSeconds === "number" && body.retryAfterSeconds >= 0) {
+            this.retryAfterMs = Math.round(body.retryAfterSeconds * 1000);
+        }
     }
 }
 export class NotFoundError extends GatewayError {
@@ -54,6 +62,17 @@ export class SandboxNotStoppedError extends GatewayError {
         this.state = body?.state;
     }
 }
+export class SnapshotNotRestorableError extends GatewayError {
+    reason;
+    snapshotImageKey;
+    hostImageKey;
+    constructor(message = "Snapshot cannot be restored", body) {
+        super(409, message, body);
+        this.reason = body?.reason;
+        this.snapshotImageKey = body?.snapshotImageKey;
+        this.hostImageKey = body?.hostImageKey;
+    }
+}
 export class ActionError extends SolariError {
     method;
     code;
@@ -101,6 +120,8 @@ export function mapGatewayError(status, body) {
             if (code === "NotStopped" || code === "StartInProgress") {
                 return new SandboxNotStoppedError(msg, body);
             }
+            if (code === "SnapshotNotRestorable")
+                return new SnapshotNotRestorableError(msg, body);
             return new GatewayError(409, msg ?? "Conflict", body);
         case 503:
             if (code === undefined || code === "NoCapacity" || code === "StartTimeout")

package/dist/handle.d.ts

@@ -58,12 +58,18 @@ export interface SessionConfig extends ControlChannelConfig {
 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 interface SessionHandle {
+    /** `await using sbx = await client.create(...)` releases the machine (`kill()`) when the scope ends. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
 export declare class SessionHandle {
     /** The session id (sandboxId / sessionId). */
     readonly id: string;
     readonly controlUrl: string;
     readonly expiresAt: string;
     protected readonly channel: ControlChannel;
+    /** Set once the gateway has refused a command stream because this sandbox is `shared`. */
+    private sharedContext;
     protected readonly hooks: SessionHooks;
     /** Set by {@link kill} so {@link close} doesn't warn about a machine we
      *  have just released. */
@@ -198,10 +204,19 @@ export declare class SessionHandle {
     };
     /** Run `git <args>` in the guest via the command RPC (no shell). */
     private runGit;
-    /** Run `git <args>`; throw with the stderr on a non-zero exit. */
+    /** Run `git <args>`; throw with the stderr on a non-zero exit. A password passed in `secret` is masked in the message. */
     private mustGit;
-    /** Splice basic-auth creds into an https remote URL (for private remotes). */
-    private authUrl;
+    /**
+     * Credentials for ONE git command, for a private http(s) remote at `remoteUrl`. They go to the guest as environment
+     * variables of that command and git reads them back through an inline credential helper, so they are never in the
+     * clone URL (and so not in `.git/config`, a snapshot or a template), never in argv (`/proc/<pid>/cmdline`), and never
+     * in a config file: the `-c` options last for this command only and the helper script holds no secret.
+     *
+     * The helper is bound to the remote's origin (`credential.<scheme>://<host>.helper`), so git never hands the password
+     * to another host: a redirect to a different host, or a downgrade to http, gets nothing. Returns undefined when
+     * there are no credentials, or the remote is not http(s) (ssh remotes do not use them).
+     */
+    private gitAuth;
     private gitClone;
     private gitStatus;
     private gitAdd;

package/dist/handle.js

@@ -23,11 +23,23 @@ function trackUnreleased(token, id) {
 }
 const MIN_REST_TIMEOUT_MS = 1000;
 export const PTY_EARLY_BUFFER_MAX = 1024 * 1024;
+const GIT_CREDENTIAL_HELPER = '!f() { test "$1" = get && printf "username=%s\\npassword=%s\\n" "$SOLARI_GIT_USERNAME" "$SOLARI_GIT_PASSWORD"; }; f';
+function gitSubcommand(args) {
+    let i = 0;
+    while (args[i] === "-c")
+        i += 2;
+    return args[i] ?? "";
+}
+function rejectOptionLike(what, v) {
+    if (v.startsWith("-"))
+        throw new Error(`git ${what} must not start with "-": ${JSON.stringify(v)}`);
+}
 export class SessionHandle {
     id;
     controlUrl;
     expiresAt;
     channel;
+    sharedContext = false;
     hooks;
     killed = false;
     releaseToken = {};
@@ -120,17 +132,26 @@ export class SessionHandle {
                     opts.onStderr?.(c.data);
             });
         }
-        this.channel.onFrame("cmd.data", cmdId, (f) => {
-            const stream = f.stream ?? "stdout";
-            const data = f.base64 ? new TextDecoder().decode(base64ToBytes(f.base64)) : "";
-            const chunk = { stream, data };
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const emit = (chunk) => {
             if (dataCbs.length === 0)
                 buffered.push(chunk);
             else
                 for (const cb of dataCbs)
                     cb(chunk);
+        };
+        this.channel.onFrame("cmd.data", cmdId, (f) => {
+            const stream = f.stream ?? "stdout";
+            const dec = decoders[stream] ?? decoders.stdout;
+            const data = f.base64 ? dec.decode(base64ToBytes(f.base64), { stream: true }) : "";
+            emit({ stream, data });
         });
         this.channel.onFrame("cmd.exit", cmdId, (f) => {
+            for (const stream of ["stdout", "stderr"]) {
+                const rest = decoders[stream].decode();
+                if (rest)
+                    emit({ stream, data: rest });
+            }
             this.channel.offFrame("cmd.data", cmdId);
             this.channel.offFrame("cmd.exit", cmdId);
             this.channel.offStreamClose(cmdId);
@@ -172,23 +193,21 @@ export class SessionHandle {
         if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
             throw new SolariError(`Solari: timeoutMs must be a non-negative number of milliseconds, got ${String(timeoutMs)}`);
         }
-        if (this.hooks.exec &&
+        const restEligible = !!this.hooks.exec &&
             !opts.background &&
             !opts.onStdout &&
             !opts.onStderr &&
             !opts.env &&
             !opts.user &&
             timeoutMs >= MIN_REST_TIMEOUT_MS &&
-            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS &&
-            !this.channel.connected) {
+            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS;
+        const viaRest = async () => {
+            const r = await this.hooks.exec(this.id, { cmd, args: opts.args, cwd: opts.cwd, timeoutMs });
+            return { ...r, timedOut: r.timedOut === true };
+        };
+        if (restEligible && (!this.channel.connected || this.sharedContext)) {
             try {
-                const r = await this.hooks.exec(this.id, {
-                    cmd,
-                    args: opts.args,
-                    cwd: opts.cwd,
-                    timeoutMs,
-                });
-                return { ...r, timedOut: r.timedOut === true };
+                return await viaRest();
             }
             catch (err) {
                 if (!isRouteUnavailable(err))
@@ -196,7 +215,24 @@ export class SessionHandle {
             }
         }
         const acc = { stdout: "", stderr: "" };
-        const handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        let handle;
+        try {
+            handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        }
+        catch (err) {
+            if (!isSharedRefusal(err))
+                throw err;
+            this.sharedContext = true;
+            if (restEligible) {
+                try {
+                    return await viaRest();
+                }
+                catch (e) {
+                    throw normalizeExecError(e, timeoutMs);
+                }
+            }
+            throw err;
+        }
         if (opts.background) {
             return { exitCode: 0, stdout: "", stderr: "", timedOut: false };
         }
@@ -378,42 +414,61 @@ export class SessionHandle {
         branches: (cwd) => this.gitBranches(cwd),
         log: (opts = {}) => this.gitLog(opts),
     };
-    async runGit(args, cwd) {
-        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}) });
+    async runGit(args, cwd, env) {
+        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) });
     }
-    async mustGit(args, cwd) {
-        const r = await this.runGit(args, cwd);
+    async mustGit(args, cwd, env, secret) {
+        const r = await this.runGit(args, cwd, env);
         if (r.exitCode !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ${args[0]} failed (exit ${r.exitCode}): ${detail}`);
+            let detail = (r.stderr || r.stdout || "").trim();
+            if (secret)
+                detail = detail.split(secret).join("***");
+            throw new Error(`git ${gitSubcommand(args)} failed (exit ${r.exitCode}): ${detail}`);
         }
         return r.stdout;
     }
-    authUrl(url, username, password) {
+    gitAuth(remoteUrl, username, password) {
         if (!username && !password)
-            return url;
+            return undefined;
+        for (const v of [username, password]) {
+            if (v !== undefined && /[\r\n\0]/.test(v))
+                throw new Error("git credentials must not contain line breaks or NUL");
+        }
+        let origin;
         try {
-            const u = new URL(url);
-            if (username)
-                u.username = encodeURIComponent(username);
-            if (password)
-                u.password = encodeURIComponent(password);
-            return u.toString();
+            const u = new URL(remoteUrl);
+            if (u.protocol !== "https:" && u.protocol !== "http:")
+                return undefined;
+            origin = `${u.protocol}//${u.host}`;
         }
         catch {
-            return url;
+            return undefined;
         }
+        if (/[=\s]/.test(origin))
+            return undefined;
+        return {
+            cfg: [
+                "-c", "credential.helper=",
+                "-c", `credential.${origin}.helper=${GIT_CREDENTIAL_HELPER}`,
+            ],
+            env: {
+                GIT_TERMINAL_PROMPT: "0",
+                SOLARI_GIT_USERNAME: username ?? "",
+                SOLARI_GIT_PASSWORD: password ?? "",
+            },
+        };
     }
     async gitClone(url, opts) {
-        const args = ["clone"];
+        const auth = this.gitAuth(url, opts.username, opts.password);
+        const args = [...(auth?.cfg ?? []), "clone"];
         if (opts.depth && opts.depth > 0)
             args.push("--depth", String(opts.depth));
         if (opts.branch)
             args.push("--branch", opts.branch);
-        args.push(this.authUrl(url, opts.username, opts.password));
+        args.push("--", url);
         if (opts.path)
             args.push(opts.path);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitStatus(cwd) {
         const out = await this.mustGit(["status", "--porcelain=v1", "--branch"], cwd);
@@ -488,25 +543,25 @@ export class SessionHandle {
     }
     async gitPushPull(op, opts) {
         const remote = opts.remote || "origin";
-        const cfg = [];
+        rejectOptionLike("remote", remote);
+        if (opts.branch)
+            rejectOptionLike("branch", opts.branch);
+        let auth;
         if (opts.username || opts.password) {
-            const plain = (await this.runGit(["remote", "get-url", remote], opts.cwd)).stdout.trim();
-            if (plain) {
-                const authed = this.authUrl(plain, opts.username, opts.password);
-                if (authed !== plain)
-                    cfg.push("-c", `url.${authed}.insteadOf=${plain}`);
-            }
+            const plain = (await this.mustGit(["remote", "get-url", "--", remote], opts.cwd)).trim();
+            auth = this.gitAuth(plain, opts.username, opts.password);
         }
-        const args = [...cfg, op, remote];
+        const args = [...(auth?.cfg ?? []), op, "--", remote];
         if (opts.branch)
             args.push(opts.branch);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitCheckout(ref, opts) {
+        rejectOptionLike("ref", ref);
         const args = ["checkout"];
         if (opts.create)
             args.push("-b");
-        args.push(ref);
+        args.push(ref, "--");
         await this.mustGit(args, opts.cwd);
     }
     async gitBranches(cwd) {
@@ -652,6 +707,11 @@ function explainShellCommandFailure(cmd, err) {
     }
     return new Error(msg + hint);
 }
+function isSharedRefusal(err) {
+    if (err instanceof ActionError && err.code === "NotAvailableOnSharedIsolation")
+        return true;
+    return err instanceof Error && /NotAvailableOnSharedIsolation|not available on a shared/.test(err.message);
+}
 function isRouteUnavailable(err) {
     return (err instanceof GatewayError &&
         (err.status === 404 || err.status === 405 || err.status === 501));

package/dist/http.d.ts

@@ -5,6 +5,8 @@ export interface HttpTransportOptions {
     fetch?: typeof fetch;
     /** Max retry attempts for idempotent requests. Default 5. */
     maxRetries?: number;
+    /** Longest server-requested `Retry-After` the transport will wait out (default 30 000 ms); a longer one surfaces the error. */
+    maxRetryAfterMs?: number;
     /** Per-request timeout in ms (AbortSignal). Default 300000. */
     requestTimeoutMs?: number;
     /** Fixed retry delay in ms. When unset, uses exponential backoff + jitter.
@@ -24,6 +26,7 @@ export declare class HttpTransport {
     readonly baseUrl: string;
     private readonly fetchImpl;
     private readonly maxRetries;
+    private readonly maxRetryAfterMs;
     private readonly requestTimeoutMs;
     private readonly retryDelayMs;
     constructor(o: HttpTransportOptions);
@@ -34,3 +37,5 @@ export declare class HttpTransport {
     request<T>(method: string, path: string, body?: unknown, opts?: HttpRequestOptions): Promise<T>;
     private backoffMs;
 }
+/** `Retry-After` is delta-seconds or an HTTP date; anything else (or negative) is ignored. */
+export declare function parseRetryAfterSeconds(value: string | null): number | undefined;

package/dist/http.js

@@ -10,6 +10,7 @@ export class HttpTransport {
     baseUrl;
     fetchImpl;
     maxRetries;
+    maxRetryAfterMs;
     requestTimeoutMs;
     retryDelayMs;
     constructor(o) {
@@ -25,6 +26,7 @@ export class HttpTransport {
         }
         this.fetchImpl = f;
         this.maxRetries = o.maxRetries ?? 5;
+        this.maxRetryAfterMs = o.maxRetryAfterMs ?? 30_000;
         this.requestTimeoutMs = o.requestTimeoutMs ?? 300_000;
         this.retryDelayMs = o.retryDelayMs;
     }
@@ -70,10 +72,21 @@ export class HttpTransport {
                 catch {
                     errBody = undefined;
                 }
+                const headerId = res.headers.get("x-request-id");
+                const headerRetryAfter = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                if (headerId || headerRetryAfter !== undefined) {
+                    errBody = {
+                        ...errBody,
+                        ...(headerId && !errBody?.requestId ? { requestId: headerId } : {}),
+                        ...(headerRetryAfter !== undefined ? { retryAfterSeconds: headerRetryAfter } : {}),
+                    };
+                }
                 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) {
-                    await sleep(this.backoffMs(attempt++));
+                const retryAfterMs = retryable && typeof errBody?.retryAfterSeconds === "number" ? errBody.retryAfterSeconds * 1000 : undefined;
+                const tooLong = retryAfterMs !== undefined && retryAfterMs > this.maxRetryAfterMs;
+                if (idempotent && retryable && !tooLong && attempt < this.maxRetries) {
+                    await sleep(Math.max(this.backoffMs(attempt++), retryAfterMs ?? 0));
                     continue;
                 }
                 throw mapGatewayError(res.status, errBody);
@@ -90,3 +103,14 @@ export class HttpTransport {
         return Math.min(150 * 2 ** attempt, 8000) + Math.floor(Math.random() * 250);
     }
 }
+export function parseRetryAfterSeconds(value) {
+    if (value === null)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number(v);
+    const t = Date.parse(v);
+    if (Number.isNaN(t))
+        return undefined;
+    return Math.max(0, Math.ceil((t - Date.now()) / 1000));
+}

package/dist/idle-policy.d.ts

@@ -0,0 +1,7 @@
+import type { IdlePolicyStages } from "./types.js";
+/**
+ * Build the string form of an idle policy from stages, e.g. `{ pause: "5m", delete: "1d" }` becomes
+ * `"pause@5m,delete@1d"` (the format the gateway echoes back). Stages come out in order: park, hibernate, pause, delete.
+ * A number is milliseconds. The gateway validates the result (ordering, bounds, conflicts); this only formats it.
+ */
+export declare function formatIdlePolicy(stages: IdlePolicyStages): string;

package/dist/idle-policy.js

@@ -0,0 +1,10 @@
+export function formatIdlePolicy(stages) {
+    const order = ["park", "hibernate", "pause", "delete"];
+    return order
+        .filter((k) => stages[k] !== undefined)
+        .map((k) => {
+        const v = stages[k];
+        return `${k}@${typeof v === "number" ? `${v}ms` : v}`;
+    })
+        .join(",");
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
+export { formatIdlePolicy } from "./idle-policy.js";
 export type { SessionConfig, SessionHooks } from "./handle.js";
 export { Desktop } from "./desktop.js";
 export type { DesktopConfig } from "./desktop.js";
@@ -11,5 +12,5 @@ export type { TemplateClientOptions } from "./template-client.js";
 export { VolumeClient } from "./volume-client.js";
 export type { VolumeClientOptions } from "./volume-client.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 { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SnapshotNotRestorableError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,9 +1,10 @@
 export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
+export { formatIdlePolicy } from "./idle-policy.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 { 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 { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SnapshotNotRestorableError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";

package/dist/types.d.ts

@@ -1,6 +1,36 @@
 import type { CompiledImage } from "./image.js";
 /** Session lifecycle status reported by `GET /desktops/:sessionId`. */
 export type DesktopStatus = "starting" | "ready" | "paused" | "releasing" | "gone";
+/**
+ * One stage of an {@link IdlePolicy}. All stages are optional and every offset is measured from the sandbox's LAST
+ * ACTIVITY, so the offsets must increase in this order:
+ *
+ *  - `park`: freeze the vCPUs but keep RAM and the slot; the next request wakes it in milliseconds. Parked time is free.
+ *  - `hibernate`: checkpoint to disk and free the slot (needs a `park` stage; a parked sandbox escalates to it).
+ *  - `pause`: snapshot and free the slot; `connect`/resume brings it back. Same as `lifecycle.onTimeout: "pause"`.
+ *  - `delete`: destroy it. After a `pause` it deletes the paused sandbox (at most 27 days after the pause on Solari
+ *    cloud); with no `pause` stage it is `lifecycle.onTimeout: "kill"`.
+ *
+ * Values are a duration string (`"30s"`, `"5m"`, `"1h30m"`, `"1d"`; units ms, s, m, h, d) or a number of milliseconds.
+ */
+export interface IdlePolicyStages {
+    park?: string | number;
+    hibernate?: string | number;
+    pause?: string | number;
+    delete?: string | number;
+}
+/**
+ * Staged idle policy: what happens as a sandbox sits idle, in one setting. Either the string form
+ * (`"park@30s,hibernate@2m,pause@5m,delete@1d"`) or {@link IdlePolicyStages}. Do not combine it with
+ * `idleTimeoutMs`/`timeoutMs`/`ttlSeconds` or `lifecycle.onTimeout`/`parkAfterMs`/`parkMaxMs`/`hibernateAfterParkedMs`;
+ * the gateway answers 400 naming the clashing field. `lifecycle.autoResume` and `lifecycle.checkpointEveryMs` still apply.
+ *
+ * If the policy has a `park` (or `hibernate`) stage but no `pause` or `delete`, the gateway adds `pause` 24 hours after
+ * the last stage so a parked sandbox cannot hold its slot for the plan's whole maximum; the sandbox view's `idlePolicy`
+ * shows the policy as applied. What is billed: running time at the normal rate; parked time is free; hibernated and
+ * paused sandboxes are not billed for compute.
+ */
+export type IdlePolicy = string | IdlePolicyStages;
 /** What the gateway does when a session's idle/ttl timeout fires. */
 export type OnTimeout = "pause" | "kill";
 /**
@@ -105,6 +135,8 @@ export interface CreateDesktopOptions {
     idleTimeoutMs?: number;
     /** Idle lifecycle policy (pause/kill on timeout; optional auto-resume). */
     lifecycle?: SandboxLifecycle;
+    /** Staged idle policy (park, hibernate, pause, delete as the sandbox sits idle); see {@link IdlePolicy}. Replaces `idleTimeoutMs` + most of `lifecycle`. */
+    idlePolicy?: IdlePolicy;
     /** Persistent volumes to mount before the session starts (Part V.4). */
     volumes?: VolumeAttachment[];
 }
@@ -120,6 +152,7 @@ export interface CreateDesktopRequest {
     record?: boolean;
     timeoutMs?: number;
     lifecycle?: SandboxLifecycle;
+    idlePolicy?: IdlePolicy;
     volumes?: VolumeAttachment[];
 }
 /** `201` response from `POST /desktops`. */
@@ -155,10 +188,25 @@ export interface GatewayErrorBody {
     /** Gateway hint that the failure is transient (e.g. 503 "No desktop host
      *  available"). The HTTP transport retries idempotent requests when set. */
     retryable?: boolean;
+    /** The gateway's id for this request (also the `x-request-id` response header). Quote it in support requests. */
+    requestId?: string;
+    /** On every `429`: `"rate_limited"` (retryable, honour `Retry-After`) or `"quota_exceeded"` (a cap; retrying cannot help). */
+    errorType?: "rate_limited" | "quota_exceeded";
+    /** Seconds to wait before retrying, mirrored from the `Retry-After` header by the transport. */
+    retryAfterSeconds?: number;
     /** Current sandbox state, set on `409 NotStopped` / `409 StartInProgress`. */
     state?: string;
     /** Set on `409 HostCapabilityMissing`: capabilities the host pool lacks (e.g. `["start"]`). */
     missingCapabilities?: string[];
+    /** Set on `409 SnapshotNotRestorable`: why. `"golden_mismatch"` = the snapshot was taken on a different
+     *  template build than the fleet runs now. Absent on the older (CPU-platform / pre-migration) refusals. */
+    reason?: string;
+    /** Set on `409 SnapshotNotRestorable`: the snapshot, where the request named one. */
+    snapshotId?: string;
+    /** Set with `reason: "golden_mismatch"`: the `golden.imageKey` the snapshot was taken on (when the host reports it). */
+    snapshotImageKey?: string;
+    /** Set with `reason: "golden_mismatch"`: the `golden.imageKey` of the host that refused. */
+    hostImageKey?: string;
 }
 /** `kind` of a session: headless `sandbox` or GUI `desktop`. */
 export type SandboxKind = "sandbox" | "desktop";
@@ -228,6 +276,8 @@ export interface CreateSandboxOptions {
     isolation?: SandboxIsolation;
     /** Idle lifecycle policy (pause/kill on timeout; optional auto-resume). */
     lifecycle?: SandboxLifecycle;
+    /** Staged idle policy (park, hibernate, pause, delete as the sandbox sits idle); see {@link IdlePolicy}. Replaces `idleTimeoutMs` + most of `lifecycle`. */
+    idlePolicy?: IdlePolicy;
     /**
      * Persistent volumes to mount into the session before it starts (Part V.4).
      * Each `volumeId` must belong to your org (create one via `client.volumes`).
@@ -295,10 +345,27 @@ export interface CreateSandboxRequest {
     resolution?: string;
     record?: boolean;
     lifecycle?: SandboxLifecycle;
+    idlePolicy?: IdlePolicy;
     volumes?: VolumeAttachment[];
     user?: string;
     cwd?: string;
 }
+/**
+ * What a sandbox (or the sandbox a snapshot was taken from) actually ran on. Goldens are content-
+ * addressed: `imageKey` is `sha256(rootfsSha256 | kernelSha256 | chVersion)`, so equal `imageKey`s
+ * mean byte-identical rootfs, kernel and VMM. `template` is only the name; this is the bits behind it.
+ */
+export interface GoldenInfo {
+    imageKey: string;
+    /** Template name the golden was built for. */
+    template?: string;
+    /** SHA-256 of the root filesystem image. */
+    rootfsSha256?: string;
+    /** SHA-256 of the guest kernel. */
+    kernelSha256?: string;
+    /** Cloud Hypervisor (VMM) version. */
+    chVersion?: string;
+}
 /** `201` response from `POST /sandboxes`. */
 export interface CreateSandboxResponse {
     sandboxId: string;
@@ -316,6 +383,10 @@ export interface CreateSandboxResponse {
     /** The default user and working directory, echoed when the gateway honoured `user` / `cwd` on create. */
     user?: string;
     cwd?: string;
+    /** The template the sandbox was created from. */
+    template?: string;
+    /** The golden it runs on (rootfs / kernel / VMM digests); absent when the host did not report one. */
+    golden?: GoldenInfo;
 }
 /** `GET /sandboxes/:id` response. */
 export interface SandboxView {
@@ -341,6 +412,14 @@ export interface SandboxView {
     diskGb?: number;
     /** Presigned playback URL, present for a recorded `kind:"desktop"` session. */
     recordingUrl?: string;
+    /** The staged idle policy as the gateway applies it (including a `pause` stage it added), when one was set. */
+    idlePolicy?: string;
+    /** Set while the sandbox is paused under an `idlePolicy` with a `delete` stage: when it will be deleted (ISO 8601). */
+    deleteAt?: string;
+    /** The template this sandbox was created from. */
+    template?: string;
+    /** The golden it runs on (rootfs / kernel / VMM digests); absent when the host did not report one. */
+    golden?: GoldenInfo;
 }
 /** `GET /sandboxes` response (paginated). */
 export interface ListSandboxesResponse {
@@ -371,6 +450,8 @@ export interface SnapshotView {
     createdAt: string;
     kind: SandboxKind;
     template: string;
+    /** The golden the source sandbox ran on when the snapshot was taken; absent for older snapshots. */
+    golden?: GoldenInfo;
 }
 /** `POST /sandboxes/:id/snapshots` response. */
 export interface CreateSnapshotResponse {
@@ -605,8 +686,12 @@ export interface ProcessListParams {
 }
 export interface ProcessInfo {
     pid: number;
+    /** The process name (the guest agent's `comm`). */
     name: string;
+    /** The full command line (the guest agent's `cmdline`). */
     cmd?: string;
+    /** Process state letter as the kernel reports it (`R`, `S`, `Z`, ...). */
+    state?: string;
 }
 export interface ProcessListResult {
     processes: ProcessInfo[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Shared runtime for the Solari SDK \u2014 transport, session handles, images, templates, and types used by @solarisdk/desktop and @solarisdk/sandbox.",
   "type": "module",
   "main": "./dist/index.js",