@promigence/sdk 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/pty.d.ts

@@ -1,11 +1,14 @@
 /**
  * Interactive terminals: `GET /v1/sandboxes/:id/pty` over a WebSocket (RFC 6455).
  *
- * The protocol:
+ * The protocol (`promigence.pty.v2`):
  *
- *   client → server  binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
+ *   client → server  first, one text frame `{"start":{"cmd"?,"secrets"?}}`: what to run and the secret
+ *                    names it gets, inside the connection, never in a header or the URL; then
+ *                    binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
  *   server → client  binary = terminal output; text = `{"event":"open",…}` first and
- *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame
+ *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame. A terminal that
+ *                    cannot open says so in its first frame: `{"event":"error","status",…}`, then Close.
  *
  * Zero dependencies, so this is a small client over `node:http` rather than the global
  * `WebSocket`: that one cannot send an `Authorization` header, and a key in the query string is
@@ -32,26 +35,20 @@ export interface PtyExit {
         message: string;
     };
 }
-/** The header the terminal's command travels in, base64. Never a query parameter. */
-export declare const PTY_COMMAND_HEADER = "promigence-pty-command";
-/** The header the terminal's secret **names** travel in, base64 JSON. */
-export declare const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+/** The WebSocket subprotocol a terminal speaks: its first message is `{"start": {"cmd"?, "secrets"?}}`. */
+export declare const PTY_PROTOCOL = "promigence.pty.v2";
 export interface PtyConnectOpts {
     /** `http(s)://host[:port]/v1/sandboxes/<id>/pty?cols=&rows=` — dimensions only. */
     url: string;
     apiKey: string;
     userAgent: string;
     /**
-     * The command to run, sent as a header rather than in the URL.
-     *
-     * It used to be `?cmd=`, with `envs` composed into it as `export K=v;` — so a terminal opened
-     * with an API key in its environment wrote that key into the query string of every request,
-     * and therefore into every access log along the path. Names and values both stay out of the
-     * URL now.
+     * The command to run. Sent in the terminal's first message, inside the connection: never in a
+     * header or the URL, where a log on the way could keep it.
      */
     command?: string;
     /** Stored secret names (or `{name, as}` bindings), resolved server-side into the terminal's
-     *  environment. JSON, base64, in a header. */
+     *  environment. Sent in the first message with the command. */
     secrets?: unknown[];
     /** The `promigence-caller` label, when one is set (`setCaller`). */
     caller?: string;

package/dist/pty.js

@@ -5,8 +5,10 @@ export const PTY_INPUT_CHUNK = 64 * 1024;
 export const PTY_INPUT_KEEP = 256 * 1024;
 export const PTY_RESUME_HEADER = "promigence-resume";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-export const PTY_COMMAND_HEADER = "promigence-pty-command";
-export const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+export const PTY_PROTOCOL = "promigence.pty.v2";
+export function ptyStartMessage(command, secrets) {
+    return JSON.stringify({ start: { ...(command ? { cmd: command } : {}), ...(secrets?.length ? { secrets } : {}) } });
+}
 export function wsAccept(key) {
     return createHash("sha1").update(key + WS_GUID).digest("base64");
 }
@@ -250,15 +252,7 @@ function openLeg(opts, url, resume) {
             authorization: `Bearer ${opts.apiKey}`,
             "user-agent": opts.userAgent,
             ...(opts.caller ? { [CALLER_HEADER]: opts.caller } : {}),
-            ...(resume ? { [PTY_RESUME_HEADER]: resume } : {}),
-            ...(opts.command && !resume
-                ? { [PTY_COMMAND_HEADER]: Buffer.from(opts.command, "utf8").toString("base64") }
-                : {}),
-            ...(opts.secrets?.length && !resume
-                ? {
-                    [PTY_SECRETS_HEADER]: Buffer.from(JSON.stringify(opts.secrets), "utf8").toString("base64"),
-                }
-                : {}),
+            ...(resume ? { [PTY_RESUME_HEADER]: resume } : { "sec-websocket-protocol": PTY_PROTOCOL }),
         },
     });
     let resolveEnded;
@@ -291,6 +285,8 @@ function openLeg(opts, url, resume) {
                 return;
             }
             socket.setNoDelay(true);
+            if (!resume)
+                socket.write(encodeFrame(0x1, Buffer.from(ptyStartMessage(opts.command, opts.secrets), "utf8")));
             const reader = new FrameReader();
             let exit;
             let closeCode;
@@ -328,6 +324,12 @@ function openLeg(opts, url, resume) {
                                 ...(typeof v["wall_ms"] === "number" ? { wallMs: v["wall_ms"] } : {}),
                             };
                         }
+                        else if (v["event"] === "error" && !wasOpen && typeof v["status"] === "number") {
+                            const e = (v["error"] && typeof v["error"] === "object" ? v["error"] : { code: v["code"], message: v["message"] });
+                            fail(v["status"], JSON.stringify({ error: e }), typeof v["retry_after"] === "string" ? v["retry_after"] : undefined);
+                            socket.destroy();
+                            return;
+                        }
                         else if (v["event"] === "error" || v["event"] === "closed") {
                             exit = {
                                 exitCode: null, signal: null,

package/dist/sandbox.d.ts

@@ -14,6 +14,8 @@ import { type CommandResult, type CommandRunOpts, type ForkOpts, type OptimizeFo
 import { PromigenceClient, type BackgroundExecRecord, type DirEntry, type DirListOpts, type ExtractResult, type FileInfo, type FileMatch, type Page, type PortRecord, type AutoPauseMode, type SandboxRecord, type SearchOpts, type SecretBinding, type SnapshotBuild, type VerifySpec } from "./client.js";
 import { CommandHandle } from "./handles.js";
 import type { PtyExit, PtySession, PtySize } from "./pty.js";
+/** `setTimeout`'s fix when the longer timeout does not fit under the run's spend cap. */
+export declare const EXTEND_OVER_CAP_FIX: string;
 /**
  * `commands.run` options for a foreground command. The call resolves with the whole result when
  * the command ends; `onStdout` / `onStderr` also receive its output as it is written.
@@ -150,6 +152,8 @@ export interface SandboxCreateOpts extends SandboxOpts {
     start?: string | string[];
     tier?: Tier;
     alias?: string;
+    /** With `alias`: take the name from the snapshot that has it (refused without this). */
+    moveAlias?: boolean;
     /** Name of a stored secret holding the registry credentials. */
     registrySecret?: string;
     /** Bound on the first build of an image (default 15 min). Expiry cancels nothing. */
@@ -196,7 +200,7 @@ export interface SandboxCreateOpts extends SandboxOpts {
  * inputs) was built before, or 202 with a `build_id`. The **body**, not the status, decides: an
  * idempotency replay answers 202 with a document that may already be `verified`.
  */
-export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
+export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "moveAlias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
      * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
      * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
@@ -312,7 +316,14 @@ export declare class Sandbox {
         resize(pid: number, size: PtySize): Promise<void>;
         kill(pid: number): Promise<boolean>;
     };
-    /** Preview URLs for ports inside the sandbox (`getHost` gives the address alone). */
+    /**
+     * Preview URLs for ports inside the sandbox (`getHost` gives the address alone).
+     *
+     * Anyone holding a preview URL can open it; revoke it any time, and it ends with the sandbox.
+     * If your account's preview URLs aren't on, `expose` throws `PreviewsUnavailableError`; write to
+     * support@promigence.ai to have them turned on, and meanwhile reach the port with
+     * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
+     */
     readonly ports: {
         expose(port: number): Promise<PortRecord>;
         list(): Promise<PortRecord[]>;
@@ -458,13 +469,16 @@ export declare class Sandbox {
     }>;
     isRunning(): Promise<boolean>;
     /**
-     * `PATCH /sandboxes/:id` — extend this sandbox's timeout.
+     * `PATCH /sandboxes/:id` — set this sandbox's timeout, in milliseconds.
      *
-     * The timeout is the sandbox's total lifetime, not "from now", and the difference is billing:
-     * commits *seconds* up front and `billable_seconds <= committed_seconds`, so an extension is a new
-     * commitment that has to fit under the spend cap you set (the run's, or the org default). It throws
-     * `SpendCapError` (409) rather than silently extending — which is the behaviour a spend
-     * cap exists to produce, and the one difference here worth a caller knowing about.
+     * The timeout is the sandbox's total lifetime, counted from its start, not from now:
+     * `setTimeout(600_000)` on a sandbox that has run 2 minutes leaves it 8 more.
+     *
+     * - Raising it commits the added seconds, which has to fit in what is left of the spend cap you set
+     *   (the run's, or the org default): past it, it throws `SpendCapError` (409) rather than silently
+     *   extending.
+     * - Lowering it goes down to what the sandbox has run plus 60 s, and no further
+     *   (`InvalidArgumentError` below that). To stop it now, `kill()` it.
      */
     setTimeout(ms: number): Promise<void>;
     /**
@@ -500,6 +514,10 @@ export declare class Sandbox {
      *
      * Async, because the address is a capability minted on demand rather than
      * a hostname derived from the id. An existing URL for the port is reused, not re-minted.
+     *
+     * If your account's preview URLs aren't on, this throws `PreviewsUnavailableError`; write to
+     * support@promigence.ai to have them turned on, and meanwhile reach the port with
+     * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
      */
     getHost(port: number): Promise<string>;
     /**

package/dist/sandbox.js

@@ -1,9 +1,11 @@
 import { inspect } from "node:util";
-import { ApiError, CommandExitError, EnvFailedError, IMAGE_BUILD_TIMEOUT_MS, InvalidArgumentError, NotFoundError, TimeoutError, UnsupportedError, WAIT_TIMEOUT_MS, withPreviewsFix, } from "./core.js";
+import { ApiError, CommandExitError, EnvFailedError, IMAGE_BUILD_TIMEOUT_MS, InvalidArgumentError, NotFoundError, SpendCapError, TimeoutError, UnsupportedError, WAIT_TIMEOUT_MS, withPreviewsFix, } from "./core.js";
 import { PromigenceClient, LONG_POLL_MS, checkImageRef, checkImageVersioned, checkSandboxId, errorFor, newIdempotencyKey, toCommandResult, isWaiting, } from "./client.js";
 import { CommandHandle } from "./handles.js";
 import { CommandTimeoutError, answerTimedOut } from "./command-errors.js";
 import { hintArg } from "./hint.js";
+export const EXTEND_OVER_CAP_FIX = "Raising the timeout must fit in what is left of the run's spend cap, and this does not: start a new " +
+    "sandbox with the longer `timeoutMs` and a `spendCap` that covers it.";
 const EXEC_TIMEOUT_DEFAULT_MS = 15 * 60_000;
 function textSink(cb) {
     if (!cb)
@@ -37,6 +39,15 @@ export function ptyCommand(opts) {
     parts.push(opts.cmd ?? DEFAULT_PTY_CMD);
     return parts.join(" ");
 }
+function allowList(hosts) {
+    if (!Array.isArray(hosts)) {
+        throw new InvalidArgumentError("allowHosts must be a list of hosts", 'Pass allowHosts: ["github.com"].');
+    }
+    if (!hosts.some((h) => typeof h !== "string" || h.trim() !== "")) {
+        throw new InvalidArgumentError("allowHosts names no host, so the allow-list is empty", 'Name each host the sandbox may reach: allowHosts: ["github.com"]. For no network pass allowInternetAccess: false; to reach anything leave allowHosts out.');
+    }
+    return hosts;
+}
 function permString(mode) {
     const r = (m) => `${m & 4 ? "r" : "-"}${m & 2 ? "w" : "-"}${m & 1 ? "x" : "-"}`;
     return r((mode >> 6) & 7) + r((mode >> 3) & 7) + r(mode & 7);
@@ -89,6 +100,8 @@ export async function imageSnapshot(client, opts, hooks = {}) {
         create.tier = opts.tier;
     if (opts.alias !== undefined)
         create.alias = opts.alias;
+    if (opts.moveAlias)
+        create.moveAlias = true;
     if (opts.registrySecret !== undefined)
         create.registrySecret = opts.registrySecret;
     let build = (await client.snapshots.create(create)) ?? {};
@@ -362,6 +375,9 @@ export class Sandbox {
                 return format === "bytes" ? bytes : new TextDecoder().decode(bytes);
             }),
             write: async (path, data, opts = {}) => {
+                if (typeof path !== "string") {
+                    throw new InvalidArgumentError(`files.write takes one path and its data; got ${Array.isArray(path) ? "an array" : path === null ? "null" : typeof path} as the path`, "Write each file with its own call: for (const f of files) await sandbox.files.write(f.path, f.data).");
+                }
                 let body;
                 if (typeof data === "string" || data instanceof Uint8Array)
                     body = data;
@@ -556,8 +572,8 @@ export class Sandbox {
             start.timeoutMs = opts.timeoutMs;
         if (opts.allowInternetAccess === false)
             start.network = "none";
-        if (opts.allowHosts?.length)
-            start.network = { allow: opts.allowHosts };
+        if (opts.allowHosts !== undefined && opts.allowHosts !== null)
+            start.network = { allow: allowList(opts.allowHosts) };
         if (opts.metadata)
             start.labels = opts.metadata;
         if (opts.secrets?.length)
@@ -695,7 +711,15 @@ export class Sandbox {
         return rec.state === "ready" || rec.state === "running";
     }
     async setTimeout(ms) {
-        await this.#client.sandboxes.patch(this.sandboxId, { timeoutMs: ms });
+        try {
+            await this.#client.sandboxes.patch(this.sandboxId, { timeoutMs: ms });
+        }
+        catch (e) {
+            if (e instanceof SpendCapError && e.code === "cap_exceeded") {
+                Object.defineProperty(e, "fix", { value: EXTEND_OVER_CAP_FIX, enumerable: true, configurable: true });
+            }
+            throw e;
+        }
         this.timeoutMs = ms;
     }
     async setAutoPause(seconds, mode) {

package/dist/transport-worker.js

@@ -290,6 +290,7 @@ function start(init) {
     let rrAny = 0;
     let pumpTimer;
     let pumpSoon;
+    let turnsHeld = false;
     const freeNow = (l, now) => {
         for (let i = 0; i < l.length; i++) {
             const k = (rr + i) % l.length;
@@ -304,6 +305,8 @@ function start(init) {
     const pump = () => {
         pumpTimer = undefined;
         pumpSoon = undefined;
+        if (turnsHeld)
+            return;
         while (waiting.length > 0) {
             const l = live();
             if (l.length === 0) {
@@ -346,7 +349,7 @@ function start(init) {
             rrAny = (rrAny % l.length) + 1;
             return e;
         }
-        if (waiting.length === 0) {
+        if (waiting.length === 0 && !turnsHeld) {
             const now = hrNow();
             const e = freeNow(l, now);
             if (e !== undefined) {
@@ -527,6 +530,12 @@ function start(init) {
         }
         else if (m?.t === "crash-for-test")
             setImmediate(() => { throw new Error("transport thread crash (test)"); });
+        else if (m?.t === "hold-turns-for-test")
+            turnsHeld = true;
+        else if (m?.t === "release-turns-for-test") {
+            turnsHeld = false;
+            pump();
+        }
     });
     void open();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.16",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",