@usestatemachines/sdk 0.7.0 → 0.8.0

package/README.md

@@ -14,13 +14,18 @@ npm install @usestatemachines/sdk
 
 ## Quickstart
 
+<!-- quickstart:start -->
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
 const sm = new StateMachines(); // reads STATEMACHINES_API_KEY
-const env = await sm.environments.create({ apps: ['salesforce'] });
+const env = await sm.environments.create(
+  { apps: ['salesforce'] },
+  { wait: false },
+);
 
 try {
+  await sm.environments.wait(env.id, { status: 'running' });
   const salesforce = await env.connect('salesforce');
   const res = await salesforce.fetch('/services/data/v67.0/limits');
   console.log(res.status, await res.json());
@@ -28,39 +33,53 @@ try {
   await env.delete();
 }
 ```
+<!-- quickstart:end -->
 
-`create` waits until the environment is `running`. If an app fails to start, the server deletes
-the environment. [Waiting](#waiting) lists what each method throws.
+`create` waits until the environment is `running` by default. This example uses `wait: false`
+to retain the environment ID before waiting, so cleanup also covers startup failures. It rejects
+unsuccessful app responses and preserves both verification and cleanup errors.
+[Waiting](#waiting) lists what each method throws.
 
 ## The client
 
 ```ts
 const sm = new StateMachines({
   apiKey: process.env.STATEMACHINES_API_KEY, // the default where `process` exists
-  baseUrl: 'https://api.usestatemachines.com', // the default
   workspaceId: 'ws_...', // for member tokens; an API key has its own workspace
   fetch, // defaults to the global fetch
   attemptTimeoutMs: 60_000, // per HTTP attempt; a retry gets a fresh one
 });
 ```
 
+`baseUrl` takes precedence over `STATEMACHINES_BASE_URL`. The SDK reads the environment
+variable where `process` exists. If neither is set, it uses `https://api.usestatemachines.com`.
+
+The selected URL must be an HTTPS origin. HTTP is allowed only for `localhost` or `127.0.0.1`,
+with an optional port. A single trailing slash is allowed. Credentials, paths, queries,
+fragments, URL templates, and URL spellings that require normalization are rejected.
+An empty or invalid selected value throws `TypeError` before any request.
+
+`sm.me()` returns the caller's `credential` metadata, including its kind, ID, name, expiry
+dates, and API key kind. Expiry dates are `Date` objects when present, or `null`.
+
 | Namespace | Methods |
 | --- | --- |
 | `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? })`, `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, appName, { actorId?, services? }?)` |
 | `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.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
+Every environment the SDK returns carries bound helpers: `env.connect(appName)`, `env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
 not enumerable, so `JSON.stringify(env)` holds only the API's fields.
 
 ## Apps
 
-A string names the app, and its name in the environment is the same string. Use the object form
-for your own name, for two copies of one app, or for settings:
+A string names the app by its ID, and its name in the environment is the same string. Use the
+object form, with the ID in `appId`, for your own name, for two copies of one app, or for the
+app's setup:
 
 ```ts
 await sm.environments.create({
@@ -70,44 +89,62 @@ await sm.environments.create({
   apps: [
     'salesforce',
     {
-      app: 'salesforce',
+      appId: 'salesforce',
       name: 'partner-org',
-      settings: { settings: { soapApiLoginEnabled: false } },
+      setup: { settings: { soapApiLoginEnabled: false } },
     },
   ],
 });
 ```
 
-`settings` is passed to the app unchanged. Salesforce takes
-`{ preset?: 'development', configure?, settings?: { soapApiLoginEnabled?: boolean } }`, where
-`configure` can set the organization's `Name` and the administrator's `Username`. A refused value
-fails the start with `failure.code: 'invalid_settings'`, and its `failure.message` names the
-setting.
+`setup` is passed to the app unchanged, and the app applies it when the environment first starts.
+Salesforce takes
+`{ preset?: 'development', configure?, settings?: { soapApiLoginEnabled?: boolean }, automation? }`,
+where `configure` can set the organization's `Name` and the administrator's `Username`, and
+`automation` holds the rules and flows that the app runs. A refused value fails the start with
+`failure.code: 'invalid_setup'`, and its `failure.message` starts with the path of the value, such
+as `setup.preset`.
 
-`sm.apps.list()` lists the apps. `sm.apps.versions(appId)` lists each version's APIs and actors.
-A new environment runs each app's default version.
+`services` holds the configuration of each service that takes one, by service ID. Salesforce's
+`api` service takes none. The API refuses a wrong value at create with `invalid_request`. The app
+checks `services` again when the environment starts, and a value that it refuses fails the start
+with `failure.code: 'invalid_services'`.
 
-## Credentials
+`sm.apps.list()` lists the apps. `sm.apps.versions(appId)` lists each version's services and
+actors. 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?)`.
+## Credentials
 
-- `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
+`env.connect(appName, { actorId?, services? })` returns the API's `Credentials`: `token`,
+`services`, `expiresAt` and `login`, plus `fetch(path, init?)` and `service(id)`.
+
+- Each entry of `services` has an `id`, a `url` and the `headers` that every request to that URL
+  needs. A service's `url` is the app URL followed by the service's `path`. The `api` service is
+  at `/`, so its `url` is the app URL. Its `headers` hold `Authorization: Bearer` with `token`
+  and, unless the environment has `tokenInUrl: true`, `StateMachines-Environment-Token`.
+- The credentials always list each `public` service of the app's version. The `services` option
+  names more services to list, by ID, and a `preview` service is listed only when it is named.
+  `sm.apps.versions(appId)` gives the `path` and `visibility` of each service that you can name.
+  An unknown ID, or an ID named twice, fails with `invalid_request`.
+- `service(id)` returns the entry with that ID. It throws a `TypeError` that names the listed
+  services when there is none.
+- `fetch` joins `path` to the `url` of the `api` service and sends its `headers` as defaults. A
+  header that you set in `init.headers` is sent in place of the service's header of the same
+  name, whatever its case. The exception is the service's `StateMachines-Environment-Token`,
+  which `fetch` always sends when the service has one. A leading `/` means the root of the app.
+- Salesforce SOAP also takes the token in the envelope: put `credentials.token` in
   `SessionHeader/sessionId` yourself.
 - `fetch` never sends your API key, never follows redirects, never retries and only reaches paths
-  under `url`.
+  under the `api` service URL.
 - `actorId` defaults to the app's default actor (for Salesforce, the administrator). Pick another
   from the version's `actors` to act with that user's permissions.
 - `login` holds what the vendor's own login call needs, when the version declares one for the
   actor.
-- `token` and `headers` are secrets. To use another client, such as jsforce, send `headers` and
-  the actor header only to `url`, with redirects off.
+- `token` and each service's `headers` are secrets. To use another client, such as jsforce, send
+  the service's `headers` only to its `url`, with redirects off.
 
-Environments created with `tokenInUrl: true` carry the environment token in `url` instead, and
-`headers` is empty.
+Environments created with `tokenInUrl: true` carry the environment token in each service's `url`
+instead of in its `headers`.
 
 ## Snapshots
 
@@ -173,7 +210,7 @@ response body.
 | `body_too_large` | 413 | The request body is over the API's size limit, which the message names. |
 | `version_unavailable` | 422 | The app has no default version. |
 | `environment_limit_reached` | 429 | Too many environments `starting` or `running`. |
-| `internal_error` | 500 | An error on the server. |
+| `internal_error` | 500 | An error in State Machines. |
 | `unavailable` | 503 | Retried automatically. |
 
 ### Errors from the app URL
@@ -187,7 +224,9 @@ error envelope, and never retries them. These codes come from State Machines, in
 | `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. |
-| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |
+| `invalid_setup` | 503 | The app refused its `setup` after the environment started, such as in a newer version. The message starts with the path of the value. |
+| `invalid_services` | 503 | The app refused a value in `services` after the environment started. The message starts with the path of the value. |
+| `unsupported_protocol` | 501 | The app does not serve this path, method or content type, or the request body is compressed. |
 
 ## Retries and timeouts
 
@@ -220,8 +259,9 @@ are open: handle values you don't recognise.
 
 ## Upgrade from 0.5
 
-0.6 follows the current API. 0.5 and older call routes that the API no longer serves, so they fail
-against it.
+0.8 follows the current API. 0.5 and older call routes that the API no longer serves, so they fail
+against it. 0.7 removed `pause()` and `resume()`, because the API no longer serves them. Create a
+snapshot of the data to reuse, then create a new environment from it.
 
 | 0.5 | 0.6 |
 | --- | --- |
@@ -243,6 +283,19 @@ against it.
 | `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) |
 
+## Upgrade from 0.7
+
+| 0.7 | 0.8 |
+| --- | --- |
+| `{ app, settings }` | `{ appId, setup }` |
+| `credentials.app`, a request's `app`, `failure.app` | `credentials.appName`, a request's `appName`, `failure.appName` |
+| `sm.requests.list({ app })`, `sm.requests.stats({ app })` | `sm.requests.list({ appName })`, `sm.requests.stats({ appName })` |
+| `app` in the `data` of an audit event, such as `credentials.created` | `appName` |
+| `credentials.url`, `credentials.headers` | `credentials.service('api').url`, `credentials.service('api').headers` |
+| `fetch` puts `token` in the header of the API whose path matches | `fetch` sends the headers of the `api` service on every path |
+| A version's `apis` | A version's `services` |
+| The failure code of a refused `settings` value | `invalid_setup` for a refused `setup`, and `invalid_services` for a refused `services` value |
+
 ## License
 
 MIT

package/agents/SKILL.md

@@ -1,27 +1,56 @@
 ---
 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, 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 setting up State Machines or running code, integration tests, or API experiments against disposable SaaS replicas such as Salesforce. Applies to @usestatemachines/sdk and STATEMACHINES_API_KEY, including environment creation, actors, snapshots, cleanup and recovery.
 ---
 
-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`.
+## Start with the user's task
 
-## Workflow
+During skill installation, read the repository instructions and preserve its existing structure. Do not create a new project, install dependencies, write examples or create remote resources. Report the installed skill location and any reload requirement, then ask "What would you like to run or test?" and wait. Skill installation does not verify a connection.
 
-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`.
+Once the user chooses a task, inspect the project's package manager, runtime, runner and secret loader. Install or reuse a compatible `@usestatemachines/sdk` only when the task needs it. Read the installed README for API signatures and `package.json` for runtime requirements. The SDK is ESM and runs on Node.js and Cloudflare Workers, not in a browser. Follow the user's task and existing project conventions without requiring a separate onboarding example.
 
-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`.
+## Check access in the right process
+
+The SDK reads `STATEMACHINES_API_KEY` from the process environment. It does not load `.env` files. Use the project's existing test command or secret loader. An empty variable in your current shell does not prove that the test process lacks it. Verify presence without displaying the value. In Workers, pass the binding explicitly with `new StateMachines({ apiKey: env.STATEMACHINES_API_KEY })`.
+
+Call `sm.me()` to verify access and workspace scope before creating resources. `me.limits` can be null. If the key is missing, prepare the local test or example and tell the user the exact local file, binding, or launch command to configure and rerun, without asking for the key in chat. Do not call the API until access is available. If access is denied or the workspace differs from the task, report the blocker. Do not invite or remove members, or change permissions.
+
+Never print, log or commit API keys, `credentials.token`, the `headers` of `credentials.services`, environment dumps, or secret-file contents. Use synthetic test data.
+
+## Run the user’s chosen task
+
+Apply this section after setup, once the user has chosen a task.
+
+- `sm.apps.list()` returns app IDs. Every list returns `{ data, nextCursor }`. Follow cursors until the required entry is found or `nextCursor` is null.
+- Create only the apps the task needs. A string such as `'salesforce'` is both its app ID and its name in the environment. For named apps, later `connect()` calls use the name.
+- `connect(appName)` uses the app's default actor, the Salesforce administrator. For another actor, find the matching app by name in `environment.apps`, read its `versionId`, then find that exact version through `sm.apps.versions(appId)`. Use an actor ID from its `actors`, never a role label, workspace member ID, or the first version in a list.
+- Check the app's services and [known differences](https://docs.usestatemachines.com/apps/known-differences.md) for the behavior under test. A replica does not import a customer's org or run arbitrary customer automation.
+- Configure the existing integration's test transport with the returned app URL and credentials. Verify its requests reach that URL. A successful standalone SDK request does not prove the integration uses the replica. If transport configuration needs a broader change, explain it before expanding the task.
+- Check the expected HTTP status and assert the result. For writes, read the stored data back and assert the relevant fields. For negative tests, assert the expected error. Do not weaken an assertion to make unsupported behavior pass.
+
+## Own the full lifecycle
+
+Create with `{ wait: false }` to retain the accepted environment ID before waiting. Enter `try` immediately, then wait for `running`, connect and run the check inside it. Delete in `finally`, including after a startup failure, timeout or failed assertion. An aborted wait does not cancel the work that the API accepted. Cleanup must use a fresh, un-aborted signal. Preserve both verification and cleanup errors, and report the environment ID if deletion fails.
+
+Delete only environments created for this task. If the organization is at its limit, clean up a known leftover from this task or ask the user to free capacity. Do not delete unrelated environments or a user-supplied reusable snapshot.
+
+The SDK retries management connection errors and `502`, `503`, `504` with one idempotency key per create call. To recover across separate attempts or a restart, retain the input and an explicit `idempotencyKey` before creation. Replay using the same input, key, workspace and caller. Do not create a replacement with a new key while the first outcome is unknown. See [operation recovery](https://docs.usestatemachines.com/sdk-api/recovery.md).
+
+## Optional connection check
+
+Run this only when the user asks to verify the connection. It proves the connection and cleanup, not an existing integration's behavior. Save it in the project's examples or test location and run it with the existing TypeScript runner and secret loader. In a new Node.js project, `state-quickstart.mts` and `npx tsx state-quickstart.mts` are a fallback. Load the key into that process first.
 
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
 const sm = new StateMachines(); // reads STATEMACHINES_API_KEY
-const env = await sm.environments.create({ apps: ['salesforce'] });
+const env = await sm.environments.create(
+  { apps: ['salesforce'] },
+  { wait: false },
+);
 
 try {
+  await sm.environments.wait(env.id, { status: 'running' });
   const salesforce = await env.connect('salesforce');
   const res = await salesforce.fetch('/services/data/v67.0/limits');
   console.log(res.status, await res.json());
@@ -30,41 +59,35 @@ try {
 }
 ```
 
-## Rules
-
-- Always delete in `finally`.
-- 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.
-- 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`.
-- 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.
-- 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.
-- Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
-- To reuse seeded data, `await env.snapshots.create({ name })` once, then `sm.environments.create({ snapshotId })` in place of `apps`.
-- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `SnapshotFailedError`, `UnexpectedStatusError`, `WaitTimeoutError`), not by `name`.
-
-## Recovering a failed create
-
-The 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`.
-
-## Troubleshooting
-
-| 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 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. | 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 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`. |
-
-More: https://docs.usestatemachines.com, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk
+## Load details when needed
+
+- **Repeated fixtures or parallel tests:** Read [isolated tests](https://docs.usestatemachines.com/sdk-api/testing.md). Save seeded data with `env.snapshots.create({ name })`, then create each test's environment with `{ snapshotId }`. A snapshot in `saving` cannot be deleted yet. Retain its ID and wait for `ready` or `failed` before cleanup. Delete a reusable snapshot only when the task calls for it.
+- **Another actor, vendor client or SOAP:** Read [credentials](https://docs.usestatemachines.com/environments/credentials.md). `credentials.fetch()` confines requests to the app URL, adds its authentication headers, and never follows redirects. External clients must send a service's `headers` only to its `url` and disable redirects. For Salesforce SOAP, put the actor token in `SessionHeader/sessionId` in the envelope.
+- **Cloudflare Workers:** Pass the key explicitly. Use `{ wait: false }` and keep the environment ID across requests or in the job's state. A request ending does not cancel startup. Follow the worker's background-job lifecycle for polling and cleanup.
+- **Long runs:** Read `sm.me().limits` when non-null. The environment time limit covers starting and running. Use a supported `timeLimitMinutes` when the task needs it.
+
+## Recover without changing the test's meaning
+
+Management failures throw SDK errors. App HTTP failures are returned as `Response` objects. Use `instanceof` with the SDK error classes. Native `credentials.fetch()` never retries. Read the State Machines error code in `error.code` and distinguish it from an app's own error.
+
+| Failure | Next action |
+| --- | --- |
+| `invalid_request` | Read `err.fields` and the installed method signature. |
+| `version_unavailable` | Discover the app ID and available versions. Stop if the required version is unavailable. |
+| `environment_limit_reached` | Clean up only this task's known leftovers, or report the capacity blocker. |
+| `EnvironmentFailedError` | Read `err.environment.failure` and clean up the owned environment. |
+| `WaitTimeoutError` or abort | Use the retained environment ID. If older code waited inside `create`, a non-null `WaitTimeoutError.resource` carries its ID. If neither an ID nor a replay key is recoverable, report unresolved cleanup. Do not guess from a list. Wait again only if the task should continue. Otherwise delete the owned environment. |
+| Unknown create outcome | Replay the retained input and idempotency key. Do not start another operation with a new key. |
+| `invalid_status` | Read the current resource status before choosing the next call. |
+| `snapshot_in_progress` | Find the saving snapshot for this environment and wait for it before creating another. |
+| `SnapshotFailedError` | Report the failure. Retry only if the task still needs a snapshot and the source environment is running. |
+| App `environment_not_running` | Inspect the environment. Do not silently switch the integration to another target. |
+| App `invalid_setup` or `invalid_services` | The app refused a value of `setup` or `services` after the start. `error.message` starts with its path. Create another environment with a value that the app accepts, and delete the owned one. |
+| App or gateway `503` | For a retryable read, honor `Retry-After`. For a write with an uncertain outcome, inspect stored state or report uncertainty before retrying. |
+| Cleanup failure | Preserve the task result, report the owned resource ID and retry deletion with valid access and a fresh signal. Do not report cleanup as successful. |
+
+## Finish with evidence
+
+Leave the smallest rerunnable test or example. Report the behavior checked, command, assertion result, SDK and app versions, selected actor, resource IDs without secrets, and cleanup outcome. Say when execution was blocked or only typechecking ran. A passing replica check establishes the asserted behavior for that version and actor, not full production compatibility.
+
+Find other guides through https://docs.usestatemachines.com/llms.txt. Read focused pages before the full documentation bundle. This dashboard also serves an agent index at https://app.usestatemachines.com/llms.txt.

package/agents/index.d.ts

@@ -8,6 +8,8 @@ export declare const skill: string;
 
 export declare const quickstart: string;
 
+export declare const cliVersion: string | null;
+
 export declare const templates: Readonly<
   Record<'prompt' | 'llmsTxt' | 'skill', string>
 >;