@things-factory/board-ai 10.0.18 → 10.1.0

package/server/service/agentic-loop.test.ts

@@ -1,859 +0,0 @@
-/**
- * agentic-loop 단위 테스트 — mock chat + mock dispatch helper 로 isolation.
- *
- * assistant.ts 의 transitive import (board-import → @aws-sdk → @nodable/entities)
- * 를 우회하므로 빠르고 안정적. loop 의 *제어 흐름* 만 검증.
- */
-import {
-  runAgenticLoop,
-  type ToolDispatchHelpers,
-  type AgenticLoopInput
-} from './agentic-loop'
-import type { AIToolChatResult, AIToolCall } from '@things-factory/ai-client-base'
-
-// ── helpers ─────────────────────────────────────────────────────
-
-const TC = (name: string, args: any = {}, id = 't1'): AIToolCall =>
-  ({ id, name, arguments: args, type: 'tool_use' } as any)
-
-const okResult = (text?: string, toolCalls: AIToolCall[] = []): AIToolChatResult => ({
-  text,
-  toolCalls,
-  stopReason: toolCalls.length > 0 ? 'tool_use' : 'end_turn',
-  usage: undefined as any
-})
-
-const baseDispatch = (overrides: Partial<ToolDispatchHelpers> = {}): ToolDispatchHelpers => ({
-  isReadTool: () => false,
-  isWriteTool: () => false,
-  isActionTool: () => false,
-  executeReadTool: () => ({ stub: true }),
-  validateWriteToolCall: () => ({ valid: true }),
-  toolCallToBoardActionOp: () => null,
-  summarizeToolResult: v => v,
-  ...overrides
-})
-
-const mkInput = (
-  overrides: Partial<AgenticLoopInput> = {},
-  dispatchOverrides: Partial<ToolDispatchHelpers> = {}
-): AgenticLoopInput => ({
-  initialConversation: [{ role: 'user', content: 'hi' }],
-  tools: [],
-  options: { systemPrompt: 'you are a bot' },
-  chat: async () => okResult('default reply'),
-  dispatch: baseDispatch(dispatchOverrides),
-  currentBoard: undefined,
-  selectedRefids: [],
-  ...overrides
-})
-
-// ── Tests ───────────────────────────────────────────────────────
-
-describe('runAgenticLoop — 단일 turn (no tool calls)', () => {
-  test('LLM 이 텍스트만 반환 → 즉시 종료', async () => {
-    const input = mkInput({ chat: async () => okResult('완료') })
-    const r = await runAgenticLoop(input)
-    expect(r.lastText).toBe('완료')
-    expect(r.accumulatedWriteCalls).toEqual([])
-    expect(r.toolUsages).toEqual([])
-    expect(r.stopReason).toBe('end_turn')
-  })
-
-  test('빈 reply + 빈 toolCalls — 그래도 정상 종료', async () => {
-    const input = mkInput({ chat: async () => okResult() })
-    const r = await runAgenticLoop(input)
-    expect(r.lastText).toBeUndefined()
-    expect(r.accumulatedWriteCalls).toEqual([])
-  })
-})
-
-describe('runAgenticLoop — read tool 처리', () => {
-  test('read tool 호출 → executeReadTool 실행 → 결과 회신 후 LLM 추론 계속', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          if (callCount === 1) {
-            return okResult(undefined, [TC('getSelection', {})])
-          }
-          return okResult('finished')
-        }
-      },
-      {
-        isReadTool: name => name === 'getSelection',
-        executeReadTool: tc => ({ called: tc.name, refids: [1, 2] })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(2)
-    expect(r.lastText).toBe('finished')
-    expect(r.toolUsages).toHaveLength(1)
-    expect(r.toolUsages[0]).toMatchObject({
-      name: 'getSelection',
-      kind: 'read',
-      result: { called: 'getSelection', refids: [1, 2] }
-    })
-  })
-
-  test('read tool 결과가 다음 turn 의 conversation 에 포함', async () => {
-    const conversations: any[] = []
-    const input = mkInput(
-      {
-        chat: async msgs => {
-          conversations.push(msgs)
-          if (conversations.length === 1) return okResult(undefined, [TC('getX')])
-          return okResult('done')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({ data: 'x' })
-      }
-    )
-    await runAgenticLoop(input)
-    // 두 번째 호출 시 conversation 에 assistant tool_use + user tool_result 가 있어야
-    expect(conversations).toHaveLength(2)
-    const second = conversations[1]
-    expect(second.length).toBeGreaterThan(2)  // 최소 user / assistant / user
-    const lastMsg = second[second.length - 1]
-    expect(lastMsg.role).toBe('user')
-    expect(lastMsg.content[0]).toMatchObject({
-      type: 'tool_result',
-      toolUseId: 't1'
-    })
-    expect(JSON.parse(lastMsg.content[0].content)).toEqual({ data: 'x' })
-  })
-
-  test('summarizeToolResult 가 result 를 변환', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('listX')])
-            : okResult('end')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({ items: Array(100).fill('x') }),
-        summarizeToolResult: v => ({ summary: 'truncated', count: v.items.length })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.toolUsages[0].result).toEqual({ summary: 'truncated', count: 100 })
-  })
-})
-
-describe('runAgenticLoop — write tool 처리', () => {
-  test('정상 write — 누적 + queued 결과 회신', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('setFill', { refids: [1] })])
-            : okResult('변경했습니다')
-        }
-      },
-      {
-        isWriteTool: name => name === 'setFill',
-        validateWriteToolCall: () => ({ valid: true })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.accumulatedWriteCalls).toHaveLength(1)
-    expect(r.accumulatedWriteCalls[0].name).toBe('setFill')
-    expect(r.toolUsages[0]).toMatchObject({
-      name: 'setFill',
-      kind: 'write',
-      result: { queued: true }
-    })
-  })
-
-  test('validation 실패 — 누적 안 됨, error 회신', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('setFill', {})])
-            : okResult('failed')
-        }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: () => ({
-          valid: false,
-          errors: [{ msg: 'refids missing' }],
-          suggestion: 'add refids array'
-        })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.accumulatedWriteCalls).toEqual([])
-    expect(r.toolUsages[0].result).toMatchObject({
-      error: 'Tool args failed validation',
-      issues: [{ msg: 'refids missing' }],
-      suggestion: 'add refids array'
-    })
-  })
-
-  test('일부는 valid, 일부는 invalid — 부분 누적', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [
-                TC('setFill', { refids: [1] }, 't1'),
-                TC('setStroke', {}, 't2')
-              ])
-            : okResult('mixed')
-        }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: tc =>
-          tc.name === 'setFill' ? { valid: true } : { valid: false, errors: ['bad'] }
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.accumulatedWriteCalls).toHaveLength(1)
-    expect(r.accumulatedWriteCalls[0].name).toBe('setFill')
-    expect(r.toolUsages).toHaveLength(2)
-  })
-})
-
-describe('runAgenticLoop — action tool 처리', () => {
-  test('action tool — accumulatedActions 에 분리 누적', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('selectComponents', { refids: [7] })])
-            : okResult('selected')
-        }
-      },
-      {
-        isActionTool: name => name === 'selectComponents',
-        toolCallToBoardActionOp: tc => ({
-          action: 'selectComponents',
-          refids: tc.arguments.refids
-        }) as any
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.accumulatedActions).toHaveLength(1)
-    expect(r.accumulatedActions[0]).toMatchObject({
-      action: 'selectComponents',
-      refids: [7]
-    })
-    expect(r.accumulatedWriteCalls).toEqual([])
-  })
-
-  test('toolCallToBoardActionOp 가 null 반환 — actions 안 누적', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('badAction', {})])
-            : okResult('done')
-        }
-      },
-      {
-        isActionTool: () => true,
-        toolCallToBoardActionOp: () => null
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.accumulatedActions).toEqual([])
-    // 그래도 toolUsages 에는 기록 (queued)
-    expect(r.toolUsages).toHaveLength(1)
-  })
-})
-
-describe('runAgenticLoop — unknown tool 처리', () => {
-  test('어떤 분류에도 안 맞음 → error 결과', async () => {
-    let callCount = 0
-    const input = mkInput({
-      chat: async () => {
-        callCount++
-        return callCount === 1
-          ? okResult(undefined, [TC('mysteryTool', {})])
-          : okResult('weird')
-      }
-    })
-    const r = await runAgenticLoop(input)
-    expect(r.toolUsages[0]).toMatchObject({
-      name: 'mysteryTool',
-      kind: 'unknown',
-      result: { error: 'Unknown tool: mysteryTool' }
-    })
-  })
-})
-
-describe('runAgenticLoop — iteration cap', () => {
-  test('LLM 이 계속 tool 호출 → maxIterations 도달 시 종료', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          // 매번 read tool 호출 — 무한 루프 가능 시나리오
-          return okResult(undefined, [TC('endless')])
-        },
-        options: { systemPrompt: 'x', maxIterations: 3 }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({ ok: true })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(3)
-    expect(r.toolUsages).toHaveLength(3)
-  })
-
-  test('기본 maxIterations 8', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return okResult(undefined, [TC('endless')])
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({})
-      }
-    )
-    await runAgenticLoop(input)
-    expect(callCount).toBe(8)
-  })
-})
-
-describe('runAgenticLoop — providerMeta round-trip (Gemini thoughtSignature 등)', () => {
-  test('tool_use 메시지에 providerMeta 포함', async () => {
-    let secondMessages: any[] = []
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async messages => {
-          callCount++
-          if (callCount === 1) {
-            return okResult(undefined, [
-              {
-                ...TC('getX'),
-                providerMeta: { thoughtSignature: 'gem-12345' }
-              } as any
-            ])
-          }
-          secondMessages = messages
-          return okResult('end')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({})
-      }
-    )
-    await runAgenticLoop(input)
-    // assistant turn 의 tool_use content 에 providerMeta 가 살아있어야
-    const assistantMsg = secondMessages.find(m => m.role === 'assistant')
-    expect(assistantMsg).toBeDefined()
-    expect(assistantMsg.content[0]).toMatchObject({
-      type: 'tool_use',
-      providerMeta: { thoughtSignature: 'gem-12345' }
-    })
-  })
-})
-
-describe('runAgenticLoop — error boundary (provider 예외)', () => {
-  test('provider 가 throw → abortReason: provider_error + graceful 종료', async () => {
-    const input = mkInput({
-      chat: async () => {
-        throw new Error('upstream timeout')
-      }
-    })
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toEqual({
-      type: 'provider_error',
-      message: 'upstream timeout',
-      iter: 0
-    })
-    expect(r.accumulatedWriteCalls).toEqual([])
-    expect(r.toolUsages).toEqual([])
-  })
-
-  test('두 번째 iteration 에서 throw — 첫 iter 결과는 보존', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          if (callCount === 1) return okResult(undefined, [TC('getX')])
-          throw new Error('500')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({ data: 'ok' })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toMatchObject({ type: 'provider_error', iter: 1 })
-    // 첫 iter 의 read tool usage 는 보존
-    expect(r.toolUsages).toHaveLength(1)
-    expect(r.toolUsages[0].name).toBe('getX')
-  })
-
-  test('AbortError 는 별도 분류 (provider_error 아님)', async () => {
-    const err = new Error('aborted')
-    ;(err as any).name = 'AbortError'
-    const input = mkInput({
-      chat: async () => {
-        throw err
-      }
-    })
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toEqual({ type: 'aborted', iter: 0 })
-  })
-})
-
-describe('runAgenticLoop — AbortSignal', () => {
-  test('이미 abort 된 신호 — 첫 iteration 도 안 돔', async () => {
-    const ctrl = new AbortController()
-    ctrl.abort()
-    let chatCalled = false
-    const input = mkInput({
-      options: { systemPrompt: 'x', signal: ctrl.signal },
-      chat: async () => {
-        chatCalled = true
-        return okResult('should-not-reach')
-      }
-    })
-    const r = await runAgenticLoop(input)
-    expect(chatCalled).toBe(false)
-    expect(r.abortReason).toEqual({ type: 'aborted', iter: 0 })
-  })
-
-  test('iteration 중간에 abort — 다음 iter 시작 시 종료', async () => {
-    const ctrl = new AbortController()
-    let callCount = 0
-    const input = mkInput(
-      {
-        options: { systemPrompt: 'x', signal: ctrl.signal },
-        chat: async () => {
-          callCount++
-          if (callCount === 1) {
-            ctrl.abort()  // 첫 iter 후 abort
-            return okResult(undefined, [TC('getX')])
-          }
-          return okResult('end')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({})
-      }
-    )
-    const r = await runAgenticLoop(input)
-    // 두 번째 iter 시작 전 abort 감지 → 1번만 호출됨
-    expect(callCount).toBe(1)
-    expect(r.abortReason).toEqual({ type: 'aborted', iter: 1 })
-    // 첫 iter 결과는 보존
-    expect(r.toolUsages).toHaveLength(1)
-  })
-
-  test('signal 이 chat 호출에 전달', async () => {
-    const ctrl = new AbortController()
-    let receivedSignal: any
-    const input = mkInput({
-      options: { systemPrompt: 'x', signal: ctrl.signal },
-      chat: async (_msgs, _tools, opts) => {
-        receivedSignal = opts.signal
-        return okResult('done')
-      }
-    })
-    await runAgenticLoop(input)
-    expect(receivedSignal).toBe(ctrl.signal)
-  })
-})
-
-describe('runAgenticLoop — repeated validation failure 조기 종료', () => {
-  test('같은 tool 3회 연속 fail — 3번째 fail 후 abort', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          // 매번 같은 tool 을 같은 invalid args 로 호출
-          return okResult(undefined, [TC('setFill', { bad: true })])
-        }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: () => ({ valid: false, errors: ['always fails'] })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(3)  // 3 회까지 호출 후 abort
-    expect(r.abortReason).toEqual({
-      type: 'repeated_validation_failure',
-      toolName: 'setFill',
-      consecutive: 3,
-      iter: 2
-    })
-  })
-
-  test('limit 설정 (2) — 2회 연속 fail 시 abort', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return okResult(undefined, [TC('setFill', {})])
-        },
-        options: { systemPrompt: 'x', repeatedFailureLimit: 2 }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: () => ({ valid: false, errors: ['x'] })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(2)
-    expect((r.abortReason as any)?.consecutive).toBe(2)
-  })
-
-  test('다른 tool 로 fail 전환 — 카운터 reset', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          // 1: setFill fail, 2: setFill fail, 3: setStroke fail (다른 tool)
-          // 3 에서 reset 되어 limit 도달 안 함, 4 에서 success 종료
-          if (callCount === 1) return okResult(undefined, [TC('setFill', {})])
-          if (callCount === 2) return okResult(undefined, [TC('setFill', {})])
-          if (callCount === 3) return okResult(undefined, [TC('setStroke', {})])
-          return okResult('end')
-        }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: () => ({ valid: false, errors: ['x'] })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(4)
-    expect(r.abortReason).toBeUndefined()
-  })
-
-  test('성공 사이에 끼어든 fail — 카운터 reset', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          // 1: fail, 2: success (read tool), 3: fail, 4: end
-          if (callCount === 1) return okResult(undefined, [TC('setFill', {})])
-          if (callCount === 2) return okResult(undefined, [TC('getX')])
-          if (callCount === 3) return okResult(undefined, [TC('setFill', {})])
-          return okResult('end')
-        }
-      },
-      {
-        isReadTool: name => name === 'getX',
-        isWriteTool: name => name === 'setFill',
-        executeReadTool: () => ({}),
-        validateWriteToolCall: () => ({ valid: false, errors: ['x'] })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(callCount).toBe(4)
-    expect(r.abortReason).toBeUndefined()
-  })
-
-  test('valid succeed → 정상 종료, abortReason undefined', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('setFill', { refids: [1] })])
-            : okResult('done')
-        }
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: () => ({ valid: true })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toBeUndefined()
-    expect(r.accumulatedWriteCalls).toHaveLength(1)
-  })
-})
-
-describe('runAgenticLoop — max iterations 표면화', () => {
-  test('max iterations 도달 시 abortReason: max_iterations', async () => {
-    const input = mkInput(
-      {
-        chat: async () => okResult(undefined, [TC('endless')]),
-        options: { systemPrompt: 'x', maxIterations: 2 }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({})
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toEqual({ type: 'max_iterations', iter: 2 })
-  })
-
-  test('정상 종료 (toolCalls 비어 break) 시 abortReason undefined', async () => {
-    const input = mkInput({ chat: async () => okResult('end') })
-    const r = await runAgenticLoop(input)
-    expect(r.abortReason).toBeUndefined()
-  })
-})
-
-describe('runAgenticLoop — signal 이 chat 호출에 전달', () => {
-  test('signal undefined 시 chat opts.signal 도 undefined', async () => {
-    let receivedSignal: any = 'unset'
-    const input = mkInput({
-      chat: async (_msgs, _tools, opts) => {
-        receivedSignal = opts.signal
-        return okResult('done')
-      }
-    })
-    await runAgenticLoop(input)
-    expect(receivedSignal).toBeUndefined()
-  })
-})
-
-describe('runAgenticLoop — currentBoard / selectedRefids 전달', () => {
-  test('executeReadTool 에 board / selection 그대로 전달', async () => {
-    const board = { width: 100, height: 100, components: [{ refid: 1 }] } as any
-    let received: any
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('peek')])
-            : okResult('done')
-        },
-        currentBoard: board,
-        selectedRefids: [1]
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: (tc, b, refids) => {
-          received = { tcName: tc.name, board: b, refids }
-          return {}
-        }
-      }
-    )
-    await runAgenticLoop(input)
-    expect(received).toEqual({
-      tcName: 'peek',
-      board,
-      refids: [1]
-    })
-  })
-
-  test('write tool 의 validation 에 components 전달', async () => {
-    let callCount = 0
-    let receivedComponents: any
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1
-            ? okResult(undefined, [TC('setFill', {})])
-            : okResult('done')
-        },
-        currentBoard: { width: 10, height: 10, components: [{ refid: 7 }] } as any
-      },
-      {
-        isWriteTool: () => true,
-        validateWriteToolCall: (_tc, components) => {
-          receivedComponents = components
-          return { valid: true }
-        }
-      }
-    )
-    await runAgenticLoop(input)
-    expect(receivedComponents).toEqual([{ refid: 7 }])
-  })
-})
-
-describe('runAgenticLoop — 접지 근거 수집', () => {
-  test('도구 결과 원문을 groundedTexts 에 담는다 — 압축본(toolUsages.result)이 아니라 원문이어야 한다', async () => {
-    let callCount = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          callCount++
-          return callCount === 1 ? okResult(undefined, [TC('getTwinStructure', {})]) : okResult('done')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] }),
-        /* 표시용 압축이 식별자를 잘라내도 근거는 온전해야 한다. */
-        summarizeToolResult: () => ({ nodes: '…(생략)' })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.groundedTexts).toEqual([JSON.stringify({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] })])
-    expect(r.toolUsages[0].result).toEqual({ nodes: '…(생략)' })
-  })
-
-  test('도구를 부르지 않으면 근거가 비어 있다 — 그 답은 접지될 수 없다', async () => {
-    const r = await runAgenticLoop(mkInput({ chat: async () => okResult('바쁘게 움직이고 있습니다') }))
-    expect(r.groundedTexts).toEqual([])
-  })
-})
-
-describe('runAgenticLoop — 첫 턴 도구 강제(근거 없는 단언 차단)', () => {
-  /** 각 iteration 의 toolChoice 를 기록하는 mock. */
-  const recordChoices = (turns: number) => {
-    const choices: any[] = []
-    let i = 0
-    return {
-      choices,
-      chat: async (_m: any, _t: any, opts: any) => {
-        choices.push(opts.toolChoice)
-        i++
-        return i < turns ? okResult(undefined, [TC('getSelection', {})]) : okResult('done')
-      }
-    }
-  }
-
-  test('켜면 첫 턴만 required, 두 번째부터 auto — 조회 결과를 받고도 또 부르지 않게', async () => {
-    const rec = recordChoices(2)
-    await runAgenticLoop(
-      mkInput(
-        { chat: rec.chat, options: { systemPrompt: 'x', requireToolOnFirstTurn: true } },
-        { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) }
-      )
-    )
-    expect(rec.choices).toEqual(['required', 'auto'])
-  })
-
-  test('끄면 기존 그대로 auto — 라이브 상태를 다루지 않는 대화면은 강제하지 않는다', async () => {
-    const rec = recordChoices(2)
-    await runAgenticLoop(
-      mkInput({ chat: rec.chat }, { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) })
-    )
-    expect(rec.choices).toEqual(['auto', 'auto'])
-  })
-})
-
-describe('runAgenticLoop — 제안 채널(실행은 사용자)', () => {
-  test('도구 결과에 proposed:true 가 있으면 제안으로 올린다 — 대화면이 실행 버튼을 그릴 근거', async () => {
-    let i = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          i++
-          return i === 1 ? okResult(undefined, [TC('proposeAction', { command: 'order.hold' })]) : okResult('확인해 주세요')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: () => ({
-          proposed: true,
-          command: 'order.hold',
-          args: { orderId: 'o7' },
-          label: 'o7 보류',
-          instanceId: 'busan-wms'
-        })
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.proposals).toHaveLength(1)
-    expect(r.proposals[0]).toMatchObject({ tool: 'proposeAction', command: 'order.hold', instanceId: 'busan-wms' })
-  })
-
-  test('평범한 조회 결과는 제안이 아니다 — 규약은 proposed 플래그 하나뿐', async () => {
-    const r = await runAgenticLoop(
-      mkInput(
-        {
-          chat: async () => okResult('상태 정상')
-        },
-        { isReadTool: () => true, executeReadTool: () => ({ occupancy: 0 }) }
-      )
-    )
-    expect(r.proposals).toEqual([])
-  })
-})
-
-describe('runAgenticLoop — 같은 조치는 한 번만 제안된다', () => {
-  /* 실제 사고: 모델이 같은 조치를 두 번 제안했고(하나는 인자가 비어 있었다) 카드가 둘 떴다.
-   * 하나를 실행한 뒤에도 나머지가 살아 있어 **같은 명령을 두 번** 보낼 수 있었다. */
-  test('효과가 같은 제안은 하나로 접는다 — 설명 문구가 달라도 같은 조치다', async () => {
-    let i = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          i++
-          return i === 1
-            ? okResult(undefined, [TC('proposeAction', { n: 1 }, 'p1'), TC('proposeAction', { n: 2 }, 'p2')])
-            : okResult('확인해 주세요')
-        }
-      },
-      {
-        isReadTool: () => true,
-        /* 같은 명령·같은 인자(키 순서만 다름), 설명만 다르게 — 같은 조치다. */
-        executeReadTool: (tc: any) =>
-          tc.id === 'p1'
-            ? { proposed: true, command: 'resource.add', instanceId: 'w1', args: { kind: 'fk', count: 3 }, label: 'A', reason: '가' }
-            : { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 3, kind: 'fk' }, label: 'B', reason: '나' }
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.proposals).toHaveLength(1)
-    expect(r.proposals[0].label).toBe('A') // 먼저 온 것을 남긴다
-  })
-
-  test('효과가 다르면 각각 남는다 — 서로 다른 결정이다', async () => {
-    let i = 0
-    const input = mkInput(
-      {
-        chat: async () => {
-          i++
-          return i === 1
-            ? okResult(undefined, [TC('proposeAction', {}, 'p1'), TC('proposeAction', {}, 'p2')])
-            : okResult('확인')
-        }
-      },
-      {
-        isReadTool: () => true,
-        executeReadTool: (tc: any) =>
-          tc.id === 'p1'
-            ? { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 3 } }
-            : { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 5 } }
-      }
-    )
-    const r = await runAgenticLoop(input)
-    expect(r.proposals).toHaveLength(2)
-  })
-})