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

package/dist/cjs/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/cjs/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/cjs/proxy.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noProxy = noProxy;
 exports.proxyFor = proxyFor;
 exports.proxyFetch = proxyFetch;
+exports.requestVia = requestVia;
 const node_http_1 = require("node:http");
 const node_https_1 = require("node:https");
 const node_tls_1 = require("node:tls");
@@ -174,3 +175,38 @@ function proxyFetch(proxy) {
     };
     return fetchViaProxy;
 }
+function requestVia(url, options, env = process.env) {
+    const proxy = proxyFor(url.href, env);
+    if (!proxy)
+        return (url.protocol === "https:" ? node_https_1.request : node_http_1.request)(url, options);
+    const proxyRequest = proxy.protocol === "https:" ? node_https_1.request : node_http_1.request;
+    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, (0, node_tls_1.connect)({ socket, servername: url.hostname, ALPNProtocols: ["http/1.1"] }));
+        });
+        connect.end();
+        return undefined;
+    };
+    return (0, node_https_1.request)(url, {
+        ...options,
+        createConnection: createConnection,
+    });
+}

package/dist/cjs/pty.js

@@ -5,9 +5,8 @@ exports.wsAccept = wsAccept;
 exports.encodeFrame = encodeFrame;
 exports.connectPty = connectPty;
 const node_crypto_1 = require("node:crypto");
-const node_http_1 = require("node:http");
-const node_https_1 = require("node:https");
 const caller_js_1 = require("./caller.js");
+const proxy_js_1 = require("./proxy.js");
 exports.PTY_INPUT_CHUNK = 64 * 1024;
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 exports.PTY_COMMAND_HEADER = "promigence-pty-command";
@@ -151,7 +150,7 @@ exports.PtySession = PtySession;
 function connectPty(opts) {
     const url = new URL(opts.url);
     const key = (0, node_crypto_1.randomBytes)(16).toString("base64");
-    const req = (url.protocol === "https:" ? node_https_1.request : node_http_1.request)(url, {
+    const req = (0, proxy_js_1.requestVia)(url, {
         method: "GET",
         headers: {
             connection: "Upgrade",

package/dist/cjs/sandbox.d.ts

@@ -297,8 +297,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/cjs/sandbox.js

@@ -69,7 +69,7 @@ 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) => {
@@ -360,7 +360,7 @@ 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;
@@ -374,7 +374,7 @@ class Sandbox {
                     throw new core_js_1.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/cjs/ssh.js

@@ -1,15 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.connectSshTunnel = connectSshTunnel;
-const node_http_1 = require("node:http");
-const node_https_1 = require("node:https");
 const node_crypto_1 = require("node:crypto");
 const caller_js_1 = require("./caller.js");
+const proxy_js_1 = require("./proxy.js");
 const pty_js_1 = require("./pty.js");
 function connectSshTunnel(opts) {
     const url = new URL(opts.url);
     const key = (0, node_crypto_1.randomBytes)(16).toString("base64");
-    const req = (url.protocol === "https:" ? node_https_1.request : node_http_1.request)(url, {
+    const req = (0, proxy_js_1.requestVia)(url, {
         method: "GET",
         headers: {
             connection: "Upgrade",

package/dist/client.d.ts

@@ -5,7 +5,7 @@ import { type Bundle } from "./bundle.js";
 import { type PtyExit, type PtySession } from "./pty.js";
 import { type SshTunnel } from "./ssh.js";
 import type * as M from "./models.gen.js";
-import { type GithubConnect, type GithubDisconnected, type GithubRepos, type GithubStatus, type GithubUntracked } from "./github.js";
+import { type ConnectRequest, type ConnectTicket, type GithubConnect, type GithubDisconnected, type GithubRepos, type GithubStatus, type GithubUntracked } from "./github.js";
 import { type GitlabConnect, type GitlabDisconnected, type GitlabRepos, type GitlabStatus, type GitlabUntracked } from "./gitlab.js";
 export type FetchLike = typeof globalThis.fetch;
 /**
@@ -343,7 +343,8 @@ export interface RunReport {
     [extra: string]: unknown;
 }
 /** A build of a snapshot (`POST /snapshots`, `GET /snapshots/builds/:id`). */
-export type BuildState = "queued" | "running" | "verified" | "rejected" | "failed";
+/** `built`: finished and stored with no verification command to run; done, like `verified`. */
+export type BuildState = "queued" | "running" | "verified" | "built" | "rejected" | "failed";
 export interface SecretRecord {
     name: string;
     /** Length of the stored value, so a caller can sanity-check without reading it. */
@@ -353,9 +354,9 @@ export interface SecretRecord {
     updated_at?: string;
     /**
      * The hosts the secret is bound to. Absent when it is not bound: a sandbox that names it is
-     * then given the value. When present, the sandbox never sees the value: requests it sends to the
-     * host's address in `urls` are authenticated with the secret; a request made straight to
-     * `https://<host>/` is not.
+     * then given the value. When present, requests the sandbox sends to the host's address in
+     * `urls` are authenticated with the secret, a request made straight to `https://<host>/` is not,
+     * and the value stays out of the sandbox unless a run asks for it (`raw`).
      */
     hosts?: string[];
     /**
@@ -364,7 +365,7 @@ export interface SecretRecord {
      */
     urls?: string[];
     /**
-     * The variables a sandbox that names this secret is also given, each pointed at its host's
+     * The variables a sandbox that names this secret is also given, each set to its host's
      * address in `urls`: `OPENAI_BASE_URL` for `api.openai.com`, `ANTHROPIC_BASE_URL` for
      * `api.anthropic.com`. Absent when there is none. A variable the caller sets itself wins.
      */
@@ -379,10 +380,10 @@ export interface SecretRecord {
     scan_responses?: boolean;
 }
 /**
- * `secrets.set` options: bind the secret to hosts. A sandbox that names a bound secret never sees
- * its value: requests it sends to the host's address the answer gives in `urls` (and to
- * `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL` for those providers) are authenticated with it, and
- * one sent straight to the host is not.
+ * `secrets.set` options: bind the secret to hosts. Requests a sandbox sends to the host's address
+ * the answer gives in `urls` (and to `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL` for those
+ * providers) are authenticated with it, one sent straight to the host is not, and the value stays
+ * out of the sandbox unless a run asks for it (`raw: "refused"` forbids that; the default allows it).
  *
  * Every option left out keeps what the secret already has, so setting a bound secret again with
  * a new value (a rotation) keeps its binding. `hosts: []` removes it.
@@ -1478,8 +1479,8 @@ export interface SandboxNetworkCut {
  * secrets: ["OPENAI_API_KEY", { name: "work_secret_7", as: "ANTHROPIC_WORK_SECRET" }]
  * ```
  *
- * A secret bound to hosts (`secrets.set(name, value, { hosts })`) arrives as its placeholder;
- * `mode: "raw"` asks for the value itself, and is refused for one stored with `raw: "refused"`.
+ * A secret bound to hosts (`secrets.set(name, value, { hosts })`) does not put its value in the
+ * sandbox; `mode: "raw"` asks for the value itself, and is refused for one stored with `raw: "refused"`.
  */
 export type SecretBinding = string | {
     name: string;
@@ -1649,6 +1650,14 @@ export interface SnapshotCreateOpts {
     verify?: VerifySpec;
     /** Image forms: a background process started before the snapshot, so forks inherit it running. */
     start?: string | string[];
+    /**
+     * Image and Dockerfile forms: environment variables for every command, terminal and SSH
+     * session in this snapshot's sandboxes (and its own setup, verify and start), set over the
+     * image's `ENV` as `docker run -e` sets them. A value may build on what the image sets with
+     * `${containerEnv:NAME}` (or `${containerEnv:NAME:default}`):
+     * `{ PATH: "${containerEnv:PATH}:/opt/tools/bin" }`.
+     */
+    env?: Record<string, string>;
     tier?: Tier;
     /** Image forms: the name of a stored secret holding the registry credentials. */
     registrySecret?: string;
@@ -1772,28 +1781,6 @@ export declare function imageRefNamesVersion(image: string): boolean;
 export declare function checkImageVersioned(image: string): void;
 /** A git context, pinned: `https://github.com/org/app@<40 hex>`. A branch is not a pin. */
 export declare const CONTEXT_GIT_RE: RegExp;
-/** The prefix a packed directory travels under. */
-export declare const CONTEXT_TAR_PREFIX = "tar;base64,";
-/**
- * Directories never worth sending. `.dockerignore` is **not** applied to a context that fits: it
- * is sent with the context and the build applies it, so honouring it twice could only disagree
- * with the build. The cost is that editing an ignored file still changes the snapshot's
- * identity, which is the safe direction to be wrong in. Only a context over the limit — one that
- * would be refused anyway — is packed again without what its `.dockerignore` excludes.
- */
-export declare const CONTEXT_SKIP: Set<string>;
-/**
- * A `.dockerignore`, as the build reads it: one pattern a line, `#` comments, `!` re-includes,
- * Go `filepath.Match` syntax plus `**`, anchored at the context root, and a pattern that matches a
- * directory matches everything under it. The last pattern that matches a path decides. Returns
- * `undefined` for a file with no patterns.
- */
-export declare function dockerignoreMatcher(text: string): {
-    ignored: (rel: string) => boolean;
-    exceptions: boolean;
-} | undefined;
-/** The server's limit, refused here so a 9 MB context does not cross the wire to be told no. */
-export declare const CONTEXT_MAX_BYTES: number;
 /**
  * What in a repository URL can carry a credential: a user name, password or token (`https://TOKEN@…`,
  * `https://user:pass@…`, `:token@`, a percent-encoded `@`, any `@` in a scheme URL, the scp form's
@@ -1813,19 +1800,6 @@ export declare const REPO_CREDENTIALS_FIX: string;
 export declare function checkRepoUrl(url: unknown, field: string): void;
 /** Refuse a context that is neither a pinned git URL nor a packed directory. */
 export declare function checkDockerfileContext(context: unknown): asserts context is string;
-/**
- * Pack a directory into the string `dockerfile.context` takes.
- *
- * The archive is only transport: the snapshot's identity is computed from the *entries* server
- * side, so this does not have to agree byte-for-byte with `sdk-py`'s packer — and two calls on
- * an unchanged directory give the same snapshot either way.
- */
-export declare function packContext(dir: string, opts?: {
-    maxBytes?: number;
-    keep?: readonly string[];
-}): string;
-/** The Dockerfile's path as the context sees it, for `dockerfile.path`. */
-export declare function contextRelative(contextDir: string, dockerfilePath: string): string;
 /**
  * The `POST /snapshots` body for one of its three forms; throws `InvalidArgumentError` before
  * anything is sent. Kept field-for-field with `sdk-py` (`_ops.snapshot_create_body`) so the two
@@ -2115,6 +2089,14 @@ export declare class PromigenceClient {
         status: () => Promise<GithubStatus>;
         /** `POST /integrations/github/connect` — the install link (15 minutes); open it in a browser. */
         connect: () => Promise<GithubConnect>;
+        /**
+         * `POST /integrations/github/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/github/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
         /** `DELETE /integrations/github/installations/:id` — nothing is built from that account any more. */
         disconnect: (installationId: number | string) => Promise<GithubDisconnected>;
         /** `GET /integrations/github/repos` — one page (at most 100) across every connection. */
@@ -2135,6 +2117,14 @@ export declare class PromigenceClient {
         status: () => Promise<GitlabStatus>;
         /** `POST /integrations/gitlab/connect` — the authorize link (15 minutes); open it in a browser. */
         connect: () => Promise<GitlabConnect>;
+        /**
+         * `POST /integrations/gitlab/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/gitlab/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
         /** `DELETE /integrations/gitlab/connections/:id` — revoked on GitLab; nothing is built through it any more. */
         disconnect: (connectionId: string) => Promise<GitlabDisconnected>;
         /** `GET /integrations/gitlab/repos` — one page (at most 100) of one connection's projects. */
@@ -2636,6 +2626,9 @@ export declare class PromigenceClient {
              * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file, and the
              * thrown error carries how far it got (`written` in the error's evidence).
              * Re-running the same `put` is safe: chunk 0 truncates.
+             *
+             * `mode` (`0o755`) sets the file's permission bits. Without it a file that already exists
+             * keeps its mode, as a shell `>` does, and a new one is `0o644`.
              */
             put: (sandboxId: string, path: string, data: string | Uint8Array, opts?: {
                 mode?: number;