@promigence/sdk 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/client.js

@@ -2,7 +2,7 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { inspect } from "node:util";
 import { dirname, join } from "node:path";
-import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, ERRORS_DOCS_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, exitForCode, previewsOff, withPreviewsFix, } from "./core.js";
+import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, ERRORS_DOCS_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, exitForCode, previewsOff, withPreviewsFix, } from "./core.js";
 import { buildBundle } from "./bundle.js";
 import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
@@ -135,7 +135,7 @@ function decodeCredentials(buf) {
         return buf.subarray(3).toString("utf8");
     return buf.toString("utf8");
 }
-export function storedCredentials(env = process.env) {
+export function storedCredentials(env = process.env, platform = process.platform) {
     const path = credentialsPath(env);
     let present = true;
     try {
@@ -145,7 +145,7 @@ export function storedCredentials(env = process.env) {
         present = e.code !== "ENOENT";
     }
     if (!present) {
-        const store = keychainStore(env);
+        const store = keychainStore(env, platform);
         if (store === undefined)
             return undefined;
         const r = keychainReadCached(store, path, env);
@@ -259,8 +259,6 @@ export function keyOrigin(env = process.env) {
     const stored = readCredentialsWithStore(env);
     if (stored.creds.api_key)
         return stored.store === "macos-keychain" ? "macOS Keychain" : stored.store === "secret-service" ? "Secret Service keyring" : "credentials file";
-    if (compatApiKey(env["E2B_API_KEY"]))
-        return "E2B_API_KEY (compat)";
     return undefined;
 }
 function resolveCredentials(opts, env = process.env) {
@@ -269,17 +267,19 @@ function resolveCredentials(opts, env = process.env) {
         const t = u.replace(/\/+$/, "");
         return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
     };
-    const { creds, store } = readCredentialsWithStore(env);
     const envKey = set(env["PROMIGENCE_API_KEY"]?.trim());
     const envUrl = set(env["PROMIGENCE_API_URL"]);
     const optKey = opts.apiKey?.trim();
+    const given = optKey !== undefined || envKey !== undefined;
+    const { creds, store } = given
+        ? { creds: {}, store: undefined }
+        : readCredentialsWithStore(env);
     const source = optKey !== undefined ? "opts" : envKey !== undefined ? "env" : creds.api_key !== undefined ? "file" : undefined;
     const ours = optKey ?? envKey ?? creds.api_key;
-    const compat = ours === undefined ? compatApiKey(env["E2B_API_KEY"]) : undefined;
-    const compatUrl = compat === undefined
-        ? undefined
-        : apiUrlFromCompatUrl(env["E2B_API_URL"]) ?? apiUrlFromCompatDomain(env["E2B_DOMAIN"]);
-    const fromFile = trim(creds.api_url ?? compatUrl ?? DEFAULT_API_URL);
+    const fallback = ours === undefined ? opts.fallbackKey : undefined;
+    const fallbackKey = set(fallback?.apiKey.trim());
+    const fallbackUrl = fallbackKey === undefined ? undefined : set(fallback?.apiUrl);
+    const fromFile = trim(creds.api_url ?? fallbackUrl ?? DEFAULT_API_URL);
     const fromEnv = envUrl !== undefined ? trim(envUrl) : fromFile;
     const apiUrl = opts.apiUrl !== undefined ? trim(opts.apiUrl) : fromEnv;
     const paired = source === "file" ? fromFile : source === "env" ? fromEnv : apiUrl;
@@ -291,10 +291,10 @@ function resolveCredentials(opts, env = process.env) {
             : "Pass apiKey together with apiUrl, or set PROMIGENCE_API_URL to that URL instead of passing apiUrl.");
         return { apiKey: undefined, apiUrl, refusal };
     }
-    const key = ours ?? compat;
+    const key = ours ?? fallbackKey;
     if (key) {
         const from = source === "opts" ? "the apiKey option" : source === "env" ? "PROMIGENCE_API_KEY"
-            : source === "file" ? storedName(store, env) : "E2B_API_KEY";
+            : source === "file" ? storedName(store, env) : fallback.from;
         const refusal = keyRefusal(key, from);
         if (refusal)
             return { apiKey: undefined, apiUrl, refusal };
@@ -652,6 +652,7 @@ export function errorFor(code, message, fix, extra = {}) {
         case "invalid_argument":
             return attach(new InvalidArgumentError(message, extra.cli ? fix : withoutCliHelp(fix), code));
         case "not_released": return attach(new NotReleasedError(message));
+        case "service_restart": return attach(new ServiceRestartError(message, fix));
         default:
             if (ENV_CODES.has(code) || extra.category === "env")
                 return attach(new EnvFailedError(code, message, fix));
@@ -1258,6 +1259,14 @@ export class PromigenceClient {
             const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
             return pageOf(r, "entries", limit);
         },
+        historyPage: async (opts = {}) => {
+            const limit = opts.limit ?? 50;
+            const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
+            if (opts.kind !== undefined && opts.kind !== "all")
+                q.set("kind", opts.kind);
+            const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
+            return pageOf(r, "entries", limit);
+        },
         checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
         portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
         referrals: () => this.request({ method: "GET", path: "/referrals" }),
@@ -1752,6 +1761,10 @@ export class PromigenceClient {
                             on.heartbeat?.();
                             continue;
                         }
+                        if (event === "reconnect") {
+                            reader.cancel().catch(() => { });
+                            throw new ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
+                        }
                         let parsed = {};
                         try {
                             parsed = JSON.parse(data);
@@ -1987,6 +2000,9 @@ export class PromigenceClient {
                 ...(opts.onData ? { onData: opts.onData } : {}),
                 ...(opts.onExit ? { onExit: opts.onExit } : {}),
                 ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
+                ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
                 refuse: (status, text, retryAfter) => {
                     let payload = {};
                     try {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.7";
+export declare const VERSION = "0.1.0-beta.8";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
@@ -190,6 +190,15 @@ export declare class TimeoutError extends PromigenceError {
         runId?: string;
     });
 }
+/**
+ * A service update may stop a command that was running while its output was streaming to you
+ * (`execStream`, `commands.run` with output callbacks); the time it ran is credited back, and the
+ * sandbox keeps running. `retryable` is `false`: the command may have done part of its work before
+ * it stopped, so run it again only if that is safe. exit 3
+ */
+export declare class ServiceRestartError extends PromigenceError {
+    constructor(message: string, fix: string);
+}
 /** An API error with no more specific class (5xx, unknown code). exit from the table. */
 export declare class ApiError extends PromigenceError {
 }

package/dist/core.js

@@ -1,5 +1,5 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.7";
+export const VERSION = "0.1.0-beta.8";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";
@@ -194,6 +194,11 @@ export class TimeoutError extends PromigenceError {
         this.runId = ids.runId;
     }
 }
+export class ServiceRestartError extends PromigenceError {
+    constructor(message, fix) {
+        super({ code: "service_restart", message, fix, exitCode: 3, category: "env", retryable: false });
+    }
+}
 export class ApiError extends PromigenceError {
 }
 export class NotReleasedError extends PromigenceError {
@@ -210,6 +215,7 @@ export const EXIT_BY_CODE = {
     invalid_argument: 2, unsupported: 2, not_released: 1, task_failed: 4,
     env_failed: 3, snapshot_rejected: 6, build_failed: 3, snapshot_failed: 4,
     not_connected: 7,
+    service_restart: 3,
     fork_failed: 3, start_timeout: 3, readiness_failed: 3, verify_too_slow: 3,
     verify_each_failed: 3, toolchain_mismatch: 3, sandbox_unresponsive: 3, oom_within_tier: 3,
     disk_full_within_tier: 3, sandbox_interrupted: 3, integrity_mismatch: 3, egress_unavailable: 3,
@@ -236,10 +242,11 @@ export const EXIT_BY_CODE = {
     build_timeout: 4,
     image_unresolvable: 2,
     registry_unavailable: 3,
-    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 10,
+    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 5,
     billing_unavailable: 5,
     project_cap_reached: 5,
     spend_limit_reached: 5,
+    billing_hold: 5,
     tier_over_plan: 2,
     network_host_refused: 9, network_policy_unsupported: 3,
     secrets_in_snapshot: 2, secrets_unavailable: 3,

package/dist/credstore.d.ts

@@ -3,7 +3,8 @@
  * the credentials file (`~/.config/promigence/credentials`, 0600). The CLI writes it
  * (`promigence login`, `promigence auth login`, `promigence logout`); the CLI and both SDKs read it.
  *
- *   macOS            the login Keychain, through `security` (when HOME holds one)
+ *   macOS            the login Keychain, through `security` (when the user's home holds one: HOME,
+ *                    or the account's own home when the environment has no HOME)
  *   Linux and BSD    the Secret Service (GNOME Keyring, KWallet), through `secret-tool`, when a
  *                    desktop session bus is there (a CI job or an SSH shell has none: the file)
  *   Windows          the file: no tool that ships with Windows can read a stored secret back
@@ -34,7 +35,7 @@ export declare function storeLabel(store: CredentialStore, path?: string): strin
  * The keychain this process stores a sign-in in, or undefined for the file. `auto` is decided by
  * the platform and by whether its tool (and, for the Secret Service, a session bus) is there.
  */
-export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string): KeychainStore | undefined;
+export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string, home?: () => string): KeychainStore | undefined;
 /**
  * The keychains a sign-out (or a sign-in that lands in the file) must clear for this path: the one
  * in use, and the platform's own even when `PROMIGENCE_CREDENTIAL_STORE=file` (an item a previous

package/dist/credstore.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 export const KEYCHAIN_SERVICE = "promigence-cli";
 const KEYCHAIN_LABEL = "Promigence CLI credentials";
@@ -30,8 +31,19 @@ function sessionBus(env) {
     const run = env["XDG_RUNTIME_DIR"];
     return Boolean(run) && existsSync(join(run, "bus"));
 }
+function userHome(env, home = homedir) {
+    const h = env["HOME"];
+    if (h)
+        return h;
+    try {
+        return home() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const warnedSetting = new Set();
-export function keychainStore(env = process.env, platform = process.platform) {
+export function keychainStore(env = process.env, platform = process.platform, home = homedir) {
     const raw = (env["PROMIGENCE_CREDENTIAL_STORE"] ?? "").trim().toLowerCase();
     switch (raw) {
         case "file": return undefined;
@@ -46,8 +58,8 @@ export function keychainStore(env = process.env, platform = process.platform) {
             }
     }
     if (platform === "darwin") {
-        const home = env["HOME"];
-        return home && existsSync(join(home, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
+        const h = userHome(env, home);
+        return h && existsSync(join(h, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
     }
     if (platform === "win32")
         return undefined;
@@ -94,8 +106,9 @@ function runTool(store, args, env, input, timeout) {
     const bin = onPath(toolName(store), env);
     if (bin === undefined)
         throw Object.assign(new Error(`${toolName(store)} not found`), { code: "ENOENT" });
+    const h = store === "macos-keychain" && !env["HOME"] ? userHome(env) : undefined;
     return execFileSync(bin, args, {
-        encoding: "utf8", timeout, env,
+        encoding: "utf8", timeout, env: h ? { ...env, HOME: h } : env,
         ...(input === undefined ? { stdio: ["ignore", "pipe", "pipe"] } : { input, stdio: ["pipe", "pipe", "pipe"] }),
     });
 }

package/dist/models.gen.d.ts

@@ -243,6 +243,36 @@ export interface BackgroundExecList {
     execs: Array<BackgroundExec>;
     sandbox_id: string;
 }
+/**
+ * `GET /v1/billing/history` — your billing history, newest first: every credit you received and
+ * every payment, one page at a time.
+ */
+export interface BillingHistory {
+    entries: Array<BillingHistoryEntry>;
+    /**
+     * Pass as `cursor` for the next, older page; `null` on the last page.
+     */
+    next_cursor?: string | null;
+}
+/**
+ * One entry of your billing history: a credit you received or a payment. Exactly one of
+ * `credit` and `payment` is set.
+ */
+export interface BillingHistoryEntry {
+    /**
+     * When it happened, RFC 3339: when a credit was added, when a payment was made, failed or
+     * was refunded.
+     */
+    at: string;
+    /**
+     * A credit you received; `null` for a payment.
+     */
+    credit?: CreditGrant | null;
+    /**
+     * A payment; `null` for a credit.
+     */
+    payment?: Payment | null;
+}
 /**
  * The billing period `usage` covers.
  */
@@ -261,9 +291,9 @@ export interface BillingPeriod {
     start: string;
 }
 /**
- * `GET /v1/billing` — plan, card on file, this month's usage, and the upcoming invoice
- * preview. Never fails because the payment provider is slow: the estimate is the only part
- * that asks it, and its failure is a field, not a status.
+ * `GET /v1/billing` — plan, card on file, this month's usage, and the upcoming invoice preview.
+ * Never fails because the payment provider is slow: the estimate is the only part that asks it,
+ * and its failure is a field, not a status.
  */
 export interface BillingStatus {
     /**
@@ -274,11 +304,22 @@ export interface BillingStatus {
      * `null` while no card is on file.
      */
     card?: CardOnFile | null;
+    /**
+     * A sentence to show beside the card when it does not unlock paid limits for this
+     * organization (it already pays for another one, or it is being confirmed with a $1 charge, or
+     * that charge did not go through); `null` otherwise.
+     */
+    card_note?: string | null;
     card_on_file: boolean;
     /**
      * True once a billing customer exists for the organisation.
      */
     customer: boolean;
+    /**
+     * The $1 that confirms the payment method on file when it has no stable payer (Apple Pay,
+     * Google Pay, Amazon Pay); `null` when it needed none.
+     */
+    method_check?: MethodCheckView | null;
     notice?: TrialNotice | null;
     org_id: string;
     period: BillingPeriod;
@@ -830,7 +871,7 @@ export interface CliTokenCreate {
 /**
  * Every error and failure code the API returns.
  */
-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" | "stopped_by_support" | "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" | "account_blocked" | "setup_required";
+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" | "stopped_by_support" | "forbidden" | "snapshot_incompatible" | "storage_limit_reached" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "credit_unclaimed" | "billing_unavailable" | "project_cap_reached" | "spend_limit_reached" | "billing_hold" | "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" | "account_blocked" | "setup_required";
 export interface Concurrency {
 }
 /**
@@ -916,6 +957,41 @@ export interface CreditClaim {
     terms_version?: string | null;
     token?: string | null;
 }
+/**
+ * A credit your organization received, and what is left of it.
+ */
+export interface CreditGrant {
+    /**
+     * When it expires, RFC 3339; `null` when it never expires.
+     */
+    expires_at?: string | null;
+    /**
+     * When it was added, RFC 3339.
+     */
+    granted_at: string;
+    /**
+     * USD.
+     */
+    granted_usd: number;
+    /**
+     * What it is: `free_credit` (the free credit), `card_bonus` (credit for adding a card),
+     * `referral` (a referral reward), `plan` (usage included with a paid plan),
+     * `from_promigence` (credit Promigence added to your account), `service_restart` (credit
+     * for a command a service restart stopped), `confirmation_credit` (a $1 charge that
+     * confirmed a payment method, added back as credit), or `other`.
+     */
+    kind: string;
+    /**
+     * What is left of it, USD: 0 once it is used, expired or taken back. Credit that expires
+     * soonest is used first, and credit that never expires last.
+     */
+    remaining_usd: number;
+    /**
+     * `active` (some of it is left), `used` (all of it was used), `expired` (it expired before
+     * all of it was used), or `taken_back`.
+     */
+    status: string;
+}
 /**
  * The account's free credit (`GET /v1/credits/offer`, and the answer to a claim). The credit is
  * claimed in the browser, where the terms are accepted: `POST /v1/credits/claim-link` makes the
@@ -942,6 +1018,11 @@ export interface CreditOffer {
      * One sentence for a person.
      */
     message: string;
+    /**
+     * USD charged to confirm a payment method with no stable payer when it is added (Apple Pay,
+     * Google Pay, Amazon Pay): it is added to your credit, and the card bonus comes with it.
+     */
+    method_check_usd?: number;
     /**
      * `claimable`, `claimed`, `pending_review`, `needs_card`, `not_eligible`, `offer_ended`,
      * `denied` or `none`.
@@ -1075,7 +1156,7 @@ export interface ErrorBody {
 /**
  * Every error code the API returns. `category` decides whether the failure is billed: `env` is ours (not billed before hand-over; after it, the time since the sandbox's last snapshot is credited back, up to 24 hours, when our side shows the cause), `task` is your command and is billed. The full table is `x-promigence-error-codes` at the document root.
  */
-export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "stopped_by_support" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "setup_required" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "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" | "account_blocked";
+export type ErrorCode = "fork_failed" | "start_timeout" | "readiness_failed" | "verify_too_slow" | "verify_each_failed" | "toolchain_mismatch" | "sandbox_unresponsive" | "oom_within_tier" | "disk_full_within_tier" | "sandbox_interrupted" | "integrity_mismatch" | "egress_unavailable" | "service_timeout" | "preempted" | "verify_did_not_cover" | "grader_failed" | "nonzero_exit" | "grade_not_passed" | "task_timeout" | "oom_over_tier" | "disk_over_tier" | "shutdown_by_task" | "modified_by_task" | "cap_killed" | "cap_exceeded" | "cap_paused" | "credits_paused" | "aborted_by_client" | "stopped_by_support" | "expired" | "not_started" | "superseded" | "usage" | "internal" | "auth" | "forbidden" | "not_found" | "unreachable" | "rate_limited" | "timeout" | "not_verified" | "snapshot_incompatible" | "storage_limit_reached" | "resume_unavailable" | "sandbox_unreachable" | "capacity_busy" | "region_at_capacity" | "builder_unavailable" | "builder_busy" | "overloaded" | "tier_unavailable" | "snapshot_unavailable" | "capacity_limit" | "build_timeout" | "dockerfile_build_failed" | "image_unresolvable" | "registry_unavailable" | "enoent" | "trial_credits_exhausted" | "credit_unclaimed" | "setup_required" | "card_required" | "billing_unavailable" | "concurrency_limit" | "egress_cap_reached" | "project_cap_reached" | "spend_limit_reached" | "billing_hold" | "tier_over_plan" | "network_host_refused" | "network_policy_unsupported" | "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" | "account_blocked";
 /**
  * `POST /v1/sandboxes/{id}/execs`, and the `exec` of `POST /v1/runs`: one command. `argv` (a
  * non-empty list) or `sh` (a shell line) is required.
@@ -2547,6 +2628,29 @@ export interface MemberView {
      */
     you: boolean;
 }
+/**
+ * The $1 charged to confirm a payment method with no stable payer (`GET /v1/billing`
+ * `method_check`).
+ */
+export interface MethodCheckView {
+    /**
+     * USD charged; added to your credit once paid.
+     */
+    amount_usd: number;
+    /**
+     * USD of credit that came with it (the card bonus), once paid; `null` otherwise.
+     */
+    bonus_usd?: number | null;
+    /**
+     * The method as a person reads it: `Apple Pay`, `Google Pay`, `Amazon Pay`, ...
+     */
+    method: string;
+    /**
+     * `confirming` (charged, its answer not in yet), `paid` (it counts as your payment method) or
+     * `failed` (declined, or it needed you there to approve it: it does not count; add a card).
+     */
+    status: string;
+}
 /**
  * `POST /v1/orgs` and `POST /v1/orgs/{org}/projects`.
  */
@@ -2814,6 +2918,44 @@ export interface ParkedBytes {
      */
     allocated: number;
 }
+/**
+ * A payment: an invoice paid, a payment that failed, a refund, or the charge that confirmed a
+ * payment method.
+ */
+export interface Payment {
+    /**
+     * USD: what was paid, what was due, what was refunded, or what confirmed the method.
+     */
+    amount_usd: number;
+    /**
+     * The invoice's number, as the invoice shows it; `null` when not known.
+     */
+    invoice_number?: string | null;
+    /**
+     * The invoice's page: its receipt once it is paid, where to pay it while a payment has
+     * failed; `null` when not known.
+     */
+    invoice_url?: string | null;
+    /**
+     * `invoice_paid`, `payment_failed`, `refund`, or `method_check` (a charge, usually $1, that
+     * confirmed a payment method; it comes back as credit).
+     */
+    kind: string;
+    /**
+     * `method_check`: the payment method it confirmed, by name (`Apple Pay`); `null` otherwise.
+     */
+    method?: string | null;
+    /**
+     * The plan whose fee the invoice billed; `null` when it billed usage alone.
+     */
+    plan?: string | null;
+    /**
+     * `paid` (for a payment that failed: paid since), `retrying` (it failed and will be tried
+     * again), `failed` (it failed and will not be tried again; for `method_check`, the method
+     * was not confirmed), `refunded`, or `confirmed` (`method_check`: the method is confirmed).
+     */
+    status: string;
+}
 export interface Percentiles {
     p50: number;
     p95: number;
@@ -4502,7 +4644,7 @@ export interface SandboxView {
      */
     outcome?: string | null;
     /**
-     * While it is paused: when it will be deleted, with its memory and files, unless it is
+     * While it is paused: when it will be deleted, with its files and state, unless it is
      * resumed before then (RFC 3339). A paused sandbox is kept for 30 days, and resuming it
      * starts the 30 days again. Absent while it is not paused, and for a paused sandbox that is
      * not due to be deleted.

package/dist/proxy.js

@@ -199,8 +199,9 @@ export function requestVia(url, options, env = process.env) {
         connect.end();
         return undefined;
     };
+    const { agent: _agent, ...direct } = options;
     return httpsRequest(url, {
-        ...options,
+        ...direct,
         createConnection: createConnection,
     });
 }

package/dist/pty.d.ts

@@ -13,6 +13,10 @@
  */
 /** Largest terminal input frame sent; the server's cap is 1 MiB per client frame. */
 export declare const PTY_INPUT_CHUNK: number;
+/** How much of what was typed a session keeps, to send again to a terminal picked up again. */
+export declare const PTY_INPUT_KEEP: number;
+/** The header a terminal is picked up again with (its resume token). */
+export declare const PTY_RESUME_HEADER = "promigence-resume";
 export interface PtySize {
     cols: number;
     rows: number;
@@ -53,6 +57,33 @@ export interface PtyConnectOpts {
     caller?: string;
     onData?: (data: Uint8Array) => void;
     onExit?: (exit: PtyExit) => void;
+    /**
+     * Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+     * terminal cannot be picked up again ([`resume`]). The session goes on over a new connection,
+     * with its callbacks, its size and what was typed meanwhile, in a NEW shell: what ran in the old
+     * one has ended. Tried for up to 30 s ([`PTY_RECONNECT_FOR_MS`]); past that the session ends with
+     * `error.code` `"service_restart"`.
+     *
+     * Default: on for a shell, off when `command` is set (reconnecting starts the command again,
+     * which may not be safe to run twice); `true` or `false` decides either way.
+     */
+    reconnect?: boolean;
+    /**
+     * Pick the same terminal up again when its connection drops or the service restarts (default
+     * on): the terminal keeps running for a short while, and the session picks up where it left off
+     * over a new connection, with what was typed meanwhile delivered once — the same shell, or the
+     * same command, still running. Where it cannot be picked up (it ended meanwhile, or too much time
+     * passed), a restart falls back to [`reconnect`]; a dropped connection ends the session, as
+     * before.
+     */
+    resume?: boolean;
+    /**
+     * Called after each reconnect: `resumed` is `true` when it is the same terminal picked up
+     * again, `false` when it is a new shell (what ran in the old one has ended).
+     */
+    onReconnected?: (how: {
+        resumed: boolean;
+    }) => void;
     /** Handshake bound (default 30 s). The session itself has none. */
     timeoutMs?: number;
     /** Maps a refused upgrade (`status`, body text, its `Retry-After`) onto the SDK's error classes. */
@@ -80,15 +111,28 @@ export declare class FrameReader {
  */
 export declare class PtySession {
     #private;
-    private readonly socket;
-    /** The id of the terminal's process inside the sandbox (`req_id`); what `pty.kill(pid)` addresses. */
+    private socket;
+    /**
+     * The id of the terminal's process inside the sandbox (`req_id`); what `pty.kill(pid)`
+     * addresses. It names this session: it stays the same after a reconnect.
+     */
     readonly pid: number;
     cols: number;
     rows: number;
     private closed;
     private readonly done;
+    /** Frames written while the session reconnects, sent once it has (at most 1 MiB). */
+    private pending;
+    /** Keystrokes written to a connection, in all, and the last of them, from `inputBase` on: what a
+     *  terminal picked up again did not take is sent again. */
+    private inputSent;
+    private inputBase;
+    private inputLog;
     /** `true` once the terminal has ended (its exit arrived, or the socket closed). */
     get ended(): boolean;
+    private flush;
+    /** Write a frame to the connection now, counting keystrokes. */
+    private writeNow;
     private send;
     /** Keystrokes / a paste. A string is sent as UTF-8. */
     write(data: string | Uint8Array): void;
@@ -105,5 +149,23 @@ export declare class PtySession {
      */
     disconnect(): void;
 }
-/** Open a terminal. Rejects with `opts.refuse(...)` if the server does not switch protocols. */
+/** The `Close` code a terminal is asked to reconnect with: 1012, "service restart" (RFC 6455's registry). */
+export declare const PTY_RECONNECT_CODE = 1012;
+/** How long a terminal tries to reconnect before it ends (`error.code` `"service_restart"`). */
+export declare const PTY_RECONNECT_FOR_MS = 30000;
+/** The first wait before a reconnect, doubled each try up to [`PTY_RECONNECT_MAX_WAIT_MS`]; each wait is jittered (50-100 %). */
+export declare const PTY_RECONNECT_FIRST_WAIT_MS = 250;
+export declare const PTY_RECONNECT_MAX_WAIT_MS = 4000;
+/** How a session that could not reconnect within [`PTY_RECONNECT_FOR_MS`] ends. */
+export declare const PTY_RESTART_EXIT: PtyExit;
+/** How a session that is not to reconnect (`reconnect` off, or a command's) ends at a 1012. */
+export declare const PTY_RESTART_CLOSED_EXIT: PtyExit;
+/**
+ * Open a terminal. Rejects with `opts.refuse(...)` if the server does not switch protocols.
+ *
+ * When its connection drops, or the service asks it to reconnect (`Close` 1012), the session goes
+ * on over a new connection: the same terminal picked up again where the service still holds it
+ * ([`PtyConnectOpts.resume`]), else, at a restart, a new shell ([`PtyConnectOpts.reconnect`]).
+ * `wait()` resolves only when the session really ends.
+ */
 export declare function connectPty(opts: PtyConnectOpts): Promise<PtySession>;