savant-code 0.0.19 → 0.0.20

package/packages/agent-runtime/src/__tests__/run-programmatic-step.test.ts

@@ -1,1743 +0,0 @@
-import * as analytics from '@savant-code/common/analytics'
-import { TEST_USER_ID } from '@savant-code/common/old-constants'
-import { emptyMcpServers } from '@savant-code/common/testing/fixtures/agent-runtime'
-import { TEST_AGENT_RUNTIME_IMPL } from '@savant-code/common/testing/impl/agent-runtime'
-import { getInitialSessionState } from '@savant-code/common/types/session-state'
-import {
-  assistantMessage,
-  jsonToolResult,
-  userMessage,
-} from '@savant-code/common/util/messages'
-import {
-  afterEach,
-  beforeEach,
-  describe,
-  expect,
-  it,
-  mock,
-  spyOn,
-} from 'bun:test'
-import { cloneDeep } from 'lodash'
-
-import {
-  clearAgentGeneratorCache,
-  runProgrammaticStep,
-} from '../run-programmatic-step'
-import { mockFileContext } from './test-utils'
-import * as toolExecutor from '../tools/tool-executor'
-
-import type { AgentTemplate, StepGenerator } from '../templates/types'
-import type { executeToolCall } from '../tools/tool-executor'
-import type { PublicAgentState } from '@savant-code/common/types/agent-template'
-import type {
-  AgentRuntimeDeps,
-  AgentRuntimeScopedDeps,
-} from '@savant-code/common/types/contracts/agent-runtime'
-import type { SendActionFn } from '@savant-code/common/types/contracts/client'
-import type { Logger } from '@savant-code/common/types/contracts/logger'
-import type { ParamsOf } from '@savant-code/common/types/function-params'
-import type { ToolResultOutput } from '@savant-code/common/types/messages/content-part'
-import type { ToolMessage } from '@savant-code/common/types/messages/savant-code-message'
-import type { AgentState } from '@savant-code/common/types/session-state'
-
-const logger: Logger = {
-  debug: () => {},
-  error: () => {},
-  info: () => {},
-  warn: () => {},
-}
-
-describe('runProgrammaticStep', () => {
-  let mockTemplate: AgentTemplate
-  let mockAgentState: AgentState
-  let mockParams: ParamsOf<typeof runProgrammaticStep>
-  let executeToolCallSpy: ReturnType<
-    typeof spyOn<typeof toolExecutor, 'executeToolCall'>
-  >
-  let agentRuntimeImpl: AgentRuntimeDeps & AgentRuntimeScopedDeps
-
-  beforeEach(() => {
-    agentRuntimeImpl = {
-      ...TEST_AGENT_RUNTIME_IMPL,
-      addAgentStep: async () => 'test-agent-step-id',
-
-      sendAction: () => {},
-    }
-
-    // Mock analytics
-    spyOn(analytics, 'trackEvent').mockImplementation(() => {})
-
-    // Mock executeToolCall
-    executeToolCallSpy = spyOn(
-      toolExecutor,
-      'executeToolCall',
-    ).mockImplementation(async () => {})
-
-    // Mock crypto.randomUUID
-    spyOn(crypto, 'randomUUID').mockImplementation(
-      () =>
-        'mock-uuid-0000-0000-0000-000000000000' as `${string}-${string}-${string}-${string}-${string}`,
-    )
-
-    // Create mock template
-    mockTemplate = {
-      id: 'test-agent',
-      displayName: 'Test Agent',
-      spawnerPrompt: 'Testing',
-      model: 'claude-3-5-sonnet-20241022',
-      inputSchema: {},
-      outputMode: 'structured_output',
-      includeMessageHistory: true,
-      inheritParentSystemPrompt: false,
-      mcpServers: emptyMcpServers,
-      toolNames: ['read_files', 'write_file', 'end_turn'],
-      spawnableAgents: [],
-      systemPrompt: 'Test system prompt',
-      instructionsPrompt: 'Test user prompt',
-      stepPrompt: 'Test agent step prompt',
-      handleSteps: undefined, // Will be set in individual tests
-    } as AgentTemplate
-
-    // Create mock agent state
-    const sessionState = getInitialSessionState(mockFileContext)
-    mockAgentState = {
-      ...sessionState.mainAgentState,
-      agentId: 'test-agent-id',
-      runId:
-        'test-run-id' as `${string}-${string}-${string}-${string}-${string}`,
-      messageHistory: [
-        userMessage('Initial message'),
-        assistantMessage('Initial response'),
-      ],
-      output: undefined,
-      directCreditsUsed: 0,
-      childRunIds: [],
-    }
-
-    // Create mock params
-    mockParams = {
-      ...agentRuntimeImpl,
-      runId: 'test-run-id',
-      ancestorRunIds: [],
-      repoId: undefined,
-      repoUrl: undefined,
-      agentState: mockAgentState,
-      template: mockTemplate,
-      prompt: 'Test prompt',
-      toolCallParams: { testParam: 'value' },
-      userId: TEST_USER_ID,
-      userInputId: 'test-user-input',
-      clientSessionId: 'test-session',
-      fingerprintId: 'test-fingerprint',
-      onResponseChunk: () => {},
-      onCostCalculated: async () => {},
-      fileContext: mockFileContext,
-      localAgentTemplates: {},
-      system: 'Test system prompt',
-      stepsComplete: false,
-      stepNumber: 1,
-      tools: {},
-
-      logger,
-      signal: new AbortController().signal,
-    }
-  })
-
-  afterEach(() => {
-    mock.restore()
-    // Clear the generator cache between tests
-    clearAgentGeneratorCache({ logger })
-  })
-
-  describe('generator lifecycle', () => {
-    it('should create new generator when none exists', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState).toBeDefined()
-    })
-
-    it('should not reuse existing generator for same agent', async () => {
-      // Note: this behavior of creating a new generator after the first generator ended prevents memory leaks.
-      let callCount = 0
-      const createGenerator = () => {
-        callCount++
-        return (function* () {
-          yield { toolName: 'end_turn', input: {} }
-        })() as StepGenerator
-      }
-
-      mockTemplate.handleSteps = createGenerator
-      // First call
-      await runProgrammaticStep(mockParams)
-      expect(callCount).toBe(1)
-
-      // Second call with same agent ID should create a new generator
-      await runProgrammaticStep(mockParams)
-      expect(callCount).toBe(2) // Should create new generator
-    })
-
-    it('should handle STEP_ALL generator state', async () => {
-      // First, set up a generator that will be marked as STEP_ALL
-      const mockGenerator = (function* () {
-        yield 'STEP_ALL'
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      // First call to set STEP_ALL state
-      const result1 = await runProgrammaticStep(mockParams)
-      expect(result1.endTurn).toBe(false)
-
-      // Second call should return early due to STEP_ALL state
-      // Use the same agent state with the same runId
-      const result2 = await runProgrammaticStep({
-        ...mockParams,
-        agentState: result1.agentState,
-      })
-      expect(result2.endTurn).toBe(false)
-      expect(result2.agentState.agentId).toEqual(result1.agentState.agentId)
-    })
-
-    it('should throw error when template has no handleStep', async () => {
-      mockTemplate.handleSteps = undefined
-
-      await expect(runProgrammaticStep(mockParams)).rejects.toThrow(
-        'No step handler found for agent template test-agent',
-      )
-    })
-
-    it('SEC1: prefers live handleStepsFn over stringified handleSteps (no eval)', async () => {
-      // A string that would throw a ReferenceError if eval'd and stepped
-      // (references an out-of-scope identifier). The live fn must be preferred
-      // so the eval trust boundary is never crossed in-process.
-      mockTemplate.handleSteps =
-        'function* () { yield { toolName: "end_turn", input: {} }; const x = someUndefinedBundlerHelper; }'
-      mockTemplate.handleStepsFn = () =>
-        (function* () {
-          yield { toolName: 'end_turn', input: {} }
-        })() as StepGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-  })
-
-  describe('tool execution', () => {
-    it('should not add tool call message for add_message tool', async () => {
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'add_message',
-          input: { role: 'user', content: 'Hello world' },
-          includeToolCall: false,
-        }
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-      })() satisfies StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = ['add_message', 'read_files', 'end_turn']
-
-      // Track chunks sent via sendSubagentChunk
-      const sentChunks: string[] = []
-      const sendActionMock = mock<SendActionFn>(({ action }) => {
-        if (action.type === 'subagent-response-chunk') {
-          sentChunks.push(action.chunk)
-        }
-      })
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        sendAction: sendActionMock,
-      })
-
-      // Verify add_message tool was executed
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          toolName: 'add_message',
-          input: { role: 'user', content: 'Hello world' },
-        }),
-      )
-
-      // Verify read_files tool was executed
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          toolName: 'read_files',
-          input: { paths: ['test.txt'] },
-        }),
-      )
-
-      // Check that no tool call chunk was sent for add_message
-      const addMessageToolCallChunk = sentChunks.find(
-        (chunk) =>
-          typeof chunk === 'string' &&
-          chunk.includes('add_message') &&
-          chunk.includes('Hello world'),
-      )
-      expect(addMessageToolCallChunk).toBeUndefined()
-
-      // Verify final message history doesn't contain add_message tool call
-      const addMessageToolCallInHistory = result.agentState.messageHistory.find(
-        (msg) =>
-          msg.content[0].type === 'text' &&
-          msg.content[0].text.includes('add_message') &&
-          msg.content[0].text.includes('Hello world'),
-      )
-      expect(addMessageToolCallInHistory).toBeUndefined()
-
-      expect(result.endTurn).toBe(true)
-    })
-    it('should execute single tool call', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(2)
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          toolName: 'read_files',
-          input: expect.any(Object),
-          agentTemplate: mockTemplate,
-          fileContext: mockFileContext,
-        }),
-      )
-      expect(result.endTurn).toBe(true)
-    })
-
-    it('should add find_files tool result to messageHistory', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'find_files', input: { query: 'authentication' } }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = ['find_files', 'end_turn']
-
-      // Mock executeToolCall to simulate find_files tool result
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'find_files') {
-            const toolResult: ToolMessage = {
-              role: 'tool',
-              toolName: 'find_files',
-              toolCallId: 'find-files-call-id',
-              content: jsonToolResult({
-                files: [
-                  { path: 'src/auth.ts', relevance: 0.9 },
-                  { path: 'src/login.ts', relevance: 0.8 },
-                ],
-              }),
-            }
-            options.toolResults.push(toolResult)
-
-            options.agentState.messageHistory.push(toolResult)
-          }
-        },
-      )
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          toolName: 'find_files',
-          input: { query: 'authentication' },
-          agentTemplate: mockTemplate,
-          fileContext: mockFileContext,
-        }),
-      )
-
-      // Verify tool result was added to messageHistory
-      const toolMessages = result.agentState.messageHistory.filter(
-        (msg) =>
-          msg.role === 'tool' &&
-          JSON.stringify(msg.content).includes('src/auth.ts'),
-      )
-      expect(toolMessages).toHaveLength(1)
-      expect(JSON.stringify(toolMessages[0].content)).toContain('src/auth.ts')
-      expect(JSON.stringify(toolMessages[0].content)).toContain('src/login.ts')
-
-      expect(result.endTurn).toBe(true)
-    })
-
-    it('should execute multiple tool calls in sequence', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['file1.txt'] } }
-        yield {
-          toolName: 'write_file',
-          input: { path: 'file2.txt', content: 'test' },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(3)
-      expect(result.endTurn).toBe(true)
-    })
-
-    it('should comprehensively test STEP_ALL functionality with multiple tools and state management', async () => {
-      // Track all tool results and state changes for verification
-      const toolResultsReceived: ToolResultOutput[][] = []
-      const stateSnapshots: PublicAgentState[] = []
-      let stepCount = 0
-
-      const mockGenerator = (function* () {
-        stepCount++
-
-        // Step 1: Read files and capture initial state
-        const step1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['src/auth.ts', 'src/config.ts'] },
-        }
-        toolResultsReceived.push(step1.toolResult)
-        stateSnapshots.push({ ...step1.agentState })
-
-        // Step 2: Search for patterns based on file content
-        const step2 = yield {
-          toolName: 'code_search',
-          input: { pattern: 'authenticate', flags: '-i' },
-        }
-        toolResultsReceived.push(step2.toolResult)
-        stateSnapshots.push({ ...step2.agentState })
-
-        // Step 3: Create a plan based on findings
-        const step3 = yield {
-          toolName: 'create_plan',
-          input: {
-            path: 'analysis-plan.md',
-            plan: 'Comprehensive analysis of authentication system',
-          },
-        }
-        toolResultsReceived.push(step3.toolResult)
-        stateSnapshots.push({ ...step3.agentState })
-
-        // Step 4: Add subgoal for tracking
-        const step4 = yield {
-          toolName: 'add_subgoal',
-          input: {
-            id: 'auth-analysis',
-            objective: 'Analyze authentication patterns',
-            status: 'IN_PROGRESS',
-            plan: 'Review auth files and create recommendations',
-          },
-        }
-        toolResultsReceived.push(step4.toolResult)
-        stateSnapshots.push({ ...step4.agentState })
-
-        // Step 5: Write analysis file
-        const step5 = yield {
-          toolName: 'write_file',
-          input: {
-            path: 'auth-analysis.md',
-            instructions: 'Create authentication analysis document',
-            content: '# Authentication Analysis\n\nBased on code review...',
-          },
-        }
-        toolResultsReceived.push(step5.toolResult)
-        stateSnapshots.push({ ...step5.agentState })
-
-        // Step 6: Update subgoal status
-        const step6 = yield {
-          toolName: 'update_subgoal',
-          input: {
-            id: 'auth-analysis',
-            status: 'COMPLETE',
-            log: 'Analysis completed successfully',
-          },
-        }
-        toolResultsReceived.push(step6.toolResult)
-        stateSnapshots.push({ ...step6.agentState })
-
-        // Step 7: Set final output with comprehensive data
-        const step7 = yield {
-          toolName: 'set_output',
-          input: {
-            status: 'success',
-            filesAnalyzed: ['src/auth.ts', 'src/config.ts'],
-            patternsFound: 3,
-            recommendations: ['Use stronger auth', 'Add 2FA'],
-            completedAt: new Date().toISOString(),
-          },
-        }
-        toolResultsReceived.push(step7.toolResult)
-        stateSnapshots.push({ ...step7.agentState })
-
-        // Step 8: Transition to STEP_ALL to continue processing
-        yield 'STEP_ALL'
-      })() as StepGenerator
-
-      // Set up comprehensive tool names for this test
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = [
-        'read_files',
-        'code_search',
-        'create_plan',
-        'add_subgoal',
-        'write_file',
-        'update_subgoal',
-        'set_output',
-        'end_turn',
-      ]
-
-      // Mock executeToolCall to simulate realistic tool results and state updates
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          const { toolName, input, toolResults, agentState } = options
-
-          let result: string
-          switch (toolName) {
-            case 'read_files':
-              result = JSON.stringify({
-                'src/auth.ts':
-                  'export function authenticate(user) { return true; }',
-                'src/config.ts': 'export const authConfig = { enabled: true };',
-              })
-              break
-            case 'code_search':
-              result =
-                'src/auth.ts:1:export function authenticate(user) {\nsrc/config.ts:1:authConfig'
-              break
-            case 'create_plan':
-              result = 'Plan created successfully at analysis-plan.md'
-              break
-            case 'add_subgoal':
-              result = 'Subgoal "auth-analysis" added successfully'
-              // Update agent state to include subgoal in agentContext
-              agentState.agentContext['auth-analysis'] = {
-                objective: 'Analyze authentication patterns',
-                status: 'IN_PROGRESS',
-                plan: 'Review auth files and create recommendations',
-                logs: [],
-              }
-              break
-            case 'write_file':
-              result = 'File written successfully: auth-analysis.md'
-              break
-            case 'update_subgoal':
-              result = 'Subgoal "auth-analysis" updated successfully'
-              // Update subgoal status in agent state
-              if (agentState.agentContext['auth-analysis']) {
-                agentState.agentContext['auth-analysis'].status = 'COMPLETE'
-                agentState.agentContext['auth-analysis'].logs.push(
-                  'Analysis completed successfully',
-                )
-              }
-              break
-            case 'set_output':
-              result = 'Output set successfully'
-              agentState.output = input
-              break
-            default:
-              result = `${toolName} executed successfully`
-          }
-
-          const toolResult: ToolMessage = {
-            role: 'tool',
-            toolName,
-            toolCallId: `${toolName}-call-id`,
-            content: [
-              {
-                type: 'json',
-                value: result,
-              },
-            ],
-          }
-          toolResults.push(toolResult)
-
-          agentState.messageHistory.push(toolResult)
-        },
-      )
-
-      // First call - should execute all tools and transition to STEP_ALL
-      const result1 = await runProgrammaticStep(mockParams)
-
-      // Verify all tools were executed
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(7) // 7 tools before STEP_ALL
-      expect(result1.endTurn).toBe(false) // Should not end turn due to STEP_ALL
-      expect(stepCount).toBe(1) // Generator should have run once
-
-      // Verify tool execution order and arguments
-      const toolCalls = executeToolCallSpy.mock.calls
-      expect(toolCalls[0][0].toolName).toBe('read_files')
-      expect(toolCalls[0][0].input.paths).toEqual([
-        'src/auth.ts',
-        'src/config.ts',
-      ])
-      expect(toolCalls[1][0].toolName).toBe('code_search')
-      expect(toolCalls[1][0].input.pattern).toBe('authenticate')
-      expect(toolCalls[2][0].toolName).toBe('create_plan')
-      expect(toolCalls[3][0].toolName).toBe('add_subgoal')
-      expect(toolCalls[4][0].toolName).toBe('write_file')
-      expect(toolCalls[5][0].toolName).toBe('update_subgoal')
-      expect(toolCalls[6][0].toolName).toBe('set_output')
-
-      // Verify tool results were passed back to generator
-      expect(toolResultsReceived).toHaveLength(7)
-      expect(JSON.stringify(toolResultsReceived[0])).toContain('authenticate')
-      expect(JSON.stringify(toolResultsReceived[3])).toContain('auth-analysis')
-      expect(JSON.stringify(toolResultsReceived[6])).toContain(
-        'Output set successfully',
-      )
-
-      // Verify state management throughout execution
-      expect(stateSnapshots).toHaveLength(7)
-      expect(Object.keys(result1.agentState.agentContext)).toContain(
-        'auth-analysis',
-      )
-      expect(result1.agentState.agentContext['auth-analysis']?.status).toBe(
-        'COMPLETE',
-      )
-      expect(result1.agentState.output).toEqual({
-        status: 'success',
-        filesAnalyzed: ['src/auth.ts', 'src/config.ts'],
-        patternsFound: 3,
-        recommendations: ['Use stronger auth', 'Add 2FA'],
-        completedAt: expect.any(String),
-      })
-
-      // Verify tool results were processed correctly
-      expect(toolResultsReceived).toHaveLength(7)
-      expect(toolResultsReceived.every((result) => result !== undefined)).toBe(
-        true,
-      )
-
-      // Verify that executeToolCall was called with agentState.messageHistory
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          agentState: expect.objectContaining({
-            messageHistory: expect.any(Array),
-          }),
-        }),
-      )
-
-      // Reset spy for second call
-      executeToolCallSpy.mockClear()
-
-      // Second call - should return early due to STEP_ALL state
-      const result2 = await runProgrammaticStep({
-        ...mockParams,
-        // Use the updated agent state from first call
-        agentState: result1.agentState,
-      })
-
-      // Verify STEP_ALL behavior
-      expect(executeToolCallSpy).not.toHaveBeenCalled() // No tools should execute
-      expect(result2.endTurn).toBe(false) // Should still not end turn
-      expect(result2.agentState.agentId).toEqual(result1.agentState.agentId) // State should be similar
-      expect(stepCount).toBe(1) // Generator should not have run again
-
-      // Third call - verify STEP_ALL state persists
-      const result3 = await runProgrammaticStep({
-        ...mockParams,
-        agentState: result2.agentState,
-      })
-
-      expect(executeToolCallSpy).not.toHaveBeenCalled()
-      expect(result3.endTurn).toBe(false)
-      expect(result3.agentState.agentId).toEqual(result1.agentState.agentId)
-      expect(stepCount).toBe(1) // Generator should still not have run again
-    })
-
-    it('should pass tool results back to generator', async () => {
-      const _toolResults: ToolMessage[] = []
-      let receivedToolResult: ToolResultOutput[] | undefined
-
-      const mockGenerator = (function* () {
-        const input1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['test.txt'] },
-        }
-        receivedToolResult = input1.toolResult
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      // Mock executeToolCall to add tool results
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'read_files') {
-            options.toolResults.push({
-              role: 'tool',
-              toolName: 'read_files',
-              toolCallId: 'test-id',
-              content: [
-                {
-                  type: 'json',
-                  value: 'file content',
-                },
-              ],
-            } satisfies ToolMessage)
-          }
-        },
-      )
-
-      await runProgrammaticStep(mockParams)
-
-      expect(receivedToolResult).toEqual([
-        {
-          type: 'json',
-          value: 'file content',
-        },
-      ])
-    })
-  })
-
-  describe('generator control flow', () => {
-    it('should handle STEP value to break execution', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield 'STEP'
-        yield {
-          toolName: 'write_file',
-          input: { path: 'test.txt', content: 'test' },
-        }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(1) // Only first tool call
-      expect(result.endTurn).toBe(false)
-    })
-
-    it('should handle generator completion', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        return // Generator completes
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-    })
-
-    it('should end turn when end_turn tool is called', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-        yield {
-          toolName: 'write_file',
-          input: { path: 'test.txt', content: 'test' },
-        } // Should not execute
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(2) // read_files + end_turn
-      expect(result.endTurn).toBe(true)
-    })
-  })
-
-  describe('state management', () => {
-    it('should preserve agent state changes', async () => {
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'set_output',
-          input: { status: 'complete' },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames.push('set_output')
-
-      // Mock executeToolCall to update state
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'set_output') {
-            options.agentState.output = { status: 'complete' }
-          }
-        },
-      )
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.agentState.output).toEqual({ status: 'complete' })
-    })
-
-    it('should preserve message history', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-      const previousMessageHistory = cloneDeep(mockAgentState.messageHistory)
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      // Verify previous messages are preserved
-      expect(result.agentState.messageHistory.length).toBeGreaterThanOrEqual(
-        previousMessageHistory.length,
-      )
-      // Check first messages match
-      expect(result.agentState.messageHistory[0]).toEqual(
-        previousMessageHistory[0],
-      )
-      expect(result.agentState.messageHistory[1]).toEqual(
-        previousMessageHistory[1],
-      )
-      // Verify an assistant message was added (with native tools, this is a tool-call structure)
-      const lastMessage =
-        result.agentState.messageHistory[
-          result.agentState.messageHistory.length - 1
-        ]
-      expect(lastMessage.role).toBe('assistant')
-      // With native tools, the tool call is structured differently than the old XML format
-      expect(lastMessage.content[0]).toMatchObject({
-        type: 'tool-call',
-        toolName: 'end_turn',
-      })
-    })
-  })
-
-  describe('error handling', () => {
-    it('should handle generator errors gracefully', async () => {
-      const mockGenerator = (function* () {
-        throw new Error('Generator error')
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain('Generator error')
-      expect(
-        responseChunks.some(
-          (chunk) =>
-            typeof chunk === 'string' && chunk.includes('Generator error'),
-        ),
-      ).toBe(true)
-    })
-
-    it('should handle tool execution errors', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      executeToolCallSpy.mockRejectedValue(new Error('Tool execution failed'))
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain('Tool execution failed')
-    })
-
-    it('should handle non-Error exceptions', async () => {
-      const mockGenerator = (function* () {
-        throw 'String error'
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain('Unknown error')
-    })
-  })
-
-  describe('output schema validation', () => {
-    it('should validate output against outputSchema when using setOutput', async () => {
-      // Create template with outputSchema
-      const schemaTemplate = {
-        ...mockTemplate,
-        outputMode: 'structured_output' as const,
-        outputSchema: {
-          type: 'object',
-          properties: {
-            message: { type: 'string' },
-            status: { type: 'string', enum: ['success', 'error'] },
-            count: { type: 'number' },
-          },
-          required: ['message', 'status'],
-        },
-        toolNames: ['set_output', 'end_turn'],
-      }
-
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'set_output',
-          input: {
-            message: 'Task completed successfully',
-            status: 'success',
-            count: 42,
-          },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      schemaTemplate.handleSteps = () => mockGenerator
-
-      // Don't mock executeToolCall - let it use the real implementation
-      executeToolCallSpy.mockRestore()
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        template: schemaTemplate as unknown as AgentTemplate,
-        localAgentTemplates: {
-          'test-agent': schemaTemplate as unknown as AgentTemplate,
-        },
-      })
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output).toEqual({
-        message: 'Task completed successfully',
-        status: 'success',
-        count: 42,
-      })
-    })
-
-    it('should handle invalid output that fails schema validation', async () => {
-      // Create template with strict outputSchema
-      const schemaTemplate = {
-        ...mockTemplate,
-        outputMode: 'structured_output' as const,
-        outputSchema: {
-          type: 'object',
-          properties: {
-            message: { type: 'string' },
-            status: { type: 'string', enum: ['success', 'error'] },
-          },
-          required: ['message', 'status'],
-        },
-        toolNames: ['set_output', 'end_turn'],
-      }
-
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'set_output',
-          input: {
-            message: 'Task completed',
-            status: 'invalid_status', // This should fail validation
-            extraField: 'not allowed',
-          },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      schemaTemplate.handleSteps = () => mockGenerator
-
-      // Don't mock executeToolCall - let it use the real implementation
-      executeToolCallSpy.mockRestore()
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        template: schemaTemplate as unknown as AgentTemplate,
-        localAgentTemplates: {
-          'test-agent': schemaTemplate as unknown as AgentTemplate,
-        },
-      })
-
-      // Should end turn (validation may fail but execution continues)
-      expect(result.endTurn).toBe(true)
-      // Test passes if no exception is thrown during execution
-      expect(result.agentState).toBeDefined()
-    })
-
-    it('should work with agents that have no outputSchema', async () => {
-      const noSchemaTemplate = {
-        ...mockTemplate,
-        outputMode: 'last_message' as const,
-        outputSchema: undefined,
-        toolNames: ['set_output', 'end_turn'],
-      }
-
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'set_output',
-          input: {
-            anyField: 'any value',
-            anotherField: 123,
-          },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      noSchemaTemplate.handleSteps = () => mockGenerator
-
-      // Don't mock executeToolCall - let it use the real implementation
-      executeToolCallSpy.mockRestore()
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        template: noSchemaTemplate,
-        localAgentTemplates: { 'test-agent': noSchemaTemplate },
-      })
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output).toEqual({
-        anyField: 'any value',
-        anotherField: 123,
-      })
-    })
-
-    it('should work with outputMode structured_output but no outputSchema defined', async () => {
-      const schemaWithoutSchemaTemplate = {
-        ...mockTemplate,
-        outputMode: 'structured_output' as const,
-        outputSchema: undefined, // No schema defined
-        toolNames: ['set_output', 'end_turn'],
-      }
-
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'set_output',
-          input: {
-            result: 'success',
-            data: { count: 5 },
-          },
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      schemaWithoutSchemaTemplate.handleSteps = () => mockGenerator
-
-      // Don't mock executeToolCall - let it use the real implementation
-      executeToolCallSpy.mockRestore()
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        template: schemaWithoutSchemaTemplate,
-        localAgentTemplates: { 'test-agent': schemaWithoutSchemaTemplate },
-      })
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output).toEqual({
-        result: 'success',
-        data: { count: 5 },
-      })
-    })
-  })
-
-  describe('stepsComplete parameter', () => {
-    it('should pass stepsComplete=false by default', async () => {
-      let receivedStepsComplete: boolean | undefined
-
-      const mockGenerator = (function* () {
-        const input = yield {
-          toolName: 'read_files',
-          input: { paths: ['test.txt'] },
-        }
-        receivedStepsComplete = input.stepsComplete
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: false,
-      })
-
-      expect(receivedStepsComplete).toBe(false)
-    })
-
-    it('should pass stepsComplete=true when specified', async () => {
-      let receivedStepsComplete: boolean | undefined
-
-      const mockGenerator = (function* () {
-        const input = yield {
-          toolName: 'read_files',
-          input: { paths: ['test.txt'] },
-        }
-        receivedStepsComplete = input.stepsComplete
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: true,
-      })
-
-      expect(receivedStepsComplete).toBe(true)
-    })
-
-    it('should handle post-processing when stepsComplete=true', async () => {
-      const executionLog: string[] = []
-
-      const mockGenerator = (function* () {
-        const step1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['file1.txt'] },
-        }
-        executionLog.push(`step1: stepsComplete=${step1.stepsComplete}`)
-
-        if (step1.stepsComplete) {
-          // Post-processing step
-          executionLog.push('performing post-processing')
-          yield {
-            toolName: 'set_output',
-            input: { message: 'Post-processing completed' },
-          }
-        }
-
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = ['read_files', 'set_output', 'end_turn']
-
-      // Mock executeToolCall to update state for set_output
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'set_output') {
-            options.agentState.output = options.input
-          }
-        },
-      )
-
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: true,
-      })
-
-      expect(executionLog).toEqual([
-        'step1: stepsComplete=true',
-        'performing post-processing',
-      ])
-      expect(result.agentState.output).toEqual({
-        message: 'Post-processing completed',
-      })
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(3) // read_files + set_output + end_turn
-    })
-
-    it('should clear STEP_ALL mode when stepsComplete=true', async () => {
-      // First, set up a generator that will be marked as STEP_ALL
-      let generatorCallCount = 0
-      const createGenerator = () => {
-        generatorCallCount++
-        if (generatorCallCount === 1) {
-          return (function* () {
-            yield 'STEP_ALL'
-          })() as StepGenerator
-        } else {
-          return (function* () {
-            yield {
-              toolName: 'set_output',
-              input: { status: 'finalized' },
-            }
-            yield { toolName: 'end_turn', input: {} }
-          })() as StepGenerator
-        }
-      }
-
-      mockTemplate.handleSteps = createGenerator
-      mockTemplate.toolNames = ['set_output', 'end_turn']
-
-      // First call to set STEP_ALL state
-      const result1 = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: false,
-      })
-      expect(result1.endTurn).toBe(false)
-      expect(generatorCallCount).toBe(1)
-
-      // Second call with stepsComplete=false should return early due to STEP_ALL
-      const result2 = await runProgrammaticStep({
-        ...mockParams,
-        agentState: result1.agentState,
-        stepsComplete: false,
-      })
-      expect(result2.endTurn).toBe(false)
-      expect(generatorCallCount).toBe(1) // Should not create new generator
-
-      // Third call with stepsComplete=true should clear STEP_ALL and continue with existing generator
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'set_output') {
-            options.agentState.output = options.input
-          }
-        },
-      )
-
-      const result3 = await runProgrammaticStep({
-        ...mockParams,
-        agentState: result2.agentState,
-        stepsComplete: true,
-      })
-
-      expect(result3.endTurn).toBe(true)
-      // The existing generator continues execution rather than creating a new one
-      expect(generatorCallCount).toBe(1)
-    })
-  })
-
-  describe('continued stepping after completion', () => {
-    it('should allow agent to continue with STEP after initial completion', async () => {
-      const executionSteps: string[] = []
-
-      const mockGenerator = (function* () {
-        executionSteps.push('initial execution')
-        const step1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['config.txt'] },
-        }
-
-        if (step1.stepsComplete) {
-          executionSteps.push('post-processing detected')
-          yield {
-            toolName: 'write_file',
-            input: {
-              path: 'summary.txt',
-              instructions: 'Create summary',
-              content: 'Processing completed',
-            },
-          }
-
-          // Force agent to continue with another step
-          executionSteps.push('requesting continuation')
-          const step2 = yield 'STEP'
-          executionSteps.push(`step2: stepsComplete=${step2.stepsComplete}`)
-
-          if (!step2.stepsComplete) {
-            yield {
-              toolName: 'set_output',
-              input: { message: 'Continued processing' },
-            }
-          }
-        }
-
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = [
-        'read_files',
-        'write_file',
-        'set_output',
-        'end_turn',
-      ]
-
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'set_output') {
-            options.agentState.output = options.input
-          }
-        },
-      )
-
-      // First call with stepsComplete=true (post-processing mode)
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: true,
-      })
-
-      expect(executionSteps).toEqual([
-        'initial execution',
-        'post-processing detected',
-        'requesting continuation',
-      ])
-      expect(result.endTurn).toBe(false) // Should not end due to STEP
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(2) // read_files + write_file
-
-      const finalResult = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: false,
-      })
-
-      expect(executionSteps).toEqual([
-        'initial execution',
-        'post-processing detected',
-        'requesting continuation',
-        'step2: stepsComplete=false',
-      ])
-      expect(finalResult.endTurn).toBe(true) // Should end from end_turn
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(4) // read_files + write_file + set_output + end_turn
-    })
-
-    it('should allow agent to continue with STEP_ALL after initial completion', async () => {
-      const executionSteps: string[] = []
-
-      const mockGenerator = (function* () {
-        executionSteps.push('initial execution')
-        const step1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['data.txt'] },
-        }
-
-        if (step1.stepsComplete) {
-          executionSteps.push('post-processing with STEP_ALL')
-          yield {
-            toolName: 'write_file',
-            input: {
-              path: 'processed.txt',
-              instructions: 'Create processed file',
-              content: 'Data processed',
-            },
-          }
-
-          // Force agent to continue with STEP_ALL
-          yield 'STEP_ALL'
-          executionSteps.push('STEP_ALL requested')
-        }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = ['read_files', 'write_file', 'end_turn']
-
-      // First call with stepsComplete=true
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: true,
-      })
-
-      expect(executionSteps).toEqual([
-        'initial execution',
-        'post-processing with STEP_ALL',
-      ])
-      expect(result.endTurn).toBe(false) // Should not end due to STEP_ALL
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(2) // read_files + write_file
-    })
-
-    it('should handle complex post-processing workflow', async () => {
-      const workflowSteps: string[] = []
-      let stepCount = 0
-
-      const mockGenerator = (function* () {
-        stepCount++
-        workflowSteps.push(`generator run ${stepCount}`)
-
-        // Initial processing
-        const step1 = yield {
-          toolName: 'read_files',
-          input: { paths: ['input.txt'] },
-        }
-        workflowSteps.push(
-          `read completed, stepsComplete=${step1.stepsComplete}`,
-        )
-
-        if (step1.stepsComplete) {
-          // Post-processing phase
-          workflowSteps.push('entering post-processing')
-
-          // Analyze the input
-          yield {
-            toolName: 'code_search',
-            input: { pattern: 'TODO', flags: '-n' },
-          }
-
-          // Create analysis report
-          yield {
-            toolName: 'write_file',
-            input: {
-              path: 'analysis.md',
-              instructions: 'Create analysis report',
-              content: '# Analysis Report\n\nTODO items found.',
-            },
-          }
-
-          // Add subgoal for tracking
-          yield {
-            toolName: 'add_subgoal',
-            input: {
-              id: 'analysis-complete',
-              objective: 'Complete post-processing analysis',
-              status: 'COMPLETE',
-            },
-          }
-
-          // Set final output
-          yield {
-            toolName: 'set_output',
-            input: {
-              phase: 'post-processing',
-              analysisCreated: true,
-              subgoalAdded: true,
-            },
-          }
-
-          // Continue for more processing
-          const step2 = yield 'STEP'
-          workflowSteps.push(
-            `step after STEP: stepsComplete=${step2.stepsComplete}`,
-          )
-
-          if (step2.stepsComplete) {
-            // Final cleanup
-            yield {
-              toolName: 'update_subgoal',
-              input: {
-                id: 'analysis-complete',
-                log: 'All post-processing completed',
-              },
-            }
-          }
-        } else {
-          // Normal processing
-          workflowSteps.push('normal processing mode')
-          yield {
-            toolName: 'set_output',
-            input: { phase: 'normal', message: 'Regular processing' },
-          }
-        }
-
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-      mockTemplate.toolNames = [
-        'read_files',
-        'code_search',
-        'write_file',
-        'add_subgoal',
-        'set_output',
-        'update_subgoal',
-        'end_turn',
-      ]
-
-      executeToolCallSpy.mockImplementation(
-        async (
-          options: ParamsOf<typeof executeToolCall>,
-        ): ReturnType<typeof executeToolCall> => {
-          if (options.toolName === 'set_output') {
-            options.agentState.output = options.input
-          } else if (options.toolName === 'add_subgoal') {
-            options.agentState.agentContext[options.input.id as string] = {
-              ...options.input,
-              logs: [],
-            }
-          }
-        },
-      )
-
-      // Call with stepsComplete=true to trigger post-processing
-      const result = await runProgrammaticStep({
-        ...mockParams,
-        stepsComplete: true,
-      })
-
-      expect(workflowSteps).toEqual([
-        'generator run 1',
-        'read completed, stepsComplete=true',
-        'entering post-processing',
-      ])
-
-      expect(result.endTurn).toBe(false) // Should not end due to STEP
-      expect(result.agentState.output).toEqual({
-        phase: 'post-processing',
-        analysisCreated: true,
-        subgoalAdded: true,
-      })
-      expect(result.agentState.agentContext['analysis-complete']).toBeDefined()
-      expect(executeToolCallSpy).toHaveBeenCalledTimes(5) // read_files, code_search, write_file, add_subgoal, set_output
-    })
-  })
-
-  describe('yield value validation', () => {
-    it('should reject invalid yield values', async () => {
-      const mockGenerator = (function* () {
-        yield { invalid: 'value' } as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject yield values with wrong types', async () => {
-      const mockGenerator = (function* () {
-        yield { type: 'STEP_TEXT', text: 123 } as unknown // text should be string
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject GENERATE_N with non-positive n', async () => {
-      const mockGenerator = (function* () {
-        yield { type: 'GENERATE_N', n: 0 } as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject GENERATE_N with negative n', async () => {
-      const mockGenerator = (function* () {
-        yield { type: 'GENERATE_N', n: -5 } as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const responseChunks: unknown[] = []
-      mockParams.onResponseChunk = (chunk) => responseChunks.push(chunk)
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should accept valid STEP literal', async () => {
-      const mockGenerator = (function* () {
-        yield 'STEP'
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(false)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should accept valid STEP_ALL literal', async () => {
-      const mockGenerator = (function* () {
-        yield 'STEP_ALL'
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(false)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should accept valid STEP_TEXT object and continue to next step', async () => {
-      // STEP_TEXT continues to the next step of handleSteps (unlike STEP which breaks)
-      // So we need additional yields after STEP_TEXT to test the continuation
-      const mockGenerator = (function* () {
-        yield { type: 'STEP_TEXT', text: 'Custom response text' }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      // Should end turn because the generator continues after STEP_TEXT and reaches end_turn
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should accept valid GENERATE_N object', async () => {
-      const mockGenerator = (function* () {
-        yield { type: 'GENERATE_N', n: 3 }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(false)
-      expect(result.generateN).toBe(3)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should accept valid tool call object', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should accept tool call with includeToolCall option', async () => {
-      const mockGenerator = (function* () {
-        yield {
-          toolName: 'read_files',
-          input: { paths: ['test.txt'] },
-          includeToolCall: false,
-        }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toBeUndefined()
-    })
-
-    it('should reject random string values', async () => {
-      const mockGenerator = (function* () {
-        yield 'INVALID_STEP' as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject null yield values', async () => {
-      const mockGenerator = (function* () {
-        yield null as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject undefined yield values', async () => {
-      const mockGenerator = (function* () {
-        yield undefined as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject tool call without toolName', async () => {
-      const mockGenerator = (function* () {
-        yield { input: { paths: ['test.txt'] } } as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-
-    it('should reject tool call without input', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files' } as unknown
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      const result = await runProgrammaticStep(mockParams)
-
-      expect(result.endTurn).toBe(true)
-      expect(result.agentState.output?.error).toContain(
-        'Invalid yield value from handleSteps',
-      )
-    })
-  })
-
-  describe('logging and context', () => {
-    it('should log agent execution start', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      await runProgrammaticStep(mockParams)
-
-      // Logger is mocked, but we can verify the function completes without error
-      expect(true).toBe(true)
-    })
-
-    it('should generate unique agent step ID', async () => {
-      const mockGenerator = (function* () {
-        yield { toolName: 'read_files', input: { paths: ['test.txt'] } }
-        yield { toolName: 'end_turn', input: {} }
-      })() as StepGenerator
-
-      mockTemplate.handleSteps = () => mockGenerator
-
-      await runProgrammaticStep(mockParams)
-
-      expect(executeToolCallSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          agentStepId: 'mock-uuid-0000-0000-0000-000000000000',
-        }),
-      )
-    })
-  })
-})