江国庆/Forrest 55c145ceb8
feat(*): probe the bug report receiver and gate uploads with a challenge (#1015)
## 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>
2026-10-20 10:22:53 +08:00

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.