@lota-sdk/core 0.4.8 → 0.4.9

package/src/services/thread/thread-record-store.ts

@@ -0,0 +1,155 @@
+import { Duration, Effect, Schedule } from 'effect'
+
+import type { RecordIdInput, RecordIdRef } from '../../db/record-id'
+import { ensureRecordId, isRecordIdInput, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { BadRequestError, DatabaseError, NotFoundError } from '../../effect/errors'
+import { ThreadSchema } from './thread.types'
+import type { ThreadRecord } from './thread.types'
+
+const THREAD_UNIQUE_LOOKUP_MAX_ATTEMPTS = 20
+const THREAD_UNIQUE_LOOKUP_RETRY_DELAY_MS = 100
+
+function requireThreadIdEffect(id: unknown): Effect.Effect<RecordIdInput, BadRequestError> {
+  return isRecordIdInput(id)
+    ? Effect.succeed(id)
+    : Effect.fail(new BadRequestError({ message: `Invalid record id for table ${TABLES.THREAD}` }))
+}
+
+type UniqueThreadLookupParams = {
+  type: 'default' | 'thread'
+  organizationId: RecordIdRef
+  userId: RecordIdRef
+  agentId?: string
+  threadType?: string
+}
+
+function buildExistingThreadLookupMessage(params: UniqueThreadLookupParams): string {
+  const scope = {
+    organizationId: recordIdToString(params.organizationId, TABLES.ORGANIZATION),
+    userId: recordIdToString(params.userId, TABLES.USER),
+    ...(params.agentId ? { agentId: params.agentId } : {}),
+    ...(params.threadType ? { threadType: params.threadType } : {}),
+  }
+  return `Thread lookup failed after duplicate ${params.type} thread create: ${JSON.stringify(scope)}`
+}
+type ThreadOrderKey = Extract<keyof ThreadRecord, string>
+
+function mapThreadStoreError(message: string) {
+  return Effect.mapError((cause: unknown) => new DatabaseError({ message, cause }))
+}
+
+export interface ThreadRecordStore {
+  findById(id: unknown): Effect.Effect<ThreadRecord | null, DatabaseError | BadRequestError>
+  getById(id: unknown): Effect.Effect<ThreadRecord, DatabaseError | BadRequestError | NotFoundError>
+  findAll(
+    filter?: Record<string, unknown>,
+    options?: { limit?: number; offset?: number; orderBy?: ThreadOrderKey; orderDir?: 'ASC' | 'DESC' },
+  ): Effect.Effect<ThreadRecord[], DatabaseError>
+  create(data: Record<string, unknown>): Effect.Effect<ThreadRecord, DatabaseError>
+  update(id: unknown, data: Record<string, unknown>): Effect.Effect<ThreadRecord, DatabaseError | NotFoundError>
+  deleteById(id: unknown): Effect.Effect<void, DatabaseError | NotFoundError>
+  findThreadByUniqueLookup(params: UniqueThreadLookupParams): Effect.Effect<ThreadRecord | null, DatabaseError>
+  waitForExistingThread(params: UniqueThreadLookupParams): Effect.Effect<ThreadRecord, NotFoundError | DatabaseError>
+}
+
+export function createThreadRecordStore(deps: { db: SurrealDBService }): ThreadRecordStore {
+  const { db } = deps
+  function findById(id: unknown): Effect.Effect<ThreadRecord | null, DatabaseError | BadRequestError> {
+    return Effect.gen(function* () {
+      const threadId = yield* requireThreadIdEffect(id)
+      return yield* db
+        .findOne(TABLES.THREAD, { id: ensureRecordId(threadId, TABLES.THREAD) }, ThreadSchema)
+        .pipe(mapThreadStoreError('Failed to load thread record.'))
+    })
+  }
+
+  function getById(id: unknown): Effect.Effect<ThreadRecord, DatabaseError | BadRequestError | NotFoundError> {
+    return Effect.gen(function* () {
+      const record = yield* findById(id)
+      if (!record) {
+        return yield* new NotFoundError({ resource: TABLES.THREAD, message: `${TABLES.THREAD} record not found` })
+      }
+      return record
+    })
+  }
+
+  function findAll(
+    filter: Record<string, unknown> = {},
+    options?: { limit?: number; offset?: number; orderBy?: ThreadOrderKey; orderDir?: 'ASC' | 'DESC' },
+  ): Effect.Effect<ThreadRecord[], DatabaseError> {
+    return db
+      .findMany(TABLES.THREAD, filter, ThreadSchema, options)
+      .pipe(mapThreadStoreError('Failed to list threads.'))
+  }
+
+  function create(data: Record<string, unknown>): Effect.Effect<ThreadRecord, DatabaseError> {
+    return db.create(TABLES.THREAD, data, ThreadSchema).pipe(mapThreadStoreError('Failed to create thread record.'))
+  }
+
+  function update(
+    id: unknown,
+    data: Record<string, unknown>,
+  ): Effect.Effect<ThreadRecord, DatabaseError | NotFoundError> {
+    return Effect.gen(function* () {
+      const record = yield* db
+        .update(TABLES.THREAD, id, data, ThreadSchema)
+        .pipe(mapThreadStoreError('Failed to update thread record.'))
+      if (!record) {
+        return yield* new NotFoundError({ resource: TABLES.THREAD, message: `${TABLES.THREAD} record not found` })
+      }
+      return record
+    })
+  }
+
+  function deleteById(id: unknown): Effect.Effect<void, DatabaseError | NotFoundError> {
+    return Effect.gen(function* () {
+      const deleted = yield* db
+        .deleteById(TABLES.THREAD, id)
+        .pipe(mapThreadStoreError('Failed to delete thread record.'))
+      if (!deleted) {
+        return yield* new NotFoundError({ resource: TABLES.THREAD, message: `${TABLES.THREAD} record not found` })
+      }
+    })
+  }
+
+  function findThreadByUniqueLookup(
+    params: UniqueThreadLookupParams,
+  ): Effect.Effect<ThreadRecord | null, DatabaseError> {
+    return db
+      .findOne(
+        TABLES.THREAD,
+        {
+          type: params.type,
+          organizationId: params.organizationId,
+          userId: params.userId,
+          ...(params.agentId ? { agentId: params.agentId } : {}),
+          ...(params.threadType ? { threadType: params.threadType } : {}),
+        },
+        ThreadSchema,
+      )
+      .pipe(mapThreadStoreError('Failed to find thread by unique lookup.'))
+  }
+
+  function waitForExistingThread(
+    params: UniqueThreadLookupParams,
+  ): Effect.Effect<ThreadRecord, NotFoundError | DatabaseError> {
+    const poll = findThreadByUniqueLookup(params).pipe(
+      Effect.flatMap((result) => (result ? Effect.succeed(result) : Effect.fail('not_found' as const))),
+    )
+
+    return Effect.retry(poll, {
+      times: THREAD_UNIQUE_LOOKUP_MAX_ATTEMPTS - 1,
+      schedule: Schedule.fixed(Duration.millis(THREAD_UNIQUE_LOOKUP_RETRY_DELAY_MS)),
+    }).pipe(
+      Effect.mapError((error) =>
+        error === 'not_found'
+          ? new NotFoundError({ resource: TABLES.THREAD, message: buildExistingThreadLookupMessage(params) })
+          : error,
+      ),
+    )
+  }
+
+  return { findById, getById, findAll, create, update, deleteById, findThreadByUniqueLookup, waitForExistingThread }
+}

package/src/services/thread/thread-title.service.ts

@@ -0,0 +1,74 @@
+import { THREAD } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+
+import { chatLogger } from '../../config/logger'
+import type { RecordIdRef } from '../../db/record-id'
+import type { HelperModelRuntime } from '../../runtime/helper-model'
+import { HelperModelTag } from '../../runtime/helper-model'
+import { deriveTitle, limitTitleWords, normalizeTitle } from '../../runtime/title-helpers'
+import {
+  createThreadTitleGeneratorAgent,
+  THREAD_TITLE_GENERATOR_PROMPT,
+} from '../../system-agents/title-generator.agent'
+import type { makeThreadService } from './thread.service'
+import { ThreadServiceTag } from './thread.service'
+
+const THREAD_TITLE_TIMEOUT_MS = 30_000
+
+class ThreadTitleError extends Schema.TaggedErrorClass<ThreadTitleError>()('ThreadTitleError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export function makeThreadTitleService(
+  threadService: ReturnType<typeof makeThreadService>,
+  helperModelRuntime: HelperModelRuntime,
+) {
+  return {
+    generateAndPersistTitle(threadId: RecordIdRef, sourceText: string) {
+      return Effect.gen(function* () {
+        const generatedTitle = yield* Effect.tryPromise({
+          try: () =>
+            helperModelRuntime.generateHelperText({
+              tag: 'thread-title',
+              createAgent: createThreadTitleGeneratorAgent,
+              defaultSystemPrompt: THREAD_TITLE_GENERATOR_PROMPT,
+              timeoutMs: THREAD_TITLE_TIMEOUT_MS,
+              messages: [{ role: 'user', content: sourceText }],
+            }),
+          catch: (error) => new ThreadTitleError({ message: 'Failed to generate thread title.', cause: error }),
+        }).pipe(
+          Effect.map((title) => normalizeTitle(title)),
+          Effect.catch((error) =>
+            Effect.sync(() => {
+              chatLogger.warn`Failed to generate thread title via LLM (non-fatal): ${error}`
+              return ''
+            }),
+          ),
+        )
+        const title = generatedTitle || limitTitleWords(deriveTitle(sourceText || THREAD.DEFAULT_TITLE))
+        yield* threadService
+          .update(threadId, { title, nameGenerated: true })
+          .pipe(
+            Effect.mapError(
+              (error) => new ThreadTitleError({ message: 'Failed to persist generated thread title.', cause: error }),
+            ),
+          )
+      })
+    },
+  }
+}
+
+export class ThreadTitleServiceTag extends Context.Service<
+  ThreadTitleServiceTag,
+  ReturnType<typeof makeThreadTitleService>
+>()('ThreadTitleService') {}
+
+export const ThreadTitleServiceLive = Layer.effect(
+  ThreadTitleServiceTag,
+  Effect.gen(function* () {
+    const threadService = yield* ThreadServiceTag
+    const helperModelRuntime = yield* HelperModelTag
+    return makeThreadTitleService(threadService, helperModelRuntime)
+  }),
+)

package/src/services/thread/thread-turn-execution.ts

@@ -0,0 +1,280 @@
+import type { ChatMessage, MessageMetadata, PlanNodeSpecRecord } from '@lota-sdk/shared'
+import { SUBMIT_PLAN_TURN_RESULT_TOOL_NAME, toTimestamp, withMessageCreatedAt } from '@lota-sdk/shared'
+import type { ToolSet, UIMessageStreamWriter } from 'ai'
+import { Schema, Effect } from 'effect'
+
+import { aiLogger } from '../../config/logger'
+import type { RecordIdRef } from '../../db/record-id'
+import { effectTryMaybeAsync, effectTryPromise as effectTryPromiseShared } from '../../effect/helpers'
+import { runPromise } from '../../effect/runtime'
+import type { readRuntimeAgentIdentityOverrides } from '../../runtime/agent-identity-overrides'
+import { resolveRuntimeAgentDisplayName } from '../../runtime/agent-identity-overrides'
+import { OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES } from '../../runtime/agent-runtime-policy'
+import { collectCompletedConsultTeamMessages, readOptionalString } from '../../runtime/thread-chat-helpers'
+import { nowEpochMillis } from '../../utils/date-time'
+import type { makeThreadMessageService } from './thread-message.service'
+import type { ThreadTurnPreparationError } from './thread-turn-preparation.service'
+import { streamAgentResponse } from './thread-turn-streaming'
+import type { StreamAgentResponseContext } from './thread-turn-streaming'
+import { buildThreadTurnSpanAttributes, compactSpanAttributes } from './thread-turn-tracing'
+
+type ChatStreamChunk = Parameters<UIMessageStreamWriter<ChatMessage>['write']>[0]
+
+export 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)
+}
+
+export 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)),
+    ),
+  )
+}
+
+interface VisibleAgentRunParams {
+  agentId: string
+  mode: 'direct' | 'fixedThreadMode' | 'threadMode'
+  skills?: string[]
+  additionalInstructionSections?: string[]
+  extraMessages?: ChatMessage[]
+  extraTools?: ToolSet
+  filterTools?: (tools: ToolSet) => ToolSet
+  includeExecutionPlanTools?: boolean
+  metadataPatch?: NonNullable<MessageMetadata>
+}
+
+interface VisibleAgentRunnerDeps<TBuildTurnToolParams> {
+  agentFactoryConfig: { buildAgentTools: (params: TBuildTurnToolParams) => Promise<ToolSet> | ToolSet }
+  buildTurnToolParams: (params: {
+    agentId: string
+    mode: 'direct' | 'fixedThreadMode' | 'threadMode'
+    memoryBlock: string
+    onAppendMemoryBlock: (value: string) => void
+    extraMessages?: ChatMessage[]
+    skills?: string[]
+    includeExecutionPlanTools: boolean
+  }) => TBuildTurnToolParams
+  threadTurnMessageContext: {
+    buildRunInputMessages: (extraMessages?: ChatMessage[]) => ChatMessage[]
+    appendMessages: (messages: ChatMessage[]) => void
+  }
+  threadMessageService: Pick<ReturnType<typeof makeThreadMessageService>, 'upsertMessagesEffect'>
+  threadRef: RecordIdRef
+  writer?: UIMessageStreamWriter<ChatMessage>
+  streamCtx: StreamAgentResponseContext
+  agentIdentityOverrides: ReturnType<typeof readRuntimeAgentIdentityOverrides>
+  getMemoryBlock: () => string
+  setMemoryBlock: (value: string) => void
+  onPersistedMessage: (message: ChatMessage) => void
+  failIfRunAborted: () => Effect.Effect<void, ThreadTurnPreparationError>
+}
+
+export function createThreadTurnVisibleAgentRunner<TBuildTurnToolParams>(
+  deps: VisibleAgentRunnerDeps<TBuildTurnToolParams>,
+) {
+  class ThreadTurnExecutionError extends Schema.TaggedErrorClass<ThreadTurnExecutionError>()(
+    'ThreadTurnExecutionError',
+    { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+  ) {}
+
+  const effectTryPromise = <A>(
+    evaluate: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+    message: string,
+  ): Effect.Effect<A, ThreadTurnExecutionError> =>
+    effectTryPromiseShared(evaluate, (error) => new ThreadTurnExecutionError({ message, cause: error }))
+
+  function effectFromMaybePromise<A>(
+    evaluate: () => A | PromiseLike<A>,
+    message: string,
+  ): Effect.Effect<A, ThreadTurnExecutionError> {
+    return effectTryMaybeAsync(evaluate, (error) => new ThreadTurnExecutionError({ message, cause: error }))
+  }
+
+  const buildAgentMetadataPatch = (agentId: string, agentName: string): NonNullable<MessageMetadata> => ({
+    agentId,
+    agentName,
+    semanticTerminationReason: 'none',
+  })
+
+  const failIfRunAborted = () =>
+    deps
+      .failIfRunAborted()
+      .pipe(
+        Effect.mapError(
+          (error) =>
+            new ThreadTurnExecutionError({ message: 'Thread turn was aborted during agent execution.', cause: error }),
+        ),
+      )
+
+  const createObserver = (agentId: string) => ({
+    run: <T>(fn: () => T | Promise<T>) =>
+      runPromise(
+        effectTryMaybeAsync(
+          fn,
+          (error) =>
+            new ThreadTurnExecutionError({ message: `Agent observer run failed (agent=${agentId}).`, cause: error }),
+        ),
+      ),
+    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 = (
+    response: ChatMessage,
+    agentId: string,
+    agentName: string,
+    metadataPatch?: NonNullable<MessageMetadata>,
+  ): Promise<ChatMessage> =>
+    runPromise(
+      Effect.gen(function* () {
+        yield* failIfRunAborted()
+
+        const toCommittedAssistantMessage = (
+          message: ChatMessage,
+          resolvedAgentId: string,
+          resolvedAgentName: string,
+          patch?: NonNullable<MessageMetadata>,
+        ) =>
+          withMessageCreatedAt(
+            {
+              ...message,
+              metadata: {
+                ...message.metadata,
+                ...buildAgentMetadataPatch(resolvedAgentId, resolvedAgentName),
+                ...patch,
+              },
+            },
+            toTimestamp(message.metadata?.createdAt) ?? nowEpochMillis(),
+          )
+
+        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]
+        yield* deps.threadMessageService.upsertMessagesEffect({ threadId: deps.threadRef, messages: messagesToPersist })
+
+        for (const persistedMessage of messagesToPersist) {
+          deps.threadTurnMessageContext.appendMessages([persistedMessage])
+          deps.onPersistedMessage(persistedMessage)
+        }
+        yield* failIfRunAborted()
+
+        return committed
+      }),
+    )
+
+  const runVisibleAgentEffect = Effect.fn('ThreadTurnExecution.runVisibleAgent')(function* (
+    runParams: VisibleAgentRunParams,
+  ) {
+    let runMemoryBlock = deps.getMemoryBlock()
+    const includeExecutionPlanTools = runParams.includeExecutionPlanTools ?? runParams.mode !== 'fixedThreadMode'
+    const builtTools = yield* effectFromMaybePromise(
+      () =>
+        deps.agentFactoryConfig.buildAgentTools(
+          deps.buildTurnToolParams({
+            agentId: runParams.agentId,
+            mode: runParams.mode,
+            skills: runParams.skills,
+            memoryBlock: runMemoryBlock,
+            onAppendMemoryBlock: (value: string) => {
+              runMemoryBlock = value
+            },
+            extraMessages: runParams.extraMessages,
+            includeExecutionPlanTools,
+          }),
+        ),
+      `Failed to build tools for ${runParams.agentId}.`,
+    ).pipe(Effect.withSpan('ThreadTurnExecution.buildAgentTools'))
+    const rawTools = { ...builtTools, ...runParams.extraTools }
+    const tools = runParams.filterTools ? runParams.filterTools(rawTools) : rawTools
+    deps.streamCtx.memoryBlock = runMemoryBlock
+    yield* failIfRunAborted()
+    const responseMessage = yield* effectTryPromise(
+      () =>
+        streamAgentResponse(deps.streamCtx, {
+          agentId: runParams.agentId,
+          mode: runParams.mode,
+          messages: deps.threadTurnMessageContext.buildRunInputMessages(runParams.extraMessages),
+          tools,
+          observer: createObserver(runParams.agentId),
+          skills: runParams.skills,
+          additionalInstructionSections: runParams.additionalInstructionSections,
+          includeExecutionPlanTools,
+          writer: deps.writer,
+        }),
+      `Failed to stream response for ${runParams.agentId}.`,
+    ).pipe(Effect.withSpan('ThreadTurnExecution.streamVisibleAgent'))
+    deps.setMemoryBlock(runMemoryBlock)
+
+    return yield* effectTryPromise(
+      () =>
+        commitAssistantResponse(
+          responseMessage,
+          runParams.agentId,
+          resolveRuntimeAgentDisplayName(deps.agentIdentityOverrides, runParams.agentId),
+          runParams.metadataPatch,
+        ),
+      `Failed to commit assistant response for ${runParams.agentId}.`,
+    ).pipe(Effect.withSpan('ThreadTurnExecution.commitAssistantResponse'))
+  })
+
+  const runVisibleAgent = (runParams: VisibleAgentRunParams): Promise<ChatMessage> =>
+    runPromise(
+      runVisibleAgentEffect(runParams).pipe(
+        Effect.annotateSpans(
+          compactSpanAttributes({
+            ...buildThreadTurnSpanAttributes({
+              threadRef: deps.threadRef,
+              orgRef: deps.streamCtx.orgRef,
+              userRef: deps.streamCtx.userRef,
+              agentId: runParams.agentId,
+              threadType: deps.streamCtx.thread.type,
+              mode: runParams.mode,
+            }),
+            includeExecutionPlanTools: runParams.includeExecutionPlanTools ?? runParams.mode !== 'fixedThreadMode',
+            extraMessageCount: runParams.extraMessages?.length ?? 0,
+            extraToolCount: runParams.extraTools ? Object.keys(runParams.extraTools).length : 0,
+          }),
+        ),
+      ),
+    )
+
+  return { runVisibleAgent }
+}

package/src/services/thread/thread-turn-message-context.ts

@@ -0,0 +1,73 @@
+import type { ChatMessage } from '@lota-sdk/shared'
+
+import type { RecordIdRef } from '../../db/record-id'
+import {
+  buildReadableUploadMetadataText,
+  buildModelInputMessagesWithUploadMetadata,
+} from '../../runtime/chat-attachments'
+import type { ReadableUploadMetadataLike } from '../../runtime/chat-types'
+import type { ContextCompactionRuntime } from '../../runtime/context-compaction/context-compaction'
+
+export 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 ThreadTurnMessageContext {
+  readonly currentMessages: ChatMessage[]
+  appendMessages(messages: ChatMessage[]): void
+  listReadableUploads(extraMessages?: ChatMessage[]): ReadableUploadMetadataLike[]
+  buildRunInputMessages(extraMessages?: ChatMessage[]): ChatMessage[]
+}
+
+export function createThreadTurnMessageContext(params: {
+  contextCompactionRuntime: Pick<ContextCompactionRuntime, 'prependSummaryMessage'>
+  persistedCompactionSummary: string
+  messagesForContext: ChatMessage[]
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+  latestUserMessageId: string
+  listReadableUploadsFromMessages: (params: {
+    messages: ChatMessage[]
+    orgId: RecordIdRef
+    userId: RecordIdRef
+  }) => ReadableUploadMetadataLike[]
+}): ThreadTurnMessageContext {
+  let currentMessages = params.contextCompactionRuntime.prependSummaryMessage(
+    params.persistedCompactionSummary,
+    params.messagesForContext,
+  )
+
+  const listReadableUploads = (extraMessages: ChatMessage[] = []) =>
+    params.listReadableUploadsFromMessages({
+      messages: [...currentMessages, ...extraMessages],
+      orgId: params.orgRef,
+      userId: params.userRef,
+    })
+
+  const buildRunInputMessages = (extraMessages: ChatMessage[] = []): ChatMessage[] =>
+    buildModelInputMessagesWithUploadMetadata({
+      messages: [...currentMessages, ...extraMessages],
+      latestUserMessageId: params.latestUserMessageId,
+      uploadMetadataText: buildReadableUploadMetadataText(listReadableUploads(extraMessages)),
+    })
+
+  return {
+    get currentMessages() {
+      return currentMessages
+    },
+    appendMessages(messages: ChatMessage[]) {
+      for (const message of messages) {
+        currentMessages = upsertChatHistoryMessage(currentMessages, message)
+      }
+    },
+    listReadableUploads,
+    buildRunInputMessages,
+  }
+}