## Summary The web page gains two things a conversation could only get from the terminal before: exporting the selected turns as a download, and reporting a problem through the bug report pipeline. The trajectory view is now on for everyone. - **Trajectory view without `--dev` (R0).** `raven`, `raven web`, `raven serve` and `raven gateway` no longer take `--dev`; the trajectory policy starts enabled. `raven tui --dev` (running the TUI from source) is unchanged. - **Turn selection.** From this version each turn's opening user message records its trace id (the Turn Trace Mark, never sent to the model). `raven/trajectory/selection.py` lists a session's main-line turns, closes a selection over the sub-agent and delegated traces it dispatched, collects their spans, and cuts the session record down to the selected turns; older records are matched conservatively and an unmatched turn stays in the trajectory only. - **Export.** The Trajectory Export package v1 (`schema: raven_trajectory_export`, `format_version: 1`) is the input contract of the coming `web-traj-import`; it is defined in `CONTEXT.md` and pinned by tests. It holds the raw spans, artifacts and v2 message blobs of the selected traces plus the cut session record, unredacted. Exports run as background jobs (at most two) and the browser downloads them from the same-origin `/trajectory/export/download` route with a one-time token. New RPCs: `trajectory.turns`, `trajectory.export`, `trajectory.export_status`, `trajectory.export_cancel`. - **Bug reports.** `freeze_export` is split into staging and finishing so a report can be prepared from selected turns; the CLI's behaviour is unchanged. A Report Session holds a web report in the gateway between page requests: at most two at once, all blocking I/O on worker threads, a cancel checked after every step (a report cancelled while packaging is never sent), a failed or uploaded report releases its slot and keeps its last status for ten minutes, and an idle one is cancelled after thirty minutes. Seven `bugreport.*` RPCs, the `bugreport-v1` capability (announced only while the receiver URL is valid), and error codes -32026 / -32027 / -32028. Every decision made on the web page, defaults and bulk buttons included, is remembered in the redaction history with `web` as its source, unlike the CLI's bulk flags. - **Web page.** A three-dot conversation menu in the header's corner (the desk launcher moves one slot in) opens the new `export` wizard. Export: pick turns, name the file under an "unredacted" warning, follow the job, download once automatically with a link to download again. Report a problem: pick turns, describe the problem, decide the uncertain values in two columns (hits highlighted at code points), upload, and get a receipt. Closing before the upload starts discards the report being prepared; once the upload starts the report is saved on the machine, a failure marked retryable offers a retry, and the saved report can be sent later from the command line by its id. Every answer is checked against the wizard's epoch and the job or report it was asked about, and a write step whose answer is lost is settled from the report's status instead of being sent again. Layouts were measured at 360 and 390 px in English and Chinese. - **Docs and tests.** The webui and trajectory-debugging pages (English and Chinese) describe both flows. Two integration tests drive them end to end: the export through the real download route, and the bug report against a real receiver process, including a stopped receiver, a retry, the redaction history's replay and a cancel at each step. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - The branch merges the current `main` (one merge commit, no conflicts); everything below ran on the merged tree. - `uv run pytest tests/ -q` (full suite): 57 failed / 31491 passed / 177 skipped. Every one of the 57 also fails on the current `main` on this machine (environment-specific, pre-existing); none is introduced by this branch. - `uv run pytest -m integration tests/integration/test_web_traj_export_e2e.py tests/integration/test_web_bugreport_e2e.py tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed (three consecutive runs of the two new files). - `uv run ruff check`, `uv run ruff format --check`, `uv run ty check` on the changed Python: pass. - ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run type-check`, `npx vitest run` (246 files / 3868 passed), `npm run build` and `python3 ui-web/build.py` (both boot snapshots match), `check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass. - ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass. - `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`: pass. - `make check-source-language check-large-files check-commits`: pass. - Headless Chromium on the built page (offline fixtures): both flows walked to the download and to the receipt; the header corner measured in five layouts (desk panel open and closed, workspace panel open, shell mode, narrow split) and the wizard at 360 and 390 px in both languages. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk - A process started with the old `--dev` flag that runs `system.upgrade` relaunches itself with `--dev`, which the new version refuses; the user runs `raven web` once by hand. This was accepted as the cost of dropping the flag. - The trajectory view is on by default: each open page calls the light, in-memory `trajectory.state` every five seconds, and the index is built only when the view is opened. No switch to turn it off is added here; the policy keeps a replaceable source for a settings entry later. - The export is the raw trajectory and may contain secrets. The page says so in a warning; the download is served only on the same origin, behind the session guard, by an unguessable one-time token, and no path ever reaches the page. - Rollback: revert the squash commit. Nothing is migrated; the `trace_id` field already written into session records is ignored by older versions. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
5.0 KiB
5.0 KiB
Command Reference
Use this reference to find the command for a task. Each command's help output lists its subcommands and options.
| Command | Purpose |
|---|---|
raven or raven tui |
Launch the terminal UI |
raven web |
Open the WebUI and keep Raven running in the background |
raven web --stop |
Stop the background WebUI service |
raven agent -m "..." |
Run a single task from the command line |
raven onboard |
Set up model providers, sandboxing, messaging channels, memory, web tool credentials, subagents, and data import |
raven status |
Show configuration and runtime status |
raven doctor |
Diagnose provider and environment problems |
raven --version |
Show the installed Raven version |
raven upgrade --check / raven upgrade |
Check for updates or upgrade a managed installation |
raven agents new <name> |
Create a specialized agent from Raven's modular templates |
raven acp |
Serve Raven as an ACP agent over stdio |
raven a2a enable / raven a2a disable |
Enable or disable the gateway-mounted A2A face; restart the host afterward |
raven a2a serve |
Start a standalone A2A HTTP listener (loopback port 8710 by default) |
raven sessions |
Create, list, fork, export, or delete sessions; resolve session keys with resume |
raven playbook |
Create, validate, manage, and run reusable agent workflows |
raven provider |
Configure providers and endpoints, authenticate, test connectivity, and select the active model |
raven channels |
List, configure, authenticate, enable, or disable messaging channels |
raven gateway |
Start the gateway and its configured services |
raven gateway status / raven gateway reload / raven gateway stop |
Inspect, reload configuration, or gracefully stop a running gateway |
raven serve |
Start the WebSocket RPC service and serve the WebUI when its build is available |
raven skill |
Browse SkillForge skills, inspect their contents, block or unblock skills, and remove installed bundles |
raven plugins |
List installed plugins and the active memory backend |
raven plugin auth <server> |
Authenticate or refresh OAuth access for an MCP server |
raven mcp bridge <socket-path> |
Bridge a subagent's MCP connection over stdio to a host-managed server |
raven import |
Preview and import data from other AI tools, inspect progress, or stop an import |
raven cron |
Create, inspect, run, enable, disable, or delete scheduled jobs |
raven sentinel |
Configure proactivity and inspect attention, routines, decisions, and nudges |
raven ops connection |
Register and list machines; add probes by default, while doctor validates registry entries |
raven sandbox |
List sandbox VMs, run commands, or open a shell; requires tools.sandbox.debug.enabled=true |
raven tracing |
Open the local trace dashboard |
raven tracing compact |
Consolidate duplicate trace artifacts to free disk space |
raven trajectory |
Save, replay, redact, label, and preserve execution trajectories for debugging, and run the bug report receiver |
Run raven --help for the command list, or raven <command> --help for details
on a specific command. From a source checkout, prefix commands with uv run.
Find documentation by task
| Task | Read |
|---|---|
| Choose a conversation or one-shot workflow | Using Raven |
| Configure shipped or external agents | Agent Integrations |
| Continue or steer a specialist task | Working with sub-agents |
| Share browser work with the agent | Browser collaboration |
| Store and search documents | Knowledge bases |
| Run and watch long tasks | Long-running work (Oncall) |
| Configure a messaging bot | Channels and Messaging |
| Integrate an editor or remote agent | Agent protocols |
| Run parallel tasks or inspect graph history | DAG orchestration |
| Save and run a reusable workflow | Playbooks |
| Evaluate harness changes against a benchmark | Evolver: usage and experiments |
| Configure approvals and unattended access | Permissions and security |
| Add knowledge, tools, or an agent | Skills and extensions |
| Deploy the resident host | Self-Hosting |
| Create an agent or plugin | Building an Agent, Building a Plugin |
| Capture, redact, and replay a failure | Trajectory debugging and replay |
Use site search to find a topic and --help to check command syntax.
For optional protocol features, consult the capabilities reported during
the handshake.
From the repository root, search the documentation and implementation together:
rg -n 'ACP|A2A|run_subagent_dag' docs-site/docs raven tests
run_subagent_dag, dag_status, cancel_dag, and a2a_send are model tools,
not shell subcommands. Use their guides for arguments and behaviour.