@lota-sdk/core 0.1.5

package/src/services/workstream.service.ts

@@ -0,0 +1,854 @@
+import { WORKSTREAM } from '@lota-sdk/shared/constants/workstream'
+import { BoundQuery, RecordId, StringRecordId, surql } from 'surrealdb'
+
+import { agentDisplayNames, getCoreWorkstreamProfile, isAgentName } from '../config/agent-defaults'
+import { getWorkstreamBootstrapConfig } from '../config/workstream-defaults'
+import { BaseService } from '../db/base.service'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import type { RecordIdInput, RecordIdRef } from '../db/record-id'
+import { databaseService } from '../db/service'
+import type { DatabaseTable } from '../db/tables'
+import { TABLES } from '../db/tables'
+import {
+  MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES,
+  MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES,
+} from '../runtime/context-compaction-constants'
+import {
+  appendToMemoryBlock,
+  compactMemoryBlockEntries,
+  formatPersistedMemoryBlockForPrompt,
+  parseMemoryBlock,
+  serializeMemoryBlock,
+} from '../runtime/memory-block'
+import { toOptionalTrimmedString } from '../runtime/workstream-chat-helpers'
+import { WorkstreamStateSchema } from '../runtime/workstream-state'
+import type { WorkstreamState } from '../runtime/workstream-state'
+import { toIsoDateTimeString } from '../utils/date-time'
+import { chatRunRegistry } from './chat-run-registry.service'
+import { contextCompactionService } from './context-compaction.service'
+import { workstreamMessageService } from './workstream-message.service'
+import { WorkstreamSchema, WorkstreamStatusSchema } from './workstream.types'
+import type {
+  NormalizedWorkstream,
+  PublicWorkstreamApprovalState,
+  PublicWorkstreamDetail,
+  PublicWorkstreamStateFocus,
+  PublicWorkstreamStatePayload,
+  PublicWorkstreamStateProgress,
+  WorkstreamRecord,
+} from './workstream.types'
+
+// Uses SurrealQL directly to keep pagination/order logic close to queries.
+
+const LIST_WORKSTREAMS_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
+WHERE userId = $userId
+  AND organizationId = $orgId
+  AND mode = $mode
+  AND core = $core
+ORDER BY updatedAt DESC
+LIMIT $limit START $offset`
+
+const LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
+WHERE userId = $userId
+  AND organizationId = $orgId
+  AND mode = $mode
+  AND core = $core
+  AND status = "regular"
+ORDER BY updatedAt DESC
+LIMIT $limit START $offset`
+
+const LIST_ALL_WORKSTREAMS_BY_MODE_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
+WHERE userId = $userId
+  AND organizationId = $orgId
+  AND mode = $mode
+  AND core = $core
+ORDER BY updatedAt DESC`
+
+const LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
+WHERE userId = $userId
+  AND organizationId = $orgId
+  AND mode = $mode
+  AND core = $core
+  AND status = "regular"
+ORDER BY updatedAt DESC`
+
+function toSafeDirectIdSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '_')
+}
+
+function toRecordIdValueString(value: RecordIdRef, fallbackTable: string): string {
+  const canonical = recordIdToString(ensureRecordId(value, fallbackTable), fallbackTable)
+  const prefix = `${fallbackTable}:`
+  const withoutTable = canonical.startsWith(prefix) ? canonical.slice(prefix.length) : canonical
+  const wrappedMatch = withoutTable.match(/^⟨(.+)⟩$/)
+  return wrappedMatch ? wrappedMatch[1] : withoutTable
+}
+
+function isRecordIdInput(value: unknown): value is RecordIdInput {
+  if (typeof value === 'string' || value instanceof RecordId || value instanceof StringRecordId) {
+    return true
+  }
+
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const record = value as { tb?: unknown; id?: unknown }
+  return typeof record.tb === 'string' && record.id !== undefined
+}
+
+function getAgentDisplayName(agentId: string): string {
+  return agentDisplayNames[agentId] ?? agentId
+}
+
+function requireDirectAgentId(agentId: string | undefined): string {
+  if (!agentId) {
+    throw new Error('Direct workstreams require an agentId')
+  }
+
+  return agentId
+}
+
+function requirestring(coreType: string | undefined): string {
+  if (!coreType) {
+    throw new Error('Core workstreams require a coreType')
+  }
+
+  return coreType
+}
+
+function buildDirectWorkstreamId({
+  userId,
+  orgId,
+  agentId,
+}: {
+  userId: RecordIdRef
+  orgId: RecordIdRef
+  agentId: string
+}): RecordId {
+  const userValue = toSafeDirectIdSegment(toRecordIdValueString(userId, TABLES.USER))
+  const orgValue = toSafeDirectIdSegment(toRecordIdValueString(orgId, TABLES.ORGANIZATION))
+  return new RecordId(TABLES.WORKSTREAM, `direct_${agentId}_user_${userValue}_organization_${orgValue}`)
+}
+
+function buildCoreWorkstreamId({
+  userId,
+  orgId,
+  coreType,
+}: {
+  userId: RecordIdRef
+  orgId: RecordIdRef
+  coreType: string
+}): RecordId {
+  const userValue = toSafeDirectIdSegment(toRecordIdValueString(userId, TABLES.USER))
+  const orgValue = toSafeDirectIdSegment(toRecordIdValueString(orgId, TABLES.ORGANIZATION))
+  const typeValue = toSafeDirectIdSegment(coreType)
+  return new RecordId(TABLES.WORKSTREAM, `core_${typeValue}_user_${userValue}_organization_${orgValue}`)
+}
+
+function toOptionalIsoDateTimeString(value: number | null | undefined): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+  return toIsoDateTimeString(new Date(value))
+}
+
+function getCompactedSummaryFocus(chatSummary: string | null): string | null {
+  if (!chatSummary) return null
+
+  const lines = chatSummary
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+
+  for (const line of lines) {
+    if (line.endsWith(':')) continue
+    if (line.startsWith('- ')) {
+      return toOptionalTrimmedString(line.slice(2))
+    }
+    return toOptionalTrimmedString(line)
+  }
+
+  return null
+}
+
+function parsePersistedWorkstreamState(value: unknown): WorkstreamState | null {
+  const parsed = WorkstreamStateSchema.safeParse(value)
+  return parsed.success ? parsed.data : null
+}
+
+function buildEmptyWorkstreamStateProgress(): PublicWorkstreamStateProgress {
+  return {
+    hasState: false,
+    lastUpdated: null,
+    completionRatio: null,
+    tasks: { total: 0, open: 0, inProgress: 0, done: 0, blocked: 0 },
+    constraints: { total: 0, approved: 0, candidate: 0 },
+    keyDecisions: 0,
+    openQuestions: 0,
+    risks: 0,
+    artifacts: 0,
+    agentContributions: 0,
+  }
+}
+
+function buildWorkstreamStateProgress(state: WorkstreamState | null): PublicWorkstreamStateProgress {
+  if (!state) {
+    return buildEmptyWorkstreamStateProgress()
+  }
+
+  const tasks = {
+    total: state.tasks.length,
+    open: state.tasks.filter((task) => task.status === 'open').length,
+    inProgress: state.tasks.filter((task) => task.status === 'in-progress').length,
+    done: state.tasks.filter((task) => task.status === 'done').length,
+    blocked: state.tasks.filter((task) => task.status === 'blocked').length,
+  }
+  const constraintsApproved = state.activeConstraints.filter((constraint) => constraint.approved).length
+
+  return {
+    hasState:
+      state.currentPlan !== null ||
+      state.activeConstraints.length > 0 ||
+      state.keyDecisions.length > 0 ||
+      state.tasks.length > 0 ||
+      state.openQuestions.length > 0 ||
+      state.risks.length > 0 ||
+      state.artifacts.length > 0 ||
+      state.agentContributions.length > 0 ||
+      toOptionalTrimmedString(state.approvedBy) !== null ||
+      typeof state.approvedAt === 'number' ||
+      toOptionalTrimmedString(state.approvalMessageId) !== null ||
+      toOptionalTrimmedString(state.approvalNote) !== null,
+    lastUpdated: toOptionalIsoDateTimeString(state.lastUpdated),
+    completionRatio: tasks.total > 0 ? Number((tasks.done / tasks.total).toFixed(4)) : null,
+    tasks,
+    constraints: {
+      total: state.activeConstraints.length,
+      approved: constraintsApproved,
+      candidate: state.activeConstraints.length - constraintsApproved,
+    },
+    keyDecisions: state.keyDecisions.length,
+    openQuestions: state.openQuestions.length,
+    risks: state.risks.length,
+    artifacts: state.artifacts.length,
+    agentContributions: state.agentContributions.length,
+  }
+}
+
+function buildWorkstreamApprovalState(state: WorkstreamState | null): PublicWorkstreamApprovalState | null {
+  if (!state) return null
+
+  const approvedBy = toOptionalTrimmedString(state.approvedBy)
+  const approvedAt = toOptionalIsoDateTimeString(state.approvedAt)
+  const approvalMessageId = toOptionalTrimmedString(state.approvalMessageId)
+  const approvalNote = toOptionalTrimmedString(state.approvalNote)
+
+  if (!approvedBy && !approvedAt && !approvalMessageId && !approvalNote) {
+    return null
+  }
+
+  return { approvedBy, approvedAt, approvalMessageId, approvalNote }
+}
+
+function buildWorkstreamStateFocus(
+  state: WorkstreamState | null,
+  chatSummary: string | null,
+): PublicWorkstreamStateFocus | null {
+  if (!state) {
+    const compactedSummaryFocus = getCompactedSummaryFocus(chatSummary)
+    return compactedSummaryFocus ? { kind: 'chat-summary', text: compactedSummaryFocus } : null
+  }
+
+  const currentPlan = toOptionalTrimmedString(state.currentPlan?.text)
+  if (currentPlan) {
+    return { kind: 'plan', text: currentPlan }
+  }
+
+  const latestTask =
+    [...state.tasks].reverse().find((task) => task.status === 'blocked') ??
+    [...state.tasks].reverse().find((task) => task.status === 'in-progress') ??
+    [...state.tasks].reverse().find((task) => task.status === 'open')
+  const taskTitle = toOptionalTrimmedString(latestTask?.title)
+  if (taskTitle) {
+    return { kind: 'task', text: taskTitle }
+  }
+
+  const latestQuestion = toOptionalTrimmedString(state.openQuestions.at(-1)?.text)
+  if (latestQuestion) {
+    return { kind: 'question', text: latestQuestion }
+  }
+
+  const latestDecision = toOptionalTrimmedString(state.keyDecisions.at(-1)?.decision)
+  if (latestDecision) {
+    return { kind: 'decision', text: latestDecision }
+  }
+
+  const latestAgentNote = toOptionalTrimmedString(state.agentContributions.at(-1)?.summary)
+  if (latestAgentNote) {
+    return { kind: 'agent-note', text: latestAgentNote }
+  }
+
+  const compactedSummaryFocus = getCompactedSummaryFocus(chatSummary)
+  if (compactedSummaryFocus) {
+    return { kind: 'chat-summary', text: compactedSummaryFocus }
+  }
+
+  return null
+}
+
+class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
+  constructor() {
+    super(TABLES.WORKSTREAM, WorkstreamSchema)
+  }
+
+  async createWorkstream(
+    userId: RecordIdRef,
+    orgId: RecordIdRef,
+    options?: { title?: string; mode?: string; agentId?: string; core?: boolean; coreType?: string },
+  ): Promise<NormalizedWorkstream> {
+    const mode = options?.mode ?? 'group'
+    const directAgentId = options?.agentId
+    const core = options?.core === true
+    const coreType = options?.coreType
+
+    if (mode === 'direct' && !directAgentId) {
+      throw new Error('Direct workstreams require an agentId')
+    }
+    if (mode === 'group' && directAgentId) {
+      throw new Error('Group workstreams cannot set agentId')
+    }
+    if (mode === 'direct' && core) {
+      throw new Error('Direct workstreams cannot be core workstreams')
+    }
+    if (core && mode !== 'group') {
+      throw new Error('Core workstreams must use group mode')
+    }
+    if (core && !coreType) {
+      throw new Error('Core workstreams require a coreType')
+    }
+    if (!core && coreType) {
+      throw new Error('Only core workstreams can set a coreType')
+    }
+    const title = (() => {
+      if (options?.title) {
+        return options.title
+      }
+      if (core) {
+        return getCoreWorkstreamProfile(requirestring(coreType)).config.title
+      }
+      if (mode === 'direct') {
+        return getAgentDisplayName(requireDirectAgentId(directAgentId))
+      }
+      return WORKSTREAM.DEFAULT_TITLE
+    })()
+
+    if (mode === 'direct') {
+      const agentId = requireDirectAgentId(directAgentId)
+      const directWorkstreamId = buildDirectWorkstreamId({ userId, orgId, agentId })
+
+      const existing = await this.findById(directWorkstreamId)
+      if (existing) {
+        return this.normalizeWorkstream(existing)
+      }
+
+      let createError: unknown = null
+
+      let workstream = await databaseService
+        .createWithId(
+          TABLES.WORKSTREAM,
+          directWorkstreamId,
+          { userId, organizationId: orgId, mode, core: false, agentId, title, status: 'regular' },
+          WorkstreamSchema,
+        )
+        .catch((error) => {
+          createError = error
+          return null
+        })
+
+      if (!workstream) {
+        workstream = await this.findById(directWorkstreamId)
+      }
+
+      if (!workstream) {
+        if (createError instanceof Error) {
+          throw createError
+        }
+        throw new Error('Failed to create or load direct workstream')
+      }
+
+      return this.normalizeWorkstream(workstream)
+    }
+
+    if (core) {
+      const resolvedCoreType = requirestring(coreType)
+      const coreProfile = getCoreWorkstreamProfile(resolvedCoreType)
+      const coreWorkstreamId = buildCoreWorkstreamId({ userId, orgId, coreType: resolvedCoreType })
+      const existing = await this.findById(coreWorkstreamId)
+      if (existing) {
+        return this.normalizeWorkstream(existing)
+      }
+
+      let createError: unknown = null
+
+      let workstream = await databaseService
+        .createWithId(
+          TABLES.WORKSTREAM,
+          coreWorkstreamId,
+          {
+            userId,
+            organizationId: orgId,
+            mode,
+            core: true,
+            coreType: resolvedCoreType,
+            agentId: coreProfile.config.agentId,
+            title,
+            status: 'regular',
+          },
+          WorkstreamSchema,
+        )
+        .catch((error) => {
+          createError = error
+          return null
+        })
+
+      if (!workstream) {
+        workstream = await this.findById(coreWorkstreamId)
+      }
+
+      if (!workstream) {
+        if (createError instanceof Error) {
+          throw createError
+        }
+        throw new Error('Failed to create or load core workstream')
+      }
+
+      return this.normalizeWorkstream(workstream)
+    }
+
+    const groupWorkstream = await this.create({
+      userId,
+      organizationId: orgId,
+      mode,
+      core: false,
+      title,
+      status: 'regular',
+    })
+
+    return this.normalizeWorkstream(groupWorkstream)
+  }
+
+  async ensureBootstrapWorkstreams(
+    userId: RecordIdRef,
+    orgId: RecordIdRef,
+    options?: { onboardStatus?: string; userName?: string | null },
+  ): Promise<void> {
+    const onboardStatus = options?.onboardStatus ?? 'completed'
+    const onboardingCompleted = onboardStatus === 'completed'
+    const bootstrapConfig = getWorkstreamBootstrapConfig()
+
+    const existingWorkstreams = await databaseService.findMany(
+      TABLES.WORKSTREAM,
+      { userId, organizationId: orgId },
+      WorkstreamSchema,
+    )
+
+    const hasStandardGroupWorkstream = existingWorkstreams.some(
+      (workstream) => workstream.mode === 'group' && workstream.core !== true,
+    )
+    const directWorkstreamsByAgent = new Map<string, WorkstreamRecord>()
+    const coreWorkstreamsByType = new Map<string, WorkstreamRecord>()
+    for (const workstream of existingWorkstreams) {
+      if (workstream.mode !== 'direct' || !workstream.agentId) continue
+      directWorkstreamsByAgent.set(workstream.agentId, workstream)
+    }
+    for (const workstream of existingWorkstreams) {
+      if (workstream.mode !== 'group' || workstream.core !== true) continue
+      if (typeof workstream.coreType !== 'string') continue
+      coreWorkstreamsByType.set(workstream.coreType, workstream)
+    }
+
+    const requiredDirectAgents = onboardingCompleted
+      ? bootstrapConfig.completedDirectAgents
+      : bootstrapConfig.onboardingDirectAgents
+    const creations: Promise<NormalizedWorkstream>[] = []
+    for (const agentId of requiredDirectAgents) {
+      if (directWorkstreamsByAgent.has(agentId)) continue
+      creations.push(
+        this.createWorkstream(userId, orgId, { mode: 'direct', agentId, title: getAgentDisplayName(agentId) }),
+      )
+    }
+
+    if (onboardingCompleted && bootstrapConfig.ensureDefaultGroupOnCompleted && !hasStandardGroupWorkstream) {
+      creations.push(
+        this.createWorkstream(userId, orgId, { mode: 'group', core: false, title: WORKSTREAM.DEFAULT_TITLE }),
+      )
+    }
+
+    if (onboardingCompleted) {
+      for (const coreType of bootstrapConfig.coreTypesAfterOnboarding) {
+        if (coreWorkstreamsByType.has(coreType)) continue
+        creations.push(
+          this.createWorkstream(userId, orgId, {
+            mode: 'group',
+            core: true,
+            coreType,
+            title: getCoreWorkstreamProfile(coreType).config.title,
+          }),
+        )
+      }
+    }
+
+    let createdWorkstreams: NormalizedWorkstream[] = []
+    if (creations.length > 0) {
+      createdWorkstreams = await Promise.all(creations)
+    }
+
+    const onboardingWelcome = bootstrapConfig.onboardingWelcome
+    if (!onboardingCompleted && onboardingWelcome) {
+      const createdChiefWorkstream = createdWorkstreams.find(
+        (workstream) => workstream.mode === 'direct' && workstream.agentId === onboardingWelcome.directAgentId,
+      )
+      const existingChiefWorkstream = directWorkstreamsByAgent.get(onboardingWelcome.directAgentId)
+
+      const chiefWorkstreamId =
+        createdChiefWorkstream?.id ??
+        (existingChiefWorkstream ? this.normalizeWorkstreamId(existingChiefWorkstream.id) : null)
+
+      if (chiefWorkstreamId) {
+        const chiefWorkstreamRef = ensureRecordId(chiefWorkstreamId, TABLES.WORKSTREAM)
+        await workstreamMessageService.ensureBootstrapWelcomeMessage({
+          workstreamId: chiefWorkstreamRef,
+          agentId: onboardingWelcome.directAgentId,
+          text: onboardingWelcome.buildMessageText({ userName: options?.userName }),
+        })
+      }
+    }
+  }
+
+  async listWorkstreams(
+    userId: RecordIdRef,
+    orgId: RecordIdRef,
+    options: { mode: string; core?: boolean; take?: number; page?: number; includeArchived: boolean },
+  ): Promise<{ workstreams: NormalizedWorkstream[]; hasMore: boolean }> {
+    const core = options.core === true
+    if (options.mode === 'direct' && core) {
+      throw new Error('Direct workstreams cannot be queried as core workstreams')
+    }
+
+    if (options.mode === 'direct' || core) {
+      const query = options.includeArchived
+        ? LIST_ALL_WORKSTREAMS_BY_MODE_QUERY
+        : LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY
+      const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
+        new BoundQuery(query, { userId, orgId, mode: options.mode, core }),
+        WorkstreamSchema,
+      )
+
+      return { workstreams: workstreams.map((workstream) => this.normalizeWorkstream(workstream)), hasMore: false }
+    }
+
+    const take = options.take ?? WORKSTREAM.DEFAULT_PAGE_LIMIT
+    const page = options.page ?? 1
+    const query = options.includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
+    const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
+      new BoundQuery(query, {
+        userId,
+        orgId,
+        mode: options.mode,
+        core: false,
+        limit: take + 1,
+        offset: (page - 1) * take,
+      }),
+      WorkstreamSchema,
+    )
+
+    const hasMore = workstreams.length > take
+    const sliced = hasMore ? workstreams.slice(0, take) : workstreams
+
+    return { workstreams: sliced.map((workstream) => this.normalizeWorkstream(workstream)), hasMore }
+  }
+
+  async getWorkstream(workstreamId: RecordIdRef): Promise<NormalizedWorkstream> {
+    const workstream = await this.getById(workstreamId)
+    return this.normalizeWorkstream(workstream)
+  }
+
+  async getWorkstreamRecord(workstreamId: RecordIdRef): Promise<WorkstreamRecord> {
+    return await this.getById(workstreamId)
+  }
+
+  async updateTitle(workstreamId: RecordIdRef, title: string): Promise<NormalizedWorkstream> {
+    const existing = await this.getById(workstreamId)
+    this.assertMutableWorkstream(existing, 'rename')
+    const workstream = await this.update(workstreamId, { title })
+    return this.normalizeWorkstream(workstream)
+  }
+
+  async updateStatus(workstreamId: RecordIdRef, status: string): Promise<NormalizedWorkstream> {
+    const validStatus = WorkstreamStatusSchema.parse(status)
+    const existing = await this.getById(workstreamId)
+    this.assertMutableWorkstream(existing, validStatus === 'archived' ? 'archive' : 'unarchive')
+    const workstream = await this.update(workstreamId, { status: validStatus })
+    return this.normalizeWorkstream(workstream)
+  }
+
+  async setActiveRunId(workstreamId: RecordIdRef, runId: string | null): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    if (runId === null) {
+      await databaseService.query<unknown>(surql`
+        UPDATE ONLY ${workstreamRef}
+        SET activeRunId = NONE
+      `)
+      return
+    }
+
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeRunId = ${runId}
+    `)
+  }
+
+  async getActiveRunId(workstreamId: RecordIdRef): Promise<string | null> {
+    const workstream = await this.getById(workstreamId)
+    const activeRunId = workstream.activeRunId
+    if (typeof activeRunId !== 'string') return null
+    const normalized = activeRunId.trim()
+    return normalized.length > 0 ? normalized : null
+  }
+
+  async clearActiveRunIdIfMatches(workstreamId: RecordIdRef, runId: string): Promise<void> {
+    const activeRunId = await this.getActiveRunId(workstreamId)
+    if (activeRunId !== runId) return
+    await this.setActiveRunId(workstreamId, null)
+  }
+
+  async persistChangeTracker(
+    workstreamId: RecordIdRef,
+    payload: { chatSummary: string; state: WorkstreamState },
+  ): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await this.update(workstreamRef, { chatSummary: payload.chatSummary, state: payload.state })
+  }
+
+  async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
+    const activeRunId = await this.getActiveRunId(workstreamId)
+    if (!activeRunId) return false
+
+    const stopped = chatRunRegistry.stop(activeRunId, new DOMException('Run stopped by user.', 'AbortError'))
+    if (stopped) {
+      return true
+    }
+
+    await this.clearActiveRunIdIfMatches(workstreamId, activeRunId)
+    return false
+  }
+
+  async setCompacting(workstreamId: RecordIdRef, value: boolean): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET isCompacting = ${value}
+    `)
+  }
+
+  async appendMemoryBlock(workstreamId: RecordIdRef, entry: string): Promise<string> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    const workstream = await this.getById(workstreamRef)
+    const entries = parseMemoryBlock(workstream.memoryBlock)
+
+    const labelMatch = entry.match(/^(\w+):\s*/i)
+    const role = labelMatch ? labelMatch[1].toLowerCase() : 'system'
+    const content = labelMatch ? entry.slice(labelMatch[0].length).trim() : entry.trim()
+
+    const updatedEntries = appendToMemoryBlock(entries, role, content)
+    const serialized = serializeMemoryBlock(updatedEntries)
+
+    await this.update(workstreamRef, { memoryBlock: serialized })
+
+    if (updatedEntries.length >= MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES) {
+      void this.compactMemoryBlock(workstreamRef).catch(() => {})
+    }
+
+    return this.formatMemoryBlockForPrompt({
+      memoryBlock: serialized,
+      memoryBlockSummary: workstream.memoryBlockSummary,
+    })
+  }
+
+  async compactMemoryBlock(workstreamId: RecordIdRef): Promise<boolean> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    const workstream = await this.getById(workstreamRef)
+    const result = await compactMemoryBlockEntries({
+      previousSummary: workstream.memoryBlockSummary,
+      entries: parseMemoryBlock(workstream.memoryBlock),
+      triggerEntries: MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES,
+      chunkEntries: MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES,
+      compact: (params) => contextCompactionService.compactMemoryBlock(params),
+    })
+
+    if (!result.compacted) return false
+
+    await this.update(workstreamRef, {
+      memoryBlockSummary: result.summary || '',
+      memoryBlock: serializeMemoryBlock(result.entries),
+    })
+
+    return true
+  }
+
+  async deleteWorkstream(workstreamId: RecordIdRef): Promise<void> {
+    const existing = await this.getById(workstreamId)
+    this.assertMutableWorkstream(existing, 'delete')
+    await this.delete(workstreamId)
+  }
+
+  async listRecentWorkstreams({
+    userId,
+    orgId,
+    excludeWorkstreamId,
+    limit,
+  }: {
+    userId: RecordIdRef
+    orgId: RecordIdRef
+    excludeWorkstreamId?: RecordIdRef
+    limit: number
+  }) {
+    let excludeCondition = ''
+    const vars: Record<string, unknown> = { userId, orgId, limit }
+
+    if (excludeWorkstreamId) {
+      excludeCondition = 'AND id != $excludeWorkstreamId'
+      vars.excludeWorkstreamId = excludeWorkstreamId
+    }
+
+    const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
+      new BoundQuery(
+        `SELECT * FROM ${TABLES.WORKSTREAM}
+	       WHERE userId = $userId
+	         AND organizationId = $orgId
+	         ${excludeCondition}
+	         AND status != "archived"
+	       ORDER BY updatedAt DESC
+	       LIMIT $limit`,
+        vars,
+      ),
+      WorkstreamSchema,
+    )
+
+    return workstreams.map((workstream) => this.normalizeWorkstream(workstream))
+  }
+
+  private normalizeWorkstreamId(id: unknown): string {
+    return this.normalizeRecordIdString(id, TABLES.WORKSTREAM)
+  }
+
+  private normalizeRecordIdString(id: unknown, table: DatabaseTable): string {
+    if (!isRecordIdInput(id)) {
+      throw new Error(`Invalid record id for table ${table}`)
+    }
+
+    return recordIdToString(id, String(table))
+  }
+
+  formatMemoryBlockForPrompt(workstream: Pick<WorkstreamRecord, 'memoryBlock' | 'memoryBlockSummary'>): string {
+    return formatPersistedMemoryBlockForPrompt({
+      summary: workstream.memoryBlockSummary,
+      entries: parseMemoryBlock(workstream.memoryBlock),
+    })
+  }
+
+  private getDefaultTitle(workstream: Pick<WorkstreamRecord, 'core' | 'coreType'>): string {
+    if (workstream.core === true && typeof workstream.coreType === 'string') {
+      return getCoreWorkstreamProfile(workstream.coreType).config.title
+    }
+
+    return WORKSTREAM.DEFAULT_TITLE
+  }
+
+  normalizeWorkstream(workstream: WorkstreamRecord): NormalizedWorkstream {
+    const activeRunId =
+      typeof workstream.activeRunId === 'string' && workstream.activeRunId.trim().length > 0
+        ? workstream.activeRunId
+        : null
+    const isCompacting = workstream.isCompacting === true
+    const mode = typeof workstream.mode === 'string' ? workstream.mode : 'group'
+    const core = workstream.core === true
+    const coreType = core && typeof workstream.coreType === 'string' ? workstream.coreType : undefined
+    const status = typeof workstream.status === 'string' ? workstream.status : 'regular'
+    return {
+      id: this.normalizeWorkstreamId(workstream.id),
+      userId: this.normalizeRecordIdString(workstream.userId, TABLES.USER),
+      organizationId: this.normalizeRecordIdString(workstream.organizationId, TABLES.ORGANIZATION),
+      mode,
+      core,
+      ...(coreType ? { coreType } : {}),
+      isRunning: activeRunId !== null,
+      isCompacting,
+      ...(isAgentName(workstream.agentId) ? { agentId: workstream.agentId } : {}),
+      title: workstream.title ?? this.getDefaultTitle(workstream),
+      status,
+      memoryBlock: this.formatMemoryBlockForPrompt(workstream),
+      createdAt: toIsoDateTimeString(workstream.createdAt),
+      updatedAt: toIsoDateTimeString(workstream.updatedAt),
+    }
+  }
+
+  toPublicWorkstream(workstream: NormalizedWorkstream | WorkstreamRecord) {
+    const id = typeof workstream.id === 'string' ? workstream.id : this.normalizeWorkstreamId(workstream.id)
+    const createdAt = toIsoDateTimeString(workstream.createdAt)
+    const updatedAt = toIsoDateTimeString(workstream.updatedAt)
+    const activeRunId =
+      'activeRunId' in workstream &&
+      typeof workstream.activeRunId === 'string' &&
+      workstream.activeRunId.trim().length > 0
+        ? workstream.activeRunId
+        : null
+    const isRunning = 'isRunning' in workstream ? workstream.isRunning : activeRunId !== null
+    const isCompacting = workstream.isCompacting === true
+    const mode = typeof workstream.mode === 'string' ? workstream.mode : 'group'
+    const core = workstream.core === true
+    const coreType = core && typeof workstream.coreType === 'string' ? workstream.coreType : undefined
+    return {
+      id,
+      mode,
+      core,
+      ...(coreType ? { coreType } : {}),
+      ...(isAgentName(workstream.agentId) ? { agentId: workstream.agentId } : {}),
+      title: workstream.title ?? this.getDefaultTitle(workstream),
+      status: workstream.status ?? 'regular',
+      isRunning,
+      isCompacting,
+      createdAt,
+      updatedAt,
+    }
+  }
+
+  toPublicWorkstreamDetail(workstream: WorkstreamRecord): PublicWorkstreamDetail {
+    const publicWorkstream = this.toPublicWorkstream(workstream)
+    const snapshot = parsePersistedWorkstreamState(workstream.state)
+    const chatSummary = toOptionalTrimmedString(workstream.chatSummary)
+    const progress = buildWorkstreamStateProgress(snapshot)
+    const workstreamState: PublicWorkstreamStatePayload = {
+      focus: buildWorkstreamStateFocus(snapshot, chatSummary),
+      chatSummary,
+      approval: buildWorkstreamApprovalState(snapshot),
+      progress,
+      snapshot,
+    }
+
+    return { ...publicWorkstream, workstreamState }
+  }
+
+  private assertMutableWorkstream(
+    workstream: WorkstreamRecord,
+    action: 'rename' | 'archive' | 'unarchive' | 'delete',
+  ): void {
+    if (workstream.mode === 'direct') {
+      throw new Error(`Direct workstreams cannot be ${action}d`)
+    }
+    if (workstream.core === true) {
+      throw new Error(`Core workstreams cannot be ${action}d`)
+    }
+  }
+}
+
+export const workstreamService = new WorkstreamService()