134 Commits

Author SHA1 Message Date
Kevin Hu
82c76a82a9
feat(knowledge): read every format, show what the index holds, and let an agent search it (#489)
<img width="2318" height="1448" alt="image"
src="https://github.com/user-attachments/assets/bca71d69-4972-420c-b14e-c8cf74a17de9"
/>

## Summary

Everything a knowledge base could not read, and the pieces it cut them
into
saying what they are.

**Reading a PDF.** A PDF records glyphs at coordinates; whether they are
a
heading, a table cell or a running footer is inferred from how they
look. There
are now two readers. The geometric one infers structure from type size
and
position and needs nothing but the file. The other asks deepdoc's
models, ported
into `raven/knowledge/parser/deepdoc`: a layout model that says what
each region
is, a detector and recognizer that read a page carrying no text at all,
and a
table-structure model that rebuilds a grid from a picture of one. 
 Detecting boxes around text the file already spells
out exactly costs an inference pass per page to learn less, and
recognising it
costs accuracy.

The layout graph answers with a shape its own postprocessing
raises on, and its classes are DocLayout-YOLO's order rather than the
list
Both were established by running the model, and the label order is
pinned by a test.

**Tables go in as tables.** `<table>` is the only shape that keeps what
a grid
states -- which column a cell stood under, which cells are merged, which
row is
the header -- and it is the shape a model reads a table in, which is
what these
chunks are for. PDF, Word and PowerPoint all state their merges exactly,
and
they now survive as `colspan` and `rowspan`. The flat form this replaces
had to
repeat a header standing over two columns across both of them, because
there was
nowhere to record a span; it had no callers left afterwards and is gone.
Two
deviations from upstream, both about what the string is for: every
cell's text
is escaped, where upstream interpolates it raw and a cell holding a `<`
produces
markup that is no longer a table, and the span attributes are written
only where
there is a span, where upstream emits `<td  >` for every ordinary cell.

**A picture of where each chunk came from.** A chunk is a few hundred
words with
a page number on it, which is enough to cite and not enough to answer
whether
the parser read the page correctly. So every PDF chunk that knows where
it sits
carries one image: the regions it covers, cropped out of the rendered
pages and
stacked. here they are already structured in the parser's element spans,
so
the markers would only put text nobody wrote into the thing being
embedded.
The panel draws a chunk's tables as tables, parsed and
rebuilt as elements rather than injected: a person can rewrite any piece
from
that same panel, so what comes back from the store is user input however
it got
there.

**The page that reads them.** Upstream retired the knowledge page while
this
branch was out; it is rebuilt against the new architecture, and the half
that
never existed is the one a reader needs -- what a document actually
became once
it was cut and embedded. Documents sit in one-level folders and arrive
by four
routes: a file, a folder, a URL, a written note. Adding and indexing are
two
calls on the contract and nothing drains that queue on its own, so a
page that
stopped after the first left every upload saying Queued for good.

Opening a file takes the whole page: the document on the left, the
pieces the
index holds of it on the right. The left half is the file drawn as its
own
pages rather than framed by the browser's PDF viewer, which reads where
to open
once and answers to nothing afterwards -- and which nothing can be drawn
on.
Pages are rendered once and kept, and the region a piece was cut from is
washed
over the page it came from, placed in fractions of the page so the
picture's
own scale never enters the arithmetic. Clicking a piece takes the file
there;
double-clicking opens it for rewriting.

The pieces can be searched, filtered by state, turned on and off,
deleted,
rewritten and added to, one at a time or in a batch. Every one of those
was
already on the contract with no reader for it. A base's settings are
back and
fuller: how many pieces a search returns, how documents are cut, and how
much
prose comes with a table or a figure. The embedding model is a picker
while the
base holds no pieces and a stated fact once it does -- moving it then is
the
collection made again at the new width and every document re-cut, which
is not
a thing a panel does by being saved.

**An agent can read them.** The retrieval engine was there and nothing
could
reach it: no agent had a tool that opened a library. A reader now points
a
conversation at bases from the composer, the way they pin a working
directory,
and the selection rides in the same place -- the session's metadata,
bound
around the turn.

The tool takes a query and never a base. The scope is the reader's
choice, so a
model cannot reach material nobody offered it, and it is withheld where
nothing
was picked rather than offered and refused. A hit says which document
and page
it came from, because a hit a reader cannot place is a hit they cannot
check --
and the passages are pressable in the transcript, walking into the base,
the
document, the folder it is filed under and then the piece. A citation a
reader
cannot follow is a claim they have to take on trust, and the whole point
of
searching their own material is that they can go and look.

**The word segmenter and the resources.** `raven.core.Tokenizer` is
Infinity's
`rag_tokenizer`, ported: a forward and backward maximum match over a
dictionary
trie, with stemming and lemmatisation on the latin path. XGBoost is not
carried
over. None of the data lives in git -- the dictionary, the NLTK corpora
and the
ONNX graphs run to about a hundred megabytes, so `make fetch-resources`
on an
install and an optional Docker layer behind `RAVEN_RESOURCES` both point
at one
script. A checkout that could not reach the network still works, and
every
feature that reads this data says so when asked.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on macOS against Python 3.12, with the deepdoc weights fetched (the
model
tests skip without them):

```
uv run pytest                        27450 passed, 111 skipped, 3 failed
npm run test --prefix ui-web          3276 passed
npm run test --prefix ui-tui          2106 passed
npm run type-check --prefix ui-web    clean (tsc)
npm run lint --prefix ui-web          clean (4 pre-existing hook warnings)
make lint-python                      clean (ruff check + format)
make lint-types                       clean (ty)
make lint-imports                     10 contracts kept, 0 broken
make check-source-language            clean
make check-large-files                clean
make build-ui                         built, both boot snapshots match
node ui-web/scripts/check-css.mjs     clean
node ui-web/scripts/check-class-namespace.mjs  clean
```

The three Python failures are not this branch's and were each confirmed
on the
base alone: one asks a host without LibreOffice to refuse a render and
this host
has LibreOffice installed, and two simulation cases fail on an
unmodified
checkout of the base commit.

The RPC contract was regenerated for both consumers and both match it
(`npm run gen --prefix ui-web`, `npm run gen:rpc --prefix ui-tui`, then
`gen:check`). The page's boot snapshots and region goldens were
refreshed where
the composer bar gained a button, and each records that button and
nothing else.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

A PDF's tables, and a Word or PowerPoint file's, are now indexed as HTML
rather
than as header-prefixed lines. Chunk text changes shape for those
documents, so
a base indexed before this and searched after it holds both forms until
its
documents are reindexed; retrieval keeps working either way, because
both forms
are text. The same applies to how much prose a table or a figure carries
with
it: the setting now reaches as far as it says, where before it stopped
at the
nearest paragraph, so a chunk cut before this keeps the narrower context
until
its document is rebuilt. Rolling back is reverting the branch and
reindexing.

The deepdoc models are optional. An install that never ran `make
fetch-resources` reads PDFs geometrically, exactly as before, and says
so when
the models are asked for by name. Nothing here reaches the network at
request
time.

Chunk crops and rendered pages are written at index time and on first
view, both
under the state directory rather than in the repository, and both are
deleted
with their document. A page is immutable for the life of its document
id, so
the route serving them caches; the document route does not. All three
routes
take ids and no path, and the two image routes answer under the
strictest
sandbox in the tree.

What an agent may search is the reader's choice and nothing else. The
tool takes
no base argument, so a model cannot name one, and it is absent from the
schema
entirely for a conversation that named none -- a lane nobody pointed at
a base
is unchanged by this branch. The bases a session carries are stored
beside its
working directory and travel no further.

- [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) <noreply@anthropic.com>
2026-10-12 19:05:16 +08:00
userName20260323
8f42a1ec03
feat: ship research reports in a reader layout, measured and link-checked (#890)
## Summary

raven-research reports were written for a grader: fixed `## Answer` /
`## Findings` / `## Limitations` headings, HTTP codes beside links, and
a
chat reply that drifted from the file saved with `write_file`. This
branch
ships them in a reader layout and closes the gaps that product runs on
DeepSeek showed between the brief, the reply and the saved file.

Reader layout (`finalShape.reportLayout = "reader"`, on for
raven-research):

- The report opens with the answer as a blockquote, with no label or
bold
  lead-in. Anything the brief asks the report to open with (a retrieval
date, the kinds of sources) follows in the blockquote. Delivery facts
the
brief asks back (path, counts) go on its last line, which the chat reply
  keeps and the saved file leaves out.
- The body sits under its own `##` headings, using the brief's section
  names word for word, numbering included, when it gives them. The last
  section names what could not be verified (`## Limitations` in English;
  the reply's language otherwise, with no English word in that heading).
The shape gate reads the last `##` section as the limits when no word it
  knows names them, since no word list covers every language, and when
  only the first heading has such a word with no body above it (a body
  heading on export limits is body, not limits). The audit reads it the
  same way and counts a body written as prose under the answer.
- Prose cites through markdown links, with no fetch status beside them.
A
brief that asks for link checks gets one table before the limits,
listing
  every cited URL as fetched, with its status, marked blocked where the
  site blocked the fetch.
- The layout is derived from the deep clause, so the evidence rules stay
  one text. The shape gate, its reminder, rewrite prompt and interrupted
  fallback, and `scripts/research_report_audit.py` read it as the same
  three parts. A test pins the audit's limits matcher to the gate's.

Chat and file are one text: at turn end the delivered reply is written
over
the report file the turn wrote. Which file that is:

- A markdown file the turn wrote whole, or appended to or edited when
the
turn wrote it whole first or it still holds exactly what an earlier turn
  of the session left in it. The session record keeps the sha256 the
session left in each report file, checked at turn start before any tool
  runs. Any other file (a log the user keeps, a report the user changed
  between turns) holds someone else's text, so it is never the report. A
later turn that only edits a report nobody else touched still syncs it.
- Whose `##` headings are at least half the reply's. On the
reader-layout
  product runs a report draft shared 75-100% of its headings with the
reply, and a notes file saved beside the report shared none, so a notes
file or a source index is never overwritten, alone or beside the report.
- Of several such files, the one the reply names; when it names none or
  more than one, every file is left alone.

The file keeps its `#` title when the reply has none. It is also left
alone
when the reply is not a report, or when the reply is under 80% of the
file's length, so a summary reply never replaces the report. The path is
read from the first line of the tool's result only, matched against the
tool's whole fixed wording, and the file tools now
refuse a path that carries a line break or other control character: they
echo the path into their results, so such a path could forge a second
result line naming a file outside the workspace.

Length and counts, measured rather than estimated:

- Every markdown write or edit gets a `[report length: ...]` line on its
  tool result, carrying:
  - CJK characters and other words, with prose and tables apart;
  - the same counts per `##` section;
  - the number of distinct URLs cited, extracted the way the research
    trail extracts them.
- The report checks a brief's length against that line, and takes any
  count it states (sources included) from it.
- `write_file` now reports bytes. Its success line said "N bytes" and
  counted characters, so a Chinese report was sized at about a third of
  its real length.

Fetch status and the research trail:

- The research fetch tool reports the target's own status from the Jina
reader's header instead of the reader's 200, and marks a CAPTCHA wall as
  `blocked`.
- The trail counts such pages as refused by the site, not as read, per
  fetch: a page refused once and read on a retry counts as read. When a
  thin page is re-read at another address, each address keeps its own
  status: the stub its own, each fallback the one in its own header.
- The trail drops click-tracking parameters (`utm_*`, `srsltid`,
`gclid`,
  `fbclid`, `msclkid`) before matching a citation.
- Its `<details>` folds are now plain labelled lists, since a terminal
  shows the tags raw.
- `scripts/research_report_audit.py` reads the refused-page clause and
  note. It also reads the reviewer verdict when the trail names the
  reviewing model. That second break predates this branch: a model id
  carries `/` and `-`, so the verdict read as missing on every product
  trail.

Other:

- The research reviewer now runs on DeepSeek in thinking mode. That
  provider refuses a named `tool_choice` with HTTP 400, so every review
  failed open and each report shipped unreviewed. The gate retries with
  `tool_choice=auto`.
- `measuredGuidance` is off in the shipped config. Its numbers were
  measured on a short-answer benchmark and pull a long report toward a
  terse answer.
- The appendix twin's guard names the twin's lead over the frozen dr@3.5
  record instead of requiring the two to be equal: 4 added and 5 changed
  definitions, with `ResearchTrail` compared member by member so its
  untouched members stay pinned. The record itself is unchanged from
  `main`.
- The product label moves to the `-reader` suffix. Its digest was
  re-stamped several times on this branch only; `main` never shipped an
  intermediate digest.

Checked and deliberately not changed here:

- The main agent's own `web_fetch` (`raven/agent/tools/web.py`) also
  reads through Jina and still reports the reader's 200 for a target
  error. It is a separate module, not a twin of the research tool, so it
  needs its own change.
- `fetch_result_ok` is unchanged, so a page the site refused still
releases the fetch gate, counts toward the evidence floor and enters the
  conversation memo as a source. Changing it would move when the gate
  releases.
- The report sync writes the file directly, not through `write_file`, so
it
  emits no file-change event and a client's diff panel does not show it.
raven-research runs with no write approval, so no approval is bypassed.
- Every CAPTCHA flag in 36 local fetches that carried a reader warning
was
  on a page of 862 characters or fewer. Target errors appear on pages of
  up to 18k characters, and each one checked was a real error page. No
  false positive was found.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run after rebasing onto the current `origin/main`. The range-diff
against
the pre-rebase branch is `=` for all 15 commits.

- `uv run pytest tests/test_agents_research_*.py
tests/test_research_*.py tests/test_filesystem_write_modes.py
tests/test_agent_tools_web_fetch.py tests/test_history_trimmer.py
tests/test_context_engine*.py -q`: 1070 passed.
- Full suite before the rebase, `uv run pytest tests -q`: 27745 passed,
  118 skipped, 12 failed. None of the 12 were introduced by this branch:
  - 11 fail identically in clean worktrees of `origin/main` and of the
    branch head. They are environment-bound: proxy redaction, NAT64
    addresses, the node path.
  - `test_agents_ppt_launcher` passes in the clean branch worktree and
    failed only because of an uncommitted local edit to
    `agents/raven-ppt/subagent.json`.
- Mutation checks: each of these, reverted alone, turns its new tests
red:
  - the target-status override;
  - the refused-page split;
  - the ledger classification;
  - choosing the named report file (3 tests fail with `paths[-1]`);
  - the audit's refused clause;
  - the audit's ` via ` terminator.
- After the second review round:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py -q`:
  1238 passed. Each fix, reverted alone, turns its new test red: the
  control-character refusal, the first-line read, the append rule, the
  last-section limits (gate and audit apart), the fallback verdicts, and
  the URL count, the per-fetch refusal, the draft-heading filter and the
session-wide edit rule. The twin guard fails on an undeclared definition
and on a
  stale lead entry.
- After the third review round, on the rebased head:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py
tests/test_history_trimmer.py -q`:
  1278 passed. Mutants each turn the new tests red: the unanchored
unchanged-file match; the control-character guard narrowed to LF, or to
  `Cc` only; each of the four success lines reworded in the real tools;
  a twin-only change to an untouched `ResearchTrail` default.
- After the fourth review round, same command: 1288 passed. Mutants each
  turn the new tests red: held files taken without the digest check, the
  digest never recorded, held files ignored, the first-heading rule
  reverted in the gate and in the audit apart, the gate's body-above
  condition dropped, and the audit's prose-body count dropped.
- `make lint-python`, `make lint-imports`, `make lint-deps`,
  `make lint-types`: all pass.
- `scripts/check_commit_messages.py origin/main..HEAD`,
  `scripts/check_source_language.py origin/main...HEAD`,
  `make check-large-files`: all exit 0.
- Product runs through the TUI host, on reports about personal agents,
AI
  glasses, AI coding agents, office agents and edge AI:
  - The saved file equals the reply, less the delivery line, with its
    title kept.
  - The stated length and source count match the `[report length]` line.
  - The link-check table has one row per counted URL.
- A Gartner 403 and an HBS 405 behind a CAPTCHA came through with their
    real status.

- [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:

- raven-research replies and saved reports change form: an answer
blockquote, no fixed headings, no HTTP codes beside links, and a single
  link-check table.
- The report file a research turn wrote is overwritten with the
delivered
  reply at turn end, except in the cases above.
- `read_file`, `write_file`, `edit_file`, `list_dir`, `deliver_files`
and
the RPC file reads refuse a path containing a line break or other
control
  character (they share `resolve_path`).

Existing installs keep the contract they seeded into
`agent_memory/profile/agent.md`. The new layout reaches them only after
that file is deleted; until then the gate still accepts the old
three-heading replies. The changelog says so.

Not covered by this branch:

- The research subagent pins `contextWindowTokens` to 65536. On a host
  model with a 1M window, the budget note reaches 80-136% early and cuts
  research short. Left as is on purpose; it is a separate decision.
- Post-delivery behaviour of the host agent is unchanged. It may recount
  or edit the report after delivery.

Rollback: revert the squash commit. To keep the code but drop the
layout,
set `finalShape.reportLayout` to `"sections"` in
`agents/raven-research/config.json`.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-12 15:41:52 +08:00
yudongyouqing
0cf70f5773
fix(sandbox): point boxlite install advice at the running environment (#822)
## Summary

- The missing-boxlite advice told users to run `pip install
'raven[sandbox]'`, which is wrong twice over: the `raven` name on
package indexes resolves to an unrelated project, and a global pip
install bypasses the uv environment raven actually runs in (#640).
- Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the
pinned boxlite requirement from the installed distribution metadata
(falling back to the bare name when metadata is absent) and renders a
copy-pasteable command targeting the running interpreter, e.g. `uv pip
install --python /path/to/venv/bin/python boxlite==0.9.5`.
- The onboarding screen keeps its translatable line in the zh catalog
and prints the command on its own untranslatable line;
`build_executor`'s ImportError message uses the same hint.
- The two init-failure messages that fire after the boxlite import
already succeeded no longer suggest a reinstall; they keep the platform
bullets naming the actual causes.

## Type

- [x] Fix

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Commands run on macOS, Python 3.12, on top of a clean checkout of main:

- `uv run pytest tests/test_sandbox_unit.py
tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py -q` -> 467 passed. The new tests
(TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor
case, one onboard screen case) were each watched failing before the fix.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002
passed, 109 skipped, 21 failed. The 21 failures reproduce identically on
unmodified main (verified by stashing this change):
`test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the six touched files
-> clean.
- `make lint-imports` -> 10 kept, 0 broken.
- `make check-source-language` -> pass.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

- User-visible change: three messages read differently (the onboarding
hint, the build_executor ImportError, two executor init-failure
messages). No API, config, or behavior change beyond the wording. The
hint assumes uv on PATH, which every documented install path already
requires.
- Rollback is a straight revert of this commit.

## Related Issues

Fixes #640
2026-10-03 22:32:44 +08:00
HylaruCoder
40a6b456dc
chore: add git story film skill (#810)
## Summary

Add a self-contained git-story-film skill for turning repository history
into animated product stories, including the drawing engine, production
helpers, and a complete Raven example.

- Provide English instructions and a Chinese README while preserving the
Chinese film variant and bilingual captions.
- Fix bundled example script paths and bring the Python helpers into
compliance with Ruff.
- Keep the bundled storyboard as a text-only reference with all 24 shots
and bilingual captions. No pre-rendered images are bundled; the studio
draws storyboard frames from code.
- Allow only the required example HTML and localized source data through
the repository gates. Keep the 1 MiB limit; standalone images, generated
exports, neighboring paths, and unsupported assets remain blocked.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other

## Verification

- `uv run pre-commit run --from-ref origin/main --to-ref HEAD`: all
applicable hooks passed after rebasing onto the latest upstream main.
- `make lint-python`: passed, including format checks for 2,147 files.
- `make lint-types`: passed.
- `make lint-imports lint-deps`: passed; all 10 import contracts held.
- `uv run ruff format --check skills/git-story-film`: passed.
- `uv run ruff check skills/git-story-film`: passed.
- `uv run pytest tests/test_large_file_check.py
tests/test_source_language_check.py -q -o addopts=''
--idle-ceiling-strict`: 50 passed.
- `make check-large-files check-source-language`: passed on the complete
committed PR diff.

Full CI, browser playback, and MP4 rendering have not been verified
locally.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

The skill is an optional development tool and does not change Raven
runtime behavior. Repository policy exceptions are limited to documented
paths; other assets and oversized files remain blocked. Roll back by
reverting this change, including the skill and its matching gate
exceptions.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

Co-authored-by: Codex <noreply@openai.com>
2026-09-27 12:56:53 +08:00
zhanghui
1aac70ed10
fix(*): ship the deck template covers so a boot draws none (#699)
## Summary

Starting a gateway started LibreOffice. Fifteen seconds after every boot
the
template picker's covers were drawn on the host: ten conversions, three
at a
time, for a gallery most readers never open. On macOS those are three
icons
in the Dock on a start that was asked to do nothing of the kind.

The covers only depend on the templates the engine ships, so the release
renders them once instead of every installation rendering them again.
`scripts/bake_deck_template_covers.py` walks the template directory and
every
phrasebook beside it, writes one JPEG per template per language into
`raven_ppt/assets/templates/covers/`, and the ppt-engine wheel carries
that
directory. `deck_templates.shipped_cover` reads it before anything is
started, `cached_cover` and `cover_for` answer from it, and the warm-up
introduced in #624 then finds nothing missing and starts nothing. Twenty
covers, 398 KB.

The warm-up itself is unchanged, and so is the rendering path:
`shipped_cover`
answers None rather than raising, so a template dropped into the
directory by
hand, a language added after the build, and an install from source all
still
draw their own. Both the bake and the release gate read the directory
rather
than a list, so a new template or a new language is a new file and not a
code
change.

Two packaging lines were measured rather than assumed. Hatch reads the
ignore
file at the built project's root, and the rule lives at the repository
root,
so the `include` list alone ships the covers today; adding a
`.gitignore`
under `plugins-dist/ppt-engine` drops them to zero, which is what
`artifacts`
is there for. Both states were built and inspected.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `uv run --frozen --python 3.12 --extra dev pytest
tests/test_rpc_deck_templates.py
tests/test_rpc_console.py tests/test_cli_serve_commands.py
tests/test_cli_gateway_commands.py
tests/test_ppt_engine_default_templates.py
tests/test_ppt_engine_templates.py -q`
  -> 417 passed.
- Reverse check: with the two `shipped_cover` short circuits removed,
the two
new cases fail on the symptom they name (`a cover the wheel carries must
not
  be drawn again`) -> 2 failed, 28 passed.
- End to end on one build, the only variable being whether the covers
are in
the package. Covers hidden: `drawing 10 missing cover(s)` and three
`soffice`
processes. Covers shipped: no log line, nothing queued, no `soffice`.
Run
  against an empty RAVEN_HOME, in both `zh` and `en`.
- `scripts/bake_deck_template_covers.py` against the real package -> 20
covers,
  398 KB; the `en` set carries English copy, checked by opening one.
- `uv build --wheel plugins-dist/ppt-engine` four times across the
include and
artifacts combinations -> 20 covers in the wheel, 0 without `artifacts`
when
  a project-local `.gitignore` exists.
- `ruff check` and `ruff format --check` on the changed Python -> clean.
`scripts/check_source_language.py` and `scripts/check_large_files.py`
over
  `github/main..HEAD` -> exit 0. `commitlint` on the commit -> exit 0.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

- Nothing a reader sees changes: the picker shows the same pictures,
drawn by
  the build rather than by their machine.
- The release job gains an apt install of `libreoffice-impress` and one
bake
step. If the bake fails the release fails there, rather than publishing
a
wheel whose covers are silently absent; the ppt-engine gate asserts one
cover
  per template per language in the built wheel.
- An install from source has no baked covers and behaves exactly as it
does
  today, rendering them once at boot.
- Rollback: revert the squash commit. Nothing is stored, cached or
migrated,
  and a host with the old wheel keeps drawing its own covers.

- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-09-23 14:56:44 +08:00
Dizhan Xue
5ef7b8302f
feat(*): give every channel its app icon and a name in both languages (#696)
## Summary

The channels section of the settings dialog drew a hashed letter tile
for every
entrance. It now draws each app's own icon, in the list row and in the
picked
channel's header, and every entrance is named in both of the web UI's
locales.

**Icons.** `ui-web/src/assets/channels/` holds eleven files:

- Nine are the icons the vendors publish on their App Store listings
(China
  storefront for Feishu, DingTalk, WeCom, WeChat and QQ; US for Slack,
Telegram, Discord and WhatsApp), resampled from the 512px artwork to
96x96
PNG. For the five Chinese apps the listing is where a colour icon was
found:
the permissively licensed icon sets checked (lobe-icons,
`@cherrystudio/ui`,
SVG Logos, Simple Icons and the brand sets on Iconify) carry them only
as
  single-colour glyphs.
- `matrix.svg` and `mochat.svg` are the files matrix.org and MoChat
serve as
  their own marks, copied byte for byte.
- Mail is a protocol rather than a brand, so it gets a neutral envelope
drawn
  in the component.

`scripts/refresh_channel_marks.py` names the listing or URL behind every
file and
regenerates the directory; `LICENSES/README.md` records the basis for
showing
them (the vendors' marks, identifying the row they sit on, as with
AMD's).
`ChannelMark` is keyed by channel id, never by the row's name, and falls
back to
the letter tile for an id with no mark and for a file that fails to
load. The
asset digest helper moves out of `ProviderMark.tsx` into
`lib/assetStamp.ts` so
both marks share it and a refreshed icon is not served from cache.

**Names.** Six brands bypassed the message catalogue with one verbatim
spelling,
and `gui.chan.mochat` held the Chinese name in its English slot. Every
entrance
now has a `gui.chan.<id>` entry in both locales (Slack, QQ, Telegram,
Discord,
WhatsApp and Matrix keep their Latin names in Chinese, as their own
Chinese
builds do), the verbatim path is gone (`ConnChannel.key` is required),
and the
English name is MoChat. The adapter's `display_name`, which the CLI
prints, and
the two channels docs pages also say MoChat. The TUI's generated
catalogue is
regenerated.

**Guards.** `tests/test_ui_channel_marks.py` holds the mark table equal
to the
adapters, the shipped files and the refresh script, and the PNGs to
96x96.
`catalogue.test.ts` holds every entrance to both locales and to English
in the
English slot. `tests/test_channels_display_names.py` holds the CLI and
the web UI
to one English name per channel.
`scripts/gates/channel-mark-css.test.mjs` reads
the expected box off `.pmtile`'s own rule, since the mark stands in for
that
per-container-sized tile.

**Also in this PR.** `.pre-commit-config.yaml` adds `channels/` to the
end-of-file fixer's exclude beside `providers/` and `agents/`:
matrix.org writes
`matrix.svg` without a trailing newline, and appending one would end the
byte-for-byte copy.

**Existing tests whose meaning changed.** `test_channels_mochat.py` now
expects
the MoChat display name; `source.test.ts` now expects every row, a brand
included, to be named through the message catalogue; the
`ConnectionsPage`
fixtures move from `name:` to `key:` (the stand-in translator hands a
key back
as its text, so no query changed); the DOM snapshot shows the mark in
place of
`.pmtile`.

**Deliberately unchanged.** Adapter docstrings, log lines and class
names keep
"Mochat" (identifiers and developer text, not a name a reader is shown).
The
TUI draws no channel list, so it gets no icons. The refresh script needs
the
network and is run by hand; neither CI nor the build runs it.

**Weight.** Eleven files, about 66 KB, copied into `dist/assets` and the
wheel.

Nine commits: the feature, then one per finding of the pre-submit sweep.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Suites ran before the last commit, which changes only
`.pre-commit-config.yaml`
and was checked with pre-commit.

- `npx vitest run --no-file-parallelism` in `ui-web/` (with
`NODE_OPTIONS=--localstorage-file=<file>`, needed under node 26): 202
files,
2790 tests, 2788 passed, 2 failed. The two are the "when storage
refuses"
cases in `src/features/desk/palette.test.ts` and `store.test.ts`, which
fail at
every revision under this machine's node 26 and pass under CI's node 22;
this
  branch touches neither.
- `npm run gen:check`, `npm run lint` (0 errors, the 4 existing
warnings),
  `npm run type-check` in `ui-web/`: pass. `npm run type-check` and
  `node scripts/gen-i18n.mjs --check` in `ui-tui/`: pass.
- `npm run build`, `python3 ui-web/build.py`, `check-page.mjs`,
`check-css.mjs`,
  `check-class-namespace.mjs`: all OK.
- `uv run pytest -q` with all extras: 25778 passed, 114 skipped, 1
failed:

`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
which fails the same way on a checkout without this branch (this machine
has
  npm on four PATH entries, which defeats its no-npm case).
- `ruff check` and `ruff format --check` over the Makefile's lint
targets: clean.
`lint-imports`: 10 kept, 0 broken. `ty check` on the changed modules:
clean.
- `uv run --isolated --frozen --group docs mkdocs build -f
docs-site/mkdocs.yml --strict`:
  exit 0; both channels pages render MoChat.
- `pre-commit run --from-ref origin/main --to-ref HEAD`: every hook
passes except
prettier (ui-tui), which flags only
`src/__tests__/instanceModeCommand.test.ts`,
unchanged here (last touched by #669); CI's pre-commit job skips that
hook,
  having no `node_modules`.
- `scripts/check_commit_messages.py origin/main..HEAD` and commitlint:
pass.
- Red first and mutants: every new case failed before its
implementation.
Mutants, each reverted with the tree clean after: no `onError` fallback,
a
failure kept as a boolean, marks keyed by name, the asset digest
dropped, `qq`
dropped from the table, the English name set back to "Mochat",
`.channel-mark`
resized, and a slot-specific `.pmtile` box. Each turned the tests
written for it
red: 1, 1, 3, 1, 3 Python guards, the display-name guard, and the CSS
gate twice.
- Browser, headless Chrome over the built page with `?stub=1`: all
twelve rows
draw a 38x38 mark with its file loaded and the digest in its URL, and no
letter
tile is left. The letter tile measures the same 38x38 with an 11px
radius in
both slots. English reads Feishu, Email, WeChat, WhatsApp, Telegram,
Discord,
MoChat, WeCom, Slack, DingTalk, QQ, Matrix. After Settings > General >
Chinese,
MoChat shows its Chinese name and the six brands keep their Latin names.
  Matrix's mark follows the theme switch on a light OS.
- `raven channels list` from this tree: `mochat | MoChat`.
- `scripts/refresh_channel_marks.py` run twice: the second run
reproduced every
PNG byte for byte, and the two SVGs are `cmp`-identical to a separate
fetch.

- [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: the channels section shows app icons where it showed
letter tiles,
and MoChat's English name changes from its Chinese name (web UI) and
from
"Mochat" (CLI). The other eleven names read as before. No config, RPC or
stored
data changes; `ConnChannel.name` was internal to `ui-web`. Rollback is
reverting
the squash commit.

- [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[1m]) <noreply@anthropic.com>
2026-09-23 14:11:10 +08:00
zhanghui
010ca4b44d
fix(*): probe raven web before launch and install plugins from the release list (#588)
## Summary

The one-line installers are served from `main` and install the latest
published release, so an ending on `raven web` (PR #476) shipped against
v0.1.13, which has no `web`: since 2026-09-17 every `curl
raven.evermind.ai/install.sh | sh` has ended in `No such command 'web'`
with exit code 2. This PR fixes that class of failure and the upgrade
defect behind the next release.

- **Probe rule.** Every `raven <sub>` call in `install.sh` and
`install.ps1` is preceded by `raven <sub> --help`. When the probe fails
the install ends on the one command every release has (`raven`), and
neither the stop nor the page's own exit code becomes the script's.
`RAVEN_NO_LAUNCH=1` skips the launch (CI, Dockerfiles); the PATH hint
the launch displaced is back.
- **The release says what it ships.** `release.yml` writes
`raven-plugins.txt`, one `name @ url` line per plugin wheel it just
built, beside the wheel and the constraints. Both installers derive
every URL from the release page redirect and hand the list to `uv tool
install --with-requirements`. No GitHub API call, no grepping asset
names out of its JSON. A release without a list (0.1.13 and older)
installs raven alone, as it effectively did before.
- **Upgrade keeps the plugins.** uv replaces a tool's requirement set
with what one command names, so the old helper (`raven[channels]` only)
uninstalled every plugin the installer had put in. The helper now
installs from the same list, descends one loss at a time (engines, then
the memory plugin, then the channel extras), and refuses to run without
the list rather than install raven alone. `raven upgrade` on an
up-to-date install whose list names a plugin it lacks reinstalls the
version with its plugins. The helper also moves a beta wheel URL's
deploy token into the request header (urllib reads `user:token@host` as
a host name) and copies it onto the list's URLs for uv.
- **Gates.** CI installs the latest release with the PR's scripts,
piped, on ubuntu and windows whenever an installer changes. The release
job installs itself from `dist/` with `install.sh` before the draft is
created and asserts the three plugin packages and `web` on the result.
The beta publisher builds and lists the same three plugin wheels. A
contract test holds the release workflow, the beta publisher, both
installers (remote list and local clone mode) and the helper to one
plugin list.

Decisions, for the reviewer: the plugins are not published to PyPI and
no names are reserved there; the list carries direct URLs, so no plugin
is ever resolved by name against an index. The LibreOffice and chromium
steps in the scripts are unchanged. The three hosted-memory plugins
(mem0, zep, memos) are built and uploaded as before but stay off the
default list.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

All installs below ran piped (`cat install.sh | sh`) in isolated
directories (own HOME, UV_TOOL_DIR, UV_TOOL_BIN_DIR, UV_CACHE_DIR,
RAVEN_HOME) with `RAVEN_MINIMAL=1`.

- `main`'s `install.sh` against the live latest release (v0.1.13): exit
2, `No such command 'web'`. This branch's `install.sh`, same
environment: exit 0, `Raven installed. Open a new terminal ... then run:
raven`; `raven --version` prints 0.1.13. With `RAVEN_NO_LAUNCH=1`: exit
0.
- A local release directory built by `scripts/publish_beta.py` (`_build`
at 0.1.14b1: raven wheel, three plugin wheels, constraints, list): this
branch's `install.sh` with `RAVEN_WHEEL_URL=file://...` installs raven
0.1.14b1, `python -c "import raven_everos, raven_design, raven_ppt"`
succeeds in the tool venv, and the uv receipt lists raven plus the three
plugins.
- The release workflow's two new step bodies (`Write the plugin list`,
`Install the release from dist with install.sh`) extracted and run
locally against that build: exit 0; removing one plugin wheel makes the
list step exit 1.
- The script's ending against the 0.1.14b1 install: `raven web --help`
exit 0, `raven web --stop` exit 0 with nothing to stop, `raven web
--foreground --port 18999` answers `GET /` with HTTP 200 after about 20
seconds.
- `uv run raven upgrade` and `uv run raven upgrade --check` from the
checkout against live GitHub: `Raven 0.1.13 is up to date.`, exit 0.
- `uv run pytest tests/integration/test_cli_upgrade_real_uv.py`: 2
passed. The test now installs the old fixture `--with` a companion wheel
and asserts the companion survives the upgrade; against `main`'s helper
the same test fails on that assertion.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py tests/test_updates_upgrade.py
tests/test_publish_beta.py tests/test_cli_smoke.py`: all pass (37 + 6 +
188 on the last run of each).
- `uv run pytest` (full suite, before the last installer rewrite): 23543
passed, 121 skipped, 4 failed. The 4 (`test_agents_oncall_launcher`,
`test_agents_code_launcher`, `test_agent_loop_token_budget`,
`test_ppt_engine_image_search`) fail identically on plain `github/main`
in a separate worktree.
- `uv run ruff check` and `uv run ruff format --check` on every touched
Python file: clean. `sh -n install.sh`, `bash -n install.sh`: clean.
Both workflow files parse.
- Not run here: the new CI job's Windows leg and the release gate inside
GitHub Actions (this PR is their first run). `install.ps1` has no local
PowerShell to execute it; its changes mirror `install.sh` and are pinned
by the text tests.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible changes: the installers no longer fail on a release without
`web`; they print the plugins they install and a warning when a release
carries none; `raven upgrade` refuses to proceed when the target
release's plugin list cannot be fetched (previously it would install
raven alone and drop the plugins), and repairs an up-to-date install
that lacks listed plugins. The beta channel's next publish carries the
three plugin wheels and the list; a beta upgrade to a build published
before this change will refuse for lack of a list, and rerunning the
beta installer is the remedy.

Rollback: revert the commit. Releases published with `raven-plugins.txt`
keep working with the old scripts, which ignore the file.

- [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-fable-5-1) <noreply@anthropic.com>
2026-09-21 16:25:33 +08:00
zhanghui
b91abe5e09
ci(*): keep commit lint off the default branch's history (#531)
## Summary

A pull request whose base is not the default branch carries, in its
`BASE..HEAD` range, every commit the default branch has gained since the
two
diverged. Both commit linters read that range, so they re-read history
that
already passed this gate when it landed and that nobody can rewrite now.

#529 is the case that surfaced it: merging `main` into
`refactor/ui_web_architecture` puts 38 `main` commits in range, one of
which
(`b01534d0`, #471) carries a `Co-authored-by` trailer with a non-ASCII
name.
The gate reports that PR red for a message it did not write. The same
will
happen to every future catch-up merge.

`scripts/check_commit_messages.py` now takes several revision arguments
and
passes them to `git log`, so a caret exclusion works. Commitlint has no
equivalent flag, so the workflow iterates the same revision list and
lints one
message at a time. On a pull request the workflow excludes the
repository's
default branch; a push to the default branch is unchanged and still
lints what
it pushed.

This does not touch the offending commit on `main` and does not relax a
rule:
a commit that a PR actually introduces is linted exactly as before.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

`uv run pytest tests/test_check_commit_messages.py
tests/test_commit_lint.py -q`
-- 15 passed. Three of those cases are new and cover a repo where the
default
branch carries a rejected message and the feature branch merges it in:
the
range fails without an exclusion, passes with one, and still fails when
the
bad commit is the branch's own.

Mutation check on the new cases: replacing `_commit_messages(args)` with
`_commit_messages(args[:1])`, which is the behaviour before this change,
turns
`test_excluding_the_default_branch_skips_the_history_it_carries` red and
leaves
the other three green. The pin fails when the fix is removed.

Against the real history behind #529, with the checker run directly:

- `check_commit_messages.py "bc74bf73..a0666244c"` -- exit 1, naming
  `b01534d02` exactly as CI does.
- the same range plus `^github/main` -- exit 0.

The workflow's new loop was run as written against both ranges: 0
commits to
lint on the catch-up range, and a planted `Update stuff.` commit on a
feature
branch still sets the failure flag.

`make lint-python` -- clean. `scripts/check_source_language.py` over the
branch
-- exit 0; the test's non-ASCII message is built from an escape, so the
file
itself stays ASCII.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

Commitlint now starts once per commit instead of once per range, so a PR
with
many commits spends a second or so more in this job. The exclusion only
ever
removes commits that are already on the default branch, so nothing a PR
introduces escapes either linter.

Rollback is reverting this PR; the previous behaviour is one range
argument and
one commitlint invocation.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A. Unblocks the `commit messages` check on #529.

---------

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-09-20 15:21:54 +08:00
Dizhan Xue
3dd06f6ea0
feat(docs): add a bilingual documentation site and its deploy pipeline (#507)
## Summary

Stands up a bilingual MkDocs site under `docs-site/`, published to
GitHub Pages
by a workflow that builds on every pull request and deploys only from
`main`.
Fourteen topics ship in English and Chinese: the quick start,
self-hosting,
Docker, the WebUI, the sandbox manual, the runtime architecture, the
command
reference, the repository layout, the developer workflow, the
proactivity design
and reference pair, the self-evolution map and the tracing API.

This pull request is additive. Both READMEs keep their prose and gain
one link
to the site in the header row; trimming them is deliberately a second
pull
request, so the site can be confirmed live before anything depends on
it.

Key decisions:

- **`docs-site/`, not `docs/`.** `docs/README.md` defines `docs/` as
design
notes and dated records, and `docs/plans/` is an archive explicitly not
held
  to today's layout. A user manual has the opposite lifecycle.
- **Full bilingual parity**, via the `mkdocs-static-i18n` suffix
structure
(`page.md` beside `page.zh.md`). Parity decays immediately without a
guard, so
  a test fails when a page has no twin.
- **Anchors are pinned on the Chinese side.** A CJK heading slugifies to
  nothing, so Markdown numbers it `_1`, `_2`, and inserting one heading
renumbers every anchor below it, silently breaking links readers already
hold.
Each Chinese heading therefore states the anchor its English twin gets
for
  free: 133 heading anchors, identical across the two languages, none
  positional.
- **A left rail, not a top bar.** The header carries the brand, the
search box
and the navigation tree down the left; the table of contents on the
right is
  one continuous polyline clipped to the headings currently on screen.
- **No template overrides.** Material customises through
`theme.custom_dir` with
Jinja partials, those partials are `.html`, and
`scripts/check_large_files.py`
  holds `.html` in `BLOCKED_ASSET_EXTENSIONS`. The skin is therefore one
stylesheet remapping Material's own custom properties, plus one script
for the
table-of-contents rail. The brand mark is a `data:` URI for the same
reason.
- **An owner-signed `docs-site/` exemption zone** in AGENTS.md section
1.3. The
i18n config carries the Chinese navigation labels, and `mkdocs.yml` is
not
`*.md`, so the blanket suffix exemption does not reach it. A contract
test
holds the AGENTS.md list and `EXEMPT_PREFIXES` equal, so both moved
together.
- **The site never links out to a file it does not host.** Documents
that stay
in the repository are named as plain paths rather than linked, and a
guard
fails a page that links to an external webpage or a repository-relative
path.

Two defects found and closed here rather than after publication. The
Chinese
site rendered an English sidebar: navigation labels live in
`mkdocs.yml`, not in
any page, so comparing the two languages' Markdown finds nothing and
only the
rendered output shows it. And a control could be present, sized,
animated and
answer `querySelector` while being unclickable, because a popup Material
sized
for a top bar landed outside the viewport once the header became a rail.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

All commands run at the pushed head, rebased onto `origin/main`.

```
make check-large-files                                         exit 0
make check-source-language                                     exit 0
make docs-build                                                exit 0, 0 errors
  docs-site/site/index.html and docs-site/site/zh/index.html   both present
  mkdocs_static_i18n: Translated 17 navigation elements to zh
uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \
  tests/test_readme_scope_canon.py tests/test_docker_runtime.py \
  tests/test_living_docs.py                                    44 passed
uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed
pre-commit run --files <changed files>                         all hooks pass
git diff --check                                               clean
```

Anchor parity was measured on the built HTML rather than assumed: 14
page pairs,
133 heading anchors compared at h2 through h6, every one identical
between the
two languages and none positional.

The controls are hit-tested rather than queried.
`document.elementFromPoint` at
the exact point a reader clicks must return the control itself, which is
the
only check that catches an off-viewport popup; the language switcher,
the search
panel, the repository link and the table-of-contents rail each pass it.

The brand lockup is measured, not eyeballed. A failing test was written
first
and reported the wordmark sitting 4.00px below the mark's centre line;
it is
0.00px after the fix, and a 4x screenshot puts the residual optical
offset at
0.25px.

Every guard this branch adds was confirmed to fail first. The
brand-class guard
was mutated from both sides in turn: renaming `.em-eyebrow` in the
stylesheet
turned it red, renaming `class="em-standfirst"` in `index.md` turned it
red, and
it is green again with both restored. The anchor guard was shown to
catch both
failure modes, a missing anchor and a wrong one.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

No behaviour change to any shipped code path. Nothing imports
`docs-site/`, the
new Makefile targets are additive, and the only change outside
`docs-site/` and
its tests is one link added to each README's header row.

Rollback is deleting the branch: the site does not exist until Pages is
enabled
with `Source: GitHub Actions`, and every other change is inert without
it.

Disclosed residue, checked and deliberately not changed:

- The README header now links to `https://evermind-ai.github.io/Raven/`,
which
404s until Pages is enabled. It is the same URL the Documentation
section
  already carries.
- The `deploy` job is skipped on pull requests by design, so a green
check here
does not prove deployment works. The first real evidence is the `deploy`
job's
  own conclusion on the `main` run after merge.
- GitHub Pages is not enabled on this repository. Measured: `GET
/repos/.../pages`
returns 404. Under `Deploy from a branch` the uploaded artifact is
silently
ignored while the workflow still reports success, so the source must be
set to
  `GitHub Actions`.
- `tests/integration/` is excluded by `norecursedirs`, so the browser
suite is a
  local guard and never runs in CI.
- The self-hosting page's Makefile target, docker path and port claims
are
unguarded. They were equally unguarded in the README they came from, and
the
  owner ruled against adding a guard for them.
- The self-evolution SOP and the benchmark contract stay in the
repository and
are named as plain paths from the pages that reference them. The SOP is
a
translation of an upstream project's internal document and carries
redaction
placeholders, which is a publication decision rather than a formatting
one.
- `docs/plans/` still shows the pre-restyle `mkdocs.yml`. CONTEXT.md
defines that
directory as an archive of the tree as it stood, with an explicit rule
against
  updating an old plan to match a later change.
- The Chinese pages drop the brand's italic serif accent word. Cormorant
Garamond
carries no CJK glyphs, so it would fall back to another face without any
sign.
- The code font is Material's default Roboto Mono. The brand names four
  typefaces and no monospace, so none was invented for it.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 07:06:24 +00:00
zhanghui
a018351f95
chore(*): gate call correctness with a pinned type checker (#416)
## Summary

Nothing in this repo could see a signature change reach its callers.
Ruff reads one file at a time, the import contracts read edges rather
than calls, and the suite only covers lines it executes. The consequence
was concrete: a required `sandbox_home` argument added to
`BoxliteExecutor` reached `plugins-dist/design-engine`'s render path
with CI green, and a reviewer -- not a gate -- found it.

`ty` answers that question. This adds it as a pinned dev dependency, a
`make lint-types` target and a CI step, with **110 of its 133 rules
live**: nine switched off with their measured backlog recorded beside
each, fourteen shipped disabled upstream and untouched.

Getting there meant clearing 81 diagnostics. This PR folds what were
three stacked PRs (#422 and #423, now closed); each rule's story is a
commit of its own.

### 1. The gate, at 108 rules (`chore(*): gate call correctness...`)

21 diagnostics to clear, five of them real:

| Where | What |
|---|---|
| `evolver/orchestrator/production.py` | `design_of` annotated as taking
two parameters while its docstring, its only implementation and its one
call site all use three |
| `raven/cli/provider_commands.py` | `dict[str, callable]` -- the
builtin function, not a type, so the annotation asserted nothing |
| `raven/config/schema.py` | `Config` is a `BaseSettings` but declared
`env_prefix` / `env_nested_delimiter` through pydantic's `ConfigDict`,
which does not carry those keys |
| `raven/spine/delivery.py` | `StreamDelta.conversation_id` is optional
and was used as a `dict[str, str]` key; a delta without one stored a
`None` entry the close path then read as "no open stream", losing that
stream's done marker |
| `research_flow/support/harness_text.py` | a predicate table typed its
matchers as `object`, so nothing checked they are callable |

The rest were unproven invariants and annotations wider than the code:
three late-bound callables asserted where a comment used to carry the
claim, one closure binding the callable it guarded instead of re-reading
it, four `hasattr` probes that now check what the call actually needs,
and a contextmanager yielding the value it just set.

### 2. `unresolved-import` (`fix(*): resolve the imports the type gate
could not`)

21 diagnostics; three were stale module paths nothing had run into:

- `HarnessNode.current_core_version()` read `raven.__core_version__`, a
module that exists neither here nor in the wheel
`scripts/build_core_wheel.py` produces. The read sat inside `try/except
ImportError`, so the except branch was the only branch and **every node
`store.py` saved recorded `core_version="unknown"`**. It reads
`raven.__version__` now and returns `0.1.13`.
- `raven/agent/loop/wiring.py` imported `SkillForgeRouterConfig` from
`raven.config.schema`; it lives in `raven.config.raven`. Under
`TYPE_CHECKING`, so the annotation simply meant nothing.
- three scripts imported `raven.context_engine.base` and
`raven.memory_engine.base`, neither of which exists. **Two failed at
module import** -- running them was not possible.

The other eighteen were the environment: the three agent products keep
their plugin package beside them, so their roots are declared in
`[tool.ty.environment]`; `lxml` ships a compiled `etree` with no type
information, so `lxml-stubs` is a dev dependency (real types rather than
five silenced lines); `uno` and `com.sun.star.*` are suppressed per
line, since that worker runs inside LibreOffice's own interpreter.

### 3. `invalid-return-type` (`fix(*): make the declared return types
true`)

39 diagnostics, and **one stale annotation held eight of them**:
`run_turn` and the `_run_turn` behind it were declared `-> LoopOutcome`
while all three of their returns build a `TurnOutcome` -- a different
dataclass with no field in common. Nothing broke, because the spine
worker reads what it actually gets and `LoopOutcome` never leaves
`_run_agent_loop`. The annotation was the only thing wrong.

The other 31: nine annotations narrower than the code (five `return
tuple(<genexpr>)` typed as fixed-arity tuples, an inner `one()` still
declaring the two-tuple it returned before a third element was added,
`image_block`'s TypedDict), five declarations refusing a value the
function returns (four tool `execute` overrides saying `-> str` while
returning `ToolResult`), seven invariants that lived in a `# type:
ignore` comment, and ten honest widenings.

### 4. What the gates then caught in this PR's own work

- The qq factory guard passed locally only because an earlier test had
left an event loop behind. Reproduced the CI state
(`asyncio.set_event_loop(None)`), then made the test async so the loop
is its own.
- `invalid-return-type`, while still disabled, hid a regression
introduced here: the qq factory returning the class instead of an
instance. Found by diffing the rule histogram, which is why that rule is
on now.
- The diff-coverage gate named four lines in `raven/routing/cache.py` --
the asserts this work had just added, sitting inside a `try` whose
`except Exception` would have swallowed the `AssertionError` and served
the stale cache. `_do_refresh` returns its data now; the asserts, their
noqa and the swallowing all go with it.

`child_scope`, `QQChannel.start()` and `BenchmarkCache` had no tests at
all and have them now. Every one was mutation-checked.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `make lint-types` -> All checks passed; 81 diagnostics cleared across
the three rule sets
- Gate proven live three times, once per rule: a missing argument, an
import of a module that does not exist, and a function returning a str
under `-> int` each turn it red, and removing the probe turns it green
- `uv run ruff check` + `ruff format --check` over all six trees ->
clean
- `uv run lint-imports` -> 10 kept, 0 broken; `deptry raven` (all
extras) -> no issues; `uv lock --check` -> resolved
- `make check-source-language` -> exit 0; `commitlint` -> exit 0
- `make coverage` locally: **22050 passed, 45 skipped, 4 failed**; diff
coverage 92.59%
- All four failures are **pre-existing on `main`**, checked by a real
checkout in the same environment where they fail identically: two
`test_the_products_tool_face_*` launcher tests,
`test_a_ceiling_as_large_as_the_window_still_leaves_room_for_history`
(`reserved_tools = 6044 > 6_000`), and
`test_a_missing_key_is_said_once_rather_than_per_query`
(environment-dependent: it asserts `SERPER_API_KEY` is absent)
- Rule counts measured with both `--extra dev` and `--all-extras` --
identical, so this gate's verdict does not depend on which optional
packages are installed

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

Behaviour changes are confined to the fixes listed above, and each
replaces an error path with a correct one: nodes are stamped with the
real raven version instead of `"unknown"`, two scripts that could not
start now start, the stream bookkeeping no longer stores a `None` key,
and a cache refresh returns what it fetched. Everything else is a
declaration moved to match what the function already returned.

`tests/` is out of the gate's scope (113 diagnostics under the same
rules). Tests are executed, so a broken call there is already loud; this
gate is for code CI does not run. Bringing them in is sized, separate
work.

Rollback: revert the whole PR to drop the gate and its fixes together,
or delete the `[tool.ty]` block, the `lint-types` target and its CI step
to keep the fixes and drop only the gate.

- [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) <noreply@anthropic.com>
2026-09-16 07:33:14 -07:00
Kevin Hu
8bb47a6eae
feat(providers): expand the provider catalog to 55 and give each a brand mark (#393)
## Summary

Takes the provider registry from 24 specs to 55 and gives the web UI a
brand mark for every provider and model family.

<img width="1998" height="1356" alt="image"
src="https://github.com/user-attachments/assets/dd909dd3-c742-45d0-a94d-61ccb1e30a0e"
/>

Four groups of providers are added: Western labs and inference hosts
(xAI, Mistral, Together AI, Fireworks AI, Perplexity, Cerebras, Hugging
Face, Poe), CN vendors (Xiaomi MiMo, Baichuan, Baidu Cloud, StepFun,
LongCat, ModelScope, Qiniu), resale gateways (302.AI, DMXAPI, BurnCloud,
ocoolai, PPIO, Lanyun, AlayaNew, SophNet, TokenHub, Xirang, PH8, AIOnly,
AMD GPU Cloud) and self-hosted servers (GPUStack, OpenVINO Model
Server). BigModel, Zhipu's CN platform, joins Z.ai, and the two Zhipu
platforms fold into a single row in the provider rail.

LiteLLM routes nine of them from a key plus a prefixed id. The other
twenty-one speak OpenAI's API with no driver of their own, so each
borrows OpenAI's driver and is told apart by its address, the way
SiliconFlow already was.

On the web UI side the provider rail gains name and connection-state
filtering, drops the generic Custom row, and keeps its scrollbar off the
connection dots. Provider marks move from Lobe Icons to the vendors' own
colour marks, and LICENSES/README.md records the new attribution.

Three decisions worth a reviewer's attention:

- The two "read-only exec allowlist and approval grants" commits from
the source branch are left out, because that work is already on main.
This was verified by symbol rather than by commit subject: every def and
class the commits add is already present.
- The README prose edits are dropped. They updated a "Providers and
Gateways" paragraph that main no longer carries after the readme
restructure, so the text had no correct place to land. Only prose was
affected; no code was lost.
- The LICENSES/README.md conflicts were resolved by merging both sides
rather than taking one. The new Cherry Studio attribution entry and the
DMXAPI resampling note are kept, while main's sub-agent mark count
(fourteen, including this project's own raven.svg) is kept over the
incoming "thirteen", because fourteen is what the tree holds.

Three fixes landed on this branch after review, beyond the provider work
itself:

- Poe ships no default and no shortlist. Its ids were the maker's
spelling, and only the outer "poe/" comes off on the way out, so the
shipped default reached Poe as a model it does not have. Routing is
unchanged and a real bot id still works.
- The upgrade marker path is read from raven.home rather than through
raven.config, whose package imports pydantic. The handoff writes that
marker from the tool environment it is replacing, which has no such
dependency, so `raven upgrade` aborted before the helper was spawned.
This one is a pre-existing bug on main, merged in here rather than left
to a separate PR.
- Two pre-existing CI gates are repaired: check-page counted two inline
script blocks where page.html has carried three since the asset digest
was added, and a doctor test asserted a path that rich folds at a column
decided by the tmp directory's length. Both were failing on main as well
as here.


## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Ran the provider, catalogue, resolution, RPC, onboarding, doctor and
upgrade suites together: 1240 passed, 103 skipped, no errors. An earlier
run of these reported a collection error in
tests/test_cli_onboard_commands.py for a missing raven_everos; that was
an incomplete local environment, resolved by the uv sync that builds
plugins-dist, and not a property of this branch.

ui-web vitest: 104 files, 1704 tests, all pass. ui-tui: lint, lint:rpc,
lint:i18n, type-check, build all clean and 2072 tests pass.

The page gate was run end to end from a clean build: npm build,
build.py, then check-page, count-shared-globals and check-css, all three
green.

Ran `make check-large-files`: passes, nothing over the limit. The
largest touched file is 340 KB. `uv run ruff check` and `ruff format
--check`: clean.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible changes: the onboarding catalog and the settings page list
55 providers instead of 24, the provider rail gains a filter, the
generic Custom row is gone, and provider marks are now the vendors' own
colour marks.

Security: the twenty-one providers that borrow OpenAI's LiteLLM driver
inherit its built-in default endpoint, api.openai.com. A spec that kept
its own address to itself would post someone else's key there, so a test
sweep asserts every borrowed-driver provider either hands LiteLLM its
own default or is reached by address.

Backward compatibility: existing provider configuration keeps its names
and fields, so current configs continue to resolve.

Rollback: revert the squash commit. No migration or config rewrite is
involved.

- [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) <noreply@anthropic.com>
2026-09-15 22:56:47 -07:00
KT
a5f84b7164
ci(*): run unit tests as four shards and speed up the suite (#413)
## Summary

The unit job takes twelve minutes on one runner. The first cut of this
PR took the production waits out of the tests, which made the suite a
quarter faster on a laptop and moved CI by 14 s (pytest 720.95 s on
main, 706.57 s here): the runner is three to four times slower than a
laptop on CPU-bound tests, and two of the twelve minutes are the four
xdist workers importing every test module. So the PR now attacks the
wall clock from every side that CI's own numbers pointed at.

- `ci(*)`: the unit job runs as four shards. pytest gains `--shard K/N`
in `tests/conftest.py`, decided in `pytest_ignore_collect` so a shard
never imports the other shards' files; test files are dealt round-robin
over their sorted list so the slow families that sort together (the ppt
engine's) are spread out. Each shard writes coverage data and no report;
a `coverage` job downloads the four data files, combines them, writes
`coverage.json` and `coverage.xml`, and runs the gates that used to
follow the tests.
- `perf(ppt-engine)`: `menu()` caches its reading of a template, capped
at eight entries. One bind reads the bound template and then every other
bundled template for the borrow offer; with ten templates bundled, every
bind evicted what the next one needed and re-measured all of them with
freetype. The cap is 32 and a hit moves its entry to the back. On this
PR's first CI run the template-tool file alone was 257 s of the
over-ceiling list, its tests 10 to 26 s each.
- `test(*)`: an autouse fixture collapses the provider chat retry
ladder, the loop's LLM-error ladder and the memory store backoff to a
millisecond per step, and the steer hook grace to one poll. It keeps
each tuple's length because both ladders count attempts with `len()`;
the steps are a millisecond rather than zero because the store pipeline
waits with `wait_for(stopping.wait(), timeout=delay)`, and a zero
timeout cancels that wait before it runs. A test that proves a timing
property opts out with the new `production_timing` marker. Ten tests
spent 257 s of the suite's worker time in those waits; none asserted on
the time.
- `test(*)`: a wall-clock ceiling. Setup plus call over 2 s on a test
marked neither `slow` nor `production_timing` is listed at the end of
the run; `--wall-clock-ceiling-strict` fails an otherwise green session
on it. Warning only here; CI flips to strict once the remaining tail is
marked.
- `test(*)`: every test created two numbered temp directories, and
pytest picks each number by scanning the base temp dir; the fake home is
now a sibling of `tmp_path`. `MPLCONFIGDIR` points at a git-ignored dir
in the checkout, because the fake home changed per test and matplotlib
rebuilt its font list from the system fonts on every run.
- `refactor(agent)`: the outer LLM-error retry ladder default `(15, 30,
60)` lived in three places; it is one constant in
`raven/config/schema.py` now, read by both `RecoveryLimits` and
`_ladder`. Behaviour unchanged.
- `test(updates)`: the first sharded run turned up an order dependency.
`beta_channel` binds `ReleaseInfo` from `raven.updates.upgrade` at
import, the update-notice tests stand a fake in for that module through
`sys.modules`, and `_refresh` imports `beta_channel` lazily; a worker
that imported `beta_channel` for the first time inside that test got an
`ImportError` swallowed as a failed refresh. The test module now imports
`beta_channel` at the top.
- `ci(*)`: the PR diff gate named every `.py` under `plugins-dist` as
production code while coverage measures only `raven` and `raven_everos`,
so a change to the ppt or design engine could never appear in the report
and the gate refused every such PR on sight; the first sharded run hit
it on `menu.py`. The pathspec now names `plugins-dist/everos-memory`,
and a test holds every production pathspec to a package some `--cov`
flag in the Makefile measures.
- Two slow tests were not waits: the sandbox second-cancel test
cancelled one tick too early (two pending cancels coalesce into one
`CancelledError`) and now waits, under a one second timeout, for the
kill to land; the two thousand-session dispatch tests wrote a span per
refused enqueue through a store that opens its file per span, so tracing
is off for them. Follow-up on the product side: `raven/tracing/store.py`
should reuse its handle.

The suite has 30 upper-bound assertions of the form `assert elapsed <
X`; shortened delays can only make those looser.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), 22051 passed / 43 skipped each time:

| tree | wall clock | unmarked tests over 2 s |
|---|---|---|
| main before this branch | 372.82 s | (no ceiling yet) |
| after the waits were taken out | 279.65 s | 63 |
| this branch | 224.25 s | 39 |

The shards partition the suite exactly (`uv run --frozen --all-extras
pytest --collect-only -q -n 0 --shard K/4`, K = 1..4):

| whole | shard 1 | shard 2 | shard 3 | shard 4 | union | ids in two
shards |
|---|---|---|---|---|---|---|
| 22095 | 5058 | 5555 | 5955 | 5527 | 22095 | 0 |

196 / 195 / 194 / 194 test files per shard. A shard collects in 7 s
where the whole suite takes 23 s on the same machine. `--ignore` still
works under `--shard`: with four `--ignore` flags on shard 1, the
ignored file that shard owns is gone from its collection (5034 ids
against 5058).

Combining loses nothing. Two small runs with `--cov=raven
--cov=raven_everos --cov-branch --cov-report=` and `COVERAGE_FILE` set,
then `make coverage-combine COVERAGE_DATA_DIR=<dir>`, against one `make
coverage` of the whole suite on main:

| report | files | statements | branches |
|---|---|---|---|
| one run of the whole suite | 704 | 82634 | 25548 |
| two shards combined | 704 | 82636 | 25548 |

Same file set; the two extra statements are the new constant and its
import. A source package's never-imported files reach the combined
report through the shard that imported it, as they reached the single
run.

The menu cache, the three files that bind templates (`uv run --frozen
--all-extras pytest -q tests/test_ppt_engine_template_tool.py
tests/test_ppt_engine_outline_checks.py
tests/test_ppt_engine_default_templates.py`): 101 s of worker time in
the last profile, now `196 passed in 11.84s` with no test over 2.9 s.
The files that call `menu()` directly: `219 passed in 8.06s`.

The font cache, the formula render test at `-n 0`: 8.91 s cold, 0.69 s
on the next run. Seven home-sensitive files: `484 passed in 5.30s`.

Ceiling guard, both modes, with the ceiling forced low so it has
something to list:

```
uv run --frozen --all-extras pytest -q -n 0 --wall-clock-ceiling=0.01 tests/test_import_cycle_budget.py tests/test_updates_install_guard.py
uv run --frozen --all-extras pytest -q -n 2 --wall-clock-ceiling=0.01 --wall-clock-ceiling-strict tests/test_updates_install_guard.py
```

First: 28 passed, five listed, exit 0. Second: 24 passed, four listed,
exit 1 (the controller flips the status; workers do not).

`make lint-python` clean, `make lint-imports` passes. The CI run on this
PR is the measurement that matters: four `unit` shards and one `coverage
gates` job.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none: CI
plumbing, a cache cap, test setup)

## Risk

- The coverage gates now run in a job after the four shards. A red shard
skips the gates, a deliberate trade: combining three of four data files
would report a coverage drop that is not one, and the PR is red either
way. The gate scripts and their thresholds are unchanged.
- The diff gate no longer sees `plugins-dist/ppt-engine` or
`plugins-dist/design-engine` at all, as it could never judge them;
measuring them (`--cov=raven_ppt --cov=raven_design`, a new ratchet
baseline) is the follow-up that would bring them under the gate.
- `--shard` is opt-in; a plain `pytest` run collects everything as
before. Shard data artifacts are kept one day, the combined reports 30
days as before.
- No product behaviour change: the ladder default is the same tuple read
from one place; the menu cap only changes how long the cache keeps
entries.
- Test-only risk: a test that implicitly relied on a production-length
retry delay would see different timing. The full suite passed with the
fixture on, and a single test can opt out with `production_timing`.
- Rollback: revert the PR. The unit job goes back to one runner with the
gates inline; both markers are additive.

- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-15 16:00:49 +08:00
Tchen
5b4cce3f43 feat(ppt-engine): deliver where the user named, one route onto a page, and the ten templates
## Summary

This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:

- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
  publish writes the deck under `out/` and copies the same measured bytes to the path
  the user named, recording it with `role: "delivery"`. The PDF preview rides along only
  where its own `.pdf` name is free: a file already at that stem is the user's and is
  left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
  template page and writing into it with `replace_text` is the only route; a page whose
  block raises loses only itself and the pages after it still build; a draft counts
  against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
  tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
  LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
  nothing names the near miss before the inventory; a text frame with no paragraph at
  all can be written into; a cloned page's title size is said; `row_type_drift` compares
  the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
  and one of them also answered "the string you named is on page N of this template".
  That clause needs the file a page was cloned out of, and the only refusal holding it
  was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
  which the runner already sets in the author's own process and which this module
  already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
  contrast gate also measures the render's own word boxes, as extra regions through the
  same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
  the dark ground and read as legible.

Decisions the union forced, none of which drops a behaviour:

- The publish record is built !602's way, with its delivery `role`, and written the way
  D49 requires -- read back off the file, atomic, and refused rather than silent when
  the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
  survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
  reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
  region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:

- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
  decision under two numbers.

Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.

## Type

- [x] Feature
- [x] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.

- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
  26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
  every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
  out plain `origin/main` in a clean worktree and ran the same two files: the same 6
  failed and 20 errors, the ids identical character for character. Nothing on this branch
  touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
  that failed on the previous revision is retired on the new base and its replacement,
  `test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
  The 6 failures and 20 errors are all cron timezone tests failing identically on plain
  `main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
  tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
  satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
  each run as a measurement rather than asserted; the `unreadable` gate was run through
  the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
  page 12 under one word at 1.6:1.

- [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: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.

Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.

Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.

- [x] Backward compatibility considered
- [x] Security impact considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 05:52:36 +00:00
0xKT
cfe806a6e0 feat(cli): onboard spends one real search on the web_search key
## Summary

The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.

- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.

Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
  tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py    410 passed
make lint-python                                                     clean
make check-source-language                                           exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD     exit 0
```

Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.

Not verified: a live run against a real vendor key.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.

## Related Issues

N/A
2026-09-11 02:35:44 +00:00
userName20260323
62aefbd1e5 feat(cli): onboard spends one real search on the web_search key
## Summary

The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.

- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.

Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
  tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py    410 passed
make lint-python                                                     clean
make check-source-language                                           exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD     exit 0
```

Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.

Not verified: a live run against a real vendor key.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.

## Related Issues

N/A
2026-09-11 02:35:44 +00:00
0xKT
02ea26aa6f refactor(permissions): the shell command policy seats where it is enforced
## Summary

`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.

The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.

Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.

Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.

This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
    tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
    tests/test_permissions_gate.py tests/test_acp_server.py \
    tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s

$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s

$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
    raven/acp/server.py raven/agent/tools/shell.py
All checks passed!

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.

Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.

Effect on the dependency graph:

```
permissions -> agent edges     1  ->  0
mutually importing pairs      14  ->  13
packages in an import cycle   22  ->  22   (unchanged)
```

The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No user-facing surface changes.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.

No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.

## Related Issues

N/A
2026-09-11 02:35:05 +00:00
gloryfromca
c01af5faa3 refactor(permissions): the shell command policy seats where it is enforced
## Summary

`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.

The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.

Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.

Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.

This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.

$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
    tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
    tests/test_permissions_gate.py tests/test_acp_server.py \
    tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s

$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s

$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
    raven/acp/server.py raven/agent/tools/shell.py
All checks passed!

$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```

The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.

Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.

Effect on the dependency graph:

```
permissions -> agent edges     1  ->  0
mutually importing pairs      14  ->  13
packages in an import cycle   22  ->  22   (unchanged)
```

The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No user-facing surface changes.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.

No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.

## Related Issues

N/A
2026-09-11 02:35:05 +00:00
0xKT
632562895a feat(ui-tui): tool cards open themselves, the strip marks here, ticker words split
## Summary

Three reader-facing changes to the TUI transcript and the instance strip.

**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.

The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.

Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.

**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.

**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.

`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on a worktree at this branch's tip, against the current main tip:

- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0

No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Three user-visible changes, all inside the terminal UI:

- a tool call that returned something now opens to a capped preview instead of
  staying shut. A reader who prefers it shut clicks once, and that decision
  holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
  has one column less for its name.
- the status ticker shows a different set of glyphs and words.

No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 12:42:09 +00:00
ethanwwwwwwww
c3822b77d2 feat(ui-tui): tool cards open themselves, the strip marks here, ticker words split
## Summary

Three reader-facing changes to the TUI transcript and the instance strip.

**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.

The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.

Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.

**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.

**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.

`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on a worktree at this branch's tip, against the current main tip:

- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0

No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Three user-visible changes, all inside the terminal UI:

- a tool call that returned something now opens to a capped preview instead of
  staying shut. A reader who prefers it shut clicks once, and that decision
  holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
  has one column less for its name.
- the status ticker shows a different set of glyphs and words.

No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 12:42:08 +00:00
0xKT
6ff5cacdcf docs(memory_engine): the node brief carries the owner's scope as written
## What

Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.

## Why

On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:

- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
  from three classes outside the falsified list" (the falsified list named 18 specific
  hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".

The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.

## The three rules

1. The owner's words and scope go into every node's brief as written; the orchestrator's
   own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
   *not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.

## Checks

- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
  `tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
  144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
  identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
  adds later in the same file.
2026-09-10 12:39:43 +00:00
silverLXT
d28bb96163 docs(memory_engine): the node brief carries the owner's scope as written
## What

Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.

## Why

On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:

- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
  from three classes outside the falsified list" (the falsified list named 18 specific
  hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".

The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.

## The three rules

1. The owner's words and scope go into every node's brief as written; the orchestrator's
   own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
   *not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.

## Checks

- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
  `tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
  144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
  identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
  adds later in the same file.
2026-09-10 12:39:43 +00:00
0xKT
baac0a6c0f feat(ui-web): ask an agent whether it works, from its card
## Summary

The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.

It comes back as a section of the card, not a third verb on the row:

- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.

No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.

**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:

- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.

This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.

**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)

**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.

**Checked and deliberately not changed, for the reviewer:**

- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:

- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.

```
npm run test --prefix ui-web    101 files, 1550 passed
npm run test --prefix ui-tui    141 files, 2017 passed, 13 skipped
npm run gen:check  --prefix ui-web    generated client matches the contract (162 methods)
npm run type-check --prefix ui-web    clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui    23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py    pass over the branch
make build-ui                                          dist rebuilt and served
```

The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)

## Risk

User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.

- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 10:00:46 +00:00
Handsome-wzw
e4b1021d73 feat(ui-web): ask an agent whether it works, from its card
## Summary

The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.

It comes back as a section of the card, not a third verb on the row:

- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.

No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.

**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:

- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.

This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.

**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)

**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.

**Checked and deliberately not changed, for the reviewer:**

- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:

- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.

```
npm run test --prefix ui-web    101 files, 1550 passed
npm run test --prefix ui-tui    141 files, 2017 passed, 13 skipped
npm run gen:check  --prefix ui-web    generated client matches the contract (162 methods)
npm run type-check --prefix ui-web    clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui    23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py    pass over the branch
make build-ui                                          dist rebuilt and served
```

The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)

## Risk

User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.

- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 10:00:45 +00:00
0xKT
ab4a605eb5 fix(*): let read_skill serve hub bodies the skill menu advertised
## Summary

The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.

Key decisions:

- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
  the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
  `use_skill` and the segment builder's post-gate hydrate refuse exactly what
  they refused before. Reading is the weaker case because it installs nothing
  and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
  flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
  products rather than being one, so reporting the root refused a skill for
  mentioning XDG at all. The reported path now runs down to the segment naming
  the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.

`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.

- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
  tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
  3 skipped. The three skips are pre-existing and environment-bound (two
  `chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
  note `these instructions reference paths outside Raven (~/.config/mcporter,
  ~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.

The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.

The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.

Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.

## Related Issues

N/A
2026-09-10 09:47:05 +00:00
LivXue
2088cb4eae fix(*): let read_skill serve hub bodies the skill menu advertised
## Summary

The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.

Key decisions:

- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
  the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
  `use_skill` and the segment builder's post-gate hydrate refuse exactly what
  they refused before. Reading is the weaker case because it installs nothing
  and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
  flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
  products rather than being one, so reporting the root refused a skill for
  mentioning XDG at all. The reported path now runs down to the segment naming
  the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.

`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.

- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
  tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
  3 skipped. The three skips are pre-existing and environment-bound (two
  `chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
  note `these instructions reference paths outside Raven (~/.config/mcporter,
  ~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.

The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.

The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.

Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.

## Related Issues

N/A
2026-09-10 09:47:05 +00:00
0xKT
35563457d2 fix(ui-web): three ways the title editors leave a conversation nameless
## Summary

Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.

**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.

**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.

**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.

**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.

The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.

Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Branch and base run in separate worktrees, both at the same base, same interpreter.

- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
  1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
  introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
  `unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
  need `--localstorage-file` for `localStorage` to exist on this box at all, and with
  it the store no longer refuses, so the refusal each asserts does not happen. Both
  reproduce on the base, and neither file imports anything this change touches. A
  second environment settles it: review ran the same head and reported 1,536 tests
  passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
  `check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
  full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
  `lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
  `renamed` call, a missing export, a missing harness verb, and the pre-edit title.
  The ordering one is driven through the real `rpc.onReconnect` rather than
  `openLiveSession`, because the ordering is between the two and a test that calls the
  inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
  forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
  on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
  editor gone, button back, zero title calls, no page error. Reconnect with the editor
  open, forced by closing the socket from the page: before, `Cannot read properties of
  null (reading 'textContent')` with the input stranded and no session reload; after,
  heading restored, editor gone, reload done, no page error. Reconnect with a name
  typed into an open editor: heading and rail row both settle on the committed name,
  no page error. That probe renamed a real conversation, so its title was put back and
  the stored metadata checked byte-identical afterwards.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible, all of it in the same direction: a title that used to vanish stays put.

- Ending an editor on a conversation switch commits what was typed, which is what
  leaving the field already did. It cannot reach a different conversation than the one
  it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
  only case that changes is a name being generated, where the heading is empty and the
  row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
  shape or a schema.

Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.

## Related Issues

N/A
2026-09-10 09:46:25 +00:00
LivXue
13252ea0e2 fix(ui-web): three ways the title editors leave a conversation nameless
## Summary

Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.

**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.

**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.

**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.

**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.

The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.

Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Branch and base run in separate worktrees, both at the same base, same interpreter.

- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
  1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
  introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
  `unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
  need `--localstorage-file` for `localStorage` to exist on this box at all, and with
  it the store no longer refuses, so the refusal each asserts does not happen. Both
  reproduce on the base, and neither file imports anything this change touches. A
  second environment settles it: review ran the same head and reported 1,536 tests
  passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
  `check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
  full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
  `lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
  `renamed` call, a missing export, a missing harness verb, and the pre-edit title.
  The ordering one is driven through the real `rpc.onReconnect` rather than
  `openLiveSession`, because the ordering is between the two and a test that calls the
  inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
  forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
  on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
  editor gone, button back, zero title calls, no page error. Reconnect with the editor
  open, forced by closing the socket from the page: before, `Cannot read properties of
  null (reading 'textContent')` with the input stranded and no session reload; after,
  heading restored, editor gone, reload done, no page error. Reconnect with a name
  typed into an open editor: heading and rail row both settle on the committed name,
  no page error. That probe renamed a real conversation, so its title was put back and
  the stored metadata checked byte-identical afterwards.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible, all of it in the same direction: a title that used to vanish stays put.

- Ending an editor on a conversation switch commits what was typed, which is what
  leaving the field already did. It cannot reach a different conversation than the one
  it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
  only case that changes is a name being generated, where the heading is empty and the
  row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
  shape or a schema.

Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.

## Related Issues

N/A
2026-09-10 09:46:25 +00:00
0xKT
297f24d4e1 refactor(*): carve the four harness strategy roles out of the turn path
## Summary

The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.

This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.

Key decisions:

- Memory is more than an adapter over the context engine. Two decisions that
  sat in the shell move onto the role that owns them: which history slice is
  even a candidate (it turns on whether the engine archives for itself), and
  how much of the window a prompt may occupy (that window's own arithmetic).
  organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
  A live model switch rebuilds the provider and the window, and trajectory
  replay rebinds loop.tools after the constructor returns. The context engine
  is the exception and is bound directly: nothing rebinds it, and a
  generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
  contract tier: a replacement loop may name its own strategy points, so these
  four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
  list cannot move which message gets marked.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.

- Captured on this branch and twice on its parent commit. Raw diffs contain
  only wrap_untrusted fence nonces, which are random per invocation; capturing
  the parent twice shows those are the sole variance. After normalising them
  all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
  commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
  default set, the two decisions Memory took over, both Action paths, the
  callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
  the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.

The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 07:23:26 +00:00
ypflll
f5c7303c44 refactor(*): carve the four harness strategy roles out of the turn path
## Summary

The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.

This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.

Key decisions:

- Memory is more than an adapter over the context engine. Two decisions that
  sat in the shell move onto the role that owns them: which history slice is
  even a candidate (it turns on whether the engine archives for itself), and
  how much of the window a prompt may occupy (that window's own arithmetic).
  organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
  A live model switch rebuilds the provider and the window, and trajectory
  replay rebinds loop.tools after the constructor returns. The context engine
  is the exception and is bound directly: nothing rebinds it, and a
  generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
  contract tier: a replacement loop may name its own strategy points, so these
  four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
  list cannot move which message gets marked.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.

- Captured on this branch and twice on its parent commit. Raw diffs contain
  only wrap_untrusted fence nonces, which are random per invocation; capturing
  the parent twice shows those are the sole variance. After normalising them
  all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
  commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
  default set, the two decisions Memory took over, both Action paths, the
  callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
  the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.

The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 07:23:26 +00:00
0xKT
44309dde3a feat(cli): raven agents new scaffolds a complete agent end to end
## Summary

raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.

Key decisions:

- **Templates are real code, fire-tested before templating.** The eleven
  files under raven/templates/agents_scaffold/ pass ruff and py_compile
  like any source, ride the wheel, and their content was proven live
  before landing: discovery, handshake, and plugin tool/hook injection
  all green on a hand-assembled probe in a disposable home. A dedicated
  spike also proved the placement is invisible to the import-linter
  contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
  target is the raven home's agents/ tree, discovery's first root: a
  scaffolded folder is on the roster without any registration.
  --register mirrors the generated install.py through the same pinned
  write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
  manifest, re-parses the plugin manifest, compiles every generated
  file, and really scans discovery; smoke spawns the launcher for one
  initialize frame. Three smoke outcomes are told apart: GREEN, the
  launcher's loud no-key refusal (fail-closed design, passed through
  verbatim), and FAILED with the scene preserved. Display names are
  fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
  renders schemas/subagent.schema.json (a discriminated union on kind)
  and schemas/raven-plugin.schema.json from the pydantic models; a
  contract family holds the on-disk files byte-equal to a fresh render
  and validates every real manifest on the tree against them. Editors
  get instant validation with two settings lines, documented in the
  guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
  the from-zero developer guide (gold standard: a developer who never
  read the source reaches a green handshake in ten minutes); CONTEXT.md
  renames the category entry to Discovered agent -- agent the thing,
  harness the mechanism, subagent the protocol seat -- with product
  absorbed into Avoid; the charter gains the scaffold entry and the
  engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
  project in the working directory (pip install -e territory); --here
  lands it on the plugins-dist shelf. The launcher adopts the official
  ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
  is missing; the doctor reports that row as disabled by design with
  the install cure printed. No plugins/ directory ships beside an
  engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
  hostile lenses (filesystem edges of a command that writes into real
  raven homes; template quality as the file set every future agent
  copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
  pin an enabled row that cannot start, the name fence ignored the
  discovered tree, one installed engine wheel rode the host's and every
  sibling's turns through a fixed tool name, and crash residue was
  discovered as a hidden live agent. All fourteen close in a
  dedicated hardening commit, each with a regression test built from the review's own
  reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
  Nothing under raven/contracts/ or the agent loop changed. The branch
  carries exactly two narrow runtime fixes exposed by the review:
  discovery now skips dot-directories (crash residue is never an
  agent), and the config schema gains an engine round-trip field
  (declared as a field-level neutral seam; merge and readiness
  semantics untouched).

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Every commit landed through a full-suite rehearsal on a clean bench
  before touching the branch; tails over the original base's 19953
  passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
  smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
  expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
  every step a pure addition, +65 tests net. The branch diff is
  fingerprint-stable across the rebase (git patch-id --stable verified
  pairwise across two clean rebases); the branch closes at 20094 passed
  / 137 skipped / exit 0 on the current main base, +80 tests net over
  whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
  end: one command scaffolds into ~/.raven/agents, the four-segment
  card runs all green, and a genuine LLM turn has the agent's own model
  call its own scaffolded hello tool through the permission gate and
  relay the exact output; the probe was then removed without touching
  the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
  four doctor lines, readiness ready, and a live ACP initialize
  handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
  passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
  tampered file each turn the family red); all six subagent manifests
  and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
  make check-large-files, make check-source-language: green at every
  step; wheel build carries all seventeen template files and none of
  schemas/.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.

## Related Issues

N/A
2026-09-10 07:07:15 +00:00
0xKT
a577cae8f4 feat(cli): raven agents new scaffolds a complete agent end to end
## Summary

raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.

Key decisions:

- **Templates are real code, fire-tested before templating.** The eleven
  files under raven/templates/agents_scaffold/ pass ruff and py_compile
  like any source, ride the wheel, and their content was proven live
  before landing: discovery, handshake, and plugin tool/hook injection
  all green on a hand-assembled probe in a disposable home. A dedicated
  spike also proved the placement is invisible to the import-linter
  contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
  target is the raven home's agents/ tree, discovery's first root: a
  scaffolded folder is on the roster without any registration.
  --register mirrors the generated install.py through the same pinned
  write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
  manifest, re-parses the plugin manifest, compiles every generated
  file, and really scans discovery; smoke spawns the launcher for one
  initialize frame. Three smoke outcomes are told apart: GREEN, the
  launcher's loud no-key refusal (fail-closed design, passed through
  verbatim), and FAILED with the scene preserved. Display names are
  fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
  renders schemas/subagent.schema.json (a discriminated union on kind)
  and schemas/raven-plugin.schema.json from the pydantic models; a
  contract family holds the on-disk files byte-equal to a fresh render
  and validates every real manifest on the tree against them. Editors
  get instant validation with two settings lines, documented in the
  guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
  the from-zero developer guide (gold standard: a developer who never
  read the source reaches a green handshake in ten minutes); CONTEXT.md
  renames the category entry to Discovered agent -- agent the thing,
  harness the mechanism, subagent the protocol seat -- with product
  absorbed into Avoid; the charter gains the scaffold entry and the
  engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
  project in the working directory (pip install -e territory); --here
  lands it on the plugins-dist shelf. The launcher adopts the official
  ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
  is missing; the doctor reports that row as disabled by design with
  the install cure printed. No plugins/ directory ships beside an
  engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
  hostile lenses (filesystem edges of a command that writes into real
  raven homes; template quality as the file set every future agent
  copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
  pin an enabled row that cannot start, the name fence ignored the
  discovered tree, one installed engine wheel rode the host's and every
  sibling's turns through a fixed tool name, and crash residue was
  discovered as a hidden live agent. All fourteen close in a
  dedicated hardening commit, each with a regression test built from the review's own
  reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
  Nothing under raven/contracts/ or the agent loop changed. The branch
  carries exactly two narrow runtime fixes exposed by the review:
  discovery now skips dot-directories (crash residue is never an
  agent), and the config schema gains an engine round-trip field
  (declared as a field-level neutral seam; merge and readiness
  semantics untouched).

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Every commit landed through a full-suite rehearsal on a clean bench
  before touching the branch; tails over the original base's 19953
  passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
  smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
  expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
  every step a pure addition, +65 tests net. The branch diff is
  fingerprint-stable across the rebase (git patch-id --stable verified
  pairwise across two clean rebases); the branch closes at 20094 passed
  / 137 skipped / exit 0 on the current main base, +80 tests net over
  whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
  end: one command scaffolds into ~/.raven/agents, the four-segment
  card runs all green, and a genuine LLM turn has the agent's own model
  call its own scaffolded hello tool through the permission gate and
  relay the exact output; the probe was then removed without touching
  the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
  four doctor lines, readiness ready, and a live ACP initialize
  handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
  passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
  tampered file each turn the family red); all six subagent manifests
  and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
  make check-large-files, make check-source-language: green at every
  step; wheel build carries all seventeen template files and none of
  schemas/.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.

## Related Issues

N/A
2026-09-10 07:07:15 +00:00
KevinHuSh
140a2cdeed feat(provider): tag models with capabilities and rebuild the provider model manager
## Change description

> ## Summary
>
> Expand provider and model metadata across the backend, RPC contract, TUI, and web UI. Providers now expose curated catalogs, homepages, native endpoints, and capability metadata. The web settings flow supports catalog browsing and manual model management, provider branding, homepage links, and green-only connected status indicators. MiniMax CN and NVIDIA onboarding remain available through their built-in provider flows.
>
> ![image.png](/uploads/5245ee6e91f17dfabdda152adac16257/image.png){width="478" height="324"}
>
> ![image.png](/uploads/fd2d7e372895b1adbad4154cdbeeecef/image.png){width="501" height="338"}
>
> ## Type
>
> - [ ] Fix
> - [x] Feature
> - [ ] Docs
> - [ ] CI / tooling
> - [ ] Refactor
> - [ ] Other
>
> ## Verification
>
> - [x] Relevant tests pass locally
> - [ ] Relevant lint / type checks pass locally
> - [ ] User-facing docs or screenshots are updated when needed
>
> Exact commands and results:
>
> - `uv run pytest tests/test_provider_catalog.py tests/test_provider_registry_data.py tests/test_rpc_model.py tests/test_providers_factory.py -x` - 234 passed, 4 skipped
> - `npm test -- --run src/shell/provider-mark.test.tsx src/features/model/ModelPicker.test.tsx src/features/onboard/OnboardPage.test.tsx src/features/settings/SettingsPage.test.tsx` - 133 passed
> - `git diff --check` - passed
>
> The full web type-check was not marked as passing because the current test tree contains unrelated existing TypeScript errors in `SettingsPage.test.tsx`.
>
> ## Risk
>
> Provider registry data and model-selection behavior change across backend and frontend surfaces. Existing provider IDs and stored configuration remain supported. The change can be rolled back by reverting this merge request.
>
> - [ ] Security impact considered
> - [x] Backward compatibility considered
> - [x] Rollback path is clear for risky changes
>
> ## Related Issues
>
> N/A

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [ ] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
2026-09-10 07:06:54 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## Summary

Reported as "deliver_files is broken". It is not: **the tool never ran.**

Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:

```
Error: Invalid parameters for tool 'deliver_files': files should be array
```

What the model sent was the array, spelled as a string:

```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```

`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.

## Type

- [x] Fix
- [ ] Feature

## The edge of the forgiving is the design

When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.

**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.

**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.

## Not just deliver_files

Six built-in tools declare an array or object parameter and were all exposed:

| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |

The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.

## Verification

```
make lint-python    ruff check + ruff format --check, 1850 files
make lint-imports   9 contracts kept, 0 broken
pytest tests/       19,699 passed, 7 failed (all pre-existing, see below)
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string

**End to end, through the real tool**, with the exact payload that failed five times in production:

```
files sent as:            str -> [{"path": ".../poster.png", "title": "..."}]
returned:                 Delivered 1 file(s): poster.png (72 B).
still "should be array":  False
registered in the store:  True
```

Twelve cases, five mutations, each killing at least one:

| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |

The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.

**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.

## Risk

- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert

## Related Issues

N/A

## Swept

`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.

- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.

Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).

## Deliberately not fixed

The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.

## Moved from !594

Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.

Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
2026-09-09 15:42:36 +00:00
forrestjgq
f01231fef6 fix(cli): overhaul trajectory browser interaction ux (#379)
## Summary

Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:

- Navigation: every screen opens with a help area under its title (page
  purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
  sentinel can never reach a conversion or the data layer; a cancelled
  report keeps its pre-confirm bundle-and-pin side effects (the existing
  declined-report contract). Back/Exit menu entries are gone; answered
  prompts erase themselves and navigation is echoed as breadcrumb lines
  with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
  attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
  budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
  drops as a whole column when it no longer fits, and below the dynamic
  minimum width the tightest layout is kept while the renderer clips
  overlong lines at the terminal edge. Every dynamic cell passes a
  single-line sanitization gate before width math (verdict sidecars only
  guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
  fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
  table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
  passes the terminal's CPR reply through to the renderer instead of
  treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
  (advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
  and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
  laggy Esc feel.

The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- The interactive browser's look and key protocol change wholesale (that
is
  the point of this PR): Esc no longer quits from the top level (Ctrl+C
  does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
  interaction wholesale, no data migration involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-05 23:58:20 +08:00
0xKT
28299e5f0e fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
userName20260323
50ad9377bd fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
daoxize1
5ee8a14f43 feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Related issues (if there is)

N/A

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
daoxize1
135312987b feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Related issues (if there is)

N/A

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
0xKT
231b270dd7 refactor(*): the vendored subagents tree retires and agents/ is the one home
## Summary

Retires the vendored fork tree (`subagents/`, ~7,500 files) and makes `agents/` the one home for the five agent products. The products were already thin launchers that render a config and exec the installed raven's own `raven acp`; this PR removes the frozen fork checkouts they replaced, migrates every consumer, and keeps the A/B verification power as byte snapshots.

Key decisions:

- **A side becomes a record.** The fork trees are deleted; the files the parity guards compare against live on as byte snapshots under `tests/fixtures/vendored_fork/` (added to ruff's exclude so a record can never be reformatted). The research flow's oracle is the fork's frozen measurement (`research_parity_probe.json`), a constant by construction.
- **Config floors v6 and v7.** Stored roster rows that pointed into the retired tree are migrated in place (floor six): rows whose folder maps to a shipped product are re-aimed at `agents/`, fork-era rows that cannot be re-aimed are left untouched and reported, unparseable rows get a fix-by-hand notice. Verdict-driven, path-root anchored, with a stamped sidecar so each pass runs once.
- **The research product reclaims its name (floor seven).** The `-NG` suffix existed only to coexist with the fork's own row, so it retires with the fork: registered `Raven-Research-NG` rows rename to `Raven-Research` on load; if a fork-era row still holds the name, the advisory repeats and the stamp holds at floor six, so the rename completes on a later load once the name frees (never two rows under one name). Display name only -- the machine id `raven-research-ng` (state root, ACP home, everos identity, the `RESEARCH_NG_*` variables) is a stable key and stays. The v6 name gate maps the research folder to None (never re-aim): the fork's research rows were cli-kind on a different flow, and after the rename a name match would select exactly the rows the gate exists to refuse.
- **Guards retire with their subject.** The vendored-invariant and vendored-subagents guard suites, their Makefile/pre-commit/CI hooks, and the fork-era install stage in `install.sh` are removed. The external-consumer tripwire now derives the promised surface from the five product installers and the charter's uninstall recipe (`add_third_party_subagent` and `remove_third_party_subagent` today) instead of restating a list that goes stale; the fork-era pin count (eight names) retired with its consumers, and `get_third_party_subagents` stays only as a courtesy to fork-era installer copies already carried into raven homes.
- **Wheel and sdist slim down.** The wheel force-includes `agents/` file-by-file from the git index (filled-in `.env` files are refused). The sdist shrinks 93.2 MB -> 2.76 MB (-97%).
- **Docs speak one era.** AGENTS.md, CONTEXT.md, README, CHANGELOG, the demo READMEs, and the RPC field descriptions (models.py -> openrpc.json -> both generated clients) describe the product tree in the present and the fork in the past.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

- Controlled A/B on a clean bench, same machine and env fingerprint, at the current pair: base 19,938 passed / 137 skipped / 0 failed vs branch 19,796 / 137 / 0, skip roster identical line by line. The -142 delta equals the collection delta and reconciles file by file: -159 across the twelve retired or trimmed test files, +9 floor-six migration tests, +8 floor-seven tests. The branch diff is fingerprint-stable across rebases (`git patch-id --stable` verified pairwise), so the reconciliation transfers to later bases. A second fingerprint (dev worktree env) shows 19,555 / 148 / 2 at the final tip; the 2 are `test_design_engine_rendering_outcome` renders hitting a local playwright-home quirk -- on the clean bench both sides skip them identically ("no system chromium"), and the branch does not touch that file.
- `uv run pytest tests/integration/test_research_subagent_smoke.py -m integration`: 2 passed (the smoke now drives the migrated product launcher end to end).
- `make lint-python` (ruff check + format), `make lint-imports` (tail line: `Contracts: 9 kept, 0 broken.` -- the ninth contract landed on main mid-branch), `make check-large-files`: all green.
- `npm run lint:rpc --prefix ui-tui` and `npm run gen:check --prefix ui-web`: generated clients in sync with `rpc-schema/openrpc.json`.
- `bash -n install.sh`: clean.
- Wheel built from the branch, installed into a clean venv: onboarding discovers the five products, and a filled-in `.env` placed in the tree fails the build (secrets refusal probed).
- Real-config upgrade rehearsal on a genuine floor-5 home config (owner present): the migration stamped the sidecar to 6, rewrote nothing (the five product rows were already registered against `agents/`; the one fork-era orphan row got its advisory notice and was left untouched), a second load was silent, and the upgraded config served a live probe plus one full one-shot agent turn. The floor-seven rehearsal on the same config renamed its one transition row (a one-line diff against the byte backup), stamped seven, was silent on the second load, and left the machine ids and the row's command untouched.

- [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: on first load of a pre-v6 config, roster rows pointing into the retired tree are re-aimed at the product tree, with a one-line `Migrated` notice per changed row and a cleanup hint for the stale on-disk copy. Rows the migration cannot decide are reported, never rewritten. The floor-seven rename tells once per changed row too; only a blocked rename repeats its advisory, deliberately, until the blocking row is gone. While the block holds, the roster shows the discovered `Raven-Research` row beside the stored `Raven-Research-NG` row -- same launcher, same state root, no state split -- and converges to one row once the name frees.
- Rollback: revert the squash commit. The fork trees return from git history, and a config the migration already re-aimed keeps working on both sides of the revert: the wheel carries `agents/` before and after (that packaging landed separately), so no config rollback is needed. Rows the migration could not decide were never rewritten, and the version sidecar is additive.
- Packaging: a wheel built from an sdist (what a combined `uv build` does) carries no agent products by design -- the sdist has no `.git` for the hook's tracked-files read; the hook warns loudly, and release.yml builds the wheel directly from the checkout and asserts the products are present. Release artifacts are unaffected; do not publish a combined-build wheel.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

BREAKING CHANGE: the `subagents/` source tree is gone. Installs never consumed it directly (the wheel carries `raven/agents`), but any local tooling that read `subagents/` paths must move to `agents/` or the snapshots under `tests/fixtures/vendored_fork/`.
2026-09-09 03:59:19 +00:00
KevinHuSh
cee84a6f60 feat(provider): expand provider catalog and settings experience
## Summary

- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.

![image.png](/uploads/73442917d65ca16c07026e9017153777/image.png){width=876 height=600}

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- [ ] `uv run pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
  * `npm test` from `ui-web/` - 1,378 passed.
  * `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
  * `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
  * `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
  * `make check-source-language check-large-files` - passed.
  * `git diff --check origin/main...HEAD` - passed.
  * Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.

## Related Issues

N/A
2026-09-08 06:05:27 +00:00
LivXue
24b9b483e0 fix(agent): a dag notices a stalled node and answers an invented field with the closed set
## Summary

Three DAG-side behaviours from the autoresearch runs, none of which adds a node field.

- A running node that shows no sign of life for ten minutes is announced to the main agent through the existing exception channel, once per silent stretch. A notice, not a timeout: nothing is cancelled, and the message says waiting is fine when the rest of the run is moving. `RunActivity.last_event_ms` is stamped by every activity report, transcript republishes included, so the acp and openai_api lanes (whose only in-flight report is a transcript) are seen as alive; the review reproduction of the false positive is kept as the regression. The announcer's required keyword is passed (a TypeError used to be swallowed).
- An invented node field (`mode`, three runs in a row) is answered with the closed field set in one message instead of pydantic's field-only rendering.
- An oversized graph call is told about the ref escape hatch rather than only that it is too big.
- `resolve_dag_node` accepts `action` as an alias for `decision` (the name the model reaches for; three calls lost to "missing required decision"); the schema keeps `decision`.

## Type
- [x] Fix

## Verification
```
uv run ruff check raven tests && uv run ruff format --check raven tests   # clean
uv run pytest tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py tests/test_subagent_dag_control_tools.py tests/test_subagent_acp.py tests/test_rpc_dag.py -q   # 606 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No schema change: the node field set is what main has. The stall notice is informational and reaches the main agent through the channel node exceptions already use. Rollback is a revert of the squash commit.

## Related Issues
Split from !475 (closed), retargeted at main; the stall-watcher blind spot found in that review (note 3786214590) is fixed here.
2026-09-07 14:43:43 +00:00
silverLXT
18a05f51c1 fix(agent): a dag notices a stalled node and answers an invented field with the closed set
## Summary

Three DAG-side behaviours from the autoresearch runs, none of which adds a node field.

- A running node that shows no sign of life for ten minutes is announced to the main agent through the existing exception channel, once per silent stretch. A notice, not a timeout: nothing is cancelled, and the message says waiting is fine when the rest of the run is moving. `RunActivity.last_event_ms` is stamped by every activity report, transcript republishes included, so the acp and openai_api lanes (whose only in-flight report is a transcript) are seen as alive; the review reproduction of the false positive is kept as the regression. The announcer's required keyword is passed (a TypeError used to be swallowed).
- An invented node field (`mode`, three runs in a row) is answered with the closed field set in one message instead of pydantic's field-only rendering.
- An oversized graph call is told about the ref escape hatch rather than only that it is too big.
- `resolve_dag_node` accepts `action` as an alias for `decision` (the name the model reaches for; three calls lost to "missing required decision"); the schema keeps `decision`.

## Type
- [x] Fix

## Verification
```
uv run ruff check raven tests && uv run ruff format --check raven tests   # clean
uv run pytest tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py tests/test_subagent_dag_control_tools.py tests/test_subagent_acp.py tests/test_rpc_dag.py -q   # 606 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No schema change: the node field set is what main has. The stall notice is informational and reaches the main agent through the channel node exceptions already use. Rollback is a revert of the squash commit.

## Related Issues
Split from !475 (closed), retargeted at main; the stall-watcher blind spot found in that review (note 3786214590) is fixed here.
2026-09-07 14:43:43 +00:00
0xKT
326853dea5 fix(agents): the on-call submit reserves the machine as one step and the launcher writes every result
## Summary

On-call plugin (`agents/raven-oncall/plugins/oncall-flow`) fixes from the autoresearch runs 10 and 11 on a shared 2xA800 machine. Nothing outside the plugin and its tests.

- `ops_submit` reads machine occupancy across every sibling campaign before buying a round: two campaigns each pinned device 0 within two minutes and the second died of CUDA OOM.
- Check and reservation are one step under an advisory lock at the ops home (the host's portable file lock, so a Windows-hosted agent can submit); a fresh handle-less record counts as the machine's reservation for ten minutes, then it is the crash orphan it always was. The in-flight window is reproduced in a test and refuses.
- A trial whose idem_key is already a live sibling campaign's job is refused: the same measurement was bought twice under two names.
- The launcher writes the missing `result.json` when a job writes none, and a piped job reports the failing stage rather than the tee.
- A local exec cap kill routes over-cap work to `ops_submit` instead of leaving the model to retry by hand.

Review round 2 (2026-09-07): the launcher could publish success while a self-detached child was still running (a command ending in `nohup ... &` returned as soon as the shell did). The fix was sitting in a downstream MR; it is folded in here so this MR is whole:

Jobs stay in launcher custody and are admitted by declared resources. Design: `docs/specs/2026-09-03-resource-admission-design.md`; the launcher plan: `docs/plans/2026-09-03-launcher-custody-and-detached-jobs.md`.

- The launcher runs the child in its own process group; a command that detaches itself (nohup/setsid/&) is refused with the reason written to `result.json`; kills reach the whole tree; `ops_kill` says when it killed a live process. Measured 2026-09-03: three jobs escaped custody and were recorded as finished in ten seconds.
- Admission is by declared resources against the machine's capacity: `ops_declare` takes `gpus_per_job` on a GPU row (`cores_per_job`, optional memory, on a CPU row), refuses a declaration over capacity or a template that pins its own `CUDA_VISIBLE_DEVICES`; the system assigns device ids, exports `CUDA_VISIBLE_DEVICES`, records them in the ledger and shows them in `ops_tune_status`; spend is width x duration. Rows without capacity information keep the job-count gate; campaigns declared before this count as one unit.
- The host registry reader gains `capacity()` and the doctor lines beside it (a GPU row that cannot be counted is told; `concurrency` beside a capacity is reported as not read); the plugin carries its parity copy.

## Type
- [x] Fix

## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents   # clean
uv run pytest tests/test_agents_oncall_flow_*.py tests/test_agents_oncall_launcher.py tests/test_shell_*.py tests/test_cli_ops_connection_commands.py tests/test_ops_connections.py -q   # 1070 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Ledger records gain `reserved_at` and `resources_held`; records without them read as before. `ops_declare` on a GPU row now requires `gpus_per_job`; a registry row for a GPU machine should carry `gpus: N` (inferred from `device: "N x ..."` otherwise). Rollback is a revert of the squash commit.

## Related Issues
Split from !475 (closed), retargeted at main. `feat/exec-machine-and-background-lanes` (!521) builds on this branch and should merge after it. !523 was folded into this MR and closed.
2026-09-07 12:58:07 +00:00
silverLXT
e7282e7667 fix(agents): the on-call submit reserves the machine as one step and the launcher writes every result
## Summary

On-call plugin (`agents/raven-oncall/plugins/oncall-flow`) fixes from the autoresearch runs 10 and 11 on a shared 2xA800 machine. Nothing outside the plugin and its tests.

- `ops_submit` reads machine occupancy across every sibling campaign before buying a round: two campaigns each pinned device 0 within two minutes and the second died of CUDA OOM.
- Check and reservation are one step under an advisory lock at the ops home (the host's portable file lock, so a Windows-hosted agent can submit); a fresh handle-less record counts as the machine's reservation for ten minutes, then it is the crash orphan it always was. The in-flight window is reproduced in a test and refuses.
- A trial whose idem_key is already a live sibling campaign's job is refused: the same measurement was bought twice under two names.
- The launcher writes the missing `result.json` when a job writes none, and a piped job reports the failing stage rather than the tee.
- A local exec cap kill routes over-cap work to `ops_submit` instead of leaving the model to retry by hand.

Review round 2 (2026-09-07): the launcher could publish success while a self-detached child was still running (a command ending in `nohup ... &` returned as soon as the shell did). The fix was sitting in a downstream MR; it is folded in here so this MR is whole:

Jobs stay in launcher custody and are admitted by declared resources. Design: `docs/specs/2026-09-03-resource-admission-design.md`; the launcher plan: `docs/plans/2026-09-03-launcher-custody-and-detached-jobs.md`.

- The launcher runs the child in its own process group; a command that detaches itself (nohup/setsid/&) is refused with the reason written to `result.json`; kills reach the whole tree; `ops_kill` says when it killed a live process. Measured 2026-09-03: three jobs escaped custody and were recorded as finished in ten seconds.
- Admission is by declared resources against the machine's capacity: `ops_declare` takes `gpus_per_job` on a GPU row (`cores_per_job`, optional memory, on a CPU row), refuses a declaration over capacity or a template that pins its own `CUDA_VISIBLE_DEVICES`; the system assigns device ids, exports `CUDA_VISIBLE_DEVICES`, records them in the ledger and shows them in `ops_tune_status`; spend is width x duration. Rows without capacity information keep the job-count gate; campaigns declared before this count as one unit.
- The host registry reader gains `capacity()` and the doctor lines beside it (a GPU row that cannot be counted is told; `concurrency` beside a capacity is reported as not read); the plugin carries its parity copy.

## Type
- [x] Fix

## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents   # clean
uv run pytest tests/test_agents_oncall_flow_*.py tests/test_agents_oncall_launcher.py tests/test_shell_*.py tests/test_cli_ops_connection_commands.py tests/test_ops_connections.py -q   # 1070 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Ledger records gain `reserved_at` and `resources_held`; records without them read as before. `ops_declare` on a GPU row now requires `gpus_per_job`; a registry row for a GPU machine should carry `gpus: N` (inferred from `device: "N x ..."` otherwise). Rollback is a revert of the squash commit.

## Related Issues
Split from !475 (closed), retargeted at main. `feat/exec-machine-and-background-lanes` (!521) builds on this branch and should merge after it. !523 was folded into this MR and closed.
2026-09-07 12:58:06 +00:00
0xKT
de155f80a4 feat(agents): the on-call agent gains Medium/High/Max modes, and a mode reaches the model call
## Summary

The on-call agent advertises Medium/High/Max session modes over ACP.

- `agents/raven-oncall/modes/{medium,max}.json` are overlays over the shipped config (reasoning effort off / max); `config.json` itself is the High baseline. Rendered through the same `render.mode_catalogue` the research agent uses. The rung ids are the ones the host's session tier is spelled in (`TIER_LADDER`), so the tier maps onto them directly.
- How the effort reaches the model call is the trunk's own mechanism, not this branch's: `AcpModeConfig.reasoningEffort` (landed on main in c25036dc) is dispensed to `SessionPolicy.reasoning_effort` and applied to every call a session in that mode makes. The product renderer lifts an overlay's `agents.defaults.reasoningEffort` onto the mode entry as that knob, so a product declares the effort where it declares its other defaults and the loop never reads the hook overlay for it. The generation-slice machinery earlier revisions of this MR carried is gone.
- Two documentation lines corrected: `agents/README.md` modes inventory; `_llm_call_stream`'s contract.

No DAG node field and no spawn parameter.

## Type
- [x] Feature

## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents   # clean
uv run pytest tests/test_config_product_render.py tests/test_agents_oncall_launcher.py tests/test_acp_modes.py tests/test_agents_research_launcher.py tests/test_acp_methods.py -q   # 228 passed
uv run lint-imports   # 8 contracts kept
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
Field check: a real ACP handshake with the on-call process on 2026-09-04 returned `currentModeId: high` and the three-rung menu; `set_mode medium` accepted, `set_mode ultra` refused as unknown.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
A product that declares no effort in its overlays renders the same entry as before. Rollback is a revert of the squash commit.

## Related Issues
Replaces !522 (closed): same feature, branch renamed to the snake_case form AGENTS.md 2.1 requires.
2026-09-07 12:51:20 +00:00
silverLXT
f89738b2d5 feat(agents): the on-call agent gains Medium/High/Max modes, and a mode reaches the model call
## Summary

The on-call agent advertises Medium/High/Max session modes over ACP.

- `agents/raven-oncall/modes/{medium,max}.json` are overlays over the shipped config (reasoning effort off / max); `config.json` itself is the High baseline. Rendered through the same `render.mode_catalogue` the research agent uses. The rung ids are the ones the host's session tier is spelled in (`TIER_LADDER`), so the tier maps onto them directly.
- How the effort reaches the model call is the trunk's own mechanism, not this branch's: `AcpModeConfig.reasoningEffort` (landed on main in c25036dc) is dispensed to `SessionPolicy.reasoning_effort` and applied to every call a session in that mode makes. The product renderer lifts an overlay's `agents.defaults.reasoningEffort` onto the mode entry as that knob, so a product declares the effort where it declares its other defaults and the loop never reads the hook overlay for it. The generation-slice machinery earlier revisions of this MR carried is gone.
- Two documentation lines corrected: `agents/README.md` modes inventory; `_llm_call_stream`'s contract.

No DAG node field and no spawn parameter.

## Type
- [x] Feature

## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents   # clean
uv run pytest tests/test_config_product_render.py tests/test_agents_oncall_launcher.py tests/test_acp_modes.py tests/test_agents_research_launcher.py tests/test_acp_methods.py -q   # 228 passed
uv run lint-imports   # 8 contracts kept
uv run python scripts/check_commit_messages.py origin/main..HEAD   # clean
```
Field check: a real ACP handshake with the on-call process on 2026-09-04 returned `currentModeId: high` and the three-rung menu; `set_mode medium` accepted, `set_mode ultra` refused as unknown.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
A product that declares no effort in its overlays renders the same entry as before. Rollback is a revert of the squash commit.

## Related Issues
Replaces !522 (closed): same feature, branch renamed to the snake_case form AGENTS.md 2.1 requires.
2026-09-07 12:51:20 +00:00
0xKT
6b688e2313 fix(rpc): a refused instance create says why instead of internal_error
## Summary

`SubagentManager._require_addressable` has two refusals, and both are written for the person who pressed the button:

```
'X' is disabled or no longer configured, so it cannot be addressed.
    Any records it already has remain on disk.
'X' is stateless, so each turn would start a fresh conversation with no memory
    of this one. Spawn it with a task instead.
```

Both were raised as bare `RuntimeError`, and the dispatcher renders anything but an `RpcError` as `internal_error` with the text buried in `data.traceback_tail`. The panel draws `s.startFail.why`, which was `e.message` -- so it drew the string `internal_error`, and the one failure on this path a caller could act on was the one nobody could read.

Measured on the running page, before and after, against a stateless agent:

```
before   message internal_error           code -32603   detail null
after    message config_validation_error  code -32011   detail "Cannot create a new
         instance: 'Raven-Research-NG' is stateless, so each turn would start a fresh
         conversation with no memory of this one. Spawn it with a task instead."
```

Three parts, because the layers are three:

- **`NotAddressableError`**, new, in `direct_chat.py`. A type rather than a message match, because the surface has to tell a refusal from a fault and `raven.agent` cannot import `raven.rpc` to do it there -- the "inner layers know no surface" contract. It subclasses `RuntimeError`, so this narrows what a raise MEANS without narrowing what it is.
- **`instances_create`** translates it to `ConfigValidationError`, the class the two refusals below it in the same file already use, for the same reason: the request was refused, nothing broke.
- **The web store** reads `data.detail` before `message`, because `message` is the wire CODE. Without this half the card would have moved from `internal_error` to `config_validation_error` and been no better.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## How narrow this is, stated plainly

The panel already hides the `+` for exactly these two cases -- `addressable()` is `enabled && stateful` -- so an ordinary click cannot reach the refusal. What reaches it is:

- a roster gone stale under an open page: an agent disabled in config, or an auto-verify recording a snapshot and `refresh_agents()` flipping `stateful` while the browser still holds the old roster;
- the TUI's own `subagents.instance.create` call, which takes a typed agent name and consults no such guard.

I first "reproduced" this by calling the DataSource method directly from the console, which bypassed a button that would not have been there. That made the defect look like an everyday one, and it is not. The value here is that when it does happen the reader gets the way out instead of a code.

## A contract change, with one caller

The exception type at this boundary went from `RuntimeError` to an `RpcError`. `instances_create`'s only caller is the dispatcher, which handles `RpcError` first -- that is the point of the change. The existing roster-refusal test now pins the new contract instead of the old one, and a second test pins that the narrowing stays narrow: a manager raising anything else is still an internal error, because dressing a fault as a validation error would tell the reader to fix a request that was never wrong.

## Verification

```
make lint-python    All checks passed
make lint-imports   8 contracts kept, 0 broken
make lint-ui        gen:check 162 methods, type-check
make lint-tui       lint, lint:rpc, lint:i18n, type-check
make test-ui        1349 tests passed
make test-python    19278 passed, 5 failed
```

The five python failures are pre-existing on `origin/main` and unrelated -- four NAT64 cases in `tests/test_security_network.py` that depend on how this host resolves that prefix, and `test_doctor_answers_where_the_memories_are`. I ran the full suite on the base tree to get that number rather than assuming it.

One run of mine also failed `test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`. It did not reproduce on a second full run of the same tree, and it passes alone and with its own file, so it is a flake sensitive to xdist distribution -- named here rather than quietly dropped, since my change adds four tests and therefore changes how work is distributed.

Mutation-checked four ways: the store back to reading `message`, the store without its fallback, the rpc layer not translating, and the manager back to `RuntimeError`. Each reds a different case. Worth recording that my first harness evaluated the test command in the argument list, so it ran *before* each patch was applied and reported four clean passes -- the giveaway was that every mutation "passed", which is the same shape of mistake as a probe whose control never fires.

## Out of scope, and worth its own change

**The TUI shows the code too.** `ui-tui/src/rpc/errors.ts` builds its message as `` `[rpc ${code}] ${message}` `` and never reads the detail, so the TUI moves from `[rpc -32603] internal_error` to `[rpc -32011] config_validation_error` and is no better off. Fixing it is one line and would change the text of every RPC error in that surface, which is not this MR's blast radius to take.

**The bigger one, which this is not.** A capability probe that fails records nothing: `probe.py`'s auto-verify calls `store.record(result)` only when `status == "ready"`, so an agent whose launch failed keeps `probe_status: "unknown"` and an empty `probe_detail` -- while the reason it measured goes to the log alone. The external-agents surface already has the slot and already renders it well for other failure classes: on this machine `Raven-Design` and `Raven-PPT` read `attention` with "the design-engine engine wheel is not installed in this raven's environment -- install it where raven is installed, then ...", whereas `Raven-Research-NG`, which exits 1 at launch for want of a search key, reads `unknown` with nothing. That is a real defect with a built surface waiting for it, and it is a separate change.

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** -- nothing moved; two raises changed type and one call site gained a translation.
- **2 (a value with several entry points)** -- `_require_addressable` has two callers, `create_instance` and `chat`. Only the create path is translated here: `chat` is reached through `turn.send` and its refusal surfaces as a turn error in the transcript, a different surface with its own rendering. Named rather than half-done.
- **3d (several lanes through one sink)** -- the client's `startFail` has one writer; the detail-before-message order is pinned by two cases, one per branch.
- **4** -- failing test IDs diffed against the base by running the full suite on both trees, not counts. 0 introduced; the flake above is named.
- **9 (error handling)** -- the whole change is error handling. The fallback chain keeps a rejection with no detail readable, which the second client test pins.
- **11** -- `npm ci` in both `ui-web` and `ui-tui`; this worktree was fresh.

Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
2026-09-07 12:50:19 +00:00
Handsome-wzw
2ec1fd0b9f fix(rpc): a refused instance create says why instead of internal_error
## Summary

`SubagentManager._require_addressable` has two refusals, and both are written for the person who pressed the button:

```
'X' is disabled or no longer configured, so it cannot be addressed.
    Any records it already has remain on disk.
'X' is stateless, so each turn would start a fresh conversation with no memory
    of this one. Spawn it with a task instead.
```

Both were raised as bare `RuntimeError`, and the dispatcher renders anything but an `RpcError` as `internal_error` with the text buried in `data.traceback_tail`. The panel draws `s.startFail.why`, which was `e.message` -- so it drew the string `internal_error`, and the one failure on this path a caller could act on was the one nobody could read.

Measured on the running page, before and after, against a stateless agent:

```
before   message internal_error           code -32603   detail null
after    message config_validation_error  code -32011   detail "Cannot create a new
         instance: 'Raven-Research-NG' is stateless, so each turn would start a fresh
         conversation with no memory of this one. Spawn it with a task instead."
```

Three parts, because the layers are three:

- **`NotAddressableError`**, new, in `direct_chat.py`. A type rather than a message match, because the surface has to tell a refusal from a fault and `raven.agent` cannot import `raven.rpc` to do it there -- the "inner layers know no surface" contract. It subclasses `RuntimeError`, so this narrows what a raise MEANS without narrowing what it is.
- **`instances_create`** translates it to `ConfigValidationError`, the class the two refusals below it in the same file already use, for the same reason: the request was refused, nothing broke.
- **The web store** reads `data.detail` before `message`, because `message` is the wire CODE. Without this half the card would have moved from `internal_error` to `config_validation_error` and been no better.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## How narrow this is, stated plainly

The panel already hides the `+` for exactly these two cases -- `addressable()` is `enabled && stateful` -- so an ordinary click cannot reach the refusal. What reaches it is:

- a roster gone stale under an open page: an agent disabled in config, or an auto-verify recording a snapshot and `refresh_agents()` flipping `stateful` while the browser still holds the old roster;
- the TUI's own `subagents.instance.create` call, which takes a typed agent name and consults no such guard.

I first "reproduced" this by calling the DataSource method directly from the console, which bypassed a button that would not have been there. That made the defect look like an everyday one, and it is not. The value here is that when it does happen the reader gets the way out instead of a code.

## A contract change, with one caller

The exception type at this boundary went from `RuntimeError` to an `RpcError`. `instances_create`'s only caller is the dispatcher, which handles `RpcError` first -- that is the point of the change. The existing roster-refusal test now pins the new contract instead of the old one, and a second test pins that the narrowing stays narrow: a manager raising anything else is still an internal error, because dressing a fault as a validation error would tell the reader to fix a request that was never wrong.

## Verification

```
make lint-python    All checks passed
make lint-imports   8 contracts kept, 0 broken
make lint-ui        gen:check 162 methods, type-check
make lint-tui       lint, lint:rpc, lint:i18n, type-check
make test-ui        1349 tests passed
make test-python    19278 passed, 5 failed
```

The five python failures are pre-existing on `origin/main` and unrelated -- four NAT64 cases in `tests/test_security_network.py` that depend on how this host resolves that prefix, and `test_doctor_answers_where_the_memories_are`. I ran the full suite on the base tree to get that number rather than assuming it.

One run of mine also failed `test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`. It did not reproduce on a second full run of the same tree, and it passes alone and with its own file, so it is a flake sensitive to xdist distribution -- named here rather than quietly dropped, since my change adds four tests and therefore changes how work is distributed.

Mutation-checked four ways: the store back to reading `message`, the store without its fallback, the rpc layer not translating, and the manager back to `RuntimeError`. Each reds a different case. Worth recording that my first harness evaluated the test command in the argument list, so it ran *before* each patch was applied and reported four clean passes -- the giveaway was that every mutation "passed", which is the same shape of mistake as a probe whose control never fires.

## Out of scope, and worth its own change

**The TUI shows the code too.** `ui-tui/src/rpc/errors.ts` builds its message as `` `[rpc ${code}] ${message}` `` and never reads the detail, so the TUI moves from `[rpc -32603] internal_error` to `[rpc -32011] config_validation_error` and is no better off. Fixing it is one line and would change the text of every RPC error in that surface, which is not this MR's blast radius to take.

**The bigger one, which this is not.** A capability probe that fails records nothing: `probe.py`'s auto-verify calls `store.record(result)` only when `status == "ready"`, so an agent whose launch failed keeps `probe_status: "unknown"` and an empty `probe_detail` -- while the reason it measured goes to the log alone. The external-agents surface already has the slot and already renders it well for other failure classes: on this machine `Raven-Design` and `Raven-PPT` read `attention` with "the design-engine engine wheel is not installed in this raven's environment -- install it where raven is installed, then ...", whereas `Raven-Research-NG`, which exits 1 at launch for want of a search key, reads `unknown` with nothing. That is a real defect with a built surface waiting for it, and it is a separate change.

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** -- nothing moved; two raises changed type and one call site gained a translation.
- **2 (a value with several entry points)** -- `_require_addressable` has two callers, `create_instance` and `chat`. Only the create path is translated here: `chat` is reached through `turn.send` and its refusal surfaces as a turn error in the transcript, a different surface with its own rendering. Named rather than half-done.
- **3d (several lanes through one sink)** -- the client's `startFail` has one writer; the detail-before-message order is pinned by two cases, one per branch.
- **4** -- failing test IDs diffed against the base by running the full suite on both trees, not counts. 0 introduced; the flake above is named.
- **9 (error handling)** -- the whole change is error handling. The fallback chain keeps a rejection with no detail readable, which the second client test pins.
- **11** -- `npm ci` in both `ui-web` and `ui-tui`; this worktree was fresh.

Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
2026-09-07 12:50:18 +00:00
0xKT
0279241dfb fix(agent): a replan nobody waits for stops costing a dispatch
## Summary

A `replan` decision charged the session's hourly sub-agent dispatch quota even when it
dispatched nothing.

Every cost of a replan is paid inside `prepare_replan` -- the confirm question, the
dispatch quota, the minted instances -- and the hand-off that discovers whether anything
is still waiting on the node runs after it. Nothing is refunded when that hand-off finds
nobody there, so a replan aimed at a node that is not suspended spent a dispatch, ran no
sub-agent, and answered "the old run is still running as submitted".

That answer arrives for ordinary reasons, which the refusal itself names: a decision past
the adjudication deadline, a stopped run, a mistyped id. Each retry paid again. Measured
against the production charger with the hourly cap set to 5, four replans aimed at a
non-waiting node consumed the whole remaining budget, and the legitimate replan after them
was refused for a rate limit reading "the task may be looping" -- leaving the node
suspended and unreplannable for the rest of the rolling hour, with the refusal
misattributing the cause. `continue` and `abandon` reach the same hand-off and charge
nothing, which isolates this to the replan path's ordering rather than to the hand-off.

The fix asks first. `dag_live.awaiting_decision` reports whether one node of one run is
suspended, and the resolve call refuses on a definite no before the reconciled read and
before `prepare_replan`. Three design points a reviewer will want stated:

- **It refuses nothing the hand-off would have accepted.** The predicate is exactly the
  condition `resolve_node` fails on: both read the run's adjudication desk, and
  `AdjudicationDesk.resolve` refuses for the same reason `is_open` answers False.
- **It fans out over every graph tool, not over `owning_tool`.**
  `WiringMixin.resolve_dag_node` answers from whichever instance holds the run, and
  `owning_tool` falls back to the registered one when no instance claims it. A pre-check
  narrower than the hand-off it guards would refuse a replan of a run the playbook
  engine's private instance is running. This was caught by the pre-submit sweep, in the
  first version of this fix, before review.
- **It is three-valued.** `None` means no instance implements the question, which
  proceeds, so a host built before the predicate keeps replanning -- the same advisory
  contract every other helper in `dag_live` states. A raising instance answers `None` too,
  rather than being read as "not waiting".

The hand-off stays the authority for the node that stops waiting *during* the validation
this now skips ahead of, and that is the one case still charged. The two refusals are now
one string: the model cannot act differently on "refused before validation" than on
"refused after it".

No model-facing text changed. The `replan` design spec's ordered validation list and its
"nobody was waiting" enumeration were both incomplete after this and are updated; the
matching plan document is left alone, per the archive rule in `CONTEXT.md`.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Test-driven: the two behavioural tests were written first and observed failing (the cost
test reported `calls == ['prepare_replan', 'resolve_node']` where it asserts `[]`), then
made to pass.

Four mutants, each killed by the test written for it:

| Mutation | Result |
|---|---|
| remove the pre-check | 2 failed |
| narrow the fan-out to the registered tool | 1 failed |
| collapse `None` into `False` (fail-closed) | 2 failed |
| make the predicate ignore `node_id` | 1 failed |

Commands and results:

- `uv run pytest tests/test_subagent_dag_control_tools.py tests/test_subagent_dag_core.py
  tests/test_subagent_dag_adjudication.py tests/test_subagent_dag_runner.py
  tests/test_subagent_dag_verdict.py tests/test_living_docs.py -q -p no:randomly`
  -> 505 passed
- `uv run --frozen --all-extras pytest -q -p no:randomly` -> 19356 passed, 2 failed,
  138 skipped. Both failures are pre-existing and neither is in this change's blast
  radius; see below.
- `make lint-python` -> ruff check clean, 1823 files already formatted
- `uv run lint-imports` -> 8 contracts kept, 0 broken (this gate does not run in the
  GitLab pipeline)
- `make check-commits` -> pass; `scripts/check_source_language.py` -> pass;
  `make check-large-files` -> pass

Beyond the unit suites, the whole chain was driven end to end against the real store,
runner, adjudication desk and resolve tool, with real subprocess sub-agents registered as
a third-party CLI agent; only the verdict model call and the turn injection were doubled.
Eight scenarios, 173 assertions: the backgrounded and bound-foreground replans, the
wind-down status table, a chained second replan reading two earlier runs, the confirm /
quota / pause gates, the post-restart reads, and the four wire frames validated against
`raven/rpc/models.py`. All pass, including the quota control experiment above, which fails
without this change.

Attribution of the two full-suite failures:

- `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are` fails in a
  clean detached worktree at the target branch's tip, run in isolation under the same
  interpreter.
- `test_subagent_raven_launcher.py::test_the_folder_ships_exactly_one_roster_manifest`
  passes in that clean worktree and fails in this working checkout. Isolated by control:
  the test globs `subagent*.json`, which also matches five untracked
  `subagents-backup-*.json` files that local runs have left in the launcher's folder since
  mid-August. Copying those five files into the clean worktree reproduces the failure
  there; removing them again turns it green. Not introduced here, and the loose glob is
  noted rather than changed, being outside this change's scope.

0 introduced failures.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

Behaviour visible to the model: a `replan` naming a node that is not suspended is now
refused before the replacement graph is validated rather than after, so a graph error in
that same call is no longer reported. The refusal text is unchanged and already directs
the model to `dag_status`, which is where the node's real state is. Every other decision
path, and every replan that does have a suspended node, is unchanged.

The pre-check is advisory in both directions that could cost anything: it refuses only on
a definite no, and any host or instance that cannot answer proceeds exactly as before.

Rollback is the revert of this one commit; it restores the previous ordering and no state
or on-disk format changes with it.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

One coordination note: an open merge request against `main` also touches
`raven/agent/subagent/dag_control_tools.py`, `raven/agent/subagent/dag_tool.py` and both
test files this change edits. The hunks are disjoint -- it changes `execute`'s signature
and the guards at the top of it, while this changes the `replan` branch further down, and
its test edits append at the file tails -- and the two are semantically independent, since
it makes `decision` optional behind an alias that is normalised before the pre-check added
here reads it. Whichever lands second rebases; no symbol is extended by both.
2026-09-07 12:49:32 +00:00
LivXue
a4f6989dc4 fix(agent): a replan nobody waits for stops costing a dispatch
## Summary

A `replan` decision charged the session's hourly sub-agent dispatch quota even when it
dispatched nothing.

Every cost of a replan is paid inside `prepare_replan` -- the confirm question, the
dispatch quota, the minted instances -- and the hand-off that discovers whether anything
is still waiting on the node runs after it. Nothing is refunded when that hand-off finds
nobody there, so a replan aimed at a node that is not suspended spent a dispatch, ran no
sub-agent, and answered "the old run is still running as submitted".

That answer arrives for ordinary reasons, which the refusal itself names: a decision past
the adjudication deadline, a stopped run, a mistyped id. Each retry paid again. Measured
against the production charger with the hourly cap set to 5, four replans aimed at a
non-waiting node consumed the whole remaining budget, and the legitimate replan after them
was refused for a rate limit reading "the task may be looping" -- leaving the node
suspended and unreplannable for the rest of the rolling hour, with the refusal
misattributing the cause. `continue` and `abandon` reach the same hand-off and charge
nothing, which isolates this to the replan path's ordering rather than to the hand-off.

The fix asks first. `dag_live.awaiting_decision` reports whether one node of one run is
suspended, and the resolve call refuses on a definite no before the reconciled read and
before `prepare_replan`. Three design points a reviewer will want stated:

- **It refuses nothing the hand-off would have accepted.** The predicate is exactly the
  condition `resolve_node` fails on: both read the run's adjudication desk, and
  `AdjudicationDesk.resolve` refuses for the same reason `is_open` answers False.
- **It fans out over every graph tool, not over `owning_tool`.**
  `WiringMixin.resolve_dag_node` answers from whichever instance holds the run, and
  `owning_tool` falls back to the registered one when no instance claims it. A pre-check
  narrower than the hand-off it guards would refuse a replan of a run the playbook
  engine's private instance is running. This was caught by the pre-submit sweep, in the
  first version of this fix, before review.
- **It is three-valued.** `None` means no instance implements the question, which
  proceeds, so a host built before the predicate keeps replanning -- the same advisory
  contract every other helper in `dag_live` states. A raising instance answers `None` too,
  rather than being read as "not waiting".

The hand-off stays the authority for the node that stops waiting *during* the validation
this now skips ahead of, and that is the one case still charged. The two refusals are now
one string: the model cannot act differently on "refused before validation" than on
"refused after it".

No model-facing text changed. The `replan` design spec's ordered validation list and its
"nobody was waiting" enumeration were both incomplete after this and are updated; the
matching plan document is left alone, per the archive rule in `CONTEXT.md`.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Test-driven: the two behavioural tests were written first and observed failing (the cost
test reported `calls == ['prepare_replan', 'resolve_node']` where it asserts `[]`), then
made to pass.

Four mutants, each killed by the test written for it:

| Mutation | Result |
|---|---|
| remove the pre-check | 2 failed |
| narrow the fan-out to the registered tool | 1 failed |
| collapse `None` into `False` (fail-closed) | 2 failed |
| make the predicate ignore `node_id` | 1 failed |

Commands and results:

- `uv run pytest tests/test_subagent_dag_control_tools.py tests/test_subagent_dag_core.py
  tests/test_subagent_dag_adjudication.py tests/test_subagent_dag_runner.py
  tests/test_subagent_dag_verdict.py tests/test_living_docs.py -q -p no:randomly`
  -> 505 passed
- `uv run --frozen --all-extras pytest -q -p no:randomly` -> 19356 passed, 2 failed,
  138 skipped. Both failures are pre-existing and neither is in this change's blast
  radius; see below.
- `make lint-python` -> ruff check clean, 1823 files already formatted
- `uv run lint-imports` -> 8 contracts kept, 0 broken (this gate does not run in the
  GitLab pipeline)
- `make check-commits` -> pass; `scripts/check_source_language.py` -> pass;
  `make check-large-files` -> pass

Beyond the unit suites, the whole chain was driven end to end against the real store,
runner, adjudication desk and resolve tool, with real subprocess sub-agents registered as
a third-party CLI agent; only the verdict model call and the turn injection were doubled.
Eight scenarios, 173 assertions: the backgrounded and bound-foreground replans, the
wind-down status table, a chained second replan reading two earlier runs, the confirm /
quota / pause gates, the post-restart reads, and the four wire frames validated against
`raven/rpc/models.py`. All pass, including the quota control experiment above, which fails
without this change.

Attribution of the two full-suite failures:

- `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are` fails in a
  clean detached worktree at the target branch's tip, run in isolation under the same
  interpreter.
- `test_subagent_raven_launcher.py::test_the_folder_ships_exactly_one_roster_manifest`
  passes in that clean worktree and fails in this working checkout. Isolated by control:
  the test globs `subagent*.json`, which also matches five untracked
  `subagents-backup-*.json` files that local runs have left in the launcher's folder since
  mid-August. Copying those five files into the clean worktree reproduces the failure
  there; removing them again turns it green. Not introduced here, and the loose glob is
  noted rather than changed, being outside this change's scope.

0 introduced failures.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

Behaviour visible to the model: a `replan` naming a node that is not suspended is now
refused before the replacement graph is validated rather than after, so a graph error in
that same call is no longer reported. The refusal text is unchanged and already directs
the model to `dag_status`, which is where the node's real state is. Every other decision
path, and every replan that does have a suspended node, is unchanged.

The pre-check is advisory in both directions that could cost anything: it refuses only on
a definite no, and any host or instance that cannot answer proceeds exactly as before.

Rollback is the revert of this one commit; it restores the previous ordering and no state
or on-disk format changes with it.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

One coordination note: an open merge request against `main` also touches
`raven/agent/subagent/dag_control_tools.py`, `raven/agent/subagent/dag_tool.py` and both
test files this change edits. The hunks are disjoint -- it changes `execute`'s signature
and the guards at the top of it, while this changes the `replan` branch further down, and
its test edits append at the file tails -- and the two are semantically independent, since
it makes `decision` optional behind an alias that is normalised before the pre-check added
here reads it. Whichever lands second rebases; no symbol is extended by both.
2026-09-07 12:49:32 +00:00