## Summary Adds two things to bug reporting, on the Bug Report Receiver and on the Raven clients that send to it. **A hello probe.** The receiver answers `GET /v1/hello` with its service name and protocol version, and Raven asks it before a report starts, so a person learns that the receiver is down (or that the URL leads to something else) before spending a redaction review on the report: - `raven trajectory report-bug` and the trajectory browser's *Report a bug* probe before collecting anything. On a TTY without `--yes` they ask whether to continue (default no; declining collects and pins nothing). With `--yes` they say they are continuing and keep the package if the upload then fails. Without a TTY and without `--yes` the existing rule still refuses first. - The WebUI's *Report a problem* wizard asks the new RPC `bugreport.probe` when it opens. When the receiver does not answer, the report does not start: the wizard shows the reason and *Check again*, and the primary button becomes *Continue anyway*, so going on is the reader's explicit choice and never a dead end. A start pressed while the check runs waits for it (at most 8 s) and then checks the form again. - The probe runs under one deadline for the whole exchange (5 s), does not follow redirects, and the new requests never echo credentials or query tokens from a redirect target. - `/healthz` stays as the operator's liveness check. It was not reused for the probe because anything alive answers ok there, and it is not under a base URL's path prefix. **An upload challenge.** The receiver now takes only uploads that answer its Upload Challenge: the client gets a challenge from `POST /v1/challenge` and sends back an HMAC, under a constant built into Raven, of the challenge and the package's report id, sha256 and size. Key decisions: - Shallow by design. The goal is that an HTTP client that is not Raven, written without reading Raven's source, cannot upload. The constant is published with the (public) source and is not configurable, so there are no credentials to manage. The docs say so, with a table of what the gate stops and what it does not. - Stateless. Challenges are sealed with a per-process random key, are valid for 300 s and are not consumed; a restart retires them all. Replaying a captured upload as it was only re-delivers the same package, which the receiver already answers as a duplicate; replaying it with another package fails because the answer is bound to the package. - Checked from the headers alone, after the existing header checks and before the daily budget is reserved: a refused upload gets 401 (`unauthorized` or `challenge_expired`) with `WWW-Authenticate: Raven-Challenge`, writes nothing, and still spends a rate-limit token. Package checks, rate limits, budgets and timeouts are unchanged. - The client fetches the challenge inside the upload's existing total deadline. A 404 there means a receiver older than this Raven; a 401 is retryable only when the challenge expired. Uploading has not shipped in a release yet (it is under `Unreleased` in the CHANGELOG), so no released client breaks. A receiver deployed from main must be upgraded together with its clients, and a proxy in front of it must forward all of `/v1/`; the docs and the CHANGELOG entry say so. Commits, in order: the hello route and the client probe; the challenge end to end (new `raven/trajectory/receiver_auth.py`, and the Upload Challenge term in `CONTEXT.md`); the CLI probe; the WebUI probe (RPC, wizard, i18n, regenerated ui-web and ui-tui bindings); a fix that checks the form again after the wizard waits on the probe; the docs in both languages; integration tests against real processes. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run --no-sync pytest tests/test_trajectory_receiver_auth.py tests/test_trajectory_receiver.py tests/test_trajectory_upload.py tests/test_rpc_bugreport.py tests/test_cli_trajectory_commands.py tests/test_cli_trajectory_browse.py tests/test_trajectory_report_session.py tests/test_rpc_schema_match.py -q --idle-ceiling-strict --cov=raven --cov-branch --cov-report=json:coverage.json`: 1190 passed. - `make coverage-diff COVERAGE_BASE_REF=origin/main`: 99.53% of changed lines (213/214), threshold 90%. - `uv run --no-sync pytest tests/integration/test_bug_report_upload_e2e.py tests/integration/test_web_bugreport_e2e.py -m integration -n 0 -q`: 10 passed, three runs in a row. - `uv run --no-sync pytest tests/ -q`: 102 failed, 33527 passed. All 102 are in 14 files this PR does not touch (code tools, code flow, subagent probe and backends, a2a, whatsapp, provider config and rates, security network, everos, tracing command), and the same 102 fail on the base commit (checked on a worktree of `main`; the two failure sets are identical). - `make lint-python`, `make lint-imports` (10 contracts kept), `deptry raven`: pass. `make lint-types`: only two `pyflakes.checker` unresolved imports in `agents/raven-code/plugins/code-flow/code_flow/tools/diagnostics.py`, because pyflakes is not installed in the local environment (CI installs all extras); every changed Python file passes `ty check`. - `mkdocs build -f docs-site/mkdocs.yml --strict`: pass. - ui-web: `gen:check`, `lint` (0 errors), `type-check`, `npx vitest run --maxWorkers=8` (251 files, 4176 tests), `build` + `build.py` + `check-page` / `check-css` / `check-class-namespace`: pass. - ui-tui: `lint`, `lint:rpc`, `lint:i18n`, `type-check`, vitest (2242 tests), `build`: pass. - `make check-source-language check-large-files check-commits`: pass. - Manual, on real processes: a receiver plus curl (hello and challenge answer; an upload without an answer, or with a forged one, gets 401 and nothing is stored); the CLI (an upload while the receiver runs; while it is down, the warning, continuing and the kept package; declining on a TTY leaves nothing); a real gateway walked with Playwright in English and Chinese at 1280 and 360 px (the warning while the receiver is down, Check again after it starts, a report through to its receipt, no page errors, no overflow). - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk User-visible changes: - With an upload URL configured, `report-bug` and the browser's *Report a bug* start with a probe of at most 5 s, and ask one more question when the receiver does not answer. The WebUI wizard shows a warning and *Continue anyway* in that case. - The receiver refuses uploads that do not answer the challenge. A receiver deployed from main must be upgraded together with its clients (no released client uploads yet). A proxy that only forwarded `/v1/bugreports` must forward all of `/v1/`. - No change to package formats, `record.json`, or anything stored on either side. Rollback: revert the squash commit; there is nothing to migrate. - [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.3 KiB
Launch WebUI
Use Raven's WebUI to chat with agents, coordinate tasks, and manage your workspace in the browser. Follow task progress, inspect files and outputs, and browse memory and skills from the same interface.
raven web
This command opens the WebUI in your browser and starts Raven in the
background. Raven keeps running after you close the browser. To stop the
service, run raven web --stop.
Trajectory view
Once a conversation has content, a trajectory toggle appears in the chat header, to the left of the workspace panel button. The trajectory view lists every recorded step of that conversation (inputs, model calls, tool calls, replies) with its timing, opens the details of any step, and draws a duration bar above the list.
Export and report a problem
The three-dot menu in the top-right corner of the chat header (the desk launcher sits just left of it) acts on the open conversation. It is disabled on a new task that has no content yet.
Export packs the turns you pick into a .tar.gz that the browser
downloads. A turn brings the sub-agents it started with it; a turn that is
still running cannot be picked. You can rename the file before exporting.
!!! warning The export is the raw trajectory and is not redacted. It can contain keys, tokens and other secrets: keep it private.
Report a problem appears only when Raven has a Bug Report Receiver to send
to (RAVEN_BUGREPORT_URL, or the built-in default address). It is the web
version of raven trajectory report-bug: pick the turns, describe the problem,
decide the values the redaction scan was unsure about (this page is skipped
when the redaction history already decided them all), then upload and get a
receipt. Every decision on that page, including "keep all" and the bulk
buttons, is remembered in the redaction history with web as its source.
When the wizard opens it checks that the receiver answers. If it does not, the
wizard says why, and the report starts only when you choose Continue
anyway; Check again asks once more, for instance after the receiver is
back. Going on without it is safe: if the upload then fails, the report is kept
on this machine as described below.
Closing the wizard before the upload starts discards the report being
prepared. Once an upload has started the report is saved on this machine: if
the upload fails, a failure marked as retryable offers a retry, and either way
the saved report can be sent later with
raven trajectory upload-bug-report <id>, using the report id the page shows.
See
Trajectory debugging for
the pipeline behind it.
Import a conversation
Import conversation, in the left menu below New task and Connectors, opens a package from another machine (or another Raven home) for reading. Pick the file in the browser and it is uploaded to Raven, so this works whether you open the WebUI locally or remotely. A file can be up to 100 MiB, and one import runs at a time: starting another while one is in progress asks you to try again when it finishes.
Three kinds of package can be imported: an export from the three-dot menu, a
bug report package (from Report a problem or
raven trajectory report-bug), and a trajectory report from
raven trajectory report. Any other file is refused with a message saying so.
A damaged or unsafe package (a path that leaves the package, a link, more data
unpacked than the limit allows) is refused and leaves nothing behind, and so is
one whose conversation record is too large to open (over 32 MiB or 50,000
entries). A package made by a newer Raven asks you to update first.
Imported packages are kept under imports/ in the Raven home and stay there
across restarts. They are never added to the workspace's sessions. Importing
the same package again says it was already imported under its current title,
and offers Open existing or Import anyway.
Imported conversations are listed under Imported, below Recent; the group is hidden while there are none. An export is titled after its original conversation (or its first user input when that had no title), a bug report package after the first line of its description (or its report id), and a trajectory report after its original conversation (or its own id). Hovering a row shows the file it came from. Hovering or right-clicking a row offers only Rename and Delete; deleting also removes the copy kept on this machine.
An imported conversation is read-only. It reads like any other conversation,
and the trajectory view works as usual, including the full model input of a
long conversation. What differs: there is no input box, the title cannot be
edited in the chat header (rename it from the rail), replies have no Branch,
and the three-dot menu and the working-directory tag are not shown. Things a
package does not carry (a sub-agent's own transcript, attachments and delivered
files, task-graph runs, generated images) are shown as unavailable rather than
as errors. The [REDACTED:...] placeholders of a bug report package are shown
as they are.
An export is not redacted, so importing someone else's export gives you its raw contents: keep it as private as they should have.
For installation and provider setup, see Quick Start. For Docker or source deployments, see Self-Hosting.