20 Commits

Author SHA1 Message Date
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
2f862d8ca2 feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## What

Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.

## Why

The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.

## Behavior on slim installs

- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.

## Verified

- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
2026-09-05 17:09:13 +00:00
hylarucoder
c703db6ffd feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## What

Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.

## Why

The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.

## Behavior on slim installs

- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.

## Verified

- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
2026-09-05 17:09:13 +00:00
0xKT
cb6adc1bcb refactor(*): found the assembly root and the contracts package
raven/core/ is re-founded as the assembly root: the seven cli _*_stack
builders move there unrenamed in spirit (eval, gateway_spine, helpers,
hooks, plugin, proactive, token_wise). Entrances keep their transport;
the stacks own discovery, admission and wiring order. The old tombstone
test asserting raven.core must not exist is retired for positive
assertions: the old context-home symbols stay dead, the stacks answer.

raven/contracts/ is founded with two papers on two promise tiers:
turn.py (contract tier: TurnRequest / TurnHandle / Origin, skeleton
re-exports until the S2 full move) and loop_hooks.py (factory_loop
tier: AgentHook / AgentHookContext / HookDecision, moved out of
raven/agent/hook/base.py and stamped with its tier).

The ask_user tool types against a QuestionResponder Protocol declared
in the tool module itself, mirroring ApprovalResponder in shell.py; the
concrete QuestionBroker stays with the transports that construct it.
The agent loop names no broker machine any more. The Protocol mirrors
the machine signature as of this base, which is keyword-only.

One guard followed the move: the provider-auth allowlist names
core/helpers.py instead of cli/_helpers.py.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-28 22:40:59 +08:00
Handsome-wzw
9a87470fdf fix(rpc): turn.started is a turn event, and says so on all three sides
## Summary

Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.

**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.

So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:

```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```

while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:

```
Additional properties are not allowed ('node_id' was unexpected)
```

That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.

**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.

## What this does

- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.

## One thing the union surfaced

`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.

Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.

## Verification

- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:

| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |

- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
  - Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.

## Type

- [x] Fix

## Risk

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

Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
2026-08-28 12:51:10 +00:00
forrestjgq
8ecfae3e0c test(tracing): isolate span emission into per-test tmp dirs (#371)
## Summary

Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.

This PR adds an autouse fixture in `tests/conftest.py` that:

- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.

Key decisions:

- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.

## Type

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

Test-suite hygiene (`test` commit type).

## Verification

- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass

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

Docs box left blank: test-only change, no user-facing docs affected.

## Risk

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

Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.

## Related Issues

N/A

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-28 19:21:16 +08:00
arelchan
7c33c4133a fix(rpc): let the viewer open the files a turn actually wrote
## Summary

A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.

The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.

This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.

Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.

## Type

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

## Verification

- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
  - narrowing the carve-out back to the workspace alone reds
    `test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
  - dropping the containment-direction guard reds
    `test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
    and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
  (`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
  and `~/.raven/serve.json` still raise PermissionError.

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

## Risk

- Widens what the file viewer will render by exactly one subtree: the directory
  turns work in. Everything the fence was written to protect (provider keys in
  `config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
  not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
  directory as the root, which their own containment check already bounds, so
  their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.

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

## Related Issues

N/A
2026-08-28 04:57:29 +00:00
LivXue
4e35a5d627 fix(tui): show the copy-on-select confirmation as a transient notice (#366)
## Summary

PR #360 reports every copy-on-select write as a permanent transcript
line, so a
reading session that drags through the transcript piles up "copied N
characters" rows under the conversation. The confirmation splits by what
the
line is for: the unbounded terse repeats become a transient notice
rendered
above the input box -- one line that replaces itself on every new copy
and
clears after 3 seconds -- while the first copy of a session keeps its
path
caveat in the transcript. The caveat is the answer a user comes looking
for
after a paste comes up empty minutes later, and it cannot pile up
because it
is once per session by construction.

The reporter still owns the per-session caveat tally and now returns
`{ text, firstOfSession }` so the caller can route the caveat to the
transcript and the repeats to the notice. A new `copyNoticeStore` holds
the
single notice; `showCopyNotice` keeps one dismiss timer, clearing any
pending
one before arming the next, so an earlier deadline can never clear a
newer
notice. `/copy` is deliberately untouched: an explicit command's answer
still
belongs in the transcript, and it cannot stack on its own.

## Type

- [x] Fix

## Verification

Run from `ui-tui/` at branch head, in a fresh worktree of `github/main`.
Dependencies came from `npm ci` in `ui-tui/` and in the hermes package;
the
hermes package's own `node_modules` holds only esbuild, so the ink
render
tests run against one react copy (two copies break every hook call).

```
npx vitest run --no-file-parallelism
  Test Files  93 passed (93)
  Tests  1084 passed | 13 skipped (1097)

npm run type-check
  clean, exit 0

npm run lint
  22 problems (0 errors, 22 warnings)

npx prettier --check src/app/copyNoticeStore.ts src/__tests__/copyNotice.test.tsx
  src/__tests__/clipboard.test.ts src/app/useMainApp.ts
  src/components/appLayout.tsx src/lib/clipboard.ts
  All matched files use Prettier code style!

python3 -m scripts.check_commit_messages github/main..HEAD
  exit 0
```

The 22 lint warnings are the baseline, not new: 22 before the branch and
22
after, none in a file this branch touches. The suite is run with
`--no-file-parallelism` deliberately: the ink render tests fail under
default
worker parallelism at this suite size, and no CI job runs them.

Suites that exercise the changed code directly:
`src/__tests__/copyNotice.test.tsx`
(7 cases), `src/__tests__/clipboard.test.ts` (30 cases, the 3 reporter
cases
updated to the new return shape).

New tests were proved load-bearing rather than assumed:

- Removing the notice render line in `appLayout.tsx` makes the render
test
  fail (content and placement above the input box).
- Removing the pending-timer clear in `showCopyNotice` makes the
re-shown-notice test fail: the earlier 3s deadline then clears the newer
  notice.
- The dismissed-notice case now shows a notice first, and removing
  `dismissCopyNotice`'s atom clear turns it red (review fix).

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

No doc change. `ui-tui/CONTEXT.md` has no clipboard or selection entry,
and
"copy notice" continues the existing "notice" vocabulary of
`copyResultNotice`
/ `copyOnSelectNotice`, so nothing new is coined.

## Risk

Behaviour change: the per-drag copy confirmation is now transient and
above
the input box instead of a permanent transcript line, and the first copy
of a
session lands one transcript line, exactly as on `main`. Reverting the
branch
restores the #360 behaviour; no data or on-disk format 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 (deepseek-v4-pro) <noreply@anthropic.com>
2026-08-25 14:27:24 +08:00
gloryfromca
df9a7d7f37 chore(*): merge upstream v0.1.13 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.13 becomes a real ancestor: the next sync starts from v0.1.13
instead of v0.1.12, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.

Cost this round: 51 conflict hunks over 27 files, against 54 over 31 for
v0.1.12. The hunks were the cheap half. Upstream's #284 moves the model and
provider from process-wide state to a per-session binding, and the trunk had 230
commits standing on the old shape.

What git reported as a clean merge and was not
---------------------------------------------

Fourteen upstream-changed paths do not exist here, because we renamed or moved
them since v0.1.12. Rename detection found none of them, so their changes were
merged into paths nothing reads, silently:

* raven/tui_rpc/* -> raven/rpc/* (renamed in ce526ad5). Nine files, including
  question_broker.py, whose whole #354 rewrite was lost, and methods/config.py,
  methods/model.py, methods/session.py, models.py and errors.py. Each was
  replayed by three-way merge against dd82f52c. The three test modules were
  rebased function by function onto upstream's version instead, after a
  three-way merge spliced assertions into the wrong tests.
* raven/agent/tools/mcp.py -> raven/mcp/client.py. Carried the release-blocking
  fix, and is handled in the commit that follows this one.
* ui-tui/rpc-schema/openrpc.json -> rpc-schema/openrpc.json.

Decisions
---------

Follow upstream wherever the two disagree about provider and model:

* providers/pin.py is gone, so a bare model id is refused instead of derived.
  A model id does not name whose credential serves it, and the derivation
  walked a list -- with two vendors configured, which one pays came down to
  their order in it. rpc/methods/config.py now requires the provider.
* ModelSwitchInTurnError (-32009) is gone with it. A session switch lands on
  that session's next turn, so there is nothing to refuse mid-turn.
* AgentLoop.refresh_context_window and the LazyProvider on_built wiring are
  gone: the window rides on the binding now.
* The skill gate no longer forwards an unpaired pin.

Keep ours where the trunk is ahead, and graft upstream's behaviour into it:

* raven/agent/subagent/backends/raven_loop.py is the live sub-agent path, so
  manager.py's inline loop stays retired and the web_search gate from #312
  applies there.
* skill_hub/client.py keeps the public zip limits the skillhub RPC path imports,
  and takes upstream's query-string cap.
* ask_user keeps our JSON-string normalizers and feeds them into upstream's
  batch contract, so a batch validated by _prepare is one _normalize_questions
  has already coerced.
* The chat view composes both filters: hideIntroAfterFirstTurn drops the cover,
  visibleRows still hands the view to a direct chat.

Tests removed, not repaired
---------------------------

Eight tests covered mechanisms this merge deletes, and one of them hung rather
than failed:

* seven in test_agent_loop_model_switch.py over AgentLoop._pending_provider,
  the switch-parking mechanism #284 replaced with per-session bindings. Its
  replacement arrives with upstream as test_agent_loop_session_model.py.
* test_a_refusal_during_a_turn_keeps_its_own_code in test_acp_methods.py, whose
  error class no longer exists.

Baseline: the pipeline for 01d39e58, this merge's base, is green, so nothing
here can be charged to a pre-existing failure.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-25 16:12:43 +08:00
Handsome-wzw
a1d5b24de3 feat(agent): withhold web_search without a key, and make tool capabilities visible (#312)
## Summary

A WeChat user asked for a recommendation and the bot answered "the web
search
tool is not configured here". That sentence was not the model's own
phrasing --
it was the tool's error text, relayed outward. `web_search` needs a
Serper key
and that deployment has never had one, but the tool was registered
unconditionally, so on every search-shaped question the model saw it,
reached
for it, and passed the setup error on to whoever was in the chat.

Withholding the tool fixes that and creates a second problem: an
unregistered
tool is invisible. Nothing in a running Raven then says the capability
exists at
all -- the model is never offered it, no document lists it, and `raven
doctor`
reports on providers and memory but has never mentioned tools. The only
way to
learn that web search is one account and one edit away was to read the
source.

This does both halves, because either alone leaves a real gap: the
deployer is
told what this install can and cannot do, and the model is still not
offered a
tool it cannot run.

### Withholding the unusable tool

`web_search` is gated on a resolved key, in the main loop and in the
sub-agent
surface (`subagent/manager.py`) -- a sub-agent that reaches for a search
it
cannot run reports the failure to its caller, and that text lands in the
parent
turn, the same leak one level down.

The gate asks the tool, not the config. `WebSearchTool.api_key` resolves
at call
time from the constructor value *or* `SERPER_API_KEY`, so reading
`tools.web.search.apiKey` alone would withdraw a working tool from any
deploy
that exports the variable and configures nothing.

The tool's error message also hard-coded `~/.raven/config.json` while
the
gateway runs with `--config` elsewhere, so following it meant editing a
file the
process never reads. It names the path actually in force now. That text
is
reachable only if the key disappears after registration, which is
exactly why it
should be right: it is the message for the case the gate cannot cover.

### Three rules, and nowhere to read them

Registration is decided per family, each a different shape:

| family | rule |
|---|---|
| `web_search` | a resolved key, asked of the built tool |
| `web_fetch` | nothing -- always registered, a key only improves
extraction |
| media x3 | an `api_key` *or* a `model`, either counting as configured
|

For media those are two questions, not one. A section naming only a
model is
registered, because a model alone counts as asking for the tool, and
then every
call returns a missing-key error. Whether a capability is *offered* and
whether
it *works* come apart there, and a report treating them as one fact
ticks a
capability that cannot run.

Each rule is defensible where it sits. What is missing is anywhere to
read them.
Providers had the same sprawl once and answered it with
`providers.auth`: a
declarative table plus `credential_status` as the single authority, with
an AST
invariant enforcing that authority, because six surfaces had answered
the same
question six ways and each looked reasonable alone. Tools never got the
equivalent.

### What this adds

**Each tool answers for itself,** twice where the questions differ.
`WebSearchTool.is_configured` reads the config value *or*
`SERPER_API_KEY`,
because those are two sources and only the tool consults both. The media
base
answers `is_configured` on a model *or* a key -- which is what stops an
OpenRouter credential set for chat from silently switching on three
tools that
bill per call -- and answers `has_key` separately on the chain it
actually
resolves at call time: its own section, the borrowed provider key, then
`OPENROUTER_API_KEY`. Both rules live with the credential they read.

**`capabilities.py` describes the five** for a human deciding what to
set up:
what each does in one line, how much work it is (nothing / reuse a
credential
you already have / obtain an account), where the key goes, where to get
one, and
what it costs. It rules on nothing -- `is_configured` and
`has_credential` both
ask the tools -- so it cannot become a second opinion.

**`raven doctor` grows a section**, listing every capability configured
or not,
ordered by how much the deployer has to do:

```
(markers render as a green check and a yellow bang; spelled [ok] and [!] here to
keep this description ASCII, since it becomes the squash commit body)

Tool capabilities
  web_fetch:       [ok] Read a web page the agent already has the URL for
  image_generate:  [ok] Generate an image  (borrowed: providers.openrouter.apiKey)
  text_to_speech:  [!] Generate speech from text
                   no key resolves; calls will fail
                   set: tools.media.speech.apiKey
                   or env: OPENROUTER_API_KEY
  video_generate:  -  Generate a video
                   switch on: tools.media.video.model
                   key: reusing providers.openrouter.apiKey
                   Billed per call; needs prepaid OpenRouter credit.
  web_search:      -  Search the web
                   set: tools.web.search.apiKey
                   or env: SERPER_API_KEY
                   key from: https://serper.dev
  2 capability(s) available but not set up; the agent is not offered them.
```

Three deliberate details.

Naming the credential is load-bearing in both directions. A row that
cannot
distinguish a reused credential from a missing one sends someone to
create an
account they already have -- and a row that claims a reuse with nothing
to reuse
is worse, because acting on it means setting a model, getting a
registered tool,
and watching every call fail on a credential they were told they had. So
the
reuse line prints only when a key is genuinely there to pick up, and a
capability already in that broken state says so outright instead of
showing a
satisfied tick.

The credential is named at the path that holds it. For the media family
`config_path` names the *model*, so reusing it as the key source pointed
the
deployer at a line with no credential in it.

And each fact is on its own line rather than in a sentence, because the
terminal
wraps a long line mid-path and a config key broken across two rows
cannot be
copied, which is the only thing that row is for.

Nothing here moves the exit code, including the warned row. An install
without
image generation is a choice, not a fault, and a doctor that fails on it
teaches
people to ignore doctor. The half-finished one is arguable -- the memory
section
does exit non-zero for a role the user configured that the server could
not
build -- but that failure is silent where it happens, recall just
returning
nothing, whereas this one returns an error string to the model on every
call.
Say the word and it becomes an exit code instead.

### Not in this change

Registration still lives in `AgentLoop`. Having it read the table is the
point
of this shape and removes the last duplicate reader, but it edits
`agent/loop/main.py`, which is under active change, and it is worth
doing on its
own once that settles. Until then the table is a description, and the
tests
below are what keep it honest.

`deep_research` is deliberately absent: it is moving to the sub-agent
surface
and its tool is going away.

## Type

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

Mixed on purpose: the first commit is a fix and the rest are the feature
it
made necessary. Splitting them would land a change that hides a
capability
without landing the one that makes it discoverable.

## Verification

```
make lint                                            exit 0
make build                                           exit 0
npm run test --prefix ui-tui                         969 passed, 13 skipped
uv run --all-extras pytest -q                        6186 passed, 35 skipped, 1 failed
uv run pytest tests/test_tool_capabilities.py \
              tests/test_cli_doctor_commands.py \
              tests/test_agent_loop_web_tools.py     64 passed
uv run --extra dev ruff check raven tests scripts    All checks passed
uv run --extra dev ruff format --check               828 files already formatted
npx commitlint --from origin/main --to HEAD          exit 0
scripts/check_commit_messages.py origin/main..HEAD   exit 0
```

The one failure is
`test_read_file_image.py::test_an_attachment_that_cannot_be_
read_costs_a_note_not_the_turn`, and it is not from this branch: it
fails the
same way on `main` at `1cb604a` with these commits absent. The case
makes a file
unreadable with `chmod 000`, which does not block a root user, so it
fails for
anyone running the suite as root and passes in CI. This branch does not
touch
that file or the code under it.

The capability tests drive a real `AgentLoop` and compare what it
registered
against what the table predicts, rather than asserting the table against
itself.
The gated set is derived -- tools present once credentials are supplied,
absent
without -- so a sixth gated tool whose author forgets the table fails
here rather
than going unnoticed.

That last claim was false when first written, and the last commit is
what makes
it true. The fixture listing the media tools by hand never switched a
fourth one
on, so a new one never joined the gated set and the assertion held over
an
already-incomplete table. #305, which adds a MiniMax voice-clone tool,
is that
case: merged against this branch the assertion passed. Read from
`MediaGenConfig` instead, it fails and names the tool -- `gated but
undeclared:
['voice_clone']`.

Which means whichever of the two lands second turns this red,
deliberately. The
fix is one table entry, and it needs the rule that PR settles:
`voice_clone`
counts as configured on `api_key or api_base or model` in
`effective_media_config` while registration still gates on `api_key or
model`,
so an `apiBase`-only install with no MiniMax key is configured by one
rule and
withheld by the other. That is the divergence this table exists to make
visible,
and it is worth resolving there rather than papering over here.

Fifteen mutations, each caught:

```
the web_search gate removed from the main loop    3 failed
the same gate removed from the sub-agent surface  1 failed
media rule reads only the key                     7 failed
web_search rule reads only the config             1 failed
a tool removed from the table                     6 failed
the doctor section not rendered                   6 failed
doctor lists only configured tools                4 failed
unconfigured treated as a failure                17 failed
the reuse line is printed unconditionally         1 failed
the key source falls back to the model path       3 failed
a keyless registered capability is not flagged    1 failed
has_key always answers yes                        1 failed
has_credential collapses into is_configured       1 failed
the credential chain drops OPENROUTER_API_KEY     3 failed
the reuse check ignores the environment           3 failed
```

Four of those tests exist only because a mutation pass found the earlier
versions insufficient, and the last rounds are why the shape changed. A
media
case that sets both a model and an OpenRouter key proves nothing about
the "or
model" half: the borrow fills the key in, so a rule reading only the key
still
answers correctly. The case that pins it has nothing to borrow.

The sub-agent case is the same argument applied to the second call site:
with
the gate present only in the main loop, every test above still passes,
because
nothing was watching what the sub-agent surface registers.

More usefully, mutating `has_key` to always answer yes changed no test
at all in
the first version, which said the ruling was not load-bearing: the
doctor was
inferring "no credential" from an *empty source string* rather than from
the
tool's answer, so a fourth credential source would have been reported as
a
missing one. `has_credential` is now its own fact, asked of the tools,
and that
mutation fails.

Separately, autouse fixtures clear `SERPER_API_KEY` and
`OPENROUTER_API_KEY`,
without which several of these pass for the wrong reason on any machine
where a
developer exported one.

Rendering was checked against a real config in six states -- nothing
set, a
provider key present, a model with nothing to borrow, a tool with its
own key, a
model plus a borrowable key, and an exported variable as the only source
--
rather than only asserted on.

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

## Risk

One behaviour change: `web_search` is no longer offered to the model
when no key
resolves. That is the fix. A deployment that has a key, in config or in
the
environment, is unaffected; one that has none was getting an error
string in
place of an answer.

The rest is additive. No other registration logic changed, so which
tools an
agent is offered is otherwise exactly what it was; `is_configured` moved
the
existing predicates onto the tools without altering them, and the
mutation
results above are what pins that. `has_key` and `_resolve_key` are new
names for
the chain `api_key` already resolved -- the property calls the extracted
one, so
callers see the same answers.

`raven doctor` gains a section and no new exit code. Its zero-network
guarantee
holds: the table reads config and environment only.

Two allowlist entries were added to
`test_only_the_auth_module_decides_configuredness_from_a_key`, argued in
place:
`subagent/manager.py`, which asks the built tool whether a key resolved
so an
unusable search is withheld, and `capabilities.py`, which reads keys to
*report*
-- which source supplied one, and whether one is there to reuse. Both
ruling
halves are delegated to the tools, whose files were already listed.

Rollback is a revert. Nothing is written and no configuration is read
differently.

- [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-08-25 10:05:58 +08:00
arelchan
82eea1dd20 fix(ui): show Raven logo as page favicon
## Summary

- Declare the existing Raven application logo as the served page favicon.
- Copy the logo into the packaged page assets so installed builds render the same branding.

## Type

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

## Verification

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

- `npm test --prefix ui` - 32 test files and 528 tests passed.
- `npm run type-check --prefix ui` - passed.
- `npm run build --prefix ui` - passed.
- `python3 ui/build.py` - built the page and copied the Raven logo asset.
- `node ui/scripts/check-page.mjs` - passed.
- `make check-large-files` - passed.

## Risk

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

Low risk. The change only adds favicon metadata and packages an existing application asset. Reverting the two source changes restores the prior browser-default icon.

## Related Issues

N/A
2026-08-23 11:11:06 +00:00
gloryfromca
56858acbce fix(*): report an invalid memory identity as the config error it is (#350)
## Summary

An identity EverOS cannot accept becomes a directory segment on its
write path, so `EverosBackend.start()` rejects it. The rejection carried
the one message a user can act on -- it names the key and the accepted
pattern -- and no surface delivered it as one. Three of the four call
sites fold the raise into `logger.exception`; under the TUI loguru is
file-only, so there an invalid identity turned memory off with nothing
on screen. The fourth, in `import_commands._build_and_run`, is not
wrapped at all, so the `ValueError` escaped as a bare traceback. Where
it was visible it was a traceback, which is not a thing a user reads as
"edit this key".

The state machine then told the user the opposite of the truth.
`start()` died before assigning a state, so `_state` stayed `UNKNOWN`,
which is not in `_NEVER_HAD_MEMORY`; every `store()` after it counted a
dropped write, and the session ended with:

```
1 turn(s) were not written to long-term memory because the memory service was
unavailable.
```

The service was fine. That sends the user to debug a server that never
broke.

**The change.** Catch the `ValueError` in `start()`, give it a
`BAD_IDENTITY` state, and file that state with the other two the user
must fix themselves:

- terminal, so a stray probe cannot promote it to `READY`;
- never-had-memory, so no dropped-write count and no outage wording;
- the message goes to stderr, matching what the unconfigured-LLM and
missing-binary paths beside it already do.

Two things came out of running it rather than reading it:

1. **The message needs escaping.** It quotes the accepted-character
class, and rich reads `[a-zA-Z0-9_.@+-]` as a markup tag and eats it,
leaving the user the pattern `^+$` to match their id against. The test
now pins the full class.
2. **`raven import` had the same defect on its own gate.** It kept the
outage wording and pointed at the server log, which holds nothing about
a config error. It now names the config keys instead.

Before / after, same config (`memory.userId: "bad/id"`), same command:

```
- 1 turn(s) were not written to long-term memory because the memory service was
- unavailable.

+ Long-term memory is off: memory.userId='bad/id' is not accepted by EverOS: it
+ becomes a directory segment on the write path, so it must match
+ ^[a-zA-Z0-9_.@+-]+$ and must not be '.' or '..'.
+ Fix memory.userId / memory.agentId in your config.json, then start a new session.
```

## Type

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

## Verification

Re-run after rebasing onto `d35e398c`, the current `main`.

```
uv run pytest tests/test_everos_backend.py tests/test_cli_import_commands.py \
              tests/test_everos_plugin_discovery.py -q
162 passed

uv run pytest -q
1 failed, 6478 passed, 43 skipped, 13 deselected

uv run ruff check <the four touched files>            All checks passed
uv run ruff format --check <the four touched files>   4 files already formatted
```

The one failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`. It
is pre-existing on this base: checked out `d35e398c` in a clean worktree
and ran `uv run pytest tests/test_cli_theme.py` there, same failure, 1
failed / 44 passed. It passes in isolation and fails when the file runs
as a whole, so it is order-dependent, and it is unrelated to anything
here. That file is untouched by this change.

Manual check, sandbox `RAVEN_HOME`, `memory.userId: "bad/id"`, `raven
agent -m "hi"`: prints the block quoted above, and the session no longer
ends with the dropped-write line.

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

## Risk

Terminal-only wording plus one new enum member. No config, schema, or
protocol change; an identity that was accepted before is accepted now,
on the same code path. The only behaviour change for a valid setup is
none.

For an invalid identity the turn behaves as it did -- memory off, turn
completes -- and only what the user is told changes. Rollback is
reverting the single commit.

`ServiceState.BAD_IDENTITY` is new. Every consumer was checked:
`raven/cli/import_commands.py` (handled here) and
`tests/test_everos_plugin_discovery.py` (reads `READY` only).
`_may_spawn` allowlists `UNKNOWN` via `_SPAWNABLE_STATES`, so a new
member is non-spawnable without a change.

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

## Related Issues

Fixes #271

Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-20 14:41:45 +08:00
arelchan
feacba682c refactor(ui): the session rail becomes a react island
## Summary

The session rail (left sidebar) becomes a React island: `ui/src/features/rail/` with types, a plain external store (draw/skeleton/markNew/remove/rename, fold state on the `raven.gui.grpfold` localStorage key), the Row/Group/RailApp components with classes and DOM shape copied byte-for-byte from the legacy renderer, and 13 tests.

Key decisions:
- `SESS`/`cur` stay shared page globals: ten demo/live files write them (including whole-array rebinds), so the island owns no rows. It reads through `DS.sessions.snapshot()`, a closure over the rebindable bindings, re-read on every `drawList()`.
- Island actions go out through 9 new optional bridge verbs (`drawList, setCur, openSession, removeSession, renameTitle, dropDraft, pinPersist, openCron, navState`), each one a guarded one-liner in 155-bridge.js and late-bound so live rebinds keep winning.
- `plainTitle` moved into the bundle and is republished as `window.plainTitle` for its 6 legacy callers (same pattern as `cronExprHuman`).
- Shrink: demo/050-rail.js 222 -> 16 lines; live/010-boot-guard.js raw-DOM skeleton painter became one `RavenIslands.rail.skeleton()` call; live/030-sessions.js untouched (already renderer-free, its helpers are read by other domains).
- Pre-existing bug left as-is: live/080-overrides' rename persist wrapper queries `#title input` after the h1 swap and throws today; the island reproduces the demo DOM dance exactly rather than patching another domain in this MR.

Ratchet: 57 -> 57 (the strands touching this domain remain demo-declared/live-assigned by design; nothing new added).

Note: pipelines are currently red project-wide with `ci_quota_exceeded` (shared-runner minutes exhausted). Local gates below are the same commands CI runs; the pipeline should be retried once quota recovers.

Review round: the fake shell handed `markNew` an empty nav and a folded More group, so both of its branches were dead in every test -- exactly the part of the port that changed shape (`Object.keys(NAV_OF)` to `nav.pages`, `$('#' + p)` to `getElementById`, `MORE_ROWS[i][0]` to `nav.morePages[i]`). Two cases added with the real nav: a module page up marks its own rail button over the new-task row, and an open More group puts the mark on the row whose page is up while the parent gives it up and takes it back when folded. Both fail against a wrong port.

## Type

- [x] Refactor

## Verification

- `npm run --prefix ui type-check` clean
- `npm test --prefix ui` 49/49 (13 new rail tests)
- `npm run --prefix ui build` (223.95 kB IIFE) and `python3 ui/build.py` (1,094,616 bytes)
- `node ui/scripts/check-page.mjs` OK; `node ui/scripts/count-shared-globals.mjs` 57/57
- `uv run pytest tests/test_ui_language_repaint.py` 9/9
- Stub browser pass (`?stub=1`): DOM byte-compared to legacy (.grp/.sess shapes, aria-current moves, fold persistence, search, pin+persist, delete+undo toast, rename via top bar, running mark lifecycle, More flyout marks, zh/en repaint)
- Live pass against a throwaway gateway (temp RAVEN_HOME, dummy keys, nonce auth): boot shows exactly 6 skeleton rows with the legacy width formula while `data-counts="pending"` holds, then the real list swaps in; draft's first send creates a real session; two-session switching moves a single mark; second boot renders with no mock flash
- Not exercised live: a successful provider turn and parked done/err badges (needs a real key); covered by unit tests and the stub replay

## Risk

User-visible behavior is intended to be identical; the rail DOM shape and class names are unchanged. Rollback is reverting the single commit.

## Related Issues

N/A
2026-08-20 06:17:21 +00:00
arelchan
e32f4b6034 fix(*): keep migration notices off stdout, and stop planting defaults (#346)
## Summary

Three follow-ups from #341, which fixed a retired `contextWindowTokens:
65536` capping every upgraded install at 64k. Two are its loose ends;
the third is the reason it happened at all.

**The notice no longer prints on stdout.** #341 drains config-migration
notices in the `run()` wrapper so every command tells the user, which
caught the two whose stdout is a machine-readable document: `raven
doctor --json` and `raven import --json`, both advertised for
automation. Reproduced -- a config still carrying the retired pin makes
`doctor --json` emit JSON with a sentence after it, and `jq` refuses the
result. Moved to stderr, where the rest of this class of message already
goes (the `ConfigReadError` branch a few lines up in the same wrapper,
and the loader's malformed-config warning). That fixes any future
`--json` command without it having to know this exists, which
allow-listing the two would not. The window is narrow -- the migration
fires once per install -- but the run it can spoil is a first run after
upgrading, and a CI job is exactly the caller not watching.

**`raven doctor` gains a Config section and a `--fix`.** The premise
changed while building it: the migrations run at load, so by the time
this command looks, nothing is pending -- they already happened,
silently, one launch ago. What is left for a person to ask about is what
Raven deliberately will not decide for them. So it reports a
`contextWindowTokens` pinned below what the configured model holds, and
names what rides on it: the per-turn history budget, when the Curator
starts paying for a slow path, and when memory consolidation archives.
`--fix` removes the pin.

Reported without `--fix`, never written: that pin is a real
configuration for a local model or an endpoint served smaller than the
catalogue thinks, and the flag is the user saying which case theirs is.
The write carries the file mode across (config.json holds
`providers.*.apiKey`) and uses a per-PID temp name -- the same rules the
loader's migration writer follows.

One check rather than two. A config naming no provider is the other
thing worth asking about, but it reads differently on either side of the
explicit-provider rule in #284, so it belongs to that change; a model
that routes to nothing is already reported above it.

**The bootstrap stops writing every default into the user's config.**
This is the cause of the bug #341 cured. `save_config` dumped the whole
`Config()`, so a new install started life with eight kilobytes of
settings its owner had never heard of and, worse, with that day's
defaults frozen into their file -- after which a default we improve
never reaches anyone who already has one. `contextWindowTokens: 65536`
got onto disk exactly this way.

It now writes only what differs from the defaults. Lossless on reload,
since a value equal to its default reloads as that default. A fresh
config drops from 7,985 bytes to 2, and to 634 once the extension blocks
are seeded -- what is left is the handful of lines someone actually
chose, which is also a config they can read.

That third one is the only change here with a broad blast radius, and it
has one visible consequence, which is an improvement: the onboarding
picker used to lead with the schema's default model, because the
bootstrap had written it into the config and the wizard read it back as
"the current model" -- a value nobody had chosen, offered as though
somebody had. With nothing written, the wizard leads with the provider's
own recommendation instead. The test that pinned the old list now pins
the new one and says why.

## Type

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

## Verification

```
pytest tests/                       6650 passed, 1 failed, 33 skipped
                                    (tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare,
                                    which fails identically on github/main when its file runs
                                    together and passes alone on both)
ruff check raven/ tests/            All checks passed
ruff format                         clean
```

Driven by hand as well as by tests, each against a throwaway home:

```
doctor --json on a fossil config   stdout parses as JSON again; the notice is on stderr
doctor    (pin 65536, model 1M)    reports the pin and what is sized against it
doctor --fix                       pin removed, file still 0600, a second run reports nothing
save_config on a fresh Config()    2 bytes; 634 after the extension blocks are seeded
```

New cases cover the stderr split, both doctor paths including the mode
preservation, and the save round-trip keeping every value the user
chose.

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

## Risk

The bootstrap change alters what every new install's config file looks
like: nearly empty instead of a full dump. Existing configs are
untouched -- nothing rewrites them -- and both shapes load identically,
so the risk is confined to anyone reading `config.json` as documentation
of what can be set. `raven doctor` and the schema remain the answer to
that question.

The onboarding picker's default moves from the schema default to the
provider's recommendation, as described above.

`doctor --fix` writes only when asked, and only removes a key.
Everything else here is output routing.

Rollback: revert the commits. Nothing persists a new format, so a
reverted build reads every config written under this one.

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-18 18:55:29 +08:00
LivXue
32f8044e86 feat(*): direct chat with a sub-agent instance, in the TUI and the web UI
## Summary

Adds direct chat with a sub-agent instance: talking to one of the instances a
session has spawned, without that exchange entering the main agent's context.
The TUI gets the feature end to end; the web UI then gets the same thing on the
same runtime.

**The runtime.** A direct turn runs on its own lane (`session#agent/handle`)
rather than the session's, so several instances answer at once while the main
agent keeps its own serial lane, and direct turns draw on a separate
concurrency pool so a user is never queued behind them. Direct turns are not
cancellable: `turn.cancel` keeps meaning the main agent's turn on both
surfaces. Each turn writes a record (`prompt.md` / `out.md` / `meta.json`), and
the main agent learns only that the exchange happened, through a handoff block.

**Sub-agent replies over ACP.** Three separate causes were losing most of a
reply. Raven answered every agent-initiated request with `method not found`,
including `session/request_permission`, and the codex adapter turns any error
from that request into a cancel -- so a turn died as soon as the agent asked to
run something. Raven now approves, choosing among the options the agent offered
by their protocol kind. A stop reason other than `end_turn` was returned as a
finished answer, so a truncated reply read as a complete one; it now carries a
notice. And several messages in one turn were joined with no boundary, so a
preamble, its tool calls and the answer ran together as one paragraph.

**Instance visibility.** A failed resume deleted the whole registry row, which
took the instance off the strip for the length of the turn recovering it, and
permanently if that turn failed; it now drops only the stale binding. A
capability snapshot whose fingerprint no longer matched was discarded, which
defaulted the agent to *stateless* -- editing an agent's `env` silently cost it
resume, its chip, and the `instance` parameter in the spawn schema. Its
capabilities are now kept and flagged, while its verdict is not, so the
`/subagents` row asks for a re-test.

**Working directory.** A direct chat was the one sub-agent dispatch that
supplied none, so it fell back to agent home and ran its commands against
raven's own memory instead of the user's checkout.

**The web UI.** Two wiring gaps came first, both silent: the browser's
dispatcher registered neither instance method, and the web channel never built
the map that tags an event with its addressee, so nothing a client could
demultiplex on was ever sent. The service then routes on that tag at the push
rather than at the read, because the main reply and a direct turn share one
subscription and two consumers on one queue would each swallow the other's
events -- including a `message.complete`, which would end the wrong turn. A
direct turn's events are published out of band; feeding them into the reply
stream is not an option, since that stream is one reply per turn.

Decisions and their measurements are recorded in `docs/specs/`. Notably, the
vendored AgentScope tree is *not* edited, which is a decision rather than an
omission: making a direct chat a real reply would mean re-keying a blocking
per-session lock that guards message storage and tool-call state as well as the
reply loop, and rendering reuse was obtained without it.

## Type

- [x] Feature

## Verification

- `uv run pytest -q` -- 8021 passed, 36 skipped. The one deselected failure,
  `tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`, fails the
  same way on `origin/main` in a clean worktree, so this introduces none.
- `uv run ruff check raven/ tests/ ui-webui/service/` -- clean;
  `uv run ruff format --check` -- 957 files already formatted.
- Web service: `python -m pytest ui-webui/service/tests -q` -- 13 passed.
- Frontend: `pnpm lint` -- 0 errors, 18 warnings, each one also present before
  this change; `pnpm build` -- succeeds; `tsc --noEmit` -- clean.
- Every fix here was checked by reverting it and watching its test go red. Two
  tests that passed either way were rewritten after that check exposed them.
- End to end against a running gateway: a direct chat sent through the new web
  route completed twice, each leaving a record whose `out.md` held the exact
  reply asked for, and the history route returned those turns afterwards.

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

The last box is unchecked: the terms are defined in `CONTEXT.md` and the designs
in `docs/specs/`, but no end-user documentation or screenshots were produced.

## Risk

**Approving sub-agent permission requests is a widened trust boundary and the
main thing to review here.** An ACP sub-agent that asks to run something now
gets a yes, and the codex preset is configured for its most permissive mode --
wider than the `-a never` the cli transport used. It is unattended by
construction: a dispatch has no operator and no surface that could render a
prompt, so the alternatives were approving or refusing, and refusing leaves the
agent unable to do the work. Rolling back is per-agent config, or reverting
`raven/agent/acp/permissions.py` to restore the refusal.

Two known gaps, neither reachable today, both stated rather than fixed:

- The web UI's event consumer has no `target` guard of its own. The two
  surfaces use disjoint session keys and the browser never sends a target, so a
  direct turn cannot reach it; a caller that sent one on a `web:` session would
  see a sub-agent's reply rendered as the main agent's. Fixing it would widen
  this into unrelated files.
- Direct-chat record directories have no TTL and no count cap, like the spawn
  and DAG trees beside them. Reclaiming them would also start deleting audit
  trails that intentionally outlive session deletion, which is its own change.

Behaviour changes worth naming: a direct chat under a sandbox whose volumes do
not cover the working directory now fails where it used to run quietly in agent
home, matching what the main path already does; and a partial reply now carries
a `[raven]` notice, so anything parsing a sub-agent's reply verbatim sees it.

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

## Related Issues

N/A
2026-08-17 02:52:57 +00:00
Elliot Chen
9bc959d7c5 docs: redesign README around benchmark proof (#280)
## Summary

- Reframe the README around benchmark evidence, onboarding, Deep
Research, and Tracing.
- Restore the main branch's opening product capability overview before
the benchmark evidence.
- Keep the table of contents removed and place the native Markdown
benchmark table directly after the introduction.
- Remove outbound links from the three benchmark row labels while
preserving the reported results and supporting context.
- Synchronize the English and Chinese READMEs around the same structure,
spacing, and Back to top section boundaries.
- Place the GitHub User Content onboarding recording directly below the
benchmark table in both READMEs, using the same bare attachment URL.
- Reduce duplicate capability, gateway, status, and ecosystem copy while
preserving concise architecture and command references.
- Document current runtime behavior for the six-step onboarding flow,
MiroThinker-backed research delivery, and local trace storage.

## Type

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

## Verification

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

Commands and results:

- `.venv/bin/pre-commit run --files README.md README.zh-CN.md` - passed
all applicable hooks.
- `git diff --check origin/main...HEAD` - passed.
- `make check-large-files` - passed.
- `git merge-tree --write-tree HEAD origin/main` - passed with no
conflicts.
- README structure assertions - passed: no table of contents, no
benchmark-label links, and four matching Back to top boundaries in each
language.
- Confirmed both READMEs use the same 33378-byte GitHub User Content
hero banner; benchmark evidence is native Markdown.
- Confirmed the 1179517-byte onboarding MP4 round-trips from GitHub User
Content with SHA-256
124024e6d64c23b3e314aa6136d9e0d922f57ded97a830a5c97cd1323cb2c57f and
renders with controls below Benchmarks in both languages.
- `uv run pytest --tb=short -q` - 6130 passed, 33 skipped, and one local
Python 3.14 ANSI color assertion failed; the GitHub Python 3.12 unit job
passed.

## Risk

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

This is a low-risk documentation-only change. Rollback requires
reverting the README commits; externally hosted user-content assets can
remain unreferenced without affecting repository size.

## Related Issues

N/A
2026-08-12 21:02:13 +08:00
LivXue
14e270f8e6 feat(*): split agent home from the working directory and record sub-agent calls
## Summary

`workspace` meant two things at once: the agent's global home (user memory,
skills, transcripts, memory store, Skill Hub cache) and the directory a turn
reads and writes files in. This splits them, and gives each half a layout that
matches how it is used.

This MR was opened once before against a per-session design and withdrawn for
requirement alignment. What lands here is the aligned design: the gateway's
unit of isolation is the **channel**, not the conversation, and per-conversation
storage is the session's own directory under `sessions/`.

**Working directory.** `raven tui` and `raven agent` work in the launch
directory, so the agent operates on the checkout you started it in; its
bookkeeping stays under that directory's `.raven/`. `raven gateway` gives each
channel one directory, set by `channels.<name>.workspace` next to that
channel's credentials (`gateway.web.workspace` for web) and defaulting to
`~/.raven/tmp/<channel>`. The default is derived from agent home rather than
`$HOME`, so `--home` keeps an isolated instance isolated.

**Session storage.** A conversation's transcript and a new metadata directory
now sit together under one group: the slugged launch directory on tui/agent,
the channel name on the gateway. The slug reproduces the scheme Claude Code
uses for `~/.claude/projects/`, transliterated from the shipped implementation
rather than inferred: each non-alphanumeric character becomes one `-` (so `_`
folds too), and past 200 characters the slug is truncated with a hash of the
whole path. Terminal conversations stop piling up under `cli/` and `tui/` with
nothing tying them to the project they were about. The slug is a bucket, not an
identity -- the launch directory is recorded in `Session.metadata`.

**Sub-agent history.** Both ways of delegating now record what they were asked
and what they answered, under `sessions/<group>/<id>/subagents/`. `spawn` wrote
no file at all before - its reply went into the conversation and nowhere else,
so a sub-agent that failed left only a log line. Failed, aborted and cancelled
calls are recorded too, and the prompt is written before dispatch, so a call
that never returns still shows what was asked. DAG run directories move here
from `<workdir>/.ravenx_dag/`.

The mechanism is a per-turn `ContextVar` bound by `AgentLoop.run_turn`.
Components running inside the turn read it; anything that outlives a turn
(sub-agents, DAG runs) captures the directory as data at spawn, marked by an
explicit `follow_binding=False`. That distinction is load-bearing: an
`asyncio.Task` inherits the binding at creation, so a re-read appears to work
and then silently follows the wrong directory once the two diverge.

### Layout

```
~/.raven/workspace/sessions/<group>/
|-- <session_id>.jsonl            transcript
`-- <session_id>/subagents/
    |-- spawn/<call_id>/          prompt.md, out.md or error.md, meta.json
    `-- mas_dag/<run_id>/         graph.json, manifest.json, <node>.*.md

~/.raven/tmp/<channel>/           gateway working directory (default)
<launch dir>/.raven/              tui/agent bookkeeping
```

### Breaking changes

- `--workspace/-w` no longer sets agent home; `--home` takes over that meaning.
  A script passing an absolute path to `-w` keeps running but silently shares
  the default agent home; one passing a relative path now exits with a
  parameter error, because a working directory must be absolute.
- Gateway sessions no longer run in the agent-home root.
- DAG run directories moved; existing `.ravenx_dag/` is neither read nor
  migrated.
- A working directory may not be agent home, anything inside its
  memory/skills/session subtrees, or any directory containing agent home.

### Defects fixed from the previous round of review

- The DAG read side resolved run directories against agent home while writes
  followed the turn binding, so a per-session run was unreadable the moment it
  was written: the graph never restored and no node detail ever opened. The
  read path is now derived from agent home plus the session key, which reads
  correctly between turns when nothing is bound. `raven.subagents.dag.node`
  gained the `session_key` it never carried.
- `validate_override` accepted an ancestor of agent home. `~/.raven` is the
  instance data directory, and the per-turn checkpoint runs `add -A` over the
  working directory, so pointing a session there would have committed
  `config.json` and `oauth/` into a shadow git repo.
- Dot-only session-key segments escaped their own root: `safe_filename` leaves
  `..` intact, which is fine for `<chat_id>.jsonl` but not for a bare directory
  name.

### Defects fixed from the second round of review

- `channels.<name>.workspace` reached the resolver unvalidated, while every
  other way of naming a working directory goes through `validate_override`.
  Agent home itself, a protected subtree and a relative path were all accepted,
  and the per-turn `add -A` would then have run over `user_memory/` and
  `sessions/` -- the shape the ancestor check exists to prevent, reachable
  through a different door. The field is settable from the web UI's channels
  form, and the mount check only refuses an out-of-mount directory when the
  executor is sandboxed, which the default backend is not.
- The default channel root is a sibling of agent home, which resolves to the
  system `/tmp` when the home sits directly under the filesystem root:
  `--home /workspace`, a common container mount, put every channel in a shared,
  world-writable, reboot-cleared directory.
- `key_from_path` derived the channel from the parent directory, which under
  project grouping is a slugged path no session key can match. The sentinel
  producers call it on every file they scan before reading it, so for them that
  fallback is the primary path.
- The slug was inferred from three directory names and got repeated separators
  and trailing slashes wrong. It is now transliterated from the reference
  implementation: replacement is per character rather than per run, and past
  200 characters the slug is truncated with a base36 hash of the whole path.
  The tests carry the reference algorithm rather than importing ours, so drift
  fails them.
- The slug is deliberately still not collision-free (`/srv/a_b` and `/srv/a/b`
  produce one segment, in the reference too), so the launch directory is now
  recorded in `Session.metadata["project_dir"]` -- the reference solves this
  the same way, by writing `cwd` on every transcript entry. Nothing is scoped
  by group today, so a collision is currently invisible; the metadata is
  written now so it is already there if `--continue` is ever scoped to the
  project.
- The sub-agent history directory is append-only with no expiry, no cap and no
  reclaim path but deleting the session. DAG runs dominate its volume, because
  a node's rendered prompt inlines its dependencies' full output. Now stated in
  `CHANGELOG.md`, `CONTEXT.md` and the design doc; bounding it is deliberately
  a separate change.

## Type

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

## Verification

- `uv run pytest -q -p no:randomly` on this branch rebased onto `2178707` ->
  5 failed, 6034 passed. The same command on `origin/main` at `2178707` in a
  separate worktree -> 5 failed, 5898 passed. The two failure sets are
  identical test ids: 0 introduced, 0 fixed. Those 5 are environmental or
  pre-existing (three `test_channels_qr_*` assert a PNG prefix with no skip
  guard for the optional `qrcode` extra, plus a theme test and an onboard
  test). GitLab's server-side rebase produced tree `eccdc91c`, byte-identical
  to the tree these numbers were measured on.
- `ruff check` over `raven tests scripts` -> clean. `ruff format --check` ->
  one file, `tests/test_web_rpc_config.py`, which reproduces on `origin/main`
  at `2178707`; it arrived with the everos memory config page and is left for
  its author rather than fixed in an unrelated MR.
- `pnpm tsc -b --noEmit --force` in `ui-webui/frontend` -> exit 0.
- `pnpm eslint` on the changed frontend files -> 0 errors, 1 warning
  (`react-hooks/exhaustive-deps` in `ChatViewport.tsx`), pre-existing on
  `origin/main`.
- `npx vitest run` in `ui-tui` -> 1005 passed; 2 failures (`modelPicker`,
  `theme`) reproduce on the baseline and pass in isolation, so they are
  suite-order sensitive, not from this branch.
- Each of the three fixed defects was mutation-checked: reverting the fix makes
  exactly the new assertions fail and nothing else.
- Manual: the web app was served from an earlier revision of this branch and
  driven through real turns; that run is what found the checkpoint defect
  already fixed in this branch.

One commit here is a rebase seam rather than this branch's own work:
`test(subagents): pass run_root in the dag test that arrived with the preset
config`. The preset-config change landed on `main` with a test calling
`run_dag` under the old signature, which this branch splits into `workdir` and
`run_root`. Neither side is wrong alone and the rebase is textually clean, so
the break only appears with both on one tree.

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

The override validator rejects relative paths, agent home, its
memory/skills/transcript subtrees, and any ancestor of agent home. Under a
sandbox, a directory outside the mount root is refused before it is created
rather than silently escaping. No filename in the history trees is derived from
a sub-agent's output, only from ids raven mints.

Backward compatibility: nothing on disk is migrated. A session whose transcript
predates project grouping keeps its file - `_get_session_path` falls back to an
existing `sessions/*/<id>.jsonl`, so resuming by id still continues the real
transcript instead of opening an empty one beside it. `list_sessions(channel=)`
and `find_most_recent_chat_id` now filter on the session key rather than the
parent directory, which no longer names the channel.

Known cost: each distinct working directory grows its own shadow-git repository
once a checkpoint runs there, and the cache is never evicted. Bounded by the
channel count, not the chat count. Noted in `CONTEXT.md` and the design doc.

Rollback is a revert of this squash commit; there is no configuration switch to
disable the split.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 02:51:42 +00:00
JasonJarvan
256b78b23b build: whole-repo lint + pre-commit convention (config only) (#59)
## Change description

> Whole-repo lint + pre-commit convention, CONFIG ONLY (no source
reformat in this PR). Python (ruff) and TypeScript (eslint + prettier)
share a 120-col margin via the committed pre-commit gate. This upgrades
main's existing basic ruff setup and adds the TS lint stack (none
existed on main).
>
> What this PR adds:
> - ruff: line-length 120; security rules
S101/S105/S106/S107/S506/S605/S607; policy per-file-ignores (tests +
accepted CLI deferred-imports + product asserts + N818, each commented);
ruff pinned <0.16.
> - eslint/prettier: shared base (`eslint.base.mjs` +
`prettier.config.mjs`); ui-tui extends it with React rules, bridge with
a Node-only config; hermes-ink vendor and generated RPC types excluded.
> - pre-commit: keeps main's hooks (conventional-commit,
detect-private-key, etc.), adds a top-level exclude and 4 local
eslint/prettier hooks; bumps the pre-commit dev dep.
> - 2 lint-surfaced fixes: PlannerContext import (F821) in the sentinel
runner; lower-cased file-local cron-heartbeat constants (N806).
(raven/config/raven.py's F821 was already fixed on main.)
>
> Sequencing: config only. `ruff check` is intentionally red on ~307
auto-fixables (I001/F401/F541/E701/E702); a SEPARATE reformat branch
runs `ruff --fix` + `ruff format` + eslint/prettier --fix to clear them
(100% auto-resolvable, zero manual). Enforcement (pre-commit install /
CI) turns on only after the reformat lands, so do not expect a green
tree from this PR alone.
>
> CLI-owned files (the reformat and several per-file-ignores touch
`raven/cli/*`) are under review by the CLI team. Judgment items (TS
no-explicit-any, no-unused-expressions, S101 convert-vs-keep, N818
rename, C90, mypy) are deferred to v2.

## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [x] Others

## Related issues (if there is)

> none

## Checklists

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

> config-only: `ruff check` is red on auto-fixables by design (the
reformat branch clears them); eslint/prettier configs load in both
ui-tui and bridge.

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

> Only dependency change is the dev-only pre-commit tool plus the ruff
pin; the detect-private-key hook from main is retained.

### Code review
- [x] Pull request has a descriptive title and context useful to a
reviewer
- [ ] Pull request linked to JIRA ticket when applicable

---------

Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-01 12:09:42 +08:00
0xKT
dc0fb2822c raven init 2026-06-29 00:23:07 +08:00