ghostlab 0.3.0__tar.gz → 0.4.0__tar.gz

{ghostlab-0.3.0 → ghostlab-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: ghostlab
-Version: 0.3.0
-Summary: OpenShell-first end-to-end evaluation lab for configured AI agents, MCP servers, skills, and MCP Apps.
+Version: 0.4.0
+Summary: Define an AI agent once (model, instructions, skills, MCPs) and run or evaluate it in Claude Code, Codex, Copilot, or OpenCode, sandboxed in NVIDIA OpenShell.
 Project-URL: Documentation, https://sajjadgg.github.io/Ghostlab/
 Project-URL: Homepage, https://github.com/sajjadGG/Ghostlab
 Project-URL: Repository, https://github.com/sajjadGG/Ghostlab
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/sajjadGG/Ghostlab/releases
 Author: SajjadGG
 License: MIT
 License-File: LICENSE
-Keywords: agents,ai-agents,claude,cli,codex,end-to-end-testing,evaluation,llm,llm-evaluation,mcp,mcp-apps,model-context-protocol,testing
+Keywords: agent-skills,agents,ai-agents,claude,claude-code,cli,codex,end-to-end-testing,evaluation,github-copilot,llm,llm-evaluation,mcp,mcp-apps,model-context-protocol,opencode,openshell,sandbox,testing
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -42,48 +42,42 @@ Description-Content-Type: text/markdown
 
 # Ghostlab
 
-> A local, end-to-end **testing lab for configured AI agents** — coding agents role-play
-> real users, drive your tools over multiple turns, and the harness captures
-> traces, scores outcomes, and even **renders and clicks through MCP Apps UI
-> widgets**.
+> **Define an agent once — model, instructions, skills, MCPs, workspace — and run
+> it in any coding-agent harness, sandboxed in NVIDIA OpenShell.** Use it to get
+> a task done, or to evaluate how well the agent does its job.
 
 [![CI](https://github.com/sajjadGG/Ghostlab/actions/workflows/ci.yml/badge.svg)](https://github.com/sajjadGG/Ghostlab/actions)
+[![PyPI](https://img.shields.io/pypi/v/ghostlab)](https://pypi.org/project/ghostlab/)
 [![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://sajjadgg.github.io/Ghostlab/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![llms.txt](https://img.shields.io/badge/llms.txt-✓-purple)](llms.txt)
 
-**Test an agent the way it is actually used** — not only with unit tests against
-the protocol, but with a real coding agent (Codex / Claude) that picks tools,
-makes mistakes, and tries to accomplish goals, while a second agent plays the
-user. Protocol-level checks (schema errors, a tool call that 500s) are useful
-sanity checks, but they aren't the real test — the real test is whether an
-agent can actually get a task done with its configured MCPs, skills, workspace,
-instructions, and runner, end to end.
-
 📖 **Docs wiki:** https://sajjadgg.github.io/Ghostlab/ · 🤖 **For agents:** [`llms.txt`](llms.txt) · 🛠 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
 
-> **Naming:** the project and repo are **Ghostlab** (formerly *Rehearsal*). The CLI
-> is `ghostlab`, with `rehearsal` kept as an alias, and the installed Python
-> package is `rehearsal` — all the same project.
-
 <p align="center">
 <img src="static/ghostlablogo.png" width="400" alt="Logo" align="center">
 </p>
 
-## Quickstart
+Ghostlab does three things with one agent definition:
 
-```bash
-python3 -m venv .venv                # Python 3.10+
-.venv/bin/pip install -e .            # add '.[ui]' for the web UI, '.[apps]' for widget rendering
+| | Command | What you get |
+| --- | --- | --- |
+| **Run** | `ghostlab exec` | The agent does a task in Claude Code, Codex, GitHub Copilot CLI, or OpenCode — inside a throwaway OpenShell sandbox — and you get its answer, tool trace, and any files it produced. |
+| **Evaluate** | `ghostlab lab` / `create` → `test` → `review` | A second agent plays realistic users, drives the configured agent over multiple turns, and a judge scores the outcome against a release gate. |
+| **Build eval sets** | `ghostlab create --target` / `--skill`, `generate-dataset` | Persona × scenario test sets generated from an MCP server's tools or a skill's `SKILL.md`, curated as files, rerunnable in CI. |
 
-ghostlab create                       # evaluate an MCP server
-ghostlab lab                          # evaluate a configured agent (model, skills, MCPs, code)
+> **Naming:** the CLI is `ghostlab` (with `rehearsal` kept as an alias) and the
+> installed Python package is `rehearsal` — all the same project.
+
+## Install
+
+```bash
+pip install ghostlab                  # add [ui] for the web UI, [apps] for MCP Apps rendering
+ghostlab doctor                       # checks OpenShell and the agent CLIs
 ```
 
-Pick `create` when the thing under test is an **MCP server**, and
-[`lab`](#evaluate-a-configured-agent-ghostlab-lab) when it is an **agent** — a
-model plus instructions, skills, MCPs, permissions, and a codebase.
+From a checkout: `python3 -m venv .venv && .venv/bin/pip install -e .`
 
 Ghostlab uses [NVIDIA OpenShell](https://docs.nvidia.com/openshell/latest/)
 as its default execution boundary. Install OpenShell, start a supported compute
@@ -103,6 +97,65 @@ brew services restart openshell
 openshell status
 ```
 
+## Run an agent: `ghostlab exec`
+
+Describe the agent in one file:
+
+```json
+{
+  "id": "release-helper",
+  "instructions": "Be concise. Never claim something was published.",
+  "runtime": { "backend": "claude", "model": "sonnet" },
+  "workspace": "repo",
+  "inputs": {
+    "mcps":   [{ "config_ref": "mcp.json", "server": "tiny" }],
+    "skills": ["skills/release-notes"]
+  },
+  "sandbox": { "backend": "openshell", "providers": ["anthropic"] }
+}
+```
+
+Then hand it a task:
+
+```bash
+ghostlab exec --agent agent.json "Draft release notes from CHANGELOG.md"
+ghostlab exec --agent agent.json --backend copilot --model gpt-5-mini --provider copilot "..."
+ghostlab exec --agent agent.json --prompt-file task.md --export /sandbox/repo/NOTES.md > answer.md
+```
+
+The answer goes to stdout; status goes to stderr; the full trace — composed
+prompt, raw harness stream, every MCP and built-in tool call, and
+`exec.json` — is kept under `runs/`. The same definition runs in every harness:
+
+| `runtime.backend` | Harness | How MCPs attach | How skills attach |
+| --- | --- | --- | --- |
+| `claude` | Claude Code (`claude -p`) | `--mcp-config` (strict), MCP tools pre-approved | Prompt preamble |
+| `codex` | Codex (`codex exec --json`) | `-c mcp_servers.*` overrides | Prompt preamble |
+| `copilot` | GitHub Copilot CLI | `--additional-mcp-config` | Prompt preamble |
+| `opencode` | OpenCode (`opencode run`) | Generated `opencode.json` | Native `skills.paths` |
+| `runner` | Any CLI in `runner.command` | Your command | Prompt preamble |
+
+Under OpenShell (the default), the agent CLI, its stdio MCP servers, its skills,
+and an uploaded copy of its workspace all live in one sandbox that is deleted
+afterwards; credentials arrive through OpenShell providers (`--provider`) and
+nothing on the host is touched. The OpenShell `base` image already ships all
+four harness CLIs. `--sandbox local` runs on your machine and edits the
+workspace in place — use it only for trusted agents. See
+[Run an Agent](docs/run-an-agent.md).
+
+## Evaluate an agent, an MCP server, or a skill
+
+```bash
+ghostlab lab                          # evaluate a configured agent (model, skills, MCPs, code)
+ghostlab create                       # evaluate an MCP server or a skill
+```
+
+Pick [`lab`](#evaluate-a-configured-agent-ghostlab-lab) when the thing under
+test is an **agent** — a model plus instructions, skills, MCPs, permissions,
+and a codebase — and `create` when it is an **MCP server** or a **skill**. The agent under test
+can run in Codex, OpenCode, GitHub Copilot CLI, or Claude Code
+(`--aut-backend claude`).
+
 OpenShell is the default; there is no `--local` flag. Use the explicit
 `--sandbox local` escape hatch only for trusted code that you intentionally
 want to execute directly on the host:
@@ -121,11 +174,12 @@ logs with the run artifacts, and deletes the sandboxes at teardown. Local stdio
 MCP processes in the job pipeline are routed through the same boundary. OpenShell failures remain
 `harness_error`s and never silently fall back to host execution.
 
-That's the whole flow. Interactive `ghostlab create` guides you through the
+Interactive `ghostlab create` guides you through the
 evaluation subject (agent/MCP/skill), OpenShell image/providers, generation
-size, four model roles (AUT, user emulator, generation, and judge), Codex
-approval/sandbox policy, runner lifecycle/timeout, release gate, and whether to
-run immediately. The Questionary/Rich terminal UI provides arrow-key selection,
+size, four model roles (AUT, user emulator, generation, and judge), separate AUT
+and user runner backends, Copilot/VS Code custom-agent names, runner policy,
+lifecycle/timeout, release gate, and whether to run immediately. The
+Questionary/Rich terminal UI provides arrow-key selection,
 multi-select suite picking, color, and numbered progress. The same choices
 remain available as flags for scripts and CI.
 
@@ -135,9 +189,10 @@ remain available as flags for scripts and CI.
    skills, workspace, and assets. `--target` and `--skill` remain simple shorthands.
 2. **Discover** — connects to the target, lints its contract (schema errors,
    risk labels), and probes any MCP Apps `ui://` widgets.
-3. **Configure semantic testing** — wires the configured runner (Codex by
-   default) as the **agent-under-test** and displays its exact command, model,
-   approval mode, nested sandbox, parser, and timeout.
+3. **Configure semantic testing** — wires the configured runner (Codex,
+   OpenCode, or GitHub Copilot CLI) as the **agent-under-test** and displays its
+   exact command, model, custom agent, policy, parser, and timeout. The user
+   emulator receives a separate runner and never receives the AUT's target MCP.
 4. **Generate a test plan** — personas × scenarios for the semantic/security
    suites, plus deterministic coverage for every discovered tool
    (`test-plan.yaml`), all editable afterward.
@@ -229,31 +284,6 @@ reasoning, and the full dual-agent transcript with inline tool calls:
 <img src="static/case-report-transcript.png" width="760" alt="Per-case report with judge verdict and conversation transcript">
 </p>
 
-## Goal
-
-Build a repeatable, sandboxed tester that can:
-
-- Run arbitrary configured agents inside NVIDIA OpenShell.
-- Compose zero or more MCPs, skills, instructions, workspace files, and assets.
-- Launch one coding-agent session as the **agent-under-test**.
-- Launch another coding-agent session as the **user emulator** (persona + goal driven).
-- Drive multi-turn interactions between them.
-- Capture full traces, tool activity, failures, and outcomes.
-
-This lets you test with your existing Codex/Claude usage path, instead of wiring a separate LLM provider deployment just for E2E testing.
-
-## Scope
-
-Ghostlab is intentionally **app-agnostic**:
-
-- Treats an agent configuration—not a single MCP—as the evaluation boundary.
-- Works with MCP servers reachable by stdio/SSE/streamable HTTP and local skills.
-- Supports local or remote MCP endpoints.
-- Supports multiple coding-agent runners (Codex, OpenCode, Claude Code, and future adapters).
-- Expresses an OpenCode agent's full configuration — model, instructions, skills, subagents, tool permissions, and any number of MCPs — and runs all of it inside the sandbox.
-
-No Cortex-specific assumptions are required in the core harness.
-
 ## Reference
 
 Everything below is the individual-command reference and advanced usage —
@@ -311,8 +341,9 @@ primary discovery input for one-MCP/one-skill jobs:
 - `capabilities`: optional expected tools/resources/prompts
 - `startup`: optional health checks and boot timeout
 
-The canonical `agent` section contains `runner`, `instructions`, and composable
-`inputs.mcps`, `inputs.skills`, and assets. The sibling `sandbox` section defaults
+The canonical `agent` section contains a `runtime` (harness backend, model,
+and harness-specific settings) or a raw `runner`, `instructions`, and composable
+`inputs.mcps`, `inputs.skills`, and assets — the same file `ghostlab exec` runs. The sibling `sandbox` section defaults
 to OpenShell and controls the image, uploads, workdir, policy, resource limits,
 network mode, environment allowlist, providers, logs, and cleanup.
 `backend: local` is explicit unsandboxed compatibility—not a fallback.
@@ -321,6 +352,7 @@ network mode, environment allowlist, providers, logs, and cleanup.
 
 The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 
+- `ghostlab exec` — run a configured agent on one task in any harness (Claude Code, Codex, Copilot, OpenCode), inside OpenShell, and print its answer.
 - `ghostlab lab` — guided setup for a **configured agent** (model, instructions, skills, MCPs, permissions, code), then generate scenarios from its inferred purpose and run them fully sandboxed.
 - `ghostlab create` — the end-to-end wizard described above.
 - `ghostlab init` — advanced: scaffold a standalone `ghostlab.yaml` **spec** from a target JSON (see [spec vs job](#spec-vs-job) — most users want `ghostlab create`).
@@ -335,7 +367,9 @@ The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 - `ghostlab run` — run one dual-agent E2E scenario directly.
 - `ghostlab evaluate` — score a run into a pass/fail verdict (codex judge).
 - `ghostlab critique` — rate a run's tool ergonomics from the agent's perspective (codex).
-- `ghostlab scorecard` — roll run verdicts and critiques into a summary scorecard.
+- `ghostlab scorecard` — roll run verdicts and critiques into a summary scorecard, or aggregate benchmark attempts with `--attempts`.
+- `ghostlab artifact-run` — run one configured agent once on a mutable workspace and export what it produced.
+- `ghostlab scorer-run` — score an exported candidate workspace with a hidden scorer package.
 - `ghostlab compare` — diff two dataset runs for regressions.
 - `ghostlab apps-probe` / `apps-render` — probe/render MCP Apps `ui://` widgets.
 - `ghostlab doctor` — check the sandbox and both LLM backends (`--probe` for a live check).
@@ -553,13 +587,13 @@ persona-specific scenarios, and the pairs become runnable cases:
 ghostlab generate-dataset \
   --profile runs/<id>-inspect/capabilities.json \
   --personas 3 --scenarios-per-persona 3 --seed 7 \
-  --name cortex
+  --name my-mcp
 ```
 
 This writes a self-contained dataset directory:
 
 ```text
-datasets/cortex/
+datasets/my-mcp/
   dataset.json          manifest: mcp, seed, cases[]
   personas/<id>.json
   scenarios/<id>.json    persona-namespaced; inline `persona` is a situational note
@@ -571,7 +605,7 @@ Before spending agent credits, check that the dataset makes sense:
 
 ```bash
 ghostlab review-dataset \
-  --dataset datasets/cortex \
+  --dataset datasets/my-mcp \
   --profile runs/<id>-inspect/capabilities.json
 ```
 
@@ -581,7 +615,7 @@ tools, personas with no scenarios). Curation is file-first — each case gets a
 `status` in `dataset.json` (`pending` / `approved` / `rejected` / `needs-edit`):
 
 ```bash
-ghostlab review-dataset --dataset datasets/cortex \
+ghostlab review-dataset --dataset datasets/my-mcp \
   --approve case-a case-b --reject case-c
 ```
 
@@ -589,9 +623,9 @@ ghostlab review-dataset --dataset datasets/cortex \
 
 ```bash
 ghostlab run-dataset \
-  --dataset datasets/cortex \
+  --dataset datasets/my-mcp \
   --target target.json \
-  --aut-runner runners/codex-cortex-aut.json \
+  --aut-runner runners/codex-aut.example.json \
   --user-runner runners/codex-user-emulator.json \
   --provider openai \
   --limit 2
@@ -634,6 +668,70 @@ ghostlab compare --base runs/<base>-summary --candidate runs/<cand>-summary \
 Diffs case-by-case on verdict, listing regressions first, then fixes, then
 other changes. Exits non-zero when there are regressions, so it can gate CI.
 
+### Benchmark a coding agent: `artifact-run` / `scorer-run`
+
+`run` evaluates a conversation. A benchmark task is the opposite shape: one
+message, a repository the agent may rewrite, and a verdict that depends only on
+the state it left behind. Two commands cover it, and neither one creates a user
+emulator.
+
+```bash
+ghostlab artifact-run \
+  --agent agents/candidate.json \
+  --workspace <materialized-base-repo> \
+  --prompt-file tasks/<task_id>/public/prompt.txt \
+  --sandbox-image 'project@sha256:<digest>' \
+  --setup-command '["python3","-m","venv",".venv"]' \
+  --optional-export /sandbox/output/notes.json=notes.json \
+  --export-workspace candidate-state.tar.zst \
+  --run-dir attempts/<attempt_id>
+
+ghostlab scorer-run \
+  --task tasks/<task_id>/public/task.json \
+  --scorer tasks/<task_id>/private/scorer/scorer.json \
+  --candidate attempts/<attempt_id>/candidate-state.tar.zst \
+  --trace attempts/<attempt_id>/events.jsonl \
+  --output attempts/<attempt_id>/score-report.json
+```
+
+The workspace is uploaded into an OpenShell sandbox, so the agent edits a
+throwaway copy. Before that sandbox is deleted, `--export-workspace` takes a
+canonical export: sorted paths with modes, sizes, and SHA-256 hashes in
+`status.json`, a `diff.patch`, an `untracked.json`, and a deterministic archive
+of exactly those files. Changed and untracked files are kept; `.git/` and the
+usual build and cache directories are not. The post-run workspace hash is
+recorded even without an archive. Required `--export` paths fail the run when
+absent; `--optional-export` paths are downloaded only when present.
+`--sandbox-image` replaces the agent definition's image with the task's pinned
+project environment, and repeatable `--setup-command` values are JSON argument
+arrays executed in that same sandbox before the agent turn. Artifact runs
+require a root-owned `/usr/bin/python3` with the standard library; Ghostlab
+validates that trusted exporter runtime before it sends the prompt and verifies
+the downloaded archive against `status.json` before accepting the candidate
+state.
+
+`scorer-run` never reuses the agent's sandbox. The candidate is mounted
+read-only at the path supplied by `repo_path`, hidden fixtures live at
+`GHOSTLAB_FIXTURES_ROOT`, and only `GHOSTLAB_OUTPUT_ROOT` and `/tmp` are
+writable. OpenShell 0.0.80 requires these roots below `/sandbox`; scorers must
+use the score input and `GHOSTLAB_*_ROOT` variables rather than hard-code the
+logical manifest paths. A fail-closed Landlock launcher applies this boundary
+to the scorer process. A scorer that executes candidate code must invoke it
+through `GHOSTLAB_SECURE_EXEC` (or an equivalently restrictive nested sandbox)
+without granting fixture, input, scorer, or report access. The agent's trace is
+redacted down to tool and timing evidence first, so the scorer cannot see who
+produced the candidate. The deterministic phase runs with no network and no
+provider credentials; a hybrid scorer's residual judge gets provider access
+in a second sandbox that cannot execute anything. Ghostlab computes the total
+outside both sandboxes: weights must sum to `1.0`, a failed hard gate forces
+`0`, and unscored soft components are reported rather than renormalized away.
+Scorer crashes, timeouts, judge outages, and unusable candidate artifacts get
+their own statuses and are never turned into a zero.
+
+`ghostlab scorecard --attempts <dir>` then rolls attempts up with equal weight
+per rollout source, reporting pass rate, per-component means, seed spread,
+valid coverage, and the error counts it deliberately excluded from the score.
+
 ### MCP Apps: `apps-probe` / `apps-render`
 
 Some MCPs ship **MCP Apps UI** resources — a tool's `_meta.ui.resourceUri`
@@ -667,21 +765,21 @@ if the render errored or any assertion failed.
 ### Session runner (one live agent across turns)
 
 By default each turn spawns a fresh agent process and the orchestrator replays
-the transcript. The session runner (`"kind": "codex-session"`) instead keeps
-one codex session alive: turn 1 records the `thread_id`, and later turns run
-`codex exec resume <thread_id>` so codex retains context — fewer tokens, no
-repeated cold-start noise.
+the transcript. Stateful runners keep native agent context: `codex-session`
+captures a Codex `thread_id` and resumes it, while `copilot-session` assigns one
+Copilot `--session-id` to every turn. Both avoid repeated cold starts and prompt
+replay.
 
 ```bash
 ghostlab run --target target.json --scenario <scenario.json> \
-  --aut-runner runners/codex-cortex-local-session.json --user-runner <user.json>
+  --aut-runner runners/codex-session.example.json --user-runner <user.json>
 ```
 
 ### Validate your setup: `doctor`
 
 ```bash
 ghostlab doctor               # validates runners/*.json
-ghostlab doctor --runners runners/codex-cortex-local-session.json
+ghostlab doctor --runners runners/codex-session.example.json
 ghostlab doctor --sandbox local  # trusted local mode; skips OpenShell checks
 ```
 
@@ -690,7 +788,7 @@ validates each runner's kind, command, and parser, and checks the OpenShell
 CLI/gateway by default. Add `--probe` to verify a backend can actually answer
 instead of only confirming its binary exists.
 
-### Coding-agent backends (codex or opencode)
+### Generation and judge backends (codex or opencode)
 
 Ghostlab drives a coding-agent CLI for generation, the agent-under-test, and
 judging. `inspect` needs no agent — it is a direct MCP client.
@@ -742,12 +840,12 @@ pass/fail/skip verdicts, gate failures). Set `NO_COLOR=1` (or
 `GHOSTLAB_COLOR=0`) to disable it, `GHOSTLAB_COLOR=1` to force it on (e.g.
 piping into a pager that groks ANSI).
 
-Use `ghostlab config --job <name>` to see the exact effective Codex command,
-model, approval policy, nested sandbox, runner parser/timeout, all four model
-roles, composed MCP/skill inputs, and OpenShell configuration. Add `--json` for
-machine-readable output. If a command omits `-m`, Ghostlab resolves the
-top-level model from Codex's `config.toml` and identifies that source. The
-Streamlit Overview and Configure tab expose the same values.
+Use `ghostlab config --job <name>` to see the exact effective AUT and user
+runner commands, backend/model/custom-agent selection, policy, parser/timeout,
+all four model roles, composed MCP/skill inputs, and OpenShell configuration.
+Add `--json` for machine-readable output. If a Codex command omits `-m`,
+Ghostlab resolves the top-level model from Codex's `config.toml` and identifies
+that source. The Streamlit Overview and Configure tab expose the same values.
 
 ## Runner Configs
 
@@ -771,7 +869,9 @@ Process runner:
 
 The process runner starts one fresh process per turn. `prompt_mode` can be
 `stdin`, `append-arg`, or `replace-placeholder`. `ghostlab create` synthesizes
-one of these automatically for the agent-under-test host (wiring the target
+separate `jobs/<name>/runners/aut.json` and
+`jobs/<name>/runners/user.json` files. The AUT receives the target MCP while
+the user emulator explicitly does not. Codex wires the target
 MCP in via codex's `-c mcp_servers.<id>...` overrides, including
 `bearer_token_env_var` for `Bearer ${VAR}`-style auth headers) — see
 `jobs/<name>/runners/aut.json` after running it. To use Claude Code or another
@@ -780,12 +880,30 @@ agent as the AUT instead, hand-write a runner JSON (see
 `ghostlab create`/`ghostlab plan`, or add it directly under `hosts:` in
 `job.yaml`.
 
-## Install from PyPI
+GitHub Copilot CLI is a native runner, including custom agents shared with VS
+Code:
 
 ```bash
-pip install ghostlab            # add [ui] and/or [apps] for those extras
-ghostlab --help
-```
+ghostlab create --name copilot-eval --target https://example.com/mcp \
+  --aut-backend copilot --user-backend copilot \
+  --model gpt-5.4 --user-model gpt-5-mini \
+  --aut-agent release-reviewer --user-agent realistic-user \
+  --aut-reasoning-effort high --aut-context long_context \
+  --sandbox local --no-discover --yes
+```
+
+`--aut-agent`/`--user-agent` map to Copilot's `--agent`; a
+`.github/agents/release-reviewer.agent.md` used in VS Code can therefore be
+selected as `release-reviewer`. Use repeatable `--aut-copilot-arg` /
+`--user-copilot-arg` and `--aut-runner-env` / `--user-runner-env` for settings
+not represented by a dedicated flag. The declarative `agent.runtime` and
+`test.user_runtime` objects in `job.yaml` expose model, agent, effort, context,
+permissions, MCP/plugin settings, environment, and `extra_args`; the UI
+Configure tab provides full JSON editors for both.
+
+See `runners/copilot-aut.example.json`, `runners/copilot-user.example.json`,
+and `examples/copilot-agent.json`. To use another process as either role, pass
+low-level JSON with `--aut-runner` and/or `--user-runner`.
 
 ## Packaging & Release