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

package/dist/models.gen.d.ts

@@ -72,7 +72,9 @@ export interface AuthConfig {
      */
     console_authorize_url?: string | null;
     /**
-     * The sign-in buttons to offer, as name -> label.
+     * The sign-in methods to offer, as name -> label (`email`, `google`, `github`). A client that
+     * asks the sign-in pages for one method passes the label as their `identity_provider`, except
+     * `email`, which is the pages' own form and needs none.
      */
     identity_providers: Record<string, string>;
     /**
@@ -81,7 +83,6 @@ export interface AuthConfig {
      * account signs in as before either way.
      */
     invite_mode?: boolean;
-    issuer: string;
     /**
      * The redirect URIs a command-line client may listen on.
      */
@@ -90,10 +91,6 @@ export interface AuthConfig {
      * Where a headless sign-in lands instead, to show a code to paste back.
      */
     paste_redirect_uri: string;
-    /**
-     * Which identity service is in front of the API.
-     */
-    provider: string;
     scopes: Array<string>;
     token_url: string;
 }
@@ -246,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.
  */
@@ -264,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 {
     /**
@@ -277,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;
@@ -660,7 +698,15 @@ export interface CaptureView {
  * The card on file, enough to recognise it.
  */
 export interface CardOnFile {
+    /**
+     * The card's brand (`visa`, `mastercard`, ...); for a card held in a wallet, the wallet
+     * (`apple_pay`, `google_pay`); for another payment method, its kind (`link`, `cashapp`,
+     * `amazon_pay`).
+     */
     brand?: string | null;
+    /**
+     * The card's last four digits; `null` for a payment method without a card number.
+     */
     last4?: string | null;
 }
 /**
@@ -825,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" | "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 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 {
 }
 /**
@@ -911,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
@@ -937,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`.
@@ -1070,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" | "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" | "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";
+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.
@@ -1989,9 +2075,10 @@ export interface Guard {
  */
 export interface Health {
     /**
-     * The commit this build came from; empty for a local build.
+     * The commit this build came from; empty for a local build. Answered to a caller with a key;
+     * absent for one without.
      */
-    build_sha: string;
+    build_sha?: string;
     /**
      * Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service
      * does not say.
@@ -2541,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`.
  */
@@ -2737,7 +2847,7 @@ export interface OtherUsage {
     amount: number;
     entries: number;
 }
-export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted";
+export type Outcome = "completed" | "task_failed" | "env_failed" | "snapshot_failed" | "aborted_by_client" | "expired" | "cap_killed" | "not_started" | "superseded" | "grader_failed" | "preempted" | "stopped_by_support";
 /**
  * `GET /v1/me/outcomes?period=month` — what the organization (with a project's key: that project)
  * got this period, measured from its own runs and sandboxes. A figure with nothing behind it is
@@ -2808,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;
@@ -3075,10 +3223,10 @@ export interface PricingTier {
     vcpus: number;
 }
 /**
- * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force, read on every
- * call from the same place billing charges from. Without a key: what a new account gets. With a
- * key: what that key's organisation pays. A run is billed at the rates in force when it was
- * created, so a later change to these values never reprices a run already started.
+ * `GET /v1/pricing` — the prices, sandbox shapes, limits and free credit in force for the key's
+ * organisation, read on every call from the same place billing charges from. A key is required.
+ * A run is billed at the rates in force when it was created, so a later change to these values
+ * never reprices a run already started.
  */
 export interface PricingView {
     /**
@@ -3118,9 +3266,9 @@ export interface PricingView {
      */
     monthly_minimum_usd: number;
     /**
-     * The organisation these values are for; `null` for `new_account`.
+     * The organisation these values are for.
      */
-    org_id?: string | null;
+    org_id: string;
     plan: PricingPlan;
     rates: PricingRates;
     /**
@@ -3128,8 +3276,7 @@ export interface PricingView {
      */
     schema: string;
     /**
-     * `new_account` (asked without a key): what a new account gets. `organization` (asked with a
-     * key): what that key's organisation pays.
+     * `organization`: what the key's organisation pays.
      */
     scope: string;
     /**
@@ -4434,6 +4581,11 @@ export interface SandboxView {
      * once it has started; absent from list rows.
      */
     cost_usd?: number | null;
+    /**
+     * When the sandbox was created, RFC 3339: when its run was started, or when the retry or
+     * replay that made it was asked for.
+     */
+    created_at: string;
     /**
      * Milliseconds from the start request, after any time queued, to the sandbox being handed
      * over: it does not include `queued_ms`. Add `queued_ms` for the whole wait.
@@ -4491,6 +4643,13 @@ export interface SandboxView {
      * Why it ended; `null` while it is still alive.
      */
     outcome?: string | null;
+    /**
+     * 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.
+     */
+    pause_expires_at?: string | null;
     /**
      * Why it is paused, when a limit paused it rather than a request: `spend_cap` (its run
      * reached its spend cap) or `credits_exhausted` (the organization's credits ran out). Its
@@ -4528,6 +4687,11 @@ export interface SandboxView {
      */
     run_id: string;
     sandbox_id: string;
+    /**
+     * The snapshot it was started from, as its run names it (`GET /v1/runs/{id}`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
+    snapshot_id: string;
     /**
      * `queued` | `ready` | `running` | `paused` | `ended`.
      */
@@ -4729,6 +4893,11 @@ export interface SecretStored {
      * otherwise. Present when `hosts` is.
      */
     raw?: string | null;
+    /**
+     * Whether the value is masked out of responses from the bound hosts. Present when `hosts`
+     * is.
+     */
+    scan_responses?: boolean | null;
     /**
      * RFC 3339.
      */
@@ -4990,6 +5159,11 @@ export interface SnapshotCreate {
      * Commands run once, in order, before `verify`.
      */
     setup?: OneOrMany | null;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setup_user?: string | null;
     /**
      * Extra repositories cloned before `setup` (repository form only, at most 8).
      */
@@ -5008,6 +5182,13 @@ export interface SnapshotCreate {
      * charged to the organization.
      */
     track?: boolean;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string | null;
     /**
      * The command that must exit 0 for the snapshot to be stored. Required in the repository
      * form.
@@ -5103,6 +5284,11 @@ export interface SnapshotDeduped {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5314,6 +5500,11 @@ export interface SnapshotView {
      * while it can be started.
      */
     unavailable?: string | null;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name
+     * none: its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
     /**
      * What the verification command did when it last ran.
      */
@@ -5650,6 +5841,11 @@ export interface Totals {
      */
     preempted?: number;
     snapshot_failed: number;
+    /**
+     * Sandboxes Promigence support stopped (`stopped_by_support`), each with its reason. Its own
+     * counter: not the customer's own kills (`aborted_by_client`) and not a failure.
+     */
+    stopped_by_support?: number;
     task_failed: number;
 }
 /**

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>;