Raven-1/tests/test_plugin_tools.py

633 lines
24 KiB
Python
Raw Permalink Normal View History

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"