@lota-sdk/core 0.1.18 → 0.1.20

package/src/services/plan-deadline.service.ts

@@ -130,14 +130,15 @@ class PlanDeadlineService {
       }
     }
 
-    const nextTriggerAt: Date | null =
+    const nextTriggerAt =
       sweep.entries
         .map((entry) => entry.evaluation.nextTriggerAt)
         .filter((value): value is Date => {
           if (!value) return false
           return value.getTime() > currentTime.getTime()
         })
-        .sort((a, b) => a.getTime() - b.getTime())[0] ?? null
+        .sort((a, b) => a.getTime() - b.getTime())
+        .at(0) ?? null
 
     if (nextTriggerAt) {
       await this.enqueueDeadlineCheck(nextTriggerAt)
@@ -152,14 +153,15 @@ class PlanDeadlineService {
       return
     }
 
-    const nextTriggerAt: Date | null =
+    const nextTriggerAt =
       sweep.entries
         .map((entry) => entry.evaluation.nextTriggerAt)
         .filter((value): value is Date => {
           if (!value) return false
           return value.getTime() > now.getTime()
         })
-        .sort((a, b) => a.getTime() - b.getTime())[0] ?? null
+        .sort((a, b) => a.getTime() - b.getTime())
+        .at(0) ?? null
 
     if (nextTriggerAt) {
       await this.enqueueDeadlineCheck(nextTriggerAt)

package/src/services/queue-job.service.ts

@@ -0,0 +1,356 @@
+import {
+  QueueJobAttemptStatusSchema,
+  QueueJobErrorSchema,
+  QueueJobStatusSchema,
+  recordIdSchema,
+} from '@lota-sdk/shared'
+import type { QueueJobError, QueueJobStatus } from '@lota-sdk/shared'
+import { RecordId } from 'surrealdb'
+import { z } from 'zod'
+
+import { recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { compactRecord, readRecord, readString, readStringField, stringifyUnknown, truncateText } from '../utils/string'
+
+const QueueJobRowSchema = z.object({
+  id: recordIdSchema,
+  queueName: z.string(),
+  jobName: z.string(),
+  bullmqJobId: z.string(),
+  status: QueueJobStatusSchema,
+  data: z.object({ value: z.unknown() }).passthrough().optional(),
+  options: z.record(z.string(), z.unknown()).optional(),
+  context: z.record(z.string(), z.unknown()).optional(),
+  deduplicationId: z.string().optional(),
+  schedulerId: z.string().optional(),
+  maxAttempts: z.number().int().nonnegative().optional(),
+  attemptCount: z.number().int().nonnegative().default(0),
+  result: z.object({ value: z.unknown() }).passthrough().optional(),
+  lastError: QueueJobErrorSchema.optional(),
+  queuedAt: z.coerce.date(),
+  startedAt: z.coerce.date().optional(),
+  completedAt: z.coerce.date().optional(),
+  failedAt: z.coerce.date().optional(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+
+const QueueJobAttemptRowSchema = z.object({
+  id: recordIdSchema,
+  queueJobId: recordIdSchema,
+  attemptNumber: z.number().int().positive(),
+  status: QueueJobAttemptStatusSchema,
+  result: z.object({ value: z.unknown() }).passthrough().optional(),
+  error: QueueJobErrorSchema.optional(),
+  startedAt: z.coerce.date(),
+  completedAt: z.coerce.date().optional(),
+  durationMs: z.number().int().nonnegative().optional(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+})
+
+export interface TrackedBullJobLike {
+  queueName: string
+  id?: string | number
+  name: string
+  data?: unknown
+  opts?: unknown
+  attemptsMade: number | null | undefined
+  timestamp?: number
+}
+
+function buildDeterministicRecordId(table: string, key: string): RecordId {
+  const digest = new Bun.CryptoHasher('sha256').update(key).digest('hex')
+  return new RecordId(table, digest)
+}
+
+function sanitizeQueueValue(value: unknown, depth = 0): unknown {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'string') return truncateText(value, 20_000)
+  if (typeof value === 'number' || typeof value === 'boolean') return value
+  if (typeof value === 'bigint') return value.toString()
+  if (value instanceof Date) return value.toISOString()
+
+  if (depth >= 6) {
+    return stringifyUnknown(value) ?? '[unserializable]'
+  }
+
+  if (Array.isArray(value)) {
+    return value.slice(0, 200).map((item) => sanitizeQueueValue(item, depth + 1))
+  }
+
+  const record = readRecord(value)
+  if (!record) {
+    return stringifyUnknown(value) ?? '[unserializable]'
+  }
+
+  return Object.fromEntries(
+    Object.entries(record)
+      .slice(0, 200)
+      .map(([key, entry]) => [key, sanitizeQueueValue(entry, depth + 1)]),
+  )
+}
+
+function wrapFlexibleValue(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined
+  return { value: sanitizeQueueValue(value) }
+}
+
+function toQueueJobError(error: unknown): QueueJobError {
+  if (error instanceof Error) {
+    const maybeCode = readString((error as Error & { code?: unknown }).code)
+    return QueueJobErrorSchema.parse(
+      compactRecord({
+        name: error.name || undefined,
+        message: truncateText(error.message || 'Unknown error', 5_000),
+        stack: typeof error.stack === 'string' ? truncateText(error.stack, 20_000) : undefined,
+        code: maybeCode,
+      }),
+    )
+  }
+
+  return QueueJobErrorSchema.parse({ message: truncateText(stringifyUnknown(error) ?? 'Unknown error', 5_000) })
+}
+
+function getBullmqJobId(job: TrackedBullJobLike): string {
+  const id = job.id
+  if (typeof id === 'string' && id.length > 0) return id
+  if (typeof id === 'number') return String(id)
+  throw new Error(`BullMQ job for queue "${job.queueName}" is missing an id.`)
+}
+
+function getQueueJobRecordId(job: TrackedBullJobLike): RecordId {
+  return buildDeterministicRecordId(TABLES.QUEUE_JOB, `${job.queueName}:${getBullmqJobId(job)}`)
+}
+
+function getQueueJobAttemptRecordId(job: TrackedBullJobLike, attemptNumber: number): RecordId {
+  return buildDeterministicRecordId(
+    TABLES.QUEUE_JOB_ATTEMPT,
+    `${job.queueName}:${getBullmqJobId(job)}:${attemptNumber}`,
+  )
+}
+
+function resolveAttemptNumber(job: TrackedBullJobLike): number {
+  return (job.attemptsMade ?? 0) + 1
+}
+
+function extractJobContext(data: unknown): Record<string, unknown> | undefined {
+  const record = readRecord(data)
+  if (!record) return undefined
+
+  const context = compactRecord({
+    organizationId: readStringField(record, 'organizationId') ?? readStringField(record, 'orgId'),
+    workstreamId: readStringField(record, 'workstreamId'),
+    userId: readStringField(record, 'userId'),
+    agentId: readStringField(record, 'agentId'),
+    sourceId: readStringField(record, 'sourceId'),
+    runId: readStringField(record, 'runId'),
+    nodeId: readStringField(record, 'nodeId'),
+    scheduleId: readStringField(record, 'scheduleId'),
+    scopeId: readStringField(record, 'scopeId'),
+    autonomousJobId: readStringField(record, 'autonomousJobId'),
+    autonomousJobRunId: readStringField(record, 'autonomousJobRunId'),
+  })
+
+  return Object.keys(context).length > 0 ? context : undefined
+}
+
+function readDeduplicationId(job: TrackedBullJobLike): string | undefined {
+  const opts = readRecord(job.opts)
+  const deduplication = opts ? readRecord(opts.deduplication) : null
+  return deduplication ? readStringField(deduplication, 'id') : undefined
+}
+
+function readMaxAttempts(job: TrackedBullJobLike): number | undefined {
+  const opts = readRecord(job.opts)
+  const attempts = opts?.attempts
+  return typeof attempts === 'number' && Number.isInteger(attempts) && attempts >= 0 ? attempts : undefined
+}
+
+function getQueuedStatus(job: TrackedBullJobLike): QueueJobStatus {
+  const opts = readRecord(job.opts)
+  const delay = opts?.delay
+  return typeof delay === 'number' && delay > 0 ? 'delayed' : 'waiting'
+}
+
+class QueueJobService {
+  getQueueJobId(queueName: string, bullmqJobId: string): string {
+    return recordIdToString(
+      buildDeterministicRecordId(TABLES.QUEUE_JOB, `${queueName}:${bullmqJobId}`),
+      TABLES.QUEUE_JOB,
+    )
+  }
+
+  async recordEnqueued(job: TrackedBullJobLike, context?: Record<string, unknown>): Promise<string> {
+    await databaseService.connect()
+
+    const queueJobId = getQueueJobRecordId(job)
+    const queuedAt = typeof job.timestamp === 'number' ? new Date(job.timestamp) : new Date()
+    const mergedContext = compactRecord({ ...extractJobContext(job.data), ...context })
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB,
+      queueJobId,
+      compactRecord({
+        queueName: job.queueName,
+        jobName: job.name,
+        bullmqJobId: getBullmqJobId(job),
+        status: getQueuedStatus(job),
+        data: wrapFlexibleValue(job.data),
+        options: sanitizeQueueValue(job.opts) as Record<string, unknown>,
+        context: Object.keys(mergedContext).length > 0 ? sanitizeQueueValue(mergedContext) : undefined,
+        deduplicationId: readDeduplicationId(job),
+        maxAttempts: readMaxAttempts(job),
+        queuedAt,
+      }),
+      QueueJobRowSchema,
+    )
+
+    return recordIdToString(queueJobId, TABLES.QUEUE_JOB)
+  }
+
+  async markAttemptStarted(job: TrackedBullJobLike): Promise<string> {
+    await databaseService.connect()
+
+    const attemptNumber = resolveAttemptNumber(job)
+    const queueJobId = getQueueJobRecordId(job)
+    const startedAt = new Date()
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB,
+      queueJobId,
+      compactRecord({
+        queueName: job.queueName,
+        jobName: job.name,
+        bullmqJobId: getBullmqJobId(job),
+        status: 'active',
+        data: wrapFlexibleValue(job.data),
+        options: sanitizeQueueValue(job.opts) as Record<string, unknown>,
+        context: sanitizeQueueValue(extractJobContext(job.data)) as Record<string, unknown> | undefined,
+        deduplicationId: readDeduplicationId(job),
+        maxAttempts: readMaxAttempts(job),
+        attemptCount: attemptNumber,
+        queuedAt: typeof job.timestamp === 'number' ? new Date(job.timestamp) : startedAt,
+        startedAt,
+      }),
+      QueueJobRowSchema,
+    )
+
+    const attemptId = getQueueJobAttemptRecordId(job, attemptNumber)
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB_ATTEMPT,
+      attemptId,
+      { queueJobId, attemptNumber, status: 'active', startedAt },
+      QueueJobAttemptRowSchema,
+    )
+
+    return recordIdToString(queueJobId, TABLES.QUEUE_JOB)
+  }
+
+  async markAttemptCompleted(job: TrackedBullJobLike, result: unknown): Promise<void> {
+    await databaseService.connect()
+
+    const attemptNumber = resolveAttemptNumber(job)
+    const queueJobId = getQueueJobRecordId(job)
+    const attemptId = getQueueJobAttemptRecordId(job, attemptNumber)
+    const completedAt = new Date()
+    const existingAttempt = await databaseService.findOne(
+      TABLES.QUEUE_JOB_ATTEMPT,
+      { id: attemptId },
+      QueueJobAttemptRowSchema,
+    )
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB_ATTEMPT,
+      attemptId,
+      compactRecord({
+        queueJobId,
+        attemptNumber,
+        status: 'completed',
+        result: wrapFlexibleValue(result),
+        startedAt: existingAttempt?.startedAt ?? completedAt,
+        completedAt,
+        durationMs: existingAttempt ? Math.max(0, completedAt.getTime() - existingAttempt.startedAt.getTime()) : 0,
+      }),
+      QueueJobAttemptRowSchema,
+    )
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB,
+      queueJobId,
+      compactRecord({
+        queueName: job.queueName,
+        jobName: job.name,
+        bullmqJobId: getBullmqJobId(job),
+        status: 'completed',
+        data: wrapFlexibleValue(job.data),
+        options: sanitizeQueueValue(job.opts) as Record<string, unknown>,
+        context: sanitizeQueueValue(extractJobContext(job.data)) as Record<string, unknown> | undefined,
+        deduplicationId: readDeduplicationId(job),
+        maxAttempts: readMaxAttempts(job),
+        attemptCount: attemptNumber,
+        queuedAt: typeof job.timestamp === 'number' ? new Date(job.timestamp) : completedAt,
+        completedAt,
+        result: wrapFlexibleValue(result),
+        lastError: undefined,
+      }),
+      QueueJobRowSchema,
+    )
+  }
+
+  async markAttemptFailed(job: TrackedBullJobLike, error: unknown): Promise<void> {
+    await databaseService.connect()
+
+    const attemptNumber = resolveAttemptNumber(job)
+    const queueJobId = getQueueJobRecordId(job)
+    const attemptId = getQueueJobAttemptRecordId(job, attemptNumber)
+    const failedAt = new Date()
+    const existingAttempt = await databaseService.findOne(
+      TABLES.QUEUE_JOB_ATTEMPT,
+      { id: attemptId },
+      QueueJobAttemptRowSchema,
+    )
+    const normalizedError = toQueueJobError(error)
+    const maxAttempts = readMaxAttempts(job)
+    const terminal = typeof maxAttempts === 'number' ? attemptNumber >= maxAttempts : true
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB_ATTEMPT,
+      attemptId,
+      compactRecord({
+        queueJobId,
+        attemptNumber,
+        status: 'failed',
+        error: normalizedError,
+        startedAt: existingAttempt?.startedAt ?? failedAt,
+        completedAt: failedAt,
+        durationMs: existingAttempt ? Math.max(0, failedAt.getTime() - existingAttempt.startedAt.getTime()) : 0,
+      }),
+      QueueJobAttemptRowSchema,
+    )
+
+    await databaseService.upsert(
+      TABLES.QUEUE_JOB,
+      queueJobId,
+      compactRecord({
+        queueName: job.queueName,
+        jobName: job.name,
+        bullmqJobId: getBullmqJobId(job),
+        status: terminal ? 'failed' : 'waiting',
+        data: wrapFlexibleValue(job.data),
+        options: sanitizeQueueValue(job.opts) as Record<string, unknown>,
+        context: sanitizeQueueValue(extractJobContext(job.data)) as Record<string, unknown> | undefined,
+        deduplicationId: readDeduplicationId(job),
+        maxAttempts,
+        attemptCount: attemptNumber,
+        queuedAt: typeof job.timestamp === 'number' ? new Date(job.timestamp) : failedAt,
+        failedAt: terminal ? failedAt : undefined,
+        lastError: normalizedError,
+      }),
+      QueueJobRowSchema,
+    )
+  }
+}
+
+export const queueJobService = new QueueJobService()

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

@@ -6,7 +6,7 @@ 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 { ensureRecordId, recordIdToString } from '../db/record-id'
 import type { RecordIdRef } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
@@ -32,6 +32,10 @@ function toWorkstreamMessageRowId(workstreamId: RecordIdRef, messageId: string):
   return new RecordId(TABLES.WORKSTREAM_MESSAGE, digest)
 }
 
+function toWorkstreamRef(workstreamId: RecordIdRef): RecordId {
+  return ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+}
+
 function toChatMessage(row: WorkstreamMessageRow): ChatMessage {
   const rowCreatedAt = requireTimestamp(row.createdAt)
   const metadata = withCreatedAtMetadata(parseRowMetadata(row.metadata), rowCreatedAt)
@@ -65,7 +69,7 @@ const workstreamPaginationConfig: CursorPaginationConfig = {
 
 class WorkstreamMessageService {
   async upsertMessages(params: { workstreamId: RecordIdRef; messages: ChatMessage[] }): Promise<void> {
-    const workstreamId = params.workstreamId
+    const workstreamId = toWorkstreamRef(params.workstreamId)
 
     const upsertPromises = params.messages.map(async (message) => {
       const messageId = message.id.trim()
@@ -108,9 +112,10 @@ class WorkstreamMessageService {
   }
 
   async listMessages(workstreamId: RecordIdRef): Promise<ChatMessage[]> {
+    const workstreamRef = toWorkstreamRef(workstreamId)
     const rows = await databaseService.query<unknown>(surql`
       SELECT * FROM workstreamMessage
-      WHERE workstreamId = ${workstreamId}
+      WHERE workstreamId = ${workstreamRef}
       ORDER BY createdAt ASC, id ASC
     `)
 
@@ -122,22 +127,24 @@ class WorkstreamMessageService {
     take: number
     beforeMessageId?: string
   }): Promise<MessageHistoryPage> {
+    const workstreamRef = toWorkstreamRef(params.workstreamId)
     return listMessageHistoryPage(workstreamPaginationConfig, {
-      parentId: params.workstreamId,
+      parentId: workstreamRef,
       take: params.take,
       beforeMessageId: params.beforeMessageId,
     })
   }
 
   async listMessagesAfterCursor(workstreamId: RecordIdRef, afterMessageId?: string): Promise<ChatMessage[]> {
+    const workstreamRef = toWorkstreamRef(workstreamId)
     const cursorMessageId = afterMessageId?.trim()
     if (!cursorMessageId) {
-      return this.listMessages(workstreamId)
+      return this.listMessages(workstreamRef)
     }
 
     const cursorRow = await databaseService.findOne(
       TABLES.WORKSTREAM_MESSAGE,
-      { workstreamId, messageId: cursorMessageId },
+      { workstreamId: workstreamRef, messageId: cursorMessageId },
       CursorRowSchema,
     )
 
@@ -146,10 +153,10 @@ class WorkstreamMessageService {
     }
 
     const cursorCreatedAt = cursorRow.createdAt
-    const cursorId = toWorkstreamMessageRowId(workstreamId, cursorMessageId)
+    const cursorId = toWorkstreamMessageRowId(workstreamRef, cursorMessageId)
     const rows = await databaseService.query<unknown>(surql`
       SELECT * FROM workstreamMessage
-      WHERE workstreamId = ${workstreamId}
+      WHERE workstreamId = ${workstreamRef}
         AND (
           createdAt > ${cursorCreatedAt}
           OR (createdAt = ${cursorCreatedAt} AND id > ${cursorId})
@@ -161,9 +168,10 @@ class WorkstreamMessageService {
   }
 
   async listRecentMessages(workstreamId: RecordIdRef, limit: number): Promise<ChatMessage[]> {
+    const workstreamRef = toWorkstreamRef(workstreamId)
     const rows = await databaseService.query<unknown>(surql`
       SELECT * FROM workstreamMessage
-      WHERE workstreamId = ${workstreamId}
+      WHERE workstreamId = ${workstreamRef}
       ORDER BY createdAt DESC, id DESC
       LIMIT ${Math.max(1, limit)}
     `)
@@ -183,7 +191,7 @@ class WorkstreamMessageService {
     const normalizedQuery = params.query.trim().toLowerCase()
     if (!normalizedQuery) return []
 
-    const messages = await this.listMessages(params.workstreamId)
+    const messages = await this.listMessages(toWorkstreamRef(params.workstreamId))
     return messages
       .filter((message) => message.role === params.role)
       .map((message) => ({
@@ -204,6 +212,7 @@ class WorkstreamMessageService {
     workstreamId: RecordIdRef
     content: string
   }): Promise<ChatMessage> {
+    const workstreamRef = toWorkstreamRef(params.workstreamId)
     const message: ChatMessage = {
       id: toMessageId(params.messageId),
       role: 'user',
@@ -211,7 +220,7 @@ class WorkstreamMessageService {
       metadata: { createdAt: Date.now() },
     }
 
-    await this.upsertMessages({ workstreamId: params.workstreamId, messages: [message] })
+    await this.upsertMessages({ workstreamId: workstreamRef, messages: [message] })
     return message
   }
 
@@ -221,6 +230,7 @@ class WorkstreamMessageService {
     parts: ChatMessage['parts']
     metadata?: ChatMessage['metadata']
   }): Promise<ChatMessage> {
+    const workstreamRef = toWorkstreamRef(params.workstreamId)
     const message: ChatMessage = {
       id: toMessageId(params.messageId),
       role: 'assistant',
@@ -228,7 +238,7 @@ class WorkstreamMessageService {
       metadata: withCreatedAtMetadata(params.metadata, Date.now()),
     }
 
-    await this.upsertMessages({ workstreamId: params.workstreamId, messages: [message] })
+    await this.upsertMessages({ workstreamId: workstreamRef, messages: [message] })
     return message
   }
 
@@ -237,9 +247,10 @@ class WorkstreamMessageService {
     agentId: string
     text: string
   }): Promise<void> {
+    const workstreamRef = toWorkstreamRef(params.workstreamId)
     const existingRow = await databaseService.findOne(
       TABLES.WORKSTREAM_MESSAGE,
-      { workstreamId: params.workstreamId },
+      { workstreamId: workstreamRef },
       WorkstreamMessageExistingRowSchema,
     )
     if (existingRow) return
@@ -248,7 +259,7 @@ class WorkstreamMessageService {
     if (!messageText) return
 
     await this.upsertMessages({
-      workstreamId: params.workstreamId,
+      workstreamId: workstreamRef,
       messages: [
         {
           id: Bun.randomUUIDv7(),

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

@@ -10,7 +10,7 @@ import {
 } from '../system-agents/title-generator.agent'
 import { workstreamService } from './workstream.service'
 
-const WORKSTREAM_TITLE_TIMEOUT_MS = 5_000
+const WORKSTREAM_TITLE_TIMEOUT_MS = 30_000
 
 class WorkstreamTitleService {
   helperRuntime = createHelperModelRuntime()

package/src/services/workstream-turn-preparation.service.ts

@@ -189,6 +189,7 @@ export interface WorkstreamTurnParams {
   orgRef: RecordIdRef
   userRef: RecordIdRef
   userName?: string | null
+  agentIdOverride?: string
   inputMessage: ChatMessage
   skipInputMessagePersistence?: boolean
   abortSignal?: AbortSignal
@@ -212,6 +213,7 @@ type WorkstreamRunCoreParams = {
   orgRef: RecordIdRef
   userRef: RecordIdRef
   userName?: string | null
+  agentIdOverride?: string
   abortSignal?: AbortSignal
   streamId?: string
 } & (
@@ -222,7 +224,12 @@ type WorkstreamRunCoreParams = {
 
 interface PreparedWorkstreamTurn {
   originalMessages: ChatMessage[]
-  run: (writer?: UIMessageStreamWriter<ChatMessage>) => Promise<void>
+  run: (writer?: UIMessageStreamWriter<ChatMessage>) => Promise<PreparedWorkstreamTurnResult>
+}
+
+export interface PreparedWorkstreamTurnResult {
+  inputMessageId?: string
+  assistantMessages: ChatMessage[]
 }
 
 function upsertChatHistoryMessage(messages: ChatMessage[], nextMessage: ChatMessage): ChatMessage[] {
@@ -632,7 +639,10 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   const workstreamRecord = await waitForWorkstreamCompactionIfNeeded(workstreamRef)
   timer.step('compaction-gate')
   if (toOptionalTrimmedString(workstreamRecord.activeRunId)) {
-    throw new WorkstreamTurnError('A chat run is already active.', 409)
+    const clearedStaleRun = await workstreamService.clearStaleActiveRunIfMissingFromRegistry(workstreamRef)
+    if (!clearedStaleRun) {
+      throw new WorkstreamTurnError('A chat run is already active.', 409)
+    }
   }
 
   if (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn') {
@@ -730,7 +740,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     workstream.core && workstream.coreType ? getCoreWorkstreamProfile(workstream.coreType) : null
   const defaultLeadAgentId = getLeadAgentId()
   const visibleWorkstreamAgentId =
-    workstream.mode === 'direct' ? workstream.agentId : (coreWorkstreamProfile?.config.agentId ?? defaultLeadAgentId)
+    params.agentIdOverride ??
+    (workstream.mode === 'direct' ? workstream.agentId : (coreWorkstreamProfile?.config.agentId ?? defaultLeadAgentId))
   const coreInstructionSections = coreWorkstreamProfile ? [coreWorkstreamProfile.instructions] : undefined
   const getLinearInstallationByOrgId = getPluginService([
     'linear',
@@ -936,7 +947,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   return {
     originalMessages,
     run: async (writer?: UIMessageStreamWriter<ChatMessage>) => {
-      const executeRun = async () => {
+      const executeRun = async (): Promise<PreparedWorkstreamTurnResult | void> => {
         const runTimer = lotaDebugLogger.timer('run')
         const serverRunId = Bun.randomUUIDv7()
         const runAbort = createServerRunAbortController(params.abortSignal)
@@ -1064,7 +1075,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
           // Execution-plan approval continuations mutate plan state and persist the approval message,
           // but they do not begin a new visible agent turn.
           if (params.kind === 'approvalContinuation') {
-            return
+            return { inputMessageId: referenceUserMessage?.id, assistantMessages: [] }
           }
 
           const consultSpecialistTool = createTool({
@@ -1322,7 +1333,12 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
         }
       }
 
-      await executeRun()
+      const runResult = await executeRun()
+      if (runResult) {
+        return runResult
+      }
+
+      return { inputMessageId: referenceUserMessage?.id, assistantMessages: [...allAssistantMessages] }
     },
   }
 }

package/src/services/workstream-turn.ts

@@ -5,10 +5,15 @@ import { lotaDebugLogger } from '../config/debug-logger'
 import { hasApprovalRespondedParts, isApprovalContinuationRequest } from '../runtime/approval-continuation'
 import { wrapResponseWithKeepalive } from '../utils/sse-keepalive'
 import { prepareWorkstreamRunCore } from './workstream-turn-preparation.service'
-import type { WorkstreamTurnParams, WorkstreamApprovalContinuationParams } from './workstream-turn-preparation.service'
+import type {
+  PreparedWorkstreamTurnResult,
+  WorkstreamApprovalContinuationParams,
+  WorkstreamTurnParams,
+} from './workstream-turn-preparation.service'
 
 export { hasApprovalRespondedParts, isApprovalContinuationRequest }
 export { wrapResponseWithKeepalive }
+export type { PreparedWorkstreamTurnResult }
 
 export async function createWorkstreamApprovalContinuationStream(params: WorkstreamApprovalContinuationParams) {
   const timer = lotaDebugLogger.timer('turn:approval-continuation')
@@ -55,10 +60,13 @@ export async function createWorkstreamTurnStream(params: WorkstreamTurnParams) {
   })
 }
 
-export async function runWorkstreamTurnInBackground(params: WorkstreamTurnParams): Promise<void> {
+export async function runWorkstreamTurnInBackground(
+  params: WorkstreamTurnParams,
+): Promise<PreparedWorkstreamTurnResult> {
   const timer = lotaDebugLogger.timer('turn:background')
   const prepared = await prepareWorkstreamRunCore({ ...params, kind: 'userTurn' })
   timer.step('prepare')
-  await prepared.run()
+  const result = await prepared.run()
   timer.step('run')
+  return result
 }