@usestatemachines/sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 State
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @usestatemachines/sdk
+
+TypeScript SDK for [State](https://usestatemachines.com): create disposable environments of
+replica apps, wait until they are ready, connect to them, and clean them up.
+
+- Node.js 20.20 or later (22 or 24 recommended), and Cloudflare Workers. ESM only.
+- Retries transient failures safely, including `create`, which is idempotent.
+
+## Install and quickstart
+
+```sh
+npm install @usestatemachines/sdk
+```
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+// Reads STATE_API_KEY. The workspace comes from the key.
+const sm = new StateMachines();
+
+// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
+const environment = await sm.environments.create({
+  name: 'quickstart',
+  // The default Salesforce app; sm.catalog.get() lists every app.
+  apps: [{ key: 'crm', appId: 'salesforce' }],
+});
+
+try {
+  await sm.environments.waitUntilReady(environment.id);
+
+  // Salesforce has several actors (its users) and API profiles, so pick one of each.
+  // The connection lists the actors; this acts as the first.
+  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
+  const [actor] = actors;
+
+  if (!actor) {
+    throw new Error('The Salesforce app has no actors.');
+  }
+
+  const crm = await sm.environments.connect(environment.id, 'crm', {
+    actorId: actor.id,
+    apiId: 'rest',
+  });
+  const response = await crm.fetch('/services/data/v67.0/limits');
+
+  console.log(response.status, await response.json());
+} finally {
+  // Stop even when a step fails; lifetime counts from the start.
+  await sm.environments.stop(environment.id);
+}
+```
+
+## Authentication
+
+`new StateMachines()` reads the API key from `STATE_API_KEY`, but only where a global `process`
+exists. Without a key, the constructor throws a `TypeError`.
+
+In Cloudflare Workers, pass `apiKey` explicitly:
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+export default {
+  async fetch(_request: Request, env: { STATE_API_KEY: string }) {
+    const sm = new StateMachines({ apiKey: env.STATE_API_KEY });
+    // Bound the call: retries could otherwise hold the request for minutes.
+    const { data } = await sm.environments.list(
+      { status: 'live' },
+      { signal: AbortSignal.timeout(20_000) },
+    );
+
+    return Response.json(data.map(({ id, status }) => ({ id, status })));
+  },
+};
+```
+
+Calls that need a workspace (`environments.list` and `environments.create`) use, in order:
+
+1. `workspaceId` passed to that call
+2. `workspaceId` passed to the constructor
+3. the workspace of the API key, read once from `sm.credential.get()` and cached
+
+A user session that has no workspace can't supply one, so those calls throw and ask for
+`workspaceId`.
+
+Other constructor options: `serverURL`, `fetch` (a custom fetch implementation), `httpClient`
+(copied, never changed; not combined with `fetch`) and `timeoutMs` (see below).
+
+## Environment lifecycle
+
+1. `create(input)` returns the environment as soon as the API accepts it, before the apps boot.
+2. `waitUntilReady(id)` polls until it is `running`. It throws `EnvironmentFailedError` if the
+   environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after `timeoutMs`
+   (default 10 minutes). It **never stops the environment**, even when it throws.
+3. `connect(id, appKey, { actorId, apiId })` returns a `Connection` to one app (see
+   [Connections](#connections)).
+4. `stop(id)` stops it. Always stop in a `finally`.
+
+`lifetimeMinutes` counts from when the environment starts, so boot time uses part of it. When it
+runs out, the environment stops with `stopReason: 'expired'`. The default and maximum are in
+`(await sm.credential.get()).limits.environmentLifetime`.
+
+Both waits accept `{ timeoutMs, signal }`. Aborting the `signal` rejects the wait with
+`signal.reason`. They poll at growing intervals of about 1 to 5 seconds, with random jitter, and
+keep polling through transient failures.
+
+## Retries and timeouts
+
+Every API call retries on its own, with growing, jittered delays of up to about 5 seconds between
+attempts:
+
+| Response | Retried | Why |
+| --- | --- | --- |
+| `502`, `503`, `504` | Yes | The API is saturated (`503`), or Cloudflare can't reach it for a moment (`502`, `504`). |
+| No response: connection error or attempt timeout | Yes | The request may never have arrived. |
+| `429` (`environment-limit`) | No | A quota on live environments. Stop one, then create again. |
+| Any other status: other `4xx`, and other `5xx` | No | Not retried by the SDK. |
+
+- A `Retry-After` header is honoured, up to 5 seconds.
+- Retries have a 10-minute budget, checked after each failed attempt. It is not a deadline: the
+  last delay and attempt can end later. Pass a `signal` to bound a call: an abort during a
+  retry delay takes effect when the delay ends, at most about 5 seconds later.
+- `timeoutMs` (constructor option, default 60 seconds) limits **each attempt**. A timed-out
+  attempt is retried with a fresh timeout.
+- A `signal` passed to a call aborts the whole call, including retries. The call rejects with a
+  `StateMachinesError` whose `status` is `null`.
+
+```ts
+const environment = await sm.environments.get('env_123', {
+  signal: AbortSignal.timeout(30_000),
+});
+```
+
+## Recovering a failed create
+
+Every error thrown by `environments.create` carries `err.idempotencyKey`. Replaying the create
+with that key and the **same input** returns the environment the first call created, instead of
+creating a duplicate. If the first call never reached the API, the replay creates it. Replaying
+with a different input fails with `idempotency-conflict`. Keys are kept for a day.
+
+```ts
+import { StateMachines, StateMachinesError } from '@usestatemachines/sdk';
+
+const sm = new StateMachines();
+const input = { name: 'nightly', apps: [{ key: 'crm', appId: 'salesforce' }] };
+
+async function createOnce() {
+  try {
+    return await sm.environments.create(input);
+  } catch (error) {
+    // Safe after any failure: the replay can't create a second environment.
+    if (error instanceof StateMachinesError && error.idempotencyKey) {
+      return sm.environments.create(input, { idempotencyKey: error.idempotencyKey });
+    }
+
+    throw error;
+  }
+}
+
+const environment = await createOnce();
+```
+
+## Cleanup
+
+`stop` returns as soon as the API accepts it. To confirm cleanup, call `waitUntilStopped`. It
+resolves only when:
+
+- the environment is `stopped` or `failed`, **and**
+- every app's `disposal` is `complete`.
+
+If any app's disposal is `failed` or `unknown`, it throws `DisposalIncompleteError` with the
+environment. We recommend it in CI, so a run fails when cleanup can't be confirmed:
+
+```ts
+await sm.environments.stop(environment.id);
+await sm.environments.waitUntilStopped(environment.id);
+```
+
+## Errors
+
+Every failed API call throws a `StateMachinesError`:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `status` | `number \| null` | HTTP status; `null` when there was no parsed response. |
+| `code` | `ErrorCode \| null` | API error code, such as `environment-limit`. |
+| `requestId` | `string \| null` | Include it when you contact support. |
+| `fields` | `Record<string, string[]> \| null` | Per-field validation messages. |
+| `retryAfter` | `number \| null` | Milliseconds the API asked you to wait. |
+| `retryable` | `boolean` | `true` for a `502`, `503` or `504`, a connection error or an attempt timeout. `false` for caller aborts, request validation errors and responses that aren't valid JSON. |
+| `idempotencyKey` | `string \| undefined` | Set on `environments.create` failures. |
+
+`status` is `null` when no HTTP response was received, and also when a response wasn't valid JSON.
+Error messages never include response bodies. The waits throw their own classes:
+`EnvironmentFailedError` and `DisposalIncompleteError` (both with `environment`) and
+`TimeoutError` (with `timeoutMs` and the last `environment` seen, or `null`). Check errors with
+`instanceof`, not `name`: a platform abort is also named `TimeoutError`.
+
+```ts
+import { ErrorCode, StateMachinesError } from '@usestatemachines/sdk';
+
+try {
+  await sm.environments.create(input);
+} catch (error) {
+  if (error instanceof StateMachinesError && error.code === ErrorCode.EnvironmentLimit) {
+    console.error('Too many live environments; stop one first.');
+  } else {
+    throw error;
+  }
+}
+```
+
+## Pagination
+
+`environments.list`, `environments.events` and `workspaces.events` return one page,
+`{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`:
+
+```ts
+let cursor: string | undefined;
+
+do {
+  const page = await sm.environments.list({ status: 'live', cursor });
+
+  for (const environment of page.data) {
+    console.log(environment.id, environment.status);
+  }
+
+  cursor = page.nextCursor ?? undefined;
+} while (cursor);
+```
+
+## Connections
+
+`connect(id, appKey)` requires the app to be ready. If the app has several actors, pass
+`{ actorId }`; if it has several API profiles, pass `{ apiId }`. Salesforce has both, so pass both.
+Otherwise it throws a `TypeError` that names the choices. It returns a `Connection` with `baseUrl`, `environmentId`, `appKey`, `actorId`, `api` and
+`expiresAt`, and these ways to call the app:
+
+- `headers()` returns `X-State-Environment-Token` plus the app's actor header, such as
+  `Authorization: Bearer <token>`. For an API that takes the actor token in the request body,
+  such as SOAP, it returns only `X-State-Environment-Token`.
+- `fetch(path, init)` sends one request with those headers and returns the raw `Response`. A
+  leading `/` means the root of `baseUrl`. It:
+  - only reaches URLs under `baseUrl`, and throws for any other path
+  - never follows redirects (`redirect: 'manual'`)
+  - never sends your API key
+  - never retries
+  - rejects `x-state-*` headers from the caller
+- `actorToken()` returns the actor token itself, for APIs that take it in the request body, such
+  as SOAP. Treat it as a secret.
+
+`formatActorHeader(actorHeader, token)` returns the `{ name, value }` for an API profile's actor
+header: `Bearer <token>` for `Authorization`, and the raw token for any other header. It returns
+`null` for a SOAP profile (`SOAP SessionHeader`), whose token goes in the envelope instead.
+
+**SOAP APIs:** Salesforce's `soap-partner` profile, when the release offers it (the default
+release does), takes the actor token in the envelope's `SessionHeader/sessionId`. XML-escape any
+value you put in the envelope:
+
+```ts
+const soap = await sm.environments.connect(environment.id, 'crm', {
+  actorId: actor.id, // from getConnection, as in the quickstart
+  apiId: 'soap-partner',
+});
+const envelope = `<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:partner.soap.sforce.com">
+  <env:Header><SessionHeader><sessionId>${soap.actorToken()}</sessionId></SessionHeader></env:Header>
+  <env:Body><undelete><ids>001000000000000AAA</ids></undelete></env:Body>
+</env:Envelope>`;
+const response = await soap.fetch('/services/Soap/u/67.0', {
+  method: 'POST',
+  headers: { 'Content-Type': 'text/xml', SOAPAction: '""' },
+  body: envelope,
+});
+```
+
+**Vendor clients:** the gateway needs `X-State-Environment-Token` on every request. A client such
+as jsforce only sends it if you configure custom headers. Prefer `Connection.fetch`. If you pass
+`headers()` to another client, those headers carry live tokens: only send them to `baseUrl`, and
+don't let the client follow redirects, which would forward the tokens to another host:
+
+```ts
+const crm = await sm.environments.connect(environment.id, 'crm', {
+  actorId: actor.id, // from getConnection, as in the quickstart
+  apiId: 'rest',
+});
+const response = await fetch(new URL('services/data/v67.0/limits', crm.baseUrl), {
+  headers: crm.headers(),
+  redirect: 'manual',
+});
+```
+
+## Supported runtimes
+
+- **Node.js 20.20 or later**, with 22 or 24 recommended: Node 20 is past its end of life, and
+  earlier Node 20 releases fail when retrying a `POST`.
+- **Cloudflare Workers.**
+- **Not browsers.** Never ship an API key to a browser.
+
+TypeScript consumers need `lib: ["DOM"]` or `@types/node`, for the `fetch`, `Request` and
+`Response` types.
+
+## Compatibility
+
+- While the version is `0.x`, a minor release may include breaking changes. Pin the minor
+  version.
+- The API may add error codes and enum values, such as a new status or stop reason. Enums are
+  open: handle values you don't recognise.
+
+## License
+
+MIT

package/agents/SKILL.md

@@ -0,0 +1,90 @@
+---
+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 sandboxed copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, connecting as an actor, cleanup, and errors such as environment-limit and release-unavailable. Also use when the user mentions State Machines, STATE_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`.
+
+## Workflow
+
+1. Check that `STATE_API_KEY` is set without printing it (`test -n "$STATE_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. Log `await sm.catalog.get()` for each app's `appId` and the actors and API profiles its release offers; don't guess IDs. `key` is your own name for the app, and later calls take it.
+3. Open a `try` right after `create` returns, and call `stop` in its `finally`.
+4. `await sm.environments.waitUntilReady(environment.id)`. It never stops the environment.
+5. Connect as one actor through one API profile. Salesforce has several of each, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name, so read them from the connection instead of hard-coding one. Choose the actor whose permissions the task needs; each release in the catalog lists them.
+6. Call the app with the connection's `fetch`. A leading `/` means the root of `baseUrl`.
+7. In `finally`, `await sm.environments.stop(environment.id)`. In CI, then await `sm.environments.waitUntilStopped(environment.id)`.
+
+The 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`.
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+// Reads STATE_API_KEY. The workspace comes from the key.
+const sm = new StateMachines();
+
+// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
+const environment = await sm.environments.create({
+  name: 'quickstart',
+  // The default Salesforce app; sm.catalog.get() lists every app.
+  apps: [{ key: 'crm', appId: 'salesforce' }],
+});
+
+try {
+  await sm.environments.waitUntilReady(environment.id);
+
+  // Salesforce has several actors (its users) and API profiles, so pick one of each.
+  // The connection lists the actors; this acts as the first.
+  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
+  const [actor] = actors;
+
+  if (!actor) {
+    throw new Error('The Salesforce app has no actors.');
+  }
+
+  const crm = await sm.environments.connect(environment.id, 'crm', {
+    actorId: actor.id,
+    apiId: 'rest',
+  });
+  const response = await crm.fetch('/services/data/v67.0/limits');
+
+  console.log(response.status, await response.json());
+} finally {
+  // Stop even when a step fails; lifetime counts from the start.
+  await sm.environments.stop(environment.id);
+}
+```
+
+## Rules
+
+- Always stop in `finally`. `waitUntilStopped` confirms every app was disposed; use it in CI so a run fails when cleanup can't be confirmed.
+- Lifetime counts from the start, including boot. It defaults to 15 minutes, or the deployment maximum if that is lower: `(await sm.credential.get()).limits.environmentLifetime`. Set `lifetimeMinutes` in `create` for longer runs.
+- Live environments are capped per organization: `limits.liveEnvironments` from `sm.credential.get()`. Stop the ones you no longer need.
+- Never print, log or commit `STATE_API_KEY`, tokens, or `headers()` or `actorToken()` output.
+- Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope, not a header: put `connection.actorToken()` in `SessionHeader/sessionId`. For it, `headers()` carries only `X-State-Environment-Token`.
+- `connection.fetch` never sends your API key, never follows redirects and only reaches URLs under `baseUrl`.
+- Runtimes: Node.js 20.20 or later (22 or 24 recommended), and Cloudflare Workers. ESM only. TypeScript needs `lib: ["DOM"]` or `@types/node`. Never ship an API key to a browser.
+- In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATE_API_KEY })`, and bound calls with `{ signal: AbortSignal.timeout(20_000) }`, since retries can take minutes.
+- `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
+- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `DisposalIncompleteError`, `TimeoutError`), not by `name`.
+
+## Recovering a failed create
+
+The SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If `create` still throws, don't call it again as a new request: that can start a second environment. Every error from `create` carries `err.idempotencyKey`. Call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency-conflict`. Keys are kept for a day.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `release-unavailable`, 422 | Unknown or retired `appId` or `appReleaseId`. | Check the IDs against `sm.catalog.get()`. Omit `appReleaseId` for the default release. |
+| `release-unavailable`, 503, or a failed app with that `errorCode` | This deployment doesn't serve the release. The SDK retries a 503 within a 10-minute budget. | Omit `appReleaseId`. If it persists, report the `requestId`. Pass a `signal` to bound the wait. |
+| `environment-limit`, 429 | The organization is at its live-environment cap. Not retried. | `sm.environments.list({ status: 'live' })`, stop one you no longer need, then create again. |
+| `lifetime-too-long`, 422 | `lifetimeMinutes` is above the maximum. | Use at most `limits.environmentLifetime.maximumMinutes`. |
+| `TypeError: Choose one actor: ...` or `Choose one API: ...` | The app has several actors or API profiles, or the ID doesn't exist. The message lists the valid IDs. | Pass both `actorId` and `apiId` from the listed IDs. |
+| `TypeError: App ... is not ready to connect` | connect() ran before the app was `ready`. | Await `waitUntilReady` first. |
+| `connection-unavailable`, 409 | The app stopped, or the environment is no longer `running`. | Check `sm.environments.get(environment.id)`; if it stopped or expired, create a new one. |
+| `EnvironmentFailedError` from `waitUntilReady` | The environment became `failed`, `stopping` or `stopped`. | Read `err.environment.stopReason` and each app's `errorCode`. Still stop it in `finally`. |
+| A vendor client such as jsforce is rejected by the gateway | The gateway needs `X-State-Environment-Token` on every request; jsforce only sends it with custom headers configured. | Prefer `connection.fetch`. If you pass `headers()` to another client, send them only to `baseUrl` and disable redirects. |
+| `TypeError: Pass apiKey or set STATE_API_KEY.` | No key in the environment. | Ask the user to set `STATE_API_KEY`; in Workers, pass `apiKey`. |
+
+More: https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/agents/index.d.ts

@@ -0,0 +1,13 @@
+// Generated by scripts/build-agents.mjs.
+
+export declare const prompt: string;
+
+export declare const llmsTxt: string;
+
+export declare const skill: string;
+
+export declare const quickstart: string;
+
+export declare const templates: Readonly<
+  Record<'prompt' | 'llmsTxt' | 'skill', string>
+>;

package/agents/index.js

@@ -0,0 +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 20.20 or later and on Cloudflare Workers, not in browsers.\n2. Check that `STATE_API_KEY` is set without printing it: `test -n \"$STATE_API_KEY\"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens. 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:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's `appId` and the actors and API profiles its release offers; don't guess IDs. Create only the apps the task needs, and pass connect() the `actorId` and `apiId` the task needs.\n5. Always stop the environment in a `finally`. In CI, then await `sm.environments.waitUntilStopped(environment.id)` so the run fails if cleanup isn't confirmed.\n6. The SDK retries `502`, `503`, `504` and connection errors itself. If `create` still throws, call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. Never retry `create` without the key: that can start a second environment.\n\nRead more: `node_modules/@usestatemachines/sdk/README.md`, https://state-web.usestatemachines.workers.dev/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 and stop them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later (22 or 24 recommended) and Cloudflare Workers, not browsers. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATE_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. Create it, wait until it is `running`, connect, then stop it.\n- App key and app ID: in `create`, `apps: [{ key: 'crm', appId: 'salesforce' }]`. `appId` names the app in the catalog (`sm.catalog.get()`); `key` is your own name for it in this environment, and later calls take the key.\n- Actor: who the app sees you as. API profile: one API of the app, with its path and versions. Each release in the catalog lists both.\n- Connection: connect() needs the app `ready`. Salesforce has several actors and API profiles, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name; read them from the connection instead of hard-coding one. `connection.fetch` never sends your API key, never follows redirects and never retries. `connection.headers()` returns live tokens: treat them as secrets. Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope instead: put `connection.actorToken()`, also a secret, in `SessionHeader/sessionId`; `headers()` then carries only `X-State-Environment-Token`.\n- Vendor clients: the gateway needs `X-State-Environment-Token` on every request. A client such as jsforce only sends it if you configure custom headers. Prefer `connection.fetch`; if you pass `headers()` to another client, send them only to `connection.baseUrl` and disable redirects.\n- Pagination: `environments.list`, `environments.events` and `workspaces.events` return 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`: `queued`, `starting`, `running`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`.\n- App `status`: `pending`, `starting`, `ready`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.\n- App `disposal`: `pending`, `complete`, `failed`, `unknown`.\n- `waitUntilReady` throws `EnvironmentFailedError` if the environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default. It never stops the environment.\n- `waitUntilStopped` resolves when the environment is `stopped` or `failed` and every app's disposal is `complete`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.\n\n## Limits\n\n- Live environments are capped per organization: `(await sm.credential.get()).limits.liveEnvironments`.\n- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it; at the end the environment stops with `stopReason: 'expired'`.\n- Always call `stop` in a `finally`. In CI, then await `waitUntilStopped`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `requestId` and `retryAfter`. The SDK retries `502`, `503`, `504`, connection errors and attempt timeouts itself, within a 10-minute retry budget (the last attempt can end later); `create` retries reuse one idempotency key. It retries nothing else: not `429`, other `4xx` or other `5xx`. Every `create` error carries `err.idempotencyKey`: `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same input returns the environment the first call created.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment-limit` | 429 | Not retried. Stop a live environment (`sm.environments.list({ status: 'live' })`), then create again. |\n| `lifetime-too-long` | 422 | Lower `lifetimeMinutes` to at most `limits.environmentLifetime.maximumMinutes`. |\n| `release-unavailable` | 422 | Unknown or retired app or release. Check `appId` and `appReleaseId` against `sm.catalog.get()`. |\n| `release-unavailable` | 503 | This deployment doesn't serve the release. Retried within the budget; omit `appReleaseId` to use the default release, or contact support with the `requestId`. A failed app can carry it as `errorCode`. |\n| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it stopped or expired, create a new one. (Before that, connect() throws a `TypeError` for an app that isn't ready or an unknown actor or API.) |\n| `idempotency-conflict` | 409 | The idempotency key was used with a different input. Replay with the exact same input. |\n| `request-timeout` | 503 | Retried automatically. If `create` still fails, replay it with `err.idempotencyKey`. |\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\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n## Docs\n\n- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions\n- [Agent skill](https://state-web.usestatemachines.workers.dev/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): product site\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 sandboxed copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, connecting as an actor, cleanup, and errors such as environment-limit and release-unavailable. Also use when the user mentions State Machines, STATE_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 `STATE_API_KEY` is set without printing it (`test -n \"$STATE_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. Log `await sm.catalog.get()` for each app's `appId` and the actors and API profiles its release offers; don't guess IDs. `key` is your own name for the app, and later calls take it.\n3. Open a `try` right after `create` returns, and call `stop` in its `finally`.\n4. `await sm.environments.waitUntilReady(environment.id)`. It never stops the environment.\n5. Connect as one actor through one API profile. Salesforce has several of each, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name, so read them from the connection instead of hard-coding one. Choose the actor whose permissions the task needs; each release in the catalog lists them.\n6. Call the app with the connection's `fetch`. A leading `/` means the root of `baseUrl`.\n7. In `finally`, `await sm.environments.stop(environment.id)`. In CI, then await `sm.environments.waitUntilStopped(environment.id)`.\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\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n## Rules\n\n- Always stop in `finally`. `waitUntilStopped` confirms every app was disposed; use it in CI so a run fails when cleanup can't be confirmed.\n- Lifetime counts from the start, including boot. It defaults to 15 minutes, or the deployment maximum if that is lower: `(await sm.credential.get()).limits.environmentLifetime`. Set `lifetimeMinutes` in `create` for longer runs.\n- Live environments are capped per organization: `limits.liveEnvironments` from `sm.credential.get()`. Stop the ones you no longer need.\n- Never print, log or commit `STATE_API_KEY`, tokens, or `headers()` or `actorToken()` output.\n- Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope, not a header: put `connection.actorToken()` in `SessionHeader/sessionId`. For it, `headers()` carries only `X-State-Environment-Token`.\n- `connection.fetch` never sends your API key, never follows redirects and only reaches URLs under `baseUrl`.\n- Runtimes: Node.js 20.20 or later (22 or 24 recommended), 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.STATE_API_KEY })`, and bound calls with `{ signal: AbortSignal.timeout(20_000) }`, since retries can take minutes.\n- `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `DisposalIncompleteError`, `TimeoutError`), 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 `create` still throws, don't call it again as a new request: that can start a second environment. Every error from `create` carries `err.idempotencyKey`. Call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency-conflict`. Keys are kept for a day.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `release-unavailable`, 422 | Unknown or retired `appId` or `appReleaseId`. | Check the IDs against `sm.catalog.get()`. Omit `appReleaseId` for the default release. |\n| `release-unavailable`, 503, or a failed app with that `errorCode` | This deployment doesn't serve the release. The SDK retries a 503 within a 10-minute budget. | Omit `appReleaseId`. If it persists, report the `requestId`. Pass a `signal` to bound the wait. |\n| `environment-limit`, 429 | The organization is at its live-environment cap. Not retried. | `sm.environments.list({ status: 'live' })`, stop one you no longer need, then create again. |\n| `lifetime-too-long`, 422 | `lifetimeMinutes` is above the maximum. | Use at most `limits.environmentLifetime.maximumMinutes`. |\n| `TypeError: Choose one actor: ...` or `Choose one API: ...` | The app has several actors or API profiles, or the ID doesn't exist. The message lists the valid IDs. | Pass both `actorId` and `apiId` from the listed IDs. |\n| `TypeError: App ... is not ready to connect` | connect() ran before the app was `ready`. | Await `waitUntilReady` first. |\n| `connection-unavailable`, 409 | The app stopped, or the environment is no longer `running`. | Check `sm.environments.get(environment.id)`; if it stopped or expired, create a new one. |\n| `EnvironmentFailedError` from `waitUntilReady` | The environment became `failed`, `stopping` or `stopped`. | Read `err.environment.stopReason` and each app's `errorCode`. Still stop it in `finally`. |\n| A vendor client such as jsforce is rejected by the gateway | The gateway needs `X-State-Environment-Token` on every request; jsforce only sends it with custom headers configured. | Prefer `connection.fetch`. If you pass `headers()` to another client, send them only to `baseUrl` and disable redirects. |\n| `TypeError: Pass apiKey or set STATE_API_KEY.` | No key in the environment. | Ask the user to set `STATE_API_KEY`; in Workers, pass `apiKey`. |\n\nMore: https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n";
+
+export const quickstart =
+  "import { StateMachines } from '@usestatemachines/sdk';\n\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\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 20.20 or later and on Cloudflare Workers, not in browsers.\n2. Check that `STATE_API_KEY` is set without printing it: `test -n \"$STATE_API_KEY\"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens. 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:\n\n```ts\nimport { StateMachines } from '@usestatemachines/sdk';\n\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's `appId` and the actors and API profiles its release offers; don't guess IDs. Create only the apps the task needs, and pass connect() the `actorId` and `apiId` the task needs.\n5. Always stop the environment in a `finally`. In CI, then await `sm.environments.waitUntilStopped(environment.id)` so the run fails if cleanup isn't confirmed.\n6. The SDK retries `502`, `503`, `504` and connection errors itself. If `create` still throws, call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. Never retry `create` without the key: that can start a second environment.\n\nRead more: `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 and stop them with the TypeScript SDK `@usestatemachines/sdk`.\n\nInstall with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later (22 or 24 recommended) and Cloudflare Workers, not browsers. TypeScript needs `lib: [\"DOM\"]` or `@types/node`. `new StateMachines()` reads the API key from `STATE_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory.\n\n## Concepts\n\n- Environment: one disposable run of one or more apps. Create it, wait until it is `running`, connect, then stop it.\n- App key and app ID: in `create`, `apps: [{ key: 'crm', appId: 'salesforce' }]`. `appId` names the app in the catalog (`sm.catalog.get()`); `key` is your own name for it in this environment, and later calls take the key.\n- Actor: who the app sees you as. API profile: one API of the app, with its path and versions. Each release in the catalog lists both.\n- Connection: connect() needs the app `ready`. Salesforce has several actors and API profiles, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name; read them from the connection instead of hard-coding one. `connection.fetch` never sends your API key, never follows redirects and never retries. `connection.headers()` returns live tokens: treat them as secrets. Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope instead: put `connection.actorToken()`, also a secret, in `SessionHeader/sessionId`; `headers()` then carries only `X-State-Environment-Token`.\n- Vendor clients: the gateway needs `X-State-Environment-Token` on every request. A client such as jsforce only sends it if you configure custom headers. Prefer `connection.fetch`; if you pass `headers()` to another client, send them only to `connection.baseUrl` and disable redirects.\n- Pagination: `environments.list`, `environments.events` and `workspaces.events` return 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`: `queued`, `starting`, `running`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`.\n- App `status`: `pending`, `starting`, `ready`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.\n- App `disposal`: `pending`, `complete`, `failed`, `unknown`.\n- `waitUntilReady` throws `EnvironmentFailedError` if the environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default. It never stops the environment.\n- `waitUntilStopped` resolves when the environment is `stopped` or `failed` and every app's disposal is `complete`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.\n\n## Limits\n\n- Live environments are capped per organization: `(await sm.credential.get()).limits.liveEnvironments`.\n- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it; at the end the environment stops with `stopReason: 'expired'`.\n- Always call `stop` in a `finally`. In CI, then await `waitUntilStopped`.\n\n## Errors and retries\n\nA failed API call throws `StateMachinesError` with `status`, `code`, `requestId` and `retryAfter`. The SDK retries `502`, `503`, `504`, connection errors and attempt timeouts itself, within a 10-minute retry budget (the last attempt can end later); `create` retries reuse one idempotency key. It retries nothing else: not `429`, other `4xx` or other `5xx`. Every `create` error carries `err.idempotencyKey`: `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same input returns the environment the first call created.\n\n| Code | Status | What to do |\n| --- | --- | --- |\n| `environment-limit` | 429 | Not retried. Stop a live environment (`sm.environments.list({ status: 'live' })`), then create again. |\n| `lifetime-too-long` | 422 | Lower `lifetimeMinutes` to at most `limits.environmentLifetime.maximumMinutes`. |\n| `release-unavailable` | 422 | Unknown or retired app or release. Check `appId` and `appReleaseId` against `sm.catalog.get()`. |\n| `release-unavailable` | 503 | This deployment doesn't serve the release. Retried within the budget; omit `appReleaseId` to use the default release, or contact support with the `requestId`. A failed app can carry it as `errorCode`. |\n| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it stopped or expired, create a new one. (Before that, connect() throws a `TypeError` for an app that isn't ready or an unknown actor or API.) |\n| `idempotency-conflict` | 409 | The idempotency key was used with a different input. Replay with the exact same input. |\n| `request-timeout` | 503 | Retried automatically. If `create` still fails, replay it with `err.idempotencyKey`. |\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\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n## Docs\n\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): product site\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 sandboxed copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, connecting as an actor, cleanup, and errors such as environment-limit and release-unavailable. Also use when the user mentions State Machines, STATE_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 `STATE_API_KEY` is set without printing it (`test -n \"$STATE_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. Log `await sm.catalog.get()` for each app's `appId` and the actors and API profiles its release offers; don't guess IDs. `key` is your own name for the app, and later calls take it.\n3. Open a `try` right after `create` returns, and call `stop` in its `finally`.\n4. `await sm.environments.waitUntilReady(environment.id)`. It never stops the environment.\n5. Connect as one actor through one API profile. Salesforce has several of each, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name, so read them from the connection instead of hard-coding one. Choose the actor whose permissions the task needs; each release in the catalog lists them.\n6. Call the app with the connection's `fetch`. A leading `/` means the root of `baseUrl`.\n7. In `finally`, `await sm.environments.stop(environment.id)`. In CI, then await `sm.environments.waitUntilStopped(environment.id)`.\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\n// Reads STATE_API_KEY. The workspace comes from the key.\nconst sm = new StateMachines();\n\n// A failed create carries err.idempotencyKey: see \"Recovering a failed create\" in the README.\nconst environment = await sm.environments.create({\n  name: 'quickstart',\n  // The default Salesforce app; sm.catalog.get() lists every app.\n  apps: [{ key: 'crm', appId: 'salesforce' }],\n});\n\ntry {\n  await sm.environments.waitUntilReady(environment.id);\n\n  // Salesforce has several actors (its users) and API profiles, so pick one of each.\n  // The connection lists the actors; this acts as the first.\n  const { actors } = await sm.environments.getConnection(environment.id, 'crm');\n  const [actor] = actors;\n\n  if (!actor) {\n    throw new Error('The Salesforce app has no actors.');\n  }\n\n  const crm = await sm.environments.connect(environment.id, 'crm', {\n    actorId: actor.id,\n    apiId: 'rest',\n  });\n  const response = await crm.fetch('/services/data/v67.0/limits');\n\n  console.log(response.status, await response.json());\n} finally {\n  // Stop even when a step fails; lifetime counts from the start.\n  await sm.environments.stop(environment.id);\n}\n```\n\n## Rules\n\n- Always stop in `finally`. `waitUntilStopped` confirms every app was disposed; use it in CI so a run fails when cleanup can't be confirmed.\n- Lifetime counts from the start, including boot. It defaults to 15 minutes, or the deployment maximum if that is lower: `(await sm.credential.get()).limits.environmentLifetime`. Set `lifetimeMinutes` in `create` for longer runs.\n- Live environments are capped per organization: `limits.liveEnvironments` from `sm.credential.get()`. Stop the ones you no longer need.\n- Never print, log or commit `STATE_API_KEY`, tokens, or `headers()` or `actorToken()` output.\n- Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope, not a header: put `connection.actorToken()` in `SessionHeader/sessionId`. For it, `headers()` carries only `X-State-Environment-Token`.\n- `connection.fetch` never sends your API key, never follows redirects and only reaches URLs under `baseUrl`.\n- Runtimes: Node.js 20.20 or later (22 or 24 recommended), 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.STATE_API_KEY })`, and bound calls with `{ signal: AbortSignal.timeout(20_000) }`, since retries can take minutes.\n- `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.\n- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `DisposalIncompleteError`, `TimeoutError`), 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 `create` still throws, don't call it again as a new request: that can start a second environment. Every error from `create` carries `err.idempotencyKey`. Call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency-conflict`. Keys are kept for a day.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `release-unavailable`, 422 | Unknown or retired `appId` or `appReleaseId`. | Check the IDs against `sm.catalog.get()`. Omit `appReleaseId` for the default release. |\n| `release-unavailable`, 503, or a failed app with that `errorCode` | This deployment doesn't serve the release. The SDK retries a 503 within a 10-minute budget. | Omit `appReleaseId`. If it persists, report the `requestId`. Pass a `signal` to bound the wait. |\n| `environment-limit`, 429 | The organization is at its live-environment cap. Not retried. | `sm.environments.list({ status: 'live' })`, stop one you no longer need, then create again. |\n| `lifetime-too-long`, 422 | `lifetimeMinutes` is above the maximum. | Use at most `limits.environmentLifetime.maximumMinutes`. |\n| `TypeError: Choose one actor: ...` or `Choose one API: ...` | The app has several actors or API profiles, or the ID doesn't exist. The message lists the valid IDs. | Pass both `actorId` and `apiId` from the listed IDs. |\n| `TypeError: App ... is not ready to connect` | connect() ran before the app was `ready`. | Await `waitUntilReady` first. |\n| `connection-unavailable`, 409 | The app stopped, or the environment is no longer `running`. | Check `sm.environments.get(environment.id)`; if it stopped or expired, create a new one. |\n| `EnvironmentFailedError` from `waitUntilReady` | The environment became `failed`, `stopping` or `stopped`. | Read `err.environment.stopReason` and each app's `errorCode`. Still stop it in `finally`. |\n| A vendor client such as jsforce is rejected by the gateway | The gateway needs `X-State-Environment-Token` on every request; jsforce only sends it with custom headers configured. | Prefer `connection.fetch`. If you pass `headers()` to another client, send them only to `baseUrl` and disable redirects. |\n| `TypeError: Pass apiKey or set STATE_API_KEY.` | No key in the environment. | Ask the user to set `STATE_API_KEY`; in Workers, pass `apiKey`. |\n\nMore: {{origin}}/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk\n",
+});

package/agents/llms.txt

@@ -0,0 +1,93 @@
+# State Machines
+
+> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Create, connect to and stop them with the TypeScript SDK `@usestatemachines/sdk`.
+
+Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later (22 or 24 recommended) and Cloudflare Workers, not browsers. TypeScript needs `lib: ["DOM"]` or `@types/node`. `new StateMachines()` reads the API key from `STATE_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory.
+
+## Concepts
+
+- Environment: one disposable run of one or more apps. Create it, wait until it is `running`, connect, then stop it.
+- App key and app ID: in `create`, `apps: [{ key: 'crm', appId: 'salesforce' }]`. `appId` names the app in the catalog (`sm.catalog.get()`); `key` is your own name for it in this environment, and later calls take the key.
+- Actor: who the app sees you as. API profile: one API of the app, with its path and versions. Each release in the catalog lists both.
+- Connection: connect() needs the app `ready`. Salesforce has several actors and API profiles, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name; read them from the connection instead of hard-coding one. `connection.fetch` never sends your API key, never follows redirects and never retries. `connection.headers()` returns live tokens: treat them as secrets. Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope instead: put `connection.actorToken()`, also a secret, in `SessionHeader/sessionId`; `headers()` then carries only `X-State-Environment-Token`.
+- Vendor clients: the gateway needs `X-State-Environment-Token` on every request. A client such as jsforce only sends it if you configure custom headers. Prefer `connection.fetch`; if you pass `headers()` to another client, send them only to `connection.baseUrl` and disable redirects.
+- Pagination: `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
+
+## Statuses
+
+Enums are open: handle values you don't recognise.
+
+- Environment `status`: `queued`, `starting`, `running`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`.
+- App `status`: `pending`, `starting`, `ready`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.
+- App `disposal`: `pending`, `complete`, `failed`, `unknown`.
+- `waitUntilReady` throws `EnvironmentFailedError` if the environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default. It never stops the environment.
+- `waitUntilStopped` resolves when the environment is `stopped` or `failed` and every app's disposal is `complete`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.
+
+## Limits
+
+- Live environments are capped per organization: `(await sm.credential.get()).limits.liveEnvironments`.
+- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it; at the end the environment stops with `stopReason: 'expired'`.
+- Always call `stop` in a `finally`. In CI, then await `waitUntilStopped`.
+
+## Errors and retries
+
+A failed API call throws `StateMachinesError` with `status`, `code`, `requestId` and `retryAfter`. The SDK retries `502`, `503`, `504`, connection errors and attempt timeouts itself, within a 10-minute retry budget (the last attempt can end later); `create` retries reuse one idempotency key. It retries nothing else: not `429`, other `4xx` or other `5xx`. Every `create` error carries `err.idempotencyKey`: `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same input returns the environment the first call created.
+
+| Code | Status | What to do |
+| --- | --- | --- |
+| `environment-limit` | 429 | Not retried. Stop a live environment (`sm.environments.list({ status: 'live' })`), then create again. |
+| `lifetime-too-long` | 422 | Lower `lifetimeMinutes` to at most `limits.environmentLifetime.maximumMinutes`. |
+| `release-unavailable` | 422 | Unknown or retired app or release. Check `appId` and `appReleaseId` against `sm.catalog.get()`. |
+| `release-unavailable` | 503 | This deployment doesn't serve the release. Retried within the budget; omit `appReleaseId` to use the default release, or contact support with the `requestId`. A failed app can carry it as `errorCode`. |
+| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it stopped or expired, create a new one. (Before that, connect() throws a `TypeError` for an app that isn't ready or an unknown actor or API.) |
+| `idempotency-conflict` | 409 | The idempotency key was used with a different input. Replay with the exact same input. |
+| `request-timeout` | 503 | Retried automatically. If `create` still fails, replay it with `err.idempotencyKey`. |
+
+## Quickstart
+
+Save it unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+// Reads STATE_API_KEY. The workspace comes from the key.
+const sm = new StateMachines();
+
+// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
+const environment = await sm.environments.create({
+  name: 'quickstart',
+  // The default Salesforce app; sm.catalog.get() lists every app.
+  apps: [{ key: 'crm', appId: 'salesforce' }],
+});
+
+try {
+  await sm.environments.waitUntilReady(environment.id);
+
+  // Salesforce has several actors (its users) and API profiles, so pick one of each.
+  // The connection lists the actors; this acts as the first.
+  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
+  const [actor] = actors;
+
+  if (!actor) {
+    throw new Error('The Salesforce app has no actors.');
+  }
+
+  const crm = await sm.environments.connect(environment.id, 'crm', {
+    actorId: actor.id,
+    apiId: 'rest',
+  });
+  const response = await crm.fetch('/services/data/v67.0/limits');
+
+  console.log(response.status, await response.json());
+} finally {
+  // Stop even when a step fails; lifetime counts from the start.
+  await sm.environments.stop(environment.id);
+}
+```
+
+## Docs
+
+- [npm package](https://www.npmjs.com/package/@usestatemachines/sdk): install, README and versions
+- [Agent skill](https://state-web.usestatemachines.workers.dev/skill.md): workflow, rules and troubleshooting for coding agents
+- [OpenAPI document](https://cdn.jsdelivr.net/npm/@usestatemachines/sdk/openapi.json): the HTTP API the SDK calls
+- [State Machines](https://usestatemachines.com): product site