@lota-sdk/core 0.4.8 → 0.4.10

package/src/services/thread-turn-preparation.service.ts

@@ -1,1147 +0,0 @@
-import {
-  THREAD,
-  dataPartsSchemas,
-  messageMetadataSchema,
-  PlanNodeResultSubmissionSchema,
-  SUBMIT_PLAN_TURN_RESULT_TOOL_NAME,
-  toTimestamp,
-  withMessageCreatedAt,
-} from '@lota-sdk/shared'
-import type { ChatMessage, MessageMetadata, PlanNodeSpecRecord } from '@lota-sdk/shared'
-import { convertToModelMessages, stepCountIs, tool as createTool, validateUIMessages } from 'ai'
-import type { PrepareStepFunction, StopCondition, ToolLoopAgent, ToolSet, UIMessageStreamWriter } from 'ai'
-
-import type { CoreThreadProfile } from '../config/agent-defaults'
-import {
-  agentRoster,
-  buildAgentTools,
-  createAgent,
-  getLeadAgentId,
-  getCoreThreadProfile,
-  getAgentRuntimeConfig,
-} from '../config/agent-defaults'
-import { lotaDebugLogger } from '../config/debug-logger'
-import { aiLogger } from '../config/logger'
-import type { RecordIdRef } from '../db/record-id'
-import { recordIdToString } from '../db/record-id'
-import { TABLES } from '../db/tables'
-import { enqueueContextCompaction } from '../queues/context-compaction.queue'
-import { enqueueThreadTitleGeneration } from '../queues/title-generation.queue'
-import { readRuntimeAgentIdentityOverrides, resolveRuntimeAgentDisplayName } from '../runtime/agent-identity-overrides'
-import { OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES } from '../runtime/agent-runtime-policy'
-import { createAgentMessageMetadata, createServerRunAbortController } from '../runtime/agent-stream-helpers'
-import { hasApprovalRespondedParts } from '../runtime/approval-continuation'
-import { buildModelInputMessagesWithUploadMetadata, buildReadableUploadMetadataText } from '../runtime/chat-attachments'
-import { hasMessageContent } from '../runtime/chat-message'
-import { waitForCompactionIfNeeded } from '../runtime/chat-run-orchestration'
-import { CONTEXT_WINDOW_TOKENS } from '../runtime/context-compaction-constants'
-import { createExecutionPlanInstructionSectionCache } from '../runtime/execution-plan'
-import { mergeInstructionSections } from '../runtime/instruction-sections'
-import { runPostTurnSideEffects } from '../runtime/post-turn-side-effects'
-import { getRuntimeAdapters, getToolProviders, getTurnHooks } from '../runtime/runtime-extensions'
-import {
-  asRecord,
-  collectCompletedConsultTeamMessages,
-  collectToolOutputErrors,
-  extractMessageText,
-  readInstructionSections,
-  readOptionalString,
-  toOptionalTrimmedString,
-} from '../runtime/thread-chat-helpers'
-import {
-  buildPlanTurnInstructionSections,
-  buildPlanTurnPromptMessage,
-  buildPlanTurnSubmitToolDescription,
-} from '../runtime/thread-plan-turn'
-import type { ThreadPlanTurnContext } from '../runtime/thread-plan-turn'
-import { assembleThreadTurnContext } from '../runtime/thread-turn-context'
-import { finalizeTurnRun } from '../runtime/turn-lifecycle'
-import { chatRunRegistry } from '../services/chat-run-registry.service'
-import type { NormalizedThread, ThreadRecord } from '../services/thread.types'
-import { triageThreadMessage, checkForNextAgent } from '../system-agents/thread-router.agent'
-import { safeEnqueue } from '../utils/async'
-import { AppError } from '../utils/errors'
-import { attachmentService } from './attachment.service'
-import { listReadableUploadsFromChatMessages } from './chat-attachments.service'
-import { contextCompactionRuntime } from './context-compaction-runtime.singleton'
-import { executionPlanService } from './execution-plan.service'
-import { learnedSkillService } from './learned-skill.service'
-import { memoryService } from './memory.service'
-import { planRunService } from './plan-run.service'
-import { threadMessageService } from './thread-message.service'
-import { ActiveThreadRunConflictError, threadService } from './thread.service'
-
-type ChatStreamChunk = Parameters<UIMessageStreamWriter<ChatMessage>['write']>[0]
-
-interface UIMessageStreamResult {
-  toUIMessageStream(options: Record<string, unknown>): ReadableStream<unknown>
-}
-
-function hasUIMessageStream(value: unknown): value is UIMessageStreamResult {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    typeof (value as { toUIMessageStream?: unknown }).toUIMessageStream === 'function'
-  )
-}
-
-const PRESEEDED_MEMORY_LOOKUP_LIMIT = 3
-
-async function waitForThreadCompactionIfNeeded(threadId: RecordIdRef): Promise<ThreadRecord> {
-  return waitForCompactionIfNeeded({
-    entityId: recordIdToString(threadId, TABLES.THREAD),
-    entityLabel: 'Thread',
-    loadEntity: () => threadService.getById(threadId),
-    isCompacting: (thread) => thread.isCompacting === true,
-  })
-}
-
-class ThreadTurnError extends AppError {
-  constructor(
-    message: string,
-    readonly statusCode: 400 | 409,
-  ) {
-    super(message, statusCode === 409 ? 'CONFLICT' : 'BAD_REQUEST', statusCode)
-    this.name = 'ThreadTurnError'
-  }
-}
-
-function optionalInstructionSection(value: unknown): string[] | undefined {
-  const section = readOptionalString(value)
-  return section ? [section] : undefined
-}
-
-function writeMultiAgentEvent(
-  writer: UIMessageStreamWriter<ChatMessage> | undefined,
-  event: {
-    phase: 'routing' | 'waiting-for-agent' | 'agent-message-persisted' | 'complete'
-    agentId?: string
-    agentName?: string
-    messageId?: string
-    note?: string
-  },
-): void {
-  if (!writer) return
-
-  const chunk: ChatStreamChunk = {
-    type: 'data-multi-agent-event',
-    id: `multi-agent-${Bun.randomUUIDv7()}`,
-    data: event,
-    transient: true,
-  }
-  writer.write(chunk)
-}
-
-function applyPlanTurnToolPolicy(tools: ToolSet, nodeSpec: PlanNodeSpecRecord): ToolSet {
-  const blockedToolNames = new Set([...OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES, ...nodeSpec.toolPolicy.deny])
-  const allowList = nodeSpec.toolPolicy.allow.length > 0 ? new Set(nodeSpec.toolPolicy.allow) : null
-
-  return Object.fromEntries(
-    Object.entries(tools).filter(
-      ([toolName]) =>
-        !blockedToolNames.has(toolName) &&
-        (toolName === SUBMIT_PLAN_TURN_RESULT_TOOL_NAME || allowList === null || allowList.has(toolName)),
-    ),
-  )
-}
-
-export interface ThreadTurnParams {
-  thread: NormalizedThread
-  threadRef: RecordIdRef
-  orgRef: RecordIdRef
-  userRef: RecordIdRef
-  userName?: string | null
-  agentIdOverride?: string
-  inputMessage: ChatMessage
-  skipInputMessagePersistence?: boolean
-  abortSignal?: AbortSignal
-  streamId?: string
-}
-
-export interface ThreadApprovalContinuationParams {
-  thread: NormalizedThread
-  threadRef: RecordIdRef
-  orgRef: RecordIdRef
-  userRef: RecordIdRef
-  userName?: string | null
-  approvalMessages: ChatMessage[]
-  abortSignal?: AbortSignal
-  streamId?: string
-}
-
-export interface ThreadPlanTurnParams {
-  thread: NormalizedThread
-  threadRef: RecordIdRef
-  orgRef: RecordIdRef
-  userRef: RecordIdRef
-  userName?: string | null
-  planTurn: ThreadPlanTurnContext
-  abortSignal?: AbortSignal
-  streamId?: string
-}
-
-type ThreadRunCoreParams = {
-  thread: NormalizedThread
-  threadRef: RecordIdRef
-  orgRef: RecordIdRef
-  userRef: RecordIdRef
-  userName?: string | null
-  agentIdOverride?: string
-  abortSignal?: AbortSignal
-  streamId?: string
-} & (
-  | { kind: 'userTurn'; inputMessage: ChatMessage; skipInputMessagePersistence?: boolean }
-  | { kind: 'approvalContinuation'; approvalMessages: ChatMessage[] }
-  | { kind: 'nativeToolApprovalTurn'; approvalMessages: ChatMessage[] }
-  | { kind: 'planTurn'; planTurn: ThreadPlanTurnContext }
-)
-
-interface PreparedThreadTurn {
-  originalMessages: ChatMessage[]
-  run: (writer?: UIMessageStreamWriter<ChatMessage>) => Promise<PreparedThreadTurnResult>
-}
-
-export interface PreparedThreadTurnResult {
-  inputMessageId?: string
-  assistantMessages: ChatMessage[]
-}
-
-function upsertChatHistoryMessage(messages: ChatMessage[], nextMessage: ChatMessage): ChatMessage[] {
-  const existingIndex = messages.findIndex((message) => message.id === nextMessage.id)
-  if (existingIndex === -1) {
-    return [...messages, nextMessage]
-  }
-
-  const nextMessages = [...messages]
-  nextMessages[existingIndex] = nextMessage
-  return nextMessages
-}
-
-interface StreamAgentResponseContext {
-  turnHooks: ReturnType<typeof getTurnHooks>
-  thread: NormalizedThread
-  threadRef: RecordIdRef
-  orgRef: RecordIdRef
-  userRef: RecordIdRef
-  userName?: string | null
-  onboardingActive: boolean
-  linearInstalled: boolean
-  githubInstalled: boolean
-  buildContextResult: Record<string, unknown> | null
-  getExecutionPlanInstructionSections: () => Promise<string[] | undefined>
-  getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
-  getLearnedSkillsSection: (agentId: string, queryText?: string) => Promise<string | undefined>
-  promptContext: { systemWorkspaceDetails?: string }
-  retrievedKnowledgeSection: string | undefined
-  memoryBlock: string
-  hookInstructionSections: string[]
-  runAbortSignal: AbortSignal
-}
-
-interface StreamAgentResponseParams {
-  agentId: string
-  mode: 'direct' | 'fixedThreadMode' | 'threadMode'
-  messages: ChatMessage[]
-  tools: ToolSet
-  observer: {
-    run: <T>(fn: () => T | Promise<T>) => Promise<T>
-    recordError: (error: unknown) => void
-    recordAbort: (error: unknown) => void
-  }
-  skills?: string[]
-  additionalInstructionSections?: string[]
-  includeExecutionPlanTools?: boolean
-  writer?: UIMessageStreamWriter<ChatMessage>
-  stopWhen?: StopCondition<ToolSet> | Array<StopCondition<ToolSet>>
-  prepareStep?: PrepareStepFunction<ToolSet>
-  abortSignal?: AbortSignal
-}
-
-async function streamAgentResponse(
-  ctx: StreamAgentResponseContext,
-  streamParams: StreamAgentResponseParams,
-): Promise<ChatMessage> {
-  const agentTimer = lotaDebugLogger.timer(`agent:${streamParams.agentId}`)
-  const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(ctx.buildContextResult)
-  // Skip full plan state during plan turns — the plan-turn sections already have the active node contract
-  const executionPlanInstructionSections =
-    streamParams.includeExecutionPlanTools === false ? undefined : await ctx.getExecutionPlanInstructionSections()
-  agentTimer.step('get-execution-plan')
-  const agentResolution = asRecord(
-    await ctx.turnHooks.resolveAgent?.({
-      agentId: streamParams.agentId,
-      mode: streamParams.mode,
-      thread: ctx.thread,
-      threadRef: ctx.threadRef,
-      orgRef: ctx.orgRef,
-      userRef: ctx.userRef,
-      userName: ctx.userName,
-      onboardingActive: ctx.onboardingActive,
-      linearInstalled: ctx.linearInstalled,
-      githubInstalled: ctx.githubInstalled,
-      skills: streamParams.skills,
-      additionalInstructionSections: streamParams.additionalInstructionSections,
-      context: ctx.buildContextResult,
-    }),
-  )
-  agentTimer.step('hook:resolveAgent')
-  const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? streamParams.agentId
-  const latestUserMessage = [...streamParams.messages].reverse().find((message) => message.role === 'user')
-  const latestUserMessageText = latestUserMessage ? extractMessageText(latestUserMessage).trim() : undefined
-  const [preSeededMemoriesSection, learnedSkillsSection] = await Promise.all([
-    ctx.getPreSeededMemoriesSection(resolvedAgentId),
-    ctx.getLearnedSkillsSection(resolvedAgentId, latestUserMessageText),
-  ])
-  agentTimer.step('parallel-fetch(memories+skills)')
-  const toolNames = new Set(Object.keys(streamParams.tools))
-  const hasRetrievalTools = [
-    'memorySearch',
-    'conversationSearch',
-    'queryKnowledge',
-    'researchTopic',
-    'fetchWebpage',
-    'inspectWebsite',
-  ].some((toolName) => toolNames.has(toolName))
-  const hasDomainRoutingSkills =
-    (streamParams.skills ?? []).some((skill) => skill.startsWith('cpo-') || skill.startsWith('mentor-')) ||
-    resolvedAgentId === 'cpo' ||
-    resolvedAgentId === 'mentor'
-  const config = getAgentRuntimeConfig({
-    agentId: resolvedAgentId,
-    threadType: ctx.thread.type,
-    mode: streamParams.mode,
-    skills: streamParams.skills,
-    onboardingActive: ctx.onboardingActive,
-    linearInstalled: ctx.linearInstalled,
-    systemWorkspaceDetails: ctx.promptContext.systemWorkspaceDetails,
-    preSeededMemoriesSection,
-    retrievedKnowledgeSection: ctx.retrievedKnowledgeSection,
-    threadMemoryBlock: ctx.memoryBlock,
-    learnedSkillsSection,
-    userMessageText: latestUserMessageText,
-    ruleOptions: { includeMemr3Rule: hasRetrievalTools, includeDomainReasoningFallbackRule: hasDomainRoutingSkills },
-    additionalInstructionSections: mergeInstructionSections(
-      executionPlanInstructionSections,
-      streamParams.additionalInstructionSections,
-      ctx.hookInstructionSections,
-      readInstructionSections(agentResolution?.additionalInstructionSections),
-      optionalInstructionSection(agentResolution?.extraInstructions),
-    ),
-    context: ctx.buildContextResult,
-  }) as Record<string, unknown>
-  agentTimer.step('build-agent-config')
-  const modelMessages = await convertToModelMessages(streamParams.messages, { ignoreIncompleteToolCalls: true })
-  agentTimer.step('convert-model-messages')
-  const agent = createAgent[config.id as string]({
-    mode: streamParams.mode,
-    tools: streamParams.tools,
-    extraInstructions: config.extraInstructions,
-    maxRetries: 3,
-    stopWhen: (agentResolution?.stopWhen as StopCondition<ToolSet> | Array<StopCondition<ToolSet>> | undefined) ??
-      streamParams.stopWhen ?? [stepCountIs(config.maxSteps as number)],
-    prepareStep: (agentResolution?.prepareStep as PrepareStepFunction<ToolSet> | undefined) ?? streamParams.prepareStep,
-  }) as ToolLoopAgent<never, ToolSet>
-  const agentAbortSignal = streamParams.abortSignal ?? ctx.runAbortSignal
-  agentTimer.step('agent-construction')
-
-  let result: unknown
-  try {
-    result = await streamParams.observer.run(() =>
-      agent.stream({ messages: modelMessages, abortSignal: agentAbortSignal }),
-    )
-    agentTimer.step('agent.stream()-resolved')
-  } catch (error) {
-    if (agentAbortSignal.aborted) {
-      streamParams.observer.recordAbort(error)
-      throw error
-    }
-
-    streamParams.observer.recordError(error)
-    throw error
-  }
-  if (!hasUIMessageStream(result)) {
-    throw new Error(`Agent run for ${resolvedAgentId} did not expose a UI message stream.`)
-  }
-
-  let responseMessage: ChatMessage | null = null
-  let resolveFinishedStream!: () => void
-  const finishedStream = new Promise<void>((resolve) => {
-    resolveFinishedStream = resolve
-  })
-
-  const uiStream = result.toUIMessageStream({
-    generateMessageId: () => Bun.randomUUIDv7(),
-    originalMessages: streamParams.messages,
-    sendReasoning: true,
-    sendSources: true,
-    messageMetadata: createAgentMessageMetadata({
-      agentId: resolvedAgentId,
-      agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, resolvedAgentId),
-    }),
-    onFinish: ({ responseMessage: finishedResponseMessage }: { responseMessage: ChatMessage }) => {
-      responseMessage = withMessageCreatedAt(finishedResponseMessage, Date.now())
-      resolveFinishedStream()
-    },
-  }) as ReadableStream<ChatStreamChunk>
-  const reader = uiStream.getReader()
-  let firstChunkLogged = false
-  try {
-    for (;;) {
-      const { done, value } = await reader.read()
-      if (done) break
-      if (!firstChunkLogged) {
-        agentTimer.step('first-stream-chunk')
-        firstChunkLogged = true
-      }
-      if (streamParams.writer) {
-        streamParams.writer.write(value)
-      }
-    }
-  } finally {
-    reader.releaseLock()
-  }
-  agentTimer.step('stream-complete')
-
-  await finishedStream
-  // responseMessage is set inside the stream callback — linter cannot track cross-callback assignment
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (responseMessage === null) {
-    throw new Error(`Agent run for ${resolvedAgentId} did not produce a response message.`)
-  }
-
-  for (const toolError of collectToolOutputErrors({ responseMessage: responseMessage })) {
-    aiLogger.error`Tool execution failed (agent=${resolvedAgentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
-  }
-
-  return responseMessage
-}
-
-export async function prepareThreadRunCore(params: ThreadRunCoreParams): Promise<PreparedThreadTurn> {
-  const { thread, threadRef, orgRef, userRef, userName } = params
-  const runtimeAdapters = getRuntimeAdapters()
-  const turnHooks = getTurnHooks()
-  const toolProviders = getToolProviders()
-  const workspaceProvider = runtimeAdapters.workspaceProvider
-  const orgIdString = recordIdToString(orgRef, TABLES.ORGANIZATION)
-  const userIdString = recordIdToString(userRef, TABLES.USER)
-  const threadIdString = recordIdToString(threadRef, TABLES.THREAD)
-
-  const hydrateMessageFileUrls = (message: ChatMessage): ChatMessage => ({
-    ...message,
-    parts: attachmentService.hydrateSignedFileUrlsInMessageParts({
-      parts: message.parts as Array<Record<string, unknown>>,
-      orgId: orgRef,
-      userId: userRef,
-    }) as ChatMessage['parts'],
-  })
-
-  let inputMessage: ChatMessage | undefined
-  const shouldPersistInputMessage = params.kind === 'userTurn' ? params.skipInputMessagePersistence !== true : false
-  const shouldProcessPostRunSideEffects =
-    params.kind !== 'planTurn' &&
-    (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage)
-  if (params.kind === 'userTurn') {
-    inputMessage = hydrateMessageFileUrls(withMessageCreatedAt(params.inputMessage, Date.now()))
-    if (inputMessage.role !== 'user') {
-      throw new ThreadTurnError('Only user messages can be submitted to the thread runtime.', 400)
-    }
-    if (!hasMessageContent(inputMessage.parts)) {
-      throw new ThreadTurnError('Thread messages must include text or attachments.', 400)
-    }
-    if (thread.type === 'default' && !thread.agentId) {
-      throw new ThreadTurnError('Default threads require an assigned agent.', 400)
-    }
-  }
-
-  const timer = lotaDebugLogger.timer('prepare')
-
-  // Start workspace fetch early unless approval handling will short-circuit the turn.
-  const workspacePromise =
-    params.kind !== 'approvalContinuation' && workspaceProvider
-      ? workspaceProvider.getWorkspace(orgRef)
-      : Promise.resolve({})
-
-  const threadRecord = await waitForThreadCompactionIfNeeded(threadRef)
-  timer.step('compaction-gate')
-  // Plan turns run without the chat lease — they must not block or be blocked by user messages.
-  if (params.kind !== 'planTurn') {
-    if ((await threadService.hasActiveRunLease(threadRef)) || toOptionalTrimmedString(threadRecord.activeRunId)) {
-      const clearedStaleRun = await threadService.clearStaleActiveRunIfMissingFromRegistry(threadRef)
-      if (!clearedStaleRun) {
-        throw new ThreadTurnError('A chat run is already active.', 409)
-      }
-    }
-  }
-
-  if (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn') {
-    const approvedAssistantMessage = [...params.approvalMessages]
-      .reverse()
-      .find((m) => m.role === 'assistant' && hasApprovalRespondedParts(m))
-    if (!approvedAssistantMessage) {
-      throw new ThreadTurnError('No approval-responded message found.', 400)
-    }
-    await threadMessageService.upsertMessages({ threadId: threadRef, messages: [approvedAssistantMessage] })
-    timer.step('persist-approval-message')
-  }
-
-  const persistedCompactionCursor = toOptionalTrimmedString(threadRecord.lastCompactedMessageId) ?? undefined
-  const persistedLiveHistoryPromise = threadMessageService.listMessagesAfterCursor(threadRef, persistedCompactionCursor)
-  let recentHistoryPromise: Promise<ChatMessage[]> | null = null
-  const loadRecentHistory = async (): Promise<ChatMessage[]> => {
-    if (!recentHistoryPromise) {
-      recentHistoryPromise = threadMessageService
-        .listRecentMessages(threadRef, 64)
-        .then(async (persistedRecentHistory) => {
-          if (persistedRecentHistory.length === 0) {
-            return [] as ChatMessage[]
-          }
-
-          const messages = await validateUIMessages<ChatMessage>({
-            messages: persistedRecentHistory,
-            metadataSchema: messageMetadataSchema,
-            dataSchemas: dataPartsSchemas,
-          })
-          return messages.map(hydrateMessageFileUrls)
-        })
-    }
-
-    return await recentHistoryPromise
-  }
-
-  let userMessage: ChatMessage | undefined
-  if (inputMessage) {
-    userMessage = {
-      ...inputMessage,
-      id: inputMessage.id,
-      role: 'user',
-      parts: inputMessage.parts,
-      metadata: { ...inputMessage.metadata, createdAt: toTimestamp(inputMessage.metadata?.createdAt) },
-    }
-  }
-
-  const persistedLiveHistory = await persistedLiveHistoryPromise
-  timer.step('fetch-history')
-  const liveHistory = await (persistedLiveHistory.length === 0
-    ? Promise.resolve([] as ChatMessage[])
-    : validateUIMessages<ChatMessage>({
-        messages: persistedLiveHistory,
-        metadataSchema: messageMetadataSchema,
-        dataSchemas: dataPartsSchemas,
-      }).then((messages) => messages.map(hydrateMessageFileUrls)))
-  timer.step('validate+hydrate-history')
-
-  if (userMessage && shouldPersistInputMessage) {
-    await threadMessageService.upsertMessages({ threadId: threadRef, messages: [userMessage] })
-    timer.step('persist-user-message')
-  }
-
-  const originalMessages = userMessage ? upsertChatHistoryMessage(liveHistory, userMessage) : liveHistory
-  let allAssistantMessages: ChatMessage[] = []
-  const referenceUserMessage =
-    params.kind === 'planTurn'
-      ? undefined
-      : params.kind === 'userTurn' && !shouldPersistInputMessage
-        ? [...liveHistory].reverse().find((m) => m.role === 'user')
-        : (userMessage ?? [...liveHistory].reverse().find((m) => m.role === 'user'))
-  const messageText =
-    params.kind === 'planTurn'
-      ? `${params.planTurn.nodeSpec.label}\n${params.planTurn.nodeSpec.objective}\n${params.planTurn.nodeSpec.instructions}`
-      : referenceUserMessage
-        ? extractMessageText(referenceUserMessage).trim()
-        : ''
-
-  const respondedBy = recordIdToString(userRef, TABLES.USER)
-  if (params.kind === 'approvalContinuation') {
-    await executionPlanService.applyApprovalResponseFromMessages({
-      threadId: threadRef,
-      approvalMessages: params.approvalMessages,
-      respondedBy,
-    })
-    timer.step('approval-continuation')
-
-    return { originalMessages, run: async () => ({ inputMessageId: referenceUserMessage?.id, assistantMessages: [] }) }
-  }
-
-  if (
-    params.kind === 'userTurn' &&
-    thread.type === 'group' &&
-    threadRecord.nameGenerated !== true &&
-    threadRecord.title === THREAD.DEFAULT_TITLE &&
-    messageText.length > 0
-  ) {
-    void safeEnqueue(() => enqueueThreadTitleGeneration({ threadId: threadIdString, sourceText: messageText }), {
-      operationName: 'thread-title-generation',
-    })
-  }
-
-  if (thread.type === 'thread' && !thread.threadType) {
-    throw new ThreadTurnError('Core threads require a thread type.', 400)
-  }
-  const coreThreadProfile: CoreThreadProfile | null =
-    thread.type === 'thread' && thread.threadType ? getCoreThreadProfile(thread.threadType) : null
-  const defaultLeadAgentId = getLeadAgentId()
-  const visibleThreadAgentId =
-    params.agentIdOverride ??
-    (thread.type === 'default' ? thread.agentId : (coreThreadProfile?.config.agentId ?? defaultLeadAgentId))
-  const coreInstructionSections = coreThreadProfile ? [coreThreadProfile.instructions] : undefined
-  const assembledContext = await assembleThreadTurnContext({
-    thread,
-    threadRef,
-    orgRef,
-    userRef,
-    userName,
-    orgIdString,
-    userIdString,
-    messageText,
-    workspacePromise,
-    workspaceProvider,
-    turnHooks,
-    onStep: (step) => timer.step(step),
-  })
-  const {
-    workspace,
-    onboardingActive,
-    linearInstalled,
-    githubInstalled,
-    indexedRepoContext,
-    promptContext,
-    retrievedKnowledgeSection,
-    buildContextResult,
-    hookInstructionSections,
-  } = assembledContext
-
-  let memoryBlock = threadService.formatMemoryBlockForPrompt(threadRecord)
-  const executionPlanInstructionSectionCache = createExecutionPlanInstructionSectionCache({
-    disabled: false,
-    loadPlans: async () => {
-      const runs = await planRunService.getActiveRunRecords(threadRef)
-      return Promise.all(runs.map((run) => planRunService.toSerializablePlan(run, { slim: true })))
-    },
-  })
-  const getExecutionPlanInstructionSections = async (): Promise<string[] | undefined> =>
-    await executionPlanInstructionSectionCache.getSections()
-  const invalidateExecutionPlanInstructionSections = () => {
-    executionPlanInstructionSectionCache.invalidate()
-  }
-  if (userMessage) {
-    const appliedHumanInput = await executionPlanService.applyHumanInputFromUserMessage({
-      threadId: threadRef,
-      message: userMessage,
-      respondedBy,
-    })
-    if (appliedHumanInput) {
-      invalidateExecutionPlanInstructionSections()
-    }
-  }
-  timer.step('execution-plan-input')
-
-  const preSeededMemoriesByAgent = new Map<string, string | undefined>()
-  const getPreSeededMemoriesSection = async (agentId: string): Promise<string | undefined> => {
-    if (preSeededMemoriesByAgent.has(agentId)) {
-      return preSeededMemoriesByAgent.get(agentId)
-    }
-
-    const preSeededMemories = await memoryService.getTopMemories({
-      orgId: orgIdString,
-      agentName: agentId,
-      limit: PRESEEDED_MEMORY_LOOKUP_LIMIT,
-    })
-    preSeededMemoriesByAgent.set(agentId, preSeededMemories)
-    return preSeededMemories
-  }
-
-  const learnedSkillsByAgent = new Map<string, string | undefined>()
-  const getLearnedSkillsSection = async (agentId: string, queryText = messageText): Promise<string | undefined> => {
-    const cacheKey = `${agentId}::${queryText}`
-    if (learnedSkillsByAgent.has(cacheKey)) return learnedSkillsByAgent.get(cacheKey)
-
-    const section = await learnedSkillService
-      .retrieveForTurn({ orgId: orgIdString, agentId, query: queryText, limit: 3, minConfidence: 0.6 })
-      .catch((error) => {
-        aiLogger.warn`Failed to retrieve learned skills for ${agentId}: ${error}`
-        return undefined
-      })
-    learnedSkillsByAgent.set(cacheKey, section)
-    return section
-  }
-
-  const persistedCompactionSummary =
-    persistedCompactionCursor && typeof threadRecord.compactionSummary === 'string'
-      ? threadRecord.compactionSummary
-      : ''
-  const messagesForContext = userMessage ? upsertChatHistoryMessage(liveHistory, userMessage) : liveHistory
-  let currentMessages = contextCompactionRuntime.prependSummaryMessage(persistedCompactionSummary, messagesForContext)
-  const referenceUserMessageId = referenceUserMessage?.id ?? ''
-  const listReadableUploads = (extraMessages: ChatMessage[] = []) =>
-    listReadableUploadsFromChatMessages({
-      messages: [...currentMessages, ...extraMessages],
-      orgId: orgRef,
-      userId: userRef,
-    })
-  const buildRunInputMessages = (extraMessages: ChatMessage[] = []): ChatMessage[] =>
-    buildModelInputMessagesWithUploadMetadata({
-      messages: [...currentMessages, ...extraMessages],
-      latestUserMessageId: referenceUserMessageId,
-      uploadMetadataText: buildReadableUploadMetadataText(listReadableUploads(extraMessages)),
-    })
-  const buildTurnToolParams = (toolParams: {
-    agentId: string
-    mode: 'direct' | 'fixedThreadMode' | 'threadMode'
-    memoryBlock: string
-    onAppendMemoryBlock: (value: string) => void
-    extraMessages?: ChatMessage[]
-    skills?: string[]
-    includeExecutionPlanTools: boolean
-  }) => ({
-    agentId: toolParams.agentId,
-    orgId: orgRef,
-    userId: userRef,
-    userName: userName ?? 'there',
-    threadId: threadRef,
-    orgIdString,
-    threadType: thread.type,
-    mode: toolParams.mode,
-    linearInstalled,
-    onboardingActive,
-    githubInstalled,
-    provideRepoTool: indexedRepoContext.provideRepoTool,
-    skills: toolParams.skills,
-    defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[toolParams.agentId],
-    memoryBlock: toolParams.memoryBlock,
-    onAppendMemoryBlock: toolParams.onAppendMemoryBlock,
-    availableUploads: listReadableUploads(toolParams.extraMessages),
-    includeExecutionPlanTools: toolParams.includeExecutionPlanTools,
-    onExecutionPlanChanged: invalidateExecutionPlanInstructionSections,
-    context: buildContextResult,
-  })
-
-  timer.step('preparation-complete')
-
-  return {
-    originalMessages,
-    run: async (writer?: UIMessageStreamWriter<ChatMessage>) => {
-      const executeRun = async (leaseAbortSignal?: AbortSignal): Promise<PreparedThreadTurnResult | void> => {
-        const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(buildContextResult)
-        const runTimer = lotaDebugLogger.timer('run')
-        const serverRunId = Bun.randomUUIDv7()
-        const runAbortSignals = leaseAbortSignal ? [params.abortSignal, leaseAbortSignal] : [params.abortSignal]
-        const runAbort = createServerRunAbortController(
-          runAbortSignals.filter((signal): signal is AbortSignal => Boolean(signal)),
-        )
-        if (runAbort.signal.aborted) {
-          throw runAbort.signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
-        }
-        // Plan turns run without the chat lease — don't claim the active run slot.
-        if (params.kind !== 'planTurn') {
-          await threadService.setActiveTurn(threadRef, serverRunId, params.streamId ?? null)
-          chatRunRegistry.register(serverRunId, runAbort.controller)
-        }
-        runTimer.step('set-active-run+stream')
-
-        try {
-          const throwIfRunAborted = () => {
-            if (!runAbort.signal.aborted) return
-            throw runAbort.signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
-          }
-
-          const buildAgentMetadataPatch = (agentId: string, agentName: string): NonNullable<MessageMetadata> => ({
-            agentId,
-            agentName,
-            semanticTerminationReason: 'none',
-          })
-
-          const createObserver = (agentId: string) => ({
-            run: <T>(fn: () => T | Promise<T>) => Promise.resolve(fn()),
-            recordError: (error: unknown) => {
-              aiLogger.error`Agent run failed (agent=${agentId}): ${error}`
-            },
-            recordAbort: (error: unknown) => {
-              aiLogger.info`Agent run aborted (agent=${agentId}): ${error instanceof Error ? error.message : String(error)}`
-            },
-          })
-
-          const commitAssistantResponse = async (
-            response: ChatMessage,
-            agentId: string,
-            agentName: string,
-            metadataPatch?: NonNullable<MessageMetadata>,
-          ) => {
-            throwIfRunAborted()
-
-            const toCommittedAssistantMessage = (
-              message: ChatMessage,
-              resolvedAgentId: string,
-              resolvedAgentName: string,
-              patch?: NonNullable<MessageMetadata>,
-            ) =>
-              withMessageCreatedAt(
-                {
-                  ...message,
-                  metadata: {
-                    ...message.metadata,
-                    ...buildAgentMetadataPatch(resolvedAgentId, resolvedAgentName),
-                    ...patch,
-                  },
-                },
-                toTimestamp(message.metadata?.createdAt) ?? Date.now(),
-              )
-
-            const committedConsultMessages = collectCompletedConsultTeamMessages({ responseMessage: response }).flatMap(
-              (consultMessage) => {
-                const consultAgentId = readOptionalString(consultMessage.metadata?.agentId)
-                const consultAgentName = readOptionalString(consultMessage.metadata?.agentName)
-                if (!consultAgentId || !consultAgentName) {
-                  return []
-                }
-
-                return [toCommittedAssistantMessage(consultMessage, consultAgentId, consultAgentName)]
-              },
-            )
-
-            const committed = toCommittedAssistantMessage(response, agentId, agentName, metadataPatch)
-            const messagesToPersist = [...committedConsultMessages, committed]
-
-            await threadMessageService.upsertMessages({ threadId: threadRef, messages: messagesToPersist })
-            for (const persistedMessage of messagesToPersist) {
-              currentMessages = upsertChatHistoryMessage(currentMessages, persistedMessage)
-              allAssistantMessages = upsertChatHistoryMessage(allAssistantMessages, persistedMessage)
-            }
-            throwIfRunAborted()
-
-            return committed
-          }
-
-          const streamCtx: StreamAgentResponseContext = {
-            turnHooks,
-            thread,
-            threadRef,
-            orgRef,
-            userRef,
-            userName,
-            onboardingActive,
-            linearInstalled,
-            githubInstalled,
-            buildContextResult,
-            getExecutionPlanInstructionSections,
-            getPreSeededMemoriesSection,
-            getLearnedSkillsSection,
-            promptContext,
-            retrievedKnowledgeSection,
-            memoryBlock,
-            hookInstructionSections,
-            runAbortSignal: runAbort.signal,
-          }
-
-          const runVisibleAgent = async (runParams: {
-            agentId: string
-            mode: 'direct' | 'fixedThreadMode' | 'threadMode'
-            skills?: string[]
-            additionalInstructionSections?: string[]
-            extraMessages?: ChatMessage[]
-            extraTools?: ToolSet
-            filterTools?: (tools: ToolSet) => ToolSet
-            includeExecutionPlanTools?: boolean
-            metadataPatch?: NonNullable<MessageMetadata>
-          }): Promise<ChatMessage> => {
-            const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
-            let runMemoryBlock = memoryBlock
-            const includeExecutionPlanTools =
-              runParams.includeExecutionPlanTools ?? runParams.mode !== 'fixedThreadMode'
-            const rawTools: ToolSet = {
-              ...((await buildAgentTools(
-                buildTurnToolParams({
-                  agentId: runParams.agentId,
-                  mode: runParams.mode,
-                  skills: runParams.skills,
-                  memoryBlock: runMemoryBlock,
-                  onAppendMemoryBlock: (value: string) => {
-                    runMemoryBlock = value
-                  },
-                  extraMessages: runParams.extraMessages,
-                  includeExecutionPlanTools,
-                }),
-              )) as ToolSet),
-              ...toolProviders,
-              ...runParams.extraTools,
-            }
-            const tools = runParams.filterTools ? runParams.filterTools(rawTools) : rawTools
-            visibleTimer.step('build-agent-tools')
-            streamCtx.memoryBlock = memoryBlock
-            throwIfRunAborted()
-            const responseMessage = await streamAgentResponse(streamCtx, {
-              agentId: runParams.agentId,
-              mode: runParams.mode,
-              messages: buildRunInputMessages(runParams.extraMessages),
-              tools,
-              observer: createObserver(runParams.agentId),
-              skills: runParams.skills,
-              additionalInstructionSections: runParams.additionalInstructionSections,
-              includeExecutionPlanTools,
-              writer,
-            })
-
-            visibleTimer.step('stream-agent-response')
-            memoryBlock = runMemoryBlock
-
-            return commitAssistantResponse(
-              responseMessage,
-              runParams.agentId,
-              resolveRuntimeAgentDisplayName(agentIdentityOverrides, runParams.agentId),
-              runParams.metadataPatch,
-            )
-          }
-
-          if (params.kind === 'planTurn') {
-            const planTurn = params.planTurn
-            const submitPlanTurnNodeResultTool = createTool({
-              description: buildPlanTurnSubmitToolDescription(planTurn),
-              inputSchema: PlanNodeResultSubmissionSchema,
-              execute: async (result) =>
-                await executionPlanService.submitPlanTurnResult({
-                  threadId: threadRef,
-                  runId: planTurn.runId,
-                  nodeId: planTurn.nodeId,
-                  emittedBy: planTurn.nodeSpec.owner.ref,
-                  input: result,
-                }),
-            })
-
-            await runVisibleAgent({
-              agentId: planTurn.nodeSpec.owner.ref,
-              mode: thread.type === 'default' ? 'direct' : 'threadMode',
-              additionalInstructionSections: buildPlanTurnInstructionSections(planTurn),
-              extraMessages: [buildPlanTurnPromptMessage(planTurn)],
-              includeExecutionPlanTools: false,
-              extraTools: { [SUBMIT_PLAN_TURN_RESULT_TOOL_NAME]: submitPlanTurnNodeResultTool },
-              filterTools: (tools) => applyPlanTurnToolPolicy(tools, planTurn.nodeSpec),
-              metadataPatch: { trigger: 'plan-turn', planRunId: planTurn.runId, planNodeId: planTurn.nodeId },
-            })
-          } else {
-            if (thread.type === 'default') {
-              if (!thread.agentId) {
-                throw new ThreadTurnError('Direct threads require an assigned agent.', 400)
-              }
-              await runVisibleAgent({ agentId: thread.agentId, mode: 'direct' })
-            } else {
-              // Multi-agent orchestration for group threads
-              const wsMembers = (thread as { members?: string[] }).members ?? []
-              const members = wsMembers.length > 0 ? wsMembers : [...agentRoster]
-              const fallbackAgentId = coreThreadProfile?.config.agentId ?? defaultLeadAgentId
-              throwIfRunAborted()
-              writeMultiAgentEvent(writer, { phase: 'routing', note: 'Routing this turn to the right agent.' })
-
-              const recentContext = currentMessages
-                .slice(-6)
-                .map((m) => `${m.role}: ${extractMessageText(m).slice(0, 200)}`)
-                .join('\n')
-
-              const triageResult = await triageThreadMessage({
-                threadTitle: thread.title,
-                members,
-                messageText,
-                recentContext,
-                displayNamesById: agentIdentityOverrides.displayNamesById,
-                shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
-                routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
-              })
-              throwIfRunAborted()
-
-              const runGroupAgent = async (agentId: string, options?: { routingContext?: string }) => {
-                const additionalSections = [...(coreInstructionSections ?? []), ...hookInstructionSections]
-                if (options?.routingContext) {
-                  additionalSections.push(`<routing-context>\n${options.routingContext}\n</routing-context>`)
-                }
-                // Multi-agent member protocol: be direct, focus on domain
-                additionalSections.push(
-                  '<multi-agent-protocol>\nYou are responding as part of a multi-agent thread. Focus on your domain expertise. Be direct and concise — another agent may follow up on different aspects.\n</multi-agent-protocol>',
-                )
-
-                return await runVisibleAgent({
-                  agentId,
-                  mode: 'threadMode',
-                  skills: coreThreadProfile?.skills ? [...coreThreadProfile.skills] : undefined,
-                  additionalInstructionSections: additionalSections,
-                })
-              }
-
-              if (!triageResult) {
-                // No specialist match — fallback to owner (core) or chief (non-core), single visible turn.
-                await runGroupAgent(fallbackAgentId)
-                throwIfRunAborted()
-                writeMultiAgentEvent(writer, { phase: 'complete' })
-              } else {
-                const respondedAgents: string[] = []
-                let lastResponse = await runGroupAgent(triageResult.agentId, {
-                  routingContext: triageResult.routingContext,
-                })
-                respondedAgents.push(triageResult.agentId)
-                throwIfRunAborted()
-
-                // Follow-up specialists stream visibly in order so the user can
-                // watch each specialist reply instead of waiting for a persisted refresh.
-                while (respondedAgents.length < 3) {
-                  const lastResponseText = extractMessageText(lastResponse).slice(0, 500)
-                  const checkResult = await checkForNextAgent({
-                    threadTitle: thread.title,
-                    members,
-                    messageText,
-                    respondedAgents,
-                    lastResponseSummary: lastResponseText,
-                    displayNamesById: agentIdentityOverrides.displayNamesById,
-                    shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
-                    routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
-                  })
-                  throwIfRunAborted()
-
-                  if (checkResult.done || !checkResult.agentId) break
-
-                  writeMultiAgentEvent(writer, {
-                    phase: 'waiting-for-agent',
-                    agentId: checkResult.agentId,
-                    agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
-                    note: checkResult.routingContext ?? undefined,
-                  })
-
-                  // Insert hidden bridge message between agent turns
-                  const bridgeMessage: ChatMessage = {
-                    id: Bun.randomUUIDv7(),
-                    role: 'user',
-                    parts: [
-                      {
-                        type: 'text',
-                        text: checkResult.routingContext ?? 'Please also provide your perspective on this topic.',
-                      },
-                    ],
-                    metadata: { hidden: true, createdAt: Date.now() } as MessageMetadata,
-                  }
-                  throwIfRunAborted()
-                  await threadMessageService.upsertMessages({ threadId: threadRef, messages: [bridgeMessage] })
-                  currentMessages = upsertChatHistoryMessage(currentMessages, bridgeMessage)
-                  throwIfRunAborted()
-
-                  lastResponse = await runGroupAgent(checkResult.agentId, {
-                    routingContext: checkResult.routingContext ?? undefined,
-                  })
-                  respondedAgents.push(checkResult.agentId)
-                  throwIfRunAborted()
-                  writeMultiAgentEvent(writer, {
-                    phase: 'agent-message-persisted',
-                    agentId: checkResult.agentId,
-                    agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
-                    messageId: lastResponse.id,
-                  })
-                }
-
-                throwIfRunAborted()
-                writeMultiAgentEvent(writer, { phase: 'complete' })
-              }
-            }
-          }
-        } finally {
-          try {
-            const latestThreadRecord = await threadService.getById(threadRef)
-
-            await finalizeTurnRun({
-              serverRunId,
-              getEntity: async () => latestThreadRecord,
-              getUncompactedMessages: (cursor) => threadMessageService.listMessagesAfterCursor(threadRef, cursor),
-              assessCompaction: (summaryText, messages) =>
-                contextCompactionRuntime.shouldCompactHistory({
-                  summaryText,
-                  liveMessages: messages,
-                  contextSize: CONTEXT_WINDOW_TOKENS,
-                }),
-              enqueueCompaction: async () => {
-                await enqueueContextCompaction({
-                  domain: 'thread',
-                  entityId: threadIdString,
-                  contextSize: CONTEXT_WINDOW_TOKENS,
-                })
-              },
-              unregisterRun: (runId) => chatRunRegistry.unregister(runId),
-              clearActiveRunId: async (runId) => {
-                const activeStreamId = await threadService.getActiveStreamId(threadRef)
-                await threadService.clearActiveTurn(threadRef, { runId, streamId: activeStreamId })
-              },
-              disposeAbort: () => runAbort.dispose(),
-              activeStreamId: params.streamId,
-              clearActiveStreamId: async (streamId) => {
-                const activeRunId = await threadService.getActiveRunId(threadRef)
-                if (!activeRunId) return
-                await threadService.clearActiveTurn(threadRef, { runId: activeRunId, streamId })
-              },
-            })
-
-            if (allAssistantMessages.length > 0 && shouldProcessPostRunSideEffects) {
-              await runPostTurnSideEffects({
-                thread,
-                threadRef,
-                orgRef,
-                userRef,
-                userName,
-                orgIdString,
-                threadIdString,
-                onboardingActive,
-                workspace,
-                allAssistantMessages,
-                referenceUserMessage,
-                referenceUserMessageId,
-                loadRecentHistory,
-                listReadableUploads: () => listReadableUploads(),
-                memoryBlock,
-                visibleThreadAgentId,
-                defaultLeadAgentId,
-                latestThreadRecord,
-                isUserTurn: params.kind === 'userTurn',
-                agentDisplayNamesById: agentIdentityOverrides.displayNamesById,
-              })
-            }
-
-            if (allAssistantMessages.length > 0 && params.kind !== 'planTurn') {
-              await turnHooks.afterTurn?.({
-                thread,
-                threadRef,
-                orgRef,
-                userRef,
-                userName,
-                onboardingActive,
-                referenceUserMessage,
-                assistantMessages: allAssistantMessages,
-                latestThreadRecord,
-                context: buildContextResult,
-              })
-            }
-          } catch (postRunError) {
-            aiLogger.error`Thread post-run cleanup failed: ${postRunError}`
-          }
-        }
-      }
-
-      // Plan turns run without the chat lease so they never block user messages.
-      // The heartbeat lock already prevents duplicate plan turns on the same node.
-      if (params.kind === 'planTurn') {
-        const runResult = await executeRun()
-        if (runResult) {
-          return runResult
-        }
-        return { inputMessageId: referenceUserMessage?.id, assistantMessages: [...allAssistantMessages] }
-      }
-
-      try {
-        return await threadService.withActiveRunLease(threadRef, async (leaseAbortSignal) => {
-          const runResult = await executeRun(leaseAbortSignal)
-          if (runResult) {
-            return runResult
-          }
-
-          return { inputMessageId: referenceUserMessage?.id, assistantMessages: [...allAssistantMessages] }
-        })
-      } catch (error) {
-        if (error instanceof ActiveThreadRunConflictError) {
-          throw new ThreadTurnError(error.message, 409)
-        }
-        throw error
-      }
-    },
-  }
-}