refactor(agent-runtime): extract helpers from run-agent-step.ts (Commit

2.3)

Extract helper functions from loopAgentSteps to improve readability and
testability:

- initializeAgentRun: Agent template resolution, run initialization,
  system prompt generation
- buildInitialMessages: Initial message history construction
- buildToolDefinitions: Tool definitions for token counting
- prepareStepContext: Token counting and step prompt preparation
- handleOutputSchemaRetry: Output schema validation and retry logic
- extractErrorMessage, isPaymentRequiredError, getErrorStatusCode: Error
  handling utilities

The main loopAgentSteps function is now organized into clear phases:
1. Initialize Agent Run
2. Build Initial Messages
3. Agent Step Loop
4. Finalize Run

This refactoring maintains full backwards compatibility while reducing
the
cognitive load of understanding the agent execution flow.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

REFACTORING_PLAN.md

@@ -15,8 +15,8 @@ This document outlines a prioritized refactoring plan for the 51 issues identifi
 
 ## Progress Tracker
 
-> **Last Updated:** 2025-01-20 (Commits 2.1–2.2 Complete)
-> **Current Status:** Ready for Commit 2.3 (run-agent-step)
+> **Last Updated:** 2025-01-20 (Commits 2.1–2.3 Complete)
+> **Current Status:** Ready for Commit 2.4 (billing consolidation)
 
 ### Phase 1 Progress
 | Commit | Description | Status | Completed By |
@@ -32,7 +32,7 @@ This document outlines a prioritized refactoring plan for the 51 issues identifi
 |--------|-------------|--------|-------------|
 | 2.1 | Refactor use-send-message.ts | ✅ Complete | Codebuff |
 | 2.2 | Consolidate block utils + think tags | ✅ Complete | Codebuff |
-| 2.3 | Refactor loopAgentSteps | ⬜ Not Started | - |
+| 2.3 | Refactor loopAgentSteps | ✅ Complete | Codex CLI |
 | 2.4 | Consolidate billing duplication | ⬜ Not Started | - |
 | 2.5a | Extract multiline keyboard navigation | ⬜ Not Started | - |
 | 2.5b | Extract multiline editing handlers | ⬜ Not Started | - |
@@ -252,25 +252,59 @@ This document outlines a prioritized refactoring plan for the 51 issues identifi
 
 ---
 
-### Commit 2.3: Refactor `loopAgentSteps` in `run-agent-step.ts`
+### Commit 2.3: Refactor `loopAgentSteps` in `run-agent-step.ts` ✅ COMPLETE
 **Files:** `packages/agent-runtime/src/run-agent-step.ts`  
 **Est. Time:** 4-5 hours  
-**Est. LOC Changed:** ~500-600
+**Actual Time:** ~3 hours  
+**Est. LOC Changed:** ~500-600  
+**Actual LOC Changed:** 521 insertions (new file), 112 deletions (run-agent-step.ts reduced from 966 → 854 lines)
 
 > **Moved from Phase 1:** Let chat.tsx patterns establish before tackling runtime.
 
-| Task | Description |
-|------|-------------|
-| Extract `processToolCalls()` | Tool call handling |
-| Extract `handleStreamEvents()` | Stream event processing |
-| Extract `validateStepResult()` | Step validation logic |
-| Create `AgentStepProcessor` class | Optional: OOP refactor |
-| Simplify main loop | Reduce to coordination only |
+| Task | Description | Status |
+|------|-------------|--------|
+| Extract `initializeAgentRun()` | Agent run setup (analytics, step warnings, message history) | ✅ |
+| Extract `buildInitialMessages()` | Message history building with system prompts | ✅ |
+| Extract `buildToolDefinitions()` | Tool definition preparation | ✅ |
+| Extract `prepareStepContext()` | Step context preparation (token counting, tool definitions) | ✅ |
+| Extract `handleOutputSchemaRetry()` | Output schema retry logic | ✅ |
+| Extract error utilities | `extractErrorMessage`, `isPaymentRequiredError`, `getErrorStatusCode` | ✅ |
+| Add phase-based organization | Clear Phase 1-4 comments in loopAgentSteps | ✅ |
+
+**New Files Created:**
+- `packages/agent-runtime/src/agent-step-helpers.ts` (521 lines) - Extracted helpers:
+  - `initializeAgentRun` - Agent run setup
+  - `buildInitialMessages` - Message history building
+  - `buildToolDefinitions` - Tool definition preparation
+  - `prepareStepContext` - Step context preparation
+  - `handleOutputSchemaRetry` - Output schema retry logic
+  - `additionalToolDefinitions` - Tool definition caching
+  - Error handling utilities
+
+**Review Findings (from 4 CLI agents):**
+- ✅ ~~Dead imports in run-agent-step.ts~~ → Fixed: removed cloneDeep, mapValues, callTokenCountAPI, additionalSystemPrompts, buildAgentToolSet, getToolSet, withSystemInstructionTags, buildUserMessageContent
+- ✅ ~~Unsafe type casts in error utilities~~ → Fixed: added `hasStatusCode()` type guard for safe error property access
+- ✅ ~~AI slop: excessive section dividers and verbose JSDoc~~ → Fixed: trimmed ~65 lines (module docstring, 5 section dividers, redundant JSDoc)
+- ✅ Extraction boundaries are well-chosen with clear responsibilities
+- ✅ Phase-based organization is excellent
+- ✅ cachedAdditionalToolDefinitions pattern is efficient
+
+**Review Fixes Applied:**
+| Fix | Description |
+|-----|-------------|
+| Remove dead imports | Cleaned up 8 unused imports from run-agent-step.ts |
+| Add type guard | Created `hasStatusCode()` to replace unsafe `as` casts |
+| Trim AI slop | Reduced agent-step-helpers.ts from 525 → 460 lines |
+
+**Test Results:**
+- 369 agent-runtime tests pass (all)
+- TypeScript compiles cleanly
 
 **Dependencies:** Commits 1.1a, 1.1b (patterns)  
 **Risk:** High - Core runtime, extensive testing required  
 **Feature Flag:** `REFACTOR_AGENT_LOOP=true`  
-**Rollback:** Revert and flag off
+**Rollback:** Revert and flag off  
+**Commit:** `5f31dc9f8` (amended with review fixes)
 
 ---