@promigence/sdk 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/models.gen.d.ts

@@ -359,7 +359,10 @@ export interface BuildJoined {
      */
     source: unknown;
     /**
-     * `queued` | `running` | `verified` | `rejected` | `failed`.
+     * `queued` | `running` | `verified` | `built` | `rejected` | `failed`. `built` is a
+     * finished build that stored its snapshot with no verification command to run (an image
+     * built without `verify`): done and ready to start, like `verified`, but nothing was
+     * verified.
      */
     state: string;
     tier: string;
@@ -371,8 +374,8 @@ export interface BuildJoined {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (stored, but nothing was verified). Nothing is stored and nothing is charged if
-     * the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
+     * is charged if the command exits non-zero.
      */
     verified: boolean;
     /**
@@ -402,7 +405,8 @@ export interface BuildLogView {
      */
     log: Array<string>;
     /**
-     * `queued` | `running` | `verified` | `rejected` | `failed`.
+     * `queued` | `running` | `verified` | `built` | `rejected` | `failed` (`built`: stored with
+     * no verification command to run).
      */
     state: string;
 }
@@ -506,7 +510,10 @@ export interface BuildView {
      */
     source: unknown;
     /**
-     * `queued` | `running` | `verified` | `rejected` | `failed`.
+     * `queued` | `running` | `verified` | `built` | `rejected` | `failed`. `built` is a
+     * finished build that stored its snapshot with no verification command to run (an image
+     * built without `verify`): done and ready to start, like `verified`, but nothing was
+     * verified.
      */
     state: string;
     tier: string;
@@ -518,8 +525,8 @@ export interface BuildView {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (stored, but nothing was verified). Nothing is stored and nothing is charged if
-     * the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
+     * is charged if the command exits non-zero.
      */
     verified: boolean;
     /**
@@ -821,6 +828,68 @@ export interface CliTokenCreate {
 export type Code = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "capacity_busy" | "verify_did_not_cover" | "nonzero_exit" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "cap_killed" | "cap_exceeded" | "aborted_by_client" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "enoent" | "trial_credits_exhausted" | "card_required" | "concurrency_limit" | "egress_cap_reached" | "network_policy_unsupported" | "network_host_refused" | "toolchain_mismatch" | "resume_unavailable" | "sandbox_unreachable" | "region_at_capacity" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "builder_unavailable" | "builder_busy" | "overloaded" | "preempted" | "grader_failed" | "grade_not_passed" | "shutdown_by_task" | "modified_by_task" | "cap_paused" | "credits_paused" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "secrets_in_snapshot" | "secrets_unavailable" | "secret_binding_unsupported" | "idempotency_key_reused" | "idempotency_key_in_use" | "repo_credentials_not_supported" | "account_exists" | "invite_invalid" | "invite_required" | "key_expired";
 export interface Concurrency {
 }
+/**
+ * One request to connect a code host (`github` or `gitlab`) to the organization, started by the
+ * person whose key or console session asked for it, and how it ended.
+ */
+export interface ConnectRequest {
+    /**
+     * The account on the code host, once it is known.
+     */
+    account?: string | null;
+    /**
+     * RFC 3339.
+     */
+    created_at: string;
+    /**
+     * RFC 3339: when it ended; absent while it is pending.
+     */
+    finished_at?: string | null;
+    /**
+     * One or two sentences for a person: what happened, then what to do next.
+     */
+    message: string;
+    /**
+     * `github` or `gitlab`.
+     */
+    provider: string;
+    /**
+     * `icr_` and 32 hex digits.
+     */
+    request_id: string;
+    /**
+     * `pending` while it is not finished; then how it ended: `connected`, `updated` (already
+     * connected to this organization; its repository access changed), `already_connected`,
+     * `pending_provider_approval` (an owner of the account must approve it on the code host
+     * first), `declined`, `other_org` (connected to another organization), `needs_admin`,
+     * `not_installer`, `wrong_user` (the connection page was opened signed in to another
+     * account), `expired` or `failed`.
+     */
+    state: string;
+}
+/**
+ * `POST /v1/integrations/{github,gitlab}/requests`: a connection started for you in the console.
+ * Open `connect_url` in a browser signed in to the console as you, then read
+ * `GET /v1/integrations/{github,gitlab}/requests/{request_id}` for how it ends.
+ */
+export interface ConnectTicket {
+    /**
+     * The console page that starts the connection: it carries the ticket and nothing else.
+     */
+    connect_url: string;
+    /**
+     * When the ticket stops working (RFC 3339): 5 minutes.
+     */
+    expires_at: string;
+    /**
+     * The connection request it starts (`icr_` and 32 hex digits).
+     */
+    request_id: string;
+    /**
+     * `ict_` and 32 hex digits: used once, by you only, within 5 minutes.
+     */
+    ticket_id: string;
+}
 export interface Cost {
     /**
      * Σ `billable_seconds` over the run's sandboxes.
@@ -1436,7 +1505,8 @@ export interface FileWritten {
      */
     chunks: number;
     /**
-     * The file's permission bits, octal (`644`).
+     * The file's permission bits after the write, octal (`644`). Without `?mode=` a file that
+     * already existed keeps its own, and a new file is `644`.
      */
     mode: string;
     /**
@@ -2105,7 +2175,9 @@ export interface InviteView {
  */
 export interface KeyCreate {
     /**
-     * `full` (the default) | `run` (use sandboxes, nothing else) | `read` (lists and reports).
+     * `full` (the default) | `run` (sandboxes, runs and builds, whose runs can use the project's
+     * stored secrets; no changes to secrets, keys or billing) | `read` (reads everything in the
+     * project, file contents and command output included; changes nothing).
      */
     access?: string | null;
     /**
@@ -2166,7 +2238,9 @@ export interface KeyRef {
  */
 export interface KeyView {
     /**
-     * What the key may do: `full`, `run` (use sandboxes) or `read` (lists and reports).
+     * What the key may do: `full`, `run` (sandboxes, runs and builds, whose runs can use the
+     * project's stored secrets; no changes to secrets, keys or billing) or `read` (reads
+     * everything in the project, file contents and command output included; changes nothing).
      */
     access?: string;
     /**
@@ -2354,8 +2428,8 @@ export interface Me {
      */
     location?: string | null;
     /**
-     * The same place as a short code for an icon: `us-east`, `us-west`, `us-midwest`, `eu-west` or
-     * `india`. Only beside `location`; a code you do not know is fine to ignore.
+     * The same place as a short code, for example `us-east`. Only beside `location`; new codes may
+     * appear, and a code you do not know is fine to ignore.
      */
     location_code?: string | null;
     /**
@@ -2540,7 +2614,9 @@ export interface OrgDeleted {
  */
 export interface OrgKeyCreate {
     /**
-     * `full` (the default) | `run` (use sandboxes, nothing else) | `read` (lists and reports).
+     * `full` (the default) | `run` (sandboxes, runs and builds, whose runs can use the project's
+     * stored secrets; no changes to secrets, keys or billing) | `read` (reads everything in the
+     * project, file contents and command output included; changes nothing).
      */
     access?: string | null;
     /**
@@ -2577,7 +2653,9 @@ export interface OrgKeyCreate {
  */
 export interface OrgKeyView {
     /**
-     * What the key may do: `full`, `run` (use sandboxes) or `read` (lists and reports).
+     * What the key may do: `full`, `run` (sandboxes, runs and builds, whose runs can use the
+     * project's stored secrets; no changes to secrets, keys or billing) or `read` (reads
+     * everything in the project, file contents and command output included; changes nothing).
      */
     access?: string;
     /**
@@ -3423,7 +3501,7 @@ export interface Run {
  */
 export interface RunCanceled {
     /**
-     * How many queued sandboxes were dropped. They were never started and are never billed.
+     * How many queued sandboxes were dropped. They were never started, so they are not billed.
      */
     canceled: number;
     ok: boolean;
@@ -4642,13 +4720,13 @@ export interface SecretStored {
      */
     next: Array<string>;
     /**
-     * What a sandbox that names this secret is given in its place: it works in requests to the
-     * bound hosts and nowhere else. Present when `hosts` is.
+     * What the variable holds, in place of the value, in a sandbox that names this secret.
+     * Present when `hosts` is.
      */
     placeholder?: string | null;
     /**
-     * `refused` when the value itself can never be given to a sandbox, `allowed` otherwise.
-     * Present when `hosts` is.
+     * `refused` when the value itself can never be given to a sandbox, `allowed` (the default)
+     * otherwise. Present when `hosts` is.
      */
     raw?: string | null;
     /**
@@ -4656,11 +4734,10 @@ export interface SecretStored {
      */
     updated_at: string;
     /**
-     * For each of `hosts`, in the same order, the address a sandbox sends its requests to,
-     * with the request's path added after it. Requests sent there are authenticated with the
-     * secret; a request made straight to the host (`https://<host>/…`)
-     * carries the placeholder, and the host refuses it. For a `*.` host, put the name
-     * in place of the `*`. Present when `hosts` is.
+     * For each of `hosts`, in the same order, the address a sandbox sends that host's requests
+     * to, with the request's path added after it. Requests sent there are authenticated with the
+     * secret; a request sent straight to the host is not. For a `*.` host, put the name in place
+     * of the `*`. Present when `hosts` is.
      */
     urls?: Array<string>;
 }
@@ -4687,14 +4764,15 @@ export interface SecretSummary {
     headers?: Array<string>;
     /**
      * The hosts the secret is bound to. Absent when it is not bound: a sandbox that names it is
-     * then given the value itself. When present, a sandbox is given a placeholder instead,
-     * which works in requests to these hosts and nowhere else.
+     * then given the value itself. When present, requests to these hosts sent through `urls`
+     * are authenticated with it, and the value stays out of the sandbox unless a run asks for
+     * it and `raw` allows it.
      */
     hosts?: Array<string>;
     name: string;
     /**
-     * `refused` when the value itself can never be given to a sandbox, `allowed` otherwise.
-     * Present when `hosts` is.
+     * `refused` when the value itself can never be given to a sandbox, `allowed` (the default)
+     * otherwise. Present when `hosts` is.
      */
     raw?: string | null;
     /**
@@ -4726,8 +4804,9 @@ export interface SecretUseBound {
      */
     as?: string | null;
     /**
-     * `raw` delivers the value itself to a secret bound to hosts; omitted, such a secret is
-     * delivered as a placeholder that only works toward its hosts.
+     * `raw` gives the command the value itself of a secret bound to hosts (refused when the
+     * secret's `raw` is `refused`); omitted, the value stays out of the sandbox and requests to
+     * its hosts sent through its `urls` are authenticated with it.
      */
     mode?: SecretUseMode | null;
     /**
@@ -4867,6 +4946,14 @@ export interface SnapshotCreate {
      * Build from a Dockerfile.
      */
     dockerfile?: DockerfileSource | null;
+    /**
+     * Image and Dockerfile forms: environment variables for every command, terminal and SSH
+     * session in sandboxes from this snapshot (and for its own `setup`, `verify` and `start`),
+     * set over the image's own `ENV` as `docker run -e` sets them. A value may build on a
+     * variable the image sets with `${containerEnv:NAME}`, or `${containerEnv:NAME:default}`
+     * when the image may not set it: `"PATH": "${containerEnv:PATH}:/opt/tools/bin"`.
+     */
+    env?: Record<string, string>;
     /**
      * `github:` repositories: the snapshot the build starts from, by id or alias. Default
      * `promigence/base`.
@@ -4998,7 +5085,7 @@ export interface SnapshotDeduped {
      */
     source: unknown;
     /**
-     * `verified`.
+     * `verified`, or `built` when the snapshot was stored with no verification command to run.
      */
     state: string;
     /**

package/dist/proxy.d.ts

@@ -1,3 +1,16 @@
+/**
+ * `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY` for the SDK and the CLI.
+ *
+ * Node's built-in `fetch` ignores the proxy variables (Node 22 has no `NODE_USE_ENV_PROXY`), so
+ * behind a corporate proxy the CLI could not reach the API while the Python SDK, which honours
+ * them, could. This is a small `fetch` over `node:http`/`node:https` that goes through the proxy
+ * the environment names: an `http://` URL is sent to the proxy in absolute form, an `https://` URL
+ * through a `CONNECT` tunnel with TLS to the API inside it (the proxy never sees the key). It is
+ * used only when a proxy variable applies to the API's host; otherwise nothing changes.
+ *
+ * No dependency: the proxy agents live in the `undici` package, which this SDK does not ship.
+ */
+import { type ClientRequest, type RequestOptions } from "node:http";
 type FetchLike = typeof globalThis.fetch;
 /** Does `NO_PROXY` exempt `host` (`*`, an exact name, a `.suffix` or `suffix`, with an optional port)? */
 export declare function noProxy(host: string, port: string, env?: NodeJS.ProcessEnv): boolean;
@@ -8,4 +21,11 @@ export declare function proxyFor(url: string, env?: NodeJS.ProcessEnv): URL | un
  * sends JSON and file chunks of at most 16 MiB); response bodies stream.
  */
 export declare function proxyFetch(proxy: URL): FetchLike;
+/**
+ * `node:http(s).request(url, options)`, through the proxy the environment names for `url` when one
+ * applies ([`proxyFor`]): an https URL over a `CONNECT` tunnel with TLS to the server inside it
+ * (the proxy never sees what is sent), an http URL in absolute form. For what `fetch` cannot
+ * carry: the terminal's and the SSH tunnel's WebSocket upgrades. With no proxy, the plain request.
+ */
+export declare function requestVia(url: URL, options: RequestOptions, env?: NodeJS.ProcessEnv): ClientRequest;
 export {};

package/dist/proxy.js

@@ -169,3 +169,38 @@ export function proxyFetch(proxy) {
     };
     return fetchViaProxy;
 }
+export function requestVia(url, options, env = process.env) {
+    const proxy = proxyFor(url.href, env);
+    if (!proxy)
+        return (url.protocol === "https:" ? httpsRequest : httpRequest)(url, options);
+    const proxyRequest = proxy.protocol === "https:" ? httpsRequest : httpRequest;
+    const proxyPort = Number(proxy.port || (proxy.protocol === "https:" ? 443 : 80));
+    if (url.protocol === "http:") {
+        return proxyRequest({
+            ...options, host: proxy.hostname, port: proxyPort, path: url.href,
+            headers: { ...options.headers, host: url.host, ...proxyAuth(proxy) },
+        });
+    }
+    const port = Number(url.port || 443);
+    const createConnection = (_opts, done) => {
+        const connect = proxyRequest({
+            host: proxy.hostname, port: proxyPort, method: "CONNECT", path: `${url.hostname}:${port}`,
+            headers: { host: `${url.hostname}:${port}`, ...proxyAuth(proxy) },
+        });
+        connect.on("error", (e) => done(e));
+        connect.on("connect", (res, socket) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                done(new Error(`the proxy ${proxy.host} refused CONNECT ${url.host} (HTTP ${res.statusCode})`));
+                return;
+            }
+            done(null, tlsConnect({ socket, servername: url.hostname, ALPNProtocols: ["http/1.1"] }));
+        });
+        connect.end();
+        return undefined;
+    };
+    return httpsRequest(url, {
+        ...options,
+        createConnection: createConnection,
+    });
+}

package/dist/pty.js

@@ -1,7 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 import { CALLER_HEADER } from "./caller.js";
+import { requestVia } from "./proxy.js";
 export const PTY_INPUT_CHUNK = 64 * 1024;
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 export const PTY_COMMAND_HEADER = "promigence-pty-command";
@@ -143,7 +142,7 @@ export class PtySession {
 export function connectPty(opts) {
     const url = new URL(opts.url);
     const key = randomBytes(16).toString("base64");
-    const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+    const req = requestVia(url, {
         method: "GET",
         headers: {
             connection: "Upgrade",

package/dist/sandbox.d.ts

@@ -224,9 +224,10 @@ interface SandboxInit {
     timeoutMs?: number;
 }
 /**
- * The snapshot `Sandbox.create()` forks when it is given none: Debian 12 + Python 3.12, node/npm,
- * git, curl, jq, gcc/make, `small` tier (built in, not verified). It is always ready to start. The template
- * name `'base'` means the same thing.
+ * The snapshot `Sandbox.create()` forks when it is given none: Debian 12 + Python 3.12 (pip, venv, uv),
+ * Node 24 (npm), Bun, Go 1.27, Docker, git, Git LFS, the GitHub CLI, curl, jq, ripgrep, rsync, gcc/make,
+ * and the Claude Code, Codex, Gemini CLI and OpenCode agents, `small` tier (built in, not verified). It
+ * is always ready to start. The template name `'base'` means the same thing.
  */
 export declare const DEFAULT_SNAPSHOT = "promigence/base";
 /**
@@ -297,8 +298,14 @@ export declare class Sandbox {
         read(path: string, opts: {
             format: "bytes";
         }): Promise<Uint8Array>;
-        /** Text is written as UTF-8; bytes as they are (a typed array, an `ArrayBuffer` or a `Blob`). */
-        write(path: string, data: string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob): Promise<void>;
+        /**
+         * Text is written as UTF-8; bytes as they are (a typed array, an `ArrayBuffer` or a `Blob`).
+         * A file that already exists keeps its mode, as a shell `>` or an editor's save does; a new
+         * one is `0o644`. `{ mode: 0o755 }` sets the mode either way.
+         */
+        write(path: string, data: string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob, opts?: {
+            mode?: number;
+        }): Promise<void>;
         remove(path: string, opts?: {
             recursive?: boolean;
         }): Promise<void>;

package/dist/sandbox.js

@@ -59,7 +59,7 @@ export function toEntryInfoFromPath(f) {
     return toEntryInfo({ ...f, name: at < 0 ? f.path : f.path.slice(at + 1) });
 }
 function buildIsFree(b) {
-    return b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified";
+    return b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified" || b.state === "built";
 }
 function buildNotice(image) {
     return (b) => {
@@ -350,7 +350,7 @@ export class Sandbox {
                 const bytes = await this.#client.sandboxes.files.get(this.sandboxId, path);
                 return format === "bytes" ? bytes : new TextDecoder().decode(bytes);
             }),
-            write: async (path, data) => {
+            write: async (path, data, opts = {}) => {
                 let body;
                 if (typeof data === "string" || data instanceof Uint8Array)
                     body = data;
@@ -364,7 +364,7 @@ export class Sandbox {
                     throw new InvalidArgumentError(`files.write data must be a string, a typed array, an ArrayBuffer or a Blob, got ${data === null ? "null" : typeof data}`, "Pass text, or the bytes as a Uint8Array.");
                 }
                 this.dirty = true;
-                await this.#client.sandboxes.files.put(this.sandboxId, path, body, {});
+                await this.#client.sandboxes.files.put(this.sandboxId, path, body, opts.mode === undefined ? {} : { mode: opts.mode });
             },
             remove: async (path, opts = {}) => {
                 this.dirty = true;

package/dist/ssh.js

@@ -1,12 +1,11 @@
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 import { randomBytes } from "node:crypto";
 import { CALLER_HEADER } from "./caller.js";
+import { requestVia } from "./proxy.js";
 import { FrameReader, encodeFrame, wsAccept } from "./pty.js";
 export function connectSshTunnel(opts) {
     const url = new URL(opts.url);
     const key = randomBytes(16).toString("base64");
-    const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+    const req = requestVia(url, {
         method: "GET",
         headers: {
             connection: "Upgrade",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "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",