refactor: assemble the tool list in one place, drop the compat shim

[njbrake]

Description

Third of five. Targets #1551.

• assemble_turn_tools. The runtime turn, the heartbeat's Phase 2 agent, and the system-prompt preview each built the same six-step tool list inline, so the preview could drift from what the agent was handed. One function now, called by all three.
• Deleted agent/file_store.py, a re-export shim kept for backwards compatibility this project does not need before its first release. Its 34 importers point at the owning modules.
• webchat upload size check calls check_media_size instead of repeating the comparison, which aligns its rejection message with the rest of the media pipeline.
• Removed three uncalled functions: latest_saved_file, _disk_path_for, get_is_allowed_override.

Tests that patched the registry through backend.app.agent.tools.registry were relying on heartbeat's deferred import. They now patch backend.app.agent.tool_assembly, the module that uses it.

Type

• Refactor

Checklist

• Tests pass (uv run pytest -v): 4268 passed, 6 skipped, unchanged
• Lint passes (ruff check backend/ && ruff format --check backend/)
• New tests added for new functionality
• Bug fixes include regression tests

AI Usage

• AI-assisted: written by Claude Opus 5 via back-and-forth with @njbrake.

🤖 Generated with Claude Code

Summary

• Centralized tool-list construction in assemble_turn_tools for runtime turns, heartbeat tasks, and system-prompt previews.
• Removed the unused file_store.py compatibility shim and updated imports to use dedicated modules.
• Replaced webchat’s duplicate upload-size check with check_media_size.
• Removed unused media, saved-file, and channel override helpers.
• Updated tests to patch the new tool-assembly module directly.

Benefits

• Keeps tool behavior consistent across execution paths.
• Reduces duplicated logic and simplifies maintenance.
• Removes obsolete compatibility code.
• Reported validation: 4,268 tests passed, 6 skipped, and lint checks passed.

[coderabbitai]

Understand this PR’s impact

Explore downstream dependencies and potential security impact with Blast Radius.

View blast radius →

Warning

Review limit reached

Next included review available in 38 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: mozilla-ai/clawbolt/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 3ddd17e6-61b9-4a9e-a325-06ba3f354cb6

📥 Commits

Reviewing files that changed from the base of the PR and between e8d1071 and 253cd36.

📒 Files selected for processing (44)

• backend/app/agent/file_store.py
• backend/app/agent/heartbeat.py
• backend/app/agent/media_staging.py
• backend/app/agent/router.py
• backend/app/agent/saved_media.py
• backend/app/agent/tool_assembly.py
• backend/app/auth/oauth_flow.py
• backend/app/channels/base.py
• backend/app/channels/webchat.py
• backend/app/routers/admin/context.py
• backend/app/routers/admin/diagnostics.py
• backend/app/routers/admin/users.py
• backend/app/routers/auth_tokens.py
• backend/app/services/data_export.py
• backend/app/services/inactive_cleanup.py
• backend/app/services/user_deletion.py
• e2e/oss/file-upload.spec.ts
• tests/conftest.py
• tests/e2e/test_telegram_e2e.py
• tests/multi_user/test_admin_endpoints.py
• tests/multi_user/test_auth.py
• tests/multi_user/test_data_export.py
• tests/multi_user/test_heartbeat_delegation.py
• tests/multi_user/test_inactive_cleanup.py
• tests/multi_user/test_oauth_callback.py
• tests/multi_user/test_oauth_endpoints.py
• tests/multi_user/test_user_lifecycle.py
• tests/test_compaction.py
• tests/test_compaction_note.py
• tests/test_compaction_recovery.py
• tests/test_conversation_continuity.py
• tests/test_error_handling.py
• tests/test_file_cataloging.py
• tests/test_heartbeat.py
• tests/test_heartbeat_tools.py
• tests/test_history_timestamps.py
• tests/test_integration.py
• tests/test_message_batcher.py
• tests/test_message_router.py
• tests/test_onboarding.py
• tests/test_rate_limiter.py
• tests/test_tool_config.py
• tests/test_typing_indicator.py
• tests/test_webhook_secret_validation.py

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: mozilla-ai/clawbolt/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: f67f57eb-fa47-4fde-9579-3c08e3412d49

📥 Commits

Reviewing files that changed from the base of the PR and between 38844de and e8d1071.

📒 Files selected for processing (43)

• backend/app/agent/file_store.py
• backend/app/agent/heartbeat.py
• backend/app/agent/media_staging.py
• backend/app/agent/router.py
• backend/app/agent/saved_media.py
• backend/app/agent/tool_assembly.py
• backend/app/auth/oauth_flow.py
• backend/app/channels/base.py
• backend/app/channels/webchat.py
• backend/app/routers/admin/context.py
• backend/app/routers/admin/diagnostics.py
• backend/app/routers/admin/users.py
• backend/app/routers/auth_tokens.py
• backend/app/services/data_export.py
• backend/app/services/inactive_cleanup.py
• backend/app/services/user_deletion.py
• tests/conftest.py
• tests/e2e/test_telegram_e2e.py
• tests/multi_user/test_admin_endpoints.py
• tests/multi_user/test_auth.py
• tests/multi_user/test_data_export.py
• tests/multi_user/test_heartbeat_delegation.py
• tests/multi_user/test_inactive_cleanup.py
• tests/multi_user/test_oauth_callback.py
• tests/multi_user/test_oauth_endpoints.py
• tests/multi_user/test_user_lifecycle.py
• tests/test_compaction.py
• tests/test_compaction_note.py
• tests/test_compaction_recovery.py
• tests/test_conversation_continuity.py
• tests/test_error_handling.py
• tests/test_file_cataloging.py
• tests/test_heartbeat.py
• tests/test_heartbeat_tools.py
• tests/test_history_timestamps.py
• tests/test_integration.py
• tests/test_message_batcher.py
• tests/test_message_router.py
• tests/test_onboarding.py
• tests/test_rate_limiter.py
• tests/test_tool_config.py
• tests/test_typing_indicator.py
• tests/test_webhook_secret_validation.py

💤 Files with no reviewable changes (4)

• backend/app/agent/saved_media.py
• backend/app/agent/file_store.py
• backend/app/agent/media_staging.py
• backend/app/channels/base.py

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

Walkthrough

The PR centralizes agent tool assembly for runtime and preview paths, removes the file_store compatibility shim, updates direct imports, adjusts webchat media validation, and deletes unused helpers and accessors.

Changes

Agent runtime and module cleanup

Layer / File(s)	Summary
Shared tool assembly and runtime integration backend/app/agent/tool_assembly.py, backend/app/agent/router.py, backend/app/agent/heartbeat.py, tests/test_heartbeat.py	assemble_turn_tools now builds the shared tool list for previews, router execution, and heartbeat execution. Heartbeat tests patch the new assembly module.
Dedicated module imports backend/app/agent/file_store.py, backend/app/agent/*.py, backend/app/routers/..., backend/app/services/..., tests/...	The file_store compatibility shim was removed. Production code and tests now import DTOs and stores from their dedicated modules.
Media and channel helper cleanup backend/app/agent/media_staging.py, backend/app/agent/saved_media.py, backend/app/channels/base.py, backend/app/channels/webchat.py	Unused helpers and the public channel override accessor were removed. Webchat upload validation now uses check_media_size.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Refactor

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses the required refactor: prefix, uses imperative wording, describes the main changes, and is 67 characters long.
Description check	✅ Passed	The description explains the shared tool assembly refactor and related cleanup, identifies the change type, reports test and lint results, and completes the AI Usage section. The unchecked checklist i…
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 39 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}