@lota-sdk/core 0.1.5

package/src/services/memory.utils.ts

@@ -0,0 +1,84 @@
+import { MEMORY } from '../config/constants'
+import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '../config/search'
+import type { MemorySearchResult } from '../db/memory-types'
+import { resolveCandidateLimit } from '../runtime/retrieval-pipeline'
+import type { MemoryRerankOutput } from './memory.service'
+
+export function getCandidateLimit(limit: number): number {
+  return resolveCandidateLimit({
+    limit,
+    multiplier: VECTOR_SEARCH_OVERFETCH_MULTIPLIER,
+    minimum: MEMORY.DEFAULT_CANDIDATE_LIMIT,
+  })
+}
+
+export function formatMemoryResults(results: MemorySearchResult[]): string {
+  if (results.length === 0) return 'No stored memories.'
+
+  const normalize = (value: string) => {
+    const trimmed = value.replace(/\s+/g, ' ').trim()
+    if (trimmed.length <= 400) return trimmed
+    return `${trimmed.slice(0, 400)}...`
+  }
+
+  return results
+    .map((item) => {
+      const line = `- ${normalize(item.content)}`
+      const annotations: string[] = []
+      if (item.contradictions?.length) {
+        for (const c of item.contradictions) {
+          annotations.push(`  [!] Contradicted by: ${normalize(c)}`)
+        }
+      }
+      const related = item.metadata.relatedContext
+      if (Array.isArray(related) && related.length > 0) {
+        for (const ctx of related.slice(0, 3)) {
+          annotations.push(`  [~] Related: ${normalize(String(ctx))}`)
+        }
+      }
+      return annotations.length > 0 ? `${line}\n${annotations.join('\n')}` : line
+    })
+    .join('\n')
+}
+
+export function formatRerankedResults(
+  reranked: MemoryRerankOutput | null,
+  candidates: MemorySearchResult[],
+  limit: number,
+): string {
+  if (!reranked || reranked.sections.length === 0) {
+    return formatMemoryResults(candidates.slice(0, limit))
+  }
+
+  const candidateById = new Map(candidates.map((item) => [item.id, item]))
+  const used = new Set<string>()
+  const sections: string[] = []
+  let total = 0
+
+  for (const section of reranked.sections) {
+    if (total >= limit) break
+
+    const lines: string[] = []
+    for (const item of section.items) {
+      const candidate = candidateById.get(item.id)
+      if (!candidate || used.has(candidate.id)) continue
+      used.add(candidate.id)
+      total += 1
+      const reason = item.relevance ? ` — ${item.relevance}` : ''
+      const trimmed = candidate.content.replace(/\s+/g, ' ').trim()
+      const content = trimmed.length <= 400 ? trimmed : `${trimmed.slice(0, 400)}...`
+      lines.push(`- ${content}${reason}`)
+      if (total >= limit) break
+    }
+
+    if (lines.length > 0) {
+      sections.push(`${section.title}:\n${lines.join('\n')}`)
+    }
+  }
+
+  if (sections.length === 0) {
+    return formatMemoryResults(candidates.slice(0, limit))
+  }
+
+  return sections.join('\n\n')
+}

package/src/services/mutating-approval.service.ts

@@ -0,0 +1,110 @@
+import type { RecordIdRef } from '../db/record-id'
+import { ensureRecordId } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { extractMessageText } from '../runtime/workstream-chat-helpers'
+import { workstreamMessageService } from './workstream-message.service'
+
+const APPROVAL_VERIFICATION_MESSAGE_WINDOW = 20
+
+export type VerifyMutatingApproval = (params: {
+  workstreamId: string
+  approvalReason: string
+  approvalToken: string
+  approvalMessageId?: string
+}) => Promise<{ ok: true } | { ok: false; reason: string }>
+
+function extractQuotedValue(value: string): string {
+  const trimmed = value.trim()
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('`') && trimmed.endsWith('`'))
+  ) {
+    return trimmed.slice(1, -1).trim()
+  }
+  return trimmed
+}
+
+function extractApprovalFieldsFromMessage(messageText: string): { token?: string; reason?: string } {
+  const lines = messageText
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+
+  let token: string | undefined
+  let reason: string | undefined
+
+  for (const line of lines) {
+    const tokenMatch = /^approval\s*token\s*:\s*(.+)$/i.exec(line)
+    if (tokenMatch?.[1]) token = extractQuotedValue(tokenMatch[1])
+
+    const reasonMatch = /^approval\s*reason\s*:\s*(.+)$/i.exec(line)
+    if (reasonMatch?.[1]) reason = extractQuotedValue(reasonMatch[1])
+  }
+
+  if (!token || !reason) {
+    const tokenJsonMatch = /["']approvalToken["']\s*:\s*["']([^"']+)["']/i.exec(messageText)
+    const reasonJsonMatch = /["']approvalReason["']\s*:\s*["']([^"']+)["']/i.exec(messageText)
+    if (!token && tokenJsonMatch?.[1]) token = tokenJsonMatch[1].trim()
+    if (!reason && reasonJsonMatch?.[1]) reason = reasonJsonMatch[1].trim()
+  }
+
+  return { token, reason }
+}
+
+function messageContainsExactApproval(messageText: string, approvalToken: string, approvalReason: string): boolean {
+  const extracted = extractApprovalFieldsFromMessage(messageText)
+  if (!extracted.token || !extracted.reason) return false
+  return extracted.token === approvalToken && extracted.reason === approvalReason
+}
+
+async function verifyMutatingApprovalForWorkstream(
+  workstreamId: RecordIdRef,
+  params: { approvalReason: string; approvalToken: string; approvalMessageId?: string },
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  const token = extractQuotedValue(params.approvalToken)
+  const reason = extractQuotedValue(params.approvalReason)
+  const approvalMessageId = params.approvalMessageId?.trim()
+  if (!token || !reason) {
+    return { ok: false, reason: 'Mutating approval metadata is incomplete.' }
+  }
+  if (params.approvalMessageId !== undefined && !approvalMessageId) {
+    return { ok: false, reason: 'approvalMessageId cannot be empty when provided.' }
+  }
+
+  const recentMessages = await workstreamMessageService.listRecentMessages(
+    workstreamId,
+    APPROVAL_VERIFICATION_MESSAGE_WINDOW,
+  )
+  const userMessages = recentMessages.filter((message) => message.role === 'user')
+  if (userMessages.length === 0) {
+    return { ok: false, reason: 'No user message history available to verify mutating approval.' }
+  }
+
+  const latestUserMessage = userMessages.at(-1)
+  if (!latestUserMessage) {
+    return { ok: false, reason: 'Latest user message was not found for mutating approval verification.' }
+  }
+
+  if (approvalMessageId && approvalMessageId !== latestUserMessage.id) {
+    return {
+      ok: false,
+      reason:
+        'approvalMessageId must reference the latest user message for mutating approval verification; stale approvals are not accepted.',
+    }
+  }
+
+  if (!messageContainsExactApproval(extractMessageText(latestUserMessage), token, reason)) {
+    return {
+      ok: false,
+      reason:
+        'Referenced approval message must contain exact approval fields: "Approval Token: <token>" and "Approval Reason: <reason>".',
+    }
+  }
+
+  return { ok: true }
+}
+
+export const verifyMutatingApproval: VerifyMutatingApproval = async (params) => {
+  return await verifyMutatingApprovalForWorkstream(ensureRecordId(params.workstreamId, TABLES.WORKSTREAM), params)
+}

package/src/services/recent-activity-title.service.ts

@@ -0,0 +1,74 @@
+import { createHelperModelRuntime } from '../runtime/helper-model'
+import {
+  createRecentActivityTitleRefinerAgent,
+  recentActivityTitleRefinerPrompt,
+} from '../system-agents/recent-activity-title-refiner.agent'
+import { compactWhitespace } from '../utils/string'
+import { recentActivityService } from './recent-activity.service'
+
+const RECENT_ACTIVITY_TITLE_TIMEOUT_MS = 60_000
+
+function normalizeTitle(value: string): string {
+  const normalized = compactWhitespace(value)
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .replace(/[.!?,;:]+$/g, '')
+  return normalized.length <= 80 ? normalized : normalized.slice(0, 80).trim()
+}
+
+function buildRefinementPromptInput(
+  candidate: Awaited<ReturnType<typeof recentActivityService.getRefinementCandidate>>,
+) {
+  if (!candidate) return null
+
+  const metadata = candidate.metadata
+  const lines = [
+    `sourceLabel=${candidate.sourceLabel}`,
+    `systemTitle=${candidate.systemTitle}`,
+    metadata.agentName ? `agentName=${metadata.agentName}` : null,
+    metadata.workstreamTitle ? `workstreamTitle=${metadata.workstreamTitle}` : null,
+    metadata.userMessageText ? `userMessage=${metadata.userMessageText}` : null,
+    metadata.assistantSummary ? `assistantSummary=${metadata.assistantSummary}` : null,
+  ].filter((line): line is string => Boolean(line))
+
+  if (lines.length === 0) return null
+  return lines.join('\n')
+}
+
+class RecentActivityTitleService {
+  helperRuntime: ReturnType<typeof createHelperModelRuntime> = createHelperModelRuntime()
+
+  async refineRecentActivityTitle(activityId: string): Promise<void> {
+    const candidate = await recentActivityService.getRefinementCandidate(activityId)
+    if (!candidate || candidate.kind !== 'chat.turn.completed') {
+      return
+    }
+
+    const promptInput = buildRefinementPromptInput(candidate)
+    if (!promptInput) {
+      return
+    }
+
+    const refinedTitle = normalizeTitle(
+      await this.helperRuntime.generateHelperText({
+        tag: 'recent-activity-title-refinement',
+        createAgent: createRecentActivityTitleRefinerAgent,
+        defaultSystemPrompt: recentActivityTitleRefinerPrompt,
+        timeoutMs: RECENT_ACTIVITY_TITLE_TIMEOUT_MS,
+        messages: [{ role: 'user', content: promptInput }],
+      }),
+    )
+    if (
+      !recentActivityService.isChiefTitleUseful({
+        currentTitle: candidate.title,
+        systemTitle: candidate.systemTitle,
+        candidateTitle: refinedTitle,
+      })
+    ) {
+      return
+    }
+
+    await recentActivityService.refineTitle({ activityId, title: refinedTitle })
+  }
+}
+
+export const recentActivityTitleService = new RecentActivityTitleService()

package/src/services/recent-activity.service.ts

@@ -0,0 +1,397 @@
+import { createHash } from 'node:crypto'
+
+import {
+  RecentActivityDeepLinkSchema,
+  RecentActivityEventInputSchema,
+  RecentActivityEventSchema,
+  RecentActivityMetadataSchema,
+  RecentActivitySchema,
+  RecentActivitySourceSchema,
+  RecentActivityTitleSourceSchema,
+} from '@lota-sdk/shared/schemas/recent-activity'
+import type {
+  RecentActivity,
+  RecentActivityEvent,
+  RecentActivityEventInput,
+  RecentActivitySource,
+} from '@lota-sdk/shared/schemas/recent-activity'
+import { RecordId } from 'surrealdb'
+import { z } from 'zod'
+
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import type { RecordIdInput, RecordIdRef } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
+import { compactWhitespace } from '../utils/string'
+
+const RecentActivityEventRowSchema = z.object({
+  id: z.unknown(),
+  organizationId: z.unknown(),
+  userId: z.unknown(),
+  sourceEventId: z.string(),
+  source: RecentActivitySourceSchema,
+  kind: RecentActivityEventInputSchema.shape.kind,
+  targetKind: RecentActivityEventInputSchema.shape.targetKind,
+  targetId: z.string().optional(),
+  mergeKey: z.string(),
+  title: z.string(),
+  sourceLabel: z.string(),
+  deepLink: RecentActivityDeepLinkSchema,
+  metadata: RecentActivityMetadataSchema.optional(),
+  occurredAt: z.union([z.string(), z.date(), z.number()]),
+  createdAt: z.union([z.string(), z.date(), z.number()]),
+})
+
+const RecentActivityRowSchema = z.object({
+  id: z.unknown(),
+  organizationId: z.unknown(),
+  userId: z.unknown(),
+  mergeKey: z.string(),
+  kind: RecentActivityEventInputSchema.shape.kind,
+  targetKind: RecentActivityEventInputSchema.shape.targetKind,
+  targetId: z.string().optional(),
+  title: z.string(),
+  systemTitle: z.string(),
+  titleSource: RecentActivityTitleSourceSchema,
+  sourceLabel: z.string(),
+  deepLink: RecentActivityDeepLinkSchema,
+  metadata: RecentActivityMetadataSchema.optional(),
+  latestEventId: z.unknown().optional(),
+  latestSourceEventId: z.string().optional(),
+  latestEventAt: z.union([z.string(), z.date(), z.number()]),
+  titleRefinedAt: z.union([z.string(), z.date(), z.number()]).optional(),
+  createdAt: z.union([z.string(), z.date(), z.number()]),
+  updatedAt: z.union([z.string(), z.date(), z.number()]),
+})
+
+type RecentActivityEventRow = z.infer<typeof RecentActivityEventRowSchema>
+type RecentActivityRow = z.infer<typeof RecentActivityRowSchema>
+
+function compactRecord(value: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== null && entry !== undefined))
+}
+
+function clampText(value: string, maxLength: number): string {
+  const normalized = compactWhitespace(value)
+  if (normalized.length <= maxLength) return normalized
+  return normalized.slice(0, maxLength).trim()
+}
+
+function buildDeterministicRecordId(table: string, key: string): RecordId {
+  const digest = createHash('sha256').update(key).digest('hex')
+  return new RecordId(table, digest)
+}
+
+function shouldKeepExistingChiefTitle(existing: RecentActivityRow | null): boolean {
+  return existing?.titleSource === 'chief' && compactWhitespace(existing.title).length > 0
+}
+
+function buildRecentActivityAreaKey(
+  row: Pick<RecentActivityRow, 'deepLink' | 'kind' | 'mergeKey' | 'metadata'>,
+): string {
+  const target = row.deepLink.search
+
+  if (target.docId) return `document:${target.docId}`
+  if (target.chat) return `workstream:${target.chat}`
+  if (target.agent) return `agent:${target.agent}`
+
+  const normalizedWebsiteUrl = row.metadata?.normalizedWebsiteUrl
+  if (row.kind === 'website-intelligence.viewed' && normalizedWebsiteUrl) {
+    return `website:${compactWhitespace(normalizedWebsiteUrl).toLowerCase()}`
+  }
+
+  if (row.kind === 'website-intelligence.viewed') return 'website-intelligence'
+
+  return row.mergeKey
+}
+
+class RecentActivityService {
+  private toPublicEvent(row: RecentActivityEventRow): RecentActivityEvent {
+    return RecentActivityEventSchema.parse({
+      id: recordIdToString(
+        ensureRecordId(row.id as RecordIdInput, TABLES.RECENT_ACTIVITY_EVENT),
+        TABLES.RECENT_ACTIVITY_EVENT,
+      ),
+      sourceEventId: row.sourceEventId,
+      source: row.source,
+      kind: row.kind,
+      targetKind: row.targetKind,
+      targetId: row.targetId,
+      mergeKey: row.mergeKey,
+      title: row.title,
+      sourceLabel: row.sourceLabel,
+      deepLink: row.deepLink,
+      ...(row.metadata ? { metadata: row.metadata } : {}),
+      occurredAt: toIsoDateTimeString(row.occurredAt),
+      createdAt: toIsoDateTimeString(row.createdAt),
+    })
+  }
+
+  private toPublicItem(row: RecentActivityRow): RecentActivity {
+    return RecentActivitySchema.parse({
+      id: recordIdToString(ensureRecordId(row.id as RecordIdInput, TABLES.RECENT_ACTIVITY), TABLES.RECENT_ACTIVITY),
+      kind: row.kind,
+      targetKind: row.targetKind,
+      targetId: row.targetId,
+      mergeKey: row.mergeKey,
+      title: row.title,
+      systemTitle: row.systemTitle,
+      titleSource: row.titleSource,
+      sourceLabel: row.sourceLabel,
+      deepLink: row.deepLink,
+      ...(row.metadata ? { metadata: row.metadata } : {}),
+      latestEventAt: toIsoDateTimeString(row.latestEventAt),
+      titleRefinedAt: toOptionalIsoDateTimeString(row.titleRefinedAt),
+      createdAt: toIsoDateTimeString(row.createdAt),
+      updatedAt: toIsoDateTimeString(row.updatedAt),
+    })
+  }
+
+  private sanitizeEvent(input: RecentActivityEventInput): RecentActivityEventInput {
+    return {
+      ...input,
+      sourceEventId: clampText(input.sourceEventId, 200),
+      ...(input.targetId ? { targetId: clampText(input.targetId, 200) } : {}),
+      mergeKey: clampText(input.mergeKey, 200),
+      title: clampText(input.title, 140),
+      sourceLabel: clampText(input.sourceLabel, 40),
+      ...(input.metadata ? { metadata: RecentActivityMetadataSchema.parse(input.metadata) } : {}),
+    }
+  }
+
+  async recordEvents(params: {
+    orgId: RecordIdRef
+    userId: RecordIdRef
+    source: RecentActivitySource
+    events: RecentActivityEventInput[]
+  }): Promise<RecentActivity[]> {
+    await databaseService.connect()
+
+    const items: RecentActivity[] = []
+    for (const candidate of params.events) {
+      const recorded = await this.recordEvent({
+        orgId: params.orgId,
+        userId: params.userId,
+        source: params.source,
+        event: candidate,
+      })
+      items.push(recorded.item)
+    }
+
+    return items
+  }
+
+  async recordEvent(params: {
+    orgId: RecordIdRef
+    userId: RecordIdRef
+    source: RecentActivitySource
+    event: RecentActivityEventInput
+  }): Promise<{ event: RecentActivityEvent; item: RecentActivity }> {
+    await databaseService.connect()
+
+    const parsedEvent = this.sanitizeEvent(RecentActivityEventInputSchema.parse(params.event))
+    const orgIdString = recordIdToString(params.orgId, TABLES.ORGANIZATION)
+    const userIdString = recordIdToString(params.userId, TABLES.USER)
+    const eventRecordId = buildDeterministicRecordId(
+      TABLES.RECENT_ACTIVITY_EVENT,
+      `${orgIdString}:${userIdString}:${parsedEvent.sourceEventId}`,
+    )
+    const recentRecordId = buildDeterministicRecordId(
+      TABLES.RECENT_ACTIVITY,
+      `${orgIdString}:${userIdString}:${parsedEvent.mergeKey}`,
+    )
+    const occurredAt = parsedEvent.occurredAt ? new Date(parsedEvent.occurredAt) : new Date()
+    const existingRecent = await databaseService.findOne(
+      TABLES.RECENT_ACTIVITY,
+      { id: recentRecordId },
+      RecentActivityRowSchema,
+    )
+
+    const eventRow = await databaseService.upsert(
+      TABLES.RECENT_ACTIVITY_EVENT,
+      eventRecordId,
+      compactRecord({
+        organizationId: params.orgId,
+        userId: params.userId,
+        sourceEventId: parsedEvent.sourceEventId,
+        source: params.source,
+        kind: parsedEvent.kind,
+        targetKind: parsedEvent.targetKind,
+        targetId: parsedEvent.targetId,
+        mergeKey: parsedEvent.mergeKey,
+        title: parsedEvent.title,
+        sourceLabel: parsedEvent.sourceLabel,
+        deepLink: parsedEvent.deepLink,
+        metadata: parsedEvent.metadata,
+        occurredAt,
+      }),
+      RecentActivityEventRowSchema,
+      { mutation: 'merge' },
+    )
+
+    const keepExistingChiefTitle = shouldKeepExistingChiefTitle(existingRecent)
+    const visibleTitle = keepExistingChiefTitle && existingRecent ? existingRecent.title : parsedEvent.title
+    const recentRow = await databaseService.upsert(
+      TABLES.RECENT_ACTIVITY,
+      recentRecordId,
+      compactRecord({
+        organizationId: params.orgId,
+        userId: params.userId,
+        mergeKey: parsedEvent.mergeKey,
+        kind: parsedEvent.kind,
+        targetKind: parsedEvent.targetKind,
+        targetId: parsedEvent.targetId,
+        title: visibleTitle,
+        systemTitle: parsedEvent.title,
+        titleSource: keepExistingChiefTitle ? 'chief' : 'system',
+        sourceLabel: parsedEvent.sourceLabel,
+        deepLink: parsedEvent.deepLink,
+        metadata: parsedEvent.metadata,
+        latestEventId: eventRecordId,
+        latestSourceEventId: parsedEvent.sourceEventId,
+        latestEventAt: occurredAt,
+      }),
+      RecentActivityRowSchema,
+      { mutation: 'merge' },
+    )
+
+    return { event: this.toPublicEvent(eventRow), item: this.toPublicItem(recentRow) }
+  }
+
+  async listRecentActivities(params: {
+    orgId: RecordIdRef
+    userId: RecordIdRef
+    limit?: number
+  }): Promise<RecentActivity[]> {
+    await databaseService.connect()
+    const limit = params.limit ?? 5
+    const rows = await databaseService.findMany(
+      TABLES.RECENT_ACTIVITY,
+      { organizationId: params.orgId, userId: params.userId },
+      RecentActivityRowSchema,
+      { orderBy: 'latestEventAt', orderDir: 'DESC', limit: Math.max(limit * 5, 25) },
+    )
+
+    const items: RecentActivity[] = []
+    const seenAreas = new Set<string>()
+
+    for (const row of rows) {
+      const areaKey = buildRecentActivityAreaKey(row)
+      if (seenAreas.has(areaKey)) continue
+
+      seenAreas.add(areaKey)
+      items.push(this.toPublicItem(row))
+
+      if (items.length === limit) break
+    }
+
+    return items
+  }
+
+  async listRecentEvents(params: {
+    orgId: RecordIdRef
+    userId: RecordIdRef
+    limit?: number
+  }): Promise<RecentActivityEvent[]> {
+    await databaseService.connect()
+    const rows = await databaseService.findMany(
+      TABLES.RECENT_ACTIVITY_EVENT,
+      { organizationId: params.orgId, userId: params.userId },
+      RecentActivityEventRowSchema,
+      { orderBy: 'occurredAt', orderDir: 'DESC', limit: params.limit ?? 25 },
+    )
+    return rows.map((row) => this.toPublicEvent(row))
+  }
+
+  async getRecentActivityById(activityId: string | RecordIdRef): Promise<RecentActivity | null> {
+    await databaseService.connect()
+    const activityRef = ensureRecordId(activityId, TABLES.RECENT_ACTIVITY)
+    const row = await databaseService.findOne(TABLES.RECENT_ACTIVITY, { id: activityRef }, RecentActivityRowSchema)
+    return row ? this.toPublicItem(row) : null
+  }
+
+  async refineTitle(params: { activityId: string | RecordIdRef; title: string }): Promise<RecentActivity | null> {
+    await databaseService.connect()
+    const activityRef = ensureRecordId(params.activityId, TABLES.RECENT_ACTIVITY)
+    const existing = await databaseService.findOne(TABLES.RECENT_ACTIVITY, { id: activityRef }, RecentActivityRowSchema)
+    if (!existing) return null
+
+    const nextTitle = clampText(params.title, 80)
+    if (!nextTitle) return this.toPublicItem(existing)
+    if (compactWhitespace(nextTitle).toLowerCase() === compactWhitespace(existing.title).toLowerCase()) {
+      return this.toPublicItem(existing)
+    }
+
+    const updated = await databaseService.update(
+      TABLES.RECENT_ACTIVITY,
+      activityRef,
+      { title: nextTitle, titleSource: 'chief', titleRefinedAt: new Date() },
+      RecentActivityRowSchema,
+      { mutation: 'merge' },
+    )
+
+    return updated ? this.toPublicItem(updated) : null
+  }
+
+  async getRefinementCandidate(
+    activityId: string | RecordIdRef,
+  ): Promise<{
+    id: string
+    title: string
+    systemTitle: string
+    sourceLabel: string
+    kind: RecentActivity['kind']
+    metadata: z.infer<typeof RecentActivityMetadataSchema>
+  } | null> {
+    await databaseService.connect()
+    const activityRef = ensureRecordId(activityId, TABLES.RECENT_ACTIVITY)
+    const row = await databaseService.findOne(TABLES.RECENT_ACTIVITY, { id: activityRef }, RecentActivityRowSchema)
+    if (!row) return null
+
+    return {
+      id: recordIdToString(activityRef, TABLES.RECENT_ACTIVITY),
+      title: row.title,
+      systemTitle: row.systemTitle,
+      sourceLabel: row.sourceLabel,
+      kind: row.kind,
+      metadata: RecentActivityMetadataSchema.parse(row.metadata ?? {}),
+    }
+  }
+
+  isMeaningfulRefinementCandidate(activity: RecentActivity | null): boolean {
+    if (!activity) return false
+    if (activity.kind !== 'chat.turn.completed') return false
+    return activity.titleSource === 'system'
+  }
+
+  isChiefTitleUseful(params: { currentTitle: string; systemTitle: string; candidateTitle: string }): boolean {
+    const candidate = compactWhitespace(params.candidateTitle)
+    if (!candidate) return false
+
+    const normalizedCandidate = candidate.toLowerCase()
+    const normalizedCurrent = compactWhitespace(params.currentTitle).toLowerCase()
+    const normalizedSystem = compactWhitespace(params.systemTitle).toLowerCase()
+
+    if (normalizedCandidate === normalizedCurrent || normalizedCandidate === normalizedSystem) {
+      return false
+    }
+
+    if (candidate.length < 8 || candidate.length > 80) {
+      return false
+    }
+
+    const bannedTitles = new Set([
+      'follow up',
+      'conversation',
+      'chat',
+      'chief task',
+      'recent activity',
+      'workstream update',
+    ])
+
+    return !bannedTitles.has(normalizedCandidate)
+  }
+}
+
+export const recentActivityService = new RecentActivityService()