@wardby/cli 0.7.0 → 0.8.0

package/help/errors/native-sandbox-worker-unready.md

@@ -4,7 +4,7 @@ title: Native worker pod did not start
 summary: On Kubernetes, the sandbox worker pod did not reach the Running state in time, so the run failed before starting.
 audience: operator
 tags: [error, native-agents, sandbox, kubernetes, native_sandbox_worker_unready]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker pod did not start

package/help/errors/repository-not-listed.md

@@ -0,0 +1,36 @@
+---
+id: errors/repository-not-listed
+title: Repository not on the agent's list (repository_not_listed)
+summary: The repository named for a coding run is not the agent's default or one of its write links; name a listed one, or add it with link_repository.
+audience: operator
+tags: [error, coding-agents, repository_not_listed, invalid_repository, link_repository]
+appliesTo: ">=0.8.0"
+---
+
+# Repository not on the agent's list
+
+`repository_not_listed` means the `repository` given to `trigger_agent` or to a
+`delegate_to_<name>` call is neither the coding agent's default
+(`codingProfile.repository`) nor one of its repository links (write access, no
+triggers). No run was started. The message lists the repositories that are
+allowed and never repeats the value that was sent.
+
+A webhook that sends `wardbyRepository` gets the same refusal as a 400
+`{ "error": "invalid_repository" }` when
+`codingProfile.allowWebhookTaskOverride` is on. A malformed value (not a string,
+empty, or over 300 characters) is that same 400 with the flag on or off. With
+the flag off, a well-formed value is refused with 403 `{ "error": "disabled" }`
+before it is compared with the list, whoever created the webhook.
+
+## What to do
+
+- Name one of the listed repositories, spelled as `your-org/your-repo`.
+- To add a repository, the agent's owner calls `link_repository` with
+  `access: "write"`, no triggers and, optionally, a `baseRef`. The owner needs
+  write access to it on the host, or an admin approves it.
+- If a native (non-coding) sub-agent is the target, `repository` is refused
+  with `repository_requires_coding_agent`: drop the argument.
+
+See [Repository required](repository-required.md),
+[Agent recipes](../agent-recipes.md) and the operator guide
+`docs/coding-agent-setup.md`, section "A coding agent's repositories".

package/help/errors/repository-required.md

@@ -0,0 +1,36 @@
+---
+id: errors/repository-required
+title: Repository required (repository_required)
+summary: A coding agent with several repositories was asked to work without being told which one; pass repository, or use continuePriorRun.
+audience: operator
+tags: [error, coding-agents, repository_required, repository, link_repository, delegation]
+appliesTo: ">=0.8.0"
+---
+
+# Repository required
+
+`repository_required` means a coding agent has more than its default repository
+(it has write links without triggers added with `link_repository`), and the
+request did not say which one to work in. Nothing was started.
+
+A `delegate_to_<name>` call to such a sub-agent must name a repository. The
+exception is a follow-up: with `continuePriorRun`, the run works in the
+repository of the run it continues. The message lists the repositories on the
+agent's list.
+
+## What to do
+
+- Pass `repository` on the call, using one of the listed repositories, for
+  example `your-org/your-repo`.
+- Tell the lead agent in its system prompt which repository each kind of
+  change belongs to.
+- If the agent should only work in one repository, remove the extra ones with
+  `unlink_repository`.
+
+On `trigger_agent` and webhooks, leaving `repository` out uses the default
+repository (`codingProfile.repository`) and is not an error. Webhooks use the
+body field `wardbyRepository`.
+
+See [Repository not on the agent's list](repository-not-listed.md),
+[Agent recipes](../agent-recipes.md) and the operator guide
+`docs/coding-agent-setup.md`, section "A coding agent's repositories".

package/help/errors/tool-timeout.md

@@ -0,0 +1,38 @@
+---
+id: errors/tool-timeout
+title: A tool call ran out of time (timeout, fetch_cancelled_or_timeout)
+summary: A sandboxed tool call hit its time limit; raise the tool's timeoutMs, up to the server's WARDBY_TOOL_MAX_TIMEOUT_MS.
+audience: developer
+tags: [timeout, timeoutMs, wall-time, fetch_cancelled_or_timeout, sleep_limit, WARDBY_TOOL_MAX_TIMEOUT_MS]
+appliesTo: ">=0.8.0"
+---
+
+# A tool call ran out of time
+
+## What happened
+
+A tool's result was `{"error":"timeout","message":"Exceeded the 10000ms wall-time limit. ..."}`.
+The call ran longer than the tool's time limit, so it was stopped. The run goes on: only this call
+failed. The message names the limit. Without `timeoutMs` a tool has 10 seconds.
+
+Related results:
+
+- `fetch_cancelled_or_timeout` from inside the tool: a `fetch` was aborted because the call ran
+  out of time or the run stopped.
+- `sleep_limit`: the tool asked to wait longer than its own limit.
+- `{"error":"cancelled"}`: the run was stopped while the call was running.
+
+## What to do
+
+1. Check how long the API the tool calls really takes.
+2. Give the tool a longer limit with `update_tool` (`timeoutMs`, in milliseconds), or
+   `wardby tool update <tool> --timeout-ms <ms>`.
+3. Test it with `dry_run_tool` and the same `timeoutMs`.
+
+`timeoutMs` can't exceed the server's `WARDBY_TOOL_MAX_TIMEOUT_MS` (default `300000`); a larger
+value is refused with an error naming the ceiling. If you need more, ask the operator to raise it.
+If the operator lowers the ceiling, a tool with a larger `timeoutMs` runs with the ceiling.
+
+Runs that started before the change keep the limit they loaded; the next run uses the new one.
+
+See [Use native agents, tools, and data](../native-capabilities.md#tool-time-limits).

package/help/host-providers.md

@@ -0,0 +1,40 @@
+---
+id: host-providers
+title: Add a code host with your own tools (host providers)
+summary: Register a code host implemented by custom tools, approve changes to them, and test them with read-only calls. Agents can't use a provider yet.
+audience: operator
+tags: [host provider, register_host_provider, approve_host_provider_tools, hosts:admin, host-manager]
+appliesTo: >=0.8.0
+---
+
+# Host providers
+
+A host provider adds a code host using your own custom tools. This release lets you register
+a provider, approve its tools and test them. Agents can't use a registered provider yet.
+
+You need the `hosts:admin` scope and a role that grants it (`admin` or `host-manager`). See
+[Identity and access](identity-and-access.md).
+
+1. Write one tool per operation with `create_tool`.
+2. Broker each credential with `set_secret_broker`, allowing the API hosts and the git host. The
+   permission credential needs only the API hosts ([Brokered secrets](brokered-secrets.md)).
+3. Call `register_host_provider`. No restart is needed today, because agents can't use a provider
+   yet; a new provider will need one once they can. A refusal has a
+   [`host_provider_*` code](errors/host-provider-error.md).
+4. Call `test_host_provider` to check each read-only tool. Failures have
+   [fixed codes](errors/host-tool-failed.md).
+
+`update_tool` changes nothing until you call `approve_host_provider_tools`, a new `timeoutMs`
+included. See which tools have changes with `get_host_provider`.
+
+A bound tool reaches only the provider's API hosts, inside one repository's path, and Wardby
+follows no redirects; the tool must fetch the `Location` itself. Any host manager can read and re-register any
+provider.
+
+Replacing a secret a provider uses, or changing its broker config, needs `hosts:admin` as well as
+`secrets:write`. A webhook secret stays at 16 characters or more.
+
+Keep provider credentials unattached: an agent's own tools can use an attached one without the
+provider's path guard.
+
+See [docs/host-providers.md](../docs/host-providers.md) for the full guide.

package/help/identity-and-access.md

@@ -21,7 +21,7 @@ audience, and the granted Wardby scopes in `scope` or `scp`.
 
 Scopes authorize normal operations such as managing agents, runs, tools,
 datastores, secrets, webhooks, budgets, packages, services, memory, and
-models. Six sensitive permissions have an additional role requirement:
+models. Seven sensitive permissions have an additional role requirement:
 
 - `agents:admin` requires the Wardby `admin` role.
 - `packages:approve` requires the `admin` or `package-approver` role.
@@ -31,6 +31,9 @@ models. Six sensitive permissions have an additional role requirement:
 - `models:admin` requires the `admin` or `model-manager` role. It adds,
   overrides, disables, and resets model catalog entries; see
   [Models and pricing](models.md).
+- `hosts:admin` requires the `admin` or `host-manager` role. It registers host
+  providers, approves their tools and, with `secrets:write`, replaces their secrets; see
+  [Host providers](../docs/host-providers.md).
 - `power:manage` requires the `admin` role. It reads low-power state and
   sleeps the coding proxy and native gateway now (`power_status`,
   `power_sleep`); see

package/help/mcp-servers.md

@@ -0,0 +1,73 @@
+---
+id: mcp-servers
+title: Remote MCP server tools for native and coding agents
+summary: Register a remote MCP server, then attach an allowlist of its tools to a native, Claude Code or Codex agent; credentials stay in brokered secrets.
+audience: operator
+tags: [mcp, mcp server, coding-agent, codex, register_mcp_server, attach_mcp_server, readOnlyHint, WARDBY_MCP_SERVERS]
+appliesTo: ">=0.8.0"
+---
+
+# Remote MCP server tools for native and coding agents
+
+A native, Claude Code or Codex agent can call tools from a remote MCP server (Streamable HTTP, HTTPS only).
+
+1. Create a [brokered secret](brokered-secrets.md) for the server's host, for example
+   `Authorization: Bearer {value}`.
+2. `register_mcp_server` with a `name`, the `url` (`https://mcp.example.com/mcp`) and
+   `secretNames`. Wardby saves the server's tool list.
+3. `attach_mcp_server` with the agent, the server and `allowedTools` (exact names, at least one).
+   The agent sees each as `<server name>__<tool name>`.
+4. After the server changes its tools, `refresh_mcp_server` applies the new list at once. Allowed
+   tools the server dropped show as `missingTools` in `get_agent`.
+
+Each call has `callTimeoutMs` (default `30000`, at most `WARDBY_TOOL_MAX_TIMEOUT_MS`, and never
+past the run's deadline). Results are untrusted input; the allowlist is the control. stdio servers
+and OAuth are not supported.
+
+`WARDBY_MCP_SERVERS` is `owners` (default), `admins` (registering needs `hosts:admin`) or `off`
+(only `detach_mcp_server` and `delete_mcp_server` still work, for cleanup).
+
+Each call opens a fresh MCP session, so a server that keeps state between calls in one session
+won't see it. Arguments that aren't a JSON object return `invalid_arguments`.
+
+## Coding agents
+
+`attach_mcp_server` also takes a Claude Code or Codex agent. Its run reaches the tools only through
+the coding proxy and the native gateway; the worker never sees the server's URL or secrets.
+
+- Claude Code agents see each tool as `mcp__wardby_mcp__<server name>__<tool name>` and may use any
+  allowed tool.
+- Codex agents may use only tools the server marks `readOnlyHint: true`. Wardby checks this when
+  you attach, when a run loads and on every call. Repository code in a Codex run can read the run's
+  MCP token, so a Codex agent must not be given tools that change things. `readOnlyHint` is the
+  server's claim, which Wardby can't verify, so the allowlist stays your control.
+- A run may make `WARDBY_MCP_MAX_CALLS_PER_RUN` calls (default `100`, failed calls count); more are
+  refused with [`mcp_call_limit`](errors/mcp-call-limit.md).
+- The proxy needs `WARDBY_MCP_GATEWAY_URL`. Without it coding agents get no MCP tools
+  ([`mcp_unavailable`](errors/mcp-unavailable.md)).
+- MCP for coding agents needs this release's Claude worker image and a new Codex driver image.
+  Older images get no MCP tools, and runs don't fail.
+- A repository's MCP configuration is still never loaded.
+- Codex models that use tool search load MCP tools on demand. They need this release's coding
+  proxy; an older one refuses their requests with `openai_tool_not_allowed:tool_search`.
+- Switching an agent to Codex with `update_agent` keeps its attachments, but tools not marked
+  read-only won't reach Codex runs; the result's `warnings` names them.
+- The proxy gives up on a coding run's MCP call after 5 minutes, whatever
+  `WARDBY_TOOL_MAX_TIMEOUT_MS` says ([`mcp_unavailable`](errors/mcp-unavailable.md)).
+
+Share a server with `grant_access` (`resourceType: "mcp_server"`; needs the `agents:write` scope,
+registering needs `tools:write`). `use` lets the grantee attach it, and its tools then run with your
+secrets. Revoking the grant, or lowering it to `read`, detaches the server from the grantee's agents
+at once, and their runs' next call is refused with `mcp_tool_not_allowed`.
+
+Errors a call can return: [`mcp_server_unreachable`](errors/mcp-server-unreachable.md),
+[`mcp_server_auth_failed`](errors/mcp-server-auth-failed.md),
+[`mcp_server_credentials_unavailable`](errors/mcp-server-credentials-unavailable.md),
+[`mcp_server_error`](errors/mcp-server-error.md),
+[`mcp_tool_not_allowed`](errors/mcp-tool-not-allowed.md),
+[`mcp_tool_removed`](errors/mcp-tool-removed.md),
+[`mcp_call_timeout`](errors/mcp-call-timeout.md),
+[`mcp_servers_off`](errors/mcp-servers-off.md), and for coding agents
+[`mcp_call_limit`](errors/mcp-call-limit.md) and [`mcp_unavailable`](errors/mcp-unavailable.md).
+
+Full guide: [Remote MCP servers](../docs/mcp-servers.md).

package/help/mcp.md

@@ -1,13 +1,13 @@
 ---
 id: mcp-access
-title: Connect an MCP client
+title: Connect a client to Wardby
 summary: Use Wardby's local stdio or protected HTTP MCP transport safely.
 audience: developer
 tags: [mcp, oauth, codex, claude-code]
 appliesTo: >=0.2.1
 ---
 
-# Connect an MCP client
+# Connect a client to Wardby
 
 For local use, `wardby quickstart` can register the local stdio MCP server with
 Codex or Claude Code. Local stdio trusts the local operator.
@@ -28,3 +28,8 @@ offline catalog as `wardby help`; they expose no instance data or credentials.
 
 See [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
 for the supported self-hosted and delegated identity-provider setup.
+
+From Wardby 0.8.0, Claude Code can show your runs in a pane beside the chat
+through the `wardby-runs` plugin: run `wardby claude-plugin install`, then
+`/wardby-runs`. Search help for "claude code plugin" (article
+`claude-code-run-pane`, Wardby 0.8.0 and later).

package/help/native-capabilities.md

@@ -3,7 +3,7 @@ id: native-capabilities
 title: Use native agents, tools, and data
 summary: Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.
 audience: developer
-tags: [agents, tools, secrets, datastores, memory, schedules, subagents, zod, paramsZod, create_tool, dry_run_tool]
+tags: [agents, tools, secrets, datastores, memory, schedules, subagents, zod, create_tool, dry_run_tool, timeoutMs, mcp]
 appliesTo: >=0.2.1
 ---
 
@@ -48,11 +48,37 @@ rewrite the schema with the Zod 4 API (for example `z.looseObject()` for
 `.nonstrict()`, `z.string().optional()` for `z.ostring()`, and `z.ipv4()` or
 `z.ipv6()` for `.ip()`), dry-run it again, and save it with `update_tool`.
 
+## Tool time limits
+
+Wardby 0.8.0 and later. Each call of a tool has 10 seconds by default. A tool that calls a slow API can
+ask for more with `timeoutMs` (milliseconds, at least `1000`) on `create_tool`,
+`update_tool` or `dry_run_tool`, or `--timeout-ms` on `wardby tool create` and
+`wardby tool update`. Pass `timeoutMs: null` to `update_tool` (or
+`--timeout-ms default` to `wardby tool update`) to go back to the default.
+
+- The limit covers the whole call. Each `fetch` may run until the limit, and a
+  timer (`setTimeout`) can't be set for longer than it.
+- The server's `WARDBY_TOOL_MAX_TIMEOUT_MS` (default `300000`, five minutes)
+  caps it. A larger `timeoutMs` is refused with an error naming the ceiling. If
+  the operator lowers the ceiling later, existing tools run with the ceiling.
+- A run keeps the value it loaded, as it does the tool's code.
+- A call never outlasts its run: stopping the run aborts it, and a sandboxed
+  run's deadline cuts it off.
+- `list_tools` and `get_agent` show each tool's `timeoutMs` (`null` means the
+  default).
+
+Test a slow tool with `dry_run_tool` and the same `timeoutMs` before you attach
+it. A call that runs out of time fails with a `timeout` error; the help article
+`errors/tool-timeout` explains what to do.
+
 Use a budget or shared budget group on every agent, and inspect runs before
 expanding its access. An access grant is intentional delegation: use it only
 when an owner permits one agent to use another resource. Creating or changing
 tools, secrets, datastores, schedules, webhooks, memory, and budget groups
 requires the matching MCP scope.
 
+Native agents can also call tools from remote MCP servers; see
+[Remote MCP servers](../docs/mcp-servers.md) (0.8.0+).
+
 See [Operate agents](operating-agents.md) for run and budget management, and
 [`README.md`](../README.md) for the feature overview and MCP operations.

package/help/native-sandbox.md

@@ -4,7 +4,7 @@ title: Run native agents in a sandbox
 summary: Turn on sandbox mode so a native agent's turn loop and tools run in a single-use, credential-free Docker container or Kubernetes pod behind a native gateway.
 audience: operator
 tags: [native-agents, sandbox, isolation, docker, kubernetes, native-gateway, security, warm-pool]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Run native agents in a sandbox

package/help/operating-agents.md

@@ -32,6 +32,22 @@ A running run's cost, token counts, and turn count update after each model
 call, so `get_run` and `list_runs` show spend so far rather than zero until the
 run finishes.
 
+To see your runs across every agent, call `list_runs` without an `agentId`
+(Wardby 0.8.0 and later). Each row names its agent and leaves out the final
+text; `active: true` keeps pending and running runs, and `since` (an ISO time)
+keeps runs that started or finished since then plus any still active. You see
+every run of the agents you own and only the runs you started on the others.
+`list_agents` with `summary: true` returns just each agent's id, name, kind,
+model, coding provider, budget, owner and your access, without the full
+configuration.
+
+From Wardby 0.8.0, `get_run` and `list_runs` without an `agentId` also return
+`triggerInfo` (the pull request or issue that started the run, and whether it
+was a review or a mention), `outcomes` (pull requests opened, comments, checks)
+and `serviceReadiness` (each coding-run service's state). They use the admin
+viewer API's shapes. Match one run's pull-request outcome to another run's
+trigger to follow a pull request through its review and fix rounds.
+
 To stop a run that is pending, queued, or running (for example one a schedule
 started that you did not want), call `stop_run` with its id. It ends as
 `cancelled`, along with the sub-agent runs it still has in flight. Search help

package/help/related-pull-requests.md

@@ -128,15 +128,19 @@ such hints: a fix round's task names only its own pull request. Merged and
 closed pull requests are never listed as continuable: a change there needs a
 new pull request, which joins the set once it is recorded.
 
+When the sub-agent is a coding agent with a list of repositories, a
+follow-up delegation passes `continuePriorRun` and takes its repository from
+that run, so it needs no `repository` of its own.
+
 Give your own delivery or router agent's system prompt a line such as:
 
     Continue the pull request you were asked about, and any listed open
     sibling the change requires; never open a new pull request in a
     repository that already has an open sibling for this request.
 
-The usual limits still apply: `maxDelegationsPerRun` and never delegating to
-the same sub-agent twice in one run; every push to a sibling pull request
-gets its own review; fix rounds are capped per pull request and only one
+The usual limits still apply: `maxDelegationsPerRun` and delegating to each
+sub-agent and repository at most once per run; every push to a sibling pull
+request gets its own review; fix rounds are capped per pull request and only one
 runs at a time on a pull request; and a continuation only ever reaches a
 sub-agent that shares the same owner as the one asked to continue it.
 

package/help/repo-instructions-and-skills.md

@@ -4,7 +4,7 @@ title: Repository instructions and skills in coding runs
 summary: What AGENTS.md, CLAUDE.md, and repo skills a coding run loads, and how to turn repo skills off per agent with codingProfile.repoSkills.
 audience: all
 tags: [coding, skills, repoSkills, claudeBareMode, CLAUDE.md, AGENTS.md, SKILL.md, codex, claude-code]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Repository instructions and skills in coding runs
@@ -81,6 +81,8 @@ never loaded in either mode.
 
 ## See also
 
+- [Remote MCP servers](../docs/mcp-servers.md) (0.8.0+) are for native agents only; a coding run loads no
+  MCP configuration.
 - [Choose a native or coding agent](creating-agents.md) for `codingProfile`
   basics and the other fields it accepts.
 - [Bring-Your-Own Coding-Worker Images](../docs/coding-worker-byo-images.md)

package/help/resume-runs-locally.md

@@ -129,3 +129,6 @@ or its runs fail at input with `worker_input_failed`.
 
 Full setup: [Resume a run locally](../docs/coding-agent-setup.md#resume-a-run-locally).
 See also [Choose a native or coding agent](help://creating-agents).
+
+The `wardby-runs` Claude Code plugin can start the import from a run's detail
+(**Continue locally**); see `claude-code-run-pane` (Wardby 0.8.0 and later).

package/help/stop-run.md

@@ -28,7 +28,7 @@ in its `stopRequestReason` (and, for a native run, in its `error`).
 | The run is                                 | `stop_run`                                                                                                                                                                                                     |
 | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Pending, or a coding run queued for a slot | Ends it now. It never starts.                                                                                                                                                                                  |
-| A running native run in the control plane  | Ends it now; the run stops at its next step (the model turn or tool call already under way finishes first).                                                                                                    |
+| A running native run in the control plane  | Ends it now; the run stops at its next step. A model turn already under way finishes first; a tool call already under way is aborted within a few seconds.                                                     |
 | A running native run in the sandbox        | Ends it now and ends its gateway session, so the worker's next call is refused and it exits. A worker still running after a short grace (5 seconds) is killed and removed; a warm pool worker is never reused. |
 | A running coding run                       | Ends it, cancels its model proxy session, and stops and removes its worker. It opens or updates no pull request afterwards.                                                                                    |
 | Already finished (any other status)        | Changes nothing and returns its status. Calling `stop_run` again is safe.                                                                                                                                      |

package/help/troubleshooting/coding-workers.md

@@ -3,7 +3,7 @@ id: troubleshooting/coding-workers
 title: Troubleshoot coding workers
 summary: Investigate coding-worker setup, isolation preflight, and safe failure handling.
 audience: operator
-tags: [coding-agents, quota, coding_queue_timeout, docker, kubernetes, isolation, services, debug-trace, debugTraceMinutes, debugTraceMaxMb, maxOutputTokens, output-tokens, claude-code, codex, memory, CODING_MEMORY_MB, CODING_CPUS, out-of-memory]
+tags: [coding-agents, get_run, request, requestUnavailable, quota, coding_queue_timeout, docker, kubernetes, isolation, services, debug-trace, debugTraceMinutes, debugTraceMaxMb, maxOutputTokens, output-tokens, claude-code, codex, memory, CODING_MEMORY_MB, CODING_CPUS, out-of-memory]
 appliesTo: >=0.2.1
 ---
 
@@ -95,6 +95,14 @@ commands run in a tool-runner container limited to at most 512 MiB and 0.25 CPU.
 3. For a Claude Code agent with heavy checks, run it on Codex instead, since raising
    the pod's memory doesn't raise the tool runner's limit.
 
+## See what a run was asked to do
+
+From Wardby 0.8.0, `get_run` returns a coding run's `request`: the task it
+received from `trigger_agent`, a webhook or a lead, without the agent's standing
+instructions. Use it to check what a lead told a coding agent. The agent's secret
+values and token-shaped values are masked. If the secrets can't be read, you get
+`requestUnavailable: true` instead of the text.
+
 ## Debug trace
 
 When a run's fixed error code or a slow run doesn't say enough, an admin can

package/help/troubleshooting/debugging-agent-runs.md

@@ -0,0 +1,29 @@
+---
+id: troubleshooting/debugging-agent-runs
+title: Debug an agent run
+summary: Triage a run that failed, opened no pull request, or missed what you expected, using the MCP tools and GitHub without server logs.
+audience: operator
+tags: [debugging, triage, get_run, list_runs, failureCategory, diagnosticId, get_run_transcript, no_changes]
+appliesTo: >=0.7.0
+---
+
+# Debug an agent run
+
+Find the run with `list_runs`, read it with `get_run`, then follow what you see.
+Without an `agentId`, `list_runs` lists your runs across every agent (from
+Wardby 0.8.0); add `active: true` or `since` to narrow it.
+
+| What you see                  | What to check                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------- |
+| No run started                | `list_repositories` on the router: is a link holding the trigger you used?                         |
+| Failed or refused             | `status`, `error`, `failureCategory` and the final text. Call `search_help` with the category      |
+| Lead ran, no coding run       | The lead's final text, which should say why it didn't delegate                                     |
+| Succeeded, no pull request    | `codingResult.outcome`: `no_changes`, `budget_exhausted`, or `branch_pushed` on a local repository |
+| Pull request missed the point | The diff, the review, the original request, and `request` on `get_run` (from Wardby 0.8.0)         |
+
+A failed coding run's specific reason is only in the server log. Send an operator
+the run ID and its `diagnosticId`. For Claude Code agents with `sessionResume` on,
+`get_run_transcript` shows what the agent did; see
+[Resume Claude Code runs locally](../resume-runs-locally.md).
+
+The full guide is [Debugging an agent run](../../docs/debugging-agent-runs.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardby/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Self-hosted control plane for budget-guarded AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/wardby/wardby#readme",
@@ -158,6 +158,7 @@
   },
   "overrides": {
     "deepmerge-ts": "8.0.2",
+    "minimatch": "11.0.3",
     "mysql2": "3.24.4",
     "uuid": "11.1.1"
   }

package/prisma/migrations/20261102000000_host_providers/migration.sql

@@ -0,0 +1,56 @@
+-- Tool-backed host providers: config and approved snapshots. No secret values.
+CREATE TABLE "HostProvider" (
+    "name" TEXT NOT NULL,
+    "contractVersion" INTEGER NOT NULL,
+    "gitHost" TEXT NOT NULL,
+    "apiHosts" TEXT[],
+    "gitUsername" TEXT NOT NULL,
+    "pullRequestUrlTemplate" TEXT NOT NULL,
+    "repositoryApiPath" TEXT NOT NULL,
+    "permissionApiPath" TEXT,
+    "webhook" JSONB NOT NULL,
+    "webhookSecretId" TEXT NOT NULL,
+    "permissionSecretId" TEXT,
+    "createdById" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    CONSTRAINT "HostProvider_pkey" PRIMARY KEY ("name")
+);
+
+CREATE TABLE "HostProviderOperation" (
+    "provider" TEXT NOT NULL,
+    "operation" TEXT NOT NULL,
+    "toolId" TEXT,
+    "code" TEXT NOT NULL,
+    "paramsZod" TEXT NOT NULL,
+    "approvedById" TEXT NOT NULL,
+    "approvedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "HostProviderOperation_pkey" PRIMARY KEY ("provider", "operation")
+);
+
+CREATE TABLE "HostProviderCredential" (
+    "id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "repositoryPattern" TEXT NOT NULL,
+    "secretId" TEXT NOT NULL,
+    "credentialKind" TEXT NOT NULL DEFAULT 'static',
+    CONSTRAINT "HostProviderCredential_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "HostProviderTrustedAccount" (
+    "provider" TEXT NOT NULL,
+    "accountId" TEXT NOT NULL,
+    "addedById" TEXT NOT NULL,
+    "addedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "HostProviderTrustedAccount_pkey" PRIMARY KEY ("provider", "accountId")
+);
+
+CREATE UNIQUE INDEX "HostProviderCredential_provider_repositoryPattern_key" ON "HostProviderCredential"("provider", "repositoryPattern");
+
+ALTER TABLE "HostProvider" ADD CONSTRAINT "HostProvider_webhookSecretId_fkey" FOREIGN KEY ("webhookSecretId") REFERENCES "Secret"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "HostProvider" ADD CONSTRAINT "HostProvider_permissionSecretId_fkey" FOREIGN KEY ("permissionSecretId") REFERENCES "Secret"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "HostProviderOperation" ADD CONSTRAINT "HostProviderOperation_provider_fkey" FOREIGN KEY ("provider") REFERENCES "HostProvider"("name") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "HostProviderOperation" ADD CONSTRAINT "HostProviderOperation_toolId_fkey" FOREIGN KEY ("toolId") REFERENCES "Tool"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+ALTER TABLE "HostProviderCredential" ADD CONSTRAINT "HostProviderCredential_provider_fkey" FOREIGN KEY ("provider") REFERENCES "HostProvider"("name") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "HostProviderCredential" ADD CONSTRAINT "HostProviderCredential_secretId_fkey" FOREIGN KEY ("secretId") REFERENCES "Secret"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "HostProviderTrustedAccount" ADD CONSTRAINT "HostProviderTrustedAccount_provider_fkey" FOREIGN KEY ("provider") REFERENCES "HostProvider"("name") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261104000000_coding_agent_repository_list/migration.sql

@@ -0,0 +1,5 @@
+-- A coding agent may work in several repositories: each link can name its own base
+-- branch, and a run records that its repository came from a link.
+ALTER TABLE "AgentRepository" ADD COLUMN "baseRef" TEXT;
+ALTER TABLE "CodingRun" ADD COLUMN "viaRepositoryLink" BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE "NativeGatewayCall" ADD COLUMN "childRepository" TEXT;

package/prisma/migrations/20261106000000_tool_timeout/migration.sql

@@ -0,0 +1,4 @@
+-- A sandboxed tool may set its own time limit per call, in milliseconds. Null keeps the
+-- default limit. A host provider's approved snapshot of a tool keeps the value it approved.
+ALTER TABLE "Tool" ADD COLUMN "timeoutMs" INTEGER;
+ALTER TABLE "HostProviderOperation" ADD COLUMN "timeoutMs" INTEGER;

package/prisma/migrations/20261107000000_mcp_servers/migration.sql

@@ -0,0 +1,33 @@
+-- Remote MCP servers an owner registers, and their attachments to native agents.
+CREATE TABLE "McpServer" (
+    "id" TEXT NOT NULL,
+    "ownerId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "url" TEXT NOT NULL,
+    "secretNames" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "toolSnapshot" JSONB NOT NULL DEFAULT '[]',
+    "snapshotAt" TIMESTAMP(3),
+    "serverInfo" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    CONSTRAINT "McpServer_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "AgentMcpServer" (
+    "agentId" TEXT NOT NULL,
+    "serverId" TEXT NOT NULL,
+    "allowedTools" TEXT[],
+    "callTimeoutMs" INTEGER,
+    "attachedById" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    CONSTRAINT "AgentMcpServer_pkey" PRIMARY KEY ("agentId", "serverId")
+);
+
+CREATE UNIQUE INDEX "McpServer_ownerId_name_key" ON "McpServer"("ownerId", "name");
+CREATE INDEX "McpServer_ownerId_idx" ON "McpServer"("ownerId");
+CREATE INDEX "AgentMcpServer_serverId_idx" ON "AgentMcpServer"("serverId");
+
+ALTER TABLE "McpServer" ADD CONSTRAINT "McpServer_ownerId_fkey" FOREIGN KEY ("ownerId") REFERENCES "Principal"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "AgentMcpServer" ADD CONSTRAINT "AgentMcpServer_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "Agent"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "AgentMcpServer" ADD CONSTRAINT "AgentMcpServer_serverId_fkey" FOREIGN KEY ("serverId") REFERENCES "McpServer"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261108000000_coding_mcp/migration.sql

@@ -0,0 +1,5 @@
+-- Coding runs: pinned MCP tools, the MCP token's hash, and a call counter.
+ALTER TABLE "CodingProxySession" ADD COLUMN "mcpTools" JSONB;
+ALTER TABLE "CodingProxySession" ADD COLUMN "mcpTokenHash" TEXT;
+ALTER TABLE "CodingProxySession" ADD COLUMN "mcpCallCount" INTEGER NOT NULL DEFAULT 0;
+CREATE UNIQUE INDEX "CodingProxySession_mcpTokenHash_key" ON "CodingProxySession"("mcpTokenHash");

package/prisma/migrations/20261109000000_task_run_index/migration.sql

@@ -0,0 +1,3 @@
+-- The run-drivability and cancelled-task lookups filter Task on (runId, status); the drivability
+-- check runs on every coding MCP request.
+CREATE INDEX "Task_runId_status_idx" ON "Task"("runId", "status");