@lota-sdk/core 0.1.15 → 0.1.17

package/src/services/playbook-registry.service.ts

@@ -0,0 +1,67 @@
+import type { PlanTemplateRecord } from '@lota-sdk/shared'
+
+import type { RecordIdInput } from '../db/record-id'
+import type { PlaybookContribution } from '../runtime/plugin-types'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+import { planTemplateService } from './plan-template.service'
+
+class PlaybookRegistryService {
+  collectPlaybooks(): PlaybookContribution[] {
+    const plugins = getRuntimeConfig().pluginRuntime ?? {}
+    const playbooks: PlaybookContribution[] = []
+    for (const plugin of Object.values(plugins)) {
+      if (plugin.playbookContributor?.playbooks) {
+        playbooks.push(...plugin.playbookContributor.playbooks)
+      }
+    }
+    return playbooks
+  }
+
+  async syncPlaybookTemplates(organizationId: RecordIdInput): Promise<PlanTemplateRecord[]> {
+    const playbooks = this.collectPlaybooks()
+    const templates: PlanTemplateRecord[] = []
+    const existing = await planTemplateService.listTemplates(organizationId, { source: 'playbook' })
+
+    for (const pb of playbooks) {
+      const match = existing.find((t) => t.sourceRef === pb.name)
+      if (match) {
+        const updated = await planTemplateService.updateTemplate(match.id, { draft: pb.draft, tags: pb.tags })
+        templates.push(updated)
+      } else {
+        const created = await planTemplateService.createTemplate({
+          organizationId,
+          name: pb.name,
+          description: pb.description,
+          draft: pb.draft,
+          tags: pb.tags,
+          source: 'playbook',
+          sourceRef: pb.name,
+        })
+        templates.push(created)
+      }
+    }
+
+    return templates
+  }
+
+  async instantiatePlaybook(params: {
+    name: string
+    organizationId: RecordIdInput
+    workstreamId: RecordIdInput
+    leadAgentId: string
+  }): Promise<unknown> {
+    const templates = await planTemplateService.listTemplates(params.organizationId, { source: 'playbook' })
+    const template = templates.find((t) => t.sourceRef === params.name)
+    if (!template) {
+      throw new Error(`Playbook "${params.name}" not found.`)
+    }
+    return planTemplateService.instantiate({
+      templateId: template.id,
+      organizationId: params.organizationId,
+      workstreamId: params.workstreamId,
+      leadAgentId: params.leadAgentId,
+    })
+  }
+}
+
+export const playbookRegistryService = new PlaybookRegistryService()

package/src/services/plugin-executor.service.ts

@@ -0,0 +1,103 @@
+import type { OwnershipDispatchContext, PlanNodeResult, PlanNodeSpec, PluginPlanNodeOwner } from '@lota-sdk/shared'
+
+import type { LotaPlugin, PluginNodeExecutionParams } from '../runtime/plugin-types'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+function getPluginRuntime() {
+  return (getRuntimeConfig().pluginRuntime ?? {}) as Record<string, LotaPlugin | undefined>
+}
+
+function buildPluginExecutionParams(params: {
+  owner: PluginPlanNodeOwner
+  nodeSpec: PlanNodeSpec
+  resolvedInput: Record<string, unknown>
+  context: OwnershipDispatchContext
+}): PluginNodeExecutionParams {
+  return {
+    operation: params.owner.operation,
+    nodeSpec: params.nodeSpec,
+    inputs: params.resolvedInput,
+    context: {
+      organizationId: params.context.organizationId,
+      workstreamId: params.context.workstreamId,
+      planId: params.context.planId,
+      nodeId: params.context.nodeId,
+      ...(params.context.userId ? { userId: params.context.userId } : {}),
+      ...(params.context.userName ? { userName: params.context.userName } : {}),
+    },
+  }
+}
+
+class PluginExecutorService {
+  validateOwner(owner: PluginPlanNodeOwner, nodeId: string): PlanValidationIssueInput[] {
+    const plugin = getPluginRuntime()[owner.ref]
+    if (!plugin) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_executor_missing',
+          message: `Node "${nodeId}" references unknown plugin executor "${owner.ref}".`,
+          nodeId,
+          detail: { pluginRef: owner.ref },
+        },
+      ]
+    }
+
+    const nodeExecutor = plugin.nodeExecutor
+    if (!nodeExecutor) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_node_executor_missing',
+          message: `Plugin "${owner.ref}" does not expose a node executor.`,
+          nodeId,
+          detail: { pluginRef: owner.ref },
+        },
+      ]
+    }
+
+    if (!nodeExecutor.supportedOperations.includes(owner.operation)) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_operation_missing',
+          message: `Plugin "${owner.ref}" does not support operation "${owner.operation}".`,
+          nodeId,
+          detail: { pluginRef: owner.ref, operation: owner.operation },
+        },
+      ]
+    }
+
+    return []
+  }
+
+  async executeNode(params: {
+    nodeSpec: PlanNodeSpec
+    resolvedInput: Record<string, unknown>
+    context: OwnershipDispatchContext
+  }): Promise<PlanNodeResult> {
+    if (params.nodeSpec.owner.executorType !== 'plugin') {
+      throw new Error(`PluginExecutor cannot execute owner type "${params.nodeSpec.owner.executorType}".`)
+    }
+
+    const plugin = getPluginRuntime()[params.nodeSpec.owner.ref]
+    const nodeExecutor = plugin?.nodeExecutor
+    if (!plugin || !nodeExecutor || !nodeExecutor.supportedOperations.includes(params.nodeSpec.owner.operation)) {
+      throw new Error(
+        `Plugin executor ${params.nodeSpec.owner.ref}.${params.nodeSpec.owner.operation} is not registered.`,
+      )
+    }
+
+    return nodeExecutor.executeNode(
+      buildPluginExecutionParams({
+        owner: params.nodeSpec.owner,
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      }),
+    )
+  }
+}
+
+export const pluginExecutorService = new PluginExecutorService()

package/src/services/quality-metrics.service.ts

@@ -0,0 +1,132 @@
+import { NodeQualityMetricsSchema } from '@lota-sdk/shared'
+import type { NodeQualityMetrics } from '@lota-sdk/shared'
+import { z } from 'zod'
+
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+
+const QualityMetricRowSchema = NodeQualityMetricsSchema.extend({
+  id: z.unknown(),
+  organizationId: z.unknown(),
+  runId: z.unknown(),
+  nodeId: z.string().optional(),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+})
+
+class QualityMetricsService {
+  async recordNodeMetrics(params: {
+    organizationId: string
+    runId: string
+    nodeId: string
+    metrics: NodeQualityMetrics
+  }): Promise<void> {
+    await databaseService.create(
+      TABLES.QUALITY_METRIC,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        nodeId: params.nodeId,
+        ownerRef: params.metrics.ownerRef,
+        ownerType: params.metrics.ownerType,
+        nodeType: params.metrics.nodeType,
+        executionTimeMs: params.metrics.executionTimeMs,
+        attemptCount: params.metrics.attemptCount,
+        artifactCount: params.metrics.artifactCount,
+        validationIssueCount: params.metrics.validationIssueCount,
+      },
+      QualityMetricRowSchema,
+    )
+  }
+
+  async recordCycleMetrics(params: { organizationId: string; runId: string }): Promise<void> {
+    const existing = await databaseService.findMany(
+      TABLES.QUALITY_METRIC,
+      { runId: ensureRecordId(params.runId, TABLES.PLAN_RUN) },
+      QualityMetricRowSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+
+    if (!Array.isArray(existing) || existing.length === 0) return
+
+    const totalExecutionTime = existing.reduce(
+      (sum, m) => sum + (typeof m.executionTimeMs === 'number' ? m.executionTimeMs : 0),
+      0,
+    )
+    const totalAttempts = existing.reduce(
+      (sum, m) => sum + (typeof m.attemptCount === 'number' ? m.attemptCount : 0),
+      0,
+    )
+    const totalIssues = existing.reduce(
+      (sum, m) => sum + (typeof m.validationIssueCount === 'number' ? m.validationIssueCount : 0),
+      0,
+    )
+
+    await databaseService.create(
+      TABLES.QUALITY_METRIC,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        ownerRef: 'cycle-summary',
+        ownerType: 'system',
+        nodeType: 'action',
+        executionTimeMs: totalExecutionTime,
+        attemptCount: totalAttempts,
+        artifactCount: existing.length,
+        validationIssueCount: totalIssues,
+      },
+      QualityMetricRowSchema,
+    )
+  }
+
+  detectRegression(params: {
+    metrics: Array<{ executionTimeMs: number; validationIssueCount: number }>
+    window?: number
+  }): { detected: boolean; trend?: 'improving' | 'stable' | 'regressing' } {
+    const window = params.window ?? 5
+    const recent = params.metrics.slice(-window)
+    if (recent.length < 2) return { detected: false, trend: 'stable' }
+
+    const mid = Math.floor(recent.length / 2)
+    const firstHalf = recent.slice(0, mid)
+    const secondHalf = recent.slice(mid)
+
+    const avgFirst = firstHalf.reduce((sum, m) => sum + m.validationIssueCount, 0) / firstHalf.length
+    const avgSecond = secondHalf.reduce((sum, m) => sum + m.validationIssueCount, 0) / secondHalf.length
+
+    const timeFirst = firstHalf.reduce((sum, m) => sum + m.executionTimeMs, 0) / firstHalf.length
+    const timeSecond = secondHalf.reduce((sum, m) => sum + m.executionTimeMs, 0) / secondHalf.length
+
+    const issueRegression = avgFirst > 0 && avgSecond > avgFirst * 1.5
+    const timeRegression = timeFirst > 0 && timeSecond > timeFirst * 2
+
+    if (issueRegression || timeRegression) {
+      return { detected: true, trend: 'regressing' }
+    }
+
+    const issueImproving = avgFirst > 0 && avgSecond < avgFirst * 0.7
+    const timeImproving = timeFirst > 0 && timeSecond < timeFirst * 0.7
+
+    if (issueImproving || timeImproving) {
+      return { detected: false, trend: 'improving' }
+    }
+
+    return { detected: false, trend: 'stable' }
+  }
+
+  async getMetricsByOwner(params: {
+    organizationId: string
+    ownerRef: string
+    limit?: number
+  }): Promise<z.infer<typeof QualityMetricRowSchema>[]> {
+    return databaseService.findMany(
+      TABLES.QUALITY_METRIC,
+      { organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION), ownerRef: params.ownerRef },
+      QualityMetricRowSchema,
+      { orderBy: 'createdAt', orderDir: 'DESC', limit: params.limit ?? 20 },
+    )
+  }
+}
+
+export const qualityMetricsService = new QualityMetricsService()

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

@@ -1,5 +1,3 @@
-import { createHash } from 'node:crypto'
-
 import {
   RecentActivityDeepLinkSchema,
   RecentActivityEventInputSchema,
@@ -8,6 +6,7 @@ import {
   RecentActivitySchema,
   RecentActivitySourceSchema,
   RecentActivityTitleSourceSchema,
+  recordIdSchema,
 } from '@lota-sdk/shared'
 import type {
   RecentActivity,
@@ -23,12 +22,12 @@ 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'
+import { compactRecord, compactWhitespace, truncateText } from '../utils/string'
 
 const RecentActivityEventRowSchema = z.object({
-  id: z.unknown(),
-  organizationId: z.unknown(),
-  userId: z.unknown(),
+  id: recordIdSchema,
+  organizationId: recordIdSchema,
+  userId: recordIdSchema,
   sourceEventId: z.string(),
   source: RecentActivitySourceSchema,
   kind: RecentActivityEventInputSchema.shape.kind,
@@ -39,14 +38,14 @@ const RecentActivityEventRowSchema = z.object({
   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()]),
+  occurredAt: z.coerce.date(),
+  createdAt: z.coerce.date(),
 })
 
 const RecentActivityRowSchema = z.object({
-  id: z.unknown(),
-  organizationId: z.unknown(),
-  userId: z.unknown(),
+  id: recordIdSchema,
+  organizationId: recordIdSchema,
+  userId: recordIdSchema,
   mergeKey: z.string(),
   kind: RecentActivityEventInputSchema.shape.kind,
   targetKind: RecentActivityEventInputSchema.shape.targetKind,
@@ -57,29 +56,19 @@ const RecentActivityRowSchema = z.object({
   sourceLabel: z.string(),
   deepLink: RecentActivityDeepLinkSchema,
   metadata: RecentActivityMetadataSchema.optional(),
-  latestEventId: z.unknown().optional(),
+  latestEventId: recordIdSchema.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()]),
+  latestEventAt: z.coerce.date(),
+  titleRefinedAt: z.coerce.date().optional(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
 })
 
 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')
+  const digest = new Bun.CryptoHasher('sha256').update(key).digest('hex')
   return new RecordId(table, digest)
 }
 
@@ -90,6 +79,11 @@ function shouldKeepExistingAgentTitle(existing: RecentActivityRow | null): boole
 function buildRecentActivityAreaKey(
   row: Pick<RecentActivityRow, 'targetKind' | 'targetId' | 'kind' | 'mergeKey' | 'metadata'>,
 ): string {
+  const workstreamId = row.metadata?.workstreamId
+  if (workstreamId) {
+    return `workstream:${compactWhitespace(workstreamId)}`
+  }
+
   if (row.targetId) {
     return `${row.targetKind}:${row.targetId}`
   }
@@ -149,11 +143,11 @@ class RecentActivityService {
   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),
+      sourceEventId: truncateText(input.sourceEventId, 200),
+      ...(input.targetId ? { targetId: truncateText(input.targetId, 200) } : {}),
+      mergeKey: truncateText(input.mergeKey, 200),
+      title: truncateText(input.title, 140),
+      sourceLabel: truncateText(input.sourceLabel, 40),
       ...(input.metadata ? { metadata: RecentActivityMetadataSchema.parse(input.metadata) } : {}),
     }
   }
@@ -309,7 +303,7 @@ class RecentActivityService {
     const existing = await databaseService.findOne(TABLES.RECENT_ACTIVITY, { id: activityRef }, RecentActivityRowSchema)
     if (!existing) return null
 
-    const nextTitle = clampText(params.title, 80)
+    const nextTitle = truncateText(params.title, 80)
     if (!nextTitle) return this.toPublicItem(existing)
     if (compactWhitespace(nextTitle).toLowerCase() === compactWhitespace(existing.title).toLowerCase()) {
       return this.toPublicItem(existing)
@@ -347,7 +341,7 @@ class RecentActivityService {
       systemTitle: row.systemTitle,
       sourceLabel: row.sourceLabel,
       kind: row.kind,
-      metadata: RecentActivityMetadataSchema.parse(row.metadata ?? {}),
+      metadata: RecentActivityMetadataSchema.parse(row.metadata),
     }
   }
 

package/src/services/skill-resolver.service.ts

@@ -0,0 +1,19 @@
+class SkillResolverService {
+  async resolve(params: {
+    skillRef: string
+    organizationId: string
+  }): Promise<{ executorType: 'agent' | 'plugin'; ref: string; operation?: string } | null> {
+    // Dynamic import to avoid circular dependencies and enable testability
+    const { learnedSkillService } = await import('./learned-skill.service')
+    const skill = await learnedSkillService.findByNameOrTag(params.organizationId, params.skillRef)
+    if (!skill) return null
+
+    if (skill.agentId) {
+      return { executorType: 'agent', ref: skill.agentId }
+    }
+
+    return null
+  }
+}
+
+export const skillResolverService = new SkillResolverService()

package/src/services/social-chat-history.service.ts

@@ -0,0 +1,197 @@
+import { z } from 'zod'
+
+import { getRedisConnection } from '../redis'
+import type { LotaRuntimeBackgroundCursor, LotaRuntimeBackgroundCursorKind } from '../runtime/runtime-extensions'
+
+const DEFAULT_SOCIAL_CHAT_HISTORY_PREFIX = 'lota:social:history'
+
+const SocialChatMessageRoleSchema = z.enum(['user', 'assistant'])
+const SocialChatSourceSchema = z.literal('social')
+const SocialChatPlatformSchema = z.literal('slack')
+
+const SocialChatHistoryMessageSchema = z.object({
+  source: SocialChatSourceSchema,
+  sourceId: z.string().trim().min(1),
+  platform: SocialChatPlatformSchema,
+  workspaceId: z.string().trim().min(1),
+  channelId: z.string().trim().min(1),
+  threadId: z.string().trim().min(1),
+  messageId: z.string().trim().min(1),
+  role: SocialChatMessageRoleSchema,
+  parts: z.array(z.record(z.string(), z.unknown())),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  cursor: z.object({ createdAt: z.coerce.date(), id: z.string().trim().min(1) }),
+})
+
+export type SocialChatHistoryMessage = z.infer<typeof SocialChatHistoryMessageSchema>
+
+let socialChatHistoryPrefix = DEFAULT_SOCIAL_CHAT_HISTORY_PREFIX
+
+function trimConfiguredPrefix(value: string | undefined): string {
+  const normalized = value?.trim()
+  return normalized && normalized.length > 0 ? normalized : DEFAULT_SOCIAL_CHAT_HISTORY_PREFIX
+}
+
+function compareCursorOrder(left: LotaRuntimeBackgroundCursor, right: LotaRuntimeBackgroundCursor): number {
+  const timeDiff = left.createdAt.getTime() - right.createdAt.getTime()
+  if (timeDiff !== 0) return timeDiff
+  return left.id.localeCompare(right.id)
+}
+
+class SocialChatHistoryService {
+  configure(params?: { keyPrefix?: string }): void {
+    socialChatHistoryPrefix = trimConfiguredPrefix(params?.keyPrefix)
+  }
+
+  private messageStorageKey(message: {
+    platform: 'slack'
+    workspaceId: string
+    threadId: string
+    messageId: string
+  }): string {
+    return `${socialChatHistoryPrefix}:message:${message.platform}:${message.workspaceId}:${message.threadId}:${message.messageId}`
+  }
+
+  private threadIndexKey(workspaceId: string, threadId: string): string {
+    return `${socialChatHistoryPrefix}:thread:${workspaceId}:${threadId}`
+  }
+
+  private workspaceIndexKey(workspaceId: string): string {
+    return `${socialChatHistoryPrefix}:workspace:${workspaceId}`
+  }
+
+  private cursorKey(kind: LotaRuntimeBackgroundCursorKind, workspaceId: string): string {
+    return `${socialChatHistoryPrefix}:cursor:${kind}:${workspaceId}`
+  }
+
+  private serializeMessage(message: SocialChatHistoryMessage): string {
+    return JSON.stringify({
+      ...message,
+      cursor: { ...message.cursor, createdAt: message.cursor.createdAt.toISOString() },
+    })
+  }
+
+  private parseStoredMessage(value: string | null): SocialChatHistoryMessage | null {
+    if (!value) return null
+    try {
+      const parsed = SocialChatHistoryMessageSchema.safeParse(JSON.parse(value))
+      return parsed.success ? parsed.data : null
+    } catch {
+      return null
+    }
+  }
+
+  private serializeCursor(cursor: LotaRuntimeBackgroundCursor): string {
+    return JSON.stringify({ ...cursor, createdAt: cursor.createdAt.toISOString() })
+  }
+
+  private parseCursor(value: string | null): LotaRuntimeBackgroundCursor | null {
+    if (!value) return null
+    try {
+      const parsed = z.object({ createdAt: z.coerce.date(), id: z.string().trim().min(1) }).safeParse(JSON.parse(value))
+      return parsed.success ? parsed.data : null
+    } catch {
+      return null
+    }
+  }
+
+  async upsertMessages(messages: SocialChatHistoryMessage[]): Promise<SocialChatHistoryMessage[]> {
+    if (messages.length === 0) return []
+
+    const redis = getRedisConnection()
+    const normalizedMessages = messages.map((message) => SocialChatHistoryMessageSchema.parse(message))
+    const multi = redis.multi()
+
+    for (const message of normalizedMessages) {
+      const storageKey = this.messageStorageKey(message)
+      const score = message.cursor.createdAt.getTime()
+      multi.set(storageKey, this.serializeMessage(message))
+      multi.zadd(this.threadIndexKey(message.workspaceId, message.threadId), score, storageKey)
+      multi.zadd(this.workspaceIndexKey(message.workspaceId), score, storageKey)
+    }
+
+    await multi.exec()
+    return normalizedMessages
+  }
+
+  async listThreadMessages(params: { workspaceId: string; threadId: string }): Promise<SocialChatHistoryMessage[]> {
+    const redis = getRedisConnection()
+    const storageKeys = await redis.zrange(this.threadIndexKey(params.workspaceId, params.threadId), 0, -1)
+    if (storageKeys.length === 0) return []
+
+    const storedValues = await redis.mget(storageKeys)
+    return storedValues
+      .map((value) => this.parseStoredMessage(value))
+      .filter((message): message is SocialChatHistoryMessage => message !== null)
+      .sort((left, right) => compareCursorOrder(left.cursor, right.cursor))
+  }
+
+  async listWorkspaceMessages(params: {
+    workspaceId: string
+    cursor: LotaRuntimeBackgroundCursor | null
+    onboardingCutoff: Date | null
+  }): Promise<SocialChatHistoryMessage[]> {
+    const redis = getRedisConnection()
+    const indexKey = this.workspaceIndexKey(params.workspaceId)
+    const scoreStart =
+      params.cursor?.createdAt.getTime() ??
+      (params.onboardingCutoff ? params.onboardingCutoff.getTime() : Number.NEGATIVE_INFINITY)
+    const storageKeys =
+      params.cursor || params.onboardingCutoff
+        ? await redis.zrangebyscore(indexKey, scoreStart, '+inf')
+        : await redis.zrange(indexKey, 0, -1)
+
+    if (storageKeys.length === 0) return []
+
+    const storedValues = await redis.mget(storageKeys)
+    return storedValues
+      .map((value) => this.parseStoredMessage(value))
+      .filter((message): message is SocialChatHistoryMessage => message !== null)
+      .filter((message) => {
+        if (params.cursor) {
+          return compareCursorOrder(message.cursor, params.cursor) > 0
+        }
+        if (params.onboardingCutoff) {
+          return message.cursor.createdAt.getTime() > params.onboardingCutoff.getTime()
+        }
+        return true
+      })
+      .sort((left, right) => compareCursorOrder(left.cursor, right.cursor))
+  }
+
+  async hasWorkspaceMessages(params: {
+    workspaceId: string
+    cursor: LotaRuntimeBackgroundCursor | null
+    onboardingCutoff: Date | null
+  }): Promise<boolean> {
+    const messages = await this.listWorkspaceMessages({
+      workspaceId: params.workspaceId,
+      cursor: params.cursor,
+      onboardingCutoff: params.onboardingCutoff,
+    })
+    return messages.length > 0
+  }
+
+  async getBackgroundCursor(
+    kind: LotaRuntimeBackgroundCursorKind,
+    workspaceId: string,
+  ): Promise<LotaRuntimeBackgroundCursor | null> {
+    const redis = getRedisConnection()
+    return this.parseCursor(await redis.get(this.cursorKey(kind, workspaceId)))
+  }
+
+  async setBackgroundCursor(
+    kind: LotaRuntimeBackgroundCursorKind,
+    workspaceId: string,
+    cursor: LotaRuntimeBackgroundCursor,
+  ): Promise<void> {
+    const redis = getRedisConnection()
+    await redis.set(this.cursorKey(kind, workspaceId), this.serializeCursor(cursor))
+  }
+}
+
+export const socialChatHistoryService = new SocialChatHistoryService()
+
+export function configureSocialChatHistory(params?: { keyPrefix?: string }): void {
+  socialChatHistoryService.configure(params)
+}