@things-factory/ai-client-base 10.0.8 → 10.1.1

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

@@ -0,0 +1,919 @@
+/**
+ * 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 }),
+  toolCallToOp: () => 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),
+  context: { board: 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',
+        toolCallToOp: 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('toolCallToOp 가 null 반환 — actions 안 누적', async () => {
+    let callCount = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          callCount++
+          return callCount === 1
+            ? okResult(undefined, [TC('badAction', {})])
+            : okResult('done')
+        }
+      },
+      {
+        isActionTool: () => true,
+        toolCallToOp: () => 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('★ 살려내기 — 한도에 닿아도 알아낸 것을 버리지 않는다', async () => {
+    /*
+     * twin-ai 에만 있던 보호 장치를 옮겨 왔다(2026-09-05). 한도에 닿으면 도구 없이 한 번 더 불러
+     * 지금까지 받은 것으로 답하게 한다. 안 그러면 사용자는 기다린 시간만 쓰고 아무것도 못 받는다.
+     */
+    const seen: any[] = []
+    const input = mkInput(
+      {
+        chat: async (_m, _t, opts: any) => {
+          seen.push(opts.toolChoice)
+          return opts.toolChoice === 'none' ? okResult('알아낸 것으로 답한다') : okResult(undefined, [TC('endless')])
+        },
+        options: { systemPrompt: 'x', maxIterations: 2, salvageOnMaxIterations: true }
+      },
+      { isReadTool: () => true, executeReadTool: () => ({}) }
+    )
+    const r = await runAgenticLoop(input)
+
+    expect(r.lastText).toBe('알아낸 것으로 답한다')
+    expect(seen[seen.length - 1]).toBe('none')
+    /* 사유는 남는다 — 살려냈다고 한도에 닿은 사실이 사라지지 않는다. */
+    expect(r.abortReason).toEqual({ type: 'max_iterations', iter: 2 })
+  })
+
+  test('★ 살려내기가 실패해도 삼키지 않는다 — 원래대로 한도 사유가 남는다', async () => {
+    const input = mkInput(
+      {
+        chat: async (_m, _t, opts: any) => {
+          if (opts.toolChoice === 'none') throw new Error('마무리 호출 실패')
+          return okResult(undefined, [TC('endless')])
+        },
+        options: { systemPrompt: 'x', maxIterations: 2, salvageOnMaxIterations: true }
+      },
+      { isReadTool: () => true, executeReadTool: () => ({}) }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.abortReason).toEqual({ type: 'max_iterations', iter: 2 })
+  })
+
+  test('★ 기본은 꺼져 있다 — 켜지 않으면 마무리 호출을 하지 않는다', async () => {
+    const choices: any[] = []
+    const input = mkInput(
+      {
+        chat: async (_m, _t, opts: any) => {
+          choices.push(opts.toolChoice)
+          return okResult(undefined, [TC('endless')])
+        },
+        options: { systemPrompt: 'x', maxIterations: 2 }
+      },
+      { isReadTool: () => true, executeReadTool: () => ({}) }
+    )
+    await runAgenticLoop(input)
+    expect(choices).not.toContain('none')
+  })
+
+  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 — 문맥 전달', () => {
+  test('★ executeReadTool 에 문맥을 그대로 전달 — 루프는 들여다보지 않는다', 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')
+        },
+        context: { board, selectedRefids: [1] }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: (tc, ctx) => {
+          received = { tcName: tc.name, ctx }
+          return {}
+        }
+      }
+    )
+    await runAgenticLoop(input)
+    expect(received).toEqual({
+      tcName: 'peek',
+      ctx: { board, selectedRefids: [1] }
+    })
+  })
+
+  test('★ write tool 의 validation 에도 같은 문맥이 간다 — 꺼내는 일은 부르는 쪽 몫', async () => {
+    /*
+     * ── 이 검사의 뜻이 바뀌었다 (2026-09-05) ──────────────────────────────────
+     * 전에는 루프가 `currentBoard?.components` 를 꺼내 검증기에 넘겼다. 그 한 줄이 「문서는 이렇게
+     * 생겼다」를 루프 안에 심고 있었고, 그래서 이 루프는 board 전용이었다.
+     *
+     * 이제 문맥을 통째로 넘기고 꺼내는 일은 검증기 자신이 한다 — board-ai 의 호출부가
+     * `(ctx.board?.components ?? [])` 를 한다. 루프는 문서의 모양을 모른다.
+     */
+    let callCount = 0
+    let receivedComponents: any
+    const input = mkInput(
+      {
+        chat: async () => {
+          callCount++
+          return callCount === 1
+            ? okResult(undefined, [TC('setFill', {})])
+            : okResult('done')
+        },
+        context: { board: { width: 10, height: 10, components: [{ refid: 7 }] }, selectedRefids: [] } as any
+      },
+      {
+        isWriteTool: () => true,
+        validateWriteToolCall: (_tc, ctx: any) => {
+          receivedComponents = ctx.board?.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)
+  })
+})