mandala-computer-mcp 0.11.0 → 0.13.0

package/README.md

@@ -96,7 +96,9 @@ right answer at all, that it costs money until it is suspended or stopped, that
 which refusals are worth a second try. It is a description of *when and how*,
 not a second client; once the server is installed it stays out of the way.
 `MANDALA_MODEL_KEY`, if exported alongside, is passed through and turns on
-`run_agent` when the configured filters permit it.
+`run_agent` when the configured filters permit it. Without it, `run_agent` runs
+on the account's AI credits when they can pay (see [Agents on AI
+credits](#agents-on-ai-credits)).
 
 To use an environment key instead of a saved profile:
 
@@ -170,9 +172,17 @@ 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`, `get_operation`,
+`delete_computer`, `move_computer_to_workspace`, `move_computer`, `list_moves`, `get_operation`,
 `list_operations`, `wait_for_operation` — see [Lifecycle operations](#lifecycle-operations)
 
+`move_computer_to_workspace` changes workspace membership and who can access a computer.
+It requires an account-wide member or owner credential and explicit `computer_id` and
+`workspace_id` arguments (`null` means unassigned). The selected computer and default
+workspace are not used. The computer must be stopped, with no saved session, snapshots
+or snapshot history copies, secret bindings, or proxy credentials. Refusals leave
+those resources intact; the tool never removes them to force a move. This is separate
+from `move_computer`, which relocates a computer to different hardware.
+
 **Driving the desktop** — `screenshot`, `click`, `type_text`, `paste_text`,
 `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`,
 `wait`
@@ -228,7 +238,18 @@ which says nothing about the path; `isTransient` is false for both.
 `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`
+**Deliberately not tools** — five API operations, each because it would put a
+credential in a model's context: minting and revoking API keys (above), and the
+three browser-connection routes (create, renew and revoke). A browser
+connection is a raw capability to drive the guest's browser; the TypeScript
+and Python SDKs' browser drivers create, renew and revoke it and keep it to
+themselves. Every other API operation has a tool.
+
+**Every tool refuses an argument it does not declare.** A misspelt or unknown
+key is an input error naming the key, and nothing is sent — so a misspelt flag
+can never be dropped and the call go ahead without it.
+
+**Spending** — `get_usage`, `get_credits`
 
 **Being told somewhere else** — `list_webhooks`, `create_webhook`,
 `get_webhook`, `update_webhook`, `rotate_webhook_secret`, `test_webhook`,
@@ -249,6 +270,25 @@ account) or bound to another account answers as if there were no such key, and
 the person removes it from the dashboard. A workspace-scoped key can read keys
 but not add or remove them.
 
+**Showing an app on the internet** — `list_public_urls`, `create_public_url`,
+`update_public_url`, `delete_public_url`. A port inside a computer served at
+`https://<label>.<base_domain>` (the domain is in the `list_public_urls`
+answer, e.g. `mandala.dev`), on 443 with no port in the address. **Public by
+default: anyone with the link can open it**; `access: "private"` requires an API
+key of this account as `Authorization: Bearer`, which never reaches the app. The
+app must listen on `0.0.0.0`, not `127.0.0.1`. Labels that read as the
+platform's or another company's address are refused. A deleted URL's label stays
+with the account: no other account can ever take it, and the account may use it
+again unless the platform has blocked it. A computer over its plan's limit
+serves only its oldest URLs, and the listing marks the rest.
+
+A browser opening a new account's URL may first see a one-time notice page. It
+goes to any request that looks like a browser opening a page — a navigation by
+its fetch metadata, or, without fetch metadata, `Accept: text/html` from a
+`Mozilla/` user agent — so a program sending browser headers sees it too. A
+client that sets headers skips it with `mandala-skip-warning: 1`; in the
+computer's own browser, where `open_url` cannot send headers, click Continue.
+
 **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`
@@ -300,9 +340,11 @@ before a request is sent — replaces the setting whole, and `null` removes it.
 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:
+**Delegating** — `run_agent`, `run_agent_chat`, registered when a model key is present:
 `MANDALA_MODEL_KEY` on stdio, or the caller's own `X-Model-Key` header over HTTP.
-Both must also survive the configured filters.
+Without a key, `run_agent` alone is registered when the account's AI credits can
+pay for a run (see [Agents on AI credits](#agents-on-ai-credits)). Both must also
+survive the configured filters.
 
 ### Tool filters
 
@@ -325,7 +367,7 @@ with an error listing all valid tags.
 | --- | --- |
 | `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` |
+| `lifecycle` | `create_computer`, `start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`, `delete_computer`, `move_computer_to_workspace`, `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` |
@@ -335,9 +377,10 @@ with an error listing all valid tags.
 | `snapshots` | All snapshot tools listed above, including `get_retention` |
 | `templates` | `list_templates`, all your-own-template tools and all build tools listed above |
 | `events` | `wait_for_event`, `poll_events`, `wait_for_file_change` |
-| `usage` | `get_usage` |
+| `usage` | `get_usage`, `get_credits` |
 | `webhooks` | All webhook tools listed above |
 | `ssh` | All SSH tools listed above |
+| `public_urls` | `list_public_urls`, `create_public_url`, `update_public_url`, `delete_public_url` |
 | `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` |
@@ -346,7 +389,8 @@ with an error listing all valid tags.
 The selected tags form a union, then intersect with read-only and the existing
 lifecycle and model-key restrictions. `MANDALA_NO_LIFECYCLE=1` still withholds
 its five tools even when their tags are selected; selecting `agent` cannot
-enable either agent tool without a per-session model key. Both agent tools are
+enable `run_agent_chat` without a per-session model key, nor `run_agent` without
+one or credits that can pay. Both agent tools are
 withheld by read-only, but remain available with lifecycle disabled alone.
 `MANDALA_TAGS=files MANDALA_READ_ONLY=1` exposes only `list_directory`.
 An `agent` selection with read-only is a valid empty tool list.
@@ -364,7 +408,7 @@ 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
+resize, host 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.
@@ -477,8 +521,10 @@ 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. Only an empty workspace can be
-deleted: one that still holds computers is refused (409), saying how many, and
-nothing is deleted or revoked.
+deleted: one that still holds computers or active secrets is refused (409),
+saying how many, and nothing is deleted or revoked. Move its computers out with
+`move_computer_to_workspace` (or delete them) and delete its secrets with
+`delete_secret`, then send it again.
 None of the three is offered to a read-only session (`MANDALA_READ_ONLY`).
 
 An account-wide key can work in one workspace without a key confined to it:
@@ -552,18 +598,28 @@ 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),
+crop, in full-size capture pixels 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.
 
+Live screenshots also return a `capture` name and the capture's original size,
+before cropping or scaling. Use that size instead of the computer record's
+`resolution`, which can differ. To crop a frame you already measured, send its
+`capture` with `region`; omit `fresh` or set it to `false`. Without `capture`,
+screenshots remain fresh by default. `fresh: true` cannot be combined with
+`capture`. If the capture is no longer held (`stale_capture`), take a new
+screenshot without `capture` or `region`, then remeasure the region and use the
+new capture name. Saved frames of suspended computers cannot be pinned this way.
+
 **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
 the platform's own loop instead, which screenshots, decides and clicks inside
 the platform and answers with a sentence and the list of what it did. It is
-registered only when a model key is present (see [Configuration](#configuration))
-and bills that key for the run. `max_steps` bounds the WORK rather than the
+registered when a model key is present (see [Configuration](#configuration)),
+and bills that key for the run, or else when the account's AI credits can pay
+(see [Agents on AI credits](#agents-on-ai-credits)). `max_steps` bounds the WORK rather than the
 bill: a step is one action on the desktop, one model reply can ask for several
 and spends a step on each, a paused turn costs tokens and no step, and not every
 step takes a screenshot. It defaults to 20 and is capped at 100 here.
@@ -919,12 +975,14 @@ does not.
 **screenshots deliberately do not**, so a loop that only watches can see its own
 machine go down under it.
 
-**A stop is a request, and can be refused.** `stop_computer` asks the guest to
-shut down and gives it time to do it. A hung X session, a modal "unsaved
-changes" dialog or a service that ignores its own shutdown will refuse that
-identically every time it is asked. `force: true` pulls the power instead — the
-equivalent of holding the button in — and whatever the guest had not written to
-disk goes with it, so it is the second attempt rather than the first.
+**A stop asks first, then forces.** `stop_computer` asks the guest to shut
+down and gives it up to 20 seconds; a guest still up after that — a hung X
+session, a modal "unsaved changes" dialog, a service that ignores its own
+shutdown — is forced off by the platform, so an ordinary stop ends stopped and
+can take up to about a minute to answer. `force: true` skips the asking and the
+wait and pulls the power at once — the equivalent of holding the button in — and
+whatever the guest had not written to disk goes with it. It saves 20 seconds,
+not a failed stop, so leave it out unless the computer must be off immediately.
 
 **Purging snapshots is bound to the set you were shown.** Deleting a computer
 keeps its snapshots by default. To destroy them too, read `snapshot_holdings`
@@ -984,8 +1042,13 @@ 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.
+`running` needs the computer stopped first. A 409 with no `reason` is
+unclassified, and is treated as one that does not clear — a label that is taken,
+a computer at its public URL limit, the webhook cap, an SSH key already
+registered — unless its `code` is one the platform documents as passing
+(`idempotency_in_progress`, or `WORKSPACE_MOVING` while the move settles). 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
@@ -1000,7 +1063,10 @@ same way. So `isTransient` is false for it whatever `reason` it carries, the
 tool's answer says to read the current state first, and `error.method` records
 the method. A `reason` this version does not
 know, such as a new word, is treated as no classification. `reasonKind` returns
-`undefined` for it, and the status decides.
+`undefined` for it, and the status decides — which, for a 409, is no: a 409 is
+transient only when its `reason` clears or its `code` is
+`idempotency_in_progress` or `WORKSPACE_MOVING` (with no `reason` saying
+otherwise). `APIError.code` carries the platform's code.
 
 The secret store has typed calls on `api.secrets`: `list`, `create`, `get`,
 `replace` and `delete`. Each answer is decoded strictly to the documented
@@ -1041,9 +1107,11 @@ intermediaries and connection failures may supply none of them. Existing
 constructor arguments retain their meanings; an optional trailing
 `APIErrorMetadata` object adds these three fields, and `method`.
 
-MCP error results include supplied `reason`, `request_id`, `allow`,
-`www_authenticate` and `retry_after_ms` as labelled JSON metadata. Diagnostic
-strings are limited to 128, 256, 512 and 512 characters respectively; an
+MCP error results include supplied `code`, `reason`, `request_id`, `allow`,
+`www_authenticate` and `retry_after_ms` as labelled JSON metadata. `code` is the
+platform's machine-readable code (`LABEL_TAKEN`, `WORKSPACE_MOVING`, …), the
+word to switch on rather than the sentence. Diagnostic
+strings are limited to 128, 128, 256, 512 and 512 characters respectively; an
 oversized field is omitted with a notice, so a shortened Allow is never
 presented as complete. Tool-specific warnings about partial work, retained
 publication, execution reads and explicit template continuation still apply.
@@ -1372,7 +1440,7 @@ address.
 | `MANDALA_PROFILE` | Local saved profile; `--profile` overrides it. Otherwise the file default is selected. Ignored by HTTP. |
 | `MANDALA_BASE_URL` | With a saved profile, must match its stored base. Otherwise defaults to `https://app.mandala.computer/api/v1`. |
 | `MANDALA_COMPUTER_ID` | Bind a computer at startup, so `use_computer` is not needed. **stdio only** — under `--http` it is ignored rather than bound into every caller's session, since it names a machine on the operator's account. |
-| `MANDALA_MODEL_KEY` | An Anthropic key. Enables `run_agent` and `run_agent_chat` when filters permit them, which runs the platform's own loop on that key. **stdio only** — under `--http` each caller sends their own as `X-Model-Key`, and this variable is ignored. |
+| `MANDALA_MODEL_KEY` | An Anthropic or OpenAI key. Enables `run_agent` and `run_agent_chat` when filters permit them, which runs the platform's own loop on that key. Without it, `run_agent` runs on the account's AI credits when they can pay. **stdio only** — under `--http` each caller sends their own as `X-Model-Key`, and this variable is ignored. |
 | `MANDALA_NO_LIFECYCLE` | `1`, `true`, `yes` or `on` withholds `create_computer`, `clone_computer`, `clone_snapshot`, `delete_computer` and `delete_snapshot` — every tool that makes a computer or destroys one. `0`, `false`, `no`, `off` or unset leaves them registered. Any other value is **refused at startup** rather than read as off: a typo here would otherwise leave those tools in place on a server whose operator believes they are gone. The `--no-lifecycle` flag reads the same vocabulary and refuses the same way, except that it has no spelling for *unset*: `--no-lifecycle=` is refused rather than ignored, so a launcher template whose variable did not expand stops instead of quietly leaving the tools registered. |
 | `PORT`, `HOST` | For `--http`. Default `3000`, `127.0.0.1`. |
 | `MANDALA_READ_ONLY` | Keep only tools annotated `readOnlyHint: true`; strict boolean parsing as described under Tool filters. |
@@ -1397,9 +1465,54 @@ none of which is true of `MANDALA_API_KEY`.
 `run_agent` deserves a note. It hands a task to the platform's own agent loop,
 which drives the computer inside the platform and answers with a sentence. Worth
 it when a stretch of pixel work would otherwise cost the calling model a
-screenshot per step — ten clicks stop being ten images. It bills your Anthropic
+screenshot per step — ten clicks stop being ten images. It bills your selected provider
 key, and the platform never stores that key.
 
+Both `run_agent` and `run_agent_chat` accept `provider: "openai"` to use
+`gpt-6.1-sol` by default, or infer OpenAI from a recognized GPT model name.
+Set `MANDALA_MODEL_KEY` (stdio) or `X-Model-Key` (HTTP) to the matching provider
+key. Custom model names require an explicit `provider`; omitting model and
+provider preserves the Anthropic default. OpenAI is BYOK only and stores
+Responses continuations at OpenAI; tasks, screenshots and tool results go to
+that provider. A native OpenAI action batch must fit the remaining step and
+API budget before it begins. Partial failures stop the run without replaying input.
+
+### Agents on AI credits
+
+Without a model key, `run_agent` can run on the account's Mandala AI credits.
+The server reads `GET /credits` on the session's own API key and registers
+`run_agent` only when the account is not frozen and has at least $0.25
+available, which is what a run's first model call reserves. On stdio that read
+happens once, at startup. Over HTTP it happens per session, at initialize, with
+that caller's bearer token; a caller who sends `X-Model-Key` is not asked, and no
+operator key or setting is ever used. Any failure of the read — a refusal (a
+workspace-scoped key cannot read the account-wide ledger), an error, a timeout or
+a record that does not parse — leaves `run_agent` out. A session started
+unfunded does not gain the tool when credits arrive later; reconnect, or restart
+a stdio server.
+
+On credits `run_agent` takes `max_cost_usd` (0.25 to 20; the platform defaults
+to 2), the most a run may start spending. The last model call can go past it,
+and a run that reaches it ends with `stop: "max_cost"`. It does not take
+`system` or `provider`: a run on credits uses the platform's own prompt and
+Anthropic, with `claude-sonnet-5-5` by default and `claude-opus-5-5` on request.
+The result reports `cost_usd`, the run's charge so far, and
+`credits_remaining_usd`, the balance the last step reported. A run whose credits
+run out partway ends with `stop: "credits_exhausted"`, and a run that cannot
+reserve its first call is refused `402` with a `top_up_url`; the tool reports
+that as the account's credits running out, with the billing page, rather than as
+a plan limit or the model provider's billing error. The platform reports its
+AI service failing a run on credits as `Mandala AI is unavailable` over the
+provider's status. On such a run that sentence, at any status, and any other
+`402`, are worded as the service failing, not as the caller's credential, the
+computer, the request or a model key. `run_agent_chat` is never registered
+without a model key: the platform runs that route only on the caller's own key.
+
+`get_credits` reads the ledger: available, balance, held, debt, whether the
+account is frozen, this period's plan grant, the unexpired lots and one page of
+the journal, newest first (`before` and `limit` page through it). Amounts are
+integer USD micros. It needs an account-wide key.
+
 ### Passive directories, activity history and signals
 
 `list_directory` takes an exact absolute guest `path`. Unicode, spaces and
@@ -1441,14 +1554,14 @@ or that a task succeeded. Unsupported (501) and unavailable (503) responses
 remain errors, never empty history or new checkpoints. There is no watcher,
 guest action, retry loop or automatic checkpoint cache in this tool.
 
-### JSON chat with your own Anthropic key
+### JSON chat with your own model key
 
-`run_agent_chat` drives the selected computer using the same BYOK Anthropic loop
+`run_agent_chat` drives the selected computer using the same BYOK Anthropic or OpenAI loop
 as `run_agent`. It accepts a nonempty array of textual OpenAI-shaped `messages`,
 including string content or arrays of `{type:"text",text:"..."}` parts. The
 **last user message** supplies the task; system messages supply standing
 instructions. Earlier user/assistant conversation is not replayed. Optional
-`model` is sent unchanged and must name an Anthropic model. `max_steps` is 1–100,
+`model` selects a computer-capable Anthropic or OpenAI model. `max_steps` is 1–100,
 default 20. This is computer control, not hosted general-purpose inference or a
 chat UI; it adds no key storage or model billing service.
 
@@ -1482,7 +1595,9 @@ 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
+without `revoked` may be the provider's permission error for that key. The one
+`402` that is Mandala's own carries a `top_up_url`: a run on AI credits the
+account cannot cover, worded as such. 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
@@ -1511,8 +1626,13 @@ overall deadline and an 8 MiB body ceiling, then exercises the real MCP tools
 and requires request evidence for every published `/api/v1` operation. Every
 exercise variant must succeed and dispatch a request, including later variants
 of a tool that already dispatched successfully.
-Non-v1 operations are explicitly excluded and reported. The check uses OpenAPI
-server inheritance and literal-path precedence, not the local route allowlist.
+Non-v1 operations are explicitly excluded and reported. Protocol forms are
+reported but not required, since no tool sends them: `OPTIONS` (the CORS
+preflight) and a `HEAD` published beside a `GET` at the same URL (that `GET`
+without its body). A `HEAD` with no such `GET` is required like any other
+operation.
+The check uses OpenAPI server inheritance and literal-path precedence, not the
+local route allowlist.
 Each path is appended to its effective server base; repeated prefixes are not
 removed. Fully prefixed paths work with an absent or root server.
 It fails on a blocked fetch, redirect, invalid document or missing operation;
@@ -1520,11 +1640,10 @@ there is no fixture fallback, credential requirement or skip branch.
 
 The committed OpenAPI fixture is synthetic, assembled from the public MCP route
 inventory, and is never presented as a downloaded publication. Offline green
-proves deterministic implementation coverage only. Anonymous CI at
-[commit 1b04314](https://github.com/mandalacomputer/mcp/commit/1b04314e84f5701e2e15c65cbb1c44a0c14a4948)
-returned HTTP 200 and matched all 56 operations in the fetched v1 contract using
-123 requests from 83 tools. That result applies to that commit and publication;
-every subsequent head must pass the gate independently. These counts are
+proves deterministic implementation coverage only. Each `published-openapi` run
+logs the publication's digest and how many operations it matched with how many
+requests from how many tools; a result applies to that commit and that
+publication, and every head must pass the gate independently. Those counts are
 observations, never fixed thresholds or exemptions. A blocked or red public gate
 must not be merged. Parameters and response modes remain separate contracts,
 with documented parameter exceptions and JSON-only chat support.
@@ -1580,6 +1699,7 @@ several names. Where a client has no way to do it, the cell says so with —.
 | 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` | — |
+| A screenshot, fresh or cached | `screenshot(width, { fresh, capture })`: cached unless `fresh: true` | `screenshot(fresh=…, capture=…)`: cached unless `fresh=True` | `screenshot`: **fresh by default** unless `capture` is given; `fresh: false` for the cache | `computers screenshot --fresh` | — |
 | 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

@@ -2,7 +2,7 @@ import { Agent } from 'undici';
 import { type SecretStore } from './secret-store.js';
 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. */
+/** The caller's provider key, forwarded for the hosted agent routes. */
 export declare const MODEL_KEY_HEADER = "X-Model-Key";
 /**
  * The header every lifecycle call carries so that sending it again cannot do
@@ -90,6 +90,13 @@ export type Bytes = {
      * than a capture of its screen.
      */
     frame?: string;
+    /** X-GC-Capture: the live screenshot's reusable capture name. */
+    capture?: string;
+    /** X-GC-Capture-Size: the capture's own pixels, before cropping or scaling. */
+    captureSize?: {
+        width: number;
+        height: number;
+    };
 };
 /**
  * The longest foreground guest exec waits 600 seconds before it answers.
@@ -210,7 +217,7 @@ export declare class Api {
      * Routes where an empty body IS the answer use `send`.
      */
     json<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
-    /** Existing exec decoding plus observed status, used only to confirm optional retention. */
+    /** JSON decoding plus observed status, for operations requiring a specific success status. */
     jsonWithStatus<T>(method: string, path: string, opts?: RequestOptions): Promise<{
         status: number;
         value: T;

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

@@ -7,7 +7,7 @@ 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. */
+/** The caller's provider key, forwarded for the hosted agent routes. */
 export const MODEL_KEY_HEADER = 'X-Model-Key';
 /**
  * The header every lifecycle call carries so that sending it again cannot do
@@ -66,6 +66,14 @@ function responseMetadata(resp) {
         wwwAuthenticate: resp.headers.get('www-authenticate') ?? undefined,
     };
 }
+function captureSizeFrom(value) {
+    if (!value || !/^[1-9]\d*x[1-9]\d*$/.test(value))
+        return undefined;
+    const [width, height] = value.split('x').map(Number);
+    return Number.isSafeInteger(width) && Number.isSafeInteger(height)
+        ? { width, height }
+        : undefined;
+}
 /**
  * How much of an event stream will be held while waiting for a boundary.
  *
@@ -574,15 +582,16 @@ export class Api {
         }
         return body;
     }
-    /** Existing exec decoding plus observed status, used only to confirm optional retention. */
+    /** JSON decoding plus observed status, for operations requiring a specific success status. */
     async jsonWithStatus(method, path, opts = {}) {
         return this.#guard(method, path, opts, () => this.#jsonWithStatusRaw(method, path, opts));
     }
     async #jsonWithStatusRaw(method, path, opts = {}) {
         const resp = await this.#fetch(method, path, opts);
         const value = await this.#decode(resp, method, path, opts.signal ?? this.#signal);
-        if (value === undefined || value === null)
-            throw new MandalaError('Expected an exec response');
+        if (value === undefined || value === null) {
+            throw new MandalaError(`${method} ${path} answered ${resp.status} without the expected JSON response; the outcome could not be confirmed`);
+        }
         return { status: resp.status, value };
     }
     /** Complete bounded responses for immutable retained protocols; never a successful prefix. */
@@ -754,6 +763,8 @@ export class Api {
             unrangeable: (resp.headers.get('accept-ranges') ?? '').trim().toLowerCase() === 'none',
             window,
             frame: resp.headers.get('x-gc-frame')?.trim().toLowerCase() || undefined,
+            capture: resp.headers.get('x-gc-capture')?.match(/^[a-f0-9]{16}$/)?.[0],
+            captureSize: captureSizeFrom(resp.headers.get('x-gc-capture-size')),
         };
     }
     // --- the account's secret store (OPL-4984) ------------------------------