archeious/luminos
1
0
Fork 0
Code Issues 42 Pull requests Projects 1 Releases Packages Wiki Activity Actions

refactor(ai): extract _run_dir_loop into three focused helpers (#57) #67

Merged
claude-code merged 1 commit from refactor/issue-57-dir-loop-helpers into main 2026-04-11 10:02:46 -06:00
Conversation 0 Commits 1 Files changed 1 +157 -107
claude-code commented 2026-04-11 10:02:39 -06:00
Collaborator
Copy link

Closes #57.

_run_dir_loop was ~160 lines holding four conceptual layers in one function: pre-loop setup, budget check + partial-flush, API call + response printing, and tool dispatch + done detection. Phase 3 dynamic turn allocation (#10) will inject more state into the same code path, so this debt is paid before that lands.

Three new helpers above _run_dir_loop

  • _build_dir_loop_context() (ai.py:855) — pure setup. Builds the dir context, child summaries, survey block, filtered tool list, system prompt, and seed user message. Returns a _DirLoopContext namedtuple. No writes.
  • _flush_partial_dir_entry() (ai.py:896) — idempotent partial-cache writer for the budget-exceeded path. Returns the partial summary string (or "" if a dir entry already exists or no file entries were available to synthesize from). Idempotent via the cache.has_entry() guard so callers can call it without checking first.
  • _handle_turn_response() (ai.py:957) — per-turn response processing. Prints text blocks and tool decisions to stderr, appends the assistant message, dispatches tools (or nudges the agent to call submit_report), appends tool_results. Mutates messages in place. Returns (done, summary).

_run_dir_loop is now a ~25-line coordinator: build context, then a for-loop that calls budget check, API, and turn handler in sequence.

Verification

  • 164/164 tests pass.
  • python3 -c "import luminos_lib.ai" succeeds.
  • No behavior change. Pure refactor. Lines moved, no logic changed.

Out of scope

  • Unit tests for the new helpers — that's #55 (the pure-helper coverage issue). Two of these three helpers (_build_dir_loop_context, _flush_partial_dir_entry) are now naturally testable with a real _CacheManager in a tempdir, which is a nice side effect.
  • _TOOL_DISPATCH / _DIR_TOOLS deduplication — that's #56.
  • Anything Phase 3.

Doc updates

Internals.md §4 updated in the wiki repo (separate commit, separate push) for the new structure and the file:line refs that drifted after the rewrite.

Closes #57. `_run_dir_loop` was ~160 lines holding four conceptual layers in one function: pre-loop setup, budget check + partial-flush, API call + response printing, and tool dispatch + done detection. Phase 3 dynamic turn allocation (#10) will inject more state into the same code path, so this debt is paid before that lands. ## Three new helpers above `_run_dir_loop` - **`_build_dir_loop_context()`** (`ai.py:855`) — pure setup. Builds the dir context, child summaries, survey block, filtered tool list, system prompt, and seed user message. Returns a `_DirLoopContext` namedtuple. No writes. - **`_flush_partial_dir_entry()`** (`ai.py:896`) — idempotent partial-cache writer for the budget-exceeded path. Returns the partial summary string (or `""` if a dir entry already exists or no file entries were available to synthesize from). Idempotent via the `cache.has_entry()` guard so callers can call it without checking first. - **`_handle_turn_response()`** (`ai.py:957`) — per-turn response processing. Prints text blocks and tool decisions to stderr, appends the assistant message, dispatches tools (or nudges the agent to call submit_report), appends tool_results. Mutates `messages` in place. Returns `(done, summary)`. `_run_dir_loop` is now a ~25-line coordinator: build context, then a for-loop that calls budget check, API, and turn handler in sequence. ## Verification - 164/164 tests pass. - `python3 -c "import luminos_lib.ai"` succeeds. - No behavior change. Pure refactor. Lines moved, no logic changed. ## Out of scope - Unit tests for the new helpers — that's #55 (the pure-helper coverage issue). Two of these three helpers (`_build_dir_loop_context`, `_flush_partial_dir_entry`) are now naturally testable with a real `_CacheManager` in a tempdir, which is a nice side effect. - `_TOOL_DISPATCH` / `_DIR_TOOLS` deduplication — that's #56. - Anything Phase 3. ## Doc updates `Internals.md` §4 updated in the wiki repo (separate commit, separate push) for the new structure and the `file:line` refs that drifted after the rewrite.
claude-code added 1 commit 2026-04-11 10:02:40 -06:00 
_run_dir_loop was ~160 lines holding four conceptual layers in one
function: pre-loop setup, budget check + partial-flush, API call +
response printing, and tool dispatch + done detection. Phase 3 dynamic
turn allocation will inject more state into the same code path, so
this debt is paid before that lands.

Three new helpers above _run_dir_loop:

- _build_dir_loop_context(): pure setup. Builds the dir context, child
  summaries, survey block, filtered tool list, system prompt, and seed
  user message. Returns a _DirLoopContext namedtuple.
- _flush_partial_dir_entry(): idempotent partial-cache writer for the
  budget-exceeded path. Returns the partial summary string. Idempotent
  via cache.has_entry() guard, so callers can call it without checking.
- _handle_turn_response(): per-turn response processing. Prints text
  blocks and tool decisions, appends the assistant message, dispatches
  tools (or nudges the agent to call submit_report), appends
  tool_results. Returns (done, summary).

_run_dir_loop is now a ~25-line coordinator: build context, then
for-loop calls budget check, API, and turn handler in sequence.

No behavior change. 164 tests pass. Internals.md §4 updated for the
new structure and the file:line refs that drifted.
claude-code merged commit a5a19fba55 into main 2026-04-11 10:02:46 -06:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: archeious/luminos#67
No description provided.
Delete branch "refactor/issue-57-dir-loop-helpers"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?