refactor(api): extract shared infrastructure + uploads routes into src/api/

[shadowinlife]

Summary

• Extract shared infrastructure from agent/api_server.py (3,626 lines) into 5 focused modules under agent/src/api/: deps.py, models.py, helpers.py, state.py, live_relay.py
• Extract upload routes (POST /upload, GET /shadow-reports/{shadow_id}) into agent/src/api/uploads_routes.py following the existing alpha_routes.py registration pattern
• Reduce api_server.py from 3,626 → 3,535 lines (−91 lines) with zero behavior change

Why

agent/api_server.py has grown to 3,626 lines with 50 route decorators — a single module hosting auth, CORS, DNS-rebinding middleware, Pydantic models, session/run/swarm orchestration, live-trading endpoints, upload handling, and the dev launcher. This concentration of unrelated responsibilities makes the file hard to review safely and raises the barrier for new contributors. See #331 for the full analysis.

This is PR 1 of 5 in an incremental modularization series. Each PR is independently mergeable with green tests.

Closes #331 (partial — shared infrastructure + uploads extraction)

Changes

New shared infrastructure modules (additive)

Module	Lines	Content
src/api/deps.py	393	Auth dependencies + security helpers (CORS, DNS-rebinding, loopback detection, CSRF, shell-tools gating)
src/api/models.py	461	All 38 Pydantic models + LiveRunnerUnavailable exception
src/api/helpers.py	401	Path constants, env I/O helpers, _build_response_from_run_dir, _validate_path_param, SPA fallback
src/api/state.py	209	Lazy-init singleton accessors (session service, goal store, swarm/channel/scheduled runtimes)
src/api/live_relay.py	204	SSE relay helpers for live trading events

First route extraction: uploads

Module	Lines	Routes
src/api/uploads_routes.py	185	POST /upload, GET /shadow-reports/{shadow_id}

api_server.py changes

• Upload route definitions replaced with register_uploads_routes(app) call
• Re-exports added for backward-compatible test access

Design decisions

1. Function-based registration (not APIRouter) — follows existing alpha_routes.py pattern
2. Per-module Pydantic models — avoids coupling unrelated groups
3. SSE relay in live_relay.py — resolves sessions ↔ live circular dependency
4. Re-exports for test compatibility — all test-accessed symbols remain importable via api_server.*

Test Plan

• Existing tests pass (cd agent && pytest tests/test_upload_api.py tests/test_upload_security.py tests/test_security_auth_api.py tests/test_settings_api.py tests/test_spa_deep_link.py tests/test_run_card.py -v — all pass)
• New tests added (not applicable — pure structural refactor, zero test changes)
• Tested manually: verified all 5 new modules importable without circular imports, all path constants resolve correctly

Checklist

• No changes to protected areas (src/agent/, src/session/, src/providers/) without prior discussion
• No hardcoded values (API keys, file paths, magic numbers)
• Code follows CONTRIBUTING.md guidelines
• Documentation updated (not applicable — internal refactor, no user-facing change)

[shadowinlife]

Subsequent PR Roadmap

This is PR 1 of 5 in the api_server.py modularization series. Each PR follows the same pattern: create a route module → move routes from api_server.py → add register_*_routes(app) + re-exports.

PR	Modules	Routes Moved	api_server.py Δ
PR 1 (this)	deps + models + helpers + state + live_relay + uploads_routes	2	−91 lines
PR 2	system_routes + settings_routes	9	~−300 lines
PR 3	runs_routes + swarm_routes	11	~−370 lines
PR 4	scheduled_routes + channels_routes	7	~−240 lines
PR 5	live_routes + sessions_routes	21	~−1,500 lines

Target: api_server.py drops from 3,626 → ~350 lines (thin assembler + middleware + serve_main).

Each subsequent PR will be opened after the previous one is merged, to keep the review surface small and avoid merge conflicts.

[shadowinlife]

Code Review — PR #358

Overall: ⚠️ CONDITIONAL PASS

Dimension	Verdict	Confidence
Goal & Constraints	⚠️ PARTIAL	HIGH
Tests (102/102)	✅ PASS	HIGH
Code Quality	⚠️ WARN	HIGH
Security	✅ PASS	HIGH
Atomicity / Incremental	✅ PASS	HIGH

---

🔴 Blocking Issue (now fixed in aaaa9c5)

state.py:192 — NameError: name '_dispatch_scheduled_research_job' is not defined

_get_scheduled_research_executor() in state.py referenced _dispatch_scheduled_research_job without defining or importing it. The function lives in api_server.py:3336 and was not carried over during extraction.

Verified at runtime:

>>> from src.api.state import _get_scheduled_research_executor
>>> _get_scheduled_research_executor()
NameError: name '_dispatch_scheduled_research_job' is not defined

Fix pushed in aaaa9c5: Added _dispatch_scheduled_research_job to state.py. The function only depends on _get_session_service() (already in state.py), so the dependency chain is now self-contained. Also cleaned up an unused datetime import in models.py.

---

🟡 Non-Blocking Findings

1. All new modules are currently dead code — api_server.py still defines its own require_auth, singleton accessors, etc. The extracted deps.py, models.py, state.py, live_relay.py have no consumers in api_server.py yet. This is acceptable for Phase 0 (additive extraction), but subsequent PRs should switch api_server.py to import from these modules and delete the originals.

2. uploads_routes.py uses sys.modules reverse lookup (lines 64-73, 80-93) to resolve require_auth and constants from the host api_server module. This is fragile and opaque. Recommend switching to explicit parameter passing in the next PR that touches this file.

3. Net reduction: only -91 lines (2.5%) — api_server.py went from 3,626 → 3,535 lines. The +1,853 lines of new modules are additive infrastructure. This is expected for Phase 1 of 5, but worth noting for reviewers tracking the overall series.

---

✅ Positives

• Upload route extraction is a clean verbatim lift with correct re-exports for test compatibility
• Module dependency graph is well-layered: models.py (leaf) → helpers.py → state.py → live_relay.py
• Security-critical auth code in deps.py is a faithful copy — no behavioral drift
• 102 existing tests pass unchanged
• Single commit, clear scope, good PR description

---

Verification

$ pytest tests/test_upload_api.py tests/test_upload_security.py tests/test_security_auth_api.py \
         tests/test_settings_api.py tests/test_spa_deep_link.py tests/test_run_card.py -v
======================= 102 passed, 4 warnings in 5.24s ========================

[Hamza4007]

very good nice

[warren618]

Thanks @shadowinlife. We integrated the upload/Shadow report route extraction via maintainer PR #375, narrowed to the routes that are wired today while keeping #331 open for the broader API modularization. Closing this PR as superseded by #375.