@things-factory/board-ai 10.0.19 → 10.1.1

package/server/service/agentic-loop.ts

@@ -1,533 +0,0 @@
-/**
- * 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 { retryTransient } 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
-  /** read/external 도구 실행. **Promise 를 반환할 수 있다** — 호출부는 반드시 await 한다. */
-  executeReadTool: (
-    tc: AIToolCall,
-    board: BoardModel | undefined,
-    selectedRefids: number[]
-  ) => any | Promise<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
-  /**
-   * **첫 턴에 도구 호출을 강제**한다(toolChoice: 'required'). 두 번째 턴부터는 자유(auto).
-   *
-   * 왜: 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
-   * ("지게차들이 바쁘게 움직이고 있다" — 실제로 이 답이 나왔다). 그건 도구를 아예 부르지 않고 답한
-   * 경우이고, 사후 검사로는 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
-   * 길이 없어진다 — 개념·사용법 질문도 문서 조회 도구로 답하므로 막히지 않는다.
-   *
-   * 대화면이 정한다(라이브 상태를 다루는 면에서만 켠다) — 여기서 질문 내용을 눈치로 분류하지 않는다.
-   */
-  requireToolOnFirstTurn?: boolean
-}
-
-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 에게 실제로 회신된 도구 결과 문자열(시간순) — **접지 판정의 근거집합**.
-   *
-   * `toolUsages[].result` 를 쓰면 안 된다: 그건 UI 표시용으로 압축된(잘린) 값이라 근거로 삼으면
-   * 잘려 나간 식별자를 "근거 없음" 으로 오판한다. 여기 담기는 것은 tool_result 로 보낸 원문 그대로다.
-   */
-  groundedTexts: string[]
-  /**
-   * **제안** — 도구가 "실행하지 않고 제안만 했다" 고 알린 결과들(시간순).
-   *
-   * 규약: read/external 도구의 결과에 `proposed === true` 가 있으면 그것은 조치 제안이다. 그 도구가
-   * 어느 도메인인지 이 루프는 모른다 — 결과를 그대로 실어 올리고, 해석·실행 확인은 대화면이 한다.
-   * 되돌릴 수 없는 조치를 AI 가 직접 실행하지 않게 하는 경계가 이 채널이다(사람이 버튼을 누른다).
-   */
-  proposals: any[]
-  /** 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[] = []
-  /* 접지 근거 — tool_result 로 LLM 에 보낸 원문(압축 전). 호출부가 답의 접지를 검사한다. */
-  const groundedTexts: string[] = []
-  /* 제안 — 도구가 실행하지 않고 제안만 한 것들. 실행 버튼은 대화면이 그린다. */
-  const proposals: any[] = []
-  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 종료.
-       *
-       * 일시 장애(429·5xx·네트워크)는 **다시 시도한다**: 모델 서비스는 가끔 잠깐 죽고(실제로 Gemini
-       * 503 으로 대화가 끊겼다), 그때 한 번도 다시 걸지 않는 것은 우리 쪽 손해다. 요청·자격 오류는
-       * 즉시 그대로 올린다(조용히 더 시도하면 원인이 늦게 드러난다). 판정·대기는 ai-client-base 가 소유. */
-      result = await retryTransient(() => chat(conversation, tools, {
-        systemPrompt: options.systemPrompt,
-        model: options.model,
-        temperature: options.temperature,
-        maxTokens: options.maxTokens,
-        /* 첫 턴만 강제 — 이후는 자유. 계속 강제하면 조회 결과를 받아 놓고도 답을 못 쓰고 도구를 또 부른다. */
-        toolChoice: iter === 0 && options.requireToolOnFirstTurn ? 'required' : 'auto',
-        allowParallelToolCalls: true,
-        signal
-      }), {
-        onRetry: ({ attempt, delayMs, error }) =>
-          log('iter %d: 일시 장애 재시도 %d회 (%dms 후): %s', iter, attempt, delayMs, error?.message)
-      })
-    } 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,
-      proposals,
-      iter
-    )
-
-    /* 접지 근거 누적 — 모델이 tool_result 로 받은 원문 그대로. 압축 전 값이어야 한다(위 필드 주석). */
-    for (const part of toolResultParts) {
-      if (typeof part?.content === 'string') groundedTexts.push(part.content)
-    }
-
-    // (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,
-    groundedTexts,
-    proposals,
-    stopReason,
-    abortReason
-  }
-}
-
-/**
- * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
- *
- * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
- * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
- */
-export function proposalEffectKey(p: any): string {
-  return [p?.tool ?? '', p?.command ?? '', p?.instanceId ?? '', stableStringify(p?.args)].join('|')
-}
-
-/** 키 정렬 직렬화 — 순서에 흔들리지 않는 비교를 위해. */
-function stableStringify(value: any): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null)
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
-  const keys = Object.keys(value).sort()
-  return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`
-}
-
-/**
- * 같은 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[],
-  proposals: any[],
-  /** 몇 번째 LLM 턴인가 — 기록에 남겨 화면이 단계로 읽을 수 있게 한다. */
-  iter: number
-): Promise<any[]> {
-  const toolResultParts: any[] = []
-
-  for (const tc of toolCalls) {
-    if (dispatch.isReadTool(tc.name)) {
-      /* await 필수 — registry 에 등록된 read/external builder 는 async 일 수 있다(DB·외부 호출).
-       * await 없이 JSON.stringify 하면 Promise 가 '{}' 로 직렬화되어 LLM 이 **빈 결과**를 받는다
-       * (board-import 의 getImportSession/importBoardAsync, operato-twin 의 getTwinStructure 등). */
-      const value = await dispatch.executeReadTool(tc, currentBoard, selectedRefids)
-      /* 제안 규약 — 결과가 `proposed: true` 면 조치 제안이다(도메인은 모른 채 그대로 실어 올린다).
-       * 이 채널이 없으면 대화면은 도구 추적(trace)을 뒤져야 하고, 실행 버튼을 만들 근거가 없다. */
-      /* 판정(outcome) — 화면이 단계별 배지로 보여줄 값. 조용한 무동작을 남기지 않는다. */
-      let outcome: ToolUsage['outcome'] = 'ok'
-      if (value && typeof value === 'object' && (value as any).proposed === true) {
-        /* **같은 조치는 한 번만** — 모델이 같은 것을 두 번 제안하는 일이 실제로 있었다(하나는 인자가
-         * 비어 있었다). 카드가 둘이면 사용자가 같은 명령을 두 번 실행할 수 있고, 그건 되돌릴 수 없다.
-         * 판정은 **효과**(도구·명령·대상·인자)로 한다 — 설명 문구(label·reason)가 달라도 같은 조치다. */
-        const candidate = { tool: tc.name, ...(value as any) }
-        const key = proposalEffectKey(candidate)
-        if (proposals.some(p => proposalEffectKey(p) === key)) {
-          outcome = 'folded' // 접힌 사실을 남긴다 — "왜 카드가 하나뿐인가" 가 추적 가능해야 한다
-        } else {
-          proposals.push(candidate)
-          outcome = 'proposed'
-        }
-      } else if (value && typeof value === 'object' && ((value as any).rejected === true || (value as any).error)) {
-        outcome = 'rejected'
-      }
-      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',
-        iter,
-        outcome
-      })
-    } 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',
-          iter,
-          outcome: 'rejected'
-        })
-        // 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',
-          iter,
-          outcome: 'queued'
-        })
-      }
-    } 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',
-        iter,
-        outcome: 'queued'
-      })
-    } 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',
-        iter,
-        outcome: 'error'
-      })
-    }
-  }
-
-  return toolResultParts
-}