mandala-computer-mcp 0.3.0 → 0.5.0

package/README.md

@@ -12,17 +12,54 @@ model looks at the screen and clicks what it sees.
 
 ## Install
 
-You need an API key from the dashboard — **Settings → API keys**, a `com_…`
-string. It is scoped to your account and it is every computer on it, so treat it
-the way you would treat a password.
+MCP requires Node 20.3 or newer. The **TypeScript CLI** login setup requires
+Node 22 or newer (`mandala-computer` on npm). Sign in once, then add the MCP
+server:
 
-Node 20.3 or newer. There is nothing else to install: `npx` fetches the server
-the first time a client starts it.
+```sh
+npm install -g mandala-computer
+mandala login
+claude mcp add mandala -- npx -y mandala-computer-mcp
+```
+
+On Node 20, MCP can use an existing saved profile or an environment key.
+The TypeScript CLI guides you through browser approval and saves an API key in
+`~/.mandala/credentials.json`. MCP only reads that file; it never issues or
+approves a device, writes credentials, or starts login automatically. The
+Python distribution also provides a `mandala` command; use the TypeScript
+CLI for `login`.
+
+To select a separate profile and workspace:
+
+```sh
+mandala login --profile Work --workspace Research
+claude mcp add mandala -- npx -y mandala-computer-mcp --profile Work
+```
+
+`--profile` takes precedence over `MANDALA_PROFILE`, then the saved default.
+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`.
+
+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,
+hardlinks, unsafe permissions, malformed files and unsupported protection are
+refused before any API request. Windows file loading is unsupported; explicit
+or environment keys remain available. Only your home directory's store is read.
+
+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.
 
 **Claude Code** — as a plugin, which installs the server and a skill together:
 
 ```sh
-export MANDALA_API_KEY=com_…       # in the shell Claude Code starts from
+# Run mandala login first, or export MANDALA_API_KEY in this shell.
 /plugin marketplace add mandalacomputer/mcp
 /plugin install mandala-computer@mandala
 ```
@@ -34,9 +71,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`.
+`run_agent` when the configured filters permit it.
 
-Or the server on its own, with the key inline:
+To use an environment key instead of a saved profile:
 
 ```sh
 claude mcp add mandala -e MANDALA_API_KEY=com_… -- npx -y mandala-computer-mcp
@@ -49,8 +86,7 @@ claude mcp add mandala -e MANDALA_API_KEY=com_… -- npx -y mandala-computer-mcp
   "mcpServers": {
     "mandala": {
       "command": "npx",
-      "args": ["-y", "mandala-computer-mcp"],
-      "env": { "MANDALA_API_KEY": "com_…" }
+      "args": ["-y", "mandala-computer-mcp"]
     }
   }
 }
@@ -59,8 +95,11 @@ claude mcp add mandala -e MANDALA_API_KEY=com_… -- npx -y mandala-computer-mcp
 **Cursor, Windsurf and the rest** take the same three fields — `command`,
 `args`, `env` — in whichever file they keep their MCP servers in.
 
-Nothing is hosted and nothing is operated: your MCP client starts this as a
-subprocess, and it talks to `https://app.mandala.computer/api/v1` with your key.
+Your MCP client starts this as a subprocess. It uses the saved profile’s API
+base, or `https://app.mandala.computer/api/v1` by default with an environment key.
+Programmatic local hosts can call `runStdio({ profile: 'Work' })`; the exported
+`StdioConfig` allows a local key or profile. `createServer` still requires an
+explicit API key, and `HttpConfig` has no local credential options.
 
 ## Use
 
@@ -95,6 +134,12 @@ entirely.
 
 ## The tools
 
+This is the unfiltered inventory. The filters below can withhold tools from
+both listing and calling; workflows in this README apply only when the needed
+tools are available. The offline fixture checks exercised operation coverage;
+verification against the live publication is a separate required CI gate.
+Parameter and response-mode support remains a separate contract.
+
 **Choosing a machine** — `list_templates`, `list_sizes`, `list_computers`, `get_computer`,
 `use_computer`, `wait_for_computer`, `get_desktop_url`
 
@@ -105,9 +150,15 @@ entirely.
 **Driving the desktop** — `screenshot`, `click`, `type_text`, `press_key`,
 `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait`
 
-**Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `open_url`,
+**Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `get_execution`,
+`read_execution_output`, `open_url`,
 `list_windows`, `window_action`, `read_clipboard`, `write_clipboard`,
-`read_file`, `write_file`
+`read_file`, `write_file`, `list_directory`
+
+**Retained versions** — `retain_execution_output`, `get_result`, `read_result_output`,
+`delete_result`, `publish_artifact`, `get_artifact`, `read_artifact`, `delete_artifact`
+
+**Passive metadata** — `list_activities`, `get_activity`, `get_activity_results`, `read_signals`
 
 **Being told rather than asking** — `wait_for_event`, `poll_events`,
 `wait_for_file_change`
@@ -121,14 +172,118 @@ entirely.
 
 **Building one** — `build_template`, `list_builds`, `get_build`, `watch_build`
 
+**Account quota** — `get_account`
+
 **Spending** — `get_usage`
 
 **Being told somewhere else** — `list_webhooks`, `create_webhook`,
 `get_webhook`, `update_webhook`, `rotate_webhook_secret`, `test_webhook`,
 `list_webhook_deliveries`, `delete_webhook`
 
-**Delegating** — `run_agent`, registered only when a model key is present:
+**SSH access** — `list_ssh_keys`, `add_ssh_key`, `remove_ssh_key`,
+`get_computer_ssh`, `set_computer_ssh`. Keys belong to the person the API key
+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.
+
+**Secret bindings** — `get_computer_secrets`, `set_computer_secrets`, and
+`create_computer`'s `secrets`. Which of the account's secrets a computer
+receives, at which revision, and where: as an environment variable (`env`) or as
+a file under `/run/mandala-secrets/user/files` (`file`). Values never cross these
+tools. A set replaces the whole 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 secret bound
+as a file is also rewritten on a running computer when its value is replaced.
+
+**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.
+Both must also survive the configured filters.
+
+### Tool filters
+
+Set `MANDALA_READ_ONLY=1` to register only tools whose existing
+`annotations.readOnlyHint` is exactly `true`. It accepts `1`, `true`, `yes`,
+`on` for on and `0`, `false`, `no`, `off`, empty or unset for off, ignoring
+surrounding whitespace and letter case. Any other value fails at startup.
+Safety is not inferred from a tool's name or HTTP method: `read_file` and
+`cursor_position` can wake and bill a computer, so they are withheld. So are
+mixed read/write tools such as `wait_for_computer` and `snapshot_schedule`.
+`screenshot`, `read_clipboard` and `list_windows` retain their read-only hints.
+
+Set `MANDALA_TAGS=input,guest` to select a union of named tool groups. Names
+are **lowercase only**, comma-separated, trimmed and deduplicated. Empty or
+unset means no tag filter; empty comma-separated entries are ignored. An
+unknown nonempty tag fails before stdio connects or HTTP starts listening,
+with an error listing all valid tags.
+
+| Tag | Tools |
+| --- | --- |
+| `account` | `get_account` |
+| `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` |
+| `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` |
+| `results` | `get_activity_results`, `retain_execution_output`, `get_result`, `read_result_output`, `delete_result` |
+| `artifacts` | `publish_artifact`, `get_artifact`, `read_artifact`, `delete_artifact` |
+| `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` |
+| `webhooks` | All webhook tools listed above |
+| `ssh` | All SSH tools listed above |
+| `secrets` | `get_computer_secrets`, `set_computer_secrets` |
+| `agent` | `run_agent`, `run_agent_chat` |
+| `activities` | `list_activities`, `get_activity`, `get_activity_results` |
+| `signals` | `read_signals` |
+
+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
+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.
+`activities,results` includes `get_activity_results` once; `signals` is separate
+from the active `events` socket. Filters never grant API privileges: the API
+checks current member/owner and workspace authorization on every request.
+
+`use_computer` is not read-only. When it is withheld, pass `computer_id`
+explicitly, or bind a computer with `MANDALA_COMPUTER_ID` at stdio startup.
+HTTP callers must supply their own computer selection. These variables apply
+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.
+
+### Current account quota
+
+`get_account` takes no arguments and reads `GET /api/v1/account` once with the
+caller's account credential. Viewer or stronger access is required. It reports
+account-wide aggregates, including for a workspace-scoped key, without resource
+identities. It needs no selected computer or model key, opens no event stream,
+and remains available with read-only and no-lifecycle filters. Select the
+`account` tag to expose it on its own.
+
+The report includes the effective plan, pool ceilings, per-computer maxima,
+Windows capability, current consumption and remaining quota. Configured CPU and
+disk include kept computers regardless of power state; running or reserved RAM
+includes current reservations. CPU, MB, GB and snapshot bytes retain the API's
+units. `get_usage` separately reports historical metered consumption over time.
+
+Quota is **advisory**: `observed_at` is an observation time, not a reservation or
+consistency token. Later create, resize, start or snapshot requests can still be
+refused, and existing 402 messages remain unchanged. Snapshot headroom is against
+**indexed stored bytes**; it does not include in-flight capture reservations and
+does not establish that a new capture will fit.
+
+`complete.computers` and `complete.snapshots` are independent. An incomplete group
+has `null` for all its consumption and remaining figures, meaning **unknown**,
+while the other group can retain numeric values. Complete zero usage and zero
+remaining quota remain numeric zeros. Verified plan ceilings remain available in
+a partial report, including a no-plan account that still has retained usage.
+Malformed reports and HTTP failures remain errors, never an empty account.
+The tool prints unknown and advisory guidance before the projected public fields.
 
 ## Things worth knowing
 
@@ -157,9 +312,11 @@ 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)),
-bills that key for every step, and `max_steps` is the spending cap as much as
-the loop bound.
+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
+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.
 
 **A screenshot is how you find out what the screen looks like.** A click that
 landed and a click that did nothing produce the same tool result, so a model
@@ -355,6 +512,107 @@ foreground comes back as a timeout, with the work still going inside the guest
 and its output unreadable. With a handle you get the exit code and the output,
 and `exec_kill` stops it.
 
+**Stable background reads.** When an accepted `exec` returns `execution_id`,
+use `get_execution` for its last observed `running`, `exited` or `lost` state.
+Only `exited` carries an `ended_at` and signed `exit_code`; `running` does not
+prove the computer is awake, and `lost` establishes neither success nor failure.
+Older replies can omit the ID. A malformed supplied ID leaves the accepted
+command and its valid PID usable, but supplies no stable identity: do not replay
+the command to obtain one. PID polls/kills never reconstruct this association.
+
+`read_execution_output` takes that ID and **both** `stdout_offset` and
+`stderr_offset` byte positions. Start each reader at zero, then pass its own
+returned positions. For example:
+
+```json
+{"execution_id":"exec_0123456789abcdef0123456789abcdef","stdout_offset":0,"stderr_offset":0,"limit":4096}
+```
+
+Each stream is bounded to 4,096 bytes by default, at most 16,384. Complete
+lossless UTF-8 appears as `stdout`/`stderr` with its BOM preserved. NUL, binary
+and split UTF-8 chunks remain exact canonical `stdout_b64`/`stderr_b64`; nothing
+is trimmed or replaced. `stdout_more` and `stderr_more` are independent, and
+false means EOF at that moment, not that the command has finished.
+
+The separate `diagnostic`/`diagnostic_b64` repeats on every read. At most 4,096
+of its up-to-65,536 available bytes are displayed: inspect
+`diagnostic_available_bytes`, `diagnostic_displayed_bytes`, and
+`diagnostic_display_truncated`. The independent `diagnostic_truncated` flag is
+the platform's capture limitation. Diagnostics never advance either cursor.
+Neither new tool consumes output from another reader or the shared `exec_poll`
+cursor, and both carry read-only, non-destructive, idempotent annotations.
+
+These are single requests with cancellation, no automatic resume, retry,
+watcher, capture or command replay. Metadata reads no guest files. Output reads
+perform guest I/O without refreshing activity and are unsuitable for passive
+Activities/history. Files are mutable guest data, not retained artifacts;
+handles can vanish on restart, replacement or cleanup, and observed exits
+expire after ten minutes. An unavailable read is an error, not empty output.
+Every new-tool result is bounded to 256 KiB of serialized data.
+
+**Explicit immutable retained versions.** `retain_execution_output` accepts an
+`execution_id` and captures one version of its volatile output with one POST.
+It performs guest I/O, without resuming or replaying the command. Its optional
+`max_bytes_per_stream` defaults to 1 MiB (maximum 4 MiB); `retention_seconds`
+defaults to 86400 (maximum 604800). Diagnostics are separate, up to 64 KiB.
+Each capture creates a version; there is no automatic capture or retry.
+
+`get_result` reads finite metadata by `result_id`. `read_result_output` requires
+`result_id`, `stream` (`stdout`, `stderr` or `diagnostic`) and `offset`, with
+`limit` defaulting to 4096 and capped at 16384 bytes. It reads one independent
+page, with exact `offset`, `next_offset`, `eof` and returned `bytes` count.
+Content is lossless `text` (BOM preserved) or canonical `base64` for binary,
+controls and split UTF-8. EOF means the end of this retained prefix, not task
+completion. A page alone does not verify the full manifest hash.
+`delete_result` deletes that version once; a repeated 404 remains unavailable.
+
+Existing synchronous `exec` accepts `retain_output: true` or a strict object
+with those same two options. False or absence leaves default behavior alone.
+It cannot be combined with `background: true`. A canonical returned `result_id`
+confirms optional retention; no execution ID is fabricated. Missing, malformed
+or unsupported optional metadata leaves the command outcome unchanged and does
+not authorize replay. Retained-prefix truncation and upstream response
+truncation are distinct. Synchronous results have no diagnostic stream; an
+explicit diagnostic read can return 409.
+
+**Nominated file versions.** `publish_artifact` requires an absolute `path`,
+`expected_size` and `expected_sha256` supplied by the caller. For example:
+
+```json
+{"path":"/tmp/empty.txt","expected_size":0,"expected_sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
+```
+
+Paths preserve legal Unicode, spaces and Linux backslashes; Windows drive and
+UNC paths are also accepted, subject to the platform's current OS proof.
+Publication performs one nominated guest-file capture, without a client-side
+stat, list, read, hash or exec preflight. `max_bytes` defaults to 8 MiB and is at
+most 64 MiB; expected size must fit. Retention has the bounds above. Optional
+`execution_id` records verified **caller selection**, not proof the execution
+created the file. Every publication creates an independent immutable version.
+
+`get_artifact` reads metadata. `read_artifact` first reads that metadata and,
+only if the complete size fits `max_bytes` (default 4096, maximum 16384), reads
+the entire retained object and verifies its exact length and SHA-256. Over-cap
+objects return metadata with a refusal before any content request; use an SDK
+whole download with an adequate cap. There are no partial artifacts, Range
+requests, local destinations, filenames, image/HTML previews or guest fallbacks.
+Verified content uses the same lossless `text`/`base64` presentation.
+`delete_artifact` deletes only that stored version, not the guest file; repeat
+404s remain truthful failures.
+
+All eight retained tools resolve the computer selection once. Reads are passive
+but require current authorization and scope availability; retained bytes can be
+unavailable when the host cannot verify access, after expiry or deletion, or
+when storage is unavailable. They never wake a guest or substitute live output.
+New operations have one 90-second budget across headers, bodies, and both
+artifact requests. An MCP client can impose an earlier deadline. Cancellation,
+redirects and malformed responses never trigger a retry; a lost publication
+response means commitment is **unconfirmed**, not undone. Each entire serialized
+retained tool result is bounded to 256 KiB. Reads are marked read-only;
+capture/publication create new versions; deletes are destructive with an
+idempotent deletion effect. Activities result detail remains outside this MCP
+runtime.
+
 Past about **two minutes** it does not even come back as a timeout. A proxy in
 front of the platform abandons a request that has produced no response for
 roughly that long and answers 524, which arrives as `GatewayTimeoutError` —
@@ -455,6 +713,66 @@ about storage instead.
 guest agent answers 409. 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
+available. A missing computer, snapshot, route or guest file remains
+`NotFoundError` (404); other guest failures keep their own status and message.
+Neither response causes an automatic retry or method switch.
+
+Embedders can inspect optional diagnostics on every `APIError`:
+
+```ts
+import { Api, APIError, MethodNotAllowedError } from 'mandala-computer-mcp';
+
+const api = new Api(process.env.MANDALA_API_KEY!);
+try {
+  await api.json('GET', 'account');
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error({ status: error.status, requestId: error.requestId,
+      reason: error.reason, allow: error.allow,
+      wwwAuthenticate: error.wwwAuthenticate });
+    if (error instanceof MethodNotAllowedError) {
+      // Inspect error.allow before correcting the request method.
+    }
+  }
+}
+```
+
+`requestId` uses a nonblank `X-Request-ID` header first, then the top-level
+`request_id` body field. It is an opaque diagnostic, never an idempotency key.
+The raw body remains available on `error.body`, including any differing body ID
+and nested chat accounting. `allow` and `wwwAuthenticate` come only from received
+headers. HEAD failures can carry these fields with no body. Older servers,
+intermediaries and connection failures may supply none of them. Existing
+constructor arguments retain their meanings; an optional trailing
+`APIErrorMetadata` object adds these three fields.
+
+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
+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.
+Serialized JSON object or array prefixes are not displayed as error prose.
+Valid scalar error messages retain their wording; embedders still have the
+original `APIError.message` and `APIError.body` for diagnostics. Native agent
+error frames retain their supplied numeric status even without a reason or
+request ID, independently of the successful HTTP stream carrying them.
+
+For a 401, `missing` means a platform credential was not supplied; `invalid`
+means the supplied platform credential was not accepted; `revoked` means its
+authority no longer holds. Unknown reasons stay visible. An unclassified 401
+alone does not identify whether the account key or model key was refused,
+including a nested chat failure. A 403 remains a permission or authority
+refusal. Inspect recorded work before another run; no key fallback, login or
+automatic replay is performed. Nested error reasons and in-band stream errors
+do not grant permission to replay a partly completed run.
+
+For desktop events, use the exact returned `events_url`, including its desktop
+capability, in a WebSocket client. A REST Bearer key alone is not sufficient;
+the HTTP events response provides JSON guidance rather than another login flow.
+
 **Desktop links are credentials.** `get_desktop_url` returns the watch-only URL
 by default — the platform drops input on that socket, so it is safe to hand to
 somebody. `control: true` returns the full-control one, which is root-equivalent
@@ -556,7 +874,9 @@ for whatever is checking that the process is up.
 bearer token and is used only for their session; there is no store, and nothing
 outlives a session but a digest of the key — kept so that a later request can be
 shown to come from the same holder, which means a leaked session id on its own
-is not enough to drive somebody else's desktop.
+is not enough to drive somebody else's desktop. HTTP startup and requests never
+read the operator's credential store, `MANDALA_API_KEY` or `MANDALA_PROFILE`.
+`--profile` is local-only and ignored with `--http`.
 
 That is also why anyone can run their own: point the same container at the same
 API and it works, with no secret to provision.
@@ -579,17 +899,20 @@ naming the fix.
 
 | Variable | Meaning |
 | --- | --- |
-| `MANDALA_API_KEY` | `com_…` from Settings → API keys. Required on stdio; over HTTP each caller sends their own. |
-| `MANDALA_BASE_URL` | Defaults to `https://app.mandala.computer/api/v1`. |
+| `MANDALA_API_KEY` | Optional local API key, taking precedence over saved credentials. Ignored by HTTP; each caller sends their own bearer token. |
+| `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`, 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 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_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. |
+| `MANDALA_TAGS` | Comma-separated lowercase tool tags; see Tool filters for the inventory and intersection rules. |
 | `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. |
 
-Every one of these but the model key has a flag as well, and a flag overrides
+Every one of these but the model key and the two tool filters has a flag as well, and a flag overrides
 the environment: `--http`, `--port`, `--host`, `--base-url`, `--computer`,
-`--allowed-hosts`, `--allowed-origins`, `--no-lifecycle`, plus `--help` and
+`--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
 `ps`, lands in shell history and is recorded verbatim by any exec audit —
@@ -601,17 +924,116 @@ 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
 key, and the platform never stores that key.
 
+### Passive directories, activity history and signals
+
+`list_directory` takes an exact absolute guest `path`. Unicode, spaces and
+punctuation survive query encoding. It requires an already running computer,
+does not resume it or extend its idle timer, and still contacts the guest with
+ordinary rate/capacity admission. The result preserves `path`, `entries` with
+`name`, `type` and optional `size_bytes`, `truncated` and `skipped`. An unavailable
+entry has no inferred type or zero size. Symlinks are not followed, and a final
+symlink directory is refused. No file content is read. A partial listing is an
+unordered subset: at most 512 examined entries/128 KiB, with no continuation
+token. Narrow the path when names are omitted; do not automatically rescan.
+
+`list_activities` returns one newest-first history page with a fixed watermark.
+Pass an opaque `cursor` for continuation, or `changes:true` with a cursor for
+late final updates to older rows. False/absent `changes` is omitted on the wire;
+there is no `limit` argument. Preserve `next_cursor`, `changes_cursor`, `gap`
+and health fields. A gap requires refreshing history. The tools keep no cursor
+cache and never drain pages automatically. `get_activity` takes an `activity_id`
+shaped as `act_` plus 32 lowercase hex digits, a request identity rather than an
+idempotency key. Recorded state, scope, revision, timestamps, execution identity
+and status remain distinct: accepted background work is not finished execution,
+and a dispatched error may have had effects. History is selected, retained,
+best-effort metadata, not all guest work or an agent identity.
+
+`get_activity_results` returns at most eight newest metadata links, preserving
+revision, availability, association, byte/truncation metadata and observations.
+`more:true` has no continuation cursor and does not mean all versions were
+returned. An unavailable item is not an empty available item. Caller-selected
+artifact association does not prove creation or command success. This tool
+never follows a link to content, files, captures, downloads or execution polling.
+
+`read_signals` reads one passive daemon page, independently of the active event
+socket. Omit `since` or send an empty string for a head-only baseline with no
+replay. Optional `limit` is 1–100; omitting it uses the API default 50. Preserve
+the returned `cursor` even when `events` is empty: filtered-out rows may advance
+it. Retention is ephemeral; expired/restarted/migrated cursors can return an
+explicit reset gap. Baselines and gaps do not prove there was no earlier work
+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
+
+`run_agent_chat` drives the selected computer using the same BYOK Anthropic 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,
+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.
+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,
+recorded steps and native usage, including separate cache-read and cache-write
+token counts, alongside OpenAI-shaped aggregate usage. Malformed native detail
+is explicitly marked incomplete. A failed call may include completed, billed
+work: inspect it before deciding what remains, and do not automatically replay.
+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.
+
 ## Development
 
 ```sh
-npm install
-npm test          # vitest, plus the surface check below
+npm ci
+npx vitest run    # deterministic offline tests, including the synthetic contract
+npm test          # offline tests plus the separate private mirror check
 npm run build
 npm run lint
 ```
 
-CI runs the suite on Node 20, 22, 24 and 26 — the floor `package.json`
-declares and the ceiling a current `npx` will actually use.
+CI runs the offline suite on Node 20, 22, 24 and 26. A separate Node 22
+`published-openapi` job runs on pull requests and main pushes:
+
+```sh
+npx vitest run --config vitest.openapi.config.ts
+```
+
+It anonymously fetches the fixed publication at
+`https://app.mandala.computer/api/docs/openapi.json` once, with a 20-second
+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.
+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;
+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
+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.
 
 ### Where the platform's rules live
 
@@ -624,17 +1046,20 @@ change to the platform's route table, not a wider pass-through here.
 
 The platform allowlists every route `/api/v1` will answer and 404s the rest.
 `test/allowlist.ts` mirrors that table, and the tests assert two things: that
-every call this server can make lands on an allowlisted route, and that the gap
-between the platform's surface and this server's coverage is *exactly* the set
-written down in `UNIMPLEMENTED`. A route added upstream becomes a failing test
-here rather than a feature nobody noticed.
+every successful exercised call lands on an allowlisted route, and that no
+mirrored operation remains unexercised (`UNIMPLEMENTED` is empty). Tool names
+and exercise entries must match in both directions, and every tool must make
+an observed HTTP request during its callback. The independent public gate also
+detects a new published operation when the mirror has not yet been updated.
 
 `npm run check:surface` goes further and diffs the mirror against the platform's
-own route table, whenever the platform repository happens to be checked out next
-door — or wherever `MANDALA_PLATFORM_REPO` points. Without it the script says
-it is skipping and exits 0, which is what it does for anyone outside the
-platform team; the diff is enforced from the platform's own CI, which checks
-this repository out beside itself and runs the same script.
+published surface manifest — a file the platform generates from its own tables
+and commits like a lockfile — whenever the platform repository happens to be
+checked out next door, or wherever `MANDALA_PLATFORM_REPO` points. Without it
+the script says it is skipping and exits 0, which is what it does for anyone
+outside the platform team; a manifest it cannot read is a failure, never a
+comparison of nothing. The diff is enforced from the platform's own CI, which
+checks this repository out beside itself and runs the same script.
 
 ```
 check:surface — the mirror matches the platform (N routes, N parameters, from …).

package/dist/api.d.ts

@@ -145,6 +145,14 @@ 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. */
+    jsonWithStatus<T>(method: string, path: string, opts?: RequestOptions): Promise<{
+        status: number;
+        value: T;
+    }>;
+    /** Complete bounded responses for immutable retained protocols; never a successful prefix. */
+    boundedBytes(method: string, path: string, limit: number, status: number, opts?: RequestOptions): Promise<BoundedBytes>;
+    boundedJson(method: string, path: string, limit: number, status: number, opts?: RequestOptions): Promise<unknown>;
     /**
      * A request whose answer may legitimately be nothing.
      *
@@ -196,4 +204,8 @@ export declare class Api {
 export declare function causes(err: unknown, depth?: number): Generator<Record<string, unknown>>;
 /** The filename the platform put on a download, if it put one there. */
 export declare function filenameFrom(disposition: string | null): string | undefined;
+export type BoundedBytes = {
+    bytes: Uint8Array;
+    headers: Record<string, string>;
+};
 //# sourceMappingURL=api.d.ts.map