@lota-sdk/core 0.1.5

package/src/services/workstream-change-tracker.service.ts

@@ -0,0 +1,313 @@
+import { z } from 'zod'
+
+import { aiLogger } from '../config/logger'
+import type { RecordIdRef } from '../db/record-id'
+import { mergeStateDelta } from '../runtime/context-compaction'
+import { createHelperModelRuntime, extractJsonObjectCandidates } from '../runtime/helper-model'
+import { toOptionalTrimmedString } from '../runtime/workstream-chat-helpers'
+import {
+  StructuredWorkstreamStateDeltaSchema,
+  createEmptyStructuredWorkstreamStateDelta,
+  createEmptyWorkstreamState,
+  parseStructuredWorkstreamStateDelta,
+} from '../runtime/workstream-state'
+import type { WorkstreamState, WorkstreamStateDelta } from '../runtime/workstream-state'
+import { createWorkstreamTrackerAgent } from '../system-agents/workstream-tracker.agent'
+import { compactWhitespace, isRecord, truncateText } from '../utils/string'
+import { workstreamService } from './workstream.service'
+
+const helperModelRuntime = createHelperModelRuntime()
+
+const TrackerOutputSchema = z.object({
+  summary: z.string().trim().min(1).max(1_200),
+  stateDelta: StructuredWorkstreamStateDeltaSchema,
+})
+
+type TrackerMessage = { label: string; text: string }
+
+const TRACKER_JSON_WRAPPER_KEYS = ['output', 'result', 'data'] as const
+const TRACKER_SUMMARY_KEYS = ['summary', 'chatSummary', 'summaryText', 'sidebarSummary', 'message'] as const
+const TRACKER_STATE_DELTA_KEYS = ['stateDelta', 'delta', 'workstreamStateDelta', 'trackerStateDelta', 'state'] as const
+const TRACKER_FALLBACK_SECTION_PREFIX =
+  /^(?:#{1,6}\s*)?(?:\*\*)?(?:state delta|current plan|new decisions|resolved questions|new questions|new constraints|new risks|task updates|artifacts|agent note|conflicts|approved by|approved at|approval message id|approval note)(?:\*\*)?\s*:?\s*/i
+
+function renderMessages(messages: TrackerMessage[]): string {
+  if (messages.length === 0) return '- None'
+  return messages
+    .map((message, index) => `### Message ${index + 1}\n- Actor: ${message.label}\n- Content: ${message.text}`)
+    .join('\n\n')
+}
+
+function getRecordStringField(record: Record<string, unknown>, keys: readonly string[]): string | null {
+  for (const key of keys) {
+    const field = toOptionalTrimmedString(typeof record[key] === 'string' ? record[key] : null)
+    if (field) return field
+  }
+
+  return null
+}
+
+function getTrackerJsonObjects(value: unknown): Record<string, unknown>[] {
+  if (!isRecord(value)) return []
+
+  const candidates: Record<string, unknown>[] = [value]
+  for (const key of TRACKER_JSON_WRAPPER_KEYS) {
+    const nested = value[key]
+    if (isRecord(nested)) {
+      candidates.push(nested)
+    }
+  }
+
+  return candidates
+}
+
+function parseTrackerJsonFallback(text: string): z.infer<typeof TrackerOutputSchema> | null {
+  for (const candidateText of extractJsonObjectCandidates(text)) {
+    let parsedJson: unknown
+
+    try {
+      parsedJson = JSON.parse(candidateText) as unknown
+    } catch {
+      continue
+    }
+
+    for (const candidate of getTrackerJsonObjects(parsedJson)) {
+      const summary = getRecordStringField(candidate, TRACKER_SUMMARY_KEYS)
+      if (!summary) continue
+
+      const stateDeltaValue = TRACKER_STATE_DELTA_KEYS.map((key) => candidate[key]).find((value) => value !== undefined)
+      const parsedStateDelta = StructuredWorkstreamStateDeltaSchema.safeParse(stateDeltaValue)
+
+      return {
+        summary: truncateText(summary, 1_200),
+        stateDelta: parsedStateDelta.success ? parsedStateDelta.data : createEmptyStructuredWorkstreamStateDelta(),
+      }
+    }
+  }
+
+  return null
+}
+
+function extractTrackerFallbackSummary(text: string): string | null {
+  const normalized = text.replace(/\r/g, '').trim()
+  if (!normalized) return null
+
+  const summaryLineMatch = normalized.match(/(?:^|\n)(?:#{1,6}\s*)?(?:\*\*)?summary(?:\*\*)?\s*:?\s*(.+?)(?=\n|$)/i)
+  const summaryLine = summaryLineMatch?.[1]?.trim()
+  if (summaryLine && !summaryLine.startsWith('{') && !summaryLine.startsWith('```')) {
+    return truncateText(summaryLine, 1_200)
+  }
+
+  const summarySectionMatch = normalized.match(
+    /(?:^|\n)(?:#{1,6}\s*)?(?:\*\*)?summary(?:\*\*)?\s*:?\s*\n([\s\S]*?)(?=\n(?:#{1,6}\s*)?(?:\*\*)?(?:state delta|summary)(?:\*\*)?\s*:?\s*\n|$)/i,
+  )
+  const summarySource = summarySectionMatch?.[1]?.trim() || normalized
+  const paragraphs = summarySource
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.trim())
+    .filter((paragraph) => paragraph.length > 0)
+
+  for (const paragraph of paragraphs) {
+    const candidate = paragraph.replace(/^(?:#{1,6}\s*)?(?:\*\*)?summary(?:\*\*)?\s*:?\s*/i, '').trim()
+    if (
+      !candidate ||
+      candidate.startsWith('{') ||
+      candidate.startsWith('```') ||
+      TRACKER_FALLBACK_SECTION_PREFIX.test(candidate)
+    ) {
+      continue
+    }
+
+    return truncateText(candidate, 1_200)
+  }
+
+  return null
+}
+
+export function parseTrackerTextFallback(text: string): z.infer<typeof TrackerOutputSchema> | null {
+  const jsonFallback = parseTrackerJsonFallback(text)
+  if (jsonFallback) {
+    return jsonFallback
+  }
+
+  const summary = extractTrackerFallbackSummary(text)
+  if (!summary) return null
+
+  return { summary, stateDelta: createEmptyStructuredWorkstreamStateDelta() }
+}
+
+function extractHeuristicSummaryCandidate(text: string | null | undefined): string | null {
+  const normalized = compactWhitespace(toOptionalTrimmedString(text) ?? '')
+  if (!normalized) return null
+
+  const match = /^(.+?[.!?])(?:\s|$)/.exec(normalized)
+  const candidate = match ? String(match[1]) : normalized
+  return truncateText(candidate, 1_200)
+}
+
+export function buildHeuristicTrackerSummary(params: {
+  previousSummary: string | null
+  userMessageText: string | null
+  assistantMessages: TrackerMessage[]
+}): string | null {
+  for (const message of params.assistantMessages) {
+    const summary = extractHeuristicSummaryCandidate(message.text)
+    if (summary) {
+      return summary
+    }
+  }
+
+  const userSummary = extractHeuristicSummaryCandidate(params.userMessageText)
+  if (userSummary) {
+    return truncateText(`User request: ${userSummary}`, 1_200)
+  }
+
+  return extractHeuristicSummaryCandidate(params.previousSummary)
+}
+
+function formatTrackerPrompt(params: {
+  title: string
+  mode: 'direct' | 'group'
+  coreType?: string
+  visibleAgentId?: string
+  hasActiveExecutionPlan: boolean
+  previousSummary: string | null
+  existingState: WorkstreamState
+  userMessageText: string | null
+  assistantMessages: TrackerMessage[]
+}): string {
+  return [
+    '# Workstream Turn',
+    '',
+    `- Title: ${params.title}`,
+    `- Mode: ${params.mode}`,
+    `- Visible agent: ${params.visibleAgentId ?? 'none'}`,
+    `- Active execution plan: ${params.hasActiveExecutionPlan ? 'yes' : 'no'}`,
+    ...(params.coreType ? [`- Core type: ${params.coreType}`] : []),
+    '',
+    '## Previous Summary',
+    params.previousSummary ?? 'None',
+    '',
+    '## Existing State',
+    JSON.stringify(params.existingState),
+    '',
+    '## User Message',
+    params.userMessageText ?? 'None',
+    '',
+    '## Assistant Messages',
+    renderMessages(params.assistantMessages),
+    ...(params.hasActiveExecutionPlan
+      ? [
+          '',
+          '## Tracker Constraint',
+          'An active execution plan exists. Do not update currentPlan or taskUpdates. Track only decisions, questions, risks, artifacts, approvals, and agent notes.',
+        ]
+      : []),
+  ].join('\n')
+}
+
+export function applyTrackedStateDelta(params: {
+  existingState: WorkstreamState
+  delta: WorkstreamStateDelta
+  hasActiveExecutionPlan: boolean
+  now: () => number
+}): WorkstreamState {
+  const mergedState = mergeStateDelta(params.existingState, params.delta, params.now)
+  if (!params.hasActiveExecutionPlan) {
+    return mergedState
+  }
+
+  return { ...mergedState, currentPlan: null, tasks: [] }
+}
+
+export async function updateWorkstreamChangeTracker(params: {
+  workstreamId: RecordIdRef
+  title: string
+  mode: 'direct' | 'group'
+  coreType?: string
+  visibleAgentId?: string
+  hasActiveExecutionPlan: boolean
+  previousSummary: string | null
+  existingState: WorkstreamState | null
+  userMessageText: string | null
+  assistantMessages: TrackerMessage[]
+}): Promise<boolean> {
+  const assistantMessages = params.assistantMessages
+    .map((message) => ({
+      label: toOptionalTrimmedString(message.label) ?? 'Assistant',
+      text: truncateText(message.text.trim(), 2_400),
+    }))
+    .filter((message) => message.text.length > 0)
+    .slice(0, 6)
+
+  if (!toOptionalTrimmedString(params.userMessageText) && assistantMessages.length === 0) {
+    return false
+  }
+
+  const existingState = params.existingState ?? createEmptyWorkstreamState()
+
+  try {
+    const output = await helperModelRuntime.generateHelperStructured({
+      tag: 'workstream-change-tracker',
+      createAgent: createWorkstreamTrackerAgent,
+      schema: TrackerOutputSchema,
+      maxOutputTokens: 1_400,
+      textFallbackParser: parseTrackerTextFallback,
+      messages: [
+        {
+          role: 'user',
+          content: formatTrackerPrompt({
+            title: params.title,
+            mode: params.mode,
+            ...(params.coreType ? { coreType: params.coreType } : {}),
+            ...(params.visibleAgentId ? { visibleAgentId: params.visibleAgentId } : {}),
+            hasActiveExecutionPlan: params.hasActiveExecutionPlan,
+            previousSummary: params.previousSummary,
+            existingState,
+            userMessageText: toOptionalTrimmedString(params.userMessageText),
+            assistantMessages,
+          }),
+        },
+      ],
+    })
+
+    const sparseStateDelta = parseStructuredWorkstreamStateDelta(output.stateDelta)
+    const nextState = applyTrackedStateDelta({
+      existingState,
+      delta: sparseStateDelta,
+      hasActiveExecutionPlan: params.hasActiveExecutionPlan,
+      now: () => Date.now(),
+    })
+    await workstreamService.persistChangeTracker(params.workstreamId, { chatSummary: output.summary, state: nextState })
+    return true
+  } catch (error) {
+    const fallbackSummary = buildHeuristicTrackerSummary({
+      previousSummary: params.previousSummary,
+      userMessageText: toOptionalTrimmedString(params.userMessageText),
+      assistantMessages,
+    })
+
+    if (!fallbackSummary) {
+      aiLogger.warn`Workstream change tracker update failed: ${error}`
+      return false
+    }
+
+    try {
+      const nextState = applyTrackedStateDelta({
+        existingState,
+        delta: {},
+        hasActiveExecutionPlan: params.hasActiveExecutionPlan,
+        now: () => Date.now(),
+      })
+      await workstreamService.persistChangeTracker(params.workstreamId, {
+        chatSummary: fallbackSummary,
+        state: nextState,
+      })
+      aiLogger.info`Workstream change tracker used heuristic fallback after helper failure`
+      return true
+    } catch (persistError) {
+      aiLogger.warn`Workstream change tracker update failed: ${error}; fallback_persist=${persistError}`
+      return false
+    }
+  }
+}

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

@@ -0,0 +1,283 @@
+import { toTimestamp, withCreatedAtMetadata } from '@lota-sdk/shared/runtime/chat-message-metadata'
+import { parseRowMetadata } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import { RecordId, surql } from 'surrealdb'
+import { z } from 'zod'
+
+import { agentDisplayNames } from '../config/agent-defaults'
+import { CursorRowSchema, listMessageHistoryPage } from '../db/cursor-pagination'
+import type { CursorPaginationConfig, MessageHistoryPage } from '../db/cursor-pagination'
+import { recordIdToString } from '../db/record-id'
+import type { RecordIdRef } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+
+const WorkstreamMessageRowSchema = z.object({
+  id: z.unknown(),
+  workstreamId: z.unknown(),
+  messageId: z.string(),
+  role: z.enum(['system', 'user', 'assistant']),
+  parts: z.array(z.record(z.string(), z.unknown())).optional(),
+  metadata: z.record(z.string(), z.unknown()).nullish(),
+  createdAt: z.union([z.date(), z.string(), z.number()]),
+  updatedAt: z.union([z.date(), z.string(), z.number()]).optional(),
+})
+
+type WorkstreamMessageRow = z.infer<typeof WorkstreamMessageRowSchema>
+
+const WorkstreamMessageExistingRowSchema = z.object({
+  id: z.unknown(),
+  createdAt: z.union([z.date(), z.string(), z.number()]),
+})
+
+function toMessageId(value: string | RecordIdRef): string {
+  return recordIdToString(value, TABLES.WORKSTREAM_MESSAGE)
+}
+
+function toWorkstreamMessageRowId(workstreamId: RecordIdRef, messageId: string): RecordId {
+  const workstreamPart = recordIdToString(workstreamId, TABLES.WORKSTREAM).replace(/[^a-zA-Z0-9_-]/g, '_')
+  const messagePart = messageId.replace(/[^a-zA-Z0-9_-]/g, '_')
+  return new RecordId(TABLES.WORKSTREAM_MESSAGE, `${workstreamPart}__${messagePart}`)
+}
+
+function toChatMessage(row: WorkstreamMessageRow): ChatMessage {
+  const rowCreatedAt = toTimestamp(row.createdAt)
+  const metadata = withCreatedAtMetadata(parseRowMetadata(row.metadata), rowCreatedAt)
+
+  return { id: row.messageId, role: row.role, parts: (row.parts ?? []) as ChatMessage['parts'], metadata }
+}
+
+const workstreamPaginationConfig: CursorPaginationConfig = {
+  table: TABLES.WORKSTREAM_MESSAGE,
+  parentFilterField: 'workstreamId',
+  toRowId: toWorkstreamMessageRowId,
+  parseRow: (row: unknown) => WorkstreamMessageRowSchema.parse(row),
+  toMessage: (row: unknown) => toChatMessage(WorkstreamMessageRowSchema.parse(row)),
+  queryLatest: (parentId, limit) => surql`
+    SELECT * FROM workstreamMessage
+    WHERE workstreamId = ${parentId}
+    ORDER BY createdAt DESC, id DESC
+    LIMIT ${limit}
+  `,
+  queryBefore: (parentId, cursorCreatedAt, cursorId, limit) => surql`
+    SELECT * FROM workstreamMessage
+    WHERE workstreamId = ${parentId}
+      AND (
+        createdAt < ${cursorCreatedAt}
+        OR (createdAt = ${cursorCreatedAt} AND id < ${cursorId})
+      )
+    ORDER BY createdAt DESC, id DESC
+    LIMIT ${limit}
+  `,
+}
+
+class WorkstreamMessageService {
+  async upsertMessages(params: { workstreamId: RecordIdRef; messages: ChatMessage[] }): Promise<void> {
+    const workstreamId = params.workstreamId
+
+    for (const message of params.messages) {
+      const messageId = message.id.trim()
+      if (!messageId) continue
+
+      const role = message.role
+      const parts = Array.isArray(message.parts)
+        ? message.parts.map((part) => structuredClone(part) as Record<string, unknown>)
+        : []
+      if (parts.length === 0) {
+        if (role === 'assistant') continue
+        throw new Error(`Refusing to persist workstream message "${messageId}" with empty parts`)
+      }
+      const rowId = toWorkstreamMessageRowId(workstreamId, messageId)
+      const existingRow = await databaseService.findOne(
+        TABLES.WORKSTREAM_MESSAGE,
+        { workstreamId, messageId },
+        WorkstreamMessageExistingRowSchema,
+      )
+      const persistedCreatedAt =
+        existingRow === null ? toTimestamp(message.metadata?.createdAt) : toTimestamp(existingRow.createdAt)
+      const metadata = withCreatedAtMetadata({ ...message.metadata, createdAt: persistedCreatedAt })
+
+      await databaseService.upsert(
+        TABLES.WORKSTREAM_MESSAGE,
+        rowId,
+        {
+          workstreamId,
+          messageId,
+          role,
+          parts,
+          metadata,
+          createdAt: existingRow ? new Date(toTimestamp(existingRow.createdAt)) : new Date(persistedCreatedAt),
+        },
+        WorkstreamMessageRowSchema,
+        { mutation: 'content' },
+      )
+    }
+  }
+
+  async listMessages(workstreamId: RecordIdRef): Promise<ChatMessage[]> {
+    const rows = await databaseService.query<unknown>(surql`
+      SELECT * FROM workstreamMessage
+      WHERE workstreamId = ${workstreamId}
+      ORDER BY createdAt ASC, id ASC
+    `)
+
+    return rows.map((row) => WorkstreamMessageRowSchema.parse(row)).map((row) => toChatMessage(row))
+  }
+
+  async listMessageHistoryPage(params: {
+    workstreamId: RecordIdRef
+    take: number
+    beforeMessageId?: string
+  }): Promise<MessageHistoryPage> {
+    return listMessageHistoryPage(workstreamPaginationConfig, {
+      parentId: params.workstreamId,
+      take: params.take,
+      beforeMessageId: params.beforeMessageId,
+    })
+  }
+
+  async listMessagesAfterCursor(workstreamId: RecordIdRef, afterMessageId?: string): Promise<ChatMessage[]> {
+    const cursorMessageId = afterMessageId?.trim()
+    if (!cursorMessageId) {
+      return await this.listMessages(workstreamId)
+    }
+
+    const cursorRow = await databaseService.findOne(
+      TABLES.WORKSTREAM_MESSAGE,
+      { workstreamId, messageId: cursorMessageId },
+      CursorRowSchema,
+    )
+
+    if (!cursorRow) {
+      throw new Error(`Workstream cursor message not found: ${cursorMessageId}`)
+    }
+
+    const cursorCreatedAt = new Date(toTimestamp(cursorRow.createdAt))
+    const cursorId = toWorkstreamMessageRowId(workstreamId, cursorMessageId)
+    const rows = await databaseService.query<unknown>(surql`
+      SELECT * FROM workstreamMessage
+      WHERE workstreamId = ${workstreamId}
+        AND (
+          createdAt > ${cursorCreatedAt}
+          OR (createdAt = ${cursorCreatedAt} AND id > ${cursorId})
+        )
+      ORDER BY createdAt ASC, id ASC
+    `)
+
+    return rows.map((row) => WorkstreamMessageRowSchema.parse(row)).map((row) => toChatMessage(row))
+  }
+
+  async listRecentMessages(workstreamId: RecordIdRef, limit: number): Promise<ChatMessage[]> {
+    const rows = await databaseService.query<unknown>(surql`
+      SELECT * FROM workstreamMessage
+      WHERE workstreamId = ${workstreamId}
+      ORDER BY createdAt DESC, id DESC
+      LIMIT ${Math.max(1, limit)}
+    `)
+
+    return rows
+      .map((row) => WorkstreamMessageRowSchema.parse(row))
+      .reverse()
+      .map((row) => toChatMessage(row))
+  }
+
+  async searchMessages(params: {
+    workstreamId: RecordIdRef
+    role: 'user' | 'assistant'
+    query: string
+    limit: number
+  }): Promise<Array<{ id: string; role: 'user' | 'assistant'; createdAt: string; content: string }>> {
+    const normalizedQuery = params.query.trim().toLowerCase()
+    if (!normalizedQuery) return []
+
+    const messages = await this.listMessages(params.workstreamId)
+    return messages
+      .filter((message) => message.role === params.role)
+      .map((message) => ({
+        id: message.id,
+        role: message.role as 'user' | 'assistant',
+        createdAt: new Date(toTimestamp(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))
+  }
+
+  async addUserMessage(params: {
+    messageId: RecordIdRef
+    workstreamId: RecordIdRef
+    content: string
+  }): Promise<ChatMessage> {
+    const message: ChatMessage = {
+      id: toMessageId(params.messageId),
+      role: 'user',
+      parts: [{ type: 'text', text: params.content }],
+      metadata: { createdAt: Date.now() },
+    }
+
+    await this.upsertMessages({ workstreamId: params.workstreamId, messages: [message] })
+    return message
+  }
+
+  async addAgentMessage(params: {
+    messageId: RecordIdRef
+    workstreamId: RecordIdRef
+    parts: ChatMessage['parts']
+    metadata?: ChatMessage['metadata']
+  }): Promise<ChatMessage> {
+    const message: ChatMessage = {
+      id: toMessageId(params.messageId),
+      role: 'assistant',
+      parts: params.parts,
+      metadata: withCreatedAtMetadata(params.metadata),
+    }
+
+    await this.upsertMessages({ workstreamId: params.workstreamId, messages: [message] })
+    return message
+  }
+
+  async ensureBootstrapWelcomeMessage(params: {
+    workstreamId: RecordIdRef
+    agentId: string
+    text: string
+  }): Promise<void> {
+    const existingRow = await databaseService.findOne(
+      TABLES.WORKSTREAM_MESSAGE,
+      { workstreamId: params.workstreamId },
+      WorkstreamMessageExistingRowSchema,
+    )
+    if (existingRow) return
+
+    const messageText = params.text.trim()
+    if (!messageText) return
+
+    await this.upsertMessages({
+      workstreamId: params.workstreamId,
+      messages: [
+        {
+          id: Bun.randomUUIDv7(),
+          role: 'assistant',
+          parts: [{ type: 'text', text: messageText }],
+          metadata: {
+            agentId: params.agentId,
+            agentName: agentDisplayNames[params.agentId] ?? params.agentId,
+            createdAt: Date.now(),
+          },
+        },
+      ],
+    })
+  }
+
+  async listAllMessages(workstreamId: RecordIdRef): Promise<ChatMessage[]> {
+    return await this.listMessages(workstreamId)
+  }
+
+  async addAttachments(): Promise<void> {
+    // Attachments are no longer persisted via workstreamMessage service in AI SDK mode.
+  }
+}
+
+export const workstreamMessageService = new WorkstreamMessageService()

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

@@ -0,0 +1,58 @@
+import { WORKSTREAM } from '@lota-sdk/shared/constants/workstream'
+
+import { chatLogger } from '../config/logger'
+import type { RecordIdRef } from '../db/record-id'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import type { HelperAgent } from '../runtime/helper-model'
+import { llmHelperService } from '../runtime/helper-model'
+import { deriveTitle, limitTitleWords } from '../runtime/title-helpers'
+import { workstreamService } from './workstream.service'
+
+const titlePromises = new Map<string, Promise<string>>()
+
+class WorkstreamTitleService {
+  async ensureTitle(workstreamId: RecordIdRef, existingTitle: string, sourceText: string): Promise<string> {
+    const trimmedSource = sourceText.trim()
+    if (!trimmedSource) return existingTitle
+    if (existingTitle && existingTitle.trim() !== WORKSTREAM.DEFAULT_TITLE) {
+      return existingTitle
+    }
+
+    const key = recordIdToString(workstreamId, TABLES.WORKSTREAM)
+    const existingPromise = titlePromises.get(key)
+    if (existingPromise) {
+      return existingPromise
+    }
+
+    const promise = this.generateAndPersistTitle(workstreamId, trimmedSource).finally(() => {
+      titlePromises.delete(key)
+    })
+    titlePromises.set(key, promise)
+
+    return promise
+  }
+
+  private async generateAndPersistTitle(workstreamId: RecordIdRef, sourceText: string): Promise<string> {
+    let title = ''
+    try {
+      title = await llmHelperService.generateHelperText({
+        tag: 'workstream-title',
+        createAgent: (_opts: unknown) => ({ generate: async () => ({ text: '' }) }) as unknown as HelperAgent,
+        messages: [{ role: 'user' as const, content: `Generate a concise 4-5 word title for: ${sourceText}` }],
+      })
+    } catch (error) {
+      chatLogger.warn`Failed to generate workstream title (non-fatal): ${error}`
+      title = ''
+    }
+
+    if (!title) {
+      title = limitTitleWords(deriveTitle(sourceText || WORKSTREAM.DEFAULT_TITLE))
+    }
+
+    await workstreamService.updateTitle(workstreamId, title)
+    return title
+  }
+}
+
+export const workstreamTitleService = new WorkstreamTitleService()