fix(plugin): restore understand_media parsing against the current everos parser

[gloryfromca]

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

• 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.

• Relevant tests pass locally

• 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.

• Backward compatibility considered

• Rollback path is clear for risky changes

Related Issues

N/A