@wardby/cli 0.7.0 → 0.8.0

package/docs/mcp-servers.md

@@ -0,0 +1,254 @@
+# Remote MCP servers for native and coding agents
+
+A native, Claude Code or Codex agent can call the tools of a remote MCP server. You register the
+server once (its HTTPS URL plus your brokered secrets), Wardby saves the
+server's tool list, and you attach an allowlisted subset of those tools to
+an agent. A native agent sees each tool as `<server name>__<tool name>`; coding agents see
+them as described in [Coding agents](#coding-agents).
+
+`WARDBY_MCP_SERVERS` decides who may register servers: `owners` (the
+default, anyone), `admins` (registering, updating and refreshing need
+`hosts:admin`) or `off` (every tool below is refused except
+`detach_mcp_server` and `delete_mcp_server`, so cleanup stays possible, and
+attached servers' tools are left out of runs).
+
+The tools below need the `tools:write` scope to change servers and
+attachments and `agents:read` to list and get them.
+
+## Tools
+
+| Tool                  | Who                   | What it does                                                                                                       |
+| --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `register_mcp_server` | anyone (see mode)     | Registers a server from `name`, `url` (e.g. `https://mcp.example.com/mcp`) and `secretNames`; saves its tool list. |
+| `update_mcp_server`   | the server's owner    | Changes the URL or secret names, saves a fresh tool list and returns what changed.                                 |
+| `refresh_mcp_server`  | the server's owner    | Saves a fresh tool list straight away; returns added, removed and changed tools and the agents left missing tools. |
+| `list_mcp_servers`    | anyone                | Your servers and those shared with you: id, name, host, tool count, saved-at, `yours`.                             |
+| `get_mcp_server`      | owner, or `read`+     | One server with its full saved tool list (secret names and URL only for the owner).                                |
+| `delete_mcp_server`   | the server's owner    | Deletes a server and detaches it from every agent. Works when the mode is `off`.                                   |
+| `attach_mcp_server`   | agent's owner; `use`+ | Lets a native or coding agent call the named tools (`allowedTools`, exact names) with an optional `callTimeoutMs`. |
+| `detach_mcp_server`   | the agent's owner     | Removes a server's tools from an agent. Works when the mode is `off`.                                              |
+
+`get_agent` shows each attached server under `mcpServers`: the server's `serverId`
+and name, the allowed tools, `callTimeoutMs`, the exposed tool names and any allowed tools the server no
+longer lists (`missingTools`). Anyone with read access on the agent sees this.
+It never includes URLs, secret names or values, or saved tool lists.
+
+## Create a secret for the server
+
+Servers are authenticated with [brokered secrets](tool-secrets.md): Wardby adds
+the value to every request to the server's host and nobody, including the
+model, can read it back. Create the secret, then set its broker config with
+`set_secret_broker` so it is limited to the server's host. For a bearer token:
+
+```json
+{
+  "hosts": ["mcp.example.com"],
+  "placement": { "kind": "header", "name": "Authorization", "format": "Bearer {value}" }
+}
+```
+
+A server that wants two headers needs two secrets, each with its own
+placement (for example `X-Api-Key` with `format: "{value}"`, and
+`X-Workspace` the same way); name both in `secretNames` (at most 8 names, each up to 1024 characters). The URL itself can't
+carry credentials: a username, password or fragment is refused.
+
+## Register, read the tool list, attach
+
+1. `register_mcp_server` with `name` (1-32 characters: lower-case letters,
+   digits, `_` or `-`), `url` (`https://mcp.example.com/mcp`: HTTPS only,
+   default port) and `secretNames`. Wardby calls the server's `tools/list`
+   and saves the result. A secret that is missing, not brokered, or not
+   brokered to the URL's host is refused.
+2. `get_mcp_server` shows the saved tools: name, description, input schema and
+   the server's annotations.
+3. `attach_mcp_server` with the agent, the server and `allowedTools`: exact
+   tool names from the saved list, at least one, no wildcards. Attaching
+   replaces the agent's earlier allowlist and time limit for that server.
+   Native, Claude Code and Codex agents can attach a server (see [Coding agents](#coding-agents)).
+
+The agent sees each tool as `<server name>__<tool name>`, with any character
+outside letters, digits, `_` and `-` changed to `_`; the result must be at
+most 64 characters. The description starts with `From MCP server <server name>: `.
+Attaching is refused if the name clashes with another tool on the agent
+(attached, another MCP tool, or a built-in name).
+
+## Coding agents
+
+A Claude Code or Codex agent can use attached servers too. Attach them the same way, with
+`attach_mcp_server`. The tools reach the run like this:
+
+1. The worker calls the coding proxy's `/mcp` route with a per-run MCP token (`rmt_…`, in the
+   worker's `WARDBY_MCP_TOKEN`). Workers still reach only the proxy.
+2. The proxy forwards the request to the native gateway's `/coding-mcp` route. The proxy never sees
+   a server's URL or secrets. The gateway checks the token again, checks the live attachment and
+   runs the call, and removes secret values from the result before it leaves.
+
+The token belongs to one run: it works only on `/mcp`, only while the run is active and before its
+deadline, and only its hash is stored.
+
+- **Claude Code agents** see each tool as `mcp__wardby_mcp__<server name>__<tool name>` and may use
+  any allowed tool. The 64-character limit on `<server name>__<tool name>` is the same as for
+  native agents; the prefix adds no other limit.
+- **Codex agents may use only tools the server marks `readOnlyHint: true`.** Wardby enforces this
+  when you attach (an allowlist with another tool is refused), when a run loads its tools (a tool
+  whose saved annotations no longer say read-only, for example after `refresh_mcp_server`, is left
+  out) and on every call. The reason is that repository code running in a Codex run can read the
+  run's MCP token, so only tools that don't change anything are safe to give it. `readOnlyHint` is
+  the server's own claim, which Wardby can't verify. The allowlist stays your control: allow only
+  tools you trust to be read-only.
+
+  A run follows the provider it was started with, even if the agent's provider changes before the
+  run launches. A coding agent with no coding profile is treated as Codex when you attach.
+
+- **Switching an agent to Codex.** When `update_agent` makes an agent a Codex agent (changing
+  `codingProfile.provider` to `codex`, or making a native agent a coding agent, which uses Codex by
+  default) and some of its attached tools aren't marked read-only, the change still goes ahead and
+  the result's `warnings` names those tools: "These MCP tools aren't read-only and won't be
+  available to Codex runs: …". They stay attached but Codex runs don't get them. Detach them, or
+  re-attach the server with only read-only tools, to remove the warning's cause.
+- **Call limit.** A run may make `WARDBY_MCP_MAX_CALLS_PER_RUN` calls (default `100`). Every call
+  counts, whatever its outcome. Past the limit a call returns
+  [`mcp_call_limit`](../help/errors/mcp-call-limit.md); the run goes on.
+- **Proxy setting.** The coding proxy needs `WARDBY_MCP_GATEWAY_URL`, the native gateway's base URL
+  (the kind and GKE manifests set it). Without it `/mcp` answers `503` with
+  [`mcp_unavailable`](../help/errors/mcp-unavailable.md) and coding agents get no MCP tools. See
+  [Remote MCP servers](security-deployment.md#remote-mcp-servers) for the variables.
+- **Worker images.** MCP for coding agents needs this release's Claude worker image and a new Codex
+  driver image. An older image ignores the token and the agent gets no MCP tools; the run does not
+  fail. Update the images together with the server.
+- **Repository configuration.** A repository's own MCP configuration (such as `.mcp.json`) is still
+  never loaded; the attached servers are the only MCP tools a coding run has.
+- **Codex models that use tool search** load MCP tools on demand: Codex sends a client-side
+  `tool_search` tool and adds the matching MCP tools to the conversation when the model searches.
+  This needs this release's coding proxy; an older proxy refuses those models' requests with
+  `openai_tool_not_allowed:tool_search`, MCP or not.
+
+Time limits and the other rules in this guide apply to coding agents too. See
+[Coding worker isolation](coding-worker-isolation.md#remote-mcp-tools) for the security notes.
+
+## Time limits
+
+Each call has `callTimeoutMs` (default `30000`, set on `attach_mcp_server`).
+It must be at least `1000` and can't exceed `WARDBY_TOOL_MAX_TIMEOUT_MS`; a call runs with the lower of
+the two, and never past the run's own deadline. `stop_run` aborts a call in
+flight. A call that runs out of time returns `mcp_call_timeout` to the model
+and the run goes on.
+
+A coding agent's calls have one more limit: the coding proxy gives up on a forwarded call after 5
+minutes, whatever `WARDBY_TOOL_MAX_TIMEOUT_MS` and `callTimeoutMs` say. The call then fails with
+[`mcp_unavailable`](../help/errors/mcp-unavailable.md) (`502`), the gateway stops the call, and it
+still counts against the run's call limit. A run that has been stopped or cancelled can't start new
+calls: its token is refused with `401`.
+
+## Refreshing and changes
+
+`refresh_mcp_server` (and `update_mcp_server`) fetch the tool list again and
+apply it at once. The reply lists tools added, removed and changed
+(description or schema). A removed tool that an agent allows is dropped from
+that agent's runs and shows under `missingTools` in `get_agent`; nothing
+needs re-attaching if the server brings it back and you refresh again. A
+tool the server newly adds is not available to any agent until you attach it.
+
+## What a call does
+
+Each call opens its own session: `initialize`, `notifications/initialized`,
+`tools/call`, then a `DELETE` to end it. Because every call gets a fresh
+session, a server that keeps state between calls in one session won't see
+that state on the next call. Wardby checks on every call that the tool is
+still attached and still in the saved list, and that the agent's owner still
+owns the server or holds `use` on it; the call uses the server's current URL
+and secrets. Arguments that aren't a JSON object return `invalid_arguments`
+without calling the server. Text returned to the model is cut at 100,000
+characters, with a note.
+
+Wardby answers none of a server's own requests (sampling, elicitation,
+roots). Notifications in a reply are ignored. A reply that carries only a
+request from the server, and no answer to Wardby's request, fails the call
+with `mcp_server_error`.
+
+One log line per call records the run id, agent id, server id, tool,
+outcome, duration and result size, never the arguments, the response or the
+URL. Secret values are removed from results, errors and logs.
+
+## Not supported
+
+stdio servers, OAuth to a server (use a header secret), MCP resources,
+prompts and sampling.
+
+## Trust
+
+A server's results are untrusted input to the model, like any tool result. The
+allowlist is the control: attach only the tools an agent needs. A server's
+annotations (read-only, destructive and so on) are hints from the server, not
+something Wardby can verify. The one place Wardby acts on a hint is Codex coding
+agents, which may use only tools marked `readOnlyHint: true` (see
+[Coding agents](#coding-agents)).
+
+## Sharing a server
+
+Share a server you own with `grant_access` (`resourceType: "mcp_server"`, a
+principal or `everyone`, level `read`, `use` or `write`; `everyone` is capped
+at `use`). `read` lets the grantee see the server and its tool list; `use`
+also lets them attach it to their own agents. The server's tools then run with
+your brokered secrets, so grant `use` only to people you trust with them.
+`write` allows nothing beyond `use`: only the owner updates, refreshes,
+deletes or re-grants a server.
+
+Sharing uses `grant_access` and `revoke_access`, which need the
+`agents:write` scope; registering and attaching need `tools:write`.
+
+An agent may use a server only while its owner owns the server or holds `use`
+(or `write`) on it. `revoke_access`, and `grant_access` lowering a grant to
+`read` (for a principal, or `everyone` from `use` to `read`), detach the
+server at once from every agent whose owner can no longer use it; the reply
+counts them under `attachmentsRemoved`. Your own agents, and agents whose
+owner still holds `use` through another grant, keep it. Runs already going
+lose the tools on their next call, which returns `mcp_tool_not_allowed`.
+
+`delete_mcp_server` removes the server's tools from every agent attached to
+it, including other owners' agents that use it through a grant, and removes
+its grants.
+
+When the server's secrets can't be loaded (a secret was deleted, or its
+broker config no longer lists the server's host), the owner's own agents get
+an `mcp_server_error` that names the secret. An agent using the server through
+a grant gets only "The MCP server's credentials can't be used; ask its owner
+to check it.", never the owner's secret names.
+
+When a secret exists but the Wardby process making the call can't decrypt its
+stored value, the call returns `mcp_server_credentials_unavailable`, and
+`register_mcp_server`, `update_mcp_server` and `refresh_mcp_server` fail with
+it as an HTTP 500 error. Every process that decrypts secrets (control plane,
+scheduler, native gateway) must use the same `SECRET_APP_KEY`; if the key
+changed, set the secret again. The owner's agents get that advice; an agent
+using the server through a grant gets the generic message above. Each failure
+also writes one operator `warn` log line with
+`reason: "mcp_secret_decrypt_failed"`, the server and the secret name.
+
+An attachment acts with the server owner's secrets. When `make_owner` gives an
+agent a new owner, servers the new owner neither owns nor holds `use` on are
+detached and listed under `bindingsRemoved` with `kind: "mcp_server"`.
+`wardby grants adopt-public` and `wardby grants prune-bindings` remove them the
+same way. An agent that holds an MCP server can't be made writable by
+everyone.
+
+## Troubleshooting
+
+A failed call returns `{"error": "<code>", "message": "..."}` to the model;
+the run goes on.
+
+| Code                                                                                         | Meaning                                                               |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [`mcp_servers_off`](../help/errors/mcp-servers-off.md)                                       | `WARDBY_MCP_SERVERS=off`.                                             |
+| [`mcp_server_unreachable`](../help/errors/mcp-server-unreachable.md)                         | Wardby couldn't connect to the server.                                |
+| [`mcp_server_auth_failed`](../help/errors/mcp-server-auth-failed.md)                         | The server answered 401 or 403.                                       |
+| [`mcp_server_credentials_unavailable`](../help/errors/mcp-server-credentials-unavailable.md) | A secret can't be decrypted: check every process's `SECRET_APP_KEY`.  |
+| [`mcp_server_error`](../help/errors/mcp-server-error.md)                                     | Another HTTP error, a malformed reply, or the tool reported an error. |
+| [`mcp_tool_not_allowed`](../help/errors/mcp-tool-not-allowed.md)                             | Detached, off the allowlist, or the owner lost `use` on the server.   |
+| [`mcp_tool_removed`](../help/errors/mcp-tool-removed.md)                                     | The server no longer lists the tool.                                  |
+| [`mcp_call_timeout`](../help/errors/mcp-call-timeout.md)                                     | The call hit its time limit or the run was stopped.                   |
+| [`mcp_call_limit`](../help/errors/mcp-call-limit.md)                                         | A coding run made more calls than `WARDBY_MCP_MAX_CALLS_PER_RUN`.     |
+| [`mcp_unavailable`](../help/errors/mcp-unavailable.md)                                       | The coding proxy has no gateway to forward MCP calls to.              |
+
+See also [Secrets and tools](tool-secrets.md) and
+[Remote MCP servers](security-deployment.md#remote-mcp-servers).

package/docs/native-sandbox.md

@@ -1,6 +1,6 @@
 # Native sandbox
 
-> **Requires Wardby 0.5.4 or later.**
+> **Requires Wardby 0.6.0 or later.**
 
 By default a native agent runs inside the Wardby server process: its turn loop
 and any user tool code you attach execute next to the database connection, the
@@ -78,6 +78,13 @@ container to it under the alias `wardby-native-gateway`, and starts the worker
 on it. When the run ends the worker, the network, and the gateway's membership
 of it are removed.
 
+The gateway also serves coding agents' remote MCP tools: the coding proxy
+forwards a coding run's `/mcp` requests to the gateway's HTTP port, on the
+`/coding-mcp` route, where the run's MCP token is checked again. Set
+`WARDBY_MCP_GATEWAY_URL` on the coding proxy to the gateway's base URL
+([details](security-deployment.md#remote-mcp-servers)). The proxy holds no
+gateway credentials, and each route authenticates separately.
+
 The gateway is stateless: all state is in Postgres. You can restart it while
 runs are in flight; workers retry their calls. It must not be given the Docker
 socket, because workers can reach it.
@@ -131,13 +138,15 @@ The gateway is the same Wardby build as the server, started with the
 `native-gateway` command. It needs the server's database, LLM, secrets, and
 integration settings, and **no Docker access**.
 
-| Gateway variable        | Purpose                                                                                                                                                                                                                                                    |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `NATIVE_GATEWAY_LISTEN` | `host:port` to listen on. Default `0.0.0.0:8790`.                                                                                                                                                                                                          |
-| `DATABASE_URL`          | The same database the server uses. With `DATABASE_AUTH=rds-iam` the gateway also needs `DATABASE_AUTH`, `AWS_REGION` (or `DATABASE_AWS_REGION`) and the CA bundle file named by `sslrootcert` ([details](security-deployment.md#database-authentication)). |
-| LLM provider keys       | The same provider settings as the server (for example `OPENAI_API_KEY`).                                                                                                                                                                                   |
-| `SECRET_APP_KEY`        | Same value as the server, so tools can read their bound secrets or send brokered ones ([details](tool-secrets.md)).                                                                                                                                        |
-| Integration settings    | The same repository-host and issue-tracker settings as the server.                                                                                                                                                                                         |
+| Gateway variable               | Purpose                                                                                                                                                                                                                                                    |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NATIVE_GATEWAY_LISTEN`        | `host:port` to listen on. Default `0.0.0.0:8790`.                                                                                                                                                                                                          |
+| `DATABASE_URL`                 | The same database the server uses. With `DATABASE_AUTH=rds-iam` the gateway also needs `DATABASE_AUTH`, `AWS_REGION` (or `DATABASE_AWS_REGION`) and the CA bundle file named by `sslrootcert` ([details](security-deployment.md#database-authentication)). |
+| LLM provider keys              | The same provider settings as the server (for example `OPENAI_API_KEY`).                                                                                                                                                                                   |
+| `SECRET_APP_KEY`               | Same value as the server, so tools can read their bound secrets or send brokered ones ([details](tool-secrets.md)).                                                                                                                                        |
+| Integration settings           | The same repository-host and issue-tracker settings as the server.                                                                                                                                                                                         |
+| `WARDBY_TOOL_MAX_TIMEOUT_MS`   | Same value as the server, if you set it: the longest time limit a tool may use ([details](security-deployment.md#tool-time-limits)).                                                                                                                       |
+| `WARDBY_MCP_MAX_CALLS_PER_RUN` | Same value as the server, if you set it: the most remote MCP tool calls one coding run may make (default `100`; [details](security-deployment.md#remote-mcp-servers)).                                                                                     |
 
 For local development, the repository ships a compose overlay
 (`deploy/local/docker-compose.native-sandbox.yml`) that runs the gateway next to
@@ -549,6 +558,12 @@ set on the gateway, not the server.
 - A sandbox run has a maximum lifetime of 60 minutes. Past it the worker is
   stopped and the run fails with `native_sandbox_deadline_exceeded`.
 - The agent's own turn and budget limits still apply as for any native agent.
+- Each tool call has the tool's own time limit (`timeoutMs`, default 10
+  seconds, capped by `WARDBY_TOOL_MAX_TIMEOUT_MS`). The worker enforces it; the
+  gateway gives each host call the limit plus 20 seconds, never past the run's
+  deadline. Update the worker image with the server: an older image refuses a
+  run whose agent has a tool with `timeoutMs`
+  ([details](security-deployment.md#tool-time-limits)).
 
 ## Stopping a run
 
@@ -558,7 +573,8 @@ run whether it is still waiting for a worker or already running:
 1. The run is recorded `cancelled` with the caller's reason, unless it already
    finished (the first terminal state wins; a finished run is not changed).
 2. Its gateway session ends. The worker's next call (a model turn, a tool, or
-   its result) is refused, and the worker exits on its own.
+   its result) is refused, and the worker exits on its own. A tool's host call
+   still running on the gateway is aborted within a few seconds.
 3. A worker still running 5 seconds later is killed. Either way the worker is
    then removed; a worker claimed from the warm pool is discarded with its pool
    row and never returned to the pool.

package/docs/security-deployment.md

@@ -79,15 +79,16 @@ Scopes and roles do different jobs:
 - **Roles authorize.** A user has a set of roles. With no roles, the user is a
   member:
 
-| Role               | Grants                                                                                                 |
-| ------------------ | ------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage` |
-| `package-approver` | `packages:approve`                                                                                     |
-| `service-manager`  | `services:manage`                                                                                      |
-| `model-manager`    | `models:admin`                                                                                         |
-| (none)             | nothing privileged; every other scope works as the token allows                                        |
+| Role               | Grants                                                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin` |
+| `package-approver` | `packages:approve`                                                                                                    |
+| `service-manager`  | `services:manage`                                                                                                     |
+| `model-manager`    | `models:admin`                                                                                                        |
+| `host-manager`     | `hosts:admin`                                                                                                         |
+| (none)             | nothing privileged; every other scope works as the token allows                                                       |
 
-Eight operations are privileged:
+Nine kinds of operation are privileged:
 
 - `make_owner`, which reassigns any agent's owner, including another
   principal's private agent (see [Sharing agents](#sharing-agents) for what
@@ -107,7 +108,15 @@ Eight operations are privileged:
   [viewer-api.md](viewer-api.md));
 - reading low-power state and scaling the coding proxy and native gateway to
   zero now (`power_status`, `power_sleep`; see
-  [Low-power mode](getting-started-gke.md#low-power-mode)).
+  [Low-power mode](getting-started-gke.md#low-power-mode));
+- registering, approving, testing and deleting host providers
+  (`register_host_provider`, `approve_host_provider_tools`,
+  `test_host_provider`, `delete_host_provider`; reading one with
+  `get_host_provider` needs the same permission). Approved tools run on the
+  control plane with the provider's credentials, so grant `hosts:admin` like
+  `agents:admin`. Any host manager can read and re-register any provider,
+  including its tool code, whoever owns the tools; see
+  [host-providers.md](host-providers.md).
 
 Each needs **both** its scope on the token **and** a role that grants that
 permission:
@@ -119,13 +128,16 @@ permission:
 - The admin viewer API needs `admin:view`, which only the `admin` role grants.
 - `power_status` and `power_sleep` need `power:manage`, which only the `admin`
   role grants.
+- Host provider tools need `hosts:admin`, which the `admin` and `host-manager`
+  roles grant.
 
 In practice:
 
-- an `admin` can do all eight;
+- an `admin` can do all of them;
 - a `package-approver` can approve packages only;
 - a `service-manager` can change the service catalog only;
 - a `model-manager` can change the model catalog only;
+- a `host-manager` can manage host providers only;
 - a member can do none of them.
 
 Callers who fail the check get `403`:
@@ -312,7 +324,7 @@ someone else's agent (it can adopt the agent first). An HTTP user whose
 subject equals `LOCAL_PRINCIPAL` is not the operator. **Admins** get no
 implicit access to others' agents: they can `list_access` any agent (incident
 response) and reassign one with `make_owner`, which removes bindings the new
-owner doesn't own, suspends tool capabilities the new owner never granted,
+owner doesn't own (secrets, datastores and MCP server attachments), suspends tool capabilities the new owner never granted,
 cuts sub-agent edges the new owner can't delegate, and, between two owners,
 resets every grant. Adopting an owner-less agent keeps its grants but lowers
 an everyone grant to `read` unless `keepEveryoneExecute` is set.
@@ -347,7 +359,7 @@ without their tools' capabilities. Operator runbook:
    printed for review, with the `attach_tool` call that re-grants any
    capabilities it had. The subject must already exist.
 4. `wardby grants prune-bindings` removes, and prints, every remaining
-   binding of one owner's secret or datastore to another owner's agent
+   binding of one owner's secret, datastore or MCP server to another owner's agent
    (already inert).
 5. `wardby grants migration-report > after.txt`.
 
@@ -380,6 +392,15 @@ Trust assumptions:
   owner enabled `allowWebhookTaskOverride`; the owner controls the tools,
   secrets and repository. A repository is a binding: only the owner (or an
   admin's explicit approval) sets it, never a `write`-grantee.
+- **A task can steer a coding agent to any repository on its list.** A caller
+  who may pass `repository` (for `trigger_agent`, the owner, or anyone when
+  `allowWebhookTaskOverride` is on; for a webhook, whoever created it, and only
+  when `allowWebhookTaskOverride` is on), and a lead that delegates to the
+  agent, can pick any listed repository, and the agent's one toolchain,
+  services and package allowlist apply to all of them. Keep the list small, and keep
+  repositories with different trust levels on separate agents. Refusals never
+  repeat the requested value, and a lead sees a sub-agent's list only when it
+  has the same owner or may choose (execute access and the opt-in).
 - **Owner-less agents never hold a repository**, even admin-approved: there is
   no owner whose GitHub access can be checked. Assign an owner first.
 - **Checked where it's used.** Every coding run (before its workspace is
@@ -522,22 +543,22 @@ records. Delete them (see pruning above) if you want the rollback to be final.
 
 ## Resource and networking limits
 
-| Surface                        | Limit                                             |
-| ------------------------------ | ------------------------------------------------- |
-| MCP/webhook bodies             | 1 MiB raw bytes                                   |
-| MCP tool-call arguments        | 100,000 array elements and object members         |
-| Auth bodies                    | 64 KiB raw bytes                                  |
-| Request completion / headers   | 15 seconds / 10 seconds                           |
-| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds              |
-| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects, 8 seconds |
-| Bridge input / output          | 1 MiB / 12 MiB                                    |
-| Parser input / console payload | 256 KiB / 16 KiB                                  |
-| HTML links extracted           | 1000, with incremental result-byte accounting     |
-| Random bytes                   | 65,536 bytes                                      |
-| Host calls                     | 256 per invocation, at most 8 pending             |
-| Datastore value / keys listed  | 1 MiB / 1000                                      |
-| Datastore key / secret name    | 1024 bytes                                        |
-| New secret plaintext           | 64 KiB                                            |
+| Surface                        | Limit                                            |
+| ------------------------------ | ------------------------------------------------ |
+| MCP/webhook bodies             | 1 MiB raw bytes                                  |
+| MCP tool-call arguments        | 100,000 array elements and object members        |
+| Auth bodies                    | 64 KiB raw bytes                                 |
+| Request completion / headers   | 15 seconds / 10 seconds                          |
+| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds (see below) |
+| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects           |
+| Bridge input / output          | 1 MiB / 12 MiB                                   |
+| Parser input / console payload | 256 KiB / 16 KiB                                 |
+| HTML links extracted           | 1000, with incremental result-byte accounting    |
+| Random bytes                   | 65,536 bytes                                     |
+| Host calls                     | 256 per invocation, at most 8 pending            |
+| Datastore value / keys listed  | 1 MiB / 1000                                     |
+| Datastore key / secret name    | 1024 bytes                                       |
+| New secret plaintext           | 64 KiB                                           |
 
 Oversized or malformed input fails explicitly. Existing oversized datastore
 values/keys and secret ciphertext fail instead of entering Node allocations.
@@ -551,8 +572,9 @@ call arguments against its `paramsZod`, runs in a fresh QuickJS runtime with the
 heap, stack, and time limits above. One that hits a limit fails that tool call
 only: the model receives a `validation_failed` or sandbox error result and the
 run continues. The invocation runs on the thread of the process that hosts the
-run (the server, or the run's worker with the native sandbox), so a call that
-runs to the time limit holds that thread for up to 10 seconds.
+run (the server, or the run's worker with the native sandbox). Code that keeps
+the thread busy is also stopped by the instruction budget, so a long time limit
+mostly lets a call wait on slow requests.
 
 For this release only, a custom tool's `paramsZod` is compiled with Zod 4's
 built-in Zod 3 API (`zod/v3`) so that existing tools keep working; see
@@ -578,7 +600,7 @@ The network layer cannot back this up for the control plane on GKE, because
 Workload Identity needs the metadata server.
 Sandbox code can explicitly log secrets it has been given; log size limits do
 not provide automatic redaction. Keep tool-authoring privileges restricted.
-Public/non-owner tool listings expose only id/name/description; owners retain
+Public/non-owner tool listings expose only id/name/description/timeoutMs; owners retain
 their source and schema. Private agents are indistinguishable from missing IDs.
 
 Cancellation stops bridge delivery, sleep timers, and in-flight network work.
@@ -591,6 +613,57 @@ bound connection pools and concurrent invocations, and review a cancellable
 database adapter or isolated worker if strict immediate termination is required.
 Do not claim these per-invocation caps establish a whole-process memory ceiling.
 
+### Tool time limits
+
+A tool call has 10 seconds unless the tool sets its own `timeoutMs`
+(`create_tool`, `update_tool`, `dry_run_tool`, `wardby tool create|update
+--timeout-ms`, or `timeoutMs` in a bundle's `config/tools.json`). The limit
+covers the whole call: each `fetch` may run until it, and a timer can't be set
+for longer. A call never outlasts its run: stopping the run aborts it, and a
+sandboxed run's deadline cuts it off.
+
+| Variable                     | Default  | Meaning                                                                                                                                                                                                                                 |
+| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_TOOL_MAX_TIMEOUT_MS` | `300000` | The longest `timeoutMs` a tool may set, in milliseconds (at least `10000`). A larger value is refused when the tool is saved. A run uses the lower of the tool's `timeoutMs` and this value, so lowering it also covers existing tools. |
+
+Set it on every process that runs tools or serves the native sandbox gateway:
+`wardby serve`, `wardby scheduler` and the gateway. An invalid value stops
+start-up. On the native sandbox the gateway gives each of a tool's host calls
+its limit plus 20 seconds, never past the run's deadline. A long limit lets one
+call hold its run (and a sandboxed run's worker) for longer, so raise the
+ceiling only as far as your tools need.
+
+**Upgrading:** the release adds the nullable `Tool.timeoutMs` and
+`HostProviderOperation.timeoutMs` columns; apply the migration with
+`prisma migrate deploy` as with any upgrade. A sandboxed run passes a tool's
+`timeoutMs` to its worker, so update the native worker image together with the
+server: an older image refuses the run of an agent that has a tool with
+`timeoutMs`. Tools without `timeoutMs` run on either image.
+
+### Remote MCP servers
+
+Owners can register a remote MCP server (Streamable HTTP, HTTPS only) and attach
+an allowlisted subset of its tools to a native agent, which then calls them
+through Wardby's control plane. `WARDBY_MCP_SERVERS` decides who may register
+servers: `owners` (the default), `admins` (only `hosts:admin` holders), or `off`
+to disable the feature. An agent can use a server only while its owner owns it or
+holds `use` on it through a grant; revoking or lowering that grant detaches it. Secret values for a server are never sent to the model,
+stored in run records, or returned by Wardby's MCP tools. See [Remote MCP servers](mcp-servers.md) for the
+full guide.
+
+Claude Code and Codex agents can use attached servers too. Their workers reach
+the tools only through the coding proxy's `/mcp` route, which forwards to the
+native sandbox gateway's `/coding-mcp` route; the proxy never sees a server's URL
+or secrets. Codex agents get only tools the server marks `readOnlyHint: true`
+(see [Coding worker isolation](coding-worker-isolation.md#remote-mcp-tools)).
+
+| Variable                       | Read by                                                                                                  | Default       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_MCP_SERVERS`           | the server processes and the gateway                                                                     | `owners`      | Who may register remote MCP servers: `owners` (the default: owners may register servers), `admins` (registering, updating and refreshing a server needs `hosts:admin`), or `off` (every MCP-server tool except `detach_mcp_server` and `delete_mcp_server` is refused with a 403 that names this variable, and attached servers' tools are left out of runs). Any other value stops start-up.                                                                                                                 |
+| `WARDBY_MCP_MAX_CALLS_PER_RUN` | the native gateway, which counts calls; also checked at start-up by the server processes and the gateway | `100`         | The most remote MCP tool calls one coding run (Claude Code or Codex) may make. Every call to one of the run's MCP tools counts, whatever its outcome; a call past the limit is refused with the [`mcp_call_limit`](../help/errors/mcp-call-limit.md) error, which the agent sees as the tool's result. A positive whole number; any other value stops start-up.                                                                                                                                               |
+| `WARDBY_MCP_GATEWAY_URL`       | the coding proxy                                                                                         | unset         | The native sandbox gateway's base URL, for example `http://<gateway host>:<port>`. The proxy's `/mcp` route, which a coding run's worker uses as its MCP server, forwards each request to the gateway's `/coding-mcp` route; the proxy never sees an MCP server's URL or credentials. Unset, coding runs get no MCP tools: `/mcp` answers `503` with [`mcp_unavailable`](../help/errors/mcp-unavailable.md). An `http` or `https` URL without credentials, query or fragment; any other value stops start-up. |
+| `WARDBY_MCP_TOKEN`             | the coding worker                                                                                        | set by Wardby | Don't set it. Wardby gives each coding run whose agent has MCP tools its own MCP token in this worker variable. It is valid only for the proxy's `/mcp` route, and only while the run is active and before its deadline; only its hash is stored, and it is never logged.                                                                                                                                                                                                                                     |
+
 ## Slack workflow notifications
 
 This integration requires Wardby 0.6.0 or later.
@@ -779,6 +852,12 @@ packages, both forced to patched versions by `overrides` in `package.json`:
   re-run `prisma generate`, `prisma validate`, the `migrate diff` drift check,
   and the migration image's `migrate deploy`.
 
+ESLint and `typescript-eslint` still ask for `minimatch` 10, which is flagged
+(GHSA-g3hv-75wg-m249, moderate, fixed in 11.0.1), so `overrides` also forces
+`minimatch` to 11.0.3. It is development-only and never reaches a production
+image. After changing it, confirm `npm run lint` checks the same files and
+still reports problems.
+
 `scripts/security-audit.mjs` carries no exceptions: with the overrides the full
 and production audits are clean, and if a lockfile change ever dropped one, the
 advisory would reappear and the security job would fail.

package/docs/tool-secrets.md

@@ -157,6 +157,9 @@ or that the tool is not granted, fails with
 [`secret_brokered`](../help/errors/secret-brokered.md), so update tools that read
 the value to use `fetch` instead.
 
+A host provider's credentials must be brokered secrets, placed in a header or
+query parameter. See [host-providers.md](host-providers.md).
+
 ## What the host enforces
 
 - **https only**, to the default port. Any other scheme or port is refused with

package/docs/viewer-api.md

@@ -13,6 +13,12 @@ the `admin` role.
 
 ## Access
 
+From an MCP client, an admin gets a deployment-wide listing without this API:
+`list_agents` and `list_runs` with `all: true` (Wardby 0.8.0 and later) need the
+same `admin:view` scope and `admin` role, and are refused otherwise. Their
+`triggerInfo` and `outcomes` fields have the same shapes as a graph run's
+`trigger` and `outcomes` here; `serviceReadiness` is `services` without `reason`.
+
 A caller needs an access token for the Wardby MCP resource that carries the
 `admin:view` scope, and the Wardby `admin` role. Send it as
 `Authorization: Bearer <token>`.

package/docs/viewer-api.openapi.yml

@@ -2,7 +2,7 @@
 openapi: 3.1.0
 info:
   title: wardby admin viewer API
-  version: 0.7.0
+  version: 0.8.0
   description: "Read-only admin API behind the wardby viewer: graph, run detail, infrastructure info and a live event stream. Response objects may gain new fields in later releases; clients should ignore unknown fields. See docs/viewer-api.md for the prose contract."
 servers:
   - url: https://{host}

package/help/admin-viewer.md

@@ -19,6 +19,10 @@ It requires the Wardby `admin` role and the `admin:view` scope, which only the
 provider and map it like `agents:admin`. See
 [Configure identity and privileged access](identity-and-access.md).
 
+From an MCP client, an admin gets the same deployment-wide listing with
+`list_agents` and `list_runs` and `all: true` (Wardby 0.8.0 and later; also
+`admin:view`). Without the role the call is refused.
+
 Endpoints, all `GET`:
 
 - `/admin/api/graph?since=1h&limit=500`: a snapshot of runs in a time window.