refactor: codebase optimization - module decomposition, test dedup, type safety

[dimakis]

Summary

• Extract BaseAgent/AgentContext to agents/base.py and merge LibrarianAgent into agents/librarian.py; slim agents/__init__.py from 502 to ~50 lines of pure re-exports
• Extract tool registry logic (get_all_tools, get_architect_tools) to tools/registry.py; slim tools/__init__.py from 212 to ~100 lines
• Create shared tests/helpers/auth.py eliminating ~360 lines of duplicated auth setup across 12 test files
• Fix dangerous asyncio.sleep(10) in timeout tests with asyncio.Event().wait() pattern
• Fix 5 mypy errors in new registry.py, remove 5 modules from mypy strict override list
• Resolve circular import chain in agent sub-modules

Motivation

Architecture review identified bloated __init__.py files with substantial logic, duplicated test helpers, unsafe test patterns, and mypy debt. This PR addresses the highest-impact structural issues.

Type of Change

• refactor — Code restructuring (no feature or fix)
• test — Adding or updating tests
• fix — Bug fix (circular import, asyncio.sleep safety)

Changes

• agents/init.py: Moved BaseAgent (431 lines) and AgentContext to canonical agents/base.py. Added LibrarianAgent to existing agents/librarian.py. Updated 5 agent sub-modules to import from agents.base directly, breaking circular import chain.
• tools/init.py: Moved get_all_tools() and get_architect_tools() (with caching) to tools/registry.py. Fixed mypy type annotations (list -> list[Any]). Fixed attr-defined errors by importing from canonical source modules.
• tests/helpers/auth.py: New shared module with make_test_settings() and make_test_jwt(). Updated 12 test files to use shared helpers.
• test safety: Replaced asyncio.sleep(10) with asyncio.Event().wait() in 2 timeout test files.
• pyproject.toml: Removed 5 modules from mypy override list (settings, llm, tracing.mlflow now pass strict).

Testing

• Unit tests added/updated
• All static checks pass (ruff lint, ruff format, mypy strict, bandit)
• Full unit test suite passes

Security Considerations

• No security implications

Checklist

• My code follows the project's style (ruff, mypy pass)
• I've written tests that prove my fix/feature works
• I've added conventional commit messages
• Coverage has not decreased
• CI passed locally

Made with Cursor