@wardby/cli 0.6.0 → 0.8.0

package/docs/getting-started-identity-provider.md

@@ -54,26 +54,27 @@ access tokens for that audience.
 
 Create these scopes in the provider:
 
-| Scope                 | Capability                                                         |
-| --------------------- | ------------------------------------------------------------------ |
-| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.      |
-| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.  |
-| `runs:trigger`        | Start agent runs.                                                  |
-| `tools:write`         | Create, attach, and manage tools.                                  |
-| `datastore:write`     | Create, attach, query, and modify datastores.                      |
-| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                |
-| `webhooks:write`      | Create and manage webhook triggers.                                |
-| `budget_groups:write` | Create and manage shared budget groups.                            |
-| `packages:approve`    | Approve coding agents' package allowlists.                         |
-| `services:manage`     | Create, update and delete coding-run service catalog entries.      |
-| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.          |
-| `memory:write`        | Set and delete agent memory entries.                               |
-| `admin:view`          | Read every owner's runs through the admin viewer API; admins only. |
-| `models:admin`        | Add, override, disable and reset model catalog entries.            |
-| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only. |
+| Scope                 | Capability                                                                      |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.                   |
+| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.               |
+| `runs:trigger`        | Start agent runs.                                                               |
+| `tools:write`         | Create, attach, and manage tools.                                               |
+| `datastore:write`     | Create, attach, query, and modify datastores.                                   |
+| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                             |
+| `webhooks:write`      | Create and manage webhook triggers.                                             |
+| `budget_groups:write` | Create and manage shared budget groups.                                         |
+| `packages:approve`    | Approve coding agents' package allowlists.                                      |
+| `services:manage`     | Create, update and delete coding-run service catalog entries.                   |
+| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.                       |
+| `memory:write`        | Set and delete agent memory entries.                                            |
+| `admin:view`          | Read every owner's runs through the admin viewer API; admins only.              |
+| `models:admin`        | Add, override, disable and reset model catalog entries.                         |
+| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only.              |
+| `hosts:admin`         | Register host providers and approve their tools; admins and host managers only. |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all fifteen in the provider even when
+may request every advertised scope. Define all sixteen in the provider even when
 policy grants a particular client or user only a subset. Ensure granted scopes
 are emitted in the access token's `scope` or `scp` claim; defining them only in
 the provider UI is not sufficient.
@@ -97,24 +98,29 @@ every advertised scope fail with `invalid_scope`.
 deployment, define it in the provider too and map it like `agents:admin`;
 otherwise clients that request every advertised scope fail with `invalid_scope`.
 
+`hosts:admin` was added after `power:manage`. When you upgrade an existing
+deployment, define it in the provider too and map it like `agents:admin`;
+otherwise clients that request every advertised scope fail with `invalid_scope`.
+
 ### Wardby roles
 
 A scope only delegates. `agents:admin`, `packages:approve`, `services:manage`,
-`admin:view`, `models:admin` and `power:manage` take effect only for a caller who also holds a Wardby role that grants them:
+`admin:view`, `models:admin`, `power:manage` and `hosts:admin` take effect only for a caller who also holds a Wardby role that grants them:
 
-| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
-| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                     |
-| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                         |
-| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                |
+| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog), `hosts:admin` (host providers) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
+| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                                                     |
+| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                                                         |
+| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                                                |
+| `host-manager`     | `hosts:admin` (`register_host_provider`, `approve_host_provider_tools`, `test_host_provider`; see [host-providers.md](host-providers.md))                                                                                                                                                                                                                      |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
 
 ```dotenv
 AUTH_ROLE_CLAIM=groups   # claim name or dotted path
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Wardby looks up `AUTH_ROLE_CLAIM` in two steps:
@@ -162,20 +168,20 @@ their next token.
 
 Provider examples:
 
-- **Okta** (custom authorization server): create four groups, `wardby-admin`,
-  `wardby-packages`, `wardby-services` and `wardby-models`. Add a `groups` claim
+- **Okta** (custom authorization server): create five groups, `wardby-admin`,
+  `wardby-packages`, `wardby-services`, `wardby-models` and `wardby-hosts`. Add a `groups` claim
   to the access token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage`.
-- **FusionAuth:** create four application roles, `admin`,
-  `package-approver`, `service-manager` and `model-manager`. They appear in the
+  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin`.
+- **FusionAuth:** create five application roles, `admin`,
+  `package-approver`, `service-manager`, `model-manager` and `host-manager`. They appear in the
   access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
-  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager`.
+  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager,host-manager=host-manager`.
 - **Keycloak:** create realm roles such as `wardby-admin`, `wardby-packages`,
-  `wardby-services` and `wardby-models`. Realm roles appear under
+  `wardby-services`, `wardby-models` and `wardby-hosts`. Realm roles appear under
   `realm_access.roles`. Set `AUTH_ROLE_CLAIM=realm_access.roles` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   For client roles, use `resource_access.<client-id>.roles`. The
   [local Keycloak harness](../deploy/keycloak-test/README.md) sets this up.
 - **Auth0:** add the user's roles to the access token as a namespaced custom
@@ -190,7 +196,10 @@ that case, register the MCP client manually as a **public/native application**:
 
 - require authorization code flow with PKCE S256;
 - do not issue or embed a client secret in a desktop client;
-- register the client's exact loopback callback URI; and
+- register the client's exact loopback callback URI;
+- enable the refresh-token grant and allow the `offline_access` scope, so the
+  client receives a refresh token (desktop clients need one to keep a session);
+  and
 - allow it to request the Wardby audience and scopes.
 
 To let the Wardby mobile app sign in, also register its private-use redirect
@@ -212,6 +221,12 @@ public client ID. If a client supports only dynamic registration, either enable
 that feature with suitable provider-side restrictions or use Wardby's
 self-hosted authentication mode.
 
+The Wardby viewer desktop app signs in on a fixed loopback callback,
+`http://127.0.0.1:8585/callback`; register that exact URI on its public/native
+client. Some providers match a loopback redirect by its exact port rather than
+the port-agnostic rule of RFC 8252 §7.3 — for those, this precise port must be
+registered, because a port-less or wildcard loopback entry will not match it.
+
 ## 4. Configure Wardby
 
 Inject these settings through the deployment's secret/configuration mechanism:
@@ -227,7 +242,7 @@ AUTH_JWKS_URI=https://identity.example.com/your-tenant/.well-known/jwks.json
 AUTH_AUDIENCE=https://wardby.example.com/mcp
 # Optional: Wardby roles (see "Wardby roles" above).
 AUTH_ROLE_CLAIM=groups
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Copy `AUTH_ISSUER` exactly from the token's `iss` claim or the provider's
@@ -263,7 +278,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all fifteen Wardby scopes.
+- `scopes_supported` contains all sixteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.

package/docs/getting-started.md

@@ -238,6 +238,13 @@ After connecting, try:
 > List my Wardby agents, show the latest run and its actual cost, then create a
 > new agent with a maximum budget of $0.50. Do not run it yet.
 
+From Wardby 0.8.0, Claude Code can also show your runs in a pane beside the
+chat. With `--client claude` or `both`, quickstart offers to install it
+(`--claude-plugin` installs it unattended, `--no-claude-plugin` skips the
+question); otherwise run `npx @wardby/cli@latest claude-plugin install`, then
+`/wardby-runs`. `wardby doctor` reports whether it is set up. See the
+[Claude Code plugin](claude-code-plugin.md) guide.
+
 ### Reasoning effort
 
 A native agent can set `effort` (`low`, `medium`, `high`, `xhigh`, or `max`)
@@ -422,6 +429,15 @@ along with the database. See
 run does, its requirements (the server must run on the same machine as the
 folders) and its limits (no submodules or Git LFS).
 
+#### Faster installs: the dependency cache
+
+For an npm repository, the coding proxy can keep `node_modules` snapshots so a
+run starts with its dependencies already installed. Add
+`WARDBY_DEPENDENCY_CACHE=true` to `.wardby/.env`, restart the stack, then set
+`codingProfile.dependencyCache` to `true` on the agent with `update_agent`. This
+needs wardby 0.7.0 or later; snapshots live on a Docker volume that
+`down -v` removes. See [Dependency cache](coding-packages.md#dependency-cache).
+
 ## Your first agents
 
 [Agent recipes](agent-recipes.md) gives two complete, copyable setups: an
@@ -455,6 +471,7 @@ help article.
 ## Next steps
 
 - [Agent recipes](agent-recipes.md)
+- [Claude Code plugin](claude-code-plugin.md): your runs beside the chat (0.8.0+)
 - [Runtime architecture](architecture-runtime.md)
 - [Coding-agent setup](coding-agent-setup.md) and its
   [local repositories](coding-agent-setup.md#local-repositories) section

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/jira-agents.md

@@ -466,9 +466,12 @@ What happens:
   the same branch instead of opening a second pull request. The run message
   lists up to ten open pull requests recorded for the issue this way — any
   agent's, not only the triggered agent's own — each with its own run id, so
-  a follow-up can continue every one the change touches.
+  a follow-up can continue every one the change touches. GitHub issues behave
+  the same way; see
+  [Follow-ups on an issue](code-review-agents.md#follow-ups-on-an-issue).
 - **Several repositories.** When the issue leads to pull requests in more
-  than one repository (in the same run, or in later runs for the same issue),
+  than one repository (in the same run, or in later runs for the same issue,
+  Jira or GitHub),
   each pull request's description gets a **Related pull requests** section
   naming the issue and every pull request recorded for it, merged and closed
   ones included as context; see
@@ -574,8 +577,16 @@ A run is attributed when:
 - its parent run is attributed (sub-agents and coding runs inherit, and cannot
   change it).
 
+GitHub issues are attributed the same way, to a work item with provider
+`github` and key `owner/repo#N`: a run started by a mention on the issue (and
+every sub-agent and coding run it starts), and runs on a pull request opened
+from it. `cost_report` lists them like any other work item
+(`provider: "github"` narrows to them).
+
 When a run is attributed to an issue, whatever the source, coding runs it
-starts name that issue in their pull request's title and body. The issue total
+starts name that issue in their pull request's title and body. A GitHub issue
+is named only in the body, as `From issue #N`, on a pull request in the
+issue's own repository. The issue total
 in a Jira comment's spend line covers every run attributed to that issue,
 whichever agent ran it.
 
@@ -602,11 +613,9 @@ How to read the numbers:
 - You see the runs of agents you own and runs you triggered, the same as
   `list_runs` and `get_run`.
 
-On GKE, existing deployments must re-run the database grants bootstrap
-(`deploy/gke/bootstrap-database-iam.sh`) after upgrading, so the coding proxy
-can write per-model usage for coding runs. Until then coding runs still work,
-but their per-model breakdown isn't recorded. See
-[Getting started on GKE](getting-started-gke.md).
+On GKE, the coding proxy needs a database grant to write per-model usage for
+coding runs; `deploy/gke/up.sh` applies it when you upgrade. See
+[Upgrading an existing deployment](getting-started-gke.md#upgrading-an-existing-deployment).
 
 ### Company-managed projects using Epic Link
 

package/docs/knowledge/blob-not-found-semantics.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Blob absence must distinguish missing infrastructure
+description: Mapping a storage outage to not_found can delete valid dependency snapshot metadata.
+tags: [storage, cache, providers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: missing
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/storage/s3.ts#L26-L32
+  - id: cleanup
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/dependency-cache/service.ts#L275-L295
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/providers/storage/**", "src/providers/coding-proxy/dependency-cache/service.ts"]
+  citations:
+    - id: missing
+      repo: github:wardby/wardby
+      path: src/providers/storage/s3.ts
+      lines: [26, 32]
+      symbol: isNotFound
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:686cdad150c8c0d58e6b9acc5a2cd0bdf2e65b07b5ce8740938f43747f1408b7
+    - id: cleanup
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/dependency-cache/service.ts
+      lines: [275, 295]
+      symbol: download
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:02d4e058438d562ba55b6681e0267e890eed1ef82159a3b332d214f2fd066427
+  confidence: high
+---
+
+The cache deletes snapshot metadata when getStream raises BlobStoreError with code not_found. The S3 adapter therefore maps missing keys, including the bare HeadObject NotFound response, but leaves NoSuchBucket and other failures as errors.[^missing][^cleanup]
+
+**Why:** not_found authorizes metadata cleanup; it is not a generic unavailable response. New storage adapters must preserve this distinction so an infrastructure failure cannot masquerade as a dangling snapshot.
+
+[^missing]: src/providers/storage/s3.ts, lines 26-32.
+
+[^cleanup]: src/providers/coding-proxy/dependency-cache/service.ts, lines 275-295.

package/docs/knowledge/bounded-file-descriptor.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Untrusted file bounds belong to the open descriptor
+description: Checking a path before reading it leaves file substitution and growth races across worker boundaries.
+tags: [coding, isolation, files]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: read
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/coding-worker/artifact.ts#L12-L48
+  - id: skills
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/coding-worker/skills.ts#L43-L54
+  - id: result
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/jobs/docker.ts#L1263-L1277
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/coding-worker/artifact.ts", "src/coding-worker/skills.ts", "src/providers/jobs/docker.ts"]
+  citations:
+    - id: read
+      repo: github:wardby/wardby
+      path: src/coding-worker/artifact.ts
+      lines: [12, 48]
+      symbol: readBoundedRegularFile
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:ce5173dc2723b798c03e33fcb780c5c4da5b2dd15f2b517c4db77fec841f788d
+    - id: skills
+      repo: github:wardby/wardby
+      path: src/coding-worker/skills.ts
+      lines: [43, 54]
+      symbol: skillNameFromFile
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:022ed743f1ccb279f73e4520bf458ad28eeace035ae695853c9e5f7ee52087d4
+    - id: result
+      repo: github:wardby/wardby
+      path: src/providers/jobs/docker.ts
+      lines: [1263, 1277]
+      symbol: readResultArtifact
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:da6466b5dc44b1de79f473668648048b3f3ef3f82a6cce61516e8bfa76efb996
+  confidence: high
+---
+
+The bounded reader opens without following a final symlink and without blocking on a FIFO, checks the opened descriptor against the path inode, and reads at most one byte beyond the limit to detect growth. Both repository skill scanning and Docker result collection use it.[^read][^skills][^result]
+
+**What to do:** preserve descriptor checks and the bounded read together. Replacing them with a path stat followed by readFile reopens substitution and growth races even when the initial size was safe.
+
+[^read]: src/coding-worker/artifact.ts, lines 12-48.
+
+[^skills]: src/coding-worker/skills.ts, lines 43-54.
+
+[^result]: src/providers/jobs/docker.ts, lines 1263-1277.