Refactor _run_dir_loop before Phase 3 dynamic turn allocation lands #57

New issue

Open

opened 2026-04-07 05:26:14 +00:00 by archeious · 0 comments

archeious commented

2026-04-07 05:26:14 +00:00

Owner

_run_dir_loop() (ai.py:845) is ~160 lines and contains four conceptual layers:

Pre-loop setup: build context, child summaries, survey block, filter tools, format system prompt
Per-turn budget check + partial-flush early-exit (~50 lines, the largest single block)
Per-turn API call + assistant message append + tool decision printing
Per-turn tool dispatch + tool_result append + done-on-submit_report

It is at its readability ceiling. Phase 3 #10 (dynamic turn allocation from plan output) will add per-dir max_turns injection plus possibly mid-loop budget renegotiation — more state in the same function. Refactoring after that lands will be harder than refactoring before.

Fix

Extract layers into focused helpers:

_build_dir_loop_context(...) — pre-loop setup (current lines 848–864)
_check_budget_and_flush_partial(...) — budget check + partial-cache writer (current 882–938)
_handle_turn_response(content_blocks, tool_uses, ...) — tool dispatch + done detection (current 974–998)

Leave the for-loop body as a thin coordinator that calls these in sequence. No behavior change. Tests: there are none today (ai.py exempt) — see related issue for adding pure-helper coverage.

Notes

Discovered during Session 5 documentation deep dive (#53)
Should land before Phase 3 #10 (dynamic turn allocation) — not after
The partial-flush block is the most extractable piece because it has a clear input (cache + dir_path + tracker) and clear output (writes a dir entry)
Internals.md §4 will need an update after this refactor

`_run_dir_loop()` (`ai.py:845`) is ~160 lines and contains four conceptual layers: 1. Pre-loop setup: build context, child summaries, survey block, filter tools, format system prompt 2. Per-turn budget check + partial-flush early-exit (~50 lines, the largest single block) 3. Per-turn API call + assistant message append + tool decision printing 4. Per-turn tool dispatch + tool_result append + done-on-submit_report It is at its readability ceiling. Phase 3 #10 (dynamic turn allocation from plan output) will add per-dir `max_turns` injection plus possibly mid-loop budget renegotiation — more state in the same function. Refactoring after that lands will be harder than refactoring before. ## Fix Extract layers into focused helpers: - `_build_dir_loop_context(...)` — pre-loop setup (current lines 848–864) - `_check_budget_and_flush_partial(...)` — budget check + partial-cache writer (current 882–938) - `_handle_turn_response(content_blocks, tool_uses, ...)` — tool dispatch + done detection (current 974–998) Leave the for-loop body as a thin coordinator that calls these in sequence. No behavior change. Tests: there are none today (`ai.py` exempt) — see related issue for adding pure-helper coverage. ## Notes - Discovered during Session 5 documentation deep dive (#53) - **Should land before Phase 3 #10** (dynamic turn allocation) — not after - The partial-flush block is the most extractable piece because it has a clear input (cache + dir_path + tracker) and clear output (writes a dir entry) - Internals.md §4 will need an update after this refactor