@lota-sdk/core 0.4.8 → 0.4.10

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

@@ -0,0 +1,1148 @@
+import {
+  THREAD,
+  dataPartsSchemas,
+  messageMetadataSchema,
+  PlanNodeResultSubmissionSchema,
+  SUBMIT_PLAN_TURN_RESULT_TOOL_NAME,
+  toTimestamp,
+  withMessageCreatedAt,
+} from '@lota-sdk/shared'
+import type { ChatMessage, MessageMetadata } from '@lota-sdk/shared'
+import { tool as createTool, validateUIMessages } from 'ai'
+import type { UIMessageStreamWriter } from 'ai'
+import { Clock, Context, Schema, Effect, Layer } from 'effect'
+
+import type { CoreThreadProfile } from '../../config/agent-defaults'
+import {
+  getAgentRoster,
+  getLeadAgentId,
+  getCoreThreadProfile,
+  getResolvedAgentFactoryConfig,
+} from '../../config/agent-defaults'
+import { aiLogger } from '../../config/logger'
+import type { RecordIdRef } from '../../db/record-id'
+import { recordIdToString } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import type { DatabaseError, ServiceError } from '../../effect/errors'
+import { ThreadTurnError } from '../../effect/errors'
+import { makeEffectTryPromiseWithMessage } from '../../effect/helpers'
+import { enqueueContextCompaction } from '../../queues/context-compaction.queue'
+import { enqueueThreadTitleGeneration } from '../../queues/title-generation.queue'
+import {
+  readRuntimeAgentIdentityOverrides,
+  resolveRuntimeAgentDisplayName,
+} from '../../runtime/agent-identity-overrides'
+import { createServerRunAbortController } from '../../runtime/agent-stream-helpers'
+import { hasApprovalRespondedParts } from '../../runtime/approval-continuation'
+import { hasMessageContent } from '../../runtime/chat-message'
+import { CompactionCoordinationTag } from '../../runtime/chat-run-orchestration'
+import { CONTEXT_WINDOW_TOKENS } from '../../runtime/context-compaction/context-compaction-constants'
+import { createWiredContextCompactionRuntime } from '../../runtime/context-compaction/context-compaction-runtime'
+import { createExecutionPlanInstructionSectionCache, toExecutionPlanCacheError } from '../../runtime/execution-plan'
+import type { HelperModelRuntime } from '../../runtime/helper-model'
+import { HelperModelTag } from '../../runtime/helper-model'
+import { runPostTurnSideEffects } from '../../runtime/post-turn-side-effects'
+import { getRuntimeAdapters, getTurnHooks } from '../../runtime/runtime-extensions'
+import { extractMessageText, 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 { finalizeTurnRunEffect, TurnLifecycleError } from '../../runtime/turn-lifecycle'
+import { triageThreadMessage, checkForNextAgent } from '../../system-agents/thread-router.agent'
+import { safeEnqueue } from '../../utils/async'
+import { nowEpochMillis } from '../../utils/date-time'
+import { getErrorMessage } from '../../utils/errors'
+import type { makeAttachmentService } from '../attachment.service'
+import { AttachmentServiceTag } from '../attachment.service'
+import { ChatRunRegistryTag } from '../chat-run-registry.service'
+import type { makeExecutionPlanService } from '../execution-plan/execution-plan.service'
+import { ExecutionPlanServiceTag } from '../execution-plan/execution-plan.service'
+import type { makeLearnedSkillService } from '../learned-skill.service'
+import { LearnedSkillServiceTag } from '../learned-skill.service'
+import type { createMemoryService } from '../memory/memory.service'
+import { MemoryServiceTag } from '../memory/memory.service'
+import type { makePlanRunService } from '../plan/plan-run.service'
+import { PlanRunServiceTag } from '../plan/plan-run.service'
+import type { makeThreadMessageService } from './thread-message.service'
+import { ThreadMessageServiceTag } from './thread-message.service'
+import {
+  applyPlanTurnToolPolicy,
+  createThreadTurnVisibleAgentRunner,
+  writeMultiAgentEvent,
+} from './thread-turn-execution'
+import { createThreadTurnMessageContext, upsertChatHistoryMessage } from './thread-turn-message-context'
+import { ThreadTurnStreamingError } from './thread-turn-streaming'
+import type { StreamAgentResponseContext } from './thread-turn-streaming'
+import { buildThreadTurnSpanAttributes, compactSpanAttributes } from './thread-turn-tracing'
+import { ThreadServiceTag } from './thread.service'
+import type { makeThreadService } from './thread.service'
+import type { NormalizedThread } from './thread.types'
+
+interface ThreadTurnPreparationServiceContext {
+  attachmentService: ReturnType<typeof makeAttachmentService>
+  chatRunRegistry: Context.Service.Shape<typeof ChatRunRegistryTag>
+  compactionCoordination: Context.Service.Shape<typeof CompactionCoordinationTag>
+  executionPlanService: ReturnType<typeof makeExecutionPlanService>
+  learnedSkillService: ReturnType<typeof makeLearnedSkillService>
+  memoryService: ReturnType<typeof createMemoryService>
+  planRunService: ReturnType<typeof makePlanRunService>
+  threadMessageService: ReturnType<typeof makeThreadMessageService>
+  threadService: ReturnType<typeof makeThreadService>
+  contextCompactionRuntime: ReturnType<typeof createWiredContextCompactionRuntime>
+}
+
+type ThreadTurnPreparationRuntimeDeps = ThreadTurnPreparationServiceContext
+
+const PRESEEDED_MEMORY_LOOKUP_LIMIT = 3
+
+function waitForThreadCompactionIfNeeded(deps: ThreadTurnPreparationRuntimeDeps, threadId: RecordIdRef) {
+  return deps.compactionCoordination.waitIfNeeded({
+    entityId: recordIdToString(threadId, TABLES.THREAD),
+    entityLabel: 'Thread',
+    loadEntity: () => deps.threadService.getById(threadId),
+    isCompacting: (thread) => thread.isCompacting === true,
+  })
+}
+
+export class ThreadTurnPreparationError extends Schema.TaggedErrorClass<ThreadTurnPreparationError>()(
+  'ThreadTurnPreparationError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+const effectTryPromise = makeEffectTryPromiseWithMessage(
+  (message, cause) => new ThreadTurnPreparationError({ message, cause }),
+)
+
+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 }
+)
+
+export interface PreparedThreadTurnResult {
+  inputMessageId?: string
+  assistantMessages: ChatMessage[]
+}
+
+type RecentHistoryLoadError = ServiceError | ThreadTurnPreparationError
+
+function hydrateThreadMessageFileUrls(
+  attachmentService: ReturnType<typeof makeAttachmentService>,
+  orgRef: RecordIdRef,
+  userRef: RecordIdRef,
+  message: ChatMessage,
+): ChatMessage {
+  return {
+    ...message,
+    parts: attachmentService.hydrateSignedFileUrlsInMessageParts({
+      parts: message.parts,
+      orgId: orgRef,
+      userId: userRef,
+    }),
+  }
+}
+
+function validateAndHydrateThreadMessagesEffect(params: {
+  attachmentService: ReturnType<typeof makeAttachmentService>
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+  messages: ChatMessage[]
+  errorMessage: string
+}): Effect.Effect<ChatMessage[], ThreadTurnPreparationError> {
+  const { attachmentService, orgRef, userRef, messages, errorMessage } = params
+
+  return effectTryPromise(
+    () =>
+      validateUIMessages<ChatMessage>({
+        messages,
+        metadataSchema: messageMetadataSchema,
+        dataSchemas: dataPartsSchemas,
+      }),
+    errorMessage,
+  ).pipe(
+    Effect.map((validated) =>
+      validated.map((message) => hydrateThreadMessageFileUrls(attachmentService, orgRef, userRef, message)),
+    ),
+  )
+}
+
+function validateUserTurnInputMessageEffect(params: {
+  thread: NormalizedThread
+  inputMessage: ChatMessage
+  attachmentService: ReturnType<typeof makeAttachmentService>
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+}): Effect.Effect<ChatMessage, ThreadTurnError> {
+  const { thread, inputMessage, attachmentService, orgRef, userRef } = params
+
+  return Effect.gen(function* () {
+    const createdAt = yield* Clock.currentTimeMillis
+    const hydratedInputMessage = hydrateThreadMessageFileUrls(
+      attachmentService,
+      orgRef,
+      userRef,
+      withMessageCreatedAt(inputMessage, createdAt),
+    )
+
+    if (hydratedInputMessage.role !== 'user') {
+      return yield* new ThreadTurnError({
+        message: 'Only user messages can be submitted to the thread runtime.',
+        reason: 'bad-request',
+      })
+    }
+    if (!hasMessageContent(hydratedInputMessage.parts)) {
+      return yield* new ThreadTurnError({
+        message: 'Thread messages must include text or attachments.',
+        reason: 'bad-request',
+      })
+    }
+    if (thread.type === 'default' && !thread.agentId) {
+      return yield* new ThreadTurnError({
+        message: 'Default threads require an assigned agent.',
+        reason: 'bad-request',
+      })
+    }
+
+    return hydratedInputMessage
+  })
+}
+
+function createRecentHistoryLoaderEffect(params: {
+  runEffect: (effect: Effect.Effect<ChatMessage[], RecentHistoryLoadError>) => Promise<ChatMessage[]>
+  threadMessageService: ReturnType<typeof makeThreadMessageService>
+  threadRef: RecordIdRef
+  attachmentService: ReturnType<typeof makeAttachmentService>
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+}) {
+  const { runEffect, threadMessageService, threadRef, attachmentService, orgRef, userRef } = params
+
+  return Effect.gen(function* () {
+    const cachedRecentHistory = yield* Effect.cached(
+      Effect.gen(function* () {
+        const persistedRecentHistory = yield* threadMessageService.listRecentMessagesEffect(threadRef, 64)
+        if (persistedRecentHistory.length === 0) {
+          return [] as ChatMessage[]
+        }
+
+        return yield* validateAndHydrateThreadMessagesEffect({
+          attachmentService,
+          orgRef,
+          userRef,
+          messages: persistedRecentHistory,
+          errorMessage: 'Failed to validate recent thread history.',
+        })
+      }),
+    )
+
+    return () => runEffect(cachedRecentHistory)
+  })
+}
+
+function loadPersistedLiveHistoryEffect(params: {
+  threadMessageService: ReturnType<typeof makeThreadMessageService>
+  threadRef: RecordIdRef
+  persistedCompactionCursor?: string
+  attachmentService: ReturnType<typeof makeAttachmentService>
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+}): Effect.Effect<ChatMessage[], ThreadTurnPreparationError> {
+  const { threadMessageService, threadRef, persistedCompactionCursor, attachmentService, orgRef, userRef } = params
+
+  return Effect.gen(function* () {
+    const persistedLiveHistory = yield* threadMessageService
+      .listMessagesAfterCursorEffect(threadRef, persistedCompactionCursor)
+      .pipe(
+        Effect.withSpan('ThreadTurnPreparation.loadPersistedHistory'),
+        Effect.mapError(
+          (error) => new ThreadTurnPreparationError({ message: 'Failed to load thread history.', cause: error }),
+        ),
+      )
+
+    if (persistedLiveHistory.length === 0) {
+      return [] as ChatMessage[]
+    }
+
+    return yield* validateAndHydrateThreadMessagesEffect({
+      attachmentService,
+      orgRef,
+      userRef,
+      messages: persistedLiveHistory,
+      errorMessage: 'Failed to validate thread history.',
+    }).pipe(Effect.withSpan('ThreadTurnPreparation.validateAndHydrateHistory'))
+  })
+}
+
+function deriveTurnMessageInputs(params: {
+  params: ThreadRunCoreParams
+  inputMessage?: ChatMessage
+  liveHistory: ChatMessage[]
+  shouldPersistInputMessage: boolean
+}): {
+  userMessage?: ChatMessage
+  originalMessages: ChatMessage[]
+  referenceUserMessage?: ChatMessage
+  messageText: string
+} {
+  const { params: turnParams, inputMessage, liveHistory } = params
+
+  const userMessage: ChatMessage | undefined = inputMessage
+    ? {
+        ...inputMessage,
+        id: inputMessage.id,
+        role: 'user',
+        parts: inputMessage.parts,
+        metadata: { ...inputMessage.metadata, createdAt: toTimestamp(inputMessage.metadata?.createdAt) },
+      }
+    : undefined
+
+  const originalMessages = userMessage ? upsertChatHistoryMessage(liveHistory, userMessage) : liveHistory
+  const referenceUserMessage =
+    turnParams.kind === 'planTurn'
+      ? undefined
+      : (userMessage ?? [...liveHistory].reverse().find((message) => message.role === 'user'))
+
+  const messageText =
+    turnParams.kind === 'planTurn'
+      ? `${turnParams.planTurn.nodeSpec.label}\n${turnParams.planTurn.nodeSpec.objective}\n${turnParams.planTurn.nodeSpec.instructions}`
+      : referenceUserMessage
+        ? extractMessageText(referenceUserMessage).trim()
+        : ''
+
+  return { userMessage, originalMessages, referenceUserMessage, messageText }
+}
+
+const prepareThreadRunCoreEffect = Effect.fn('ThreadTurnPreparation.prepareThreadRunCore')(function* (
+  deps: ThreadTurnPreparationRuntimeDeps,
+  params: ThreadRunCoreParams,
+) {
+  const runtimeAdapters = getRuntimeAdapters()
+  const turnHooks = getTurnHooks()
+  const workspaceProvider = runtimeAdapters.workspaceProvider
+  const workspacePromise =
+    params.kind !== 'approvalContinuation' && workspaceProvider
+      ? workspaceProvider.getWorkspace(params.orgRef)
+      : Promise.resolve<Record<string, unknown>>({})
+  const attachmentService = deps.attachmentService
+  const executionPlanService = deps.executionPlanService
+  const learnedSkillService = deps.learnedSkillService
+  const memoryService = deps.memoryService
+  const planRunService = deps.planRunService
+  const threadMessageService = deps.threadMessageService
+  const threadService = deps.threadService
+  const contextCompactionRuntime = deps.contextCompactionRuntime
+  const chatRunRegistry = deps.chatRunRegistry
+  const { thread, threadRef, orgRef, userRef, userName } = params
+  const orgIdString = recordIdToString(orgRef, TABLES.ORGANIZATION)
+  const userIdString = recordIdToString(userRef, TABLES.USER)
+  const threadIdString = recordIdToString(threadRef, TABLES.THREAD)
+
+  const shouldPersistInputMessage = params.kind === 'userTurn' ? params.skipInputMessagePersistence !== true : false
+  const shouldProcessPostRunSideEffects =
+    params.kind !== 'planTurn' &&
+    (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage)
+  const inputMessage =
+    params.kind === 'userTurn'
+      ? yield* validateUserTurnInputMessageEffect({
+          thread,
+          inputMessage: params.inputMessage,
+          attachmentService,
+          orgRef,
+          userRef,
+        })
+      : undefined
+  const currentContext = yield* Effect.context()
+  const runPromiseWithCurrentContext = Effect.runPromiseWith(currentContext)
+
+  // Start workspace fetch early unless approval handling will short-circuit the turn.
+  const threadRecord = yield* waitForThreadCompactionIfNeeded(deps, threadRef).pipe(
+    Effect.mapError(
+      (error) => new ThreadTurnPreparationError({ message: 'Failed to wait for thread compaction.', cause: error }),
+    ),
+    Effect.withSpan('ThreadTurnPreparation.waitForCompactionGate'),
+  )
+  // Plan turns run without the chat lease — they must not block or be blocked by user messages.
+  if (params.kind !== 'planTurn') {
+    const persistedActiveRunId = toOptionalTrimmedString(threadRecord.activeRunId)
+    if (persistedActiveRunId && !(yield* threadService.hasActiveRunLease(threadRef))) {
+      const clearedStaleRun = yield* threadService.clearStaleActiveRunIfMissingFromRegistry(threadRef)
+      if (!clearedStaleRun) {
+        return yield* new ThreadTurnError({ message: 'A chat run is already active.', reason: 'conflict' })
+      }
+    }
+  }
+
+  if (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn') {
+    const approvedAssistantMessage = [...params.approvalMessages]
+      .reverse()
+      .find((m) => m.role === 'assistant' && hasApprovalRespondedParts(m))
+    if (!approvedAssistantMessage) {
+      return yield* new ThreadTurnError({ message: 'No approval-responded message found.', reason: 'bad-request' })
+    }
+    yield* threadMessageService
+      .upsertMessagesEffect({ threadId: threadRef, messages: [approvedAssistantMessage] })
+      .pipe(Effect.withSpan('ThreadTurnPreparation.persistApprovalMessage'))
+  }
+
+  const persistedCompactionCursor = toOptionalTrimmedString(threadRecord.lastCompactedMessageId) ?? undefined
+  const loadRecentHistory = yield* createRecentHistoryLoaderEffect({
+    runEffect: (effect) => runPromiseWithCurrentContext(effect),
+    threadMessageService,
+    threadRef,
+    attachmentService,
+    orgRef,
+    userRef,
+  })
+  const liveHistory = yield* loadPersistedLiveHistoryEffect({
+    threadMessageService,
+    threadRef,
+    persistedCompactionCursor,
+    attachmentService,
+    orgRef,
+    userRef,
+  })
+  const { userMessage, originalMessages, referenceUserMessage, messageText } = deriveTurnMessageInputs({
+    params,
+    inputMessage,
+    liveHistory,
+    shouldPersistInputMessage,
+  })
+
+  if (userMessage && shouldPersistInputMessage) {
+    yield* threadMessageService
+      .upsertMessagesEffect({ threadId: threadRef, messages: [userMessage] })
+      .pipe(Effect.withSpan('ThreadTurnPreparation.persistUserMessage'))
+  }
+
+  let allAssistantMessages: ChatMessage[] = []
+
+  const respondedBy = recordIdToString(userRef, TABLES.USER)
+  if (params.kind === 'approvalContinuation') {
+    yield* executionPlanService
+      .applyApprovalResponseFromMessages({
+        threadId: threadRef,
+        approvalMessages: params.approvalMessages,
+        respondedBy,
+      })
+      .pipe(Effect.withSpan('ThreadTurnPreparation.applyApprovalContinuation'))
+
+    return {
+      originalMessages,
+      run: () => Effect.succeed({ 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) {
+    return yield* new ThreadTurnError({ message: 'Core threads require a thread type.', reason: 'bad-request' })
+  }
+  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 = yield* effectTryPromise(
+    () =>
+      assembleThreadTurnContext({
+        thread,
+        threadRef,
+        orgRef,
+        userRef,
+        userName,
+        orgIdString,
+        userIdString,
+        messageText,
+        workspacePromise,
+        workspaceProvider,
+        turnHooks,
+      }),
+    'Failed to assemble thread turn context.',
+  ).pipe(Effect.withSpan('ThreadTurnPreparation.assembleThreadTurnContext'))
+  const {
+    workspace,
+    onboardingActive,
+    linearInstalled,
+    githubInstalled,
+    indexedRepoContext,
+    promptContext,
+    retrievedKnowledgeSection,
+    buildContextResult,
+    hookInstructionSections,
+  } = assembledContext
+
+  let memoryBlock = threadService.formatMemoryBlockForPrompt(threadRecord)
+  const executionPlanInstructionSectionCache = createExecutionPlanInstructionSectionCache({
+    disabled: false,
+    loadPlansEffect: () =>
+      Effect.gen(function* () {
+        const runs = yield* planRunService.getActiveRunRecords(threadRef)
+        return yield* Effect.forEach(runs, (run) => planRunService.toSerializablePlan(run, { slim: true }))
+      }).pipe(Effect.mapError(toExecutionPlanCacheError)),
+  })
+  const getExecutionPlanInstructionSections = (): Effect.Effect<string[] | undefined, ThreadTurnStreamingError> =>
+    executionPlanInstructionSectionCache
+      .getSectionsEffect()
+      .pipe(
+        Effect.mapError(
+          (error) =>
+            new ThreadTurnStreamingError({ message: 'Failed to load execution plan instructions.', cause: error }),
+        ),
+      )
+  const invalidateExecutionPlanInstructionSections = () => {
+    executionPlanInstructionSectionCache.invalidate()
+  }
+  if (userMessage) {
+    const appliedHumanInput = yield* executionPlanService
+      .applyHumanInputFromUserMessage({ threadId: threadRef, message: userMessage, respondedBy })
+      .pipe(Effect.withSpan('ThreadTurnPreparation.applyExecutionPlanHumanInput'))
+    if (appliedHumanInput) {
+      invalidateExecutionPlanInstructionSections()
+    }
+  }
+
+  const preSeededMemoriesByAgent = new Map<string, string | undefined>()
+  const getPreSeededMemoriesSection = (
+    agentId: string,
+  ): Effect.Effect<string | undefined, ThreadTurnStreamingError> => {
+    if (preSeededMemoriesByAgent.has(agentId)) {
+      return Effect.succeed(preSeededMemoriesByAgent.get(agentId))
+    }
+
+    return memoryService
+      .getTopMemories({ orgId: orgIdString, agentName: agentId, limit: PRESEEDED_MEMORY_LOOKUP_LIMIT })
+      .pipe(
+        Effect.tap((preSeededMemories) =>
+          Effect.sync(() => {
+            preSeededMemoriesByAgent.set(agentId, preSeededMemories)
+          }),
+        ),
+        Effect.mapError(
+          (error) =>
+            new ThreadTurnStreamingError({
+              message: `Failed to load pre-seeded memories for ${agentId}.`,
+              cause: error,
+            }),
+        ),
+      )
+  }
+
+  const learnedSkillsByAgent = new Map<string, string | undefined>()
+  const getLearnedSkillsSection = (
+    agentId: string,
+    queryText = messageText,
+  ): Effect.Effect<string | undefined, ThreadTurnStreamingError> => {
+    const cacheKey = `${agentId}::${queryText}`
+    if (learnedSkillsByAgent.has(cacheKey)) {
+      return Effect.succeed(learnedSkillsByAgent.get(cacheKey))
+    }
+
+    return Effect.gen(function* () {
+      const section = yield* learnedSkillService
+        .retrieveForTurn({ orgId: orgIdString, agentId, query: queryText, limit: 3, minConfidence: 0.6 })
+        .pipe(
+          Effect.catch((error: unknown) =>
+            Effect.sync(() => {
+              aiLogger.warn`Failed to retrieve learned skills for ${agentId}: ${error}`
+              return undefined
+            }),
+          ),
+        )
+      learnedSkillsByAgent.set(cacheKey, section)
+      return section
+    }).pipe(
+      Effect.mapError(
+        (error) =>
+          new ThreadTurnStreamingError({ message: `Failed to load learned skills for ${agentId}.`, cause: error }),
+      ),
+    )
+  }
+
+  const persistedCompactionSummary =
+    persistedCompactionCursor && typeof threadRecord.compactionSummary === 'string'
+      ? threadRecord.compactionSummary
+      : ''
+  const messagesForContext = userMessage ? upsertChatHistoryMessage(liveHistory, userMessage) : liveHistory
+  const threadTurnMessageContext = createThreadTurnMessageContext({
+    contextCompactionRuntime,
+    persistedCompactionSummary,
+    messagesForContext,
+    orgRef: recordIdToString(orgRef, TABLES.ORGANIZATION),
+    userRef: recordIdToString(userRef, TABLES.USER),
+    latestUserMessageId: referenceUserMessage?.id ?? '',
+    listReadableUploadsFromMessages: (uploadParams) =>
+      attachmentService.listReadableUploadsFromMessages({
+        messages: uploadParams.messages.map((message) => ({ parts: message.parts })),
+        orgId: uploadParams.orgId,
+        userId: uploadParams.userId,
+      }),
+  })
+  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: threadTurnMessageContext.listReadableUploads(toolParams.extraMessages),
+    includeExecutionPlanTools: toolParams.includeExecutionPlanTools,
+    onExecutionPlanChanged: invalidateExecutionPlanInstructionSections,
+    context: buildContextResult,
+  })
+  const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(buildContextResult)
+
+  const executeRun = (runParams: {
+    serverRunId: string
+    runAbort: ReturnType<typeof createServerRunAbortController>
+    writer?: UIMessageStreamWriter<ChatMessage>
+  }): Effect.Effect<PreparedThreadTurnResult | void, DatabaseError | ThreadTurnError | ThreadTurnPreparationError> =>
+    Effect.ensuring(
+      Effect.gen(function* () {
+        const currentRunAbort = runParams.runAbort
+        const toAbortReason = (): unknown =>
+          currentRunAbort.signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
+        const failIfRunAborted = (): Effect.Effect<void, ThreadTurnPreparationError> =>
+          currentRunAbort.signal.aborted
+            ? Effect.fail(
+                new ThreadTurnPreparationError({ message: 'Thread turn was aborted.', cause: toAbortReason() }),
+              )
+            : Effect.void
+        yield* failIfRunAborted()
+        if (params.kind !== 'planTurn') {
+          yield* threadService
+            .setActiveTurn(threadRef, runParams.serverRunId, params.streamId ?? null)
+            .pipe(Effect.withSpan('ThreadTurnPreparation.setActiveTurn'))
+        }
+
+        const agentFactoryConfig = getResolvedAgentFactoryConfig()
+
+        const streamCtx: StreamAgentResponseContext = {
+          turnHooks,
+          thread,
+          threadRef,
+          orgRef,
+          userRef,
+          userName,
+          onboardingActive,
+          linearInstalled,
+          githubInstalled,
+          buildContextResult,
+          getExecutionPlanInstructionSections,
+          getPreSeededMemoriesSection,
+          getLearnedSkillsSection,
+          promptContext,
+          retrievedKnowledgeSection,
+          memoryBlock,
+          hookInstructionSections,
+          runAbortSignal: currentRunAbort.signal,
+        }
+
+        const { runVisibleAgent } = createThreadTurnVisibleAgentRunner({
+          agentFactoryConfig: { buildAgentTools: agentFactoryConfig.buildAgentTools },
+          buildTurnToolParams,
+          threadTurnMessageContext,
+          threadMessageService,
+          threadRef,
+          writer: runParams.writer,
+          streamCtx,
+          agentIdentityOverrides,
+          getMemoryBlock: () => memoryBlock,
+          setMemoryBlock: (value: string) => {
+            memoryBlock = value
+          },
+          onPersistedMessage: (persistedMessage: ChatMessage) => {
+            allAssistantMessages = upsertChatHistoryMessage(allAssistantMessages, persistedMessage)
+          },
+          failIfRunAborted,
+        })
+
+        if (params.kind === 'planTurn') {
+          const planTurn = params.planTurn
+          const submitPlanTurnNodeResultTool = createTool({
+            description: buildPlanTurnSubmitToolDescription(planTurn),
+            inputSchema: PlanNodeResultSubmissionSchema,
+            execute: (result) =>
+              executionPlanService.submitPlanTurnResult({
+                threadId: threadRef,
+                runId: planTurn.runId,
+                nodeId: planTurn.nodeId,
+                emittedBy: planTurn.nodeSpec.owner.ref,
+                input: result,
+              }),
+          })
+
+          yield* effectTryPromise(
+            () =>
+              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 },
+              }),
+            'Failed to execute plan-turn visible agent.',
+          ).pipe(Effect.withSpan('ThreadTurnPreparation.executePlanTurn'))
+        } else if (thread.type === 'default') {
+          if (!thread.agentId) {
+            return yield* new ThreadTurnError({
+              message: 'Direct threads require an assigned agent.',
+              reason: 'bad-request',
+            })
+          }
+          const directAgentId = thread.agentId
+          yield* effectTryPromise(
+            () => runVisibleAgent({ agentId: directAgentId, mode: 'direct' }),
+            'Failed to execute direct thread agent.',
+          ).pipe(Effect.withSpan('ThreadTurnPreparation.executeDirectThread'))
+        } else {
+          const wsMembers = (thread as { members?: string[] }).members ?? []
+          const members = wsMembers.length > 0 ? wsMembers : [...getAgentRoster()]
+          const fallbackAgentId = coreThreadProfile?.config.agentId ?? defaultLeadAgentId
+          yield* failIfRunAborted()
+          writeMultiAgentEvent(runParams.writer, { phase: 'routing', note: 'Routing this turn to the right agent.' })
+
+          const recentContext = threadTurnMessageContext.currentMessages
+            .slice(-6)
+            .map((m) => `${m.role}: ${extractMessageText(m).slice(0, 200)}`)
+            .join('\n')
+
+          const triageResult = yield* effectTryPromise(
+            () =>
+              triageThreadMessage({
+                threadTitle: thread.title,
+                members,
+                messageText,
+                recentContext,
+                displayNamesById: agentIdentityOverrides.displayNamesById,
+                shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
+                routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
+              }),
+            'Failed to triage group thread message.',
+          ).pipe(Effect.withSpan('ThreadTurnPreparation.routeGroupThread'))
+          yield* failIfRunAborted()
+
+          const runGroupAgent = (agentId: string, options?: { routingContext?: string }) => {
+            const additionalSections = [...(coreInstructionSections ?? []), ...hookInstructionSections]
+            if (options?.routingContext) {
+              additionalSections.push(`<routing-context>\n${options.routingContext}\n</routing-context>`)
+            }
+            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 runVisibleAgent({
+              agentId,
+              mode: 'threadMode',
+              skills: coreThreadProfile?.skills ? [...coreThreadProfile.skills] : undefined,
+              additionalInstructionSections: additionalSections,
+            })
+          }
+
+          if (!triageResult) {
+            yield* effectTryPromise(
+              () => runGroupAgent(fallbackAgentId),
+              'Failed to execute fallback group agent.',
+            ).pipe(Effect.withSpan('ThreadTurnPreparation.executeFallbackGroupAgent'))
+            yield* failIfRunAborted()
+            writeMultiAgentEvent(runParams.writer, { phase: 'complete' })
+          } else {
+            const respondedAgents: string[] = []
+            let lastResponse = yield* effectTryPromise(
+              () => runGroupAgent(triageResult.agentId, { routingContext: triageResult.routingContext }),
+              'Failed to execute routed group agent.',
+            ).pipe(Effect.withSpan('ThreadTurnPreparation.executeRoutedGroupAgent'))
+            respondedAgents.push(triageResult.agentId)
+            yield* failIfRunAborted()
+
+            while (respondedAgents.length < 3) {
+              const lastResponseText = extractMessageText(lastResponse).slice(0, 500)
+              const checkResult = yield* effectTryPromise(
+                () =>
+                  checkForNextAgent({
+                    threadTitle: thread.title,
+                    members,
+                    messageText,
+                    respondedAgents,
+                    lastResponseSummary: lastResponseText,
+                    displayNamesById: agentIdentityOverrides.displayNamesById,
+                    shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
+                    routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
+                  }),
+                'Failed to select the next group agent.',
+              ).pipe(Effect.withSpan('ThreadTurnPreparation.selectNextGroupAgent'))
+              yield* failIfRunAborted()
+
+              if (checkResult.done || !checkResult.agentId) break
+
+              writeMultiAgentEvent(runParams.writer, {
+                phase: 'waiting-for-agent',
+                agentId: checkResult.agentId,
+                agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
+                note: checkResult.routingContext ?? undefined,
+              })
+
+              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: yield* Clock.currentTimeMillis } as MessageMetadata,
+              }
+              yield* failIfRunAborted()
+              yield* threadMessageService
+                .upsertMessagesEffect({ threadId: threadRef, messages: [bridgeMessage] })
+                .pipe(Effect.withSpan('ThreadTurnPreparation.persistBridgeMessage'))
+              threadTurnMessageContext.appendMessages([bridgeMessage])
+              yield* failIfRunAborted()
+
+              lastResponse = yield* effectTryPromise(
+                () => runGroupAgent(checkResult.agentId, { routingContext: checkResult.routingContext ?? undefined }),
+                'Failed to execute follow-up group agent.',
+              ).pipe(Effect.withSpan('ThreadTurnPreparation.executeFollowUpGroupAgent'))
+              respondedAgents.push(checkResult.agentId)
+              yield* failIfRunAborted()
+              writeMultiAgentEvent(runParams.writer, {
+                phase: 'agent-message-persisted',
+                agentId: checkResult.agentId,
+                agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
+                messageId: lastResponse.id,
+              })
+            }
+
+            yield* failIfRunAborted()
+            writeMultiAgentEvent(runParams.writer, { phase: 'complete' })
+          }
+        }
+      }),
+      Effect.gen(function* () {
+        const latestThreadRecord = yield* threadService.getById(threadRef)
+
+        yield* finalizeTurnRunEffect({
+          serverRunId: runParams.serverRunId,
+          getEntity: () => Effect.succeed(latestThreadRecord),
+          getUncompactedMessages: (cursor) =>
+            threadMessageService
+              .listMessagesAfterCursorEffect(threadRef, cursor)
+              .pipe(
+                Effect.mapError((error) => new TurnLifecycleError({ message: getErrorMessage(error), cause: error })),
+              ),
+          assessCompaction: (summaryText, messages) =>
+            contextCompactionRuntime.shouldCompactHistory({
+              summaryText,
+              liveMessages: messages,
+              contextSize: CONTEXT_WINDOW_TOKENS,
+            }),
+          enqueueCompaction: () =>
+            enqueueContextCompaction({
+              domain: 'thread',
+              entityId: threadIdString,
+              contextSize: CONTEXT_WINDOW_TOKENS,
+            }),
+          unregisterRun: () => undefined,
+          clearActiveRunId: (runId) =>
+            Effect.gen(function* () {
+              const activeStreamId = yield* threadService.getActiveStreamId(threadRef)
+              yield* threadService.clearActiveTurn(threadRef, { runId, streamId: activeStreamId })
+            }).pipe(
+              Effect.mapError((error) => new TurnLifecycleError({ message: getErrorMessage(error), cause: error })),
+            ),
+          disposeAbort: () => runParams.runAbort.dispose(),
+          activeStreamId: params.streamId,
+          clearActiveStreamId: (streamId) =>
+            Effect.gen(function* () {
+              const activeRunId = yield* threadService.getActiveRunId(threadRef)
+              if (!activeRunId) {
+                return
+              }
+              yield* threadService.clearActiveTurn(threadRef, { runId: activeRunId, streamId })
+            }).pipe(
+              Effect.mapError((error) => new TurnLifecycleError({ message: getErrorMessage(error), cause: error })),
+            ),
+        }).pipe(
+          Effect.withSpan('ThreadTurnPreparation.finalizeTurnRun'),
+          Effect.mapError(
+            (error) => new ThreadTurnPreparationError({ message: 'Failed to finalize thread turn run.', cause: error }),
+          ),
+        )
+
+        if (allAssistantMessages.length > 0 && shouldProcessPostRunSideEffects) {
+          yield* effectTryPromise(
+            () =>
+              runPostTurnSideEffects({
+                thread,
+                threadRef,
+                orgRef,
+                userRef,
+                userName,
+                orgIdString,
+                threadIdString,
+                onboardingActive,
+                workspace,
+                allAssistantMessages,
+                referenceUserMessage,
+                referenceUserMessageId: referenceUserMessage?.id ?? '',
+                loadRecentHistory,
+                listReadableUploads: () => threadTurnMessageContext.listReadableUploads(),
+                memoryBlock,
+                visibleThreadAgentId,
+                defaultLeadAgentId,
+                latestThreadRecord,
+                isUserTurn: params.kind === 'userTurn',
+                agentDisplayNamesById: agentIdentityOverrides.displayNamesById,
+              }),
+            'Failed to run post-turn side effects.',
+          ).pipe(Effect.withSpan('ThreadTurnPreparation.runPostTurnSideEffects'))
+        }
+
+        if (allAssistantMessages.length > 0 && params.kind !== 'planTurn') {
+          const afterTurn = turnHooks.afterTurn
+          if (afterTurn) {
+            yield* effectTryPromise(
+              () =>
+                afterTurn({
+                  thread,
+                  threadRef,
+                  orgRef,
+                  userRef,
+                  userName,
+                  onboardingActive,
+                  referenceUserMessage,
+                  assistantMessages: allAssistantMessages,
+                  latestThreadRecord,
+                  context: buildContextResult,
+                }),
+              'Failed to run afterTurn hook.',
+            ).pipe(Effect.withSpan('ThreadTurnPreparation.afterTurnHook'))
+          }
+        }
+      }).pipe(
+        Effect.catch((postRunError) =>
+          Effect.sync(() => {
+            aiLogger.error`Thread post-run cleanup failed: ${postRunError}`
+          }),
+        ),
+      ),
+    ).pipe(
+      Effect.mapError((error) =>
+        error._tag === 'ServiceError'
+          ? new ThreadTurnPreparationError({ message: error.message, cause: error.cause })
+          : error,
+      ),
+    )
+
+  const toPreparedThreadTurnResult = (): PreparedThreadTurnResult => ({
+    inputMessageId: referenceUserMessage?.id,
+    assistantMessages: [...allAssistantMessages],
+  })
+
+  const run = (writer?: UIMessageStreamWriter<ChatMessage>) => {
+    const serverRunId = Bun.randomUUIDv7()
+
+    const runEffect =
+      params.kind === 'planTurn'
+        ? Effect.gen(function* () {
+            const runAbort = createServerRunAbortController(
+              [params.abortSignal].filter((signal): signal is AbortSignal => Boolean(signal)),
+            )
+            yield* Effect.annotateCurrentSpan('serverRunId', serverRunId)
+            const runResult = yield* executeRun({ serverRunId, runAbort, writer })
+            return runResult ?? toPreparedThreadTurnResult()
+          })
+        : threadService.withActiveRunLease(threadRef, (leaseAbortSignal) =>
+            Effect.gen(function* () {
+              const runAbort = createServerRunAbortController(
+                [params.abortSignal, leaseAbortSignal].filter((signal): signal is AbortSignal => Boolean(signal)),
+              )
+              yield* Effect.annotateCurrentSpan('serverRunId', serverRunId)
+              const runResult = yield* chatRunRegistry.trackRunEffect(
+                serverRunId,
+                runAbort.controller,
+                executeRun({ serverRunId, runAbort, writer }),
+              )
+              return runResult ?? toPreparedThreadTurnResult()
+            }),
+          )
+
+    return runEffect.pipe(Effect.withSpan('ThreadTurnPreparation.executeRun'), Effect.provide(currentContext))
+  }
+
+  return { originalMessages, run }
+})
+
+interface ThreadTurnPreparationDeps {
+  attachment: ReturnType<typeof makeAttachmentService>
+  chatRunRegistry: Context.Service.Shape<typeof ChatRunRegistryTag>
+  compactionCoordination: Context.Service.Shape<typeof CompactionCoordinationTag>
+  executionPlan: ReturnType<typeof makeExecutionPlanService>
+  learnedSkill: ReturnType<typeof makeLearnedSkillService>
+  memory: ReturnType<typeof createMemoryService>
+  planRun: ReturnType<typeof makePlanRunService>
+  threadMessage: ReturnType<typeof makeThreadMessageService>
+  thread: ReturnType<typeof makeThreadService>
+  helperModelRuntime: HelperModelRuntime
+}
+
+export function makeThreadTurnPreparationService(deps: ThreadTurnPreparationDeps) {
+  const runtimeDeps: ThreadTurnPreparationRuntimeDeps = {
+    attachmentService: deps.attachment,
+    chatRunRegistry: deps.chatRunRegistry,
+    compactionCoordination: deps.compactionCoordination,
+    executionPlanService: deps.executionPlan,
+    learnedSkillService: deps.learnedSkill,
+    memoryService: deps.memory,
+    planRunService: deps.planRun,
+    threadMessageService: deps.threadMessage,
+    threadService: deps.thread,
+    contextCompactionRuntime: createWiredContextCompactionRuntime({
+      helperModelRuntime: deps.helperModelRuntime,
+      now: nowEpochMillis,
+      randomId: () => Bun.randomUUIDv7(),
+    }),
+  }
+  const annotateTurnSpans = <A, E, R>(params: ThreadRunCoreParams, effect: Effect.Effect<A, E, R>) =>
+    effect.pipe(
+      Effect.annotateSpans(
+        compactSpanAttributes({
+          ...buildThreadTurnSpanAttributes({
+            threadRef: params.threadRef,
+            orgRef: params.orgRef,
+            userRef: params.userRef,
+            kind: params.kind,
+            streamId: params.streamId,
+            agentId: params.agentIdOverride,
+            threadType: params.thread.type,
+            planRunId: params.kind === 'planTurn' ? params.planTurn.runId : undefined,
+            planNodeId: params.kind === 'planTurn' ? params.planTurn.nodeId : undefined,
+          }),
+          userName: params.userName ?? undefined,
+        }),
+      ),
+    )
+
+  return {
+    prepareThreadRunCoreEffect(params: ThreadRunCoreParams) {
+      return annotateTurnSpans(params, prepareThreadRunCoreEffect(runtimeDeps, params))
+    },
+    prepareThreadRunCore(params: ThreadRunCoreParams) {
+      return annotateTurnSpans(params, prepareThreadRunCoreEffect(runtimeDeps, params))
+    },
+  } as const
+}
+
+export class ThreadTurnPreparationServiceTag extends Context.Service<
+  ThreadTurnPreparationServiceTag,
+  ReturnType<typeof makeThreadTurnPreparationService>
+>()('@lota-sdk/core/ThreadTurnPreparationService') {}
+
+export const ThreadTurnPreparationServiceLive = Layer.effect(
+  ThreadTurnPreparationServiceTag,
+  Effect.gen(function* () {
+    const attachment = yield* AttachmentServiceTag
+    const chatRunRegistry = yield* ChatRunRegistryTag
+    const compactionCoordination = yield* CompactionCoordinationTag
+    const executionPlan = yield* ExecutionPlanServiceTag
+    const learnedSkill = yield* LearnedSkillServiceTag
+    const memory = yield* MemoryServiceTag
+    const planRun = yield* PlanRunServiceTag
+    const threadMessage = yield* ThreadMessageServiceTag
+    const thread = yield* ThreadServiceTag
+    return makeThreadTurnPreparationService({
+      attachment,
+      chatRunRegistry,
+      compactionCoordination,
+      executionPlan,
+      learnedSkill,
+      memory,
+      planRun,
+      threadMessage,
+      thread,
+      helperModelRuntime: yield* HelperModelTag,
+    })
+  }),
+)