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

package/server/service/agentic-loop.ts

@@ -0,0 +1,431 @@
+/**
+ * agentic-loop — multi-turn LLM ↔ tool 루프.
+ *
+ * assistant.ts 에서 추출 — loop 자체를 *순수 함수* 로 만들어:
+ *   1. 단위 테스트 가능 (assistant.ts 의 board-import → @aws-sdk transitive 경로 회피)
+ *   2. 관측성 (error boundary / iter log / AbortSignal / repeated-failure 조기 종료)
+ *      을 한 곳에 응집
+ *   3. 향후 split (Phase 3) 의 자연 경계
+ *
+ * 입력 — `chat` 함수와 dispatch helper 들을 의존성 주입. board-ai 본체는 본 모듈에
+ * 의존하지만 본 모듈은 board-ai 의 어떤 무거운 import 도 모름.
+ */
+import debug from 'debug'
+import type {
+  AIMessage,
+  AIToolCall,
+  AIToolChatResult
+} from '@things-factory/ai-client-base'
+import type { BoardModel } from '@things-factory/board-import'
+import type { BoardActionOp, ToolUsage } from './types'
+
+const log = debug('things-factory:board-ai:loop')
+
+// ── Public types ─────────────────────────────────────────────────
+
+/**
+ * Loop 가 호출하는 dispatch 함수들. 모두 의존성 주입.
+ *
+ * assistant.ts 가 자기 자신의 함수 (isReadTool, executeReadTool 등) 를 그대로
+ * 넘겨주는 구조. 본 모듈은 이 함수들의 *시그니처* 만 알면 됨.
+ */
+export interface ToolDispatchHelpers {
+  isReadTool: (name: string) => boolean
+  isWriteTool: (name: string) => boolean
+  isActionTool: (name: string) => boolean
+  executeReadTool: (
+    tc: AIToolCall,
+    board: BoardModel | undefined,
+    selectedRefids: number[]
+  ) => any
+  validateWriteToolCall: (
+    tc: AIToolCall,
+    components: any[]
+  ) => { valid: boolean; errors?: any[]; suggestion?: string }
+  toolCallToBoardActionOp: (tc: AIToolCall) => BoardActionOp | null
+  summarizeToolResult: (value: any) => any
+}
+
+export interface AgenticLoopOptions {
+  systemPrompt: string
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  /** 최대 iteration. 기본 8. */
+  maxIterations?: number
+  /**
+   * 사용자 abort 신호. iteration 시작 직전 / chat() 호출 후 체크.
+   * 이미 abort 된 신호로 들어오면 첫 iteration 도 안 돔.
+   */
+  signal?: AbortSignal
+  /**
+   * 같은 tool 의 validation 실패가 N회 연속이면 조기 종료. 기본 3.
+   * LLM 이 같은 잘못을 무한 반복하는 경우 방어.
+   */
+  repeatedFailureLimit?: number
+}
+
+export interface AgenticLoopInput {
+  initialConversation: AIMessage[]
+  tools: any[]
+  options: AgenticLoopOptions
+  /** LLM provider 의 chatWithTools 위임. provider-specific 구현. */
+  chat: (
+    messages: AIMessage[],
+    tools: any[],
+    options: any
+  ) => Promise<AIToolChatResult>
+  dispatch: ToolDispatchHelpers
+  currentBoard: BoardModel | undefined
+  selectedRefids: number[]
+}
+
+export interface AgenticLoopResult {
+  lastText: string | undefined
+  accumulatedWriteCalls: AIToolCall[]
+  accumulatedActions: BoardActionOp[]
+  toolUsages: ToolUsage[]
+  /** LLM 마지막 응답의 stopReason. provider-specific 문자열. */
+  stopReason: string
+  /**
+   * 비정상 종료 사유 — 정상 종료 시 undefined.
+   * 호출자 (assistant.ts) 가 사용자 메시지에 반영 (예: '시도 중 오류가 발생했어요').
+   */
+  abortReason?:
+    | { type: 'provider_error'; message: string; iter: number }
+    | { type: 'aborted'; iter: number }
+    | { type: 'max_iterations'; iter: number }
+    | { type: 'repeated_validation_failure'; toolName: string; consecutive: number; iter: number }
+}
+
+// ── Loop ─────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_ITERATIONS = 8
+
+/**
+ * multi-turn agentic loop.
+ *
+ * LLM 이 read tool 을 호출 → 서버에서 즉시 실행 → 결과 회신 → LLM 추론 반복.
+ * write tool 은 누적해 client 에 patch 로 전달. 무한 루프 방지를 위해 iteration cap.
+ *
+ * 본 함수는 *순수* — input 만 보고 결정. 외부 mutable state 없음.
+ */
+export async function runAgenticLoop(
+  input: AgenticLoopInput
+): Promise<AgenticLoopResult> {
+  const {
+    initialConversation,
+    tools,
+    options,
+    chat,
+    dispatch,
+    currentBoard,
+    selectedRefids
+  } = input
+
+  const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS
+  const failureLimit = options.repeatedFailureLimit ?? 3
+  const signal = options.signal
+
+  let conversation = initialConversation
+  const accumulatedWriteCalls: AIToolCall[] = []
+  const accumulatedActions: BoardActionOp[] = []
+  const toolUsages: ToolUsage[] = []
+  let lastText: string | undefined
+  let stopReason: string = 'end_turn'
+  let abortReason: AgenticLoopResult['abortReason']
+
+  // 같은 tool 의 validation 실패 연속 카운터 — 다른 tool 호출 시 reset
+  let lastFailedToolName: string | undefined
+  let consecutiveFailures = 0
+
+  let iter = 0
+  for (; iter < maxIterations; iter++) {
+    // (1) AbortSignal — iteration 시작 시 체크
+    if (signal?.aborted) {
+      log('iter %d: aborted by signal', iter)
+      abortReason = { type: 'aborted', iter }
+      break
+    }
+
+    log('iter %d: chat() 호출', iter)
+    let result: AIToolChatResult
+    try {
+      // (2) Error boundary — provider 예외 시 graceful 종료
+      result = await chat(conversation, tools, {
+        systemPrompt: options.systemPrompt,
+        model: options.model,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+        toolChoice: 'auto',
+        allowParallelToolCalls: true,
+        signal
+      })
+    } catch (e: any) {
+      // AbortError — 별도 분류
+      if (e?.name === 'AbortError' || signal?.aborted) {
+        log('iter %d: provider AbortError', iter)
+        abortReason = { type: 'aborted', iter }
+      } else {
+        log('iter %d: provider error: %s', iter, e?.message)
+        abortReason = {
+          type: 'provider_error',
+          message: e?.message ?? String(e),
+          iter
+        }
+      }
+      break
+    }
+
+    lastText = result.text || lastText
+    stopReason = result.stopReason
+
+    log(
+      'iter %d: text=%s, toolCalls=%d, stopReason=%s',
+      iter,
+      result.text ? `"${result.text.slice(0, 60)}..."` : '(none)',
+      result.toolCalls.length,
+      result.stopReason
+    )
+
+    if (result.toolCalls.length === 0) break
+
+    // (1b) 삭제: chat() 직후 abort 는 다음 iter 시작 시 (1) 에서 감지.
+    // 현재 iter tool 실행을 중단하면 read tool 결과도 버려져 테스트/동작 불일치.
+
+    // tool 결과 빌드 — read 는 즉시 실행, write 는 누적, action 은 별도 채널
+    const beforeUsages = toolUsages.length
+    const toolResultParts = await processToolCalls(
+      result.toolCalls,
+      currentBoard,
+      selectedRefids,
+      dispatch,
+      accumulatedWriteCalls,
+      accumulatedActions,
+      toolUsages
+    )
+
+    // (4) 같은 tool 의 validation 실패 연속 감지 — LLM 이 같은 잘못 반복 시 abort
+    const newUsages = toolUsages.slice(beforeUsages)
+    const repeatedFailureAbort = detectRepeatedValidationFailure(
+      newUsages,
+      lastFailedToolName,
+      consecutiveFailures,
+      failureLimit
+    )
+    if (repeatedFailureAbort.shouldAbort) {
+      log(
+        'iter %d: repeated validation failure on %s (%d consecutive) — abort',
+        iter,
+        repeatedFailureAbort.toolName,
+        repeatedFailureAbort.consecutive
+      )
+      abortReason = {
+        type: 'repeated_validation_failure',
+        toolName: repeatedFailureAbort.toolName,
+        consecutive: repeatedFailureAbort.consecutive,
+        iter
+      }
+      break
+    }
+    lastFailedToolName = repeatedFailureAbort.lastFailedToolName
+    consecutiveFailures = repeatedFailureAbort.consecutive
+
+    // assistant 의 tool_use turn + user 의 tool_result turn 을 conversation 에 누적
+    const assistantContent: any[] = []
+    if (result.text) assistantContent.push({ type: 'text', text: result.text })
+    for (const tc of result.toolCalls) {
+      // providerMeta (Gemini thoughtSignature 등) 를 그대로 round-trip — 안 보내면 400.
+      assistantContent.push({
+        type: 'tool_use',
+        id: tc.id,
+        name: tc.name,
+        arguments: tc.arguments,
+        ...(tc.providerMeta && { providerMeta: tc.providerMeta })
+      })
+    }
+
+    conversation = [
+      ...conversation,
+      { role: 'assistant', content: assistantContent },
+      { role: 'user', content: toolResultParts }
+    ]
+  }
+
+  // (3) max iterations 도달 시 사용자에게 표면화
+  if (iter >= maxIterations && !abortReason) {
+    log('iter %d: max iterations reached', iter)
+    abortReason = { type: 'max_iterations', iter }
+  }
+
+  return {
+    lastText,
+    accumulatedWriteCalls,
+    accumulatedActions,
+    toolUsages,
+    stopReason,
+    abortReason
+  }
+}
+
+/**
+ * 같은 tool 의 validation 실패 연속 감지 — pure helper.
+ *
+ * 같은 tool 이 반복 fail 하면 LLM 이 self-correct 못 하는 상태.
+ * 다른 tool 이 fail 하면 시퀀스 새로 시작 (전혀 다른 패턴이라).
+ * tool 이 succeed 하면 카운터 reset.
+ */
+function detectRepeatedValidationFailure(
+  newUsages: ToolUsage[],
+  lastFailedToolName: string | undefined,
+  consecutiveFailures: number,
+  limit: number
+): {
+  shouldAbort: boolean
+  toolName: string
+  consecutive: number
+  lastFailedToolName: string | undefined
+} {
+  // 이번 iteration 에서 실패한 write tool 들 (validation 거절)
+  const failed = newUsages.filter(
+    u => u.kind === 'write' && (u.result as any)?.error === 'Tool args failed validation'
+  )
+
+  if (failed.length === 0) {
+    // 실패 없음 — reset
+    return {
+      shouldAbort: false,
+      toolName: '',
+      consecutive: 0,
+      lastFailedToolName: undefined
+    }
+  }
+
+  // 모든 실패가 같은 tool 인지 확인
+  const firstName = failed[0].name
+  const allSame = failed.every(u => u.name === firstName)
+
+  if (allSame && firstName === lastFailedToolName) {
+    const consecutive = consecutiveFailures + 1
+    return {
+      shouldAbort: consecutive >= limit,
+      toolName: firstName,
+      consecutive,
+      lastFailedToolName: firstName
+    }
+  }
+
+  // 다른 tool 또는 첫 실패
+  return {
+    shouldAbort: false,
+    toolName: firstName,
+    consecutive: 1,
+    lastFailedToolName: firstName
+  }
+}
+
+/**
+ * 한 iteration 의 tool 결과를 분류·실행·누적. (loop 에서 분리해 읽기 쉽게.)
+ */
+async function processToolCalls(
+  toolCalls: AIToolCall[],
+  currentBoard: BoardModel | undefined,
+  selectedRefids: number[],
+  dispatch: ToolDispatchHelpers,
+  accumulatedWriteCalls: AIToolCall[],
+  accumulatedActions: BoardActionOp[],
+  toolUsages: ToolUsage[]
+): Promise<any[]> {
+  const toolResultParts: any[] = []
+
+  for (const tc of toolCalls) {
+    if (dispatch.isReadTool(tc.name)) {
+      const value = dispatch.executeReadTool(tc, currentBoard, selectedRefids)
+      toolResultParts.push({
+        type: 'tool_result',
+        toolUseId: tc.id,
+        content: JSON.stringify(value)
+      })
+      toolUsages.push({
+        name: tc.name,
+        arguments: tc.arguments ?? {},
+        result: dispatch.summarizeToolResult(value),
+        kind: 'read'
+      })
+    } else if (dispatch.isWriteTool(tc.name)) {
+      // 사전 검증 — args 가 schema / build 함수 검증 통과해야 누적.
+      // 실패 시 LLM 한테 detailed error 반환 → 다음 turn 에서 자기 회복 (retry).
+      const components = (currentBoard?.components ?? []) as any[]
+      const validation = dispatch.validateWriteToolCall(tc, components)
+      if (!validation.valid) {
+        const errorResult = {
+          error: 'Tool args failed validation',
+          issues: validation.errors,
+          suggestion: validation.suggestion,
+          note: 'Fix the args and call the tool again.'
+        }
+        toolResultParts.push({
+          type: 'tool_result',
+          toolUseId: tc.id,
+          content: JSON.stringify(errorResult)
+        })
+        toolUsages.push({
+          name: tc.name,
+          arguments: tc.arguments ?? {},
+          result: errorResult,
+          kind: 'write'
+        })
+        // continue — 누적 안 함. LLM 이 다음 turn 에서 정정 호출.
+      } else {
+        accumulatedWriteCalls.push(tc)
+        const queuedResult = { queued: true, note: 'Will be applied on the client.' }
+        toolResultParts.push({
+          type: 'tool_result',
+          toolUseId: tc.id,
+          content: JSON.stringify(queuedResult)
+        })
+        toolUsages.push({
+          name: tc.name,
+          arguments: tc.arguments ?? {},
+          result: queuedResult,
+          kind: 'write'
+        })
+      }
+    } else if (dispatch.isActionTool(tc.name)) {
+      // ephemeral scene 조작 — accumulatedActions 로 누적, ChatResponse.actions 로 client 전달
+      const action = dispatch.toolCallToBoardActionOp(tc)
+      if (action) accumulatedActions.push(action)
+      const queuedResult = {
+        queued: true,
+        note: 'Will be executed on the modeller (ephemeral).'
+      }
+      toolResultParts.push({
+        type: 'tool_result',
+        toolUseId: tc.id,
+        content: JSON.stringify(queuedResult)
+      })
+      toolUsages.push({
+        name: tc.name,
+        arguments: tc.arguments ?? {},
+        result: queuedResult,
+        kind: 'write'
+      })
+    } else {
+      const errResult = { error: `Unknown tool: ${tc.name}` }
+      toolResultParts.push({
+        type: 'tool_result',
+        toolUseId: tc.id,
+        content: JSON.stringify(errResult),
+        isError: true
+      })
+      toolUsages.push({
+        name: tc.name,
+        arguments: tc.arguments ?? {},
+        result: errResult,
+        kind: 'unknown'
+      })
+    }
+  }
+
+  return toolResultParts
+}