@usestatemachines/sdk 0.6.1 → 0.7.0

package/README.md

@@ -1,7 +1,7 @@
 # @usestatemachines/sdk
 
 TypeScript SDK for [State Machines](https://usestatemachines.com): create disposable environments
-of replica apps, connect to them, take snapshots of their data, pause and resume them, and delete
+of replica apps, connect to them, take snapshots of their data, and delete
 them.
 
 Documentation: [docs.usestatemachines.com](https://docs.usestatemachines.com)
@@ -49,13 +49,12 @@ const sm = new StateMachines({
 | `sm` | `me()` |
 | `sm.apps` | `list(query?)`, `versions(appId, query?)` |
 | `sm.workspaces` | `list(query?)`, `get(id)` |
-| `sm.environments` | `create(input, options?)`, `list(query?)`, `get(id)`, `update(id, { name?, labels? })`, `pause(id)`, `resume(id, options?)`, `delete(id)`, `wait(id, { status })`, `connect(id, app, { actorId? }?)` |
+| `sm.environments` | `create(input, options?)`, `list(query?)`, `get(id)`, `update(id, { name?, labels? })`, `delete(id)`, `wait(id, { status })`, `connect(id, app, { actorId? }?)` |
 | `sm.snapshots` | `create({ environmentId, name? }, options?)`, `list(query?)`, `get(id)`, `update(id, { name })`, `delete(id)`, `wait(id, { status })` |
 | `sm.requests` | `list(query)`, `get(id)`, `stats(query)`, `body(id, 'request' \| 'response')` |
 | `sm.auditEvents` | `list(query?)` |
 
-Every environment the SDK returns carries bound helpers: `env.connect(app)`, `env.pause()`,
-`env.resume()`, `env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
+Every environment the SDK returns carries bound helpers: `env.connect(app)`, `env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
 not enumerable, so `JSON.stringify(env)` holds only the API's fields.
 
 ## Apps
@@ -93,7 +92,7 @@ A new environment runs each app's default version.
 `env.connect(app, { actorId? })` returns the API's `Credentials`: `url`, `headers`, `token`,
 `expiresAt` and `login`, plus `fetch(path, init?)`.
 
-- `fetch` joins `path` to `url`; a leading `/` means the root of the app. It adds `headers`
+- `fetch` joins `path` to `url`. A leading `/` means the root of the app. It adds `headers`
   (`StateMachines-Environment-Token`), and puts `token` in the header of the API whose path
   matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0.
 - Salesforce SOAP takes the token in the envelope: put `credentials.token` in
@@ -110,13 +109,6 @@ A new environment runs each app's default version.
 Environments created with `tokenInUrl: true` carry the environment token in `url` instead, and
 `headers` is empty.
 
-## Pausing and resuming
-
-`env.pause()` takes effect when the API answers: the gateway refuses calls, the compute is
-released and the data stays. The time limit stops counting. `env.resume()` boots the apps again
-on the same data and waits until `running`. A paused or failed environment is deleted after one
-day.
-
 ## Snapshots
 
 ```ts
@@ -125,7 +117,7 @@ const copy = await sm.environments.create({ snapshotId: seeded.id });
 ```
 
 A snapshot holds every app of a running environment at one moment, and waits until `ready`. A
-pause or delete during the snapshot fails it with `failure.code: 'interrupted'`. One snapshot is
+delete during the snapshot fails it with `failure.code: 'interrupted'`. One snapshot is
 `saving` per environment at a time. `sm.snapshots.delete(id)` deletes a `ready` or `failed`
 snapshot.
 
@@ -133,14 +125,13 @@ snapshot.
 
 | Method | Waits for | Throws |
 | --- | --- | --- |
-| `environments.create` | `running` | `EnvironmentFailedError` when the environment fails; `UnexpectedStatusError` on `paused` or `deleted` for another reason; `WaitTimeoutError` |
-| `environments.resume` | `running` | `EnvironmentFailedError` when the environment fails; `UnexpectedStatusError` on `paused` or `deleted` for another reason; `WaitTimeoutError` |
-| `snapshots.create` | `ready` | `SnapshotFailedError` on `failed`; `UnexpectedStatusError` on `deleted` |
+| `environments.create` | `running` | `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` on `deleted` for another reason, and `WaitTimeoutError` |
+| `snapshots.create` | `ready` | `SnapshotFailedError` on `failed` and `UnexpectedStatusError` on `deleted` |
 | `environments.wait(id, { status })`, `snapshots.wait(id, { status })` | `status` | the same rule: a status that cannot reach `status` without another call |
 
-Pass `{ wait: false }` to `create`, `resume` or `snapshots.create` to get the API's answer at once.
+Pass `{ wait: false }` to `create` or `snapshots.create` to get the API's answer at once.
 `timeoutMs` bounds the wait, and `signal` aborts it. The option types document each default.
-`pause` and `delete` do not wait: the status changes when the API answers.
+`delete` returns when the API confirms the status change.
 
 ## YAML
 
@@ -171,7 +162,7 @@ response body.
 
 | Code | Status | Meaning |
 | --- | --- | --- |
-| `invalid_request` | 400 | A wrong field; see `fields`. |
+| `invalid_request` | 400 | A wrong field. See `fields`. |
 | `unauthenticated` | 401 | A missing, expired or revoked key. |
 | `forbidden` | 403 | The key lacks the permission. |
 | `not_found` | 404 | No such resource in this workspace. |
@@ -192,17 +183,16 @@ error envelope, and never retries them. These codes come from State Machines, in
 
 | Code | Status | Meaning |
 | --- | --- | --- |
-| `environment_not_running` | 409 | The environment is `paused`, `failed` or `deleted`. The body's `error.status` names the status. |
+| `environment_not_running` | 409 | The environment is `failed` or `deleted`. The body's `error.status` names the status. |
 | `environment_starting` | 503 | The environment is still `starting`. The response carries `Retry-After`. |
 | `environment_unavailable` | 503 | The app is restarting or did not answer. The response carries `Retry-After`. |
 | `response_too_large` | 502 | The app's response is over the size limit of State Machines. |
-| `capacity_exceeded` | 429 | The app has too many requests in flight. |
 | `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |
 
 ## Retries and timeouts
 
 The SDK retries `502`, `503`, `504` and connection errors with backoff, until a deadline.
-`create` and `snapshots.create` send one `Idempotency-Key` for every retry; pass your own
+`create` and `snapshots.create` send one `Idempotency-Key` for every retry. Pass your own
 `idempotencyKey` to replay a call whose outcome you don't know. Each HTTP attempt times out after
 `attemptTimeoutMs`.
 
@@ -239,11 +229,9 @@ against it.
 | Default host `https://state-api.usestatemachines.workers.dev` | `https://api.usestatemachines.com` |
 | `sm.environments.start(input)` | `sm.environments.create(input)`, which waits until `running` |
 | `env.stop()`, `sm.environments.stop(id)` | `env.delete()`, `sm.environments.delete(id)` |
-| `env.suspend()`, `sm.environments.suspend(id)` | `env.pause()`, `sm.environments.pause(id)` |
-| `env.resume()` then `env.waitUntilReady()` | `env.resume()`, which waits until `running` |
 | `waitUntilReady`, `waitUntilStopped`, `waitUntilSuspended` | `sm.environments.wait(id, { status })` |
 | Apps as `{ key, appId }` | Apps as `{ app, name }`, or the app name as a string |
-| `env.connect(app, { apiId, actorId })` returns a `Connection` | `env.connect(app, { actorId })` returns `Credentials`; `fetch` picks the API from the path |
+| `env.connect(app, { apiId, actorId })` returns a `Connection` | `env.connect(app, { actorId })` returns `Credentials`, and `fetch` picks the API from the path |
 | `connection.baseUrl`, `connection.headers()` | `credentials.url`, `credentials.headers`, `credentials.token` |
 | `X-State-Environment-Token` | `StateMachines-Environment-Token` |
 | `env.snapshot(options)`, `sm.snapshots.capture(environmentId, options)` | `env.snapshots.create(options)`, `sm.snapshots.create({ environmentId, ...options })` |
@@ -253,7 +241,7 @@ against it.
 | The catalog | `sm.apps.list()`, `sm.apps.versions(appId)` |
 | `TimeoutError` | `WaitTimeoutError` |
 | `error.retryAfter` | `error.retryAfterMs` |
-| Error codes such as `environment-limit` and `capture-in-progress` | Codes such as `environment_limit_reached` and `snapshot_in_progress`; see [Errors](#errors) |
+| Error codes such as `environment-limit` and `capture-in-progress` | Codes such as `environment_limit_reached` and `snapshot_in_progress`. See [Errors](#errors) |
 
 ## License
 

package/agents/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: state-machines
-description: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, pausing and resuming, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.
+description: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.
 ---
 
-Read `node_modules/@usestatemachines/sdk/README.md` before relying on memory; it matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.
+Read `node_modules/@usestatemachines/sdk/README.md` before relying on memory. It matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.
 
 ## Workflow
 
-1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n "$STATEMACHINES_API_KEY"`). If it isn't, ask the user to set it; the SDK doesn't read `.env` files.
-2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID; don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.
+1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n "$STATEMACHINES_API_KEY"`). If it isn't, ask the user to set it. The SDK doesn't read `.env` files.
+2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID. Don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.
 3. Open a `try` right after `create` returns, and call `await env.delete()` in its `finally`. It deletes the environment and its data.
 4. Get credentials for one app: `const crm = await env.connect('salesforce')`. This acts as the app's default actor, the Salesforce administrator. To act with another user's permissions, pass an `actorId` from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name.
 5. Call the app with `crm.fetch(path)`. A leading `/` means the root of the app's `url`.
@@ -33,10 +33,9 @@ try {
 ## Rules
 
 - Always delete in `finally`.
-- `env.pause()` releases the compute and keeps the data; it is not cleanup. `env.resume()` waits until `running` again. A paused or failed environment is deleted after one day, and still needs `env.delete()` once you are done.
 - To create without waiting, pass `{ wait: false }`, then `sm.environments.wait(env.id, { status: 'running' })`.
 - The time limit counts `starting` and `running`. `(await sm.me()).limits.timeLimitMinutes` gives its `default` and `maximum`. Set `timeLimitMinutes` in `create` for longer runs.
-- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need. A paused or failed environment doesn't count until it resumes.
+- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need.
 - Never print, log or commit `STATEMACHINES_API_KEY`, `credentials.token` or `credentials.headers`.
 - Salesforce's SOAP API takes the actor token in the envelope, not a header: put `crm.token` in `SessionHeader/sessionId`. `crm.fetch` then sends only the environment token header.
 - `crm.fetch` never sends your API key, never follows redirects and only reaches URLs under the app's `url`.
@@ -55,17 +54,17 @@ The SDK already retries `502`, `503`, `504` and connection errors with one idemp
 | Symptom | Cause | Fix |
 | --- | --- | --- |
 | `version_unavailable`, 422 | The app has no default version. | Check the app ID against `sm.apps.list()`. |
-| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete or pause one, then create again. |
-| `invalid_status`, 409 | The status does not allow the call, for example pausing an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |
+| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete one, then create again. |
+| `invalid_status`, 409 | The status does not allow the call, for example taking a snapshot of an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |
 | `invalid_request`, 400 | A wrong field. | Read `err.fields`, keyed by dotted path. |
-| `EnvironmentFailedError` | The environment failed to start or resume. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |
-| `UnexpectedStatusError` | The environment was paused or deleted while the SDK waited. | Read `err.status` and `err.resource`. |
+| `EnvironmentFailedError` | The environment failed to start. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |
+| `UnexpectedStatusError` | The environment was deleted while the SDK waited. | Read `err.status` and `err.resource`. |
 | `WaitTimeoutError` | The status was not reached within `timeoutMs`. | Wait again with `sm.environments.wait(id, { status })`, or delete the environment. |
 | `snapshot_in_progress`, 409 | The environment already has a snapshot in `saving`. | `const [running] = (await sm.snapshots.list({ environmentId: env.id, status: ['saving'] })).data`, then `await sm.snapshots.wait(running.id, { status: 'ready' })`, then create another. |
-| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was paused or deleted first. | Create another snapshot while the environment is `running`. |
-| `environment_not_running`, 409, from `crm.fetch` | The environment is paused, failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`; `env.resume()` a paused or failed environment. |
+| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was deleted first. | Create another snapshot while the environment is `running`. |
+| `environment_not_running`, 409, from `crm.fetch` | The environment is failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`. Create a new environment if you need another run. |
 | `environment_starting` or `environment_unavailable`, 503, from `crm.fetch` | The app is starting or restarting. | Wait the `Retry-After` seconds and call again. |
 | A vendor client such as jsforce is refused by the gateway | The gateway needs `StateMachines-Environment-Token` on every request. | Prefer `crm.fetch`. If you pass `crm.headers` to another client, send them only to `crm.url` and disable redirects. |
-| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`; in Workers, pass `apiKey`. |
+| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`. In Workers, pass `apiKey`. |
 
 More: https://docs.usestatemachines.com, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/agents/index.js

@@ -1,22 +1,22 @@
 // Generated by scripts/build-agents.mjs from templates/ and examples/quickstart.ts.
 
 export const prompt =
-  "Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.\n\n1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.\n2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n \"$STATEMACHINES_API_KEY\"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.\n3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup. It prints `200` and the Salesforce org's limits:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions; don't guess IDs. Create only the apps the task needs; a string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator; to act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.\n5. Always call `env.delete()` in a `finally`; it deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`; if it throws with no response, call it again with the same input and key.\n6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.\n\nRead more: https://docs.usestatemachines.com, `node_modules/@usestatemachines/sdk/README.md`, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n";
+  "Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.\n\n1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.\n2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n \"$STATEMACHINES_API_KEY\"`. If it is missing, stop and ask me to set it. The SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.\n3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup. It prints `200` and the Salesforce org's limits:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions. Don't guess IDs. Create only the apps the task needs. A string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator. To act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.\n5. Always call `env.delete()` in a `finally`. It deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`. If it throws with no response, call it again with the same input and key.\n6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.\n\nRead more: https://docs.usestatemachines.com, `node_modules/@usestatemachines/sdk/README.md`, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n";
 
 export const llmsTxt =
-  "# State Machines\n\n> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, pause, resume and delete them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_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.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Pass `{ wait: false }` to get it back at once in `starting`. Always call `env.delete()` in a `finally`.\n- Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.\n- Pause and resume: `env.pause()` releases the compute and keeps the data; the time limit stops counting. `env.resume()` boots the apps again on the same data and waits until `running`. A paused environment is deleted after one day.\n- Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.\n- Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Read them from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`.\n- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A pause or delete during the snapshot fails it with `interrupted`.\n- Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.\n- YAML: `parseEnvironmentYaml(text)` turns a YAML document with the fields of `create` into its input.\n- Pagination: every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n\n## Statuses\n\nEnums are open: handle values you don't recognise.\n\n- Environment `status`: `starting`, `running`, `paused`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment keeps its data for `resume()` and has `failure`: `{ app, code, message }` with `start_failed`, `resume_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.\n- Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.\n- `create` and `resume` throw `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `paused` or `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.\n- `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.\n- `sm.environments.wait(id, { status })` and `sm.snapshots.wait(id, { status })` wait for any status, and throw once it cannot be reached without another call.\n\n## Limits\n\n- Running environments are capped per organization: `(await sm.me()).limits.concurrentEnvironments` counts `starting` and `running`.\n- `timeLimitMinutes` has a default and a maximum: `(await sm.me()).limits.timeLimitMinutes`. It counts `starting` and `running` only; at the end the environment is deleted with `reason: 'expired'`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `message`, `requestId`, `fields` and `retryAfterMs`. The SDK retries `502`, `503`, `504` and connection errors itself, until a deadline; `create` retries reuse one idempotency key. It retries nothing else.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `invalid_request` | 400 | Read `fields`, keyed by the dotted path of each wrong field. |\n| `forbidden` | 403 | The key lacks the permission. |\n| `not_found` | 404 | Check the ID and the workspace. |\n| `invalid_status` | 409 | The status does not allow the call: pause needs `running`; resume needs `paused` or `failed`. |\n| `snapshot_in_progress` | 409 | Wait for the running snapshot, then create another. |\n| `idempotency_key_reused` | 409 | The key was used with a different input. Replay with the exact same input. |\n| `workspace_archived` | 409 | The workspace is archived. |\n| `body_too_large` | 413 | The request body is over the API's size limit. Send less. |\n| `version_unavailable` | 422 | The app has no default version. |\n| `environment_limit_reached` | 429 | Pause or delete an environment, then create or resume again. |\n| `unavailable` | 503 | Retried automatically. If `create` still fails, call it again with the same input and your own `idempotencyKey`. |\n\n## Errors from the app URL\n\n`crm.fetch` returns these as responses with the same JSON envelope, and never retries them.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment_not_running` | 409 | The environment is paused, failed or deleted; `error.status` names it. Resume a paused or failed environment. |\n| `environment_starting` | 503 | Wait `Retry-After` and call again. |\n| `environment_unavailable` | 503 | The app is restarting. Wait `Retry-After` and call again. |\n| `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |\n| `capacity_exceeded` | 429 | Too many requests in flight to the app. Send fewer at once. |\n| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |\n\n## Quickstart\n\nSave it unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Docs\n\n- [Documentation](https://docs.usestatemachines.com): guides, concepts and reference ([llms.txt](https://docs.usestatemachines.com/llms.txt))\n- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions\n- [Agent skill](https://app.usestatemachines.com/skill.md): workflow, rules and troubleshooting for coding agents\n- [OpenAPI document](https://cdn.jsdelivr.net/npm/@usestatemachines/sdk/openapi.json): the HTTP API the SDK calls\n- [State Machines](https://usestatemachines.com): website\n";
+  "# State Machines\n\n> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, and delete them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_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.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Pass `{ wait: false }` to get it back at once in `starting`. Always call `env.delete()` in a `finally`.\n- Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.\n- Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.\n- Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Read them from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`.\n- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A delete during the snapshot fails it with `interrupted`.\n- Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.\n- YAML: `parseEnvironmentYaml(text)` turns a YAML document with the fields of `create` into its input.\n- Pagination: every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n\n## Statuses\n\nEnums are open: handle values you don't recognise.\n\n- Environment `status`: `starting`, `running`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment has `failure`: `{ app, code, message }` with `start_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.\n- Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.\n- `create` throws `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.\n- `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.\n- `sm.environments.wait(id, { status })` and `sm.snapshots.wait(id, { status })` wait for any status, and throw once it cannot be reached without another call.\n\n## Limits\n\n- Running environments are capped per organization: `(await sm.me()).limits.concurrentEnvironments` counts `starting` and `running`.\n- `timeLimitMinutes` has a default and a maximum: `(await sm.me()).limits.timeLimitMinutes`. It counts `starting` and `running` only; at the end the environment is deleted with `reason: 'expired'`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `message`, `requestId`, `fields` and `retryAfterMs`. The SDK retries `502`, `503`, `504` and connection errors itself, until a deadline; `create` retries reuse one idempotency key. It retries nothing else.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `invalid_request` | 400 | Read `fields`, keyed by the dotted path of each wrong field. |\n| `forbidden` | 403 | The key lacks the permission. |\n| `not_found` | 404 | Check the ID and the workspace. |\n| `invalid_status` | 409 | The status does not allow the call. Snapshots need a running environment. |\n| `snapshot_in_progress` | 409 | Wait for the running snapshot, then create another. |\n| `idempotency_key_reused` | 409 | The key was used with a different input. Replay with the exact same input. |\n| `workspace_archived` | 409 | The workspace is archived. |\n| `body_too_large` | 413 | The request body is over the API's size limit. Send less. |\n| `version_unavailable` | 422 | The app has no default version. |\n| `environment_limit_reached` | 429 | Delete an environment, then create again. |\n| `unavailable` | 503 | Retried automatically. If `create` still fails, call it again with the same input and your own `idempotencyKey`. |\n\n## Errors from the app URL\n\n`crm.fetch` returns these as responses with the same JSON envelope, and never retries them.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment_not_running` | 409 | The environment is failed or deleted; `error.status` names it. Create another environment. |\n| `environment_starting` | 503 | Wait `Retry-After` and call again. |\n| `environment_unavailable` | 503 | The app is restarting. Wait `Retry-After` and call again. |\n| `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |\n| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |\n\n## Quickstart\n\nSave it unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Docs\n\n- [Documentation](https://docs.usestatemachines.com): guides, concepts and reference ([llms.txt](https://docs.usestatemachines.com/llms.txt))\n- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions\n- [Agent skill](https://app.usestatemachines.com/skill.md): workflow, rules and troubleshooting for coding agents\n- [OpenAPI document](https://cdn.jsdelivr.net/npm/@usestatemachines/sdk/openapi.json): the HTTP API the SDK calls\n- [State Machines](https://usestatemachines.com): website\n";
 
 export const skill =
-  "---\nname: state-machines\ndescription: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, pausing and resuming, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.\n---\n\nRead `node_modules/@usestatemachines/sdk/README.md` before relying on memory; it matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.\n\n## Workflow\n\n1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n \"$STATEMACHINES_API_KEY\"`). If it isn't, ask the user to set it; the SDK doesn't read `.env` files.\n2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID; don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.\n3. Open a `try` right after `create` returns, and call `await env.delete()` in its `finally`. It deletes the environment and its data.\n4. Get credentials for one app: `const crm = await env.connect('salesforce')`. This acts as the app's default actor, the Salesforce administrator. To act with another user's permissions, pass an `actorId` from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name.\n5. Call the app with `crm.fetch(path)`. A leading `/` means the root of the app's `url`.\n\nThe whole flow, as the package ships it. It is ESM with top-level `await`: save it as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Rules\n\n- Always delete in `finally`.\n- `env.pause()` releases the compute and keeps the data; it is not cleanup. `env.resume()` waits until `running` again. A paused or failed environment is deleted after one day, and still needs `env.delete()` once you are done.\n- To create without waiting, pass `{ wait: false }`, then `sm.environments.wait(env.id, { status: 'running' })`.\n- The time limit counts `starting` and `running`. `(await sm.me()).limits.timeLimitMinutes` gives its `default` and `maximum`. Set `timeLimitMinutes` in `create` for longer runs.\n- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need. A paused or failed environment doesn't count until it resumes.\n- Never print, log or commit `STATEMACHINES_API_KEY`, `credentials.token` or `credentials.headers`.\n- Salesforce's SOAP API takes the actor token in the envelope, not a header: put `crm.token` in `SessionHeader/sessionId`. `crm.fetch` then sends only the environment token header.\n- `crm.fetch` never sends your API key, never follows redirects and only reaches URLs under the app's `url`.\n- Runtimes: Node.js, at the versions in the package's `engines` field, and Cloudflare Workers. ESM only. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. Never ship an API key to a browser.\n- In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATEMACHINES_API_KEY })`. A start takes longer than one request may last, so create with `{ wait: false }` and read `sm.environments.get(id)` in later requests until it is `running`, or pass a `signal` no shorter than the expected start.\n- Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- To reuse seeded data, `await env.snapshots.create({ name })` once, then `sm.environments.create({ snapshotId })` in place of `apps`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `SnapshotFailedError`, `UnexpectedStatusError`, `WaitTimeoutError`), not by `name`.\n\n## Recovering a failed create\n\nThe SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If you need to replay a create whose outcome is unknown, pass your own key: `sm.environments.create(input, { idempotencyKey })`, and call it again with the same input and key. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency_key_reused`.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `version_unavailable`, 422 | The app has no default version. | Check the app ID against `sm.apps.list()`. |\n| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete or pause one, then create again. |\n| `invalid_status`, 409 | The status does not allow the call, for example pausing an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |\n| `invalid_request`, 400 | A wrong field. | Read `err.fields`, keyed by dotted path. |\n| `EnvironmentFailedError` | The environment failed to start or resume. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |\n| `UnexpectedStatusError` | The environment was paused or deleted while the SDK waited. | Read `err.status` and `err.resource`. |\n| `WaitTimeoutError` | The status was not reached within `timeoutMs`. | Wait again with `sm.environments.wait(id, { status })`, or delete the environment. |\n| `snapshot_in_progress`, 409 | The environment already has a snapshot in `saving`. | `const [running] = (await sm.snapshots.list({ environmentId: env.id, status: ['saving'] })).data`, then `await sm.snapshots.wait(running.id, { status: 'ready' })`, then create another. |\n| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was paused or deleted first. | Create another snapshot while the environment is `running`. |\n| `environment_not_running`, 409, from `crm.fetch` | The environment is paused, failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`; `env.resume()` a paused or failed environment. |\n| `environment_starting` or `environment_unavailable`, 503, from `crm.fetch` | The app is starting or restarting. | Wait the `Retry-After` seconds and call again. |\n| A vendor client such as jsforce is refused by the gateway | The gateway needs `StateMachines-Environment-Token` on every request. | Prefer `crm.fetch`. If you pass `crm.headers` to another client, send them only to `crm.url` and disable redirects. |\n| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`; in Workers, pass `apiKey`. |\n\nMore: https://docs.usestatemachines.com, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n";
+  "---\nname: state-machines\ndescription: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.\n---\n\nRead `node_modules/@usestatemachines/sdk/README.md` before relying on memory. It matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.\n\n## Workflow\n\n1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n \"$STATEMACHINES_API_KEY\"`). If it isn't, ask the user to set it. The SDK doesn't read `.env` files.\n2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID. Don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.\n3. Open a `try` right after `create` returns, and call `await env.delete()` in its `finally`. It deletes the environment and its data.\n4. Get credentials for one app: `const crm = await env.connect('salesforce')`. This acts as the app's default actor, the Salesforce administrator. To act with another user's permissions, pass an `actorId` from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name.\n5. Call the app with `crm.fetch(path)`. A leading `/` means the root of the app's `url`.\n\nThe whole flow, as the package ships it. It is ESM with top-level `await`: save it as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Rules\n\n- Always delete in `finally`.\n- To create without waiting, pass `{ wait: false }`, then `sm.environments.wait(env.id, { status: 'running' })`.\n- The time limit counts `starting` and `running`. `(await sm.me()).limits.timeLimitMinutes` gives its `default` and `maximum`. Set `timeLimitMinutes` in `create` for longer runs.\n- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need.\n- Never print, log or commit `STATEMACHINES_API_KEY`, `credentials.token` or `credentials.headers`.\n- Salesforce's SOAP API takes the actor token in the envelope, not a header: put `crm.token` in `SessionHeader/sessionId`. `crm.fetch` then sends only the environment token header.\n- `crm.fetch` never sends your API key, never follows redirects and only reaches URLs under the app's `url`.\n- Runtimes: Node.js, at the versions in the package's `engines` field, and Cloudflare Workers. ESM only. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. Never ship an API key to a browser.\n- In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATEMACHINES_API_KEY })`. A start takes longer than one request may last, so create with `{ wait: false }` and read `sm.environments.get(id)` in later requests until it is `running`, or pass a `signal` no shorter than the expected start.\n- Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- To reuse seeded data, `await env.snapshots.create({ name })` once, then `sm.environments.create({ snapshotId })` in place of `apps`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `SnapshotFailedError`, `UnexpectedStatusError`, `WaitTimeoutError`), not by `name`.\n\n## Recovering a failed create\n\nThe SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If you need to replay a create whose outcome is unknown, pass your own key: `sm.environments.create(input, { idempotencyKey })`, and call it again with the same input and key. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency_key_reused`.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `version_unavailable`, 422 | The app has no default version. | Check the app ID against `sm.apps.list()`. |\n| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete one, then create again. |\n| `invalid_status`, 409 | The status does not allow the call, for example taking a snapshot of an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |\n| `invalid_request`, 400 | A wrong field. | Read `err.fields`, keyed by dotted path. |\n| `EnvironmentFailedError` | The environment failed to start. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |\n| `UnexpectedStatusError` | The environment was deleted while the SDK waited. | Read `err.status` and `err.resource`. |\n| `WaitTimeoutError` | The status was not reached within `timeoutMs`. | Wait again with `sm.environments.wait(id, { status })`, or delete the environment. |\n| `snapshot_in_progress`, 409 | The environment already has a snapshot in `saving`. | `const [running] = (await sm.snapshots.list({ environmentId: env.id, status: ['saving'] })).data`, then `await sm.snapshots.wait(running.id, { status: 'ready' })`, then create another. |\n| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was deleted first. | Create another snapshot while the environment is `running`. |\n| `environment_not_running`, 409, from `crm.fetch` | The environment is failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`. Create a new environment if you need another run. |\n| `environment_starting` or `environment_unavailable`, 503, from `crm.fetch` | The app is starting or restarting. | Wait the `Retry-After` seconds and call again. |\n| A vendor client such as jsforce is refused by the gateway | The gateway needs `StateMachines-Environment-Token` on every request. | Prefer `crm.fetch`. If you pass `crm.headers` to another client, send them only to `crm.url` and disable redirects. |\n| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`. In Workers, pass `apiKey`. |\n\nMore: https://docs.usestatemachines.com, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n";
 
 export const quickstart =
   "import { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n";
 
 export const templates = Object.freeze({
   prompt:
-    "Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.\n\n1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.\n2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n \"$STATEMACHINES_API_KEY\"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.\n3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup. It prints `200` and the Salesforce org's limits:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions; don't guess IDs. Create only the apps the task needs; a string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator; to act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.\n5. Always call `env.delete()` in a `finally`; it deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`; if it throws with no response, call it again with the same input and key.\n6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.\n\nRead more: https://docs.usestatemachines.com, `node_modules/@usestatemachines/sdk/README.md`, {{origin}}/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n",
+    "Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.\n\n1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.\n2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n \"$STATEMACHINES_API_KEY\"`. If it is missing, stop and ask me to set it. The SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.\n3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup. It prints `200` and the Salesforce org's limits:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions. Don't guess IDs. Create only the apps the task needs. A string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator. To act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.\n5. Always call `env.delete()` in a `finally`. It deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`. If it throws with no response, call it again with the same input and key.\n6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.\n\nRead more: https://docs.usestatemachines.com, `node_modules/@usestatemachines/sdk/README.md`, {{origin}}/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n",
   llmsTxt:
-    "# State Machines\n\n> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, pause, resume and delete them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_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.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Pass `{ wait: false }` to get it back at once in `starting`. Always call `env.delete()` in a `finally`.\n- Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.\n- Pause and resume: `env.pause()` releases the compute and keeps the data; the time limit stops counting. `env.resume()` boots the apps again on the same data and waits until `running`. A paused environment is deleted after one day.\n- Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.\n- Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Read them from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`.\n- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A pause or delete during the snapshot fails it with `interrupted`.\n- Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.\n- YAML: `parseEnvironmentYaml(text)` turns a YAML document with the fields of `create` into its input.\n- Pagination: every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n\n## Statuses\n\nEnums are open: handle values you don't recognise.\n\n- Environment `status`: `starting`, `running`, `paused`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment keeps its data for `resume()` and has `failure`: `{ app, code, message }` with `start_failed`, `resume_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.\n- Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.\n- `create` and `resume` throw `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `paused` or `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.\n- `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.\n- `sm.environments.wait(id, { status })` and `sm.snapshots.wait(id, { status })` wait for any status, and throw once it cannot be reached without another call.\n\n## Limits\n\n- Running environments are capped per organization: `(await sm.me()).limits.concurrentEnvironments` counts `starting` and `running`.\n- `timeLimitMinutes` has a default and a maximum: `(await sm.me()).limits.timeLimitMinutes`. It counts `starting` and `running` only; at the end the environment is deleted with `reason: 'expired'`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `message`, `requestId`, `fields` and `retryAfterMs`. The SDK retries `502`, `503`, `504` and connection errors itself, until a deadline; `create` retries reuse one idempotency key. It retries nothing else.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `invalid_request` | 400 | Read `fields`, keyed by the dotted path of each wrong field. |\n| `forbidden` | 403 | The key lacks the permission. |\n| `not_found` | 404 | Check the ID and the workspace. |\n| `invalid_status` | 409 | The status does not allow the call: pause needs `running`; resume needs `paused` or `failed`. |\n| `snapshot_in_progress` | 409 | Wait for the running snapshot, then create another. |\n| `idempotency_key_reused` | 409 | The key was used with a different input. Replay with the exact same input. |\n| `workspace_archived` | 409 | The workspace is archived. |\n| `body_too_large` | 413 | The request body is over the API's size limit. Send less. |\n| `version_unavailable` | 422 | The app has no default version. |\n| `environment_limit_reached` | 429 | Pause or delete an environment, then create or resume again. |\n| `unavailable` | 503 | Retried automatically. If `create` still fails, call it again with the same input and your own `idempotencyKey`. |\n\n## Errors from the app URL\n\n`crm.fetch` returns these as responses with the same JSON envelope, and never retries them.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment_not_running` | 409 | The environment is paused, failed or deleted; `error.status` names it. Resume a paused or failed environment. |\n| `environment_starting` | 503 | Wait `Retry-After` and call again. |\n| `environment_unavailable` | 503 | The app is restarting. Wait `Retry-After` and call again. |\n| `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |\n| `capacity_exceeded` | 429 | Too many requests in flight to the app. Send fewer at once. |\n| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |\n\n## Quickstart\n\nSave it unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Docs\n\n- [Documentation](https://docs.usestatemachines.com): guides, concepts and reference ([llms.txt](https://docs.usestatemachines.com/llms.txt))\n- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions\n- [Agent skill]({{origin}}/skill.md): workflow, rules and troubleshooting for coding agents\n- [OpenAPI document](https://cdn.jsdelivr.net/npm/@usestatemachines/sdk/openapi.json): the HTTP API the SDK calls\n- [State Machines](https://usestatemachines.com): website\n",
+    "# State Machines\n\n> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, and delete them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_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.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Pass `{ wait: false }` to get it back at once in `starting`. Always call `env.delete()` in a `finally`.\n- Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.\n- Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.\n- Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Read them from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`.\n- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A delete during the snapshot fails it with `interrupted`.\n- Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.\n- YAML: `parseEnvironmentYaml(text)` turns a YAML document with the fields of `create` into its input.\n- Pagination: every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n\n## Statuses\n\nEnums are open: handle values you don't recognise.\n\n- Environment `status`: `starting`, `running`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment has `failure`: `{ app, code, message }` with `start_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.\n- Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.\n- `create` throws `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.\n- `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.\n- `sm.environments.wait(id, { status })` and `sm.snapshots.wait(id, { status })` wait for any status, and throw once it cannot be reached without another call.\n\n## Limits\n\n- Running environments are capped per organization: `(await sm.me()).limits.concurrentEnvironments` counts `starting` and `running`.\n- `timeLimitMinutes` has a default and a maximum: `(await sm.me()).limits.timeLimitMinutes`. It counts `starting` and `running` only; at the end the environment is deleted with `reason: 'expired'`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `message`, `requestId`, `fields` and `retryAfterMs`. The SDK retries `502`, `503`, `504` and connection errors itself, until a deadline; `create` retries reuse one idempotency key. It retries nothing else.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `invalid_request` | 400 | Read `fields`, keyed by the dotted path of each wrong field. |\n| `forbidden` | 403 | The key lacks the permission. |\n| `not_found` | 404 | Check the ID and the workspace. |\n| `invalid_status` | 409 | The status does not allow the call. Snapshots need a running environment. |\n| `snapshot_in_progress` | 409 | Wait for the running snapshot, then create another. |\n| `idempotency_key_reused` | 409 | The key was used with a different input. Replay with the exact same input. |\n| `workspace_archived` | 409 | The workspace is archived. |\n| `body_too_large` | 413 | The request body is over the API's size limit. Send less. |\n| `version_unavailable` | 422 | The app has no default version. |\n| `environment_limit_reached` | 429 | Delete an environment, then create again. |\n| `unavailable` | 503 | Retried automatically. If `create` still fails, call it again with the same input and your own `idempotencyKey`. |\n\n## Errors from the app URL\n\n`crm.fetch` returns these as responses with the same JSON envelope, and never retries them.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment_not_running` | 409 | The environment is failed or deleted; `error.status` names it. Create another environment. |\n| `environment_starting` | 503 | Wait `Retry-After` and call again. |\n| `environment_unavailable` | 503 | The app is restarting. Wait `Retry-After` and call again. |\n| `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |\n| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |\n\n## Quickstart\n\nSave it unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Docs\n\n- [Documentation](https://docs.usestatemachines.com): guides, concepts and reference ([llms.txt](https://docs.usestatemachines.com/llms.txt))\n- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions\n- [Agent skill]({{origin}}/skill.md): workflow, rules and troubleshooting for coding agents\n- [OpenAPI document](https://cdn.jsdelivr.net/npm/@usestatemachines/sdk/openapi.json): the HTTP API the SDK calls\n- [State Machines](https://usestatemachines.com): website\n",
   skill:
-    "---\nname: state-machines\ndescription: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, pausing and resuming, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.\n---\n\nRead `node_modules/@usestatemachines/sdk/README.md` before relying on memory; it matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.\n\n## Workflow\n\n1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n \"$STATEMACHINES_API_KEY\"`). If it isn't, ask the user to set it; the SDK doesn't read `.env` files.\n2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID; don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.\n3. Open a `try` right after `create` returns, and call `await env.delete()` in its `finally`. It deletes the environment and its data.\n4. Get credentials for one app: `const crm = await env.connect('salesforce')`. This acts as the app's default actor, the Salesforce administrator. To act with another user's permissions, pass an `actorId` from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name.\n5. Call the app with `crm.fetch(path)`. A leading `/` means the root of the app's `url`.\n\nThe whole flow, as the package ships it. It is ESM with top-level `await`: save it as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Rules\n\n- Always delete in `finally`.\n- `env.pause()` releases the compute and keeps the data; it is not cleanup. `env.resume()` waits until `running` again. A paused or failed environment is deleted after one day, and still needs `env.delete()` once you are done.\n- To create without waiting, pass `{ wait: false }`, then `sm.environments.wait(env.id, { status: 'running' })`.\n- The time limit counts `starting` and `running`. `(await sm.me()).limits.timeLimitMinutes` gives its `default` and `maximum`. Set `timeLimitMinutes` in `create` for longer runs.\n- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need. A paused or failed environment doesn't count until it resumes.\n- Never print, log or commit `STATEMACHINES_API_KEY`, `credentials.token` or `credentials.headers`.\n- Salesforce's SOAP API takes the actor token in the envelope, not a header: put `crm.token` in `SessionHeader/sessionId`. `crm.fetch` then sends only the environment token header.\n- `crm.fetch` never sends your API key, never follows redirects and only reaches URLs under the app's `url`.\n- Runtimes: Node.js, at the versions in the package's `engines` field, and Cloudflare Workers. ESM only. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. Never ship an API key to a browser.\n- In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATEMACHINES_API_KEY })`. A start takes longer than one request may last, so create with `{ wait: false }` and read `sm.environments.get(id)` in later requests until it is `running`, or pass a `signal` no shorter than the expected start.\n- Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- To reuse seeded data, `await env.snapshots.create({ name })` once, then `sm.environments.create({ snapshotId })` in place of `apps`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `SnapshotFailedError`, `UnexpectedStatusError`, `WaitTimeoutError`), not by `name`.\n\n## Recovering a failed create\n\nThe SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If you need to replay a create whose outcome is unknown, pass your own key: `sm.environments.create(input, { idempotencyKey })`, and call it again with the same input and key. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency_key_reused`.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `version_unavailable`, 422 | The app has no default version. | Check the app ID against `sm.apps.list()`. |\n| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete or pause one, then create again. |\n| `invalid_status`, 409 | The status does not allow the call, for example pausing an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |\n| `invalid_request`, 400 | A wrong field. | Read `err.fields`, keyed by dotted path. |\n| `EnvironmentFailedError` | The environment failed to start or resume. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |\n| `UnexpectedStatusError` | The environment was paused or deleted while the SDK waited. | Read `err.status` and `err.resource`. |\n| `WaitTimeoutError` | The status was not reached within `timeoutMs`. | Wait again with `sm.environments.wait(id, { status })`, or delete the environment. |\n| `snapshot_in_progress`, 409 | The environment already has a snapshot in `saving`. | `const [running] = (await sm.snapshots.list({ environmentId: env.id, status: ['saving'] })).data`, then `await sm.snapshots.wait(running.id, { status: 'ready' })`, then create another. |\n| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was paused or deleted first. | Create another snapshot while the environment is `running`. |\n| `environment_not_running`, 409, from `crm.fetch` | The environment is paused, failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`; `env.resume()` a paused or failed environment. |\n| `environment_starting` or `environment_unavailable`, 503, from `crm.fetch` | The app is starting or restarting. | Wait the `Retry-After` seconds and call again. |\n| A vendor client such as jsforce is refused by the gateway | The gateway needs `StateMachines-Environment-Token` on every request. | Prefer `crm.fetch`. If you pass `crm.headers` to another client, send them only to `crm.url` and disable redirects. |\n| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`; in Workers, pass `apiKey`. |\n\nMore: https://docs.usestatemachines.com, {{origin}}/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n",
+    "---\nname: state-machines\ndescription: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a disposable copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, credentials, choosing an actor, snapshots, cleanup, and errors such as environment_limit_reached and version_unavailable. Also use when the user mentions State Machines, STATEMACHINES_API_KEY or @usestatemachines/sdk.\n---\n\nRead `node_modules/@usestatemachines/sdk/README.md` before relying on memory. It matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.\n\n## Workflow\n\n1. Check that `STATEMACHINES_API_KEY` is set without printing it (`test -n \"$STATEMACHINES_API_KEY\"`). If it isn't, ask the user to set it. The SDK doesn't read `.env` files.\n2. Create the environment with only the apps the task needs: `const env = await sm.environments.create({ apps: ['salesforce'] })`. Log `await sm.apps.list()` for each app's ID. Don't guess IDs. `create` waits until the environment is `running`. If the start fails, the server deletes the environment and `create` throws `EnvironmentFailedError` with `err.environment.failure`.\n3. Open a `try` right after `create` returns, and call `await env.delete()` in its `finally`. It deletes the environment and its data.\n4. Get credentials for one app: `const crm = await env.connect('salesforce')`. This acts as the app's default actor, the Salesforce administrator. To act with another user's permissions, pass an `actorId` from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name.\n5. Call the app with `crm.fetch(path)`. A leading `/` means the root of the app's `url`.\n\nThe whole flow, as the package ships it. It is ESM with top-level `await`: save it as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\nconst sm = new StateMachines(); // reads STATEMACHINES_API_KEY\nconst env = await sm.environments.create({ apps: ['salesforce'] });\n\ntry {\n  const salesforce = await env.connect('salesforce');\n  const res = await salesforce.fetch('/services/data/v67.0/limits');\n  console.log(res.status, await res.json());\n} finally {\n  await env.delete();\n}\n```\n\n## Rules\n\n- Always delete in `finally`.\n- To create without waiting, pass `{ wait: false }`, then `sm.environments.wait(env.id, { status: 'running' })`.\n- The time limit counts `starting` and `running`. `(await sm.me()).limits.timeLimitMinutes` gives its `default` and `maximum`. Set `timeLimitMinutes` in `create` for longer runs.\n- Running environments are capped per organization: `limits.concurrentEnvironments` from `sm.me()`. Delete the ones you no longer need.\n- Never print, log or commit `STATEMACHINES_API_KEY`, `credentials.token` or `credentials.headers`.\n- Salesforce's SOAP API takes the actor token in the envelope, not a header: put `crm.token` in `SessionHeader/sessionId`. `crm.fetch` then sends only the environment token header.\n- `crm.fetch` never sends your API key, never follows redirects and only reaches URLs under the app's `url`.\n- Runtimes: Node.js, at the versions in the package's `engines` field, and Cloudflare Workers. ESM only. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. Never ship an API key to a browser.\n- In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATEMACHINES_API_KEY })`. A start takes longer than one request may last, so create with `{ wait: false }` and read `sm.environments.get(id)` in later requests until it is `running`, or pass a `signal` no shorter than the expected start.\n- Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- To reuse seeded data, `await env.snapshots.create({ name })` once, then `sm.environments.create({ snapshotId })` in place of `apps`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `SnapshotFailedError`, `UnexpectedStatusError`, `WaitTimeoutError`), not by `name`.\n\n## Recovering a failed create\n\nThe SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If you need to replay a create whose outcome is unknown, pass your own key: `sm.environments.create(input, { idempotencyKey })`, and call it again with the same input and key. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency_key_reused`.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `version_unavailable`, 422 | The app has no default version. | Check the app ID against `sm.apps.list()`. |\n| `environment_limit_reached`, 429 | The organization is at its cap of running environments. | List them with `sm.environments.list({ status: ['starting', 'running'] })`, delete one, then create again. |\n| `invalid_status`, 409 | The status does not allow the call, for example taking a snapshot of an environment that is `starting`. | Read `sm.environments.get(id)` and act on its `status`. |\n| `invalid_request`, 400 | A wrong field. | Read `err.fields`, keyed by dotted path. |\n| `EnvironmentFailedError` | The environment failed to start. | Read `err.environment.failure`: `{ app, code, message }`. `invalid_settings` means the app refused its settings. |\n| `UnexpectedStatusError` | The environment was deleted while the SDK waited. | Read `err.status` and `err.resource`. |\n| `WaitTimeoutError` | The status was not reached within `timeoutMs`. | Wait again with `sm.environments.wait(id, { status })`, or delete the environment. |\n| `snapshot_in_progress`, 409 | The environment already has a snapshot in `saving`. | `const [running] = (await sm.snapshots.list({ environmentId: env.id, status: ['saving'] })).data`, then `await sm.snapshots.wait(running.id, { status: 'ready' })`, then create another. |\n| `SnapshotFailedError` | The snapshot failed. `interrupted` means the environment was deleted first. | Create another snapshot while the environment is `running`. |\n| `environment_not_running`, 409, from `crm.fetch` | The environment is failed or deleted. `crm.fetch` returns it as a response and never retries. | Read `(await res.json()).error.status`. Create a new environment if you need another run. |\n| `environment_starting` or `environment_unavailable`, 503, from `crm.fetch` | The app is starting or restarting. | Wait the `Retry-After` seconds and call again. |\n| A vendor client such as jsforce is refused by the gateway | The gateway needs `StateMachines-Environment-Token` on every request. | Prefer `crm.fetch`. If you pass `crm.headers` to another client, send them only to `crm.url` and disable redirects. |\n| `TypeError: Pass apiKey or set STATEMACHINES_API_KEY.` | No key in the environment. | Ask the user to set `STATEMACHINES_API_KEY`. In Workers, pass `apiKey`. |\n\nMore: https://docs.usestatemachines.com, {{origin}}/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n",
 });

package/agents/llms.txt

@@ -1,6 +1,6 @@
 # State Machines
 
-> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, pause, resume and delete them with the TypeScript SDK `@usestatemachines/sdk`.
+> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to, and delete them with the TypeScript SDK `@usestatemachines/sdk`.
 
 Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: ["DOM"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_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.
 
@@ -8,10 +8,9 @@ Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Nod
 
 - Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Pass `{ wait: false }` to get it back at once in `starting`. Always call `env.delete()` in a `finally`.
 - Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.
-- Pause and resume: `env.pause()` releases the compute and keeps the data; the time limit stops counting. `env.resume()` boots the apps again on the same data and waits until `running`. A paused environment is deleted after one day.
 - Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.
 - Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Read them from the `actors` of the environment's version: the entry of `(await sm.apps.versions('salesforce')).data` whose `id` is `env.apps[0].versionId`.
-- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A pause or delete during the snapshot fails it with `interrupted`.
+- Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A delete during the snapshot fails it with `interrupted`.
 - Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.
 - YAML: `parseEnvironmentYaml(text)` turns a YAML document with the fields of `create` into its input.
 - Pagination: every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
@@ -20,9 +19,9 @@ 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`: `starting`, `running`, `paused`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment keeps its data for `resume()` and has `failure`: `{ app, code, message }` with `start_failed`, `resume_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.
+- Environment `status`: `starting`, `running`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment has `failure`: `{ app, code, message }` with `start_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.
 - Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.
-- `create` and `resume` throw `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `paused` or `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.
+- `create` throws `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.
 - `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.
 - `sm.environments.wait(id, { status })` and `sm.snapshots.wait(id, { status })` wait for any status, and throw once it cannot be reached without another call.
 
@@ -40,13 +39,13 @@ A failed API call throws `StateMachinesError` with `status`, `code`, `message`,
 | `invalid_request` | 400 | Read `fields`, keyed by the dotted path of each wrong field. |
 | `forbidden` | 403 | The key lacks the permission. |
 | `not_found` | 404 | Check the ID and the workspace. |
-| `invalid_status` | 409 | The status does not allow the call: pause needs `running`; resume needs `paused` or `failed`. |
+| `invalid_status` | 409 | The status does not allow the call. Snapshots need a running environment. |
 | `snapshot_in_progress` | 409 | Wait for the running snapshot, then create another. |
 | `idempotency_key_reused` | 409 | The key was used with a different input. Replay with the exact same input. |
 | `workspace_archived` | 409 | The workspace is archived. |
 | `body_too_large` | 413 | The request body is over the API's size limit. Send less. |
 | `version_unavailable` | 422 | The app has no default version. |
-| `environment_limit_reached` | 429 | Pause or delete an environment, then create or resume again. |
+| `environment_limit_reached` | 429 | Delete an environment, then create again. |
 | `unavailable` | 503 | Retried automatically. If `create` still fails, call it again with the same input and your own `idempotencyKey`. |
 
 ## Errors from the app URL
@@ -55,11 +54,10 @@ A failed API call throws `StateMachinesError` with `status`, `code`, `message`,
 
 | Code | Status | What to do |
 | --- | --- | --- |
-| `environment_not_running` | 409 | The environment is paused, failed or deleted; `error.status` names it. Resume a paused or failed environment. |
+| `environment_not_running` | 409 | The environment is failed or deleted; `error.status` names it. Create another environment. |
 | `environment_starting` | 503 | Wait `Retry-After` and call again. |
 | `environment_unavailable` | 503 | The app is restarting. Wait `Retry-After` and call again. |
 | `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |
-| `capacity_exceeded` | 429 | Too many requests in flight to the app. Send fewer at once. |
 | `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |
 
 ## Quickstart

package/agents/prompt.md

@@ -1,7 +1,7 @@
 Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.
 
 1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.
-2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n "$STATEMACHINES_API_KEY"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.
+2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n "$STATEMACHINES_API_KEY"`. If it is missing, stop and ask me to set it. The SDK doesn't read `.env` files. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.
 3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup. It prints `200` and the Salesforce org's limits:
 
 ```ts
@@ -19,8 +19,8 @@ try {
 }
 ```
 
-4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions; don't guess IDs. Create only the apps the task needs; a string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator; to act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.
-5. Always call `env.delete()` in a `finally`; it deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`; if it throws with no response, call it again with the same input and key.
+4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions. Don't guess IDs. Create only the apps the task needs. A string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator. To act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.
+5. Always call `env.delete()` in a `finally`. It deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`. If it throws with no response, call it again with the same input and key.
 6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.
 
 Read more: https://docs.usestatemachines.com, `node_modules/@usestatemachines/sdk/README.md`, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/esm/extensions/client.d.ts

@@ -40,12 +40,6 @@ export interface CreateEnvironmentOptions extends SignalOptions {
     /** A replay with the same key and input returns the same environment. Defaults to a new UUID. */
     idempotencyKey?: string;
 }
-export interface ResumeOptions extends SignalOptions {
-    /** Wait until the environment is `running`. Defaults to true. */
-    wait?: boolean;
-    /** Deadline for the wait. Defaults to 10 minutes. */
-    timeoutMs?: number;
-}
 export type CreateSnapshotOptions = CreateEnvironmentOptions;
 export interface ConnectOptions {
     /** Defaults to the app's default actor (for Salesforce, the administrator). */
@@ -87,10 +81,6 @@ export declare class StateMachines {
         get: (environmentId: string) => Promise<Environment>;
         /** `labels` replaces the whole map. */
         update: (environmentId: string, body: UpdateEnvironmentRequestBody) => Promise<Environment>;
-        /** Takes effect when the API answers: the gateway refuses calls from then on. */
-        pause: (environmentId: string, options?: SignalOptions) => Promise<Environment>;
-        /** Resumes a paused or failed environment and, unless `wait` is false, waits until it is `running`. */
-        resume: (environmentId: string, options?: ResumeOptions) => Promise<Environment>;
         /** Deletes the environment and its data. Safe to repeat. */
         delete: (environmentId: string, options?: SignalOptions) => Promise<Environment>;
         /**

package/esm/extensions/client.js

@@ -72,18 +72,6 @@ export class StateMachines {
         get: async (environmentId) => this.#bind(await this.#call(undefined, (call) => this.#sdk.environments.get({ environmentId }, call))),
         /** `labels` replaces the whole map. */
         update: async (environmentId, body) => this.#bind(await this.#call(undefined, (call) => this.#sdk.environments.update({ environmentId, body }, call))),
-        /** Takes effect when the API answers: the gateway refuses calls from then on. */
-        pause: async (environmentId, options = {}) => this.#bind(await this.#call(options.signal, (call) => this.#sdk.environments.pause({ environmentId }, call))),
-        /** Resumes a paused or failed environment and, unless `wait` is false, waits until it is `running`. */
-        resume: async (environmentId, options = {}) => {
-            const resumed = await this.#call(options.signal, (call) => this.#sdk.environments.resume({ environmentId }, call));
-            return options.wait === false
-                ? this.#bind(resumed)
-                : this.environments.wait(environmentId, {
-                    status: 'running',
-                    ...waitOptions(options),
-                });
-        },
         /** Deletes the environment and its data. Safe to repeat. */
         delete: async (environmentId, options = {}) => this.#bind(await this.#call(options.signal, (call) => this.#sdk.environments.delete({ environmentId }, call))),
         /**
@@ -186,8 +174,6 @@ export class StateMachines {
         const { id } = data;
         const helpers = {
             connect: (app, options = {}) => this.#connect(id, data, app, options),
-            pause: (options) => this.environments.pause(id, options),
-            resume: (options) => this.environments.resume(id, options),
             delete: (options) => this.environments.delete(id, options),
             refresh: () => this.environments.get(id),
             snapshots: {

package/esm/extensions/environment.d.ts

@@ -1,6 +1,6 @@
 import type { Environment as EnvironmentData } from '../models/environment.js';
 import type { Snapshot } from '../models/snapshot.js';
-import type { ConnectOptions, CreateSnapshotOptions, ResumeOptions, SignalOptions } from './client.js';
+import type { ConnectOptions, CreateSnapshotOptions, SignalOptions } from './client.js';
 import type { Credentials } from './credentials.js';
 /**
  * An environment as the API returned it, with helpers bound to it. The helpers are not
@@ -10,9 +10,6 @@ export type Environment = EnvironmentData & EnvironmentHelpers;
 export interface EnvironmentHelpers {
     /** Credentials for one app; `actorId` defaults to the app's default actor. */
     connect(app: string, options?: ConnectOptions): Promise<Credentials>;
-    pause(options?: SignalOptions): Promise<Environment>;
-    /** Waits until `running` unless `wait` is false. */
-    resume(options?: ResumeOptions): Promise<Environment>;
     delete(options?: SignalOptions): Promise<Environment>;
     /** Reads the environment again. */
     refresh(): Promise<Environment>;

package/esm/extensions/index.d.ts

@@ -1,5 +1,5 @@
 export type { Actor, Api, App, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, Me, Permission, Principal, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotStatus, Version, Workspace, } from '../models/index.js';
-export type { ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListAuditEventsQuery, ListEnvironmentsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, ResumeOptions, SignalOptions, StateMachinesOptions, } from './client.js';
+export type { ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListAuditEventsQuery, ListEnvironmentsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, SignalOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
 export type { Credentials } from './credentials.js';
 export type { Environment, EnvironmentHelpers } from './environment.js';

package/esm/extensions/wait.js

@@ -2,14 +2,10 @@ import { EnvironmentFailedError, isTransient, SnapshotFailedError, toStateMachin
 import { linkSignal } from './signal.js';
 export const defaultTimeoutMs = 600000;
 const readTimeoutMs = 30000;
-/**
- * The statuses each status reaches with no call from the customer: a boot ends, a restart
- * fails, the time limit passes, a paused or failed environment expires after a day.
- */
+/** Statuses reachable without another customer request. */
 const environmentReaches = {
     starting: ['running', 'failed', 'deleted'],
     running: ['failed', 'deleted'],
-    paused: ['deleted'],
     failed: ['deleted'],
     deleted: [],
 };

package/esm/lib/config.d.ts

@@ -31,7 +31,7 @@ export declare function serverURLFromOptions(options: SDKOptions): URL | null;
 export declare const SDK_METADATA: {
     readonly language: "typescript";
     readonly openapiDocVersion: "1.0.0";
-    readonly sdkVersion: "0.6.1";
+    readonly sdkVersion: "0.7.0";
     readonly genVersion: "2.941.0";
-    readonly userAgent: "speakeasy-sdk/typescript 0.6.1 2.941.0 1.0.0 @usestatemachines/sdk";
+    readonly userAgent: "speakeasy-sdk/typescript 0.7.0 2.941.0 1.0.0 @usestatemachines/sdk";
 };

package/esm/lib/config.js

@@ -24,7 +24,7 @@ export function serverURLFromOptions(options) {
 export const SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "1.0.0",
-    sdkVersion: "0.6.1",
+    sdkVersion: "0.7.0",
     genVersion: "2.941.0",
-    userAgent: "speakeasy-sdk/typescript 0.6.1 2.941.0 1.0.0 @usestatemachines/sdk",
+    userAgent: "speakeasy-sdk/typescript 0.7.0 2.941.0 1.0.0 @usestatemachines/sdk",
 };