@wardby/cli 0.7.0 → 0.9.0

package/docs/host-providers.md

@@ -0,0 +1,294 @@
+# Host providers
+
+A host provider adds a code host to Wardby using your own custom tools. You can add
+a host, or fix one, without a Wardby release.
+
+Host providers are being added in stages. **This release (0.8.0) lets you register a
+provider, approve its tools and test them. Agents can't use a registered provider yet**,
+and `link_repository` still refuses its repositories.
+
+## Who can manage one
+
+Every host provider tool (`register_host_provider`, `approve_host_provider_tools`,
+`get_host_provider`, `test_host_provider`, `delete_host_provider`) needs the
+`hosts:admin` scope and a role that grants it (`admin` or `host-manager`), or the local
+stdio operator. Bound tools decide who has permission and who wrote a comment, so treat
+this like `agents:admin`. See
+[getting-started-identity-provider.md](getting-started-identity-provider.md#wardby-roles)
+for defining the scope and mapping the role.
+
+Providers are shared by every host manager: any host manager can read and re-register any
+provider, including its tool code, whoever owns the tools it names.
+
+## Register a provider
+
+1. Create a tool for each operation with `create_tool`. Each does one host call. See
+   [Tool contract](#tool-contract).
+2. Store each credential with `create_secret`, and broker it with `set_secret_broker`
+   ([tool-secrets.md](tool-secrets.md)). Allow every API host and place it in a header or
+   query parameter. Repository credentials also allow the git host; the permission
+   credential needs only the API hosts.
+3. Store a webhook secret of at least 16 characters. Don't attach it to any agent.
+4. Call `register_host_provider`:
+
+   ```json
+   {
+     "provider": "your-host",
+     "gitHost": "git.example.com",
+     "apiHosts": ["api.example.com"],
+     "gitUsername": "x-token-auth",
+     "pullRequestUrlTemplate": "https://git.example.com/{repository}/pull/{number}",
+     "repositoryApiPath": "/2.0/repositories/{repository}",
+     "webhook": {
+       "header": "X-Hub-Signature",
+       "algorithm": "sha256",
+       "deliveryHeader": "X-Request-UUID",
+       "eventHeader": "X-Event-Key",
+       "secret": "your-webhook-secret"
+     },
+     "credentials": [{ "repositories": "your-workspace/*", "secret": "your-token" }],
+     "trustedAccounts": ["<account id>"],
+     "tools": { "getPullRequest": "your_get_pr_tool" }
+   }
+   ```
+
+   Bind every required operation in `tools` (names here are placeholders), and any optional
+   ones you want. For example:
+
+   ```json
+   "tools": {
+     "getPullRequest": "your_get_pr", "listPullRequestFiles": "your_list_files",
+     "getDiff": "your_get_diff", "readFile": "your_read_file", "listFiles": "your_list_dir",
+     "listComments": "your_list_comments", "createComment": "your_create_comment",
+     "submitVerdict": "your_submit_verdict", "findPullRequest": "your_find_pr",
+     "openPullRequest": "your_open_pr", "updatePullRequest": "your_update_pr"
+   }
+   ```
+
+5. No restart is needed in this release, because agents can't use a provider yet. Once they
+   can, a new provider will need a server restart; approvals won't.
+
+The tools and secrets you name must be yours. Secret rules, each refused with a named code:
+
+- Credentials and `permissionCredential` must be brokered, placed in a header or query
+  parameter, and allowed on the API hosts (credentials also on the git host; the permission credential needs only the API hosts).
+- `permissionCredential` can't also be listed in `credentials`
+  (`host_provider_permission_secret_shared`), so no other operation can reach it.
+- The webhook secret can't be a credential or permission secret of any provider, and can't
+  be attached to an agent (`host_provider_webhook_secret_shared`). `attach_secret` refuses
+  it too.
+- The webhook secret needs at least 16 characters (`host_provider_webhook_secret_short`).
+- A permission secret can't be a credential or permission secret of any other provider, and a
+  credential can't be another provider's permission secret
+  (`host_provider_permission_secret_shared`).
+- `gitUsername` can't be a credential's value and can't contain "username".
+- `pullRequestUrlTemplate` is an https URL on `gitHost`, with no username, password or port.
+
+Keep provider credentials unattached. A brokered credential attached to one of its owner's agents
+can be used by that agent's tools without the host provider path guard, which only applies to a
+provider's bound tools.
+
+See [the refusal codes](../help/errors/host-provider-error.md) for what each one means.
+
+These provider names can't be used: `github`, `local`, `http`, `https`, `ssh`, `git`,
+`file` and `constructor`. Names match `^[a-z][a-z0-9-]{1,30}$`.
+
+These operations are required: `getPullRequest`, `listPullRequestFiles`, `getDiff`,
+`readFile`, `listFiles`, `listComments`, `createComment`, `submitVerdict`,
+`findPullRequest`, `openPullRequest` and `updatePullRequest`. These are optional:
+`editComment`, `resolveThread`, `listCommitStatuses`, `setCommitStatus`,
+`getRepositoryPermission` and `normalizeEvent`. `getRepositoryPermission` becomes required
+when you set `permissionCredential`.
+
+## Who may start a run
+
+This is how it will work once agents can use a provider. Registering records your choice
+now; nothing enforces it in this release.
+
+| Setup                     | Situation                                | Result                            |
+| ------------------------- | ---------------------------------------- | --------------------------------- |
+| `permissionCredential`    | The host says the user has enough access | Run starts                        |
+| `permissionCredential`    | The host says they don't                 | Refused, even if in the allowlist |
+| `permissionCredential`    | The lookup fails                         | Refused, with no fallback         |
+| No `permissionCredential` | The user is in `trustedAccounts`         | Run starts, at `write` level      |
+| No `permissionCredential` | The user isn't in `trustedAccounts`      | Refused                           |
+
+`permissionCredential` needs `permissionApiPath` (with `{workspace}` and `{repo}`) and a
+bound `getRepositoryPermission`.
+
+## Change a tool
+
+Registering copies each tool's code, schema and `timeoutMs` (its time limit), and only that
+copy ever runs.
+`update_tool` changes nothing until you approve it, so the last approved version keeps
+working in the meantime.
+
+1. Call `update_tool`.
+2. Call `get_host_provider` with `includeCode: true`. Changed tools show `status: "changed"`.
+   Each operation has `approvedCode` and `approvedParamsZod`, and a changed one also has
+   `currentCode` and `currentParamsZod`, because a change can be to the schema alone. Every
+   operation also shows `approvedTimeoutMs` and `currentTimeoutMs` (`null` is the default
+   10 seconds), since a change can be to the time limit alone.
+3. Read the change, then call `approve_host_provider_tools` with the operation names. It
+   applies from the next call.
+
+Deleting a tool keeps its snapshot running, with `status: "tool_deleted"`. To change that
+operation, bind a new tool by registering again. Registering again also approves every tool
+at its current code.
+
+## Rotate a secret
+
+A secret a provider uses is replaced with `create_secret` under the same name, whether it's a
+credential, the permission credential or the webhook secret. Change its broker config with
+`set_secret_broker`. Both need `hosts:admin` with a role that grants it, as well as
+`secrets:write`, and refuse before handing out a browser link. Without brokering a credential
+stops working, so `set_secret_broker` with `broker: null` also breaks the provider.
+
+Only the secret's owner can rotate it this way, because secret names belong to their owner. If
+another host manager calls `create_secret` with the same name, they get a separate secret and the
+provider keeps the old value. They must register the provider again with their own secret instead.
+
+The new webhook value needs at least 16 characters, whether you pass it directly or enter it
+in the browser (`host_provider_webhook_secret_short`). A browser link requested before the secret
+joined a provider is refused (`host_provider_secret_link_stale`); request a new one.
+
+Rotating needs no re-registration: the next call uses the new value. Update the webhook secret on
+the host at the same time.
+
+## Test a provider
+
+`test_host_provider` runs each approved read-only tool against one repository, using the
+real credential:
+
+```json
+{
+  "provider": "your-host",
+  "repository": "your-host:your-workspace/your-repo",
+  "pullRequest": 4,
+  "headRef": "a-branch-with-a-pull-request",
+  "ref": "a-commit-or-branch",
+  "accountId": "<account id>"
+}
+```
+
+Only `provider` and `repository` are required. Each other field enables the checks that need it:
+
+| Field         | Checks it enables                                                                   |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `pullRequest` | `getPullRequest`, `listPullRequestFiles`, `getDiff`, `listComments`                 |
+| `headRef`     | `findPullRequest`                                                                   |
+| `ref`         | `readFile`, `listFiles`, `listCommitStatuses` (defaults to the pull request's head) |
+| `accountId`   | `getRepositoryPermission`                                                           |
+
+Each result is an `outcome` of `pass`, `fail` (with a fixed code, below) or `skipped`. A skip has
+one of these codes: `not_bound` (no tool bound), `needs_pull_request`, `needs_head_ref`,
+`needs_ref`, `needs_account` (the field above is missing), `allowlist_mode` (no
+`permissionCredential`, so no permission lookup) and `not_read_only` (a write operation, never run).
+
+Write operations are skipped. A read-only tool can only send GET requests. The report holds
+an operation, an outcome and a fixed code for each, and no response data, so you can share it.
+
+| Code                                    | Meaning                                                          |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `host_unauthorized`, `host_forbidden`   | The host refused the credential for this call.                   |
+| `host_not_found`                        | The host doesn't have what was asked for.                        |
+| `host_rate_limited`, `host_unavailable` | Try again later.                                                 |
+| `host_conflict`                         | The host refused because of the current state.                   |
+| `host_tool_invalid_result`              | The tool's answer doesn't match its operation's shape.           |
+| `host_tool_invalid_params`              | The tool's schema refused what Wardby sends it.                  |
+| `host_tool_request_denied`              | The tool went outside what a bound tool may request (see below). |
+| `host_tool_no_credential`               | See below.                                                       |
+| `host_tool_failed`                      | The tool threw an error. Its message is dropped on purpose.      |
+| `host_tool_timeout`                     | The tool ran out of time or instructions.                        |
+
+`host_tool_no_credential` has these causes: no credential's `repositories` covers this repository,
+the secret can't be decrypted, or the secret is no longer brokered or no longer allows every API
+host.
+
+## Tool contract
+
+Each tool receives `workspace`, `repo` and `repository` (`workspace/repo`), plus its
+operation's input fields (below). Declare them in `paramsZod`.
+
+A tool answers with its operation's result, or `{ "error": "<code>" }` when the host refused,
+where the code is `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited` or
+`unavailable`. Results are checked strictly: an extra key, a missing key or a wrong type fails the
+call with `host_tool_invalid_result`.
+
+A pull request object, as returned by `getPullRequest` and `findPullRequest`, has exactly:
+`number` (positive integer), `title`, `body`, `author` (string or null), `state` (`open` or
+`closed`; a merged pull request is `closed` with `merged` true, so map your host's own states),
+`merged` (boolean), `draft` (boolean), `baseRef`, `headRef`, `headSha` (non-empty), `isFork` (boolean) and
+`htmlUrl` (a URL).
+
+Read operations (method GET):
+
+| Operation                 | Input fields          | Result                                                                                                                                                                                                                                  |
+| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getPullRequest`          | `number`              | A pull request object.                                                                                                                                                                                                                  |
+| `findPullRequest`         | `headRef`             | `{ pullRequest }`: a pull request object, or null if none.                                                                                                                                                                              |
+| `listPullRequestFiles`    | `number`, `page`      | `{ files, nextPage }`. Each file: `filename`, `status` (`added`, `modified`, `removed` or `renamed`), `additions`, `deletions` (non-negative integers) and optionally `previousFilename`.                                               |
+| `getDiff`                 | `number`              | `{ diff }`: the unified diff text.                                                                                                                                                                                                      |
+| `readFile`                | `ref`, `path`         | `{ kind: "file", content }`, `{ kind: "directory" }` or `{ kind: "not_found" }`. No other keys.                                                                                                                                         |
+| `listFiles`               | `ref`, `path`, `page` | `{ entries, nextPage }`. Each entry: `path`, `type` (`file` or `directory`) and optionally `size` (non-negative integer).                                                                                                               |
+| `listComments`            | `number`, `page`      | `{ comments, nextPage }`. Each comment: `id` (non-empty), `author` and `authorId` (string or null), `body`, `createdAt`, `path` (string or null), `line` (positive integer or null), `parentId` (string or null), `resolved` (boolean). |
+| `listCommitStatuses`      | `ref`, `page`         | `{ statuses, nextPage }`. Each status: `key`, `state` (`pending`, `success`, `failure` or `stopped`) and `url` (string or null).                                                                                                        |
+| `getRepositoryPermission` | `accountId`           | `{ permission }`: `none`, `read`, `triage`, `write`, `maintain` or `admin`. Uses the permission credential and `permissionApiPath`.                                                                                                     |
+
+`listPullRequestFiles`, `listFiles`, `listComments` and `listCommitStatuses` page. Each returns
+one page per call, with `nextPage`: a string to continue from, or null at the end. To get the next
+page, Wardby passes that string back as the optional `page` input, and it leaves `page` out for the
+first page. Declare `page` in `paramsZod`, because `z.object` drops keys it doesn't name, and a tool
+without it would return the first page every time. `test_host_provider` reads the first page only.
+
+`ref` is optional on `readFile` and `listFiles`, where leaving it out means the default branch, so
+declare it as optional there. `listCommitStatuses` always needs one, because statuses belong to a
+commit.
+
+Keep a file's `status` to those four words: Wardby treats a `removed` file as having nothing to read
+at the head.
+
+Write operations:
+
+| Operation           | Method | Result                       |
+| ------------------- | ------ | ---------------------------- |
+| `openPullRequest`   | POST   | A pull request object.       |
+| `updatePullRequest` | PUT    | A pull request object.       |
+| `createComment`     | POST   | `{ id }` (non-empty string). |
+| `editComment`       | PUT    | `{ id }` (non-empty string). |
+| `resolveThread`     | POST   | `{}`                         |
+| `submitVerdict`     | POST   | `{}`                         |
+| `setCommitStatus`   | POST   | `{}`                         |
+
+The input fields of the write operations are defined when agents can use a provider, in a later
+release, so tools for them may need changing then. `test_host_provider` never runs them.
+
+`normalizeEvent` makes no requests and isn't called yet.
+
+Use `fetch(url, { secrets: ["host"] })`. Wardby resolves `host` to the credential for this
+call's repository. A bound tool:
+
+- reaches only `apiHosts`, over https on the default port, with no embedded credentials;
+- stays under `repositoryApiPath` for this repository. `getRepositoryPermission` stays under
+  `permissionApiPath` instead, and is the only operation that gets `permissionCredential`;
+- uses its operation's method: GET for reads, and POST or PUT for writes;
+- may set only the headers `accept`, `content-type`, `if-match` and `if-none-match`;
+- makes at most three requests per call. No request follows a redirect, whether or not it
+  carries a secret: follow a `Location` yourself, which counts as a request and goes through
+  the same limits;
+- can't send the query keys `_method` or any starting `x-http-method`, in any case, which some
+  frameworks read as the request's method;
+- has its path judged by what a server could turn it into: dot-only segments after decoding
+  and encoded separators are refused. A few unusual file names can therefore be refused, and a
+  repository path must be sent literally, not percent-encoded;
+- has no datastore, shared datastore or readable secrets, and its `console` output is dropped;
+- runs under the usual sandbox limits: 10 s per call, 8 s per fetch, 8 MiB per response.
+
+Anything outside these limits fails the call with `host_tool_request_denied`, even if the
+tool catches the error.
+
+## Remove a provider
+
+`delete_host_provider` removes a provider and its snapshots. It's refused while an agent links
+to one of its repositories. `delete_secret` is refused while a provider uses that secret, and
+names the provider.

package/docs/mcp-servers.md

@@ -0,0 +1,263 @@
+# 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.
+- **Low-power mode (0.9.0 and later).** With `WARDBY_LOW_POWER=1`, a coding run with MCP tools wakes the native
+  gateway as well as the coding proxy before its worker launches (both at once), and the gateway
+  stays awake while any such run is pending or running, or finished within the idle window. Those
+  runs appear in the gateway's `blockers` in `power_status`, and `power_sleep` refuses to sleep the
+  gateway while they are pending or running. If the gateway doesn't wake in time the run fails before
+  launch with
+  [`coding_failure_mcp_gateway_unavailable`](../help/errors/coding-mcp-gateway-unavailable.md),
+  rather than start without its MCP tools. Runs without MCP tools don't wake the gateway. See
+  [Low-power mode](getting-started-gke.md#low-power-mode).
+- **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,16 @@ 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_RUN_STEPS`             | Same value as the server, if you set it: the ceiling for run steps. The gateway records at each run's own level, so set `detail` here too if agents use it ([details](debugging-agent-runs.md#run-steps)).                                                 |
+| `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
@@ -541,6 +551,11 @@ or the server running upkeep is not up.
 Gateway-side variables (`NATIVE_GATEWAY_LISTEN`, `NATIVE_GATEWAY_DENY_PORT`) are
 set on the gateway, not the server.
 
+The gateway also records sandbox runs' steps (see
+[Run steps](debugging-agent-runs.md#run-steps)), so when you change
+`WARDBY_RUN_STEPS` (including `detail`) or `RUN_STEP_RETENTION_DAYS`, set them on
+the gateway as well as the server.
+
 ## Limits and deadline
 
 - Each worker is limited by `NATIVE_SANDBOX_CPUS`, `NATIVE_SANDBOX_MEMORY_MB`,
@@ -549,6 +564,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 +579,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.