mandala-computer-mcp 0.7.0 → 0.9.0

package/README.md

@@ -40,7 +40,8 @@ claude mcp add mandala -- npx -y mandala-computer-mcp --profile Work
 Names are case-sensitive. An explicit key or nonempty `MANDALA_API_KEY` takes
 precedence over every profile and avoids accessing the credential store.
 Empty explicit keys fail; an empty or whitespace-only environment key is absent.
-You can still use a key from **Settings → API keys** with `MANDALA_API_KEY`.
+You can still use a key from **Settings → Credentials → API keys** with
+`MANDALA_API_KEY`.
 
 Saved credentials require POSIX protection: a real directory owned by you with
 mode `0700`, and an owned regular file with mode `0600` and one link. Symlinks,
@@ -52,9 +53,29 @@ A saved profile also binds its API base URL. `--base-url` or `MANDALA_BASE_URL`
 must match that stored base after canonicalization, including the entire path
 prefix and port. An explicitly empty base flag is invalid with saved credentials.
 Each stdio session resolves once: restart to pick up another saved key. Revoking
-the key in **Settings → API keys** makes later calls fail; MCP does not switch
-profiles, reread the file, or retry a refused action. Run login explicitly when
-new credentials are needed.
+the key in **Settings → Credentials → API keys** makes later calls fail; MCP
+does not switch profiles, reread the file, or retry a refused action. Run login
+explicitly when new credentials are needed.
+
+A saved profile can also carry a default workspace, set with
+`mandala workspaces use <workspace>` (and removed with `--clear`); the CLI keeps
+it in `~/.mandala/defaults.json`, beside `credentials.json`, which it never
+changes. Started from that profile, the secret tools (`list_secrets`,
+`get_secret`, `create_secret`, `set_secret`, `replace_secret`,
+`delete_secret`) use it when a call leaves out `workspace_id`; an explicit
+`workspace_id` always wins. Their descriptions say so and name the workspace,
+`list_secrets` says when the default chose the scope, and startup prints it on
+stderr. MCP only reads that file, once at startup, with the same checks as
+`credentials.json`. It is not applied when the profile's key is confined to a
+workspace (that key's own scope applies), when the default was saved for
+another account than the profile is logged in to now, or with an explicit or
+environment key. A file that cannot be read (not valid JSON, another version,
+or readable by others) is noted on stderr: `list_secrets` and `get_secret` then
+use account-wide, but `create_secret`, `set_secret`, `replace_secret` and
+`delete_secret` refuse a call without `workspace_id`, sending nothing, rather
+than act account-wide; pass `workspace_id`, or fix or delete the file and
+restart the server. The hosted HTTP server never reads it, and its tools are
+unchanged.
 
 **Claude Code** — as a plugin, which installs the server and a skill together:
 
@@ -152,6 +173,13 @@ Parameter and response-mode support remains a separate contract.
 `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`,
 `wait`
 
+Every one of these that acts — all but `screenshot` and `cursor_position` —
+takes `context: true` and then answers the desktop as it stands just after the
+action: the windows `list_windows` would list and the one with focus, without a
+second call. They are read once, straight after the action, so a window still
+opening may not be listed yet; when they cannot be read the action still
+happened, and the answer says why.
+
 **Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `get_execution`,
 `read_execution_output`, `open_url`,
 `list_windows`, `window_action`, `read_clipboard`, `write_clipboard`,
@@ -188,7 +216,8 @@ 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
+`get_workspace`, `list_workspace_members`, `create_workspace`,
+`rename_workspace`, `delete_workspace`. 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`
@@ -218,10 +247,10 @@ 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. A bound computer runs,
@@ -277,7 +306,7 @@ with an error listing all valid tags.
 
 | Tag | Tools |
 | --- | --- |
-| `account` | `get_account`, `whoami`, `list_api_keys`, `list_workspaces`, `get_workspace`, `list_workspace_members` |
+| `account` | `get_account`, `whoami`, `list_api_keys`, `list_workspaces`, `get_workspace`, `list_workspace_members`, `create_workspace`, `rename_workspace`, `delete_workspace` |
 | `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`, `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` |
@@ -350,8 +379,16 @@ with. What to do next depends on who answered:
   `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`**, or `idempotency_outcome_unknown`: the key
-  is spent, and resending with it only answers `idempotency_outcome_unknown`.
+- **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:
@@ -398,8 +435,9 @@ 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
+revoke the keys it minted. It needs this server's key to be allowed to manage
+keys, which only a person can turn on in the dashboard (Settings → Credentials →
+API keys → the key's menu → **Allow managing keys**); without it the
 tool answers the platform's 403, whose sentence says exactly that. A Connected
 app's key never has the permission.
 
@@ -414,8 +452,15 @@ 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.
+the whole account's: workspaces do not divide people. All three are reads.
+
+`create_workspace`, `rename_workspace` and `delete_workspace` change them, and
+need an owner's key that is not confined to a workspace: any key confined to
+one is refused (403), so none of them can touch the workspace this server's own
+key stands in. `delete_workspace` needs `confirm: true` and REVOKES every API
+key confined to the workspace, whoever holds it — a person's CI or another agent
+may be using one — and answers how many; the workspace's computers are kept.
+None of the three is offered to a read-only session (`MANDALA_READ_ONLY`).
 
 ### Current account quota
 
@@ -468,6 +513,14 @@ 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.
 
+**Some defaults here differ from the SDKs', on purpose.** `screenshot`'s
+`fresh` defaults to true (the SDKs default to false), because after a click a
+cached frame can predate the action and a model reading it clicks again. Its
+`width` outside 64-3840 is refused rather than clamped as the API would.
+`wait_for_computer` polls every 2 seconds (an SDK launch polls every 3), and
+refuses a suspended computer and names `start_computer`, where the SDKs'
+`waitForGuest` resumes it.
+
 **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
@@ -580,7 +633,11 @@ predates the feature is not something a caller can act on at all.
 **`running` does not mean ready.** A computer reports running when the
 hypervisor has started the VM; the desktop inside comes up seconds later.
 `wait_for_computer(until="guest")` waits for the software to answer, which is
-what `exec`, files and a painted screen actually need.
+what `exec`, files and a painted screen actually need. On a Linux computer it
+also waits for the desktop session to be logged in, so an `exec` with
+`desktop: true` sent next is not refused. That is more than the SDKs'
+`waitForGuest` / `wait_for_guest`, which return once the guest agent answers;
+the value keeps the name `"guest"` because renaming it would break callers.
 
 **A resize can be refused with an offer rather than a no.** Growing a computer
 past what the host it is on can run comes back as a refusal that says another
@@ -1119,10 +1176,11 @@ address.
   API key, which the platform still accepts. The access token is good for this
   endpoint only. It is not an API key: sent to the API directly, the platform
   refuses it with `401` (`reason: "invalid"`). A person revokes it under
-  Settings → Connected apps.
+  Settings → Credentials → 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
@@ -1132,6 +1190,105 @@ 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 one in
+  all (below), 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, except a
+  suspended account's (below). 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 64 sessions, a quarter of 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. A full pool (256) is answered `503` with
+  `Retry-After`, whoever holds it, and nothing is closed to make room in it.
+  The last 64 of the 256 go only to accounts holding less than their share,
+  where a share is the other 192 divided by the accounts holding sessions,
+  the asking one included (initializes in flight count as held): an account
+  at its share once only those 64 are free is answered `503` with
+  `Retry-After` too, saying so, and nothing is closed for it. A lone account
+  therefore stops at 192 even with its ceiling raised, and each newcomer
+  still gets in.
+  `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 64
+  sessions, raise both.
+- **One workspace holds at most 16 sessions, a quarter of its account's
+  ceiling, across all its tokens.** A workspace-scoped key is counted by the
+  workspace the platform's `whoami` names for it as well as by its account;
+  a key of the account as a whole (`workspace: null`) is held by no
+  workspace limit. Workspace-scoped keys share their operator's account
+  ceiling above the sub-ceiling: the operator's own sessions and all its end
+  customers' together stay under 64, so a workspace with room is still
+  answered the account's `429` when the account is full. The same workspace
+  id under two accounts is two workspaces. Room is made, and in-flight
+  initializes are counted, as for the account ceiling; past it the answer is
+  `429` with `Retry-After`, saying it is the workspace's limit and naming
+  only that number. `runHttp` takes it as `maxSessionsPerWorkspace` (default
+  a quarter of the account ceiling, whatever that is set to; above it, it is
+  the account ceiling), and the CLI reads it from
+  `MANDALA_MCP_MAX_SESSIONS_PER_WORKSPACE` (a whole number from 1 to 256;
+  anything else is refused at startup). Hosted only: a self-hosted server
+  verifies no workspace.
+- **A suspended account holds one session in all, across all its tokens**
+  (enough to ask `whoami`, the one call the platform still answers for it).
+  Whether an account is suspended is the platform's latest answer about it
+  from any of its tokens: each check is numbered as it starts, and a slower
+  check that started earlier never overrides a newer one, in either
+  direction. So a newer check that finds the account active lifts the hold at
+  once for every token, and one that finds it suspended holds every token,
+  including one whose own acceptance is still cached. Held, an initialize
+  from any of the account's tokens (a refreshed token, say) closes the
+  account's idle sessions to take the one slot: first those whose token the
+  platform has refused, then the least recently used. A session serving a
+  request is never closed; while the one the account holds is busy, an
+  initialize is answered `429` with `Retry-After`, saying the account is
+  suspended. An account suspended after it opened sessions keeps only one:
+  its next initialize, or the next request, notification or event stream on
+  any of its sessions, closes its other idle sessions, keeping the one being
+  served, and a busy one goes at a later one of these once it is idle.
+  Notifications and streams, which ask the platform nothing, do this only
+  while their token's acceptance is cached (60 s). A self-hosted server asks
+  the platform nothing, so nothing is suspended there.
 - **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
@@ -1144,7 +1301,12 @@ 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. On a suspended account the new token's
+  initialize closes it instead, while it is idle (above).
 - `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
@@ -1166,9 +1328,14 @@ 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. |
-
-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
-the environment: `--http`, `--port`, `--host`, `--base-url`, `--computer`,
+| `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 is held to one session in all, across its tokens, 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 64, a quarter of 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. A suspended account is held to one session whatever this says. Whatever this says, the last quarter of the pool goes only to accounts holding less than their share of it. |
+| `MANDALA_MCP_MAX_SESSIONS_PER_WORKSPACE` | `--http`, hosted only. How many live sessions one workspace may hold across all its tokens. Default a quarter of the per-account limit (16 of 64); a whole number from 1 to 256, and anything else is refused at startup; above the per-account limit it is that limit. Counted by the workspace the platform's `whoami` names for a workspace-scoped token; such tokens also share their account's limit, above, with the account's own tokens and its other workspaces. |
+
+Every one of these but the model key, the two tool filters, the two hosted
+settings (`MANDALA_MCP_RESOURCE_METADATA_URL` and `MANDALA_MCP_SERVICE_SECRET`)
+and the three 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
 different keys, and warns when used, because an argument vector is readable by
@@ -1234,7 +1401,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,
@@ -1247,9 +1420,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
 
@@ -1324,8 +1509,26 @@ check:surface — the mirror matches the platform (N routes, N parameters, from
 
 ## See also
 
-- [python-sdk](https://github.com/mandalacomputer/python-sdk) — the Python SDK,
-  for writing code against the same API rather than driving it from a model.
+- [typescript-sdk](https://github.com/mandalacomputer/typescript-sdk) — the
+  TypeScript SDK and the `mandala` CLI, for writing code against the same API
+  rather than driving it from a model.
+- [python-sdk](https://github.com/mandalacomputer/python-sdk) — the Python SDK
+  and the `mandala-py` CLI, for the same thing from Python.
+
+### The same operation under each client's name
+
+The clients follow their own language's naming, so one operation can go by
+several names. Where a client has no way to do it, the cell says so with —.
+
+| Operation | TypeScript SDK | Python SDK | MCP tool | `mandala` CLI | `mandala-py` CLI |
+|---|---|---|---|---|---|
+| A command in the background | `execBackground()`, then `execPoll(pid)` and `execKill(pid)` | `start_exec()`, then `background_command(pid).poll()` and `.kill()` | `exec` with `background: true`, then `exec_poll` and `exec_kill` | `computers exec --background`, then `computers exec-poll` and `computers exec-kill` | — |
+| Delete a computer with its snapshots | `delete({ deleteSnapshots: true, expect })` | `delete(delete_snapshots=True, expect=…)`; `purge_snapshots` is the deprecated name | `delete_computer` with `delete_snapshots` and `expect` | `computers delete --delete-snapshots --expect` | — |
+| Snapshot holdings (count, bytes, fingerprint) | `holdings()`, or its alias `snapshotHoldings()` | `snapshot_holdings()` | `snapshot_holdings` | `snapshots holdings` | — |
+| The usage window | `usage.read({ from, to })` | `usage.read(since=…, until=…)`, or `from_=` and `to=` | `get_usage` with `from` and `to` | `usage --from … --to …` | — |
+| Change a computer (`PATCH`) | `update({ … })` | `rename()`, `resize()`, `set_idle_suspend()`, `set_browser_proxy()`, `set_egress_proxy()` | `update_computer` | `computers rename`, `resize`, `idle-suspend`, `browser-proxy set`/`clear`, `egress-proxy set`/`clear` | `browser-proxy set`/`clear`, `egress-proxy set`/`clear` |
+| Wait until the computer is ready | `waitForGuest()`, `waitForDesktop()` | `wait_for_guest()`, `wait_for_desktop()` | `wait_for_computer` with `until: "guest"`, which on Linux also waits for the desktop session | `computers wait --until guest` or `--until desktop` | — |
+| The windows after an input action | `{ context: true }` on an input method, e.g. `click(x, y, [], { context: true })` | `context=True` on an input method, e.g. `click(x, y, context=True)` | `context: true` on an input tool | — | — |
 
 ## Security
 

package/dist/api.d.ts

@@ -173,6 +173,12 @@ export type ApiOptions = {
      */
     onBearerRefused?: () => void;
 };
+/**
+ * The `User-Agent` every request carries: this server and its version, and
+ * the Node it runs on, so the platform can tell which client and release sent
+ * a request.
+ */
+export declare const USER_AGENT: string;
 export declare class Api {
     #private;
     readonly baseUrl: string;

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,9 +1,10 @@
 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 { CancelledError, ConnectivityError, ConnectivityInterruptedError, createOnlyRefusal, errorForStatus, isCreateOnlyUpload, MandalaError, messageFromBody, RangeNotSatisfiableError, RedirectError, } from './errors.js';
 import * as P from './paths.js';
 import { MalformedSecretAnswerError, sanitizeSecretError, secretRouteOf, } from './secret-errors.js';
 import { DOCUMENTED_REASONS, secretListOf, secretOf } from './secret-store.js';
+import { SERVER_VERSION } from './version.js';
 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. */
@@ -150,6 +151,12 @@ const NATIVE_FETCH = globalThis.fetch;
 export const platformFetch = () => globalThis.fetch === NATIVE_FETCH
     ? undiciFetch
     : globalThis.fetch;
+/**
+ * The `User-Agent` every request carries: this server and its version, and
+ * the Node it runs on, so the platform can tell which client and release sent
+ * a request.
+ */
+export const USER_AGENT = `mandala-computer-mcp/${SERVER_VERSION} node/${process.versions.node}`;
 export class Api {
     baseUrl;
     /** The same thing parsed, so a path is joined onto the path and nothing else. */
@@ -161,7 +168,7 @@ export class Api {
     #options;
     constructor(apiKey, baseUrl = DEFAULT_BASE_URL, signal, options = {}) {
         if (!apiKey) {
-            throw new MandalaError('No API key. Set MANDALA_API_KEY (create one at Settings → API keys), ' +
+            throw new MandalaError('No API key. Set MANDALA_API_KEY (create one at Settings → Credentials → API keys), ' +
                 'or send it as a bearer token when running over HTTP.');
         }
         // Validated here rather than at the first request. An unusable base URL is
@@ -204,6 +211,7 @@ export class Api {
         this.#headers = {
             Authorization: `Bearer ${apiKey}`,
             Accept: 'application/json',
+            'User-Agent': USER_AGENT,
         };
     }
     /**
@@ -480,7 +488,9 @@ export class Api {
                 if (truncated)
                     throw new SyntaxError('truncated response body');
                 body = JSON.parse(text);
-                message = platformSaid(body) ?? text.slice(0, 500);
+                // An RFC 9457 `detail`/`title` counts for the message, never as the
+                // platform naming the failure: see messageFromBody.
+                message = messageFromBody(body) ?? text.slice(0, 500);
             }
             catch {
                 message = text.slice(0, 500);