mandala-computer-mcp 0.6.0 → 0.8.0

package/README.md

@@ -145,10 +145,12 @@ Parameter and response-mode support remains a separate contract.
 
 **Lifecycle** — `create_computer`, `start_computer`, `stop_computer`,
 `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`,
-`delete_computer`, `move_computer`, `list_moves`
+`delete_computer`, `move_computer`, `list_moves`, `get_operation`,
+`list_operations`, `wait_for_operation` — see [Lifecycle operations](#lifecycle-operations)
 
-**Driving the desktop** — `screenshot`, `click`, `type_text`, `press_key`,
-`scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait`
+**Driving the desktop** — `screenshot`, `click`, `type_text`, `paste_text`,
+`press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`,
+`wait`
 
 **Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `get_execution`,
 `read_execution_output`, `open_url`,
@@ -185,6 +187,10 @@ which says nothing about the path; `isTransient` is false for both.
 
 **Account quota** — `get_account`
 
+**Who you are** — `whoami`, `list_api_keys`, `list_workspaces`,
+`get_workspace`, `list_workspace_members`. Minting and revoking API keys are
+deliberately not tools — see [Who you are, and API keys](#who-you-are-and-api-keys).
+
 **Spending** — `get_usage`
 
 **Being told somewhere else** — `list_webhooks`, `create_webhook`,
@@ -197,11 +203,12 @@ was issued to, not to the account, and are accepted by every computer with SSH
 on, on every account where that person is an owner or member. A
 workspace-scoped key can read keys but not add or remove them.
 
-**Secrets** — `list_secrets`, `get_secret`, `create_secret`, `replace_secret`,
-`delete_secret` for the account's secret store, and `get_computer_secrets`,
-`set_computer_secrets` and `create_computer`'s `secrets` for which of them a
-computer receives. A value goes in through `create_secret` or `replace_secret`
-and never comes back out. No route answers one, and a store tool's result
+**Secrets** — `list_secrets`, `get_secret`, `create_secret`, `set_secret`,
+`replace_secret`, `delete_secret` for the account's secret store, and
+`get_computer_secrets`, `set_computer_secrets` and `create_computer`'s `secrets`
+for which of them a computer receives. A value goes in through `create_secret`,
+`set_secret` (create the name, or replace its value if the scope holds it —
+names match ignoring ASCII case) or `replace_secret`, and never comes back out. No route answers one, and a store tool's result
 holds only the decoded documented fields (success) or the status, the `reason`
 word and a sentence of its own (refusal). It never includes the platform's
 response text, and the `Api` keeps none for these routes. The bindings carry
@@ -211,13 +218,41 @@ binding list (`[]` removes every binding) and reaches the guest at the
 computer's next start or restart; send the `version` a read answered to have it
 refused with 409 if the list changed since. A replaced value also reaches a
 running computer: a file binding's file is rewritten in place, and on an image
-that supports it an env binding reaches new shells and `exec` with
-`desktop: true` (programs already running keep the old value until a restart).
-A command that needs a bound variable should use `desktop: true`. Whether a
-plain root `exec` sees it depends on the platform version. `replace_secret`
+that supports it an env binding reaches new shells, and every `exec`, plain
+or with `desktop: true`, runs with the bound variables as they are at that
+moment (programs already running keep the old value until a restart).
+`replace_secret`
 and `delete_secret` need the current `revision_id`, and a stale one is a 409.
 `delete_secret` also needs `confirm: true`: a computer still bound to a deleted
-secret cannot start again until that binding is removed.
+secret cannot start again until that binding is removed. A bound computer runs,
+and its guest answers, a few seconds before its secrets land, so
+`wait_for_computer(until="guest")` on one also waits until they have;
+`get_computer` shows the gap as "its secrets are still on their way in".
+
+**A proxy for the browsers** — `browser_proxy: {server, bypass}` on
+`create_computer` and `update_computer` sends a Linux computer's browsers
+(Chromium, Chrome, Firefox) through a proxy; nothing else on the computer uses
+it. On `update_computer` it goes alone, replaces the setting whole, and `null`
+removes it. Which proxies are accepted is the platform's rule, and its refusal
+comes back as it is. A running computer has a change within seconds:
+`wait_for_computer(until="guest")` waits until its browsers have it, and
+`get_computer` shows the gap as "its browser proxy is still being applied".
+
+**A proxy for all outbound traffic** — `egress_proxy: {server,
+credentials_secret_id}` on `create_computer` and `update_computer` sends ALL of
+a computer's outbound TCP (`exec`, terminals, package managers and browsers
+alike) through a proxy, taken on its host so nothing inside the computer can
+opt out. The server is `http://`, `https://` or `socks5://` with an explicit
+port; there is no bypass list. `credentials_secret_id` names a secret holding
+`user:password` that is not bound to the computer and never reaches it: the
+computer's host signs in to the proxy with it. It fails closed (proxy down or
+refusing, or credentials not on the host yet: the connection fails, nothing goes
+direct), drops UDP to the internet and ICMP, and does not proxy DNS lookups.
+On `update_computer` it goes alone — beside any other field it is refused
+before a request is sent — replaces the setting whole, and `null` removes it.
+`get_computer` names the proxy and, while the host waits for its credentials,
+says "its egress proxy is waiting for credentials; connections are closed until
+they arrive".
 
 **Delegating** — `run_agent`, `run_agent_chat`, registered only when a model key is present:
 `MANDALA_MODEL_KEY` on stdio, or the caller's own `X-Model-Key` header over HTTP.
@@ -242,10 +277,10 @@ with an error listing all valid tags.
 
 | Tag | Tools |
 | --- | --- |
-| `account` | `get_account` |
+| `account` | `get_account`, `whoami`, `list_api_keys`, `list_workspaces`, `get_workspace`, `list_workspace_members` |
 | `computers` | `list_computers`, `get_computer`, `use_computer`, `wait_for_computer`, `get_desktop_url`, `list_sizes` |
-| `lifecycle` | `create_computer`, `start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`, `delete_computer`, `move_computer`, `list_moves` |
-| `input` | `screenshot`, `click`, `type_text`, `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait` |
+| `lifecycle` | `create_computer`, `start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`, `delete_computer`, `move_computer`, `list_moves`, `get_operation`, `list_operations`, `wait_for_operation` |
+| `input` | `screenshot`, `click`, `type_text`, `paste_text`, `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait` |
 | `guest` | `exec`, `exec_poll`, `exec_kill`, `open_url`, `list_windows`, `window_action`, `read_clipboard`, `write_clipboard` |
 | `files` | `list_directory`, `read_file`, `write_file`, `wait_for_file_change` |
 | `executions` | `get_execution`, `read_execution_output` |
@@ -257,7 +292,7 @@ with an error listing all valid tags.
 | `usage` | `get_usage` |
 | `webhooks` | All webhook tools listed above |
 | `ssh` | All SSH tools listed above |
-| `secrets` | `list_secrets`, `get_secret`, `create_secret`, `replace_secret`, `delete_secret`, `get_computer_secrets`, `set_computer_secrets` |
+| `secrets` | `list_secrets`, `get_secret`, `create_secret`, `set_secret`, `replace_secret`, `delete_secret`, `get_computer_secrets`, `set_computer_secrets` |
 | `agent` | `run_agent`, `run_agent_chat` |
 | `activities` | `list_activities`, `get_activity`, `get_activity_results` |
 | `signals` | `read_signals` |
@@ -280,6 +315,116 @@ to both transports and the plugin forwards them. Embedders can pass
 `readOnly: true` and `tags: ['input', 'guest']` in `ServerConfig`; the server
 does not read the environment itself.
 
+### Lifecycle operations
+
+Every accepted create, clone, start, stop, suspend, restart, snapshot restore,
+resize, move and delete records a lifecycle operation, and the tool that made the call
+says its `operation_id` — in its sentence, as `(operation op_…)`, and in the
+JSON. `move_computer` carries it onto the outcome it reports. It is absent where
+the platform could not record one; the call happened either way.
+
+`get_operation` reads one, and `list_operations` pages through them newest
+first (`computer_id`, `limit`, `cursor`, `idempotency_key`; `computer_id` is not
+defaulted to the selected computer, and `idempotency_key` finds the operation a
+call sent with that key recorded, even when the call's answer was lost). `wait_for_operation` polls one until it is final: it
+answers on `succeeded`, and a `failed` one is an error carrying the platform's
+`error.code` (`start_failed`, `build_failed`, `computer_gone`, `move_failed`,
+`resize_not_applied`, `lost`, and more may be added) and its sentence.
+
+`succeeded` means the platform finished its step, not that the desktop has
+booted: `wait_for_computer` is still the wait for a desktop that answers. Most
+operations are already `succeeded` when their tool answers; a clone is
+`running` until its disk is copied, and a move until it lands. All three are
+reads, and all three stay registered when the lifecycle tools are withheld,
+since start, stop, suspend and restart record operations too.
+
+The eleven lifecycle tools (`create_computer`, `clone_computer`,
+`start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`,
+`update_computer`, `move_computer`, `delete_computer`, `restore_snapshot`,
+`clone_snapshot`) take an optional `idempotency_key`. Leave it out and a fresh
+one is sent for you; a failure whose outcome is unknown names the key it went
+with. What to do next depends on who answered:
+
+- **The answer was lost** (the connection dropped after the request went out,
+  or a proxy in front of the platform gave up), or the platform answers
+  `idempotency_in_progress`: call the same tool again with the same
+  `idempotency_key`. The platform answers with the first call's result, or says
+  it is still running; the step is not done twice.
+- **The platform answered a `5xx` that names no `operation_id`**: nothing may
+  have been done. A refusal given before the call was sent anywhere — another
+  launch already in progress, no host to place it on, the template catalogue
+  incomplete — names none, and the platform releases its key. Call the same
+  tool again with the same `idempotency_key`: the platform carries it out if
+  the key was released, or answers `idempotency_outcome_unknown` if not, and
+  only then does the case below apply.
+- **The platform answered a `5xx` that names an `operation_id`**, or
+  `idempotency_outcome_unknown`: the key is spent, and resending with it only
+  answers `idempotency_outcome_unknown`.
+  The platform then keeps the call's operation `pending` for up to an hour,
+  whatever happened, while its host may be carrying it out. What to read
+  depends on the tool:
+  - `start_computer`, `stop_computer`, `suspend_computer`,
+    `delete_computer`, `move_computer` and `update_computer`: read
+    `get_computer` (and `get_operation` with the `operation_id` the error
+    named: `succeeded` means the step happened, `running` means wait on it,
+    and `pending` alone is no reason to wait). If the step did not take
+    effect, send the call again with a new key, or none.
+  - `restart_computer`, which `get_computer` cannot show: a computer reads
+    `running` before and after a reset. Read the operation instead
+    (`get_operation` with the `operation_id` the error named, or
+    `list_operations` with the key): `succeeded` means the restart happened,
+    `running` means wait on it. Anything else leaves the restart possibly
+    done, so ask the user before sending it again with a new key, or none; a
+    second restart resets the guest again.
+  - `create_computer`, `clone_computer`, `clone_snapshot` and
+    `restore_snapshot`, where a read of the computer made straight away can
+    show no effect for a build or restore that then lands, and a second one
+    is a second computer or a second overwrite: read the operation first —
+    `get_operation` with the `operation_id` the error named, or
+    `list_operations` with the key — and while it is `pending` or `running`,
+    wait (`wait_for_operation`) and do not resend with any key. Only once it
+    is final as `failed` (`error.code` `lost`, for one) or no longer found, AND
+    `get_computer` (`list_computers` after a create or a clone) shows the step
+    did not happen, send the call again with a new key, or none. If no
+    operation is found at all, read the computer again after a few minutes
+    before resending.
+- **`idempotency_key_reused`**: a different call already used that key, and
+  nothing was done. Send this one with a new key, or none.
+
+Keys last 24 hours.
+
+### Who you are, and API keys
+
+`whoami` takes no arguments and reads `GET /api/v1/whoami`: the person this
+server's API key was issued to, the account and role it acts with (the role as
+it is now), the workspace it is confined to, and the key itself — including
+`manage_keys`, whether it may manage API keys. It needs no permission and any
+role, and a suspended account can call it; the answer says so when the account
+is suspended. Behind the hosted server's OAuth sign-in, the key is the Connected
+app's (`prefix` `oauth`).
+
+`list_api_keys` lists the key holder's API keys on the account, newest first —
+never a raw key. Each carries `minted_by_key_id`: the key that minted it over
+the API, or `null` for one minted from the dashboard. Revoking a key does not
+revoke the keys it minted. It needs this server's key to have the **Manage keys**
+permission, which only a person can turn on, in the dashboard; without it the
+tool answers the platform's 403, whose sentence says exactly that. A Connected
+app's key never has the permission.
+
+**Minting and revoking keys are not offered here, on purpose.** A mint answers
+the new key in full, once, and a model's context — the conversation, the
+client's logs, whatever the transcript is shared with — is the worst place for a
+long-lived credential and one nobody can take it back from. A revoke is
+irreversible, and on a model's reading of a list it can cut off the person's CI,
+another agent, or this very session. People do both from the dashboard or with
+the `mandala api-keys` CLI.
+
+`list_workspaces`, `get_workspace` and `list_workspace_members` read the
+account's workspaces, which partition its computers. A key confined to a
+workspace lists only that one, and is refused (403) the member list, which is
+the whole account's: workspaces do not divide people. All three are reads;
+workspaces are created, renamed and deleted in the dashboard.
+
 ### Current account quota
 
 `get_account` takes no arguments and reads `GET /api/v1/account` once with the
@@ -331,6 +476,12 @@ anything and keep the hint. When a stretch of work is over, `suspend_computer` (
 suspend catches the ones a model forgets, but only after 30 minutes untouched.
 `get_usage` is what says what any of it cost.
 
+**A screenshot need not be the whole screen.** `screenshot` takes `region` (a
+crop, in the screen pixels `click` takes, before any scaling), `scale` (0 to 1),
+`format` (`png` or `jpeg`) and `quality` (JPEG, 1-100). A cropped or scaled
+picture is in its own pixel space, so the tool says alongside it how to turn a
+position in it back into screen coordinates.
+
 **Ten clicks need not be ten screenshots.** Driving the desktop one tool at a
 time — `screenshot`, `click`, `screenshot` — puts an image in the calling
 model's context for every step. `run_agent` hands a task in plain language to
@@ -733,9 +884,15 @@ listing leaves it out — every ordinary caller is asking "what can I restore".
 `list_snapshots(include_unfinished: true)` is the flag for when the question is
 about storage instead.
 
-**A 409 usually clears; a 400 never does.** A guest still booting or a busy
-guest agent answers 409. The platform's own error messages come through
-unedited, because they are written to be acted on.
+**Read the `reason`, not the status.** Whether a refusal clears on its own is
+the platform's `reason` word, and each tool's answer says what it means:
+`contention` (something was in flight) and `starting` (the guest agent is still
+inside its boot window) clear, so the same call works in a moment;
+`unavailable`, `running`, `unsupported`, `exists` and `revoked` do not. A 409
+does not mean "wait": `exec`, input and the clipboard on a stopped computer
+answer 409 `unavailable`, and `start_computer` is what fixes that, while
+`running` needs the computer stopped first. The platform's own error messages
+come through unedited, because they are written to be acted on.
 
 HTTP failures preserve their actual response status. An unsupported method on a
 known path is `MethodNotAllowedError` (405), with the received `Allow` value when
@@ -973,7 +1130,8 @@ address.
   Settings → Connected apps.
 - **A bearer is checked with the platform before it gets anything.** An
   initialize makes no session until the platform accepts its token — a `2xx`
-  from `GET ssh-keys`, which every valid credential gets — so invented tokens
+  from `GET whoami`, which every valid credential gets, a suspended account's
+  included — so invented tokens
   cannot fill the session pool. A `401` is the challenge above; any other
   answer is `503` and nothing is remembered. Refused initializes are budgeted
   per source address, 20 a minute. Past that, a token already accepted still
@@ -983,6 +1141,65 @@ address.
   carrying a request is checked again before it is dispatched, with an
   acceptance cached for 60 s under the token's digest, so an expired or
   revoked token is a clean `401` before any stream opens.
+- **One bearer holds at most 16 sessions**, and a suspended account's bearer
+  one (enough to ask `whoami`), so no single token can fill the pool. At that
+  limit, an initialize closes the bearer's least recently used idle session to
+  make room, once its own session exists (a refused initialize closes
+  nothing), and a client whose old session is gone initializes again; if none
+  is idle, the answer is `429` with `Retry-After`. One race differs: if the
+  idle session it planned to close is put to work before the new session is
+  made, the new one is dropped instead and the initialize is answered `404`
+  (`Session not found`, no `Retry-After`), which an SDK client reports as a
+  failed connect. Other bearers' sessions are never touched. An account
+  suspended after its bearer opened sessions keeps only one: the next request
+  on any of them closes the bearer's other idle sessions, as does its next
+  initialize, and one still serving a request goes on a later request once
+  it is idle. A
+  `429` names what the bearer holds, so one still over its limit is told to
+  wait for its busy sessions rather than to close one. `runHttp` takes the 16
+  as `maxSessionsPerBearer`, and the CLI reads it from
+  `MANDALA_MCP_MAX_SESSIONS_PER_TOKEN` (a whole number from 1 to 256, the
+  whole pool; anything else is refused at startup; a token is also held to
+  its account's ceiling, below). A self-hosted `--http` server applies it
+  too, but checks no bearer with the platform, so there any string is its own
+  bucket: the per-bearer cap spreads one key's clients, and what bounds an
+  untrusted caller is the process-wide cap (256), and the default loopback
+  bind until you expose the port.
+- **One account holds at most 128 sessions, half the pool, across all its
+  tokens.** Sessions are counted by the account id the platform's `whoami`
+  names for each token, so an account with many keys or grants counts once;
+  a token whose `whoami` names no account counts as an account of its own.
+  Initializes in flight are counted too, so a burst across one account's keys
+  cannot pass the ceiling together. At the ceiling, an initialize makes room
+  by closing idle sessions of two kinds only: the account's sessions whose
+  token the platform has already refused on a request made there, first,
+  and then the requesting token's own least recently used,
+  as at its own cap and even while it is under that cap. When that is not
+  enough the answer is `429` with `Retry-After`, saying it is the account's
+  limit and naming only that number. A live session of another token is
+  never closed for the ceiling, nor any session of another account, and the
+  race above applies here too (`404`). A refused session counts until it is
+  closed, so revoking keys never lets an account past its ceiling; a session
+  whose token was revoked but never sent a request again is not known to be
+  refused, and counts until it idles out. So does the session a token
+  leaves behind when the client refreshes it (see below): it is neither the
+  new token's own nor refused, so an account that holds more than half its
+  ceiling when its clients refresh can be answered `429` for up to the
+  session idle timeout (30 minutes), longer than its `Retry-After` suggests,
+  unless those clients close their old sessions. A revoked token's session
+  idles out within about the acceptance window (60 s) plus that timeout even
+  while its holder keeps sending notifications, holding the stream, or
+  sending `HEAD /mcp` or a `DELETE /mcp` the server refuses: traffic that
+  carries no request is never checked with the platform, so it keeps a
+  session alive only while the token's acceptance is still cached. Suspension is held per
+  token, as above, not per account. A full pool (256) is answered `503` with
+  `Retry-After`, whoever holds it, and nothing is closed to make room in it.
+  `runHttp` takes the ceiling as `maxSessionsPerAccount`, and the CLI reads
+  it from `MANDALA_MCP_MAX_SESSIONS_PER_ACCOUNT` (a whole number from 1 to
+  256; anything else is refused at startup). A self-hosted server verifies
+  no account, so there each token is an account of its own, held to the
+  ceiling as well as to its own cap; to let one token hold more than 128
+  sessions, raise both.
 - **A token the platform refuses during a call comes back as that same
   `401`**, not as a tool error, so the client refreshes or authorizes again —
   the answer is held until its first byte for this. The one case that cannot
@@ -995,7 +1212,11 @@ address.
   `404 Unknown session`, the MCP spec's signal to initialize again. An access
   token says nothing this server can check about which grant it came from, so
   rebinding would let any valid credential that learned a session id take over
-  its bound computer, buffered events and retained results.
+  its bound computer, buffered events and retained results. The old session
+  is not closed by the refresh: it still counts against the token's account
+  ceiling (above) until the client closes it with `DELETE /mcp` under the old
+  token (only the token's digest is compared, so an expired one still works)
+  or it idles out after 30 minutes.
 - `X-Mandala-MCP-Service` carries `MANDALA_MCP_SERVICE_SECRET` on every
   platform request, only ever to `MANDALA_BASE_URL`, so a token cannot be
   replayed at the API directly by the app it was issued to. A client's own
@@ -1017,8 +1238,10 @@ address.
 | `MANDALA_ALLOWED_HOSTS`, `MANDALA_ALLOWED_ORIGINS` | Comma-separated. Which `Host` and `Origin` values this server answers to. On a loopback bind the host list defaults to the address it was given, so DNS-rebinding protection is on without configuration; set this when serving under a name. |
 | `MANDALA_MCP_RESOURCE_METADATA_URL` | `--http` only. The OAuth protected-resource metadata URL this server is published under. Set, it answers OAuth clients as described under Hosted, with OAuth; unset, callers bring an API key. |
 | `MANDALA_MCP_SERVICE_SECRET` | `--http` only. Sent as `X-Mandala-MCP-Service` on every platform request, to `MANDALA_BASE_URL` only. Never logged. |
+| `MANDALA_MCP_MAX_SESSIONS_PER_TOKEN` | `--http` only. How many live sessions one bearer token may hold. Default 16; a whole number from 1 to 256 (the server's whole session pool), and anything else is refused at startup. A suspended account's token is held to one whatever this says. A token is also held to its account's limit, below. |
+| `MANDALA_MCP_MAX_SESSIONS_PER_ACCOUNT` | `--http` only. How many live sessions one account may hold across all its tokens. Default 128, half the pool; a whole number from 1 to 256, and anything else is refused at startup. Hosted (the metadata URL set), the account is the one the platform's `whoami` names for the token; self-hosted, or when `whoami` names none, each token is an account of its own. Past it an initialize is refused `429`, after closing only the token's own idle sessions or the account's refused ones. Suspension is not counted here; it holds each token to one. |
 
-Every one of these but the model key, the two tool filters and the two OAuth settings has a flag as well, and a flag overrides
+Every one of these but the model key, the two tool filters, the two OAuth settings and the two session limits has a flag as well, and a flag overrides
 the environment: `--http`, `--port`, `--host`, `--base-url`, `--computer`,
 `--allowed-hosts`, `--allowed-origins`, `--no-lifecycle`, local `--profile`, plus `--help` and
 `--version`. `--key` exists for a caller launching several servers under
@@ -1085,7 +1308,13 @@ default 20. This is computer control, not hosted general-purpose inference or a
 chat UI; it adds no key storage or model billing service.
 
 This tool deliberately sends `stream:false` and uses the JSON response so the
-result preserves the underlying `agent.stop`, step count and token usage.
+result preserves the underlying `agent.stop`, step count and token usage: the
+streamed form of this route carries no usage and no `agent` block. The price is
+time. **On the hosted API a request that does not stream is cut at the edge after
+about 120 seconds** (a bodiless `524`), which stops the run where it was and loses
+its result, usage and steps; the default 20 steps can take longer than that. Use
+`run_agent`, which streams, for anything that may. The tool answers a `524` by
+saying so rather than as a generic gateway failure.
 Only explicit `end_turn` consistent with the completion's finish reason can
 report success. Limits, refusal, missing or conflicting terminal fields remain
 errors with valid partial results. Nested failures preserve the agent computer,
@@ -1098,9 +1327,21 @@ Neither agent tool starts the computer or switches endpoints after a failure.
 The caller supplies the model key through `MANDALA_MODEL_KEY` on stdio or their
 own `X-Model-Key` header on HTTP. The account Authorization remains separate;
 HTTP never falls back to the operator's model key. Waiting heartbeats count
-notifications, not completed actions. Long-running clients need a
-`progressToken` plus `resetTimeoutOnProgress`; otherwise choose a smaller
-`max_steps`. That bound is neither a time cap nor a spend cap.
+notifications, not completed actions. A `progressToken` plus
+`resetTimeoutOnProgress` keeps the MCP client waiting, but not the hosted edge
+above; `max_steps` is neither a time cap nor a spend cap.
+
+On both agent tools a failure status is read for what it is on these routes
+rather than for what it means elsewhere. The platform's own re-check of the
+caller is a `401` or `403` carrying `reason: "revoked"`, and only that gets
+account advice. A `402`, `504` or `529` is the model provider's own status for
+the configured model key (its billing, timeout or overloaded error), so the
+advice is to check the model-provider account, not the Mandala plan; a `403`
+without `revoked` may be the provider's permission error for that key. The
+exception is a refusal `run_agent_chat` is given before any run started — a flat
+`{error: string}` body, from the role gate, a bad body, a suspension or the
+meter: nothing ran, and it keeps the usual role and plan advice every other tool
+gets.
 
 ## Development
 

package/dist/api.d.ts

@@ -4,6 +4,25 @@ export { isSecretStoreRoute } from './secret-errors.js';
 export declare const DEFAULT_BASE_URL = "https://app.mandala.computer/api/v1";
 /** Anthropic's own key, forwarded for the one route that runs a model. */
 export declare const MODEL_KEY_HEADER = "X-Model-Key";
+/**
+ * The header every lifecycle call carries so that sending it again cannot do
+ * it twice (platform OPL-5127). The platform records a call that carries one
+ * before carrying it out, and for 24 hours answers the same key with the same
+ * request from that record instead of doing the call again: `409` with `code:
+ * "idempotency_in_progress"` while it runs, the original answer once it has
+ * finished. A different request under the same key is a `422`.
+ */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/** The platform's rule for a key: 1 to 255 characters, each printable ASCII other than a space. */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/**
+ * The key for ONE lifecycle tool call — the caller's, already checked by the
+ * tool's input schema, or a fresh random one — made once, before the request,
+ * so that whatever re-sends this call re-sends the same key.
+ */
+export declare const idempotencyKeyFor: (given?: string) => string;
+/** The header that carries it. */
+export declare const idempotencyHeaders: (key: string) => Record<string, string>;
 /**
  * Proof, to the platform, that a request comes through the hosted MCP service
  * (OPL-4982). The platform takes an OAuth access token only alongside it, so a
@@ -19,7 +38,7 @@ export type RequestOptions = {
     body?: unknown;
     /** Raw bytes as the request body, for the file upload. Mutually exclusive with `body`. */
     raw?: Uint8Array;
-    /** Extra headers for this call only — currently just the model key. */
+    /** Extra headers for this call only: the model key, and a lifecycle call's Idempotency-Key. */
     headers?: Record<string, string>;
     signal?: AbortSignal;
 };
@@ -65,6 +84,12 @@ export type Bytes = {
      * differently" and "there is no offset that will work on this file".
      */
     unrangeable: boolean;
+    /**
+     * `X-GC-Frame`, when the platform labelled what it served: `suspended` is a
+     * screenshot answered with the saved frame of a suspended computer rather
+     * than a capture of its screen.
+     */
+    frame?: string;
 };
 /**
  * The longest foreground guest exec waits 600 seconds before it answers.

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Agent, Headers as UndiciHeaders, fetch as undiciFetch } from 'undici';
 import { CancelledError, ConnectivityError, ConnectivityInterruptedError, createOnlyRefusal, errorForStatus, isCreateOnlyUpload, MandalaError, platformSaid, RangeNotSatisfiableError, RedirectError, } from './errors.js';
 import * as P from './paths.js';
@@ -7,6 +8,27 @@ export { isSecretStoreRoute } from './secret-errors.js';
 export const DEFAULT_BASE_URL = 'https://app.mandala.computer/api/v1';
 /** Anthropic's own key, forwarded for the one route that runs a model. */
 export const MODEL_KEY_HEADER = 'X-Model-Key';
+/**
+ * The header every lifecycle call carries so that sending it again cannot do
+ * it twice (platform OPL-5127). The platform records a call that carries one
+ * before carrying it out, and for 24 hours answers the same key with the same
+ * request from that record instead of doing the call again: `409` with `code:
+ * "idempotency_in_progress"` while it runs, the original answer once it has
+ * finished. A different request under the same key is a `422`.
+ */
+export const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key';
+/** The platform's rule for a key: 1 to 255 characters, each printable ASCII other than a space. */
+export const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7e]{1,255}$/;
+/**
+ * The key for ONE lifecycle tool call — the caller's, already checked by the
+ * tool's input schema, or a fresh random one — made once, before the request,
+ * so that whatever re-sends this call re-sends the same key.
+ */
+export const idempotencyKeyFor = (given) => given ?? randomUUID();
+/** The header that carries it. */
+export const idempotencyHeaders = (key) => ({
+    [IDEMPOTENCY_KEY_HEADER]: key,
+});
 /**
  * Proof, to the platform, that a request comes through the hosted MCP service
  * (OPL-4982). The platform takes an OAuth access token only alongside it, so a
@@ -721,6 +743,7 @@ export class Api {
                     : bytes.length,
             unrangeable: (resp.headers.get('accept-ranges') ?? '').trim().toLowerCase() === 'none',
             window,
+            frame: resp.headers.get('x-gc-frame')?.trim().toLowerCase() || undefined,
         };
     }
     // --- the account's secret store (OPL-4984) ------------------------------