mandala-computer-mcp 0.5.0 → 0.7.0

package/README.md

@@ -145,16 +145,29 @@ Parameter and response-mode support remains a separate contract.
 
 **Lifecycle** — `create_computer`, `start_computer`, `stop_computer`,
 `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`,
-`delete_computer`, `move_computer`, `list_moves`
+`delete_computer`, `move_computer`, `list_moves`, `get_operation`,
+`list_operations`, `wait_for_operation` — see [Lifecycle operations](#lifecycle-operations)
 
-**Driving the desktop** — `screenshot`, `click`, `type_text`, `press_key`,
-`scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait`
+**Driving the desktop** — `screenshot`, `click`, `type_text`, `paste_text`,
+`press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`,
+`wait`
 
 **Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `get_execution`,
 `read_execution_output`, `open_url`,
 `list_windows`, `window_action`, `read_clipboard`, `write_clipboard`,
 `read_file`, `write_file`, `list_directory`
 
+`write_file` replaces a file already at the path. With `overwrite: false` it
+creates the file only if nothing is there, and a path that is taken is refused
+without that attempt writing anything (Linux computers only). Incomplete
+contents are never published at the path, but a failure while publishing or
+answering can leave the complete file there, so after any error read the path
+before retrying or overwriting. `read_file` and `write_file` take `no_wake: true`
+to refuse (409) rather than resume a computer that is not running. For
+embedders, the `Api` raises that refusal as `FileExistsError`, and a
+create-only 409 whose reason could not be read as `CreateOnlyConflictError`,
+which says nothing about the path; `isTransient` is false for both.
+
 **Retained versions** — `retain_execution_output`, `get_result`, `read_result_output`,
 `delete_result`, `publish_artifact`, `get_artifact`, `read_artifact`, `delete_artifact`
 
@@ -174,6 +187,10 @@ Parameter and response-mode support remains a separate contract.
 
 **Account quota** — `get_account`
 
+**Who you are** — `whoami`, `list_api_keys`, `list_workspaces`,
+`get_workspace`, `list_workspace_members`. Minting and revoking API keys are
+deliberately not tools — see [Who you are, and API keys](#who-you-are-and-api-keys).
+
 **Spending** — `get_usage`
 
 **Being told somewhere else** — `list_webhooks`, `create_webhook`,
@@ -186,14 +203,56 @@ 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.
+**Secrets** — `list_secrets`, `get_secret`, `create_secret`, `set_secret`,
+`replace_secret`, `delete_secret` for the account's secret store, and
+`get_computer_secrets`, `set_computer_secrets` and `create_computer`'s `secrets`
+for which of them a computer receives. A value goes in through `create_secret`,
+`set_secret` (create the name, or replace its value if the scope holds it —
+names match ignoring ASCII case) or `replace_secret`, and never comes back out. No route answers one, and a store tool's result
+holds only the decoded documented fields (success) or the status, the `reason`
+word and a sentence of its own (refusal). It never includes the platform's
+response text, and the `Api` keeps none for these routes. The bindings carry
+only secret ids, revisions and names. A computer receives a secret as an environment variable (`env`) or as a
+file under `/run/mandala-secrets/user/files` (`file`). A set replaces the whole
+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`
+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,
+and its guest answers, a few seconds before its secrets land, so
+`wait_for_computer(until="guest")` on one also waits until they have;
+`get_computer` shows the gap as "its secrets are still on their way in".
+
+**A proxy for the browsers** — `browser_proxy: {server, bypass}` on
+`create_computer` and `update_computer` sends a Linux computer's browsers
+(Chromium, Chrome, Firefox) through a proxy; nothing else on the computer uses
+it. On `update_computer` it goes alone, replaces the setting whole, and `null`
+removes it. Which proxies are accepted is the platform's rule, and its refusal
+comes back as it is. A running computer has a change within seconds:
+`wait_for_computer(until="guest")` waits until its browsers have it, and
+`get_computer` shows the gap as "its browser proxy is still being applied".
+
+**A proxy for all outbound traffic** — `egress_proxy: {server,
+credentials_secret_id}` on `create_computer` and `update_computer` sends ALL of
+a computer's outbound TCP (`exec`, terminals, package managers and browsers
+alike) through a proxy, taken on its host so nothing inside the computer can
+opt out. The server is `http://`, `https://` or `socks5://` with an explicit
+port; there is no bypass list. `credentials_secret_id` names a secret holding
+`user:password` that is not bound to the computer and never reaches it: the
+computer's host signs in to the proxy with it. It fails closed (proxy down or
+refusing, or credentials not on the host yet: the connection fails, nothing goes
+direct), drops UDP to the internet and ICMP, and does not proxy DNS lookups.
+On `update_computer` it goes alone — beside any other field it is refused
+before a request is sent — replaces the setting whole, and `null` removes it.
+`get_computer` names the proxy and, while the host waits for its credentials,
+says "its egress proxy is waiting for credentials; connections are closed until
+they arrive".
 
 **Delegating** — `run_agent`, `run_agent_chat`, registered only when a model key is present:
 `MANDALA_MODEL_KEY` on stdio, or the caller's own `X-Model-Key` header over HTTP.
@@ -218,10 +277,10 @@ with an error listing all valid tags.
 
 | Tag | Tools |
 | --- | --- |
-| `account` | `get_account` |
+| `account` | `get_account`, `whoami`, `list_api_keys`, `list_workspaces`, `get_workspace`, `list_workspace_members` |
 | `computers` | `list_computers`, `get_computer`, `use_computer`, `wait_for_computer`, `get_desktop_url`, `list_sizes` |
-| `lifecycle` | `create_computer`, `start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`, `delete_computer`, `move_computer`, `list_moves` |
-| `input` | `screenshot`, `click`, `type_text`, `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait` |
+| `lifecycle` | `create_computer`, `start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`, `delete_computer`, `move_computer`, `list_moves`, `get_operation`, `list_operations`, `wait_for_operation` |
+| `input` | `screenshot`, `click`, `type_text`, `paste_text`, `press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`, `wait` |
 | `guest` | `exec`, `exec_poll`, `exec_kill`, `open_url`, `list_windows`, `window_action`, `read_clipboard`, `write_clipboard` |
 | `files` | `list_directory`, `read_file`, `write_file`, `wait_for_file_change` |
 | `executions` | `get_execution`, `read_execution_output` |
@@ -233,7 +292,7 @@ with an error listing all valid tags.
 | `usage` | `get_usage` |
 | `webhooks` | All webhook tools listed above |
 | `ssh` | All SSH tools listed above |
-| `secrets` | `get_computer_secrets`, `set_computer_secrets` |
+| `secrets` | `list_secrets`, `get_secret`, `create_secret`, `set_secret`, `replace_secret`, `delete_secret`, `get_computer_secrets`, `set_computer_secrets` |
 | `agent` | `run_agent`, `run_agent_chat` |
 | `activities` | `list_activities`, `get_activity`, `get_activity_results` |
 | `signals` | `read_signals` |
@@ -256,6 +315,108 @@ to both transports and the plugin forwards them. Embedders can pass
 `readOnly: true` and `tags: ['input', 'guest']` in `ServerConfig`; the server
 does not read the environment itself.
 
+### Lifecycle operations
+
+Every accepted create, clone, start, stop, suspend, restart, snapshot restore,
+resize, move and delete records a lifecycle operation, and the tool that made the call
+says its `operation_id` — in its sentence, as `(operation op_…)`, and in the
+JSON. `move_computer` carries it onto the outcome it reports. It is absent where
+the platform could not record one; the call happened either way.
+
+`get_operation` reads one, and `list_operations` pages through them newest
+first (`computer_id`, `limit`, `cursor`, `idempotency_key`; `computer_id` is not
+defaulted to the selected computer, and `idempotency_key` finds the operation a
+call sent with that key recorded, even when the call's answer was lost). `wait_for_operation` polls one until it is final: it
+answers on `succeeded`, and a `failed` one is an error carrying the platform's
+`error.code` (`start_failed`, `build_failed`, `computer_gone`, `move_failed`,
+`resize_not_applied`, `lost`, and more may be added) and its sentence.
+
+`succeeded` means the platform finished its step, not that the desktop has
+booted: `wait_for_computer` is still the wait for a desktop that answers. Most
+operations are already `succeeded` when their tool answers; a clone is
+`running` until its disk is copied, and a move until it lands. All three are
+reads, and all three stay registered when the lifecycle tools are withheld,
+since start, stop, suspend and restart record operations too.
+
+The eleven lifecycle tools (`create_computer`, `clone_computer`,
+`start_computer`, `stop_computer`, `suspend_computer`, `restart_computer`,
+`update_computer`, `move_computer`, `delete_computer`, `restore_snapshot`,
+`clone_snapshot`) take an optional `idempotency_key`. Leave it out and a fresh
+one is sent for you; a failure whose outcome is unknown names the key it went
+with. What to do next depends on who answered:
+
+- **The answer was lost** (the connection dropped after the request went out,
+  or a proxy in front of the platform gave up), or the platform answers
+  `idempotency_in_progress`: call the same tool again with the same
+  `idempotency_key`. The platform answers with the first call's result, or says
+  it is still running; the step is not done twice.
+- **The platform answered a `5xx`**, or `idempotency_outcome_unknown`: the key
+  is spent, and resending with it only answers `idempotency_outcome_unknown`.
+  The platform then keeps the call's operation `pending` for up to an hour,
+  whatever happened, while its host may be carrying it out. What to read
+  depends on the tool:
+  - `start_computer`, `stop_computer`, `suspend_computer`,
+    `delete_computer`, `move_computer` and `update_computer`: read
+    `get_computer` (and `get_operation` with the `operation_id` the error
+    named: `succeeded` means the step happened, `running` means wait on it,
+    and `pending` alone is no reason to wait). If the step did not take
+    effect, send the call again with a new key, or none.
+  - `restart_computer`, which `get_computer` cannot show: a computer reads
+    `running` before and after a reset. Read the operation instead
+    (`get_operation` with the `operation_id` the error named, or
+    `list_operations` with the key): `succeeded` means the restart happened,
+    `running` means wait on it. Anything else leaves the restart possibly
+    done, so ask the user before sending it again with a new key, or none; a
+    second restart resets the guest again.
+  - `create_computer`, `clone_computer`, `clone_snapshot` and
+    `restore_snapshot`, where a read of the computer made straight away can
+    show no effect for a build or restore that then lands, and a second one
+    is a second computer or a second overwrite: read the operation first —
+    `get_operation` with the `operation_id` the error named, or
+    `list_operations` with the key — and while it is `pending` or `running`,
+    wait (`wait_for_operation`) and do not resend with any key. Only once it
+    is final as `failed` (`error.code` `lost`, for one) or no longer found, AND
+    `get_computer` (`list_computers` after a create or a clone) shows the step
+    did not happen, send the call again with a new key, or none. If no
+    operation is found at all, read the computer again after a few minutes
+    before resending.
+- **`idempotency_key_reused`**: a different call already used that key, and
+  nothing was done. Send this one with a new key, or none.
+
+Keys last 24 hours.
+
+### Who you are, and API keys
+
+`whoami` takes no arguments and reads `GET /api/v1/whoami`: the person this
+server's API key was issued to, the account and role it acts with (the role as
+it is now), the workspace it is confined to, and the key itself — including
+`manage_keys`, whether it may manage API keys. It needs no permission and any
+role, and a suspended account can call it; the answer says so when the account
+is suspended. Behind the hosted server's OAuth sign-in, the key is the Connected
+app's (`prefix` `oauth`).
+
+`list_api_keys` lists the key holder's API keys on the account, newest first —
+never a raw key. Each carries `minted_by_key_id`: the key that minted it over
+the API, or `null` for one minted from the dashboard. Revoking a key does not
+revoke the keys it minted. It needs this server's key to have the **Manage keys**
+permission, which only a person can turn on, in the dashboard; without it the
+tool answers the platform's 403, whose sentence says exactly that. A Connected
+app's key never has the permission.
+
+**Minting and revoking keys are not offered here, on purpose.** A mint answers
+the new key in full, once, and a model's context — the conversation, the
+client's logs, whatever the transcript is shared with — is the worst place for a
+long-lived credential and one nobody can take it back from. A revoke is
+irreversible, and on a model's reading of a list it can cut off the person's CI,
+another agent, or this very session. People do both from the dashboard or with
+the `mandala api-keys` CLI.
+
+`list_workspaces`, `get_workspace` and `list_workspace_members` read the
+account's workspaces, which partition its computers. A key confined to a
+workspace lists only that one, and is refused (403) the member list, which is
+the whole account's: workspaces do not divide people. All three are reads;
+workspaces are created, renamed and deleted in the dashboard.
+
 ### Current account quota
 
 `get_account` takes no arguments and reads `GET /api/v1/account` once with the
@@ -307,6 +468,12 @@ anything and keep the hint. When a stretch of work is over, `suspend_computer` (
 suspend catches the ones a model forgets, but only after 30 minutes untouched.
 `get_usage` is what says what any of it cost.
 
+**A screenshot need not be the whole screen.** `screenshot` takes `region` (a
+crop, in the screen pixels `click` takes, before any scaling), `scale` (0 to 1),
+`format` (`png` or `jpeg`) and `quality` (JPEG, 1-100). A cropped or scaled
+picture is in its own pixel space, so the tool says alongside it how to turn a
+position in it back into screen coordinates.
+
 **Ten clicks need not be ten screenshots.** Driving the desktop one tool at a
 time — `screenshot`, `click`, `screenshot` — puts an image in the calling
 model's context for every step. `run_agent` hands a task in plain language to
@@ -709,9 +876,15 @@ listing leaves it out — every ordinary caller is asking "what can I restore".
 `list_snapshots(include_unfinished: true)` is the flag for when the question is
 about storage instead.
 
-**A 409 usually clears; a 400 never does.** A guest still booting or a busy
-guest agent answers 409. The platform's own error messages come through
-unedited, because they are written to be acted on.
+**Read the `reason`, not the status.** Whether a refusal clears on its own is
+the platform's `reason` word, and each tool's answer says what it means:
+`contention` (something was in flight) and `starting` (the guest agent is still
+inside its boot window) clear, so the same call works in a moment;
+`unavailable`, `running`, `unsupported`, `exists` and `revoked` do not. A 409
+does not mean "wait": `exec`, input and the clipboard on a stopped computer
+answer 409 `unavailable`, and `start_computer` is what fixes that, while
+`running` needs the computer stopped first. The platform's own error messages
+come through unedited, because they are written to be acted on.
 
 HTTP failures preserve their actual response status. An unsupported method on a
 known path is `MethodNotAllowedError` (405), with the received `Allow` value when
@@ -719,6 +892,25 @@ 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.
 
+`isTransient(err)` answers "is this worth sending again unchanged". A `503` is
+transient only for a GET or HEAD. Any change answered `503` may or may not have
+happened, because the platform answers a failure after the request was sent the
+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.
+
+The secret store has typed calls on `api.secrets`: `list`, `create`, `get`,
+`replace` and `delete`. Each answer is decoded strictly to the documented
+fields, and none of them carries a value:
+
+```ts
+const { secrets } = await api.secrets.list();
+const s = await api.secrets.create({ name: 'OPENAI_API_KEY', value: key });
+await api.secrets.replace(s.id, { value: next, revisionId: s.revision_id });
+```
+
 Embedders can inspect optional diagnostics on every `APIError`:
 
 ```ts
@@ -746,7 +938,7 @@ and nested chat accounting. `allow` and `wwwAuthenticate` come only from receive
 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.
+`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
@@ -895,6 +1087,69 @@ not list it, and every request is refused with a 403. Set
 is in force, so a `403` on a deployment that worked before has a line above it
 naming the fix.
 
+### Hosted, with OAuth
+
+The endpoint at `https://app.mandala.computer/mcp` is this server run with
+`--http` behind the platform's own proxy, with the platform as its OAuth 2.1
+authorization server. Nobody pastes a key:
+
+```sh
+claude mcp add --transport http mandala https://app.mandala.computer/mcp
+```
+
+Two variables make an HTTP server behave that way, and without them nothing
+changes — self-hosters keep bringing API keys:
+
+```sh
+MANDALA_MCP_RESOURCE_METADATA_URL=https://app.mandala.computer/.well-known/oauth-protected-resource/mcp \
+MANDALA_MCP_SERVICE_SECRET=… \
+MANDALA_ALLOWED_HOSTS=app.mandala.computer \
+  npx mandala-computer-mcp --http --host 127.0.0.1 --port 3000
+```
+
+In this mode `X-Forwarded-For` is believed from a loopback peer only, so the
+proxy in front must be on the same machine and must set it to the real client
+address.
+
+- **Every `/mcp` request needs a bearer**, initialize and `tools/list`
+  included. One without is answered `401` with exactly
+  `WWW-Authenticate: Bearer resource_metadata="<that URL>", scope="mcp:tools"`,
+  which is how a client finds where to authorize. `/healthz` stays open.
+- **The bearer is passed through unchanged** — an `mcpat_…` access token, or an
+  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.
+- **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
+  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
+  passes and a new one is still checked, but only one every 5 s per address;
+  the rest get `429` with `Retry-After`. The budget comes back when its minute
+  is up. A POST
+  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.
+- **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
+  work: a token that dies mid-call AFTER the stream has committed (the SDK's
+  15 s keep-alive, a progress notification or a partial result). That call
+  ends as a tool error, the session remembers the refusal, and the next
+  request on that token gets the `401` without reaching the platform.
+- **A refreshed token starts a new session.** A session is bound to the digest
+  of the bearer that opened it, and a different bearer on it is answered
+  `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.
+- `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
+  header of that name is never forwarded.
+
 ### Configuration
 
 | Variable | Meaning |
@@ -909,8 +1164,10 @@ naming the fix.
 | `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. |
+| `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 and the two tool filters has a flag as well, and a flag overrides
+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`,
 `--allowed-hosts`, `--allowed-origins`, `--no-lifecycle`, local `--profile`, plus `--help` and
 `--version`. `--key` exists for a caller launching several servers under

package/dist/api.d.ts

@@ -1,13 +1,44 @@
 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. */
 export declare const MODEL_KEY_HEADER = "X-Model-Key";
+/**
+ * The header every lifecycle call carries so that sending it again cannot do
+ * it twice (platform OPL-5127). The platform records a call that carries one
+ * before carrying it out, and for 24 hours answers the same key with the same
+ * request from that record instead of doing the call again: `409` with `code:
+ * "idempotency_in_progress"` while it runs, the original answer once it has
+ * finished. A different request under the same key is a `422`.
+ */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/** The platform's rule for a key: 1 to 255 characters, each printable ASCII other than a space. */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/**
+ * The key for ONE lifecycle tool call — the caller's, already checked by the
+ * tool's input schema, or a fresh random one — made once, before the request,
+ * so that whatever re-sends this call re-sends the same key.
+ */
+export declare const idempotencyKeyFor: (given?: string) => string;
+/** The header that carries it. */
+export declare const idempotencyHeaders: (key: string) => Record<string, string>;
+/**
+ * Proof, to the platform, that a request comes through the hosted MCP service
+ * (OPL-4982). The platform takes an OAuth access token only alongside it, so a
+ * token cannot be replayed at the API directly by the app it was issued to.
+ *
+ * Only this server's own value is ever sent. A header of this name arriving
+ * from anywhere else — a caller, or a per-call header set — is dropped in
+ * `#fetch`, so a client cannot supply the secret or learn anything by trying.
+ */
+export declare const SERVICE_HEADER = "X-Mandala-MCP-Service";
 export type RequestOptions = {
     query?: Record<string, string | number | boolean | undefined>;
     body?: unknown;
     /** Raw bytes as the request body, for the file upload. Mutually exclusive with `body`. */
     raw?: Uint8Array;
-    /** Extra headers for this call only — currently just the model key. */
+    /** Extra headers for this call only: the model key, and a lifecycle call's Idempotency-Key. */
     headers?: Record<string, string>;
     signal?: AbortSignal;
 };
@@ -53,6 +84,12 @@ export type Bytes = {
      * differently" and "there is no offset that will work on this file".
      */
     unrangeable: boolean;
+    /**
+     * `X-GC-Frame`, when the platform labelled what it served: `suspended` is a
+     * screenshot answered with the saved frame of a suspended computer rather
+     * than a capture of its screen.
+     */
+    frame?: string;
 };
 /**
  * The longest foreground guest exec waits 600 seconds before it answers.
@@ -114,10 +151,32 @@ export type SSEEvent = {
  * result goes into a model's context and from there into transcripts, and an
  * API key is every computer on the account, forever.
  */
+/**
+ * What an embedding transport adds to every request one client makes.
+ *
+ * Both halves exist for the hosted install (OPL-4982), where this server stands
+ * between an OAuth client and the platform: the platform takes an access token
+ * only from a caller that also proves it is this service, and a refused token
+ * has to reach the MCP client as an HTTP 401 rather than as a tool error.
+ */
+export type ApiOptions = {
+    /**
+     * Sent as {@link SERVICE_HEADER} with every request to the configured base
+     * URL, and nowhere else. Never logged and never put on an error, like the
+     * key itself.
+     */
+    serviceSecret?: string;
+    /**
+     * Called when the platform refuses THE BEARER: a 401 carrying a `Bearer`
+     * challenge. A 401 without one is a model provider refusing a model key,
+     * which says nothing about this client's credential, and is not reported.
+     */
+    onBearerRefused?: () => void;
+};
 export declare class Api {
     #private;
     readonly baseUrl: string;
-    constructor(apiKey: string, baseUrl?: string, signal?: AbortSignal);
+    constructor(apiKey: string, baseUrl?: string, signal?: AbortSignal, options?: ApiOptions);
     /**
      * This same client, with every request bound to one tool call's cancellation.
      *
@@ -182,6 +241,18 @@ export declare class Api {
     }>;
     /** For the two routes whose body is not JSON: the screenshot and the download. */
     bytes(method: string, path: string, opts?: RequestOptions, maxBytes?: number | ((contentType: string) => number)): Promise<Bytes>;
+    /**
+     * The account's secret store, `GET|POST secrets` and `GET|PUT|DELETE
+     * secrets/:id`, as five typed calls.
+     *
+     * Typed, and decoded strictly, because a value goes IN here and the caller
+     * must be able to rely on nothing coming back: every answer is reduced to the
+     * documented fields before it is returned, so no answer can hand a value on.
+     * A malformed answer is a {@link MandalaError}; for a change it says the
+     * change may have been made. Bound to this client, so
+     * `api.with(signal).secrets` carries the signal.
+     */
+    get secrets(): SecretStore;
     /**
      * The agent route, which answers with a stream of steps rather than a result.
      *

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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"}