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

package/dist/cjs/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;
@@ -305,16 +346,29 @@ export interface BuildJoined {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when the running build carries another. It was not applied;
-     * `warnings` says what to do once the build verifies.
+     * The alias that was asked for, when the build in progress was to carry another, or none.
+     * The build carries it now (`alias_applied: true`) and its snapshot is stored under it;
+     * `warnings` names the alias the build was to carry.
      */
     alias_requested?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -337,10 +391,20 @@ export interface BuildJoined {
      * Always true here.
      */
     joined: boolean;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -371,8 +435,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` (state `built`: 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 if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -414,7 +478,8 @@ export interface BuildQueued {
     alias?: string | null;
     build_id: string;
     /**
-     * What the build costs, in USD, said before it runs.
+     * The most the build can cost, in USD, said before it runs: `max_seconds` at
+     * `per_second_usd`. It is billed per second for the time it runs.
      */
     build_price: number;
     commit: string;
@@ -428,10 +493,18 @@ export interface BuildQueued {
      * given, so a client can say which earlier request this repeats.
      */
     idempotent_replay_age_s?: number | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate.
+     */
+    per_second_usd?: number | null;
     repo: string;
     /**
      * What it is being built from. The `kind` field says which of the three forms it is.
@@ -470,12 +543,24 @@ export interface BuildView {
      * the snapshot is deleted: the name may belong to another snapshot by then.
      */
     alias?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -488,10 +573,20 @@ export interface BuildView {
      * RFC 3339.
      */
     finished_at?: string | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -522,8 +617,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` (state `built`: 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 if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -830,7 +925,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 +1011,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 +1072,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 +1210,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.
@@ -2379,7 +2514,7 @@ export interface LedgerEntryView {
      */
     seconds: number;
     /**
-     * What was charged: a sandbox id or a build id.
+     * What was charged: a sandbox id or a build id; for credit, what it is for (e.g. "Credit from Promigence").
      */
     subject: string;
     tier: string;
@@ -2547,6 +2682,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 +2972,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;
@@ -2961,6 +3157,11 @@ export interface PricingFreeCredit {
  * The limits in force.
  */
 export interface PricingLimits {
+    /**
+     * The longest a snapshot build may run, in seconds, and so the most seconds one build is
+     * billed for.
+     */
+    build_max_s?: number | null;
     /**
      * A sandbox's timeout when its run names none, in seconds.
      */
@@ -3019,8 +3220,11 @@ export interface PricingPlan {
  */
 export interface PricingRates {
     /**
-     * One snapshot build, charged once it verifies. A build that fails `verify` stores nothing
-     * and is not charged; reusing an identical build is free.
+     * The most one snapshot build of the default tier can cost: `limits.build_max_s` seconds at
+     * that tier's per-second rate. A build is billed per second at its own tier's rate (`tiers`)
+     * for the time it runs, whether it is stored, its own `setup` or `verify` fails, or it runs to
+     * its time limit; a failure on our side, and reusing or joining an identical build, cost
+     * nothing.
      */
     build_usd: number;
     /**
@@ -4502,7 +4706,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.
@@ -5059,8 +5263,7 @@ export interface SnapshotCreate {
  */
 export type SnapshotCreated = BuildQueued | BuildJoined | SnapshotDeduped;
 /**
- * Inputs that are already built: the existing snapshot, and whether the alias that was asked
- * for could be applied to it.
+ * Inputs that are already built: the existing snapshot, named with the alias that was asked for.
  */
 export interface SnapshotDeduped {
     /**
@@ -5069,8 +5272,10 @@ export interface SnapshotDeduped {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when it differs from the snapshot's. An unnamed snapshot
-     * takes the name (`alias_applied: true`); a named one keeps its own and `warnings` says so.
+     * The alias that was asked for, when the snapshot did not hold it. The snapshot takes it
+     * (`alias_applied: true`) as a new build would: another snapshot of the project that had it
+     * keeps its row, without a name. A snapshot has one alias, so a name it had before gives
+     * way, and `warnings` says which.
      */
     alias_requested?: string | null;
     /**

package/dist/cjs/proxy.js

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

package/dist/cjs/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>;