## Summary
`raven --dev` and `raven web --dev` now serve a trajectory view in the
web page: an icon toggle in the chat header, left of the workspace panel
button, once a conversation has content. The view lists every recorded
step of the conversation with its timing, opens the details of any step,
and draws a duration bar above the list. A normal launch is unchanged:
no capability, no toggle, `/health` reports `trajectory_view: false`,
and `raven web --dev` against a running normal service refuses to attach
and says how to proceed.
Backend (`raven/trajectory`, `raven/observability`, `raven/rpc`,
`raven/cli`):
- `entries.py` projects the span log into trajectory entries with stable
ids and a single Timing Owner per logical span, so the bar never charges
a duration twice; broken records keep unique ids and in-progress spans
charge nothing. A turn opens with `user.input` and closes with
`turn.end`, which owns the turn's whole clock. The projection marks the
rows the list need not show (`meta.hidden`: a turn's end that repeats
the turn's last model output word for word, a turn's end of a turn that
finished ok with nothing recorded in it, an internal step that recorded
nothing) and what every model input adds to the conversation before it
(`meta.delta` first / continued / independent / unknown, with
`new_from`, `echo_at` and `message_count`, proven by an ordered prefix
over the v2 message references within one chain and purpose, the
predecessor's own output written back into the history not counted as
news). Tool results that trip an error rule (an error key, a true
is_error, a false ok / success, an error status word) fail the output
entry with the rule as evidence. A model input's row previews the first
message with text that is not a system one of what the call brought,
read from an inline payload or learnt by bounded repair reads the index
queues, which keep at most five probes per input and treat a failed read
as terminal. A shell that a long tool list pushes past the 64 KiB
preview read still gives its message references, which precede the
tools; an input whose references cannot be read at all leaves unknown
only the input it may have preceded directly. A span whose preview pass
raises (a result nested too deep to parse, a pointer that cannot name a
file) marks its own entry unreadable and never stops the session's
index.
- `observability/purpose.py` names the purpose of each model call
through a context variable that the `llm.call` span records as
`llm.purpose`; the main loop (its wrap-up when the iterations run out
included), watch work, titles, the permission judge, DAG verdicts,
memory extraction, the skill gate and playbooks each set theirs around a
call that records an `llm.call` span, so side questions are told apart
from the main line.
- `index.py` indexes one session's spans incrementally across the
archive chain and the active file, verifies log identity on open,
detects same-size rewrites, serves change snapshots with cursors bound
to an epoch and a revision (up to four list walks at once), and queues
the one blob read a continued input needs for its preview. One index
refreshes one scan at a time, even when the request that started a scan
was cancelled; a spilled sub-agent trace whose first log file was
removed is recovered from the files still there, and the gap is counted.
- `details.py` describes an entry's blocks and reads them in pages under
bounded limits, with integrity findings (missing, outside the store,
oversized, unreadable artifacts) built from the same pass. A
memory.feedback step's skills carry the names its own turn's
skill.inject step recorded. The usage block is attributes only, the
timing block is left out when nothing was charged, empty optional blocks
are left out, the tool block is gone (its fields live in timing and
error), an outline block lists a message list page by page (role, size,
first words and the cursor of the page each row starts, read from the
first 8 KiB of a large message) so a long prompt can be folded before it
is read, and two blocks under the raw record serve the files the span
names: a directory with the recorded size and a cursor per file, and one
file's content by its cursor, as JSON when it parses and text otherwise,
saying when it was cut at the 512 KiB read limit or to fit one response.
- Five RPC methods, `trajectory.state`, `trajectory.list`,
`trajectory.changes`, `trajectory.detail` and `trajectory.block`, with
error codes -32020 (disabled), -32021 (entry not found), -32022 (cursor
expired) and -32023 (revision changed); the `trajectory-v1` capability
is announced only by a process launched with `--dev`, which `web`,
`serve` and `gateway` all accept, and which the page-triggered upgrade
carries into the relaunch; a root `--dev` ahead of a subcommand is
refused with the form that works. Detail and block reads refresh the
index first, and while a rebuilt index is still scanning, an entry it
has not reached yet is answered with its new epoch rather than as gone;
response pages are measured in the UTF-8 bytes the transports send.
Frontend (`ui-web/src/features/trajectory`):
- The icon toggle and the parked conversation scroller; the fixed-row
virtual list over the index's visible rows, with live appends followed
near the tail (a selection from the bar or a link brings its row into
view once and leaves the following alone), stable selection, and
per-session memory of the place, the selection and the zoom. Hidden rows
stay out unless "show hidden entries (n)" is on or a link pointed at
one, which reveals it with a marked edge. That switch and the bar's
duration threshold (a slider over detents from 0 to 1000 ms, applied to
the bar only) are viewer preferences in localStorage, where an earlier
build's switches are migrated.
- The details pane: tabs per block with arrows when they overflow,
on-demand paged reads, an 8 MiB cache budget and a page window that lets
its stalest page go but never the one just asked for, recovery through
revision and epoch changes with bounded retries, and a place in the
page's Escape order. Relations resolve to links by (trace, span); the
usage block is six labelled rows with unrecorded cache counters said so;
an unreadable artifact reads as missing data in red. The messages tab
lists the outline on its own, folds the messages the model had already
seen and opens the new ones, draws only the rows near the viewport and
reads bodies for the open rows in that window; a row whose page the
cache let go folds again until asked for, a row a page was cut short of
to fit one response is read by its own cursor, a page that failed to
read is said in place with a retry, and an outline walk cut short is
taken up again on return. A JSON node draws its children two hundred at
a time. Under the raw record every file the span names is headed by its
attribute and shown as a JSON tree or text; contents are read by their
own cursor only for open files near the viewport, placed by where they
stand on the page, two at a time, kept apart from block pages, and let
go stalest first when the budget is short, to be read again only on
request.
- The duration bar on a canvas above the list: a fit that goes dense
when the rows outnumber the minimum slots, a spread with a frozen unit,
wheel zoom about the pointer, drag to pan with the anchor carried along,
a delayed click that checks the world it was made in, a pick list for
dense blocks placed within the window, a hidden turn end's time as the
turn's band under its blocks, a green dot above the selected entry's
block and a red one below a failed one, the summary in the band's hover
and the tools' title, a sideways wheel or swipe (or Shift with the
wheel) panning a zoomed bar, and a zoomed view that keeps its place on
the next entry when the threshold takes its anchor away.
- 223 `gui.trajectory.*` catalogue keys in both languages, the kind
vocabulary covering every kind the index emits with zh labels of at most
four characters; the TUI catalogue regenerated.
Docs: `commands.md`, `webui.md` and `webui.zh.md` describe the developer
launch; `CONTEXT.md` and `ui-web/CONTEXT.md` define Trajectory Entry,
Timing Owner, Message Delta, LLM Purpose and Trajectory View.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Python, compared with the main commit this branch is based on (61269654)
by test nodeid, same command and environment in both trees (`uv sync
--frozen --python 3.12 --extra dev --dev`, then `uv run --frozen
--python 3.12 --extra dev --dev pytest tests/ -q -p no:cacheprovider
--junitxml=...`):
- main: 52 failed, 27541 passed, 143 skipped (all environment-dependent:
subagent probes, a2a interop, whatsapp, everos, ...)
- branch: 52 failed, 27786 passed, 143 skipped, the same 52 as main, so
no test that passes on main fails here; tests collected only on the
branch: 245 (all added by this PR)
- `uv run ruff check .`: All checks passed; `uv run ruff format --check
.`: already formatted; `make lint-types`: All checks passed
Web UI (`ui-web/`):
- `npm run gen:check`: generated.ts matches the contract (215 methods)
- `npm run type-check`: 0 errors; `npm run lint`: 0 errors, 4
pre-existing warnings outside this change
- `npx vitest run --maxWorkers=24`: 231 files, 3493 tests passed (the
`scripts/gates/*.test.mjs` gates included)
- `npm run build && python3 build.py`: the build matches the boot
goldens, which this PR changes by one node each, `div#trajHost`
(`boot-stub.txt` 344, `boot-live-noserver.txt` 343,
`src/test/__golden__/region-app.txt` 189 lines)
TUI (`ui-tui/`): `npm run lint:rpc` in sync, `npm run lint:i18n` up to
date, `npm test`: 144 files, 2098 passed, 13 skipped.
Repository gates: `make check-source-language`, `make check-large-files`
and `git diff --check` exit 0; `uv run --frozen --group docs mkdocs
build -f docs-site/mkdocs.yml --strict`: built with no warnings.
End to end, on a real service with headless Chromium (scripts, logs and
screenshots kept outside the repository; run on this branch at its head,
every review change in): `raven web --foreground --dev` on a freshly
built fixture home with thirteen sessions (slow, failed, parallel,
nested sub-agent trace with injected skills, rotated archive, broken
artifacts, a 45-message prompt continued twice and a side question, a
240-message prompt, a turn whose end recorded nothing, a tool round
trip, a span naming thirteen small and another naming twenty large
files, empty, 10002 entries). The expected entries, with their hidden
marks, deltas and failure rules, are derived from the fixture definition
by the recording rules; the indexer and the paged `trajectory.list` walk
are checked against that list first, and the page is checked against it
after. 185 checks passed: the toggle and the parked scroller, the
visible rows' ids and order with hidden replies left out and listed
again under the switch, failure marks including a result that carried an
error key, integrity wording per broken artifact, the virtual window
bound and both ends of the long list, the details tabs, relation links
across traces, the usage rows, the messages tab folding the old rows and
opening the new ones as a window over the pane's viewport, a 240-message
list reading only the pages in view, letting the stalest pages go on the
way down and reading a folded row back on request, a feedback step's
skills under their own turn's names, a turn whose end recorded nothing
hidden while a failed one stays, the call after a tool round trip
previewing the first result with its predecessor's echo folded, the
duration threshold at 200 ms and 1 s, sideways panning, every file of a
span headed and read as it comes into view, large files each read once
with the earliest released and read back on request, a file's tree
folding to bring the next file in, the bar above the list, the turn's
band and its hover, the green and red dots read from the canvas, the
short filter, a slot doubling under a x2 wheel, drag by the pointer's
travel with the anchor kept across live appends, dense slots in
proportion at the scale ceiling, the summary hover in the gap between
blocks, pick list placement in tall and short windows, measured column
widths per language, tab arrows under overflow, theme and language
switches, viewports of 1200, 800 and 320 px; then a normal `raven web`
with no toggle, and `raven web --dev` against it exiting 1 with the
stop-first message while the service kept running.
## Risk
- [x] Security impact considered: the view is served only under `--dev`;
the RPC methods answer -32020 otherwise, artifact reads stay inside the
trace store with the 512 KiB cap, and the page reads through the
existing authenticated channel.
- [x] Backward compatibility considered: no existing RPC method, session
file or span format changes; the one new span attribute (`llm.purpose`)
is additive; a normal launch behaves as before. Known recorder gap, left
for a follow-up: `semconv.turn` reads the turn's reply from a tuple and
records `{"content": null}`; this PR only hides such empty turn ends.
- [x] Rollback path is clear for risky changes: revert this PR; it adds
a feature behind a flag and no migration.
## Related Issues
N/A
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
1.2 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.
Developer launch
raven web --dev
raven --dev and raven web --dev start the same service with the
trajectory view enabled: a toggle appears in the chat header, to the left
of the workspace panel button, once a conversation has content. It 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. A normal raven web shows no toggle. If a
normal service is already running, --dev reports that it has no trajectory
view and leaves it running; stop it with raven web --stop first.
For installation and provider setup, see Quick Start. For Docker or source deployments, see Self-Hosting.