@things-factory/board-ai 10.0.0-beta.108

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

@@ -0,0 +1,705 @@
+/**
+ * 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 }])
+  })
+})