@usestatemachines/sdk 0.3.0 → 0.5.0

package/agents/llms.txt

@@ -1,18 +1,20 @@
 # State Machines
 
-> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Start, connect to and stop them with the TypeScript SDK `@usestatemachines/sdk`.
+> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Start, connect to, suspend, resume and stop them with the TypeScript SDK `@usestatemachines/sdk`.
 
 Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later (22 or 24 recommended) and Cloudflare Workers, not browsers. TypeScript needs `lib: ["DOM"]` or `@types/node`. `new StateMachines()` reads the API key from `STATE_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory.
 
 ## Concepts
 
 - Environment: one disposable run of one or more apps. `const env = await sm.environments.start({ apps: ['salesforce'] })` creates it, waits until it is `running` and returns a `RunningEnvironment`. If the environment fails or the wait times out or is aborted, `start()` stops the environment and rethrows the original error; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. Always call `env.stop()` in a `finally`.
+- Suspend and resume: `env.suspend()` ends the sandboxes and keeps the data; the lifetime pauses. Await `env.waitUntilSuspended()`, later `env.resume()` and `env.waitUntilReady()` to run again on the same data. `env.stop()` ends the environment and discards its data; a suspended environment still needs it.
 - Apps: a string is shorthand for `{ key: s, appId: s }`, nothing more. Use the object form, such as `{ key: 'crm', appId: 'salesforce' }`, for your own key or two instances of one app. `appId` names the app in the catalog (`sm.catalog.get()`); `key` is your name for it in this environment, and later calls take the key.
 - Actor: one of the app's users; requests run with that user's permissions. Salesforce actor IDs are its user IDs, such as `005…`, never a role name. `await env.actors('salesforce')` lists them in the release's order. connect() acts as the environment's declared default connection's actor, or else the first actor, the administrator, unless you pass `actorId`; pick a less-privileged actor to test permissions.
 - API profile: one API of the app, with its path and versions. Salesforce offers several (`rest`, `soap-partner`, `bulk2`, `oauth`) and has no default, so always pass `apiId`: `env.connect('salesforce', { apiId: 'rest' })`.
 - Connection: `connection.fetch` never sends your API key, never follows redirects and never retries. `connection.headers()` returns live tokens: treat them as secrets. Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope instead: put `connection.actorToken()`, also a secret, in `SessionHeader/sessionId`; `headers()` then carries only `X-State-Environment-Token`.
 - Full control: `sm.environments.create(input)` returns one `Environment` before the apps boot, `sm.environments.waitUntilReady(environment.id)` waits, and `sm.environments.connect(environment.id, key, options)` connects. Nothing on this path stops the environment for you; use it to keep a failed environment for inspection.
-- Snapshot: the saved data of a running environment's apps, taken per app instance. `const snapshot = await env.snapshot({ name: 'seeded' })` captures it and waits until it is `ready`. `sm.environments.start({ snapshotId: snapshot.id })` starts a new environment from it, in place of `apps`; each app keeps its key. Capturing needs `snapshots:create` and `snapshots:read`, restoring needs `snapshots:read`, `rename` needs `snapshots:create`, and `sm.snapshots.delete(id)` needs `snapshots:delete`, which keys created by members don't hold. Snapshots are never deleted automatically, not even failed or timed-out ones: `SnapshotFailedError` and `SnapshotTimeoutError` carry `err.snapshotId`. `sm.snapshots` also has `create`, `waitUntilReady`, `get`, `list` and `rename`.
+- Snapshot: the saved data of a running environment's apps. Every app is paused while it is cut, so a multi-app snapshot is one instant (`consistency: 'environment'`); a single app is `'app_instance'`. `const snapshot = await env.snapshot({ name: 'seeded' })` captures it and waits until it is `ready`. `sm.environments.start({ snapshotId: snapshot.id })` starts a new environment from it, in place of `apps`; each app keeps its key. Capturing needs `snapshots:create` and `snapshots:read`, restoring needs `snapshots:read`, `rename` needs `snapshots:create`, and `sm.snapshots.delete(id)` needs `snapshots:delete`, which keys created by members don't hold. Snapshots are never deleted automatically, not even failed or timed-out ones: `SnapshotFailedError` and `SnapshotTimeoutError` carry `err.snapshotId`. `sm.snapshots` also has `create`, `waitUntilReady`, `get`, `list` and `rename`.
+- Recorded requests: `sm.environments.listRequests(env.id)` pages the calls made to the environment's apps (method, path, status, duration); `getRequest(env.id, id)` adds headers and bodies. Recording is best effort and SOAP bodies are not stored.
 - Vendor clients: the gateway needs `X-State-Environment-Token` on every request. A client such as jsforce only sends it if you configure custom headers. Prefer `connection.fetch`; if you pass `headers()` to another client, send them only to `connection.baseUrl` and disable redirects.
 - Pagination: `environments.list`, `environments.events`, `workspaces.events` and `snapshots.list` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
 
@@ -20,17 +22,19 @@ Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Nod
 
 Enums are open: handle values you don't recognise.
 
-- Environment `status`: `queued`, `starting`, `running`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`.
-- App `status`: `pending`, `starting`, `ready`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.
+- Environment `status`: `queued`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`. A suspended environment keeps its data and carries `suspendedAt`.
+- App `status`: `pending`, `starting`, `ready`, `recovering`, `suspended`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.
 - App `disposal`: `pending`, `complete`, `failed`, `unknown`.
-- Snapshot `status`: `capturing`, `ready`, `failed`. A failed snapshot carries `errorCode`: `capture-failed`, or `capture-interrupted` when the API restarted mid-capture.
-- `start()` and `waitUntilReady` throw `EnvironmentFailedError` if the environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default (`readyTimeoutMs` for `start()`, `timeoutMs` for `waitUntilReady`). `start()` then stops the environment; `waitUntilReady` never does.
-- `waitUntilStopped` resolves when the environment is `stopped` or `failed` and every app's disposal is `complete`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.
+- Snapshot `status`: `capturing`, `ready`, `failed`. A failed snapshot carries `errorCode`: `capture-failed`, `pause-failed` or `pause-lost` when the apps could not be held paused for the capture, or `capture-interrupted` when the API restarted mid-capture.
+- `start()` and `waitUntilReady` throw `EnvironmentFailedError` if the environment becomes `failed`, `suspending`, `suspended`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default (`readyTimeoutMs` for `start()`, `timeoutMs` for `waitUntilReady`). `start()` then stops the environment; `waitUntilReady` never does.
+- `waitUntilSuspended` resolves when the environment is `suspended`, and throws `EnvironmentFailedError` if it ends instead.
+- `waitUntilStopped` resolves when the environment is `stopped` and every app's disposal is `complete`. A `failed` environment keeps its data for `resume()` and is not stopped until you call `stop()`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.
 
 ## Limits
 
 - Live environments are capped per organization: `(await sm.credential.get()).limits.liveEnvironments`.
-- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it; at the end the environment stops with `stopReason: 'expired'`.
+- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it, and pauses while suspended; at the end the environment stops with `stopReason: 'expired'`.
+- A suspended environment doesn't count toward the live cap; resuming it does.
 - Always call `env.stop()` in a `finally`. In CI, then await `env.waitUntilStopped()`.
 
 ## Errors and retries
@@ -39,13 +43,17 @@ A failed API call throws `StateMachinesError` with `status`, `code`, `requestId`
 
 | Code | Status | What to do |
 | --- | --- | --- |
-| `environment-limit` | 429 | Not retried. Stop a live environment (`sm.environments.list({ status: 'live' })`), then start again. |
+| `environment-limit` | 429 | Not retried. Suspend or stop a live environment (`sm.environments.list({ status: 'live' })`), then start or resume again. |
+| `not-ready` | 409 | Only a running environment whose apps are all ready can be suspended. Wait for it, or stop it. |
+| `not-suspended` | 409 | Only a suspended environment can resume. After `suspend()`, await `waitUntilSuspended()` first. |
+| `suspend-in-progress` | 409 | The environment is suspending. Await `waitUntilSuspended()`, then stop it. |
 | `lifetime-too-long` | 422 | Lower `lifetimeMinutes` to at most `limits.environmentLifetime.maximumMinutes`. |
 | `release-unavailable` | 422 | Unknown or retired app or release. Check `appId` and `appReleaseId` against `sm.catalog.get()`. |
 | `release-unavailable` | 503 | This deployment doesn't serve the release. Retried within the budget; omit `appReleaseId` to use the default release, or contact support with the `requestId`. A failed app can carry it as `errorCode`. |
-| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it stopped or expired, start a new one. (Before revealing any token, connect() throws a `TypeError` for an app that isn't ready, an unknown actor, or a missing `apiId`.) |
+| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it is suspended, resume it; if it stopped or expired, start a new one. (Before revealing any token, connect() throws a `TypeError` for an app that isn't ready, an unknown actor, or a missing `apiId`.) |
 | `idempotency-conflict` | 409 | The idempotency key was used with a different input. Replay with the exact same input. |
-| `snapshot-limit` | 429 | Too many captures are running. `capture` and `env.snapshot()` retry it for up to 60 seconds; if it still fails, wait and capture again. |
+| `capture-in-progress` | 409 | This environment is already capturing a snapshot; one runs at a time. Wait for it, then capture again. |
+| `snapshot-limit` | 429 | Older APIs only. `capture` and `env.snapshot()` retry it for up to 60 seconds; if it still fails, wait and capture again. |
 | `not-ready` | 409 | Capture: the environment isn't `running` or an app isn't `ready`. Restore: the snapshot isn't `ready` yet; `await sm.snapshots.waitUntilReady(id)`. Delete: the snapshot is still `capturing`. |
 | `version-conflict` | 409 | `rename` sent a stale `expectedVersion`, or the snapshot was deleted. `get` it: if `deletedAt` is set it's gone, otherwise retry with its `version`. |
 | `release-unavailable` | 422 | On a restore: no release on this deployment matches the snapshot's apps. Start from `apps`, seed again and capture a new snapshot. |

package/agents/prompt.md

@@ -20,7 +20,7 @@ try {
 ```
 
 4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's ID and the actors and API profiles its release offers; don't guess IDs. Start only the apps the task needs; a string such as `'salesforce'` means `{ key: 'salesforce', appId: 'salesforce' }`. Salesforce always needs an `apiId`. `connect()` acts as the declared default connection's actor, or else the app's first actor, the administrator; to act as a specific user, pass an `actorId` from `await env.actors('salesforce')`. To reuse seeded data, `await env.snapshot()` once, then `sm.environments.start({ snapshotId })`.
-5. Always call `env.stop()` in a `finally`. In CI, then await `env.waitUntilStopped()` so the run fails if cleanup isn't confirmed. If `start()` fails after creating the environment, it stops it; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. If the create itself fails, call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`; never retry without the key, which can start a second environment.
+5. Always call `env.stop()` in a `finally`; it ends the environment and discards its data. In CI, then await `env.waitUntilStopped()` so the run fails if cleanup isn't confirmed. If `start()` fails after creating the environment, it stops it; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. If the create itself fails, call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`; never retry without the key, which can start a second environment.
 6. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens.
 
 Read more: `node_modules/@usestatemachines/sdk/README.md`, https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/esm/extensions/client.d.ts

@@ -4,9 +4,14 @@ import type { Connection as ConnectionDetails } from '../models/connection.js';
 import type { ConnectionSecret } from '../models/connection-secret.js';
 import type { Credential } from '../models/credential.js';
 import type { Environment } from '../models/environment.js';
+import type { EnvironmentRequest } from '../models/environment-request.js';
+import type { EnvironmentRequestDetail } from '../models/environment-request-detail.js';
+import type { EnvironmentRequestStats } from '../models/environment-request-stats.js';
 import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { EventPage } from '../models/event-page.js';
 import type { CaptureSnapshotRequestBody } from '../models/operations/capture-snapshot.js';
+import type { GetEnvironmentRequestStatsRequest } from '../models/operations/get-environment-request-stats.js';
+import type { ListEnvironmentRequestsRequest } from '../models/operations/list-environment-requests.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
 import type { ListSnapshotsRequest } from '../models/operations/list-snapshots.js';
 import type { ListWorkspacesRequest } from '../models/operations/list-workspaces.js';
@@ -33,6 +38,9 @@ export interface StateMachinesOptions {
 export interface CallOptions {
     signal?: AbortSignal;
 }
+export interface LifecycleOptions extends CallOptions {
+    idempotencyKey?: string;
+}
 export interface CreateOptions extends CallOptions {
     idempotencyKey?: string;
     workspaceId?: string;
@@ -92,17 +100,31 @@ export declare class StateMachines {
          * failure carries the `idempotencyKey`; replaying the create with it is safe.
          */
         create: (input: EnvironmentSource, options?: CreateOptions) => Promise<Environment>;
-        stop: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        /** Ends the environment and discards its data. Safe to repeat. */
+        stop: (environmentId: string, options?: LifecycleOptions | undefined) => Promise<Environment>;
+        /**
+         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
+         * Its lifetime is paused meanwhile. Use `stop` to end it.
+         */
+        suspend: (environmentId: string, options?: LifecycleOptions | undefined) => Promise<Environment>;
+        /** Resumes a suspended or failed environment using its retained data. */
+        resume: (environmentId: string, options?: LifecycleOptions | undefined) => Promise<Environment>;
         events: (environmentId: string, query?: {
             limit?: number;
             cursor?: string;
         }, options?: CallOptions | undefined) => Promise<EventPage>;
+        listRequests: (environmentId: string, query?: Omit<ListEnvironmentRequestsRequest, "environmentId">, options?: CallOptions | undefined) => Promise<Page<EnvironmentRequest>>;
+        getRequestStats: (environmentId: string, query: Omit<GetEnvironmentRequestStatsRequest, "environmentId">, options?: CallOptions | undefined) => Promise<EnvironmentRequestStats>;
+        getRequest: (environmentId: string, requestId: string, options?: CallOptions | undefined) => Promise<EnvironmentRequestDetail>;
+        getRequestPayload: (environmentId: string, requestId: string, direction: "request" | "response", options?: CallOptions | undefined) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
         /** The app's users, in the release's order. */
         actors: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ReleaseActor[]>;
         getConnection: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ConnectionDetails>;
         reveal: (environmentId: string, appKey: string, actorId: string, options?: CallOptions | undefined) => Promise<ConnectionSecret>;
-        /** Resolves when the environment is running. Never stops it. */
+        /** Resolves when the environment is running. Never suspends or stops it. */
         waitUntilReady: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
+        /** Resolves when the environment is suspended and can resume. */
+        waitUntilSuspended: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
         /** Resolves when the environment ended and every sandbox is confirmed disposed. */
         waitUntilStopped: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
         /**

package/esm/extensions/client.js

@@ -6,7 +6,7 @@ import { Connection } from './connection.js';
 import { CallerAbortedError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, toStateMachinesError, } from './errors.js';
 import { RunningEnvironment } from './running-environment.js';
 import { linkSignal } from './signal.js';
-import { backoff, defaultTimeoutMs, disposed, poll, pollUntil, ready, sleep, snapshotReady, } from './wait.js';
+import { backoff, defaultTimeoutMs, disposed, poll, pollUntil, ready, sleep, snapshotReady, suspended, } from './wait.js';
 const stopAfterFailureMs = 30000;
 const busyBudgetMs = 60000;
 export class StateMachines {
@@ -127,15 +127,29 @@ export class StateMachines {
                 throw new StateMachinesError(error, { idempotencyKey });
             }
         },
-        stop: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.stop({ environmentId }, call)),
+        /** Ends the environment and discards its data. Safe to repeat. */
+        stop: (environmentId, options) => this.#command('stop', environmentId, options),
+        /**
+         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
+         * Its lifetime is paused meanwhile. Use `stop` to end it.
+         */
+        suspend: (environmentId, options) => this.#command('suspend', environmentId, options),
+        /** Resumes a suspended or failed environment using its retained data. */
+        resume: (environmentId, options) => this.#command('resume', environmentId, options),
         events: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.events({ ...query, environmentId }, call)),
+        listRequests: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.listRequests({ ...query, environmentId }, call)),
+        getRequestStats: (environmentId, query, options) => this.#unwrap(options, (call) => this.#sdk.environments.getRequestStats({ ...query, environmentId }, call)),
+        getRequest: (environmentId, requestId, options) => this.#unwrap(options, (call) => this.#sdk.environments.getRequest({ environmentId, requestId }, call)),
+        getRequestPayload: (environmentId, requestId, direction, options) => this.#call(options, (call) => this.#sdk.environments.getRequestPayload({ environmentId, requestId, direction }, call)),
         /** The app's users, in the release's order. */
         actors: async (environmentId, appKey, options) => (await this.environments.getConnection(environmentId, appKey, options))
             .actors,
         getConnection: (environmentId, appKey, options) => this.#unwrap(options, (call) => this.#sdk.environments.getConnection({ environmentId, appKey }, call)),
         reveal: (environmentId, appKey, actorId, options) => this.#reveal(environmentId, appKey, { actorId }, options),
-        /** Resolves when the environment is running. Never stops it. */
+        /** Resolves when the environment is running. Never suspends or stops it. */
         waitUntilReady: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), ready, options),
+        /** Resolves when the environment is suspended and can resume. */
+        waitUntilSuspended: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), suspended, options),
         /** Resolves when the environment ended and every sandbox is confirmed disposed. */
         waitUntilStopped: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), disposed, options),
         /**
@@ -217,6 +231,15 @@ export class StateMachines {
         /** Marks the snapshot deleted and returns it; safe to repeat. A capturing snapshot is a 409 `not-ready`. */
         delete: (snapshotId, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.delete({ snapshotId }, call)),
     };
+    async #command(verb, environmentId, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+        try {
+            return await this.#unwrap(options, (call) => this.#sdk.environments[verb]({ environmentId, idempotencyKey }, call));
+        }
+        catch (error) {
+            throw new StateMachinesError(error, { idempotencyKey });
+        }
+    }
     async #createSnapshot(environmentId, input, options, busyMs) {
         const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
         try {

package/esm/extensions/index.d.ts

@@ -1,11 +1,11 @@
 export type { Fetcher, HTTPClientOptions } from '../lib/http.js';
 export { HTTPClient } from '../lib/http.js';
 export { ConnectionError, ErrorResponse, HTTPClientError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, ResponseValidationError, SDKValidationError, StateMachinesHTTPError, UnexpectedClientError, UnexpectedResponseError, } from '../models/errors/index.js';
-export type { ApiProfile, App, AppInstanceSnapshot, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, EnvironmentSnapshot, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
+export type { ApiProfile, App, AppInstanceSnapshot, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, EnvironmentRequest, EnvironmentRequestDetail, EnvironmentRequestStats, EnvironmentSnapshot, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
 export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../models/index.js';
 export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
 export type { AppInput, EnvironmentInput, SnapshotEnvironmentInput, } from './apps.js';
-export type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, CreateOptions, ListEnvironmentsQuery, ListSnapshotsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
+export type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, CreateOptions, LifecycleOptions, ListEnvironmentsQuery, ListSnapshotsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
 export { Connection, formatActorHeader } from './connection.js';
 export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';

package/esm/extensions/running-environment.d.ts

@@ -1,10 +1,10 @@
 import type { Environment } from '../models/environment.js';
 import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { ReleaseActor } from '../models/release-actor.js';
-import type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, StateMachines } from './client.js';
+import type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, LifecycleOptions, StateMachines } from './client.js';
 import type { Connection } from './connection.js';
 import type { WaitOptions } from './wait.js';
-/** A started environment. It remains the handle after `stop()`. */
+/** A started environment. It remains the handle after `suspend()` and `stop()`. */
 export declare class RunningEnvironment {
     #private;
     readonly id: string;
@@ -21,8 +21,22 @@ export declare class RunningEnvironment {
     actors(appKey: string, options?: CallOptions): Promise<ReleaseActor[]>;
     /** Captures a snapshot in the environment's own workspace and waits until it's `ready`. */
     snapshot(input?: CaptureInput, options?: CaptureOptions): Promise<EnvironmentSnapshot>;
-    /** Safe to call twice. Doesn't wait for disposal: use `waitUntilStopped()`. */
-    stop(options?: CallOptions): Promise<Environment>;
+    /**
+     * Ends the sandboxes and keeps the data for `resume()`. Doesn't wait: use
+     * `waitUntilSuspended()` before resuming.
+     */
+    suspend(options?: LifecycleOptions): Promise<Environment>;
+    /** Resolves when the environment is suspended and can resume. */
+    waitUntilSuspended(options?: WaitOptions): Promise<Environment>;
+    /** Runs a suspended or failed environment again on its data. Use `waitUntilReady()` before connecting. */
+    resume(options?: LifecycleOptions): Promise<Environment>;
+    /** Resolves when the environment is running again. */
+    waitUntilReady(options?: WaitOptions): Promise<Environment>;
+    /**
+     * Ends the environment and discards its data. Safe to call twice. Doesn't wait for
+     * disposal: use `waitUntilStopped()`.
+     */
+    stop(options?: LifecycleOptions): Promise<Environment>;
     /** Resolves when the environment ended and every sandbox is confirmed disposed. */
     waitUntilStopped(options?: WaitOptions): Promise<Environment>;
     toJSON(): {

package/esm/extensions/running-environment.js

@@ -1,4 +1,4 @@
-/** A started environment. It remains the handle after `stop()`. */
+/** A started environment. It remains the handle after `suspend()` and `stop()`. */
 export class RunningEnvironment {
     id;
     /** The record when `start()` resolved. Use `sm.environments.get(id)` for fresh state. */
@@ -30,7 +30,29 @@ export class RunningEnvironment {
             workspaceId: options.workspaceId ?? this.environment.workspaceId,
         });
     }
-    /** Safe to call twice. Doesn't wait for disposal: use `waitUntilStopped()`. */
+    /**
+     * Ends the sandboxes and keeps the data for `resume()`. Doesn't wait: use
+     * `waitUntilSuspended()` before resuming.
+     */
+    suspend(options) {
+        return this.#environments.suspend(this.id, options);
+    }
+    /** Resolves when the environment is suspended and can resume. */
+    waitUntilSuspended(options) {
+        return this.#environments.waitUntilSuspended(this.id, options);
+    }
+    /** Runs a suspended or failed environment again on its data. Use `waitUntilReady()` before connecting. */
+    resume(options) {
+        return this.#environments.resume(this.id, options);
+    }
+    /** Resolves when the environment is running again. */
+    waitUntilReady(options) {
+        return this.#environments.waitUntilReady(this.id, options);
+    }
+    /**
+     * Ends the environment and discards its data. Safe to call twice. Doesn't wait for
+     * disposal: use `waitUntilStopped()`.
+     */
     stop(options) {
         return this.#environments.stop(this.id, options);
     }

package/esm/extensions/wait.d.ts

@@ -15,8 +15,10 @@ export declare function poll(read: Read<Environment>, done: Decide<Environment>,
  * Transient read failures are retried with backoff until the deadline.
  */
 export declare function pollUntil<T>(read: Read<T>, done: Decide<T>, options: WaitOptions | undefined, timeout: (timeoutMs: number, last: T | null) => Error): Promise<T>;
-/** Resolves on `running`. Never stops the environment. */
+/** Resolves on `running`. Never suspends or stops the environment. */
 export declare function ready(environment: Environment): boolean;
+/** Resolves on `suspended`, when the environment can resume. */
+export declare function suspended(environment: Environment): boolean;
 /** Resolves once the environment ended and every app's sandbox is confirmed disposed. */
 export declare function disposed(environment: Environment): boolean;
 /** Resolves on `ready`. A failed or deleted snapshot ends the wait. */

package/esm/extensions/wait.js

@@ -58,12 +58,27 @@ export async function pollUntil(read, done, options = {}, timeout) {
         await sleep(Math.min(waitMs, deadline - Date.now()), signal);
     }
 }
-/** Resolves on `running`. Never stops the environment. */
+/** Resolves on `running`. Never suspends or stops the environment. */
 export function ready(environment) {
     switch (environment.status) {
         case 'running':
             return true;
         case 'failed':
+        case 'suspending':
+        case 'suspended':
+        case 'stopping':
+        case 'stopped':
+            throw new EnvironmentFailedError(environment);
+        default:
+            return false;
+    }
+}
+/** Resolves on `suspended`, when the environment can resume. */
+export function suspended(environment) {
+    switch (environment.status) {
+        case 'suspended':
+            return true;
+        case 'failed':
         case 'stopping':
         case 'stopped':
             throw new EnvironmentFailedError(environment);
@@ -73,7 +88,7 @@ export function ready(environment) {
 }
 /** Resolves once the environment ended and every app's sandbox is confirmed disposed. */
 export function disposed(environment) {
-    if (environment.status !== 'stopped' && environment.status !== 'failed') {
+    if (environment.status !== 'stopped') {
         return false;
     }
     const unconfirmed = environment.apps.some(({ disposal }) => disposal === 'failed' || disposal === 'unknown');

package/esm/funcs/environments-get-request-payload.d.ts

@@ -0,0 +1,11 @@
+import { StateMachinesCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import { StateMachinesHTTPError } from "../models/errors/state-machines-http-error.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+export declare function environmentsGetRequestPayload(client: StateMachinesCore, request: operations.GetEnvironmentRequestPayloadRequest, options?: RequestOptions): APIPromise<Result<ReadableStream<Uint8Array>, errors.ErrorResponse | StateMachinesHTTPError | ResponseValidationError | ConnectionError | RequestAbortedError | RequestTimeoutError | InvalidRequestError | UnexpectedClientError | SDKValidationError>>;

package/esm/funcs/environments-get-request-payload.js

@@ -0,0 +1,100 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+import * as z from "zod/v4-mini";
+import { encodeSimple } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as errors from "../models/errors/index.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+export function environmentsGetRequestPayload(client, request, options) {
+    return new APIPromise($do(client, request, options));
+}
+async function $do(client, request, options) {
+    const parsed = safeParse(request, (value) => z.parse(operations.GetEnvironmentRequestPayloadRequest$outboundSchema, value), "Input validation failed");
+    if (!parsed.ok) {
+        return [parsed, { status: "invalid" }];
+    }
+    const payload = parsed.value;
+    const body = null;
+    const pathParams = {
+        direction: encodeSimple("direction", payload.direction, {
+            explode: false,
+            charEncoding: "percent",
+        }),
+        environmentId: encodeSimple("environmentId", payload.environmentId, {
+            explode: false,
+            charEncoding: "percent",
+        }),
+        requestId: encodeSimple("requestId", payload.requestId, {
+            explode: false,
+            charEncoding: "percent",
+        }),
+    };
+    const path = pathToFunc("/v1/environments/{environmentId}/requests/{requestId}/payload/{direction}")(pathParams);
+    const headers = new Headers(compactMap({
+        Accept: "application/octet-stream",
+    }));
+    const secConfig = await extractSecurity(client._options.apiKey);
+    const securityInput = secConfig == null ? {} : { apiKey: secConfig };
+    const requestSecurity = resolveGlobalSecurity(securityInput);
+    const context = {
+        options: client._options,
+        baseURL: options?.serverURL ?? client._baseURL ?? "",
+        operationID: "getEnvironmentRequestPayload",
+        oAuth2Scopes: null,
+        resolvedSecurity: requestSecurity,
+        securitySource: client._options.apiKey,
+        retryConfig: options?.retries
+            || client._options.retryConfig
+            || {
+                strategy: "backoff",
+                backoff: {
+                    initialInterval: 1000,
+                    maxInterval: 5000,
+                    exponent: 1.5,
+                    maxElapsedTime: 600000,
+                },
+                retryConnectionErrors: true,
+            }
+            || { strategy: "none" },
+        retryCodes: options?.retryCodes || ["502", "503", "504"],
+    };
+    const requestRes = client._createRequest(context, {
+        security: requestSecurity,
+        method: "GET",
+        baseURL: options?.serverURL,
+        path: path,
+        headers: headers,
+        body: body,
+        userAgent: client._options.userAgent,
+        timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+    }, options);
+    if (!requestRes.ok) {
+        return [requestRes, { status: "invalid" }];
+    }
+    const req = requestRes.value;
+    const doResult = await client._do(req, {
+        context,
+        isErrorStatusCode: (statusCode) => matchStatusCode({ status: statusCode }, ["4XX", "5XX"]),
+        retryConfig: context.retryConfig,
+        retryCodes: context.retryCodes,
+    });
+    if (!doResult.ok) {
+        return [doResult, { status: "request-error", request: req }];
+    }
+    const response = doResult.value;
+    const responseFields = {
+        HttpMeta: { Response: response, Request: req },
+    };
+    const [result] = await M.match(M.stream(200, z.custom(x => x instanceof ReadableStream)), M.jsonErr([400, 401, 403, 404, 409, 413, 422, 429], errors.ErrorResponse$inboundSchema), M.jsonErr([500, 503], errors.ErrorResponse$inboundSchema), M.fail("4XX"), M.fail("5XX"))(response, req, { extraFields: responseFields });
+    if (!result.ok) {
+        return [result, { status: "complete", request: req, response }];
+    }
+    return [result, { status: "complete", request: req, response }];
+}

package/esm/funcs/environments-get-request-stats.d.ts

@@ -0,0 +1,11 @@
+import { StateMachinesCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import { StateMachinesHTTPError } from "../models/errors/state-machines-http-error.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+export declare function environmentsGetRequestStats(client: StateMachinesCore, request: operations.GetEnvironmentRequestStatsRequest, options?: RequestOptions): APIPromise<Result<operations.GetEnvironmentRequestStatsResponse, errors.ErrorResponse | StateMachinesHTTPError | ResponseValidationError | ConnectionError | RequestAbortedError | RequestTimeoutError | InvalidRequestError | UnexpectedClientError | SDKValidationError>>;

package/esm/funcs/environments-get-request-stats.js

@@ -0,0 +1,103 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+import * as z from "zod/v4-mini";
+import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as errors from "../models/errors/index.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+export function environmentsGetRequestStats(client, request, options) {
+    return new APIPromise($do(client, request, options));
+}
+async function $do(client, request, options) {
+    const parsed = safeParse(request, (value) => z.parse(operations.GetEnvironmentRequestStatsRequest$outboundSchema, value), "Input validation failed");
+    if (!parsed.ok) {
+        return [parsed, { status: "invalid" }];
+    }
+    const payload = parsed.value;
+    const body = null;
+    const pathParams = {
+        environmentId: encodeSimple("environmentId", payload.environmentId, {
+            explode: false,
+            charEncoding: "percent",
+        }),
+    };
+    const path = pathToFunc("/v1/environments/{environmentId}/requests/stats")(pathParams);
+    const query = encodeFormQuery({
+        "appKey": payload.appKey,
+        "from": payload.from,
+        "method": payload.method,
+        "search": payload.search,
+        "status": payload.status,
+        "statusClass": payload.statusClass,
+        "to": payload.to,
+        "writesOnly": payload.writesOnly,
+    });
+    const headers = new Headers(compactMap({
+        Accept: "application/json",
+    }));
+    const secConfig = await extractSecurity(client._options.apiKey);
+    const securityInput = secConfig == null ? {} : { apiKey: secConfig };
+    const requestSecurity = resolveGlobalSecurity(securityInput);
+    const context = {
+        options: client._options,
+        baseURL: options?.serverURL ?? client._baseURL ?? "",
+        operationID: "getEnvironmentRequestStats",
+        oAuth2Scopes: null,
+        resolvedSecurity: requestSecurity,
+        securitySource: client._options.apiKey,
+        retryConfig: options?.retries
+            || client._options.retryConfig
+            || {
+                strategy: "backoff",
+                backoff: {
+                    initialInterval: 1000,
+                    maxInterval: 5000,
+                    exponent: 1.5,
+                    maxElapsedTime: 600000,
+                },
+                retryConnectionErrors: true,
+            }
+            || { strategy: "none" },
+        retryCodes: options?.retryCodes || ["502", "503", "504"],
+    };
+    const requestRes = client._createRequest(context, {
+        security: requestSecurity,
+        method: "GET",
+        baseURL: options?.serverURL,
+        path: path,
+        headers: headers,
+        query: query,
+        body: body,
+        userAgent: client._options.userAgent,
+        timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+    }, options);
+    if (!requestRes.ok) {
+        return [requestRes, { status: "invalid" }];
+    }
+    const req = requestRes.value;
+    const doResult = await client._do(req, {
+        context,
+        isErrorStatusCode: (statusCode) => matchStatusCode({ status: statusCode }, ["4XX", "5XX"]),
+        retryConfig: context.retryConfig,
+        retryCodes: context.retryCodes,
+    });
+    if (!doResult.ok) {
+        return [doResult, { status: "request-error", request: req }];
+    }
+    const response = doResult.value;
+    const responseFields = {
+        HttpMeta: { Response: response, Request: req },
+    };
+    const [result] = await M.match(M.json(200, operations.GetEnvironmentRequestStatsResponse$inboundSchema), M.jsonErr([400, 401, 403, 404, 409, 413, 422, 429], errors.ErrorResponse$inboundSchema), M.jsonErr([500, 503], errors.ErrorResponse$inboundSchema), M.fail("4XX"), M.fail("5XX"))(response, req, { extraFields: responseFields });
+    if (!result.ok) {
+        return [result, { status: "complete", request: req, response }];
+    }
+    return [result, { status: "complete", request: req, response }];
+}

package/esm/funcs/environments-get-request.d.ts

@@ -0,0 +1,11 @@
+import { StateMachinesCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import { StateMachinesHTTPError } from "../models/errors/state-machines-http-error.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+export declare function environmentsGetRequest(client: StateMachinesCore, request: operations.GetEnvironmentRequestRequest, options?: RequestOptions): APIPromise<Result<operations.GetEnvironmentRequestResponse, errors.ErrorResponse | StateMachinesHTTPError | ResponseValidationError | ConnectionError | RequestAbortedError | RequestTimeoutError | InvalidRequestError | UnexpectedClientError | SDKValidationError>>;