2026-06-28 18:17:27 +08:00
|
|
|
"""Plugin ``tools`` contribution point — manifest, registry, CLI stack,
|
|
|
|
|
render surfacing, and the EverOS ``understand_media`` tool itself.
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
from __future__ import annotations
|
|
|
|
|
|
|
|
|
|
import sys
|
|
|
|
|
import textwrap
|
|
|
|
|
import types
|
|
|
|
|
from pathlib import Path
|
|
|
|
|
|
|
|
|
|
import pytest
|
|
|
|
|
from pydantic import ValidationError
|
|
|
|
|
|
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
|
|
|
from raven.plugins import (
|
2026-06-28 18:17:27 +08:00
|
|
|
Contributes,
|
|
|
|
|
DiscoveredPlugin,
|
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
|
|
|
ManifestOrigin,
|
2026-06-28 18:17:27 +08:00
|
|
|
PluginContext,
|
|
|
|
|
PluginManifest,
|
refactor(*): finish whole-repo lint convention (#80)
## Summary
Two focused lint cleanups off the whole-repo lint convention:
**Python (ruff N818)** — rename exception classes to the `*Error` suffix
so
they satisfy the N818 naming rule, and update every reference:
`_SocketClosed`, `MultimodalUnavailable`, `PluginConflict`,
`PluginNotFound`.
Pre-stable rename with no external consumers. The matching N818
per-file-ignores
are dropped from `pyproject.toml`; the CONTEXT glossary entry and the
registry
diagram are updated in step.
**TypeScript (eslint no-explicit-any, ui-tui)** — remove `any` from the
code and
ratchet the rule to error:
- Replace `any` in 6 rpc/config generic signatures with
`unknown`/`object`. The
default type stays the record shape; the generic constraint loosens to
`object` so concrete response interfaces satisfy it without an index
signature (and `object` is not `any`, so type safety holds).
- Remove dead shift/ctrl click-modifier branches in `thinking.tsx`: the
hermes-ink `ClickEvent` never carries modifier keys, so those branches
were
unreachable (confirmed by tracing the click pipeline); drop them and the
now-unused expand-all helpers.
- Ratchet `@typescript-eslint/no-explicit-any` to error, scoped to the
ui-tui
config layer; test files stay exempt.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Run from the branch (rebased on latest `main`):
- `uv run ruff check .` — All checks passed.
- `uv run pytest tests/test_plugin_registry.py
tests/test_plugin_bootstrap.py tests/test_plugin_tools.py` — 43 passed.
- `npm run type-check` (ui-tui) — 0 errors.
- `npm run lint` (ui-tui) — 0 errors; no-explicit-any is now error with
0 violations.
- `npm test` (ui-tui) — 868 passed, 16 skipped, 0 failed.
- Full Python suite: no regressions vs the `main` baseline (the
remaining
failures are environment-only: an optional native dep not importable in
the
worktree venv, plus TTY/subprocess e2e that need a real terminal).
- [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
The exception renames are a source-visible API change, but the project
is
pre-stable and the renamed exceptions have no external consumers. The
TypeScript
changes are behavior-preserving; the removed click-modifier branches
were proven
unreachable.
## Related Issues
N/A
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-02 21:24:02 +08:00
|
|
|
PluginNotFoundError,
|
2026-06-28 18:17:27 +08:00
|
|
|
PluginRegistry,
|
|
|
|
|
ServiceLocator,
|
|
|
|
|
ToolContribution,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
# Test-module injection (mirrors test_plugin_registry.py)
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
_INJECTED_MODULES: set[str] = set()
|
|
|
|
|
|
|
|
|
|
|
2026-06-28 18:17:27 +08:00
|
|
|
def _install_test_module(name: str, attrs: dict[str, object]) -> None:
|
|
|
|
|
mod = types.ModuleType(name)
|
|
|
|
|
for k, v in attrs.items():
|
|
|
|
|
setattr(mod, k, v)
|
|
|
|
|
sys.modules[name] = mod
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
_INJECTED_MODULES.add(name)
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
|
|
|
def _cleanup_modules():
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
# Only the fakes injected above -- evicting every module a test imported
|
|
|
|
|
# also drops real ones, and a Rust extension that installs a global logger
|
|
|
|
|
# on import (lancedb, reached via everos) panics on the second import.
|
2026-06-28 18:17:27 +08:00
|
|
|
yield
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
for name in _INJECTED_MODULES:
|
|
|
|
|
sys.modules.pop(name, None)
|
|
|
|
|
_INJECTED_MODULES.clear()
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
def _discovered_with_tools(
|
|
|
|
|
plugin_id: str,
|
|
|
|
|
tools: list[tuple[str, str]],
|
|
|
|
|
) -> DiscoveredPlugin:
|
|
|
|
|
mf = PluginManifest(
|
|
|
|
|
id=plugin_id,
|
|
|
|
|
version="0.1.0",
|
|
|
|
|
contributes=Contributes(
|
|
|
|
|
tools=[ToolContribution(name=n, factory=f) for n, f in tools],
|
|
|
|
|
),
|
|
|
|
|
)
|
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
|
|
|
return DiscoveredPlugin(manifest=mf, source=ManifestOrigin.USER, location=None)
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
# Manifest
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestManifestTools:
|
|
|
|
|
def test_parses_tools_contribution(self) -> None:
|
|
|
|
|
toml = textwrap.dedent("""
|
|
|
|
|
[plugin]
|
|
|
|
|
id = "everos-memory"
|
|
|
|
|
version = "0.1.0"
|
|
|
|
|
[[plugin.contributes.tools]]
|
|
|
|
|
name = "understand_media"
|
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
|
|
|
factory = "raven_everos.tools:make_understand_media_tool"
|
2026-06-28 18:17:27 +08:00
|
|
|
""")
|
|
|
|
|
mf = PluginManifest.from_toml_str(toml)
|
|
|
|
|
assert [t.name for t in mf.contributes.tools] == ["understand_media"]
|
|
|
|
|
assert mf.contributes.tools[0].factory.endswith(":make_understand_media_tool")
|
|
|
|
|
|
|
|
|
|
def test_default_tools_empty(self) -> None:
|
|
|
|
|
mf = PluginManifest(id="p", version="0.1.0")
|
|
|
|
|
assert mf.contributes.tools == []
|
|
|
|
|
|
|
|
|
|
def test_bad_factory_ref_rejected(self) -> None:
|
|
|
|
|
with pytest.raises(ValidationError):
|
|
|
|
|
ToolContribution(name="t", factory="not-a-ref")
|
|
|
|
|
|
|
|
|
|
def test_duplicate_tool_names_rejected(self) -> None:
|
|
|
|
|
with pytest.raises(ValidationError, match="duplicate tool name"):
|
|
|
|
|
PluginManifest(
|
|
|
|
|
id="p",
|
|
|
|
|
version="0.1.0",
|
|
|
|
|
contributes=Contributes(
|
|
|
|
|
tools=[
|
|
|
|
|
ToolContribution(name="dup", factory="m:a"),
|
|
|
|
|
ToolContribution(name="dup", factory="m:b"),
|
|
|
|
|
],
|
|
|
|
|
),
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
def test_backend_and_tool_may_share_name(self) -> None:
|
|
|
|
|
# Uniqueness is per-kind; a backend and a tool named the same is fine.
|
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
|
|
|
from raven.plugins import MemoryBackendContribution
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
mf = PluginManifest(
|
|
|
|
|
id="p",
|
|
|
|
|
version="0.1.0",
|
|
|
|
|
contributes=Contributes(
|
|
|
|
|
memory_backends=[MemoryBackendContribution(name="x", factory="m:b")],
|
|
|
|
|
tools=[ToolContribution(name="x", factory="m:t")],
|
|
|
|
|
),
|
|
|
|
|
)
|
|
|
|
|
assert mf.contributes.tools[0].name == "x"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
# Registry
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestRegistryTools:
|
|
|
|
|
def test_activates_and_resolves_tool(self) -> None:
|
|
|
|
|
def fake_factory(ctx):
|
|
|
|
|
return "tool-instance"
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_a", {"make_tool": fake_factory})
|
|
|
|
|
reg = PluginRegistry()
|
|
|
|
|
reg.activate([_discovered_with_tools("alpha", [("understand_media", "_tp_tools_a:make_tool")])])
|
|
|
|
|
|
|
|
|
|
assert reg.tool_names() == ["understand_media"]
|
|
|
|
|
assert reg.tool_plugin_id("understand_media") == "alpha"
|
|
|
|
|
assert reg.get_tool_factory("understand_media") is fake_factory
|
|
|
|
|
|
|
|
|
|
def test_build_tool_invokes_factory_with_context(self, tmp_path: Path) -> None:
|
|
|
|
|
captured = {}
|
|
|
|
|
|
|
|
|
|
def fake_factory(ctx: PluginContext):
|
|
|
|
|
captured["config"] = ctx.config
|
|
|
|
|
return "built"
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_b", {"make_tool": fake_factory})
|
|
|
|
|
reg = PluginRegistry()
|
|
|
|
|
reg.activate([_discovered_with_tools("p", [("t", "_tp_tools_b:make_tool")])])
|
|
|
|
|
|
|
|
|
|
out = reg.build_tool(
|
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
|
|
|
"t",
|
|
|
|
|
config={"k": 1},
|
feat(*): add hermes as a cold-start import source (#264)
## Summary
Adds Hermes as a cold-start import source, alongside the existing Claude
Code
scanner, across three kinds of data.
**Memory files.** `MEMORY.md` and `USER.md` are discovered through the
same
profile resolution Hermes itself uses (`HERMES_HOME`, then
`active_profile`
redirecting to `<root>/profiles/<name>`). `USER.md` entries are
additionally
mirrored into the native `user_memory/profile/user.md`: six host
consumers
(Curator, Personalizer, four Sentinel producers) read that file directly
and
never see EverOS-only content. An LLM picks each entry's H2 heading;
every
failure path lands the entry under `## Notes`, which injection always
includes,
so a misclassification costs tokens rather than visibility.
**Conversations.** Sessions are enumerated by shelling out to
`hermes sessions export --dry-run`, whose listing is capped at 100 rows.
The
scanner walks time windows until every session is covered rather than
silently
importing the first 100. Only ended sessions are candidates, and
`reopen_session()` can clear `ended_at`, so the window reconciliation
documents
the resulting race in both directions instead of assuming monotonicity.
**Skills.** Provenance is classified from on-disk evidence -- the
`.bundled_manifest` name-to-md5 map, `.hub/lock.json`, and `.usage.json`
-- with
a `package_hash` byte-identical to Hermes' own `_dir_hash`, so a skill
still
matching its factory content is left alone and only user-authored or
curator-managed skills are copied into the local skill pool. Skills
never travel
as ScanResults, so the menus, the confirm line and the final summary all
state
the skill count explicitly; without it a run that installs 12 of 82
reads as
having dropped 70.
Failure isolation: `scan_all` now reports a failing scanner through an
`on_error` callback and keeps the other platforms' results, and a Hermes
run
whose conversations cannot be enumerated still returns its memory files.
Two pre-existing defects found while working here are fixed in the same
branch:
a multi-line recall hit escaped its bullet in the context segment
renderer, and
a recalled EverOS profile was rendered as a Python repr and left
uncapped.
Also in this branch, from hands-on testing of the finished flow:
- `raven import run` could never reach its interactive path. The
selectors
called questionary's synchronous `ask()` from inside `asyncio.run()`,
and
prompt_toolkit drives `Application.run()` through `asyncio.run()`, which
raises inside a running loop. No test covered it: every case passed
`--platform` and `--tier`, bypassing the selectors.
- Import outcomes now render as one block after the progress display
closes.
Printing them from `_build_and_run` sent them to this module's Console
while
onboard's live progress belongs to its themed Console, and Rich's Live
can
only hold back writes on its own console, so they landed mid-bar and
left the
bar duplicated.
- The `import run` selectors use the shared prompt style and glyphs
instead of
questionary's defaults; onboard's foreground import gains the phase
reporter
it never had, so the multi-second USER.md mirror is no longer silent
behind a
bar reading 100%.
The EverOS backend moves with it. Agent-track recall turned out to be
dead:
agent-track HYBRID fuses `agent_case` and `agent_skill` through a rerank
cross-encoder, and with no rerank provider the server refuses the
request
outright, which `recall` catches and turns into an empty list against a
file-only logger. A live 1.1.3 probe returns `RuntimeError:
owner_type='agent'
with method='hybrid' requires a rerank provider`. The adapter now reads
`capabilities.rerank` from `/health` and asks for the LLM lane only when
the
cross-encoder is genuinely absent -- always sending it would make every
correctly configured user pay an LLM call per recall, never sending it
leaves
the track dead for anyone who skipped the optional rerank role in
onboard.
That capability is only readable from everos 1.2.1, so the pin moves
1.1.3 ->
1.2.1, skipping 1.2.0 (built from a branch missing the 1.1.4 fixes,
including a
knowledge-upload path traversal). Memory endpoints move to `/api/v2`,
canonical
since 1.2.0; `/api/v1` still resolves to the same handlers but is
documented as
a legacy alias. Only everos endpoints move -- the Skill Hub and
OpenRouter
clients have their own v1 surfaces.
That upgrade also broke an assumption Raven was making. "Server running"
and
"server can recall" used to be the same statement; 1.2.1 boots with
`[llm]` alone
instead of aborting, so a misconfigured provider answers 200 and quietly
serves
less. Raven decided a role was configured by reading model + api_key out
of
`everos.toml`, which cannot see that. Capabilities are now read from
`/health` at
all three points where it matters: the memory step (right after the
server it
already starts), `raven doctor` (which had no EverOS check at all), and
`backend.start()` -- the only one of the three on the path every session
takes,
which is where an expired key actually surfaces. It follows the
precedent already
set there for native Windows and prints to stderr rather than a log
nobody reads,
but does not drop to a no-op: writes still land, and `everos cascade
backfill`
gives those rows their vectors once the provider is fixed.
The same reading makes the embedding role genuinely optional. It was not
before:
recall sends no `method`, so it took the server default of HYBRID, which
everos
refuses without an embedding provider -- skipping the role produced a
memory that
stored everything and returned nothing. The adapter now asks for KEYWORD
when no
embedding capability is reported, searching the same rows lexically
instead of
semantically, and that also rules out the rerank fallback because
KEYWORD's agent
path never reaches the cross-encoder. So the wizard stops requiring
embedding and
states what each role buys before asking for it -- llm alone gets
keyword recall,
embedding adds meaning, rerank sharpens ordering -- and skipping
embedding is
reported in colour rather than dim, because skipping rerank costs
ordering while
skipping embedding costs semantic recall entirely.
Fault and degradation are now distinguished rather than lumped together:
only a
missing llm sets doctor's exit code, and `raven doctor` names what each
unconfigured optional role costs, per role, since "optional" alone does
not help
anyone decide. The wizard also stops asking whether to enable memory at
all --
everos is the only backend, so the question framed a choice that does
not exist,
and both of its answers were described wrongly (declining was said to
use "native
Markdown memory", which does not exist: `raven/plugin/memory/` holds
only everos,
and `ContextAssembler.owns_compaction` is a hardcoded True that stops
the
consolidator from ever updating user.md). Backing out is still possible
and now
states the real consequence in colour. The memory LLM field is
pre-filled with
the user's own main model rather than a recommended id, because a
recommendation
is only reachable if their key carries it.
Two rounds of review on this branch found defects worth naming, since
each was
invisible for the same reason -- no test covered the path:
- **Skills were copied before the run's own `Proceed?` gate.** The two
early
returns that install a skills-only import sit above it, so a machine
whose only
importable data is skills had directories copied before being asked
anything.
Both paths now name the count and ask; the wizard's `Start?` gate is
further
down still, so its two call sites ask as well. Every covering test
passed
`--yes`, which is what hid it.
- **A cancelled run still ran both post-phases.** `run_import` returns
normally
once it sees the cancel file, so `raven import stop` halted the
conversation
loop and then started an LLM call per USER.md entry plus a full skill
copy.
- **Org-mirror skills were imported past a gate Hermes applies itself.**
Hermes
token-gates `_org/`: with no `.active_org` marker it prunes the whole
mirror,
and with one it descends only into the named org, so a stale mirror is
content
Hermes no longer loads. Discovery now mirrors that. Excluding `_org`
outright
would have been the opposite error -- it drops the active org's skills.
- **`doctor` and the wizard probed the default address.** Both took
`DEFAULT_EVEROS_BASE_URL` while the backend reads the configured
`base_url`, so
a user who moved everos off port 18791 was told it was not running -- by
the
checks added to make a degraded server visible.
- **An unbuilt multimodal role was reported by nobody.** The
section-to-capability
mapping had an entry both consumers skipped.
- **The USER.md progress line reached 100% before the last call.** Each
report
counted the call about to start; on a measured 9.4s run that left ~3s
sitting at
100%, the exact symptom the phase reporter was added to remove.
- **Registry-name collisions were only checked within one run**, so a
name an
earlier import or the user's own skill already claimed produced the
invisible
skill that `get(name)` never returns.
- **"All platforms" plus "run in background" could not work.** `import
run` has no
all-platforms flag, so the child reached its platform picker with
DEVNULL on
both streams and no terminal, after the wizard reported the import as
started.
It now runs in the foreground and says so.
The e2e tests this branch made dead are fixed too: identity moved to the
host, so
`config={"agent_id": ...}` is ignored, and the agent-track test wrote
under the
services default while querying the tag -- `hits` was empty, its per-hit
assertions vacuous, and an `xfail` absorbed it. The plugin manifest
moves to
1.1.0, which the upgrade SOP in this same diff asks for.
Not in scope: Codex, KimiCode and OpenClaw remain placeholders;
cold-start
import stays an EverOS-only path with no native fallback.
## Type
- [x] Feature
- [ ] Fix
## Verification
```
uv run --all-extras pytest -q 5405 passed, 30 skipped, 13 deselected
uv run ruff check . All checks passed!
uv run ruff format --check . 873 files already formatted
make check-large-files passed
```
Beyond the suite, the importer was run against a real Hermes install at
`--tier full`: memory files, conversations and skills all landed, EverOS
extracted agent cases from the imported conversations
(`quality_score=1.0` in
the server log), and a second run over the same data reported
`Submitted: 0, Skipped: 4`, confirming the checkpointing is idempotent.
The everos upgrade was verified against a live server holding real
imported
data: on 1.1.3 the agent track returns 500 and `/api/v2` returns 404; on
1.2.1
with this change the agent track returns an `agent_case` and the user
track is
unchanged at three episodes. Re-verified after killing the server and
cold
starting it, with the resolved binary printed to confirm which build
answered.
`raven doctor` and the wizard both report llm and embedding available
with
rerank absent against that server.
The suite was also run with HOME pointed at an empty directory, which is
how the
memory-probe and import-step tests were caught reading the developer's
own
configuration instead of their own fixtures. That pass also found the
test suite
waiting out `ensure_everos_server`'s 30s readiness timeout on every
machine
without a running server -- always, on CI -- which cost one file 34 of
its 35
seconds and is now stubbed.
The interactive flow was verified under a pty, comparing the two console
wirings directly, and each new assertion was mutation-tested: every
behavioural
change on this branch had its fix reverted and the covering test
confirmed red,
and only that test. Where a fix had a plausible wrong shape, that shape
was
mutated too -- excluding `_org` wholesale rather than token-gating it,
reporting
progress after the await instead of before, seeding the registry-name
check from
the pool without ordering it after the target resolution. Two of those
mutations
survived and were the more useful result: one showed a guard clause
could not
fire (`_target_for` only ever returns a path that does not exist, so
excluding it
from the pool lookup was dead code, now removed), the other showed the
wizard's
own confirmation sits below the returns it was supposed to cover.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
User-facing docs are unchanged: this adds a platform to an existing
documented
command rather than a new surface. The developer docs move with the code
--
`docs/memory-plugin-architecture.md` (the everos pin, and the upgrade
SOP now
stating that a one-way migration belongs in the release notes) and
`scripts/README.md` (two deleted scripts).
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The import writes to EverOS and to `user_memory/profile/user.md`, and
copies
skill directories into the local skill pool. EverOS has no delete
endpoint, so
an unwanted import is not undone by reverting this branch; the skill
copies and
the profile edits are plain files and can be removed by hand. Import
state
lives in `~/.raven/import_state.json` and can be deleted to start over.
Behaviour changes for existing users: the onboard wizard's import step
and
`raven import run` both look different (shared prompt style, skill
counts,
one summary block). `raven import run`'s interactive path changes from
"crashes immediately" to working. Rolling back restores the crash.
Three more, from the review round: a skills-only import now asks before
copying
(one extra prompt, skippable with `--yes`), an all-platforms import
chosen with
"run in background" runs in the foreground instead and says so, and
skills under
a stale `_org/` mirror are no longer imported -- Hermes does not load
them
either, but anyone who had them imported by an earlier build keeps them,
since
nothing here deletes.
Two consequences of the everos upgrade that operators need to know:
- **The index migration is one-way.** everos 1.2.1 migrates the LanceDB
schema
on first start and prunes older manifest versions, so once a machine has
run
this, its memory index can no longer be read by an older everos.
Reverting
the branch does not undo it.
- **A missing provider no longer aborts startup.** 1.2.1 boots with
`[llm]`
alone. A misconfigured embedding provider used to fail loudly; it now
degrades
to keyword search, and rows written in that state carry no vector until
`everos cascade backfill` is run. everos itself only logs one warning
line,
which is why the wizard, `raven doctor` and `backend.start()` all
surface it --
the last of those runs every session, so an expired key is reported
rather
than discovered.
- **Behaviour change for users who skip embedding.** Recall degrades to
keyword
matching instead of failing, and the wizard no longer stops them from
getting
there. That is the point of the change, but it means a user can now end
up with
a working memory that is measurably worse at recall than the previous
all-or-nothing setup would have allowed.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-04 20:44:07 +08:00
|
|
|
services=ServiceLocator(workspace=tmp_path, user_id="default", agent_id="default"),
|
2026-06-28 18:17:27 +08:00
|
|
|
)
|
|
|
|
|
assert out == "built"
|
|
|
|
|
assert captured["config"] == {"k": 1}
|
|
|
|
|
|
|
|
|
|
def test_tool_name_conflict_across_plugins(self) -> None:
|
|
|
|
|
def f(ctx):
|
|
|
|
|
return None
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_c", {"make_tool": f})
|
|
|
|
|
reg = PluginRegistry()
|
fix(plugins): a plugin that fails to load no longer takes every other plugin with it (#703)
## Summary
One plugin that failed to activate dropped every plugin.
`PluginRegistry.activate` raised on the first plugin whose factory would
not import (or whose contribution name collided), and
`build_plugin_registry` (`raven/core/plugin_stack.py`) answered by
returning an empty registry. A single broken user plugin therefore
silently removed research-flow, ppt-engine, design-engine, the memory
backend and the bundled playbook tools, with one stderr warning as the
only trace. Reproduced with two mock plugins under a scratch
`RAVEN_HOME`: `aa-broken` (factory raises `ImportError`) beside
`zz-good`; before this change the registry came back with `activated:
[]`, after it with `design-engine, everos-memory, playbook, ppt-engine,
zz-good` activated and `aa-broken` named as failed.
Changes:
- **Per-plugin activation** (`raven/plugins/registry.py`). Each admitted
plugin activates on its own. One that fails is rolled back whole (no
partial contribution in any table, and the `sys.path` entry
`_ensure_importable` appended for it is withdrawn), recorded as a
`PluginActivationFailure` (`activation_failures()`), and the plugins
after it still activate. In a name conflict the plugin activated first
(discovery order, by id) keeps the name and the other is recorded as
failed. A module `__getattr__` that raises something other than
`AttributeError` is now a recorded failure rather than an uncaught
crash.
- **Said to the user** (`plugin_stack.build_plugin_registry`,
`runtime.build_runtime`). Each failure is one notice naming the plugin,
its cause and the `plugins.disabled` escape, through the host's notifier
(`HostWiring.notify`), else stderr - the same channel the
missing-memory-backend notice already uses. When the configured memory
backend belongs to a plugin that failed, the memory notice names that
plugin and its cause instead of "no installed plugin provides it".
- **`raven plugins`** shows a `failed` status and the cause under the
table (the command called `activate` directly and previously crashed on
such a plugin).
- **Agents smoke check** (`raven/cli/agents_commands.py`) matched the
old log line "plugin activation failed", which no longer exists; it now
reads the shared `PLUGIN_FAILURE_MARKER`, and its test prints the notice
the real producer writes, so the two cannot drift.
- **Sub-agents inherit the host's opt-outs**
(`product_render.write_rendered`, `inherit_plugin_opt_outs`). A product
engine inherits `RAVEN_HOME`, so it scans the host's `<home>/plugins`
and the shared interpreter's entry points, but it read
`plugins.disabled` only from its own rendered config; a plugin disabled
on the host came back in every product. Every render now merges the
host's list after the product's own. The product's own engine plugin
never travels (`own_plugins=`, passed by all five launchers and the
scaffold): the PPT agent is `ppt-engine`, and a host turning it off for
its own agent is not a request to run the PPT agent without it. A
contract test reads every launcher's `write_rendered` call and requires
it to name its `*_PLUGIN_ID`.
- `CONTEXT.md` (Plugin Registry) and
`docs-site/docs/building-plugin{,.zh}.md` describe the new behaviour.
Not in this PR: the Web UI plugin list (`ext.list`) is discovery-only
and does not show a failed plugin; adding it is a wire change
(`ExtListResult`, openrpc, generated TS, the page) and is left for a
follow-up. The TUI, gateway and `raven agent` hosts show the notice
through their notifiers; the rpc stack (serve/acp) prints it to stderr,
which is also what the agents smoke check reads.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
**Rebased**: head 7cd000dbc on origin/main 8ee5ae0d8, without conflicts.
`git range-diff` shows every commit replayed unchanged. The branch's own
test files rerun at this head: 395 passed. Numbers elsewhere in this
description are from earlier heads.
Head b4d51aee8, rebased onto origin/main 6551f8259 after #698 and #708
merged. #698 conflicted in `raven/config/product_render.py` and
`tests/test_config_product_render.py`: both PRs added a function at the
same spot (`inherit_host_denials` there, `inherit_plugin_opt_outs` here)
and a call in `write_rendered`. The resolution keeps both functions and
all their tests; `write_rendered` now reads `host_config()` once and
passes it to both. #708 touches none of these files. At this head:
```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q -p no:cacheprovider
25948 passed, 109 skipped
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_config_product_render.py
44 passed
ruff check / ruff format --check / make lint-imports lint-deps lint-types / git diff --check origin/main...HEAD
check_source_language.py origin/main...HEAD / make check-commits / check-large-files
all clean
cd ui-tui && npm run lint:rpc && npm run type-check && npm test
144 files, 2106 passed
```
The earlier `TUI checks` failure (run 35834019105, head 5fc374035) was
`newInstancePicker.test.tsx > quick-selects by the number it printed`.
This PR changes nothing under `ui-tui/`; the test passed 5 of 5 runs
locally at this head and in the full ui-tui run above.
The numbers below are from the earlier heads and are kept for the
record.
```
uv run --frozen --python 3.12 --extra dev ruff check raven evolver agents plugins-dist tests scripts
All checks passed
uv run --frozen --python 3.12 --extra dev ruff format --check raven evolver agents plugins-dist tests scripts
2083 files already formatted
make lint-imports && make lint-deps && make lint-types
Contracts: 10 kept, 0 broken / No dependency issues found / All checks passed
git diff --check origin/main...HEAD
clean
COLORTERM=truecolor make coverage (full suite, head before rebasing onto 7fdf296f4)
25847 passed, 109 skipped
COVERAGE_BASE_REF=origin/main make coverage-diff
Diff coverage: 100.00% (71/71 executable changed lines)
PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
exit 0
make check-commits
pass
git merge-tree --write-tree HEAD origin/main
clean
```
After rebasing onto 7fdf296f4 (its two new commits touch none of these
files), the touched suites at this head:
```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q tests/test_plugin_*.py tests/test_core_plugin_stack.py tests/test_cli_plugin_commands.py tests/test_cli_agents_commands.py tests/test_cli_tui_commands.py tests/test_config_product_render.py tests/test_agents_*launcher*.py tests/test_everos_plugin_discovery.py tests/test_release_plugin_list.py tests/test_cli_gateway_commands.py
727 passed
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_subagent_vendored_agents.py tests/test_rpc_subagents.py tests/test_subagent_acp.py
452 passed
```
Revert-to-red, one production file restored to origin/main at a time
with the tests kept:
```
raven/plugins/registry.py -> 2 errors (plugin_stack imports PluginActivationFailure)
raven/core/plugin_stack.py -> 6 failed
raven/core/runtime.py -> 1 failed (build_runtime hands the host's notifier to the registry)
raven/config/product_render.py -> 42 failed
raven/cli/agents_commands.py -> 1 failed (smoke reds a handshake whose plugin did not load)
raven/cli/plugin_commands.py -> 1 failed (failed row and escaped cause)
agents/raven-ppt/run.py -> 2 failed (engine exemption, launcher contract)
```
Ten existing tests pinned "activation raises" (`test_plugin_registry`,
`test_plugin_bootstrap`, and the conflict tests for tools, hooks, tool
gates and session observers). They now assert the new contract instead:
the later plugin is recorded with the same reason text, the earlier one
keeps the name, and nothing of the loser is registered. Two stubs in
`test_cli_tui_commands.py` took `build_plugin_registry(cfg)` and now
accept the `notify` keyword.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- A plugin conflict used to disable all plugins; it now keeps the plugin
that activates first and skips the other with a notice. Two plugins
contributing the same name therefore run with one of them instead of
none.
- A product sub-agent now starts with the host's `plugins.disabled`
merged into its config (its own engine excepted). A plugin that was
disabled on the host but relied on inside a product stops loading there;
the remedy is to enable it on the host.
- `PluginRegistry.activate` no longer raises `PluginConflictError` /
`PluginFactoryImportError`; the only in-tree callers were
`assemble_plugin_registry` and `raven plugins`. The exception classes
stay exported.
- Security: the change only narrows what loads. A failed plugin's
directory leaves sys.path, and the inherited opt-outs can only remove
plugins from a product, never add one.
- Rollback: revert 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) <noreply@anthropic.com>
2026-09-23 22:41:21 +08:00
|
|
|
reg.activate(
|
|
|
|
|
[
|
|
|
|
|
_discovered_with_tools("one", [("dup", "_tp_tools_c:make_tool")]),
|
|
|
|
|
_discovered_with_tools("two", [("dup", "_tp_tools_c:make_tool")]),
|
|
|
|
|
]
|
|
|
|
|
)
|
|
|
|
|
assert reg.activated_ids() == ["one"]
|
|
|
|
|
assert reg.tool_plugin_id("dup") == "one"
|
|
|
|
|
[failure] = reg.activation_failures()
|
|
|
|
|
assert failure.plugin_id == "two"
|
|
|
|
|
assert "tool 'dup' contributed by both 'one' and 'two'" in failure.reason
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
def test_unknown_tool_raises(self) -> None:
|
|
|
|
|
reg = PluginRegistry()
|
refactor(*): finish whole-repo lint convention (#80)
## Summary
Two focused lint cleanups off the whole-repo lint convention:
**Python (ruff N818)** — rename exception classes to the `*Error` suffix
so
they satisfy the N818 naming rule, and update every reference:
`_SocketClosed`, `MultimodalUnavailable`, `PluginConflict`,
`PluginNotFound`.
Pre-stable rename with no external consumers. The matching N818
per-file-ignores
are dropped from `pyproject.toml`; the CONTEXT glossary entry and the
registry
diagram are updated in step.
**TypeScript (eslint no-explicit-any, ui-tui)** — remove `any` from the
code and
ratchet the rule to error:
- Replace `any` in 6 rpc/config generic signatures with
`unknown`/`object`. The
default type stays the record shape; the generic constraint loosens to
`object` so concrete response interfaces satisfy it without an index
signature (and `object` is not `any`, so type safety holds).
- Remove dead shift/ctrl click-modifier branches in `thinking.tsx`: the
hermes-ink `ClickEvent` never carries modifier keys, so those branches
were
unreachable (confirmed by tracing the click pipeline); drop them and the
now-unused expand-all helpers.
- Ratchet `@typescript-eslint/no-explicit-any` to error, scoped to the
ui-tui
config layer; test files stay exempt.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Run from the branch (rebased on latest `main`):
- `uv run ruff check .` — All checks passed.
- `uv run pytest tests/test_plugin_registry.py
tests/test_plugin_bootstrap.py tests/test_plugin_tools.py` — 43 passed.
- `npm run type-check` (ui-tui) — 0 errors.
- `npm run lint` (ui-tui) — 0 errors; no-explicit-any is now error with
0 violations.
- `npm test` (ui-tui) — 868 passed, 16 skipped, 0 failed.
- Full Python suite: no regressions vs the `main` baseline (the
remaining
failures are environment-only: an optional native dep not importable in
the
worktree venv, plus TTY/subprocess e2e that need a real terminal).
- [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
The exception renames are a source-visible API change, but the project
is
pre-stable and the renamed exceptions have no external consumers. The
TypeScript
changes are behavior-preserving; the removed click-modifier branches
were proven
unreachable.
## Related Issues
N/A
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-02 21:24:02 +08:00
|
|
|
with pytest.raises(PluginNotFoundError):
|
2026-06-28 18:17:27 +08:00
|
|
|
reg.get_tool_factory("nope")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
# CLI stack — build_plugin_tools
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestBuildPluginTools:
|
|
|
|
|
def _config(self, plugin_config: dict | None = None):
|
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
|
|
|
from raven.config.raven import PluginsConfig, RavenConfig
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
return RavenConfig(plugins=PluginsConfig(config=dict(plugin_config or {})))
|
|
|
|
|
|
|
|
|
|
def test_builds_tools_from_registry(self, tmp_path: Path) -> None:
|
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
|
|
|
from raven.core.plugin_stack import build_plugin_tools
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
seen = {}
|
|
|
|
|
|
|
|
|
|
def fake_factory(ctx):
|
|
|
|
|
seen["config"] = ctx.config
|
|
|
|
|
return f"tool::{ctx.config.get('flag')}"
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_d", {"make_tool": fake_factory})
|
|
|
|
|
reg = PluginRegistry()
|
|
|
|
|
reg.activate([_discovered_with_tools("myplugin", [("t1", "_tp_tools_d:make_tool")])])
|
|
|
|
|
|
|
|
|
|
cfg = self._config({"myplugin": {"flag": "on"}})
|
|
|
|
|
tools = build_plugin_tools(tmp_path, cfg, registry=reg)
|
|
|
|
|
assert tools == ["tool::on"]
|
|
|
|
|
assert seen["config"] == {"flag": "on"}
|
|
|
|
|
|
|
|
|
|
def test_empty_when_no_tools(self, tmp_path: Path) -> None:
|
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
|
|
|
from raven.core.plugin_stack import build_plugin_tools
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
assert build_plugin_tools(tmp_path, self._config(), registry=PluginRegistry()) == []
|
|
|
|
|
|
|
|
|
|
def test_failing_factory_is_skipped(self, tmp_path: Path) -> None:
|
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
|
|
|
from raven.core.plugin_stack import build_plugin_tools
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
def boom(ctx):
|
|
|
|
|
raise RuntimeError("nope")
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_e", {"make_tool": boom})
|
|
|
|
|
reg = PluginRegistry()
|
|
|
|
|
reg.activate([_discovered_with_tools("p", [("t", "_tp_tools_e:make_tool")])])
|
|
|
|
|
# One bad tool doesn't crash the build — it's logged + skipped.
|
|
|
|
|
assert build_plugin_tools(tmp_path, self._config(), registry=reg) == []
|
|
|
|
|
|
|
|
|
|
def test_none_factory_is_skipped(self, tmp_path: Path) -> None:
|
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
|
|
|
from raven.core.plugin_stack import build_plugin_tools
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
# A factory may return None to decline contribution (e.g. an
|
|
|
|
|
# optional dependency is absent) — skipped without error.
|
|
|
|
|
def opt_out(ctx):
|
|
|
|
|
return None
|
|
|
|
|
|
|
|
|
|
_install_test_module("_tp_tools_f", {"make_tool": opt_out})
|
|
|
|
|
reg = PluginRegistry()
|
|
|
|
|
reg.activate([_discovered_with_tools("p", [("t", "_tp_tools_f:make_tool")])])
|
|
|
|
|
assert build_plugin_tools(tmp_path, self._config(), registry=reg) == []
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
# render.build_user_content — attachment surfacing
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestRenderAttachments:
|
|
|
|
|
def test_non_image_surfaced_as_note(self, tmp_path: Path) -> None:
|
|
|
|
|
from raven.context_engine.segments import render
|
|
|
|
|
|
|
|
|
|
pdf = tmp_path / "report.pdf"
|
|
|
|
|
pdf.write_bytes(b"%PDF-1.4 data")
|
chore(*): merge upstream v0.1.11 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.11 becomes a real ancestor: the next sync then starts from
v0.1.11 instead of the July fork point, and the eventual contribution back to
GitHub can tell our commits from the upstream ones it already has.
Notable conflict resolutions, 19 hunks over 14 files:
* providers/litellm_provider.py takes upstream's wire_model delegation. Both
sides had fixed the same gateway-prefix bug; upstream moved the logic into
providers/wire.py and deleted _canonicalize_explicit_prefix, so keeping our
call would reference a method that no longer exists.
* cli/onboard_commands.py takes upstream's three-way file split. Our only
change to that file was _NON_CREDENTIAL_CHANNEL_FIELDS, ported to its new
home in cli/onboard_channels.py.
* agent/loop/main.py keeps our stream reconnect loop and grafts upstream's
terminal error-delta handling into it; takes upstream's _route_result_images
helper, which also covers the no-vision case our inline version did not, and
keeps our read_skill/use_skill reporting; takes upstream's ordering that
routes before assembly, since assembly decides whether an attachment is
inlined as a picture, while keeping our per-session model override.
* agent/subagent/manager.py keeps our backend dispatch and spawn history, and
threads the provider/model pair spawn snapshots into backend.run so a live
/model switch reaches subagents. The SubagentBackend protocol gained the
pair as optional keywords, travelling per call for the same reason workspace
already does.
Three breakages git merged cleanly and never flagged:
* web_rpc/methods_config.py imported six EverOS symbols from onboard_commands,
which upstream moved to onboard_everos.
* tui_rpc/methods/turn.py passed a single directory to _resolve_path, whose
third parameter we had changed to a tuple. Left as it was, an attachment was
dropped in silence whenever restrict_to_workspace is on.
* config/schema.py carried a second configuredness rule next to the one
upstream routes through providers.auth, so routing bypassed the
endpoints-first check and read a flat key that no request would use. It now
delegates, with include_external for parity with list_providers.
Verification: uv run ruff check passes; uv run pytest reports 6823 passed and
4 failed. All four fail on origin/main as well (one theme assertion, three
channel QR cases) and are left for a separate fix. Upstream's own 53 changed
test files pass, and so do our 85, which is what pins both sides' semantics
through these resolutions.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 23:59:07 +08:00
|
|
|
# Named explicitly: the hint is only emitted when a description tool
|
|
|
|
|
# is actually registered, and it is absent on a default install.
|
|
|
|
|
out = render.build_user_content("summarize this", [str(pdf)], describe_tool="understand_media")
|
2026-06-28 18:17:27 +08:00
|
|
|
assert isinstance(out, str)
|
|
|
|
|
assert "report.pdf" in out
|
|
|
|
|
assert "understand_media" in out
|
chore(*): merge upstream v0.1.11 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.11 becomes a real ancestor: the next sync then starts from
v0.1.11 instead of the July fork point, and the eventual contribution back to
GitHub can tell our commits from the upstream ones it already has.
Notable conflict resolutions, 19 hunks over 14 files:
* providers/litellm_provider.py takes upstream's wire_model delegation. Both
sides had fixed the same gateway-prefix bug; upstream moved the logic into
providers/wire.py and deleted _canonicalize_explicit_prefix, so keeping our
call would reference a method that no longer exists.
* cli/onboard_commands.py takes upstream's three-way file split. Our only
change to that file was _NON_CREDENTIAL_CHANNEL_FIELDS, ported to its new
home in cli/onboard_channels.py.
* agent/loop/main.py keeps our stream reconnect loop and grafts upstream's
terminal error-delta handling into it; takes upstream's _route_result_images
helper, which also covers the no-vision case our inline version did not, and
keeps our read_skill/use_skill reporting; takes upstream's ordering that
routes before assembly, since assembly decides whether an attachment is
inlined as a picture, while keeping our per-session model override.
* agent/subagent/manager.py keeps our backend dispatch and spawn history, and
threads the provider/model pair spawn snapshots into backend.run so a live
/model switch reaches subagents. The SubagentBackend protocol gained the
pair as optional keywords, travelling per call for the same reason workspace
already does.
Three breakages git merged cleanly and never flagged:
* web_rpc/methods_config.py imported six EverOS symbols from onboard_commands,
which upstream moved to onboard_everos.
* tui_rpc/methods/turn.py passed a single directory to _resolve_path, whose
third parameter we had changed to a tuple. Left as it was, an attachment was
dropped in silence whenever restrict_to_workspace is on.
* config/schema.py carried a second configuredness rule next to the one
upstream routes through providers.auth, so routing bypassed the
endpoints-first check and read a flat key that no request would use. It now
delegates, with include_external for parity with list_providers.
Verification: uv run ruff check passes; uv run pytest reports 6823 passed and
4 failed. All four fail on origin/main as well (one theme assertion, three
channel QR cases) and are left for a separate fix. Upstream's own 53 changed
test files pass, and so do our 85, which is what pins both sides' semantics
through these resolutions.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 23:59:07 +08:00
|
|
|
|
|
|
|
|
bare = render.build_user_content("summarize this", [str(pdf)])
|
|
|
|
|
assert "report.pdf" in bare and f"(path: {pdf})" in bare
|
|
|
|
|
assert "understand_media" not in bare
|
2026-06-28 18:17:27 +08:00
|
|
|
assert "summarize this" in out
|
|
|
|
|
|
|
|
|
|
def test_image_inlined_as_block(self, tmp_path: Path) -> None:
|
|
|
|
|
import base64 as _b64
|
|
|
|
|
|
|
|
|
|
from raven.context_engine.segments import render
|
|
|
|
|
|
|
|
|
|
png = tmp_path / "a.png"
|
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
|
|
|
png.write_bytes(
|
|
|
|
|
_b64.b64decode(
|
|
|
|
|
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
|
|
|
|
|
)
|
|
|
|
|
)
|
2026-06-28 18:17:27 +08:00
|
|
|
out = render.build_user_content("look", [str(png)])
|
|
|
|
|
assert isinstance(out, list)
|
|
|
|
|
assert out[0]["type"] == "image_url"
|
feat(tools): read images with read_file, and fix four silent type-check bugs (#251)
## Summary
`read_file` could not read images: it called
`read_text(encoding="utf-8")`, so a PNG raised `UnicodeDecodeError` on
byte 0. Raven has supported image *understanding* since its first
commit, but only on the inbound path (an IM attachment goes into a
`user` message, which every provider accepts). The path an agent needs
-- looking at a file on disk -- puts the image in a **tool result**, and
that is where it gets hard: OpenAI's Chat Completions types
`role:"tool"` content as `string | ChatCompletionContentPartText[]`, so
an image has nowhere to go at the schema level.
This branch adds that capability, and fixes four pre-existing defects
found on the way there. Nineteen commits, each independently reviewable;
they read best oldest-first.
### Pre-existing bugs (independent of the feature)
| Commit | Defect |
|---|---|
| `fix(utils)` | Image tokens were counted as the length of the base64
data URI. Measured on a 2.9MB PNG: **2,813,577 estimated vs ~1,300
real**, over by ~2168x, and the factor grows linearly with file size.
This starves the history budget and can trip emergency shrinking on a
prompt that would have fit. |
| `fix(providers)` | The Responses converter ended with
`json.dumps(content)` for any non-string tool result, so a multimodal
result reached the model as its own base64 rendered as prose. Nothing
raised. |
| `fix(*)` (MCP) | Same shape, different call site: the MCP wrapper
ended with `str(block)`, and `str()` on a pydantic model is its repr --
so an MCP tool returning `ImageContent` put `type='image'
data='iVBORw0KGgo...'` into the prompt. Live today for any MCP server
that returns a screenshot. |
| `feat(agent)` (persistence) | `_save_turn` guarded truncation with `if
role == "tool" and isinstance(content, str)`, and the branch below it
was `elif role == "user"`. A list-shaped tool result matched neither, so
it was persisted verbatim -- the 16,000-char cap never applied. |
All four are the same failure mode: **a type check standing in for a
capability check**. `isinstance(x, str)`, `json.dumps`, `str()` each
answer "can I stringify this" when the question was "what is this" --
and they answer wrong silently as soon as the type widens. The
persistence one is the only defect here that cannot be reverted: code
can be changed back, bytes already written to session JSONL cannot.
### How images travel
- **Detection** is by magic bytes, not extension, so a PNG named `.txt`
is handled as an image and a `.png` full of text is not.
- **Preprocessing** clears three independent limits, because exceeding
any one gets the image rejected or silently altered: 2000px per side,
4.5MB of base64 (under the 5MB per-image cap Bedrock and Vertex AI
enforce -- one payload per turn may go to any target, so it must satisfy
the lowest bound), and 1568 patch tokens. Both size limits are checked
rather than just the long edge: the docs are explicit that "Images
larger than either limit are downscaled", so passing the pixel check
alone still leaves an image the server resizes, which makes any local
token estimate wrong.
- **Delivery** depends on the transport, not the model.
`supports_image_tool_result` returns True only for measured targets
(`anthropic`, `vertex_ai`, `bedrock`) and, behind a gateway, only for
measured model families (`anthropic/claude-`, `google/gemini-`);
everything else takes a placeholder-plus-attachment path, the shape
OpenClaw uses against Chat Completions endpoints. The list is
deliberately a whitelist of what was probed rather than a blacklist of
known failures, because the dangerous failure is silent:
`openrouter/openai/gpt-4.1-mini` accepts the request, discards the image
and confabulates a colour, while the same image in a user message gets a
correct answer from it. The gateway key is a family prefix rather than
the creator segment for the same reason --
`openrouter/google/gemma-3-27b-it` is served only by third-party
OpenAI-compatible hosts, two of which reject the payload with a 422
while two accept it, and OpenRouter picks the host per request. Absences
mean unprobed, not known-bad: `gemini` almost certainly works (LiteLLM
routes it through the same transform as the listed `vertex_ai`) but
there was no direct key to prove it.
`ProviderSpec.image_tool_result_override` lets a deployment opt in.
- **Lifetime** is one turn. Images degrade to a placeholder on the way
to the session, so they are never replayed on resume or re-sent to the
model in a later turn. The text kept alongside names the file path, so
the model can re-read an image rather than only learning that one
existed. Inbound IM images now do the same, mirroring what the non-image
branch of that loop has always done for PDFs.
### Design notes for review
- **`ToolOutput` stays a `str` subclass.** Its docstring already
explains why -- the sentinel executor, subagent manager, context curator
and tracing all put the registry's return value straight into a message
or preview. `blocks` rides along as an attribute, so those four callers
are untouched and need no knowledge that multimodal results exist. This
makes `model_text` a contract rather than a courtesy: it is what
text-only transports send and what lands in the transcript, so a tool
setting `blocks` puts the metadata and the path in it, never "see the
image above".
- **Graceful degradation is built into the type.** A provider that
ignores `blocks` still gets a self-sufficient text result naming the
file, rather than nothing.
- **The content-part shape is written in one place.** It was
hand-written in five and re-derived in nine, with nothing verifying any
of them -- a mistyped key (`imageURL`) would drop the picture with a
clean log. Construction now goes through `image_block()` /
`text_block()`, and a test greps the tree to keep the literal from
coming back.
- **TypedDicts type what Raven produces, not what it reads.** Inbound
content legitimately carries parts the union does not model (an
Anthropic part with `cache_control`, an MCP audio block, a future
extension), and pass-through code would otherwise become a type error
for behaving correctly. Read-side helpers keep taking `Any` and checking
shape at runtime; a test pins that permissiveness. Worth stating
plainly: CI runs no type checker, so these annotations gate nothing on
merge -- they document the contract and give an editor language server
something to check.
- **Security posture is unchanged in kind.** `wrap_untrusted_blocks`
fences text parts and leaves image bytes untouched, because a text
boundary cannot contain pixels and rewriting the bytes would corrupt the
picture. Instructions rendered *into* an image stay unfenced; the
defense for those is the one that already covers text -- privileged
actions are gated by policy regardless of what the model just looked at.
This matches OpenClaw and Claude Code, neither of which tracks taint
from an image to a later action.
- **Pillow is pinned directly.** It already arrives via
`everos[multimodal]` -> `everalgo-parser`, but that is a three-hop
transitive path, so it is pinned for the same reason `tiktoken` already
is.
### Deliberately not included
Terminal rendering of images (needs the Kitty/iTerm2 graphics protocol
and would hit the 1 MiB JSON-RPC frame cap; the goal here is images
reaching the model, not the eye), a structured `details` channel for
program-readable tool metadata (nothing needs it yet --
`CallToolResult.structuredContent` is the shape to copy when something
does), and native PDF, audio or video input.
### Fixed during review
Three defects found in review, all on the fallback path, plus one
recovery mechanism added on top:
| Item | Defect |
|---|---|
| R1 | `read_file` on a `.svg` regressed from returning the text to
returning an error: the extension guess sent XML into the image branch,
Pillow could not decode it, and nothing fell back to the text path. |
| R2 | The image carrier message was appended inside the per-tool-call
loop, so a batch whose non-last call returned an image put a `user`
message between two tool results. Measured: gpt-4o returns 400,
Anthropic accepts it, so it fires only on the transport that actually
takes this path. |
| R3 | The capability verdict was cached from `self.model` while the
turn ran on `effective_model`, which the router selects per turn. A
wrong `True` is the silent image loss the whitelist exists to prevent. |
| R5 | The carrier message persisted as a user turn holding `[image]`,
which reads on resume and in export as something the user sent. Filtered
where the turn's message list is finalized, upstream of persistence,
`after_turn` extraction and `backend.store` alike. |
| N1 | The gateway whitelist keyed on the creator segment, admitting
routes served by unmeasured third-party hosts. Narrowed to measured
family prefixes. |
`ErrorClassification` gained a fourth flag so a refused image is
recoverable rather than fatal: classify, move the picture to a user
message, retry the iteration once, cache the verdict per model. Worth
stating the limit plainly -- this heals a wrong guess only when the
endpoint says so. A silent drop stays undetectable, which is why the
whitelist is the primary defence and the retry is the backstop.
## Type
- [x] Fix
- [x] Feature
- [x] Refactor
## Verification
Commands run:
```
uv run --extra dev ruff check raven/ tests/ # All checks passed
uv run --extra dev ruff format --check raven/ tests/
uv run --extra dev pytest tests/ -q # 23 failed, 5036 passed, 30 skipped
make check-commits # clean
make check-large-files # clean
```
The 23 failures are pre-existing on `main` and unrelated
(`test_sandbox_debug_server.py`, `test_cli_theme.py`). Verified by
running the suite in a clean worktree at `origin/main` and diffing
failing test IDs: **no test fails on this branch that passes on
`main`**. The baseline worktree showed three extra failures in
`test_channels_errors.py`, which are an artifact of `slack_sdk` being
absent from that fresh environment, not a fix from this branch.
65 tests in `tests/test_read_file_image.py`, no skips, no xfail, no
weakened assertions. One pre-existing test changed on purpose:
`test_image_inlined_as_block` pinned the old user-content text block
exactly, and now pins the new shape plus asserts the path and re-read
hint are present.
Every commit was checked to import cleanly on its own, since the series
is meant to be read commit by commit.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Two surfaces, both updated: `read_file`'s tool description, and
`TOOLS.md` (the workspace file for non-obvious tool constraints, loaded
into the system prompt) which now documents content-based detection,
downscaling, the one-turn lifetime, and the follow-up-message delivery
path. Checked that no other doc enumerates tools -- neither README nor
README.zh-CN mentions `read_file`.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: a tool returning `str` behaves exactly as
before, and `read_file` on a text file is unchanged. `blocks` is
additive and only `read_file` and the MCP wrapper set it. The registry
keeps its 4-argument `add_tool_result` call for text results so no
existing caller or test double sees a signature change.
Rollback: reverting the branch restores prior behavior. The one
asymmetry worth naming is the persistence fix -- if the block-carrying
commit had landed without it, session JSONL written in between would
contain base64 permanently. They are in the same commit for that reason.
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-07-31 21:57:41 +08:00
|
|
|
assert out[0]["image_url"]["url"].startswith("data:image/png;base64,")
|
|
|
|
|
# The user's own text comes first, then the path. The base64 survives
|
|
|
|
|
# only this turn (the session keeps a placeholder), so the path is what
|
|
|
|
|
# lets a later turn re-read the picture.
|
|
|
|
|
text_block = out[-1]["text"]
|
|
|
|
|
assert text_block.startswith("look\n\n")
|
|
|
|
|
assert f"(path: {png})" in text_block
|
|
|
|
|
assert "read_file" in text_block
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
def test_mixed_image_and_doc(self, tmp_path: Path) -> None:
|
|
|
|
|
import base64 as _b64
|
|
|
|
|
|
|
|
|
|
from raven.context_engine.segments import render
|
|
|
|
|
|
|
|
|
|
png = tmp_path / "a.png"
|
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
|
|
|
png.write_bytes(
|
|
|
|
|
_b64.b64decode(
|
|
|
|
|
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
|
|
|
|
|
)
|
|
|
|
|
)
|
2026-06-28 18:17:27 +08:00
|
|
|
pdf = tmp_path / "d.pdf"
|
|
|
|
|
pdf.write_bytes(b"%PDF-1.4")
|
chore(*): merge upstream v0.1.11 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.11 becomes a real ancestor: the next sync then starts from
v0.1.11 instead of the July fork point, and the eventual contribution back to
GitHub can tell our commits from the upstream ones it already has.
Notable conflict resolutions, 19 hunks over 14 files:
* providers/litellm_provider.py takes upstream's wire_model delegation. Both
sides had fixed the same gateway-prefix bug; upstream moved the logic into
providers/wire.py and deleted _canonicalize_explicit_prefix, so keeping our
call would reference a method that no longer exists.
* cli/onboard_commands.py takes upstream's three-way file split. Our only
change to that file was _NON_CREDENTIAL_CHANNEL_FIELDS, ported to its new
home in cli/onboard_channels.py.
* agent/loop/main.py keeps our stream reconnect loop and grafts upstream's
terminal error-delta handling into it; takes upstream's _route_result_images
helper, which also covers the no-vision case our inline version did not, and
keeps our read_skill/use_skill reporting; takes upstream's ordering that
routes before assembly, since assembly decides whether an attachment is
inlined as a picture, while keeping our per-session model override.
* agent/subagent/manager.py keeps our backend dispatch and spawn history, and
threads the provider/model pair spawn snapshots into backend.run so a live
/model switch reaches subagents. The SubagentBackend protocol gained the
pair as optional keywords, travelling per call for the same reason workspace
already does.
Three breakages git merged cleanly and never flagged:
* web_rpc/methods_config.py imported six EverOS symbols from onboard_commands,
which upstream moved to onboard_everos.
* tui_rpc/methods/turn.py passed a single directory to _resolve_path, whose
third parameter we had changed to a tuple. Left as it was, an attachment was
dropped in silence whenever restrict_to_workspace is on.
* config/schema.py carried a second configuredness rule next to the one
upstream routes through providers.auth, so routing bypassed the
endpoints-first check and read a flat key that no request would use. It now
delegates, with include_external for parity with list_providers.
Verification: uv run ruff check passes; uv run pytest reports 6823 passed and
4 failed. All four fail on origin/main as well (one theme assertion, three
channel QR cases) and are left for a separate fix. Upstream's own 53 changed
test files pass, and so do our 85, which is what pins both sides' semantics
through these resolutions.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 23:59:07 +08:00
|
|
|
out = render.build_user_content("q", [str(png), str(pdf)], describe_tool="understand_media")
|
2026-06-28 18:17:27 +08:00
|
|
|
assert isinstance(out, list)
|
|
|
|
|
assert out[0]["type"] == "image_url"
|
|
|
|
|
text_block = out[-1]["text"]
|
|
|
|
|
assert "d.pdf" in text_block and "understand_media" in text_block
|
|
|
|
|
|
|
|
|
|
def test_no_media_returns_text(self) -> None:
|
|
|
|
|
from raven.context_engine.segments import render
|
|
|
|
|
|
|
|
|
|
assert render.build_user_content("hi", None) == "hi"
|
|
|
|
|
|
chore(*): merge upstream v0.1.11 into the gitlab trunk
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.11 becomes a real ancestor: the next sync then starts from
v0.1.11 instead of the July fork point, and the eventual contribution back to
GitHub can tell our commits from the upstream ones it already has.
Notable conflict resolutions, 19 hunks over 14 files:
* providers/litellm_provider.py takes upstream's wire_model delegation. Both
sides had fixed the same gateway-prefix bug; upstream moved the logic into
providers/wire.py and deleted _canonicalize_explicit_prefix, so keeping our
call would reference a method that no longer exists.
* cli/onboard_commands.py takes upstream's three-way file split. Our only
change to that file was _NON_CREDENTIAL_CHANNEL_FIELDS, ported to its new
home in cli/onboard_channels.py.
* agent/loop/main.py keeps our stream reconnect loop and grafts upstream's
terminal error-delta handling into it; takes upstream's _route_result_images
helper, which also covers the no-vision case our inline version did not, and
keeps our read_skill/use_skill reporting; takes upstream's ordering that
routes before assembly, since assembly decides whether an attachment is
inlined as a picture, while keeping our per-session model override.
* agent/subagent/manager.py keeps our backend dispatch and spawn history, and
threads the provider/model pair spawn snapshots into backend.run so a live
/model switch reaches subagents. The SubagentBackend protocol gained the
pair as optional keywords, travelling per call for the same reason workspace
already does.
Three breakages git merged cleanly and never flagged:
* web_rpc/methods_config.py imported six EverOS symbols from onboard_commands,
which upstream moved to onboard_everos.
* tui_rpc/methods/turn.py passed a single directory to _resolve_path, whose
third parameter we had changed to a tuple. Left as it was, an attachment was
dropped in silence whenever restrict_to_workspace is on.
* config/schema.py carried a second configuredness rule next to the one
upstream routes through providers.auth, so routing bypassed the
endpoints-first check and read a flat key that no request would use. It now
delegates, with include_external for parity with list_providers.
Verification: uv run ruff check passes; uv run pytest reports 6823 passed and
4 failed. All four fail on origin/main as well (one theme assertion, three
channel QR cases) and are left for a separate fix. Upstream's own 53 changed
test files pass, and so do our 85, which is what pins both sides' semantics
through these resolutions.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-12 23:59:07 +08:00
|
|
|
def test_image_becomes_a_note_when_the_model_cannot_see(self, tmp_path: Path) -> None:
|
|
|
|
|
"""A text-only model must be told the picture exists and how to read it.
|
|
|
|
|
|
|
|
|
|
Inlining it instead is the one outcome with no recovery: the endpoint
|
|
|
|
|
either rejects the request or drops the image and answers from the text
|
|
|
|
|
alone, which reads as a correct reply built on nothing.
|
|
|
|
|
"""
|
|
|
|
|
import base64 as _b64
|
|
|
|
|
|
|
|
|
|
from raven.context_engine.segments import render
|
|
|
|
|
|
|
|
|
|
png = tmp_path / "a.png"
|
|
|
|
|
png.write_bytes(
|
|
|
|
|
_b64.b64decode(
|
|
|
|
|
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
|
|
|
|
|
)
|
|
|
|
|
)
|
|
|
|
|
out = render.build_user_content("look", [str(png)], can_see_images=False, describe_tool="understand_media")
|
|
|
|
|
|
|
|
|
|
assert isinstance(out, str)
|
|
|
|
|
assert "base64" not in out
|
|
|
|
|
assert f"(path: {png})" in out
|
|
|
|
|
assert "understand_media" in out
|
|
|
|
|
assert out.startswith("look\n\n")
|
|
|
|
|
|
feat(tools): read images with read_file, and fix four silent type-check bugs (#251)
## Summary
`read_file` could not read images: it called
`read_text(encoding="utf-8")`, so a PNG raised `UnicodeDecodeError` on
byte 0. Raven has supported image *understanding* since its first
commit, but only on the inbound path (an IM attachment goes into a
`user` message, which every provider accepts). The path an agent needs
-- looking at a file on disk -- puts the image in a **tool result**, and
that is where it gets hard: OpenAI's Chat Completions types
`role:"tool"` content as `string | ChatCompletionContentPartText[]`, so
an image has nowhere to go at the schema level.
This branch adds that capability, and fixes four pre-existing defects
found on the way there. Nineteen commits, each independently reviewable;
they read best oldest-first.
### Pre-existing bugs (independent of the feature)
| Commit | Defect |
|---|---|
| `fix(utils)` | Image tokens were counted as the length of the base64
data URI. Measured on a 2.9MB PNG: **2,813,577 estimated vs ~1,300
real**, over by ~2168x, and the factor grows linearly with file size.
This starves the history budget and can trip emergency shrinking on a
prompt that would have fit. |
| `fix(providers)` | The Responses converter ended with
`json.dumps(content)` for any non-string tool result, so a multimodal
result reached the model as its own base64 rendered as prose. Nothing
raised. |
| `fix(*)` (MCP) | Same shape, different call site: the MCP wrapper
ended with `str(block)`, and `str()` on a pydantic model is its repr --
so an MCP tool returning `ImageContent` put `type='image'
data='iVBORw0KGgo...'` into the prompt. Live today for any MCP server
that returns a screenshot. |
| `feat(agent)` (persistence) | `_save_turn` guarded truncation with `if
role == "tool" and isinstance(content, str)`, and the branch below it
was `elif role == "user"`. A list-shaped tool result matched neither, so
it was persisted verbatim -- the 16,000-char cap never applied. |
All four are the same failure mode: **a type check standing in for a
capability check**. `isinstance(x, str)`, `json.dumps`, `str()` each
answer "can I stringify this" when the question was "what is this" --
and they answer wrong silently as soon as the type widens. The
persistence one is the only defect here that cannot be reverted: code
can be changed back, bytes already written to session JSONL cannot.
### How images travel
- **Detection** is by magic bytes, not extension, so a PNG named `.txt`
is handled as an image and a `.png` full of text is not.
- **Preprocessing** clears three independent limits, because exceeding
any one gets the image rejected or silently altered: 2000px per side,
4.5MB of base64 (under the 5MB per-image cap Bedrock and Vertex AI
enforce -- one payload per turn may go to any target, so it must satisfy
the lowest bound), and 1568 patch tokens. Both size limits are checked
rather than just the long edge: the docs are explicit that "Images
larger than either limit are downscaled", so passing the pixel check
alone still leaves an image the server resizes, which makes any local
token estimate wrong.
- **Delivery** depends on the transport, not the model.
`supports_image_tool_result` returns True only for measured targets
(`anthropic`, `vertex_ai`, `bedrock`) and, behind a gateway, only for
measured model families (`anthropic/claude-`, `google/gemini-`);
everything else takes a placeholder-plus-attachment path, the shape
OpenClaw uses against Chat Completions endpoints. The list is
deliberately a whitelist of what was probed rather than a blacklist of
known failures, because the dangerous failure is silent:
`openrouter/openai/gpt-4.1-mini` accepts the request, discards the image
and confabulates a colour, while the same image in a user message gets a
correct answer from it. The gateway key is a family prefix rather than
the creator segment for the same reason --
`openrouter/google/gemma-3-27b-it` is served only by third-party
OpenAI-compatible hosts, two of which reject the payload with a 422
while two accept it, and OpenRouter picks the host per request. Absences
mean unprobed, not known-bad: `gemini` almost certainly works (LiteLLM
routes it through the same transform as the listed `vertex_ai`) but
there was no direct key to prove it.
`ProviderSpec.image_tool_result_override` lets a deployment opt in.
- **Lifetime** is one turn. Images degrade to a placeholder on the way
to the session, so they are never replayed on resume or re-sent to the
model in a later turn. The text kept alongside names the file path, so
the model can re-read an image rather than only learning that one
existed. Inbound IM images now do the same, mirroring what the non-image
branch of that loop has always done for PDFs.
### Design notes for review
- **`ToolOutput` stays a `str` subclass.** Its docstring already
explains why -- the sentinel executor, subagent manager, context curator
and tracing all put the registry's return value straight into a message
or preview. `blocks` rides along as an attribute, so those four callers
are untouched and need no knowledge that multimodal results exist. This
makes `model_text` a contract rather than a courtesy: it is what
text-only transports send and what lands in the transcript, so a tool
setting `blocks` puts the metadata and the path in it, never "see the
image above".
- **Graceful degradation is built into the type.** A provider that
ignores `blocks` still gets a self-sufficient text result naming the
file, rather than nothing.
- **The content-part shape is written in one place.** It was
hand-written in five and re-derived in nine, with nothing verifying any
of them -- a mistyped key (`imageURL`) would drop the picture with a
clean log. Construction now goes through `image_block()` /
`text_block()`, and a test greps the tree to keep the literal from
coming back.
- **TypedDicts type what Raven produces, not what it reads.** Inbound
content legitimately carries parts the union does not model (an
Anthropic part with `cache_control`, an MCP audio block, a future
extension), and pass-through code would otherwise become a type error
for behaving correctly. Read-side helpers keep taking `Any` and checking
shape at runtime; a test pins that permissiveness. Worth stating
plainly: CI runs no type checker, so these annotations gate nothing on
merge -- they document the contract and give an editor language server
something to check.
- **Security posture is unchanged in kind.** `wrap_untrusted_blocks`
fences text parts and leaves image bytes untouched, because a text
boundary cannot contain pixels and rewriting the bytes would corrupt the
picture. Instructions rendered *into* an image stay unfenced; the
defense for those is the one that already covers text -- privileged
actions are gated by policy regardless of what the model just looked at.
This matches OpenClaw and Claude Code, neither of which tracks taint
from an image to a later action.
- **Pillow is pinned directly.** It already arrives via
`everos[multimodal]` -> `everalgo-parser`, but that is a three-hop
transitive path, so it is pinned for the same reason `tiktoken` already
is.
### Deliberately not included
Terminal rendering of images (needs the Kitty/iTerm2 graphics protocol
and would hit the 1 MiB JSON-RPC frame cap; the goal here is images
reaching the model, not the eye), a structured `details` channel for
program-readable tool metadata (nothing needs it yet --
`CallToolResult.structuredContent` is the shape to copy when something
does), and native PDF, audio or video input.
### Fixed during review
Three defects found in review, all on the fallback path, plus one
recovery mechanism added on top:
| Item | Defect |
|---|---|
| R1 | `read_file` on a `.svg` regressed from returning the text to
returning an error: the extension guess sent XML into the image branch,
Pillow could not decode it, and nothing fell back to the text path. |
| R2 | The image carrier message was appended inside the per-tool-call
loop, so a batch whose non-last call returned an image put a `user`
message between two tool results. Measured: gpt-4o returns 400,
Anthropic accepts it, so it fires only on the transport that actually
takes this path. |
| R3 | The capability verdict was cached from `self.model` while the
turn ran on `effective_model`, which the router selects per turn. A
wrong `True` is the silent image loss the whitelist exists to prevent. |
| R5 | The carrier message persisted as a user turn holding `[image]`,
which reads on resume and in export as something the user sent. Filtered
where the turn's message list is finalized, upstream of persistence,
`after_turn` extraction and `backend.store` alike. |
| N1 | The gateway whitelist keyed on the creator segment, admitting
routes served by unmeasured third-party hosts. Narrowed to measured
family prefixes. |
`ErrorClassification` gained a fourth flag so a refused image is
recoverable rather than fatal: classify, move the picture to a user
message, retry the iteration once, cache the verdict per model. Worth
stating the limit plainly -- this heals a wrong guess only when the
endpoint says so. A silent drop stays undetectable, which is why the
whitelist is the primary defence and the retry is the backstop.
## Type
- [x] Fix
- [x] Feature
- [x] Refactor
## Verification
Commands run:
```
uv run --extra dev ruff check raven/ tests/ # All checks passed
uv run --extra dev ruff format --check raven/ tests/
uv run --extra dev pytest tests/ -q # 23 failed, 5036 passed, 30 skipped
make check-commits # clean
make check-large-files # clean
```
The 23 failures are pre-existing on `main` and unrelated
(`test_sandbox_debug_server.py`, `test_cli_theme.py`). Verified by
running the suite in a clean worktree at `origin/main` and diffing
failing test IDs: **no test fails on this branch that passes on
`main`**. The baseline worktree showed three extra failures in
`test_channels_errors.py`, which are an artifact of `slack_sdk` being
absent from that fresh environment, not a fix from this branch.
65 tests in `tests/test_read_file_image.py`, no skips, no xfail, no
weakened assertions. One pre-existing test changed on purpose:
`test_image_inlined_as_block` pinned the old user-content text block
exactly, and now pins the new shape plus asserts the path and re-read
hint are present.
Every commit was checked to import cleanly on its own, since the series
is meant to be read commit by commit.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Two surfaces, both updated: `read_file`'s tool description, and
`TOOLS.md` (the workspace file for non-obvious tool constraints, loaded
into the system prompt) which now documents content-based detection,
downscaling, the one-turn lifetime, and the follow-up-message delivery
path. Checked that no other doc enumerates tools -- neither README nor
README.zh-CN mentions `read_file`.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: a tool returning `str` behaves exactly as
before, and `read_file` on a text file is unchanged. `blocks` is
additive and only `read_file` and the MCP wrapper set it. The registry
keeps its 4-argument `add_tool_result` call for text results so no
existing caller or test double sees a signature change.
Rollback: reverting the branch restores prior behavior. The one
asymmetry worth naming is the persistence fix -- if the block-carrying
commit had landed without it, session JSONL written in between would
contain base64 permanently. They are in the same commit for that reason.
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-07-31 21:57:41 +08:00
|
|
|
def test_legacy_builder_names_the_image_path_too(self, tmp_path: Path) -> None:
|
|
|
|
|
"""There are two content builders (context engine and legacy
|
|
|
|
|
ContextBuilder); a path dropped in either one is a path the model cannot
|
|
|
|
|
use to re-read the picture."""
|
|
|
|
|
import base64 as _b64
|
|
|
|
|
|
|
|
|
|
from raven.agent.context.builder import ContextBuilder
|
|
|
|
|
|
|
|
|
|
png = tmp_path / "a.png"
|
|
|
|
|
png.write_bytes(
|
|
|
|
|
_b64.b64decode(
|
|
|
|
|
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
|
|
|
|
|
)
|
|
|
|
|
)
|
|
|
|
|
out = ContextBuilder._build_user_content(object.__new__(ContextBuilder), "look", [str(png)])
|
|
|
|
|
|
|
|
|
|
assert isinstance(out, list)
|
|
|
|
|
assert out[0]["type"] == "image_url"
|
|
|
|
|
text_block = out[-1]["text"]
|
|
|
|
|
assert text_block.startswith("look\n\n")
|
|
|
|
|
assert f"(path: {png})" in text_block
|
|
|
|
|
assert "read_file" in text_block
|
|
|
|
|
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
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
|
|
|
# EverOS understand_media tool (needs raven_everos importable)
|
2026-06-28 18:17:27 +08:00
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
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
|
|
|
from raven_everos.tools import UnderstandMediaTool, make_understand_media_tool
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestUnderstandMediaTool:
|
|
|
|
|
def test_factory_returns_tool_when_extra_available(self, monkeypatch) -> None:
|
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
|
|
|
import raven_everos.tools as tools_mod
|
|
|
|
|
from raven.contracts.tool import Tool
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
# Gate on the parser extra; force it "available" so the assertion
|
|
|
|
|
# holds regardless of whether the heavy extra is installed here.
|
|
|
|
|
monkeypatch.setattr(tools_mod, "_multimodal_available", lambda: True)
|
|
|
|
|
t = make_understand_media_tool(None)
|
|
|
|
|
assert isinstance(t, Tool)
|
|
|
|
|
assert t.name == "understand_media"
|
|
|
|
|
assert "paths" in t.parameters["properties"]
|
|
|
|
|
|
|
|
|
|
def test_factory_returns_none_when_extra_missing(self, monkeypatch) -> None:
|
|
|
|
|
# No everos[multimodal] extra → factory declines to contribute the
|
|
|
|
|
# tool (returns None) so the host never registers it.
|
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
|
|
|
import raven_everos.tools as tools_mod
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
monkeypatch.setattr(tools_mod, "_multimodal_available", lambda: False)
|
|
|
|
|
assert make_understand_media_tool(None) is None
|
|
|
|
|
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
def test_description_defers_images_to_read_file(self) -> None:
|
|
|
|
|
# Both tools accept an image path, so without an explicit steer the
|
|
|
|
|
# model picks either and may get a transcription instead of the picture.
|
|
|
|
|
assert "read_file" in UnderstandMediaTool().description
|
|
|
|
|
|
2026-06-28 18:17:27 +08:00
|
|
|
async def test_missing_paths_errors(self) -> None:
|
|
|
|
|
t = UnderstandMediaTool()
|
|
|
|
|
assert (await t.execute(paths=None)).startswith("Error")
|
|
|
|
|
assert (await t.execute(paths=[])).startswith("Error")
|
|
|
|
|
|
|
|
|
|
async def test_degrades_when_unavailable(self, monkeypatch) -> None:
|
|
|
|
|
# When the multimodal runtime is unavailable, understand_files
|
refactor(*): finish whole-repo lint convention (#80)
## Summary
Two focused lint cleanups off the whole-repo lint convention:
**Python (ruff N818)** — rename exception classes to the `*Error` suffix
so
they satisfy the N818 naming rule, and update every reference:
`_SocketClosed`, `MultimodalUnavailable`, `PluginConflict`,
`PluginNotFound`.
Pre-stable rename with no external consumers. The matching N818
per-file-ignores
are dropped from `pyproject.toml`; the CONTEXT glossary entry and the
registry
diagram are updated in step.
**TypeScript (eslint no-explicit-any, ui-tui)** — remove `any` from the
code and
ratchet the rule to error:
- Replace `any` in 6 rpc/config generic signatures with
`unknown`/`object`. The
default type stays the record shape; the generic constraint loosens to
`object` so concrete response interfaces satisfy it without an index
signature (and `object` is not `any`, so type safety holds).
- Remove dead shift/ctrl click-modifier branches in `thinking.tsx`: the
hermes-ink `ClickEvent` never carries modifier keys, so those branches
were
unreachable (confirmed by tracing the click pipeline); drop them and the
now-unused expand-all helpers.
- Ratchet `@typescript-eslint/no-explicit-any` to error, scoped to the
ui-tui
config layer; test files stay exempt.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Run from the branch (rebased on latest `main`):
- `uv run ruff check .` — All checks passed.
- `uv run pytest tests/test_plugin_registry.py
tests/test_plugin_bootstrap.py tests/test_plugin_tools.py` — 43 passed.
- `npm run type-check` (ui-tui) — 0 errors.
- `npm run lint` (ui-tui) — 0 errors; no-explicit-any is now error with
0 violations.
- `npm test` (ui-tui) — 868 passed, 16 skipped, 0 failed.
- Full Python suite: no regressions vs the `main` baseline (the
remaining
failures are environment-only: an optional native dep not importable in
the
worktree venv, plus TTY/subprocess e2e that need a real terminal).
- [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
The exception renames are a source-visible API change, but the project
is
pre-stable and the renamed exceptions have no external consumers. The
TypeScript
changes are behavior-preserving; the removed click-modifier branches
were proven
unreachable.
## Related Issues
N/A
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-02 21:24:02 +08:00
|
|
|
# raises MultimodalUnavailableError and the tool surfaces one clear
|
2026-06-28 18:17:27 +08:00
|
|
|
# error message rather than propagating the exception.
|
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
|
|
|
import raven_everos.tools as tools_mod
|
|
|
|
|
from raven_everos.multimodal import MultimodalUnavailableError
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
async def fake_unavailable(paths):
|
refactor(*): finish whole-repo lint convention (#80)
## Summary
Two focused lint cleanups off the whole-repo lint convention:
**Python (ruff N818)** — rename exception classes to the `*Error` suffix
so
they satisfy the N818 naming rule, and update every reference:
`_SocketClosed`, `MultimodalUnavailable`, `PluginConflict`,
`PluginNotFound`.
Pre-stable rename with no external consumers. The matching N818
per-file-ignores
are dropped from `pyproject.toml`; the CONTEXT glossary entry and the
registry
diagram are updated in step.
**TypeScript (eslint no-explicit-any, ui-tui)** — remove `any` from the
code and
ratchet the rule to error:
- Replace `any` in 6 rpc/config generic signatures with
`unknown`/`object`. The
default type stays the record shape; the generic constraint loosens to
`object` so concrete response interfaces satisfy it without an index
signature (and `object` is not `any`, so type safety holds).
- Remove dead shift/ctrl click-modifier branches in `thinking.tsx`: the
hermes-ink `ClickEvent` never carries modifier keys, so those branches
were
unreachable (confirmed by tracing the click pipeline); drop them and the
now-unused expand-all helpers.
- Ratchet `@typescript-eslint/no-explicit-any` to error, scoped to the
ui-tui
config layer; test files stay exempt.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Run from the branch (rebased on latest `main`):
- `uv run ruff check .` — All checks passed.
- `uv run pytest tests/test_plugin_registry.py
tests/test_plugin_bootstrap.py tests/test_plugin_tools.py` — 43 passed.
- `npm run type-check` (ui-tui) — 0 errors.
- `npm run lint` (ui-tui) — 0 errors; no-explicit-any is now error with
0 violations.
- `npm test` (ui-tui) — 868 passed, 16 skipped, 0 failed.
- Full Python suite: no regressions vs the `main` baseline (the
remaining
failures are environment-only: an optional native dep not importable in
the
worktree venv, plus TTY/subprocess e2e that need a real terminal).
- [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
The exception renames are a source-visible API change, but the project
is
pre-stable and the renamed exceptions have no external consumers. The
TypeScript
changes are behavior-preserving; the removed click-modifier branches
were proven
unreachable.
## Related Issues
N/A
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-02 21:24:02 +08:00
|
|
|
raise MultimodalUnavailableError("multimodal extra not configured")
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
monkeypatch.setattr(tools_mod, "understand_files", fake_unavailable)
|
|
|
|
|
out = await UnderstandMediaTool().execute(paths=["/tmp/x.pdf"])
|
|
|
|
|
assert "unavailable" in out.lower()
|
|
|
|
|
|
|
|
|
|
async def test_formats_results(self, monkeypatch) -> None:
|
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
|
|
|
import raven_everos.tools as tools_mod
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
async def fake_understand(paths):
|
|
|
|
|
return [
|
|
|
|
|
{"path": paths[0], "name": "a.pdf", "text": "hello world"},
|
|
|
|
|
{"path": paths[1], "name": "b.mp4", "error": "video not supported"},
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
monkeypatch.setattr(tools_mod, "understand_files", fake_understand)
|
|
|
|
|
out = await UnderstandMediaTool().execute(paths=["/x/a.pdf", "/x/b.mp4"])
|
|
|
|
|
assert "## a.pdf" in out and "hello world" in out
|
|
|
|
|
assert "## b.mp4" in out and "video not supported" in out
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestContentItemRouting:
|
|
|
|
|
"""Input routing in multimodal._content_item_for — file path vs URL.
|
|
|
|
|
|
|
|
|
|
Unit-level so it needs no LLM / network: just asserts the ContentItem
|
|
|
|
|
shape everalgo will receive.
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
def test_http_url_detection(self) -> None:
|
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
|
|
|
from raven_everos.multimodal import _is_http_url
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
assert _is_http_url("https://example.com/page")
|
|
|
|
|
assert _is_http_url("http://example.com")
|
|
|
|
|
assert not _is_http_url("/tmp/a.png")
|
|
|
|
|
assert not _is_http_url("file:///tmp/a.png")
|
|
|
|
|
assert not _is_http_url("relative/path.pdf")
|
|
|
|
|
|
|
|
|
|
def test_url_becomes_uri_item(self) -> None:
|
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
|
|
|
from raven_everos.multimodal import _content_item_for
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
item = _content_item_for("https://example.com/doc")
|
|
|
|
|
# uri-backed → everalgo fetches + dispatches by Content-Type;
|
|
|
|
|
# no base64 payload, no local read.
|
|
|
|
|
assert item == {
|
|
|
|
|
"type": "url",
|
|
|
|
|
"uri": "https://example.com/doc",
|
|
|
|
|
"name": "https://example.com/doc",
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
def test_local_file_becomes_base64_item(self, tmp_path: Path) -> None:
|
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
|
|
|
from raven_everos.multimodal import _content_item_for
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
f = tmp_path / "hello.txt"
|
|
|
|
|
f.write_text("hi")
|
|
|
|
|
item = _content_item_for(str(f))
|
|
|
|
|
assert item["name"] == "hello.txt"
|
|
|
|
|
assert item["ext"] == ".txt"
|
|
|
|
|
assert "base64" in item and "uri" not in item
|
|
|
|
|
|
|
|
|
|
def test_missing_local_file_raises(self) -> None:
|
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
|
|
|
from raven_everos.multimodal import _content_item_for
|
2026-06-28 18:17:27 +08:00
|
|
|
|
|
|
|
|
with pytest.raises(FileNotFoundError):
|
|
|
|
|
_content_item_for("/no/such/file.pdf")
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
class TestEverosParserContract:
|
|
|
|
|
"""``understand_files`` driving the *real* everos parser call chain.
|
|
|
|
|
|
|
|
|
|
Every other test here replaces ``understand_files`` wholesale, so a
|
|
|
|
|
signature change in ``everos.memory.extract.parser.enrich_content_items``
|
|
|
|
|
reaches users as a per-file "could not understand" note instead of a test
|
|
|
|
|
failure. These stub only the two external boundaries -- the optional
|
|
|
|
|
parser extra's availability probe and the vision LLM call -- leaving the
|
|
|
|
|
call into everos, and therefore its signature, genuinely exercised.
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
@staticmethod
|
|
|
|
|
def _stub_boundaries(monkeypatch: pytest.MonkeyPatch, parse) -> None:
|
|
|
|
|
import everos.component.llm.client as llm_client
|
|
|
|
|
import everos.component.parser as component_parser
|
|
|
|
|
|
|
|
|
|
monkeypatch.setattr(component_parser, "parser_available", lambda: True)
|
|
|
|
|
monkeypatch.setattr(component_parser, "aparse_file", parse)
|
|
|
|
|
monkeypatch.setattr(llm_client, "get_multimodal_llm_client", lambda: object())
|
|
|
|
|
|
|
|
|
|
@staticmethod
|
|
|
|
|
def _png(tmp_path: Path, name: str = "shot.png") -> Path:
|
|
|
|
|
f = tmp_path / name
|
|
|
|
|
f.write_bytes(b"payload")
|
|
|
|
|
return f
|
|
|
|
|
|
|
|
|
|
async def test_local_file_parses_through_real_enrich(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
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
|
|
|
from raven_everos.multimodal import understand_files
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
assert raw_file.content == b"payload"
|
|
|
|
|
assert raw_file.extension == "png"
|
|
|
|
|
return types.SimpleNamespace(text="a diagram")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
f = self._png(tmp_path)
|
|
|
|
|
assert await understand_files([str(f)]) == [{"path": str(f), "name": "shot.png", "text": "a diagram"}]
|
|
|
|
|
|
|
|
|
|
async def test_interface_error_aborts_the_batch(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
|
|
|
# A TypeError out of the parser means our call no longer matches
|
|
|
|
|
# everos's API -- true of every file, so it must not be reported as
|
|
|
|
|
# one file the parser could not read.
|
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
|
|
|
from raven_everos.multimodal import (
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
MultimodalUnavailableError,
|
|
|
|
|
understand_files,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
raise TypeError("unexpected keyword argument")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
f = self._png(tmp_path)
|
|
|
|
|
with pytest.raises(MultimodalUnavailableError):
|
|
|
|
|
await understand_files([str(f)])
|
|
|
|
|
|
|
|
|
|
async def test_one_failed_file_does_not_abort_the_batch(
|
|
|
|
|
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
|
|
|
|
) -> None:
|
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
|
|
|
from raven_everos.multimodal import understand_files
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
if raw_file.content == b"payload":
|
|
|
|
|
raise ValueError("cannot decode")
|
|
|
|
|
return types.SimpleNamespace(text="second one")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
bad = self._png(tmp_path, "bad.png")
|
|
|
|
|
good = tmp_path / "good.png"
|
|
|
|
|
good.write_bytes(b"other")
|
|
|
|
|
out = await understand_files([str(bad), str(good)])
|
|
|
|
|
assert "cannot decode" in out[0]["error"]
|
|
|
|
|
assert out[1]["text"] == "second one"
|
|
|
|
|
|
|
|
|
|
async def test_unsupported_modality_degrades_per_item(
|
|
|
|
|
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
|
|
|
|
) -> None:
|
|
|
|
|
from everos.core.errors import UnsupportedModalityError
|
|
|
|
|
|
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
|
|
|
from raven_everos.multimodal import understand_files
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
if raw_file.content == b"payload":
|
|
|
|
|
raise UnsupportedModalityError("video is not supported")
|
|
|
|
|
return types.SimpleNamespace(text="fine")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
video = self._png(tmp_path, "clip.png")
|
|
|
|
|
good = tmp_path / "good.png"
|
|
|
|
|
good.write_bytes(b"other")
|
|
|
|
|
out = await understand_files([str(video), str(good)])
|
|
|
|
|
assert "not supported" in out[0]["error"]
|
|
|
|
|
assert out[1]["text"] == "fine"
|
|
|
|
|
|
|
|
|
|
async def test_unconfigured_llm_fails_the_call_once(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
|
|
|
# The reason understand_files probes the client up front: without it
|
|
|
|
|
# the parser resolves its own client per file and the same failure
|
|
|
|
|
# would come back once per attachment.
|
|
|
|
|
import everos.component.llm.client as llm_client
|
|
|
|
|
|
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
|
|
|
from raven_everos.multimodal import (
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
MultimodalUnavailableError,
|
|
|
|
|
understand_files,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
parsed: list[object] = []
|
|
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
parsed.append(raw_file)
|
|
|
|
|
return types.SimpleNamespace(text="never")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
|
|
|
|
|
def unconfigured():
|
|
|
|
|
raise llm_client.LLMNotConfiguredError("multimodal LLM not configured")
|
|
|
|
|
|
|
|
|
|
monkeypatch.setattr(llm_client, "get_multimodal_llm_client", unconfigured)
|
|
|
|
|
with pytest.raises(MultimodalUnavailableError, match="not configured"):
|
|
|
|
|
await understand_files([str(self._png(tmp_path))])
|
|
|
|
|
assert parsed == []
|
|
|
|
|
|
|
|
|
|
async def test_missing_parser_extra_fails_the_call(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
|
|
|
import everos.component.parser as component_parser
|
|
|
|
|
|
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
|
|
|
from raven_everos.multimodal import (
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
MultimodalUnavailableError,
|
|
|
|
|
understand_files,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
monkeypatch.setattr(component_parser, "parser_available", lambda: False)
|
|
|
|
|
with pytest.raises(MultimodalUnavailableError, match="not installed"):
|
|
|
|
|
await understand_files([str(self._png(tmp_path))])
|
|
|
|
|
|
|
|
|
|
async def test_llm_failure_reads_back_parse_error(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
|
|
|
# everos degrades an LLMError in place (parse_error set, no
|
|
|
|
|
# parsed_content); understand_files must surface that as the error.
|
|
|
|
|
from everalgo.llm import LLMError
|
|
|
|
|
|
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
|
|
|
from raven_everos.multimodal import understand_files
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
raise LLMError("upstream 500")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
f = self._png(tmp_path)
|
|
|
|
|
assert await understand_files([str(f)]) == [{"path": str(f), "name": "shot.png", "error": "LLMError"}]
|
|
|
|
|
|
|
|
|
|
async def test_missing_file_is_reported_not_fatal(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
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
|
|
|
from raven_everos.multimodal import understand_files
|
fix(plugin): restore understand_media parsing against the current everos parser (#273)
## Summary
`understand_media` has been failing on every call. EverOS moved
multimodal LLM resolution into `aparse_file` and dropped the `llm`
keyword from `enrich_content_items`, so the call raised `TypeError`. The
per-item `except Exception` then degraded that into a per-file `[could
not understand: ...]` note, so an interface mismatch read like an
attachment the parser could not handle.
Three changes:
- Drop the stale `llm=` keyword. The up-front
`get_multimodal_llm_client()` probe stays: the parser resolves its own
client per file, so without it an unconfigured deployment reports the
same failure once per attachment.
- Re-raise a `TypeError` from the parser as a batch-level
`MultimodalUnavailableError`. A signature mismatch is true of every
attachment, so per-item degradation is the wrong shape for it.
- Steer image reads to `read_file` in the tool description. Both tools
claimed images, so the model could pick the one that hands back another
model's transcription instead of the picture itself. This matches what
`render.build_user_content` already tells the model next to each
attachment.
The existing tests stub `understand_files` wholesale and never reach
everos, which is why the drift was invisible. `TestEverosParserContract`
stubs only the two external boundaries -- the optional parser extra's
availability probe and the vision call -- and lets the real
`enrich_content_items` run, so the next signature change fails a test
instead of a user. It covers the failure contract as a whole: a
signature mismatch aborts the batch; an unsupported modality, an LLM
error and a missing file are each reported per item without stopping the
rest; and an unconfigured client or a missing parser extra fails the
call once, before any file is parsed.
That exposed a pre-existing isolation bug in the same test file: the
autouse `_cleanup_modules` fixture evicted every module a test imported,
including lancedb, whose Rust extension panics when re-imported after a
logger is installed. It now clears only the fakes it injects.
Fixing the `pre-commit diff` job then surfaced a second version skew.
`.pre-commit-config.yaml` pins ruff v0.15.12 while the dev group
resolved 0.15.11, and the two format the same signatures differently, so
`uv run ruff format --check` passed locally on files CI rejected. The
dev group is now pinned to `ruff==0.15.12`. A range does not fix this:
local ruff only has to differ from the hook's version, in either
direction, for the two to disagree. The published `dev` extra keeps its
looser `ruff>=0.6.0`, since that is for consumers installing
`raven[dev]` rather than what `uv run ruff` resolves.
Not covered here: `read_file` on a PDF still ends at `Error reading
file: 'utf-8' codec can't decode byte ...` with no pointer to
`understand_media`, and `render.build_user_content` names
`understand_media` unconditionally even where the plugin is not
registered. Both need a way for core code to refer to an optional tool
without hardcoding its name, which is worth designing separately.
## Type
- [x] Fix
## Verification
- `uv run pytest tests/ --ignore=tests/integration` -> 1 failed, 5176
passed, 40 skipped. The failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`,
which fails identically on an unmodified checkout (the local terminal
reports 16-color rather than truecolor) and passes in the `unit` job
here.
- `uv run pytest tests/test_plugin_tools.py` -> 36 passed.
- `uv run ruff format .` -> 873 files left unchanged, and `uv run ruff
check .` -> All checks passed, both on the newly pinned 0.15.12.
- `uv run pre-commit run` over this branch's diff -> every hook Passed
or Skipped, with the working tree unmodified afterwards. This is the
same command the `pre-commit diff` job runs.
- The new tests were confirmed red before the fix, reporting
`enrich_content_items() got an unexpected keyword argument 'llm'` -- the
same string users were seeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- `understand_media` goes from always-failing to working, so attachments
that used to produce "could not understand" now spend vision-model calls
and tokens. It still requires `EVEROS_MULTIMODAL__*`; an unconfigured
deployment gets one clear error instead of one per file.
- A `TypeError` anywhere under the parser now aborts the batch rather
than degrading a single file. That is the intent; per-item isolation is
unchanged for every other exception.
- The dev ruff pin is exact, so it has to be bumped together with the
rev in `.pre-commit-config.yaml`. Moving one without the other puts
local formatting and CI back out of step.
- No schema, config, or on-disk format changes. Rollback is a revert of
these commits.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-06 17:42:29 +08:00
|
|
|
|
|
|
|
|
async def parse(raw_file):
|
|
|
|
|
return types.SimpleNamespace(text="fine")
|
|
|
|
|
|
|
|
|
|
self._stub_boundaries(monkeypatch, parse)
|
|
|
|
|
good = self._png(tmp_path)
|
|
|
|
|
missing = tmp_path / "gone.png"
|
|
|
|
|
out = await understand_files([str(missing), str(good)])
|
|
|
|
|
assert out[0] == {"path": str(missing), "name": "gone.png", "error": "file not found"}
|
|
|
|
|
assert out[1]["text"] == "fine"
|