@wardby/cli 0.7.0 → 0.9.0

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/low-power-mode.md

@@ -3,7 +3,7 @@ id: low-power-mode
 title: Low power mode on GKE
 summary: Low power mode: scale the coding proxy and native gateway to zero when idle to cut the cost of a lightly used GKE deployment, and what changes when they wake.
 audience: operator
-tags: [gke, cost, low-power, scale-to-zero, kubernetes, autoscaling, idle, power_sleep, power_status, sleep now, power:manage]
+tags: [gke, cost, low-power, scale-to-zero, kubernetes, autoscaling, idle, power_sleep, power_status, sleep now, power:manage, mcp, coding-agents]
 appliesTo: ">=0.6.0"
 ---
 
@@ -38,14 +38,20 @@ only when `WARDBY_LOW_POWER=1`.
 - **Sleep.** Every minute the scheduler leader scales the coding proxy
   (`wardby-coding-proxy`) or native gateway (`wardby-native-gateway`) to 0 when
   nothing is pending or running for it and nothing finished within the idle
-  window. The gateway also needs no active session. Either target sleeps only
+  window. For the gateway that means sandbox runs and coding runs with MCP
+  tools, and it also needs no active session. Either target sleeps only
   once at least one idle window has passed since it was last woken (annotation
   `wardby.io/power-woke-at`) and since the control plane started, whichever is
   later. The check repeats just before scaling. Log: `power: proxy slept (idle 30m)`.
 - **Wake.** A coding run scales the proxy to 1 and waits for a ready endpoint;
-  a sandbox run does the same for the gateway. The wait is at least 5 minutes.
-  A `KUBERNETES_READY_TIMEOUT_MS` (proxy) or `NATIVE_SANDBOX_READY_TIMEOUT_MS`
-  (gateway) above that, set on the control-plane Deployment, raises it. Expect
+  a sandbox run does the same for the gateway. A coding run with MCP tools
+  wakes both at once, because its MCP calls go through the gateway; if the
+  gateway does not wake it fails before launch with
+  [`coding_failure_mcp_gateway_unavailable`](errors/coding-mcp-gateway-unavailable.md).
+  The wait is at least 5 minutes.
+  A `KUBERNETES_READY_TIMEOUT_MS` (the proxy, and the gateway wake of a coding
+  run) or `NATIVE_SANDBOX_READY_TIMEOUT_MS` (the gateway wake of a sandbox run)
+  above that, set on the control-plane Deployment, raises it. Expect
   about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`. A
   sandbox run woken this way may then wait for a gVisor node for its worker
   pod, so its first model call can come several minutes after it started. From
@@ -71,15 +77,17 @@ Pass `target: "proxy"` or `target: "gateway"` to sleep one; omit it for both.
 
 - It scales the target to 0 at once, ignoring the idle window and the woke-at
   grace.
-- It never stops a run. A target with a pending or running run, or for the
-  gateway an active gateway session, stays up, and its run ids are returned:
+- It never stops a run. A target with a pending or running run (for the
+  gateway, a sandbox run or a coding run with MCP tools), or for the gateway an
+  active gateway session, stays up, and its run ids are returned:
   `{ "slept": ["proxy"], "blocked": [{ "target": "gateway", "runIds": ["..."] }] }`.
   Recently finished runs do not block it.
 - The next run wakes the target as usual.
 - Each call is logged with `event: "power.sleep"` and the caller's principal.
 
 `power_status` returns, for each target, `replicas`, `ready`, `wokeAt` and
-`blockers` (the run ids keeping it busy).
+`blockers` (the run ids keeping it busy; for the gateway these include
+pending or running coding runs with MCP tools).
 
 Both tools need the `power:manage` scope, which only the `admin` role grants
 (see [Identity and access](identity-and-access.md)). With the mode off,
@@ -111,6 +119,9 @@ full table.
 
 - [`low_power_wake_timeout`](errors/low-power-wake-timeout.md): the target did
   not become ready in time, or its Deployment does not exist.
+- [`coding_failure_mcp_gateway_unavailable`](errors/coding-mcp-gateway-unavailable.md):
+  a coding run with MCP tools failed before launch because the gateway did not
+  wake.
 - `native_sandbox_launch_abandoned` (0.7.0 and later): a sandbox run was
   stopped while the gateway woke, so no worker pod was made.
 - [`low_power_disabled`](errors/low-power-disabled.md): `power_sleep` was

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,10 @@ 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).
+
+To follow what a run is doing, call `get_run_steps` (article `run-steps`).

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

@@ -49,6 +49,10 @@ blob store nothing is stored, and `update_agent` warns you.
   (default 10 MiB, at most 64 MiB). Each run records a status (`stored`,
   `too_large`, `not_captured` or `failed`) with a reason code.
 
+For a short line-per-step record of any run, without a blob store and without
+continuing it, see `run-steps`; from 0.9.0 its `detail` level is a lighter way to
+see tool output without a transcript.
+
 ## Who can read it
 
 Transcripts are stored from the first run with `sessionResume` on. Anyone
@@ -129,3 +133,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/run-steps.md

@@ -0,0 +1,140 @@
+---
+id: run-steps
+title: See what a run is doing (run steps)
+summary: Wardby records each run's steps, one line per tool call or model message, so you can follow a running run and read what a finished one did with get_run_steps. Run steps detail adds tool output.
+audience: operator
+tags: [run steps, claude code run steps, get_run_steps, what is my run doing, WARDBY_RUN_STEPS, viewer step event]
+appliesTo: >=0.9.0
+---
+
+# See what a run is doing
+
+Wardby records the steps of a run while it runs:
+
+- one line for each **tool call**: the tool, and its command, file or first
+  argument, cut to about 100 characters, with its status once the result is
+  back (`ok`, `error`, or `exit N` for a command that exited with code N);
+- one line for what the **model said**, cut to about 120 characters.
+
+## Levels
+
+| Level     | Tool input           | Tool result                             | Model text           |
+| --------- | -------------------- | --------------------------------------- | -------------------- |
+| `off`     | -                    | -                                       | -                    |
+| `summary` | about 100 characters | status only (`ok`, `error`, `exit N`)   | about 120 characters |
+| `detail`  | up to about 4 KB     | status and the last ~2 KB of its output | up to about 8 KB     |
+
+At `summary`, the default, tool output is never recorded. At `detail` each step
+also keeps a **detail** text, at most 16 KB. When the output is cut at the
+start, the partial first line is dropped if it ends within 256 characters;
+otherwise only the first 256 characters are dropped, so a long single-line
+output, such as a JSON result, keeps about its last 1.8 KB. At every level,
+terminal escape sequences (colour codes, links, clipboard writes, title changes)
+and every other control character except line breaks and tabs are removed from
+step text before it is stored.
+
+A run's level is the lower of two settings, fixed when the run is dispatched (a
+change reaches later runs only; lowering the ceiling also stops detail for runs
+already in flight):
+
+- the instance's ceiling, `WARDBY_RUN_STEPS` (default `summary`);
+- the agent's `runSteps` (`off`, `summary` or `detail`), set by the agent's
+  owner with `create_agent` or `update_agent`. Unset counts as `summary`. Set
+  `null` to clear it.
+
+So `detail` needs both the operator and the agent's owner. If `runSteps` asks
+for more than the instance allows, the value is stored, `update_agent` and
+`get_agent` say so in `warnings`, and runs record at the ceiling.
+
+> **Warning: `detail` stores tool output.** Before a step is stored, every
+> secret value the run was given is removed and anything shaped like a token or
+> key is masked. A secret that exists only inside a repository file, or another
+> source the run read, and that matches no known shape, is not known to Wardby
+> and can remain in the detail text. That is why detail is off unless both the
+> operator and the agent's owner ask for it. Turn it on only for agents whose
+> tool output you are prepared to keep for the retention period.
+
+Steps are recorded for native runs (in the control plane and on the native
+sandbox) and for Claude Code and Codex runs. Every agent's shell command shows
+as `Bash`: a native agent's `run_command`, Claude Code's command tool, and
+Codex's `exec_command`, `shell`, `local_shell` and `shell_command`. Another tool
+shows under its own name (for example `apply_patch`), and a remote MCP tool as
+`mcp:<tool>`.
+
+A Claude Code or Codex run's final answer is one `said` step: the start of the
+summary it returned (the pull request description), or `Finished` with the
+outcome (for example `Finished: changes ready`) when it returned none.
+
+For Claude Code and Codex runs, the coding proxy reads the steps from the
+model's replies after relaying them and posts them to the server, which needs a
+listener for them: `WARDBY_RUN_STEPS_LISTEN` on `wardby serve` and
+`WARDBY_RUN_STEPS_URL` on the proxy. The reference GKE manifests set both; the
+kind overlay sets only `WARDBY_RUN_STEPS_URL`, so set
+`WARDBY_RUN_STEPS_LISTEN` on the host's `wardby serve`. Without either, coding
+runs record no steps; native runs are not affected. A slow or unreachable listener loses steps; it never slows the run.
+
+## Read the steps
+
+- `get_run_steps` with `runId` lists a run's steps, oldest first, 50 at a time
+  (`limit`, at most 200). `next` is what to pass as `after` for the next page.
+  To follow a running run, call it again every few seconds with `after` set to
+  the last `seq` you have.
+- `get_run` and `list_runs` (without `agentId`) include `lastStep`, the run's
+  newest step as one line, for example `Bash: npm test (exit 1)`.
+- The `wardby-runs` Claude Code pane shows a running run's last steps and a
+  finished run's steps; see `claude-code-run-pane`.
+- The admin viewer API sends a `step` event on `/admin/api/events` for each
+  step and status, and `GET /admin/api/runs/<id>` lists the run's newest 200
+  steps (see `admin-viewer`). The Wardby Viewer app shows them in a **Steps**
+  section of a run's detail.
+
+At `detail`, `get_run_steps` also returns each step's `detail` to the agent's
+owner and to the person who started the run (and to the stdio operator); anyone
+else, including an admin who does not own the agent, gets the lines only. `lastStep`, the admin viewer API
+and its `step` events never include detail.
+
+You can read a run's steps when you can read the run with `get_run`.
+
+A run records at most 2,000 steps. Later steps are not recorded; `dropped`
+counts them.
+
+## Secrets
+
+Before a step is stored, Wardby removes every secret value the run's agent has
+(its attached secrets, readable or brokered, and its MCP servers' secrets), the
+run's own capability and registry token, and
+anything shaped like a token or key. A command that echoes a secret shows
+`[REDACTED]` in its place.
+
+## Retention
+
+Steps, and their detail, are deleted `RUN_STEP_RETENTION_DAYS` after they are
+recorded (default 30). A change applies to steps recorded after it. `get_run_steps` reports `expired` when a run finished more than
+`RUN_STEP_RETENTION_DAYS` ago and has no steps left.
+
+## Settings
+
+| Variable                  | Default   | What it does                                                                                                                                                                        |
+| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_RUN_STEPS`        | `summary` | `off` records no steps; `summary` the lines above; `detail` allows agents whose `runSteps` is `detail` to record detail. The ceiling for every run. Any other value stops start-up. |
+| `RUN_STEP_RETENTION_DAYS` | `30`      | Days to keep a step, a whole number from 1 to 3650. Any other value stops start-up.                                                                                                 |
+| `WARDBY_RUN_STEPS_LISTEN` | unset     | On `wardby serve` only: `host:port` (or `:port`) of the listener the coding proxy posts coding runs' steps to. Unset: no listener.                                                  |
+| `WARDBY_RUN_STEPS_URL`    | unset     | On the coding proxy: the listener's origin, for example `http://<server host>:8792`, with no credentials or path. Unset: coding runs record no steps.                               |
+
+Set `WARDBY_RUN_STEPS` (including `detail`) and `RUN_STEP_RETENTION_DAYS` on
+every process that writes steps: `wardby serve`,
+`wardby scheduler`, `wardby run`, `wardby mcp` and `wardby native-gateway`. The
+coding proxy reads `WARDBY_RUN_STEPS` too: with `off`, or with
+`WARDBY_RUN_STEPS_URL` unset, no step text leaves the proxy. For a coding
+run's steps use `wardby serve` (the only process that runs the listener), not
+the stdio `wardby mcp`.
+
+For coding runs at `detail`, set `WARDBY_RUN_STEPS=detail` on the coding proxy
+too: below `detail`, the proxy never sends any tool output to the server.
+
+The listener is a second network path into the server, from the coding proxy
+only; keep it off any load balancer. See
+[Run steps](../docs/security-deployment.md#run-steps) for how to restrict it.
+
+The full guide is
+[Debugging agent runs](../docs/debugging-agent-runs.md#run-steps).

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