@lota-sdk/core 0.4.0 → 0.4.2

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

@@ -90,7 +90,11 @@ function serializeArtifact(artifact: PlanArtifactRecord): SerializablePlanArtifa
     pointer: artifact.pointer,
     schemaRef: artifact.schemaRef,
     description: artifact.description,
+    content: artifact.content,
     payload: artifact.payload,
+    publishedArtifactId: artifact.publishedArtifactId
+      ? recordIdToString(artifact.publishedArtifactId, TABLES.ARTIFACT)
+      : undefined,
     createdAt: toIsoDateTimeString(artifact.createdAt),
   }
 }

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

@@ -8,6 +8,17 @@ import { TABLES } from '../db/tables'
 import { executionPlanService } from './execution-plan.service'
 
 class PlanTemplateService {
+  private resolveSourceIdentity(params: { source?: 'user' | 'playbook' | 'system'; sourceRef?: string }) {
+    const source = params.source ?? 'user'
+    const sourceRef = params.sourceRef?.trim()
+
+    if (source !== 'user' && !sourceRef) {
+      throw new Error(`sourceRef is required when source is "${source}".`)
+    }
+
+    return { source, sourceRef }
+  }
+
   async createTemplate(params: {
     organizationId: RecordIdInput
     name: string
@@ -18,6 +29,7 @@ class PlanTemplateService {
     sourceRef?: string
   }): Promise<PlanTemplateRecord> {
     const now = new Date()
+    const identity = this.resolveSourceIdentity({ source: params.source, sourceRef: params.sourceRef })
     return databaseService.create(
       TABLES.PLAN_TEMPLATE,
       {
@@ -26,8 +38,8 @@ class PlanTemplateService {
         ...(params.description ? { description: params.description } : {}),
         draft: params.draft,
         tags: params.tags ?? [],
-        source: params.source ?? 'user',
-        ...(params.sourceRef ? { sourceRef: params.sourceRef } : {}),
+        source: identity.source,
+        ...(identity.sourceRef ? { sourceRef: identity.sourceRef } : {}),
         createdAt: now,
       },
       PlanTemplateRecordSchema,
@@ -42,6 +54,22 @@ class PlanTemplateService {
     )
   }
 
+  async getTemplateBySourceRef(params: {
+    organizationId: RecordIdInput
+    source: 'user' | 'playbook' | 'system'
+    sourceRef: string
+  }): Promise<PlanTemplateRecord | null> {
+    return await databaseService.findOne(
+      TABLES.PLAN_TEMPLATE,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        source: params.source,
+        sourceRef: params.sourceRef,
+      },
+      PlanTemplateRecordSchema,
+    )
+  }
+
   async listTemplates(
     organizationId: RecordIdInput,
     params?: { tags?: string[]; source?: string },
@@ -80,6 +108,33 @@ class PlanTemplateService {
     return updated
   }
 
+  async upsertTemplateBySourceRef(params: {
+    organizationId: RecordIdInput
+    name: string
+    description?: string
+    draft: PlanDraft
+    tags?: string[]
+    source: 'user' | 'playbook' | 'system'
+    sourceRef: string
+  }): Promise<PlanTemplateRecord> {
+    const existing = await this.getTemplateBySourceRef({
+      organizationId: params.organizationId,
+      source: params.source,
+      sourceRef: params.sourceRef,
+    })
+
+    if (!existing) {
+      return await this.createTemplate(params)
+    }
+
+    return await this.updateTemplate(existing.id, {
+      name: params.name,
+      description: params.description,
+      draft: params.draft,
+      tags: params.tags ?? [],
+    })
+  }
+
   async deleteTemplate(templateId: RecordIdInput): Promise<void> {
     await databaseService.deleteById(TABLES.PLAN_TEMPLATE, ensureRecordId(templateId, TABLES.PLAN_TEMPLATE))
   }

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

@@ -510,7 +510,7 @@ class PlanValidatorService {
     // Validate cross-plan dependency cycles
     if (draft.dependencies && draft.dependencies.length > 0) {
       const cycleIssues = planCoordinationService.validateNoCycles([
-        { title: draft.title, dependencies: draft.dependencies },
+        { id: draft.title, title: draft.title, dependencies: draft.dependencies },
       ])
       blocking.push(...cycleIssues)
     }

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

@@ -50,6 +50,10 @@ const QueueJobAttemptRowSchema = z.object({
   updatedAt: z.coerce.date(),
 })
 
+const PERSISTENCE_MAX_ATTEMPTS = 4
+const PERSISTENCE_RETRY_BASE_DELAY_MS = 25
+const PERSISTENCE_RETRY_JITTER_MS = 25
+
 export interface TrackedBullJobLike {
   queueName: string
   id?: string | number
@@ -174,7 +178,43 @@ function getQueuedStatus(job: TrackedBullJobLike): QueueJobStatus {
   return typeof delay === 'number' && delay > 0 ? 'delayed' : 'waiting'
 }
 
+function isRetriablePersistenceConflict(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+
+  const message = error.message.toLowerCase()
+  return (
+    message.includes('transaction conflict') ||
+    message.includes('transaction read conflict') ||
+    message.includes('read or write conflict') ||
+    message.includes('write conflict') ||
+    message.includes('resource busy') ||
+    message.includes('this transaction can be retried')
+  )
+}
+
 class QueueJobService {
+  private async withPersistenceRetry<T>(work: () => Promise<T>): Promise<T> {
+    let lastError: unknown = null
+
+    for (let attempt = 1; attempt <= PERSISTENCE_MAX_ATTEMPTS; attempt += 1) {
+      try {
+        return await work()
+      } catch (error) {
+        lastError = error
+        const hasMoreAttempts = attempt < PERSISTENCE_MAX_ATTEMPTS
+        if (!isRetriablePersistenceConflict(error) || !hasMoreAttempts) {
+          throw error
+        }
+
+        const backoffMs =
+          PERSISTENCE_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * PERSISTENCE_RETRY_JITTER_MS)
+        await Bun.sleep(backoffMs)
+      }
+    }
+
+    throw lastError instanceof Error ? lastError : new Error('Queue job persistence retry exhausted')
+  }
+
   getQueueJobId(queueName: string, bullmqJobId: string): string {
     return recordIdToString(
       buildDeterministicRecordId(TABLES.QUEUE_JOB, `${queueName}:${bullmqJobId}`),
@@ -184,172 +224,178 @@ class QueueJobService {
 
   async recordEnqueued(job: TrackedBullJobLike, context?: Record<string, unknown>): Promise<string> {
     await databaseService.connect()
+    return this.withPersistenceRetry(async () => {
+      const queueJobId = getQueueJobRecordId(job)
+      const queuedAt = typeof job.timestamp === 'number' ? new Date(job.timestamp) : new Date()
+      const mergedContext = compactRecord({ ...extractJobContext(job.data), ...context })
 
-    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)
+      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)
+    return this.withPersistenceRetry(async () => {
+      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({
+    await this.withPersistenceRetry(async () => {
+      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,
-        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,
-    )
+        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({
+    await this.withPersistenceRetry(async () => {
+      const existingAttempt = await databaseService.findOne(
+        TABLES.QUEUE_JOB_ATTEMPT,
+        { id: attemptId },
+        QueueJobAttemptRowSchema,
+      )
+
+      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,
-        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,
-    )
+        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,
+      )
+    })
   }
 }
 

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

@@ -41,6 +41,7 @@ import { runPostTurnSideEffects } from '../runtime/post-turn-side-effects'
 import { getRuntimeAdapters, getToolProviders, getTurnHooks } from '../runtime/runtime-extensions'
 import {
   asRecord,
+  collectCompletedConsultTeamMessages,
   collectToolOutputErrors,
   extractMessageText,
   readInstructionSections,
@@ -767,17 +768,44 @@ export async function prepareThreadRunCore(params: ThreadRunCoreParams): Promise
           ) => {
             throwIfRunAborted()
 
-            const committed = withMessageCreatedAt(
-              {
-                ...response,
-                metadata: { ...response.metadata, ...buildAgentMetadataPatch(agentId, agentName), ...metadataPatch },
+            const toCommittedAssistantMessage = (
+              message: ChatMessage,
+              resolvedAgentId: string,
+              resolvedAgentName: string,
+              patch?: NonNullable<MessageMetadata>,
+            ) =>
+              withMessageCreatedAt(
+                {
+                  ...message,
+                  metadata: {
+                    ...message.metadata,
+                    ...buildAgentMetadataPatch(resolvedAgentId, resolvedAgentName),
+                    ...patch,
+                  },
+                },
+                toTimestamp(message.metadata?.createdAt) ?? Date.now(),
+              )
+
+            const committedConsultMessages = collectCompletedConsultTeamMessages({ responseMessage: response }).flatMap(
+              (consultMessage) => {
+                const consultAgentId = readOptionalString(consultMessage.metadata?.agentId)
+                const consultAgentName = readOptionalString(consultMessage.metadata?.agentName)
+                if (!consultAgentId || !consultAgentName) {
+                  return []
+                }
+
+                return [toCommittedAssistantMessage(consultMessage, consultAgentId, consultAgentName)]
               },
-              Date.now(),
             )
 
-            await threadMessageService.upsertMessages({ threadId: threadRef, messages: [committed] })
-            currentMessages = upsertChatHistoryMessage(currentMessages, committed)
-            allAssistantMessages = upsertChatHistoryMessage(allAssistantMessages, committed)
+            const committed = toCommittedAssistantMessage(response, agentId, agentName, metadataPatch)
+            const messagesToPersist = [...committedConsultMessages, committed]
+
+            await threadMessageService.upsertMessages({ threadId: threadRef, messages: messagesToPersist })
+            for (const persistedMessage of messagesToPersist) {
+              currentMessages = upsertChatHistoryMessage(currentMessages, persistedMessage)
+              allAssistantMessages = upsertChatHistoryMessage(allAssistantMessages, persistedMessage)
+            }
             throwIfRunAborted()
 
             return committed

package/src/services/thread-turn.ts

@@ -121,7 +121,11 @@ export async function triggerPlanNodeTurn(params: {
       name: artifact.name,
       kind: artifact.kind,
       ...(artifact.description ? { description: artifact.description } : {}),
+      ...(artifact.content !== undefined ? { content: artifact.content } : {}),
       ...(artifact.payload !== undefined ? { payload: artifact.payload } : {}),
+      ...(artifact.publishedArtifactId
+        ? { publishedArtifactId: recordIdToString(artifact.publishedArtifactId, TABLES.ARTIFACT) }
+        : {}),
     }))
   const upstreamNodeSpecs = new Map(
     (await planRunService.listNodeSpecs(spec.id)).map((upstreamNodeSpec) => [

package/src/storage/generated-document-storage.service.ts

@@ -52,6 +52,14 @@ class GeneratedDocumentStorageService {
     await this.client.file(storageKey).write(params.content, { type: params.mediaType })
     return { storageKey, sizeBytes }
   }
+
+  async readTextArtifact(storageKey: string): Promise<string> {
+    return await this.client.file(storageKey).text()
+  }
+
+  async deleteTextArtifact(storageKey: string): Promise<void> {
+    await this.client.file(storageKey).delete()
+  }
 }
 
 export const generatedDocumentStorageService = new GeneratedDocumentStorageService()