@spheron/sandbox 0.0.0-stage → 0.1.1

package/dist/http.d.ts

@@ -0,0 +1,37 @@
+import { SpheronApiError } from './errors.js';
+export declare const DEFAULT_BASE_URL = "https://app.spheron.ai";
+export declare const SDK_VERSION = "0.1.1";
+export interface ClientOptions {
+    /** A GPU VM API key (`sai_pk_...`). Defaults to the SPHERON_API_KEY environment variable. */
+    apiKey?: string;
+    /** Defaults to SPHERON_BASE_URL, then https://app.spheron.ai. */
+    baseUrl?: string;
+    /** A fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Retries for a safe request that failed to connect or got a 502, 503 or 504. Default 3. (429s retry for 90 s.) */
+    maxRetries?: number;
+    /** Timeout for one HTTP request. Default 90 s; long polls add their wait on top. */
+    requestTimeoutMs?: number;
+}
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    timeoutMs?: number;
+    /** Safe to send again after a dropped connection or a 502/503/504. GET requests always are. */
+    idempotent?: boolean;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** The typed error for a refused response. */
+export declare function apiError(res: Response, body: unknown): SpheronApiError;
+/** The HTTP layer every SDK call goes through: auth, JSON, typed errors and retries. */
+export declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    constructor(opts?: ClientOptions);
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,198 @@
+import { AuthenticationError, InstanceNotRunningError, NotFoundError, RateLimitError, SandboxNotReadyError, SandboxUnreachableError, SpheronApiError, SpheronError, } from './errors.js';
+export const DEFAULT_BASE_URL = 'https://app.spheron.ai';
+export const SDK_VERSION = '0.1.1';
+const CLIENT_NAME = `spheron-sandbox-js/${SDK_VERSION}`;
+/** The API answers these two 409s with exactly this text (shipped API text never changes), so they map to types. */
+const NOT_RUNNING = 'This instance is not running.';
+const INSTALLING = 'The GPU sandbox is still being set up on this instance. Try again in a minute.';
+/** A 429 is retried until this much time has passed. The file transfer cap frees a slot within seconds to a minute. */
+const RATE_LIMIT_BUDGET_MS = 90_000;
+/** The longest single wait for a 429, whatever Retry-After says (the general limit can say 15 minutes). */
+const RATE_LIMIT_MAX_WAIT_MS = 30_000;
+/** An environment variable, or undefined where there is none or reading it is not allowed (Deno without --allow-env). */
+function env(name) {
+    try {
+        return globalThis.process?.env?.[name];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function retryAfterSec(res, body) {
+    const header = Number(res.headers.get('retry-after'));
+    if (Number.isFinite(header) && header > 0)
+        return header;
+    const b = body;
+    const fromBody = Number(b?.details?.retryAfter ?? b?.retryAfter);
+    return Number.isFinite(fromBody) && fromBody > 0 ? fromBody : undefined;
+}
+/** The typed error for a refused response. */
+export function apiError(res, body) {
+    const b = (body && typeof body === 'object' ? body : {});
+    // Auth refusals put the useful sentence in `message` and a bare "Unauthorized" in `error`.
+    const generic = b.error === 'Unauthorized' || b.error === 'Forbidden';
+    const message = (typeof b.error === 'string' && !generic ? b.error : undefined) ??
+        (typeof b.message === 'string' ? b.message : undefined) ??
+        (typeof b.error === 'string' ? b.error : undefined) ??
+        `HTTP ${res.status}`;
+    const opts = { code: typeof b.code === 'string' ? b.code : undefined, requestId: res.headers.get('x-request-id') ?? undefined, body };
+    switch (res.status) {
+        case 401:
+        case 403:
+            return new AuthenticationError(res.status, message, opts);
+        case 404:
+            return new NotFoundError(res.status, message, opts);
+        case 409:
+            if (message === NOT_RUNNING)
+                return new InstanceNotRunningError(res.status, message, opts);
+            if (message === INSTALLING)
+                return new SandboxNotReadyError(res.status, message, opts);
+            return new SpheronApiError(res.status, message, opts);
+        case 429:
+            return new RateLimitError(res.status, message, { ...opts, retryAfterSec: retryAfterSec(res, body) });
+        case 503:
+            if (b.recovery)
+                return new SandboxUnreachableError(res.status, message, { ...opts, recovery: b.recovery });
+            return new SpheronApiError(res.status, message, opts);
+        default:
+            return new SpheronApiError(res.status, message, opts);
+    }
+}
+/** The HTTP layer every SDK call goes through: auth, JSON, typed errors and retries. */
+export class HttpClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    maxRetries;
+    timeoutMs;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? env('SPHERON_API_KEY');
+        if (!apiKey)
+            throw new SpheronError('No API key. Pass apiKey, or set SPHERON_API_KEY to a GPU VM API key (sai_pk_...).');
+        this.apiKey = apiKey;
+        this.baseUrl = (opts.baseUrl ?? env('SPHERON_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new SpheronError('No fetch available. Use Node 18 or later, or pass a fetch implementation.');
+        this.fetchImpl = f.bind(globalThis);
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.timeoutMs = opts.requestTimeoutMs ?? 90_000;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const idempotent = opts.idempotent ?? method === 'GET';
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': CLIENT_NAME,
+            // Names the SDK and its version to Spheron, so a release that breaks shows on our side (a browser may drop User-Agent).
+            'X-Spheron-Client': CLIENT_NAME,
+            ...opts.headers,
+        };
+        let payload;
+        if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            payload = JSON.stringify(opts.body);
+        }
+        const started = Date.now();
+        for (let attempt = 0;; attempt++) {
+            if (opts.signal?.aborted)
+                throw opts.signal.reason;
+            const call = withTimeout(timeoutMs, opts.signal);
+            let res;
+            let text;
+            try {
+                res = await this.fetchImpl(url, { method, headers, body: payload, signal: call.signal });
+                text = await res.text();
+            }
+            catch (error) {
+                if (opts.signal?.aborted)
+                    throw opts.signal.reason;
+                // A dropped connection or a timeout: the request may have done its work, so only a safe one is sent again.
+                if (idempotent && attempt < this.maxRetries) {
+                    await sleep(backoffMs(attempt), opts.signal);
+                    continue;
+                }
+                const why = call.timedOut() ? `timed out after ${timeoutMs} ms` : String(error?.message ?? error);
+                throw new SpheronError(`${method} ${path} failed: ${why}`);
+            }
+            finally {
+                call.done();
+            }
+            const body = parseBody(text);
+            if (res.ok)
+                return body;
+            const err = apiError(res, body);
+            // A 429 did nothing, so any request can be sent again: wait as asked, for up to the budget.
+            if (err instanceof RateLimitError) {
+                const wait = Math.min((err.retryAfterSec ?? backoffMs(attempt) / 1000) * 1000, RATE_LIMIT_MAX_WAIT_MS);
+                if (Date.now() - started + wait > RATE_LIMIT_BUDGET_MS)
+                    throw err;
+                await sleep(wait, opts.signal);
+                continue;
+            }
+            const transient = res.status === 502 || res.status === 504 || (res.status === 503 && !(err instanceof SandboxUnreachableError));
+            if (!(idempotent && transient && attempt < this.maxRetries))
+                throw err;
+            await sleep(backoffMs(attempt), opts.signal);
+        }
+    }
+}
+function parseBody(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * A signal that aborts after `ms` or when `outer` does (AbortSignal.any and AbortSignal.timeout are not on Node 18).
+ * Call done() when the request ends, so the timer and the listener on `outer` do not outlive it.
+ */
+function withTimeout(ms, outer) {
+    const ac = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        ac.abort(new SpheronError(`timed out after ${ms} ms`));
+    }, ms);
+    const onAbort = () => ac.abort(outer.reason);
+    if (outer?.aborted)
+        ac.abort(outer.reason);
+    else
+        outer?.addEventListener('abort', onAbort, { once: true });
+    return {
+        signal: ac.signal,
+        timedOut: () => timedOut,
+        done: () => {
+            clearTimeout(timer);
+            outer?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+function backoffMs(attempt) {
+    return Math.min(500 * 2 ** attempt, 8_000) + Math.floor(Math.random() * 250);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Sandbox } from './sandbox.js';
+export type { CreateOptions, OfferChoice, ReadyPhase, SandboxOptions, WaitReadyOptions } from './sandbox.js';
+export { CommandHandle, Commands } from './commands.js';
+export type { RunOptions, StartOptions, WaitOptions } from './commands.js';
+export { Files, MAX_FILE_BYTES } from './files.js';
+export { hourlyPrice } from './offers.js';
+export type { OfferFilter } from './offers.js';
+export type { ClientOptions } from './http.js';
+export { DEFAULT_BASE_URL, SDK_VERSION } from './http.js';
+export * from './errors.js';
+export type { CommandResult, CommandStatus, Deployment, FileEntry, GpuOffer, SandboxStatus } from './types.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { Sandbox } from './sandbox.js';
+export { CommandHandle, Commands } from './commands.js';
+export { Files, MAX_FILE_BYTES } from './files.js';
+export { hourlyPrice } from './offers.js';
+export { DEFAULT_BASE_URL, SDK_VERSION } from './http.js';
+export * from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,cAAc,aAAa,CAAC"}

package/dist/offers.d.ts

@@ -0,0 +1,25 @@
+import type { HttpClient } from './http.js';
+import type { GpuOffer } from './types.js';
+export interface OfferFilter {
+    /** GPU model, one word: h100, a100, l40s, rtx4090. Leave out for any GPU. */
+    gpu?: string;
+    /** GPUs per instance. */
+    gpuCount?: number;
+    /** Spot offers only (cheaper, and can be reclaimed at any time). Default: dedicated only. */
+    spot?: boolean;
+    /** Regions to include. */
+    regions?: string[];
+    /** Providers to include, as the API names them (spheron-ai, spheron-es, data-crunch, ...). */
+    providers?: string[];
+    /** Most you are willing to pay per hour for the whole instance, in USD. */
+    maxHourlyPrice?: number;
+}
+/** What an offer bills per hour: the spot price on a spot offer when there is one. */
+export declare function hourlyPrice(offer: GpuOffer): number;
+/** Offers a sandbox can be deployed on, matching the filter, cheapest first. Virtual machines only. */
+export declare function findOffers(http: HttpClient, filter?: OfferFilter): Promise<GpuOffer[]>;
+/**
+ * The operating system to deploy: the one asked for when the offer has it (exact, then by substring), else an
+ * Ubuntu image with CUDA, else any Ubuntu, else the first listed.
+ */
+export declare function pickOperatingSystem(offer: GpuOffer, wanted?: string): string | undefined;

package/dist/offers.js

@@ -0,0 +1,55 @@
+/** What an offer bills per hour: the spot price on a spot offer when there is one. */
+export function hourlyPrice(offer) {
+    return String(offer.instanceType).toUpperCase() === 'SPOT' && typeof offer.spot_price === 'number' ? offer.spot_price : offer.price;
+}
+/** Pages of the listing read at most: 50 GPU types each, more than the catalogue holds today. */
+const MAX_PAGES = 5;
+/** Offers a sandbox can be deployed on, matching the filter, cheapest first. Virtual machines only. */
+export async function findOffers(http, filter = {}) {
+    const search = filter.gpu?.replace(/\s+/g, '').toLowerCase() || undefined;
+    const offers = [];
+    // GPU count and price are filtered here, so read every page: a match can be on any of them.
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const res = await http.request('GET', '/api/gpu-offers', {
+            query: {
+                search,
+                computeType: 'gpu',
+                instanceType: filter.spot ? 'SPOT' : 'DEDICATED',
+                regions: filter.regions?.join(','),
+                providers: filter.providers?.join(','),
+                sortBy: 'price',
+                sortOrder: 'asc',
+                limit: 50,
+                page,
+            },
+        });
+        for (const group of res.data ?? []) {
+            for (const offer of group.offers ?? [])
+                offers.push({ ...offer, gpuType: group.gpuType });
+        }
+        if (!res.totalPages || page >= res.totalPages)
+            break;
+    }
+    const isSpot = (o) => String(o.instanceType).toUpperCase() === 'SPOT';
+    return offers
+        // The listing's instanceType filter lets some providers' spot offers through: a dedicated ask must never land
+        // on a VM that can be reclaimed (seen live on Spheron ES).
+        .filter((o) => isSpot(o) === !!filter.spot)
+        .filter((o) => o.available !== false && o.maintenance !== true)
+        .filter((o) => filter.gpuCount === undefined || o.gpuCount === filter.gpuCount)
+        .filter((o) => filter.maxHourlyPrice === undefined || hourlyPrice(o) <= filter.maxHourlyPrice)
+        .sort((a, b) => hourlyPrice(a) - hourlyPrice(b));
+}
+/**
+ * The operating system to deploy: the one asked for when the offer has it (exact, then by substring), else an
+ * Ubuntu image with CUDA, else any Ubuntu, else the first listed.
+ */
+export function pickOperatingSystem(offer, wanted) {
+    const options = offer.os_options ?? [];
+    if (wanted) {
+        const w = wanted.toLowerCase();
+        return options.find((o) => o.toLowerCase() === w) ?? options.find((o) => o.toLowerCase().includes(w)) ?? undefined;
+    }
+    return options.find((o) => /ubuntu/i.test(o) && /cuda/i.test(o)) ?? options.find((o) => /ubuntu/i.test(o)) ?? options[0];
+}
+//# sourceMappingURL=offers.js.map

package/dist/offers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offers.js","sourceRoot":"","sources":["../src/offers.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.d.ts

@@ -0,0 +1,140 @@
+import { Commands } from './commands.js';
+import { Files } from './files.js';
+import { type ClientOptions } from './http.js';
+import { type OfferFilter } from './offers.js';
+import type { Deployment, GpuOffer, SandboxStatus } from './types.js';
+export interface SandboxOptions extends ClientOptions {
+    /** How often a running command's output is read, at most. Default 2000 ms. */
+    pollIntervalMs?: number;
+}
+export interface WaitReadyOptions {
+    /** Give up after this long. Default 20 minutes. */
+    timeoutMs?: number;
+    /** Called when the phase changes: deploying, installing, then ready. */
+    onStatus?: (phase: ReadyPhase, status: SandboxStatus | null) => void;
+    /** How often the status is checked. Default 5000 ms. */
+    checkEveryMs?: number;
+    signal?: AbortSignal;
+}
+export type ReadyPhase = 'deploying' | 'installing' | 'ready';
+/** An offer picked by hand, for example from Sandbox.findOffers(). */
+export interface OfferChoice {
+    provider: string;
+    offerId: string;
+    gpuType: string;
+    gpuCount: number;
+    region?: string;
+    clusters?: string[];
+    instanceType?: string;
+    os_options?: string[];
+}
+export interface CreateOptions extends SandboxOptions, OfferFilter {
+    /** Deploy this exact offer instead of picking the cheapest match. */
+    offer?: OfferChoice | GpuOffer;
+    /** Operating system, matched against the offer's options. Default: Ubuntu with CUDA when listed. */
+    operatingSystem?: string;
+    /** Instance name. */
+    name?: string;
+    /** Team to deploy in. Default: your only team (required when you belong to several). */
+    teamId?: string;
+    /** A saved SSH key's id. Default: the team's first saved key. */
+    sshKeyId?: string;
+    /** A public key for this instance only (not saved). Use instead of sshKeyId. */
+    sshPublicKey?: string;
+    /** Volumes to attach at launch (same provider and region). */
+    volumeIds?: string[];
+    /** How many matching offers to try when one is sold out or cannot take the sandbox. Default 3. */
+    maxOfferAttempts?: number;
+    /** Wait until commands can run. Default true. */
+    waitUntilReady?: boolean;
+    /** How long to wait for it. Default 20 minutes. */
+    readyTimeoutMs?: number;
+    /** Called when the phase changes while waiting: deploying, installing, then ready. */
+    onStatus?: WaitReadyOptions['onStatus'];
+    /** How often the status is checked while waiting. Default 5000 ms. */
+    checkEveryMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * A Spheron Agent GPU Sandbox: a GPU VM you run commands on and move files to and from, over the Spheron API.
+ *
+ * ```ts
+ * const sandbox = await Sandbox.create({ gpu: 'h100', maxHourlyPrice: 3 });
+ * const r = await sandbox.commands.run('nvidia-smi');
+ * console.log(r.output);
+ * await sandbox.terminate();
+ * ```
+ *
+ * The instance bills at its normal hourly price from the moment it runs until it is stopped or terminated.
+ */
+export declare class Sandbox {
+    #private;
+    /** The deployment id. */
+    readonly id: string;
+    readonly commands: Commands;
+    readonly files: Files;
+    private constructor();
+    private get path();
+    /** Offers a sandbox can be deployed on, cheapest first. Pass one to Sandbox.create({ offer }). */
+    static findOffers(filter?: OfferFilter & ClientOptions): Promise<GpuOffer[]>;
+    /**
+     * Connect to an instance that already has a sandbox (deployed with it on, by this SDK, the API or an AI agent).
+     * Only the person who deployed it can use its sandbox.
+     */
+    static connect(deploymentId: string, opts?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * Deploy a GPU VM with the sandbox on and, by default, wait until commands can run.
+     *
+     * Picks the cheapest offer matching the filter (or deploys `offer`), and moves on to the next one when an offer
+     * is sold out or cannot take the sandbox. Set maxHourlyPrice so a scarce GPU never lands on a pricey offer.
+     * Once an instance exists, any error names it in `deploymentId`: it bills until it is terminated.
+     */
+    static create(opts?: CreateOptions): Promise<Sandbox>;
+    /** The sandbox's state: installing, ready, failed or removed, and whether the instance is reachable now. */
+    status(signal?: AbortSignal): Promise<SandboxStatus>;
+    /** The instance: status, IP, SSH command, GPU, region, hourly rate and so on. */
+    info(signal?: AbortSignal): Promise<Deployment>;
+    /**
+     * Wait until the instance runs and the sandbox is reachable. Throws SandboxFailedError when the install fails or
+     * the instance dies, and TimeoutError (the instance keeps running and billing) when it takes too long.
+     */
+    waitUntilReady(opts?: WaitReadyOptions): Promise<SandboxStatus>;
+    /** waitUntilReady, also for the moment after a Start when the instance still reads stopped. */
+    private waitReady;
+    /**
+     * Stop the instance: it keeps its disk and bills only storage. Commands fail until it is started again. By default
+     * this waits until the provider has finished stopping it, which can take minutes on a large machine.
+     */
+    stop(opts?: {
+        wait?: boolean;
+        timeoutMs?: number;
+        checkEveryMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Start a stopped instance, and by default wait until the sandbox is reachable again (timeoutMs covers both).
+     * While the provider is still stopping it, has no capacity yet or is busy, nothing changes and the start is tried
+     * again every retryEveryMs (default 30 s) for up to retryForMs (default 10 minutes).
+     */
+    start(opts?: {
+        waitUntilReady?: boolean;
+        retryEveryMs?: number;
+        retryForMs?: number;
+    } & WaitReadyOptions): Promise<void>;
+    /**
+     * Terminate the instance. It is deleted with its disk and stops billing. An instance must run for its offer's
+     * minimum runtime (usually 20 minutes) first: before then the API refuses with minimum_runtime_not_met.
+     */
+    terminate(): Promise<void>;
+    /** Uninstall the sandbox program. The instance keeps running and your SSH access is unaffected. */
+    removeSandbox(): Promise<void>;
+    /**
+     * POST pause or resume. A slow one answers 202 (or, from a server that ignores Prefer, 504) with the operation
+     * still running: both are handed back to follow, not thrown.
+     */
+    private lifecycleCall;
+    /** Wait for a Stop or Start to finish. Throws the operation's own error when it fails. */
+    private follow;
+    /** Runs fn and names this instance on any error it throws, wrapping errors that are not ours. */
+    private tagged;
+}