feat: room file tools behind Capability.FILES

[eric-descourtis-thenvoi]

What

Three built-in room file tools behind a new opt-in Capability.FILES:

Tool	Does
band_list_room_files	Lists files shared with this agent, newest first (name/type/size + sender)
band_read_room_file	Text inline (16 KiB cap); images become real vision input; other formats described
band_send_room_file	Uploads a text file it wrote and attaches it to a mention-reply

Plus two Claude SDK bridge fixes the vision path needs:

• _make_result passes through results that are already MCP-shaped ({"content": [...]}) instead of json-dumping an image block into base64 prose.
• A custom tool that declares room_id as a real input field keeps it; the strip now applies only to the schema-injected extra.

How

• The generated REST client (band-client-rest==0.0.10) doesn't expose the agent file endpoints yet, so the tools use the client's own transport (same base URL/auth/pool) with a comment marking the migration point once Fern regen lands.
• Tool-family registries treat files exactly like memory: excluded from BASE/CHAT, present in ALL, own FILE_TOOL_NAMES set and "files" category. band_send_room_file counts as a room-posting tool for reply suppression; the two readers join READ_ONLY_TOOL_NAMES.
• Wired adapters: claude_sdk (definition-driven, vision capable), pydantic_ai and crewai/crewai_flow (concrete wrappers). Other adapters keep their current capability set — enabling them is a follow-up per adapter.
• Mentions resolve client-side via the existing participants cache, so the send works against platforms without server-side handle resolution.
• Listing queries the delivery-status views (processing/processed/pending/unfiltered) because the message that triggered the current turn is still processing — skip that view and "the file you were just sent" doesn't exist yet.

Capability negotiation (added since first review)

Capability.FILES is the operator saying "this agent may use files". It cannot say "this
deployment has them" — one SDK build talks to the SaaS node, to an on-prem node whose licence
grants room files and to one whose licence does not, and only the last 404s these endpoints. So
the SDK asks.

GET /api/v1/agent/me now answers with a feature_flags block (Agent API 1.15.0) under the same
ff_* keys the web app and JAM read from their own boot payload — one vocabulary, three clients.
PlatformRuntime keeps the answer from the metadata fetch it already performs, so there is no
extra round trip, and Agent.start() drops any refused capability from the adapter's
AdapterFeatures before on_started. Every adapter builds its tool list there and they all
read features.capabilities, so one prune hides the tools in every framework at once.

Only an explicit false refuses. A platform that answers nothing is not saying no — it may
predate the flag while still serving the endpoints, so reading silence as a refusal would take
working tools away from a deployment that has them. src/band/runtime/capabilities.py is the one
place the flag key is spelled.

The platform half is thenvoi-platform #2651, which also puts the whole feature behind
ff_file_transfer, off by default until a deployment asks for it.

Platform dependency

The endpoints ship in thenvoi-platform PLT-1209/1210/1211 (in review). The capability defaults off everywhere, so this is safe to merge ahead of them; agents opt in with AdapterFeatures(capabilities={Capability.FILES}).

Proven end-to-end on a dev platform node: an agent read a text file word-for-word, described a webp book cover from pixels, and authored+attached its own file — the same flows now covered by 18 unit tests (tests/runtime/test_file_tools.py, tests/integrations/claude_sdk/test_mcp_content_passthrough.py).

Tests

• uv run pytest tests/ --ignore=tests/integration/ --ignore=tests/e2e/: 4578 passed. The only residue is the desktop_app suite, which needs a working node on PATH: in a full run this box's asdf shim answers unknown command: node, and those same tests pass in isolation here and on clean main.
• ruff check / ruff format / pyrefly check: clean.

🤖 Generated with Claude Code

[eric-descourtis-thenvoi]

Dogfooding note: while live-testing this branch, agent turns went silent-empty (~1s, $0.00, no tool calls) and the adapter logged nothing. A probe with ClaudeAgentOptions(stderr=...) showed the real cause: RateLimitEvent (five-hour subscription limit) with a synthetic "session limit" assistant message and is_error=True on the result. Two adapter gaps worth follow-ups, not in this PR's scope:

1. ResultMessage.is_error / RateLimitEvent should be logged (or surfaced as a band error event) instead of reading as a successful $0.0000 turn.
2. Resuming a dead claude_sdk_session_id doesn't raise — the CLI accepts the id and returns empty turns forever, so the adapter's resume-failure fallback never fires. The ACP adapter's validate-then-fallback pattern (session/load) is the model to copy.