@lota-sdk/core 0.4.8 → 0.4.10

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

@@ -0,0 +1,379 @@
+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 type { ZodTypeAny } 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 parseRowOrFail<TSchema extends ZodTypeAny>(
+  schema: TSchema,
+  value: unknown,
+  operation: string,
+): Effect.Effect<z.infer<TSchema>, ServiceError> {
+  return Effect.try({
+    try: () => schema.parse(value) as z.infer<TSchema>,
+    catch: (cause) => new ServiceError({ message: `Failed to parse row for ${operation}.`, cause }),
+  })
+}
+
+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.flatMap((rows) =>
+          Effect.forEach(rows, (row) => parseRowOrFail(ThreadMessageRowSchema, row, 'listMessages')),
+        ),
+        Effect.map((rows) => rows.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.',
+        )
+        const parsedRows = yield* Effect.forEach(rows, (row) =>
+          parseRowOrFail(ThreadMessageRowSchema, row, 'listMessagesAfterCursor'),
+        )
+        return parsedRows.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.flatMap((rows) =>
+          Effect.forEach(rows, (row) => parseRowOrFail(ThreadMessageRowSchema, row, 'listRecentMessages')),
+        ),
+        Effect.map((rows) => rows.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>
+>()('@lota-sdk/core/ThreadMessageService') {}
+
+export const ThreadMessageServiceLive = Layer.effect(
+  ThreadMessageServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    return makeThreadMessageService(db)
+  }),
+)

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>
+>()('@lota-sdk/core/ThreadTitleService') {}
+
+export const ThreadTitleServiceLive = Layer.effect(
+  ThreadTitleServiceTag,
+  Effect.gen(function* () {
+    const threadService = yield* ThreadServiceTag
+    const helperModelRuntime = yield* HelperModelTag
+    return makeThreadTitleService(threadService, helperModelRuntime)
+  }),
+)