@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/thread/thread-listing.ts

@@ -0,0 +1,198 @@
+import { THREAD } from '@lota-sdk/shared'
+import { Schema, Effect } from 'effect'
+import { BoundQuery } from 'surrealdb'
+
+import type { RecordIdRef } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { makeEffectTryPromiseWithMessage } from '../../effect/helpers'
+import { ThreadSchema } from './thread.types'
+import type { NormalizedThread, ThreadRecord } from './thread.types'
+
+function buildListThreadsQuery(options: {
+  includeArchived: boolean
+  paginate: boolean
+  type?: string
+  types?: string[]
+}): string {
+  const clauses = [`SELECT * FROM ${TABLES.THREAD}`, 'WHERE userId = $userId', '  AND organizationId = $orgId']
+
+  if (options.types) {
+    clauses.push('  AND type IN $types')
+  } else if (options.type) {
+    clauses.push('  AND type = $type')
+  }
+
+  if (!options.includeArchived) {
+    clauses.push('  AND status = "active"')
+  }
+  clauses.push('ORDER BY updatedAt DESC')
+  if (options.paginate) {
+    clauses.push('LIMIT $limit START $offset')
+  }
+  return clauses.join('\n')
+}
+
+export function createThreadListingHelpers(deps: {
+  db: SurrealDBService
+  normalizeThreads(
+    threads: ThreadRecord[],
+    options?: { checkLease?: boolean },
+  ): Effect.Effect<NormalizedThread[], unknown>
+}) {
+  class ThreadListingError extends Schema.TaggedErrorClass<ThreadListingError>()('ThreadListingError', {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  }) {}
+
+  const effectTryPromise = makeEffectTryPromiseWithMessage(
+    (message, cause) => new ThreadListingError({ message, cause }),
+  )
+
+  function listThreads(
+    userId: RecordIdRef,
+    orgId: RecordIdRef,
+    options: { type?: string; types?: string[]; take?: number; page?: number; includeArchived?: boolean },
+  ): Effect.Effect<{ threads: NormalizedThread[]; hasMore: boolean }, ThreadListingError> {
+    const includeArchived = options.includeArchived ?? false
+    const type = options.type
+    const types = options.types
+
+    if (type === 'default' || type === 'thread') {
+      const vars: Record<string, unknown> = { userId, orgId, type }
+      return Effect.gen(function* () {
+        const threads = yield* effectTryPromise(
+          () =>
+            deps.db.queryMany(
+              new BoundQuery(buildListThreadsQuery({ includeArchived, paginate: false, type }), vars),
+              ThreadSchema,
+            ),
+          'Failed to list threads.',
+        )
+        const normalizedThreads = yield* effectTryPromise(
+          () => deps.normalizeThreads(threads, { checkLease: false }),
+          'Failed to normalize listed threads.',
+        )
+        return { threads: normalizedThreads, hasMore: false }
+      })
+    }
+
+    const take = options.take ?? THREAD.DEFAULT_PAGE_LIMIT
+    const page = options.page ?? 1
+    const vars: Record<string, unknown> = { userId, orgId, limit: take + 1, offset: (page - 1) * take }
+
+    if (types) {
+      vars.types = types
+    } else if (type) {
+      vars.type = type
+    }
+
+    return Effect.gen(function* () {
+      const threads = yield* effectTryPromise(
+        () =>
+          deps.db.queryMany(
+            new BoundQuery(buildListThreadsQuery({ includeArchived, paginate: true, type, types }), vars),
+            ThreadSchema,
+          ),
+        'Failed to list paginated threads.',
+      )
+      const hasMore = threads.length > take
+      const sliced = hasMore ? threads.slice(0, take) : threads
+      const normalizedThreads = yield* effectTryPromise(
+        () => deps.normalizeThreads(sliced, { checkLease: false }),
+        'Failed to normalize paginated threads.',
+      )
+      return { threads: normalizedThreads, hasMore }
+    })
+  }
+
+  function listOrganizationThreads(params: {
+    orgId: RecordIdRef
+    type?: string
+    agentId?: string
+    includeArchived?: boolean
+  }): Effect.Effect<NormalizedThread[], ThreadListingError> {
+    const whereClauses = ['organizationId = $orgId']
+    const variables: Record<string, unknown> = { orgId: params.orgId }
+
+    if (params.type) {
+      whereClauses.push('type = $type')
+      variables.type = params.type
+    }
+
+    if (params.agentId) {
+      whereClauses.push('agentId = $agentId')
+      variables.agentId = params.agentId
+    }
+
+    if (params.includeArchived !== true) {
+      whereClauses.push('status = "active"')
+    }
+
+    return Effect.gen(function* () {
+      const threads = yield* effectTryPromise(
+        () =>
+          deps.db.queryMany(
+            new BoundQuery(
+              `SELECT * FROM ${TABLES.THREAD}
+         WHERE ${whereClauses.join('\n           AND ')}
+         ORDER BY createdAt ASC, id ASC`,
+              variables,
+            ),
+            ThreadSchema,
+          ),
+        'Failed to list organization threads.',
+      )
+      return yield* effectTryPromise(
+        () => deps.normalizeThreads(threads, { checkLease: false }),
+        'Failed to normalize organization threads.',
+      )
+    })
+  }
+
+  function listRecentThreads({
+    userId,
+    orgId,
+    excludeThreadId,
+    limit,
+  }: {
+    userId: RecordIdRef
+    orgId: RecordIdRef
+    excludeThreadId?: RecordIdRef
+    limit: number
+  }): Effect.Effect<NormalizedThread[], ThreadListingError> {
+    let excludeCondition = ''
+    const vars: Record<string, unknown> = { userId, orgId, limit }
+
+    if (excludeThreadId) {
+      excludeCondition = 'AND id != $excludeThreadId'
+      vars.excludeThreadId = excludeThreadId
+    }
+
+    return Effect.gen(function* () {
+      const threads = yield* effectTryPromise(
+        () =>
+          deps.db.queryMany(
+            new BoundQuery(
+              `SELECT * FROM ${TABLES.THREAD}
+	       WHERE userId = $userId
+	         AND organizationId = $orgId
+	         ${excludeCondition}
+	         AND status != "archived"
+	       ORDER BY updatedAt DESC
+	       LIMIT $limit`,
+              vars,
+            ),
+            ThreadSchema,
+          ),
+        'Failed to list recent threads.',
+      )
+      return yield* effectTryPromise(
+        () => deps.normalizeThreads(threads, { checkLease: false }),
+        'Failed to normalize recent threads.',
+      )
+    })
+  }
+
+  return { listThreads, listOrganizationThreads, listRecentThreads }
+}

package/src/services/thread/thread-memory-block.ts

@@ -0,0 +1,117 @@
+import { Schema, Effect } from 'effect'
+
+import { serverLogger } from '../../config/logger'
+import type { RecordIdRef } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import { TABLES } from '../../db/tables'
+import { makeEffectTryPromiseWithMessage } from '../../effect/helpers'
+import {
+  appendToMemoryBlock,
+  compactMemoryBlockEntries,
+  formatPersistedMemoryBlockForPrompt,
+  parseMemoryBlock,
+  serializeMemoryBlock,
+} from '../../runtime/memory/memory-block'
+import { MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES, MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES } from './thread-constants'
+import type { ThreadRecordStore } from './thread-record-store'
+import type { ThreadRecord } from './thread.types'
+
+type ContextCompactionServiceLike = {
+  compactMemoryBlock(params: { previousSummary: string; newEntriesText: string }): Effect.Effect<string, unknown>
+}
+
+class ThreadMemoryBlockError extends Schema.TaggedErrorClass<ThreadMemoryBlockError>()('ThreadMemoryBlockError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+const tryThreadMemoryBlockEffect = makeEffectTryPromiseWithMessage(
+  (message, cause) => new ThreadMemoryBlockError({ message, cause }),
+)
+
+export function formatMemoryBlockForPrompt(thread: Pick<ThreadRecord, 'memoryBlock' | 'memoryBlockSummary'>): string {
+  return formatPersistedMemoryBlockForPrompt({
+    summary: thread.memoryBlockSummary,
+    entries: parseMemoryBlock(thread.memoryBlock),
+  })
+}
+
+export function createThreadMemoryBlockHelpers(deps: {
+  threadStore: ThreadRecordStore
+  contextCompactionService: ContextCompactionServiceLike
+}) {
+  function appendMemoryBlock(threadId: RecordIdRef, entry: string): Effect.Effect<string, ThreadMemoryBlockError> {
+    return Effect.gen(function* () {
+      const threadRef = ensureRecordId(threadId, TABLES.THREAD)
+      const threadIdString = recordIdToString(threadRef, TABLES.THREAD)
+      const thread = yield* tryThreadMemoryBlockEffect(
+        () => deps.threadStore.getById(threadRef),
+        `Failed to load thread ${threadIdString} for memory block append`,
+      )
+      const entries = parseMemoryBlock(thread.memoryBlock)
+
+      const labelMatch = entry.match(/^(\w+):\s*/i)
+      const role = labelMatch ? labelMatch[1].toLowerCase() : 'system'
+      const content = labelMatch ? entry.slice(labelMatch[0].length).trim() : entry.trim()
+
+      const updatedEntries = appendToMemoryBlock(entries, role, content)
+      const serialized = serializeMemoryBlock(updatedEntries)
+
+      yield* tryThreadMemoryBlockEffect(
+        () => deps.threadStore.update(threadRef, { memoryBlock: serialized }),
+        `Failed to persist memory block for thread ${threadIdString}`,
+      )
+
+      if (updatedEntries.length >= MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES) {
+        yield* Effect.forkDetach(
+          compactMemoryBlock(threadRef).pipe(
+            Effect.catch((error: unknown) =>
+              Effect.sync(() => {
+                serverLogger.warn`Memory block compaction failed for ${threadIdString}: ${error}`
+              }),
+            ),
+          ),
+        )
+      }
+
+      return formatMemoryBlockForPrompt({ memoryBlock: serialized, memoryBlockSummary: thread.memoryBlockSummary })
+    })
+  }
+
+  function compactMemoryBlock(threadId: RecordIdRef): Effect.Effect<boolean, ThreadMemoryBlockError> {
+    return Effect.gen(function* () {
+      const threadRef = ensureRecordId(threadId, TABLES.THREAD)
+      const threadIdString = recordIdToString(threadRef, TABLES.THREAD)
+      const thread = yield* tryThreadMemoryBlockEffect(
+        () => deps.threadStore.getById(threadRef),
+        `Failed to load thread ${threadIdString} for memory block compaction`,
+      )
+      const result = yield* tryThreadMemoryBlockEffect(
+        () =>
+          compactMemoryBlockEntries({
+            previousSummary: thread.memoryBlockSummary,
+            entries: parseMemoryBlock(thread.memoryBlock),
+            triggerEntries: MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES,
+            chunkEntries: MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES,
+            compact: (params) => deps.contextCompactionService.compactMemoryBlock(params),
+          }),
+        `Failed to compact memory block for thread ${threadIdString}`,
+      )
+
+      if (!result.compacted) return false
+
+      yield* tryThreadMemoryBlockEffect(
+        () =>
+          deps.threadStore.update(threadRef, {
+            memoryBlockSummary: result.summary || '',
+            memoryBlock: serializeMemoryBlock(result.entries),
+          }),
+        `Failed to persist compacted memory block for thread ${threadIdString}`,
+      )
+
+      return true
+    })
+  }
+
+  return { appendMemoryBlock, compactMemoryBlock }
+}

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

@@ -0,0 +1,363 @@
+import { parseRowMetadata, recordIdSchema, requireTimestamp, withCreatedAtMetadata } from '@lota-sdk/shared'
+import type { ChatMessage } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
+import { RecordId, surql } from 'surrealdb'
+import { z } from 'zod'
+
+import { getAgentDisplayNames } from '../../config/agent-defaults'
+import { CursorRowSchema, listMessageHistoryPageEffect } from '../../db/cursor-pagination'
+import type { CursorPaginationConfig } from '../../db/cursor-pagination'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { RecordIdRef } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { ThreadMessageRowSchema } from '../../db/thread-message-row'
+import type { ThreadMessageRow } from '../../db/thread-message-row'
+import { ServiceError } from '../../effect/errors'
+import { effectTryServicePromise } from '../../effect/helpers'
+import { DatabaseServiceTag } from '../../effect/services'
+import { sha256Hex } from '../../utils/crypto'
+import { nowEpochMillis, unsafeDateFrom } from '../../utils/date-time'
+
+const ThreadMessageExistingRowSchema = z.object({ id: recordIdSchema, createdAt: z.coerce.date() })
+
+function toMessageId(value: string | RecordIdRef): string {
+  return recordIdToString(value, TABLES.THREAD_MESSAGE)
+}
+
+function toThreadMessageRowId(threadId: RecordIdRef, messageId: string): RecordId {
+  const threadStr = recordIdToString(threadId, TABLES.THREAD)
+  const digest = sha256Hex(`${threadStr}\0${messageId}`).slice(0, 32)
+  return new RecordId(TABLES.THREAD_MESSAGE, digest)
+}
+
+function toThreadRef(threadId: RecordIdRef): RecordId {
+  return ensureRecordId(threadId, TABLES.THREAD)
+}
+
+function normalizeMessageValue(value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeMessageValue(item))
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, entry]) => [key, normalizeMessageValue(entry)]),
+    )
+  }
+
+  return value
+}
+
+function readPersistedMessageParts(parts: ThreadMessageRow['parts']): ChatMessage['parts'] {
+  return (Array.isArray(parts) ? normalizeMessageValue(parts) : []) as ChatMessage['parts']
+}
+
+function toChatMessage(row: ThreadMessageRow): ChatMessage {
+  const rowCreatedAt = requireTimestamp(row.createdAt)
+  const metadata = withCreatedAtMetadata(parseRowMetadata(row.metadata), rowCreatedAt)
+
+  return { id: row.messageId, role: row.role, parts: readPersistedMessageParts(row.parts), metadata }
+}
+
+function cloneMessageParts(parts: ChatMessage['parts'] | undefined): NonNullable<ThreadMessageRow['parts']> {
+  return Array.isArray(parts)
+    ? (normalizeMessageValue(structuredClone(parts)) as NonNullable<ThreadMessageRow['parts']>)
+    : []
+}
+
+const threadPaginationConfig: CursorPaginationConfig = {
+  table: TABLES.THREAD_MESSAGE,
+  parentFilterField: 'threadId',
+  toRowId: toThreadMessageRowId,
+  parseRow: (row: unknown) => ThreadMessageRowSchema.parse(row),
+  toMessage: (row: unknown) => toChatMessage(ThreadMessageRowSchema.parse(row)),
+  queryLatest: (parentId, limit) => surql`
+    SELECT * FROM threadMessage
+    WHERE threadId = ${parentId}
+    ORDER BY createdAt DESC, id DESC
+    LIMIT ${limit}
+  `,
+  queryBefore: (parentId, cursorCreatedAt, cursorId, limit) => surql`
+    SELECT * FROM threadMessage
+    WHERE threadId = ${parentId}
+      AND (
+        createdAt < ${cursorCreatedAt}
+        OR (createdAt = ${cursorCreatedAt} AND id < ${cursorId})
+      )
+    ORDER BY createdAt DESC, id DESC
+    LIMIT ${limit}
+  `,
+}
+
+export function makeThreadMessageService(db: SurrealDBService) {
+  function upsertMessages(params: { threadId: RecordIdRef; messages: ChatMessage[] }) {
+    const threadId = toThreadRef(params.threadId)
+    return Effect.forEach(params.messages, (message) =>
+      Effect.gen(function* () {
+        const messageId = message.id.trim()
+        if (!messageId) {
+          return
+        }
+
+        const role = message.role
+        const parts = cloneMessageParts(message.parts)
+        if (parts.length === 0) {
+          if (role === 'assistant') {
+            return
+          }
+          return yield* new ServiceError({
+            message: `Refusing to persist thread message "${messageId}" with empty parts`,
+          })
+        }
+
+        const rowId = toThreadMessageRowId(threadId, messageId)
+        const existingRow = yield* effectTryServicePromise(
+          () => db.findOne(TABLES.THREAD_MESSAGE, { threadId, messageId }, ThreadMessageExistingRowSchema),
+          `Failed to load existing thread message "${messageId}".`,
+        )
+        const persistedCreatedAt =
+          existingRow === null ? requireTimestamp(message.metadata?.createdAt) : requireTimestamp(existingRow.createdAt)
+        const metadata = withCreatedAtMetadata({ ...message.metadata, createdAt: persistedCreatedAt })
+
+        yield* effectTryServicePromise(
+          () =>
+            db.upsert(
+              TABLES.THREAD_MESSAGE,
+              rowId,
+              {
+                threadId,
+                messageId,
+                role,
+                parts,
+                metadata,
+                createdAt: existingRow ? existingRow.createdAt : unsafeDateFrom(persistedCreatedAt),
+              },
+              ThreadMessageRowSchema,
+              { mutation: 'content' },
+            ),
+          `Failed to upsert thread message "${messageId}".`,
+        )
+      }),
+    ).pipe(Effect.asVoid)
+  }
+
+  const service = {
+    upsertMessages,
+    upsertMessagesEffect: upsertMessages,
+    listMessages(threadId: RecordIdRef) {
+      const threadRef = toThreadRef(threadId)
+      return effectTryServicePromise(
+        () =>
+          db.query<unknown>(surql`
+        SELECT * FROM threadMessage
+        WHERE threadId = ${threadRef}
+        ORDER BY createdAt ASC, id ASC
+      `),
+        'Failed to list thread messages.',
+      ).pipe(
+        Effect.map((rows) => rows.map((row) => ThreadMessageRowSchema.parse(row)).map((row) => toChatMessage(row))),
+      )
+    },
+    listMessagesEffect(threadId: RecordIdRef) {
+      return service.listMessages(threadId)
+    },
+
+    listMessageHistoryPage(params: { threadId: RecordIdRef; take: number; beforeMessageId?: string }) {
+      const threadRef = toThreadRef(params.threadId)
+      return listMessageHistoryPageEffect(db, threadPaginationConfig, {
+        parentId: threadRef,
+        take: params.take,
+        beforeMessageId: params.beforeMessageId,
+      })
+    },
+    listMessageHistoryPageEffect(params: { threadId: RecordIdRef; take: number; beforeMessageId?: string }) {
+      return service.listMessageHistoryPage(params)
+    },
+
+    listMessagesAfterCursor(threadId: RecordIdRef, afterMessageId?: string) {
+      const threadRef = toThreadRef(threadId)
+      const cursorMessageId = afterMessageId?.trim()
+      if (!cursorMessageId) {
+        return service.listMessages(threadRef)
+      }
+
+      return Effect.gen(function* () {
+        const cursorRow = yield* effectTryServicePromise(
+          () => db.findOne(TABLES.THREAD_MESSAGE, { threadId: threadRef, messageId: cursorMessageId }, CursorRowSchema),
+          `Failed to load cursor message "${cursorMessageId}".`,
+        )
+        if (!cursorRow) {
+          return yield* new ServiceError({ message: `Thread cursor message not found: ${cursorMessageId}` })
+        }
+
+        const cursorCreatedAt = cursorRow.createdAt
+        const cursorId = toThreadMessageRowId(threadRef, cursorMessageId)
+        const rows = yield* effectTryServicePromise(
+          () =>
+            db.query<unknown>(surql`
+            SELECT * FROM threadMessage
+            WHERE threadId = ${threadRef}
+              AND (
+                createdAt > ${cursorCreatedAt}
+                OR (createdAt = ${cursorCreatedAt} AND id > ${cursorId})
+              )
+            ORDER BY createdAt ASC, id ASC
+          `),
+          'Failed to list thread messages after cursor.',
+        )
+        return rows.map((row) => ThreadMessageRowSchema.parse(row)).map((row) => toChatMessage(row))
+      })
+    },
+    listMessagesAfterCursorEffect(threadId: RecordIdRef, afterMessageId?: string) {
+      return service.listMessagesAfterCursor(threadId, afterMessageId)
+    },
+
+    listRecentMessages(threadId: RecordIdRef, limit: number) {
+      const threadRef = toThreadRef(threadId)
+      return effectTryServicePromise(
+        () =>
+          db.query<unknown>(surql`
+        SELECT * FROM threadMessage
+        WHERE threadId = ${threadRef}
+        ORDER BY createdAt DESC, id DESC
+        LIMIT ${Math.max(1, limit)}
+      `),
+        'Failed to list recent thread messages.',
+      ).pipe(
+        Effect.map((rows) =>
+          rows
+            .map((row) => ThreadMessageRowSchema.parse(row))
+            .reverse()
+            .map((row) => toChatMessage(row)),
+        ),
+      )
+    },
+    listRecentMessagesEffect(threadId: RecordIdRef, limit: number) {
+      return service.listRecentMessages(threadId, limit)
+    },
+
+    searchMessages(params: { threadId: RecordIdRef; role: 'user' | 'assistant'; query: string; limit: number }) {
+      const normalizedQuery = params.query.trim().toLowerCase()
+      if (!normalizedQuery) return Effect.succeed([])
+
+      return Effect.gen(function* () {
+        const messages = yield* service.listMessages(toThreadRef(params.threadId))
+        return messages
+          .filter((message) => message.role === params.role)
+          .map((message) => ({
+            id: message.id,
+            role: message.role as 'user' | 'assistant',
+            createdAt: unsafeDateFrom(requireTimestamp(message.metadata?.createdAt)).toISOString(),
+            content: message.parts
+              .flatMap((part) => (part.type === 'text' && typeof part.text === 'string' ? [part.text] : []))
+              .join('\n')
+              .trim(),
+          }))
+          .filter((item) => item.content.length > 0 && item.content.toLowerCase().includes(normalizedQuery))
+          .slice(-Math.max(1, params.limit))
+      })
+    },
+    searchMessagesEffect(params: { threadId: RecordIdRef; role: 'user' | 'assistant'; query: string; limit: number }) {
+      return service.searchMessages(params)
+    },
+
+    addUserMessage(params: { messageId: RecordIdRef; threadId: RecordIdRef; content: string }) {
+      const threadRef = toThreadRef(params.threadId)
+      const message: ChatMessage = {
+        id: toMessageId(params.messageId),
+        role: 'user',
+        parts: [{ type: 'text', text: params.content }],
+        metadata: { createdAt: nowEpochMillis() },
+      }
+
+      return Effect.gen(function* () {
+        yield* upsertMessages({ threadId: threadRef, messages: [message] })
+        return message
+      })
+    },
+    addUserMessageEffect(params: { messageId: RecordIdRef; threadId: RecordIdRef; content: string }) {
+      return service.addUserMessage(params)
+    },
+
+    addAgentMessage(params: {
+      messageId: RecordIdRef
+      threadId: RecordIdRef
+      parts: ChatMessage['parts']
+      metadata?: ChatMessage['metadata']
+    }) {
+      const threadRef = toThreadRef(params.threadId)
+      const message: ChatMessage = {
+        id: toMessageId(params.messageId),
+        role: 'assistant',
+        parts: params.parts,
+        metadata: withCreatedAtMetadata(params.metadata, nowEpochMillis()),
+      }
+
+      return Effect.gen(function* () {
+        yield* upsertMessages({ threadId: threadRef, messages: [message] })
+        return message
+      })
+    },
+    addAgentMessageEffect(params: {
+      messageId: RecordIdRef
+      threadId: RecordIdRef
+      parts: ChatMessage['parts']
+      metadata?: ChatMessage['metadata']
+    }) {
+      return service.addAgentMessage(params)
+    },
+
+    ensureBootstrapWelcomeMessage(params: { threadId: RecordIdRef; agentId: string; text: string }) {
+      const threadRef = toThreadRef(params.threadId)
+      return Effect.gen(function* () {
+        const existingRow = yield* effectTryServicePromise(
+          () => db.findOne(TABLES.THREAD_MESSAGE, { threadId: threadRef }, ThreadMessageExistingRowSchema),
+          'Failed to check for existing bootstrap welcome message.',
+        )
+        if (existingRow) return
+
+        const messageText = params.text.trim()
+        if (!messageText) return
+
+        yield* upsertMessages({
+          threadId: threadRef,
+          messages: [
+            {
+              id: Bun.randomUUIDv7(),
+              role: 'assistant',
+              parts: [{ type: 'text', text: messageText }],
+              metadata: {
+                agentId: params.agentId,
+                agentName: getAgentDisplayNames()[params.agentId] ?? params.agentId,
+                createdAt: nowEpochMillis(),
+              },
+            },
+          ],
+        })
+      })
+    },
+    ensureBootstrapWelcomeMessageEffect(params: { threadId: RecordIdRef; agentId: string; text: string }) {
+      return service.ensureBootstrapWelcomeMessage(params)
+    },
+  }
+
+  return service
+}
+
+export class ThreadMessageServiceTag extends Context.Service<
+  ThreadMessageServiceTag,
+  ReturnType<typeof makeThreadMessageService>
+>()('ThreadMessageService') {}
+
+export const ThreadMessageServiceLive = Layer.effect(
+  ThreadMessageServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    return makeThreadMessageService(db)
+  }),
+)