@lota-sdk/core 0.1.15 → 0.1.16

package/src/create-runtime.ts

@@ -15,9 +15,11 @@ import { TABLES } from './db/tables'
 import type { RedisConnectionManager } from './redis/connection'
 import { createRedisConnectionManager } from './redis/connection'
 import { setRedisConnectionManager } from './redis/index'
+import { closeSharedSubscriber } from './redis/stream-context'
 import type { isApprovalContinuationRequest } from './runtime/approval-continuation'
 import { routeWorkstreamChatMessages } from './runtime/chat-request-routing'
-import type { LotaPlugin } from './runtime/plugin-types'
+import { configureGraphDesigner } from './runtime/graph-designer'
+import type { LotaPlugin, SystemNodeExecutor } from './runtime/plugin-types'
 import { configureRuntimeConfig, LOTA_RUNTIME_ENV_KEYS, parseLotaRuntimeConfig } from './runtime/runtime-config'
 import type { LotaRuntimeConfig, ResolvedLotaRuntimeConfig } from './runtime/runtime-config'
 import { configureRuntimeExtensions } from './runtime/runtime-extensions'
@@ -25,22 +27,27 @@ import type { LotaRuntimeWorkers } from './runtime/runtime-worker-registry'
 import { buildRuntimeWorkerRegistry } from './runtime/runtime-worker-registry'
 import type { attachmentService } from './services/attachment.service'
 import { attachmentService as attachmentServiceSingleton } from './services/attachment.service'
+import { coordinationRegistryService as coordinationRegistryServiceSingleton } from './services/coordination-registry.service'
 import type { documentChunkService } from './services/document-chunk.service'
 import { documentChunkService as documentChunkServiceSingleton } from './services/document-chunk.service'
+import { domainAgentExecutorService } from './services/domain-agent-executor.service'
 import type { executionPlanService } from './services/execution-plan.service'
 import { executionPlanService as executionPlanServiceSingleton } from './services/execution-plan.service'
 import type { memoryService } from './services/memory.service'
 import { memoryService as memoryServiceSingleton } from './services/memory.service'
 import type { verifyMutatingApproval } from './services/mutating-approval.service'
 import { verifyMutatingApproval as verifyMutatingApprovalSingleton } from './services/mutating-approval.service'
+import { configureNotificationService } from './services/notification.service'
 import type { organizationMemberService } from './services/organization-member.service'
 import { organizationMemberService as organizationMemberServiceSingleton } from './services/organization-member.service'
 import type { organizationService } from './services/organization.service'
 import { organizationService as organizationServiceSingleton } from './services/organization.service'
+import { playbookRegistryService } from './services/playbook-registry.service'
 import type { recentActivityTitleService } from './services/recent-activity-title.service'
 import { recentActivityTitleService as recentActivityTitleServiceSingleton } from './services/recent-activity-title.service'
 import type { recentActivityService } from './services/recent-activity.service'
 import { recentActivityService as recentActivityServiceSingleton } from './services/recent-activity.service'
+import { getBuiltInSystemExecutors } from './services/system-executor.service'
 import type { userService } from './services/user.service'
 import { userService as userServiceSingleton } from './services/user.service'
 import type { workstreamMessageService } from './services/workstream-message.service'
@@ -75,6 +82,24 @@ type UnarchiveSdkWorkstream = (
   status?: 'regular',
 ) => ReturnType<typeof workstreamServiceSingleton.updateStatus>
 
+let activeRuntimeToken: symbol | null = null
+
+function claimRuntimeToken(): symbol {
+  if (activeRuntimeToken) {
+    throw new Error('createLotaRuntime() is process-scoped. Disconnect the active runtime before creating another one.')
+  }
+
+  const token = Symbol('lota-runtime')
+  activeRuntimeToken = token
+  return token
+}
+
+function releaseRuntimeToken(token: symbol) {
+  if (activeRuntimeToken === token) {
+    activeRuntimeToken = null
+  }
+}
+
 export interface LotaRuntime {
   services: {
     database: SurrealDBService
@@ -99,6 +124,7 @@ export interface LotaRuntime {
     createWorkstreamTurnStream: typeof createWorkstreamTurnStream
     isApprovalContinuationRequest: typeof isApprovalContinuationRequest
     runWorkstreamTurnInBackground: typeof runWorkstreamTurnInBackground
+    syncPlaybookTemplates: typeof playbookRegistryService.syncPlaybookTemplates
   }
   lota: {
     organizations: {
@@ -162,201 +188,241 @@ export interface LotaRuntime {
   contributions: { envKeys: readonly string[]; schemaFiles: Array<string | URL> }
   config: ResolvedLotaRuntimeConfig
   plugins: Record<string, LotaPlugin>
+  systemExecutors: Record<string, SystemNodeExecutor>
   connectPluginDatabases(): Promise<void>
   connect(): Promise<void>
   disconnect(): Promise<void>
 }
 
 export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntime> {
-  const resolvedConfig = parseLotaRuntimeConfig(config)
-  configureRuntimeConfig(resolvedConfig)
+  const runtimeToken = claimRuntimeToken()
 
-  await configureLotaLogger(resolvedConfig.logging.level)
+  try {
+    const resolvedConfig = parseLotaRuntimeConfig(config)
+    const systemExecutors = { ...getBuiltInSystemExecutors(), ...resolvedConfig.systemExecutors }
+    const runtimeConfig = { ...resolvedConfig, systemExecutors } satisfies ResolvedLotaRuntimeConfig
+    configureRuntimeConfig(runtimeConfig)
 
-  const db = new SurrealDBServiceClass({
-    url: resolvedConfig.database.url,
-    namespace: resolvedConfig.database.namespace,
-    database: LOTA_SDK_DATABASE_NAME,
-    username: resolvedConfig.database.username,
-    password: resolvedConfig.database.password,
-  })
-  setDatabaseService(db)
+    await configureLotaLogger(runtimeConfig.logging.level)
 
-  const redisManager = createRedisConnectionManager({ url: resolvedConfig.redis.url })
-  setRedisConnectionManager(redisManager)
-  configureEmbeddingCache(redisManager.getConnection(), resolvedConfig.memory.embeddingCacheTtlSeconds)
-  configureBackgroundProcessing(resolvedConfig.backgroundProcessing)
+    const db = new SurrealDBServiceClass({
+      url: runtimeConfig.database.url,
+      namespace: runtimeConfig.database.namespace,
+      database: LOTA_SDK_DATABASE_NAME,
+      username: runtimeConfig.database.username,
+      password: runtimeConfig.database.password,
+    })
+    setDatabaseService(db)
 
-  configureAgents({
-    roster: resolvedConfig.agents.roster,
-    leadAgentId: resolvedConfig.agents.leadAgentId,
-    displayNames: resolvedConfig.agents.displayNames,
-    shortDisplayNames: resolvedConfig.agents.shortDisplayNames,
-    teamConsultParticipants: resolvedConfig.agents.teamConsultParticipants,
-    getCoreWorkstreamProfile: resolvedConfig.agents.getCoreWorkstreamProfile,
-  })
-  configureAgentFactory({
-    createAgent: resolvedConfig.agents.createAgent,
-    buildAgentTools: resolvedConfig.agents.buildAgentTools,
-    getAgentRuntimeConfig: resolvedConfig.agents.getAgentRuntimeConfig,
-    pluginRuntime: resolvedConfig.pluginRuntime,
-  })
-  configureWorkstreams({ agentRoster: resolvedConfig.agents.roster, config: resolvedConfig.workstreams })
-  configureRuntimeExtensions({
-    adapters: resolvedConfig.runtimeAdapters,
-    turnHooks: resolvedConfig.turnHooks,
-    toolProviders: (resolvedConfig.toolProviders ?? {}) as never,
-    extraWorkers: resolvedConfig.extraWorkers,
-  })
+    const redisManager = createRedisConnectionManager({ url: runtimeConfig.redis.url })
+    setRedisConnectionManager(redisManager)
+    configureEmbeddingCache(redisManager.getConnection(), runtimeConfig.memory.embeddingCacheTtlSeconds)
+    configureBackgroundProcessing(runtimeConfig.backgroundProcessing)
 
-  const pluginRuntime = resolvedConfig.pluginRuntime ?? {}
-  const pluginContributions = Object.values(pluginRuntime).map((plugin) => plugin.contributions)
-  const schemaFiles = [...getBuiltInSchemaFiles(), ...(resolvedConfig.extraSchemaFiles ?? [])]
-  const hostContributionSchemaFiles = pluginContributions.flatMap((plugin) => plugin.schemaFiles)
-  const contributionEnvKeys = [...LOTA_RUNTIME_ENV_KEYS, ...pluginContributions.flatMap((plugin) => plugin.envKeys)]
-  const connectPluginDatabases = createPluginDatabaseConnector(pluginRuntime)
-  const workers = buildRuntimeWorkerRegistry(resolvedConfig.extraWorkers)
+    configureAgents({
+      roster: runtimeConfig.agents.roster,
+      leadAgentId: runtimeConfig.agents.leadAgentId,
+      displayNames: runtimeConfig.agents.displayNames,
+      shortDisplayNames: runtimeConfig.agents.shortDisplayNames,
+      teamConsultParticipants: runtimeConfig.agents.teamConsultParticipants,
+      getCoreWorkstreamProfile: runtimeConfig.agents.getCoreWorkstreamProfile,
+    })
+    configureAgentFactory({
+      createAgent: runtimeConfig.agents.createAgent,
+      buildAgentTools: runtimeConfig.agents.buildAgentTools,
+      getAgentRuntimeConfig: runtimeConfig.agents.getAgentRuntimeConfig,
+      pluginRuntime: runtimeConfig.pluginRuntime,
+    })
+    configureWorkstreams({ agentRoster: runtimeConfig.agents.roster, config: runtimeConfig.workstreams })
+    configureNotificationService(runtimeConfig.notificationService ?? null)
+    configureRuntimeExtensions({
+      adapters: runtimeConfig.runtimeAdapters,
+      turnHooks: runtimeConfig.turnHooks,
+      toolProviders: (runtimeConfig.toolProviders ?? {}) as never,
+      extraWorkers: runtimeConfig.extraWorkers,
+    })
 
-  const lota = {
-    organizations: {
-      create: organizationServiceSingleton.createOrganization.bind(organizationServiceSingleton),
-      upsert: organizationServiceSingleton.upsertOrganization.bind(organizationServiceSingleton),
-      get: organizationServiceSingleton.getOrganization.bind(organizationServiceSingleton),
-      list: organizationServiceSingleton.listOrganizations.bind(organizationServiceSingleton),
-      update: organizationServiceSingleton.updateOrganization.bind(organizationServiceSingleton),
-      delete: organizationServiceSingleton.deleteOrganization.bind(organizationServiceSingleton),
-    },
-    users: {
-      upsert: userServiceSingleton.upsertUser.bind(userServiceSingleton),
-      get: userServiceSingleton.getUser.bind(userServiceSingleton),
-      list: userServiceSingleton.listUsers.bind(userServiceSingleton),
-      update: userServiceSingleton.updateUser.bind(userServiceSingleton),
-      delete: userServiceSingleton.deleteUser.bind(userServiceSingleton),
-    },
-    memberships: {
-      add: organizationMemberServiceSingleton.addMembership.bind(organizationMemberServiceSingleton),
-      listForOrganization: organizationMemberServiceSingleton.listMembershipsForOrganization.bind(
-        organizationMemberServiceSingleton,
-      ),
-      listForUser: organizationMemberServiceSingleton.listMembershipsForUser.bind(organizationMemberServiceSingleton),
-      remove: organizationMemberServiceSingleton.removeMembership.bind(organizationMemberServiceSingleton),
-      isMember: organizationMemberServiceSingleton.isMember.bind(organizationMemberServiceSingleton),
-    },
-    workstreams: {
-      create: workstreamServiceSingleton.createWorkstream.bind(workstreamServiceSingleton),
-      list: workstreamServiceSingleton.listWorkstreams.bind(workstreamServiceSingleton),
-      get: workstreamServiceSingleton.getWorkstream.bind(workstreamServiceSingleton),
-      update: workstreamServiceSingleton.updateTitle.bind(workstreamServiceSingleton),
-      archive: async (workstreamId, status = 'archived') =>
-        await workstreamServiceSingleton.updateStatus(workstreamId, status),
-      unarchive: async (workstreamId, status = 'regular') =>
-        await workstreamServiceSingleton.updateStatus(workstreamId, status),
-      delete: workstreamServiceSingleton.deleteWorkstream.bind(workstreamServiceSingleton),
-      stop: workstreamServiceSingleton.stopActiveRun.bind(workstreamServiceSingleton),
-      listMessages: workstreamMessageServiceSingleton.listMessageHistoryPage.bind(workstreamMessageServiceSingleton),
-      getMessage: async ({ workstreamId, messageId }) => {
-        const messages = await workstreamMessageServiceSingleton.listMessages(
-          ensureRecordId(workstreamId, TABLES.WORKSTREAM),
-        )
-        const message = messages.find((candidate) => candidate.id === messageId)
-        if (!message) {
-          throw new Error(`Workstream message not found: ${messageId}`)
-        }
-        return message
-      },
-      sendMessage: async ({ workstreamId, organizationId, userId, userName, messages }) => {
-        const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-        const workstream = await workstreamServiceSingleton.getWorkstream(workstreamRef)
-        const routed = routeWorkstreamChatMessages(messages)
-        if (routed.kind !== 'turn') {
-          throw new Error(routed.kind === 'invalid' ? routed.message : 'Expected a user turn payload.')
-        }
+    const pluginRuntime = runtimeConfig.pluginRuntime ?? {}
+    domainAgentExecutorService.configure(pluginRuntime)
+    if (runtimeConfig.graphDesigner) {
+      configureGraphDesigner(runtimeConfig.graphDesigner)
+    }
+
+    for (const [pluginRef, plugin] of Object.entries(pluginRuntime)) {
+      const signals = plugin.contributions.signals
+      if (signals && signals.length > 0) {
+        coordinationRegistryServiceSingleton.register(pluginRef, [...signals])
+      }
+    }
+    coordinationRegistryServiceSingleton.validate()
+    // Collect playbook contributions early to fail fast on misconfiguration
+    playbookRegistryService.collectPlaybooks()
+
+    const pluginContributions = Object.values(pluginRuntime).map((plugin) => plugin.contributions)
+    const schemaFiles = [...getBuiltInSchemaFiles(), ...(runtimeConfig.extraSchemaFiles ?? [])]
+    const hostContributionSchemaFiles = pluginContributions.flatMap((plugin) => plugin.schemaFiles)
+    const contributionEnvKeys = [...LOTA_RUNTIME_ENV_KEYS, ...pluginContributions.flatMap((plugin) => plugin.envKeys)]
+    const connectPluginDatabases = createPluginDatabaseConnector(pluginRuntime)
+    const workers = buildRuntimeWorkerRegistry(runtimeConfig.extraWorkers)
 
-        return await createWorkstreamTurnStreamSingleton({
-          workstream,
-          workstreamRef,
-          orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
-          userRef: ensureRecordId(userId, TABLES.USER),
-          userName,
-          inputMessage: routed.inputMessage,
-        })
+    const lota = {
+      organizations: {
+        create: organizationServiceSingleton.createOrganization.bind(organizationServiceSingleton),
+        upsert: organizationServiceSingleton.upsertOrganization.bind(organizationServiceSingleton),
+        get: organizationServiceSingleton.getOrganization.bind(organizationServiceSingleton),
+        list: organizationServiceSingleton.listOrganizations.bind(organizationServiceSingleton),
+        update: organizationServiceSingleton.updateOrganization.bind(organizationServiceSingleton),
+        delete: organizationServiceSingleton.deleteOrganization.bind(organizationServiceSingleton),
+      },
+      users: {
+        upsert: userServiceSingleton.upsertUser.bind(userServiceSingleton),
+        get: userServiceSingleton.getUser.bind(userServiceSingleton),
+        list: userServiceSingleton.listUsers.bind(userServiceSingleton),
+        update: userServiceSingleton.updateUser.bind(userServiceSingleton),
+        delete: userServiceSingleton.deleteUser.bind(userServiceSingleton),
+      },
+      memberships: {
+        add: organizationMemberServiceSingleton.addMembership.bind(organizationMemberServiceSingleton),
+        listForOrganization: organizationMemberServiceSingleton.listMembershipsForOrganization.bind(
+          organizationMemberServiceSingleton,
+        ),
+        listForUser: organizationMemberServiceSingleton.listMembershipsForUser.bind(organizationMemberServiceSingleton),
+        remove: organizationMemberServiceSingleton.removeMembership.bind(organizationMemberServiceSingleton),
+        isMember: organizationMemberServiceSingleton.isMember.bind(organizationMemberServiceSingleton),
       },
-      continueApproval: async ({ workstreamId, organizationId, userId, userName, messages }) => {
-        const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-        const workstream = await workstreamServiceSingleton.getWorkstream(workstreamRef)
-        const routed = routeWorkstreamChatMessages(messages)
-        if (routed.kind !== 'approval-continuation') {
-          throw new Error(
-            routed.kind === 'invalid' ? routed.message : 'Expected approval continuation messages payload.',
+      workstreams: {
+        create: workstreamServiceSingleton.createWorkstream.bind(workstreamServiceSingleton),
+        list: workstreamServiceSingleton.listWorkstreams.bind(workstreamServiceSingleton),
+        get: workstreamServiceSingleton.getWorkstream.bind(workstreamServiceSingleton),
+        update: workstreamServiceSingleton.updateTitle.bind(workstreamServiceSingleton),
+        archive: async (workstreamId, status = 'archived') =>
+          await workstreamServiceSingleton.updateStatus(workstreamId, status),
+        unarchive: async (workstreamId, status = 'regular') =>
+          await workstreamServiceSingleton.updateStatus(workstreamId, status),
+        delete: workstreamServiceSingleton.deleteWorkstream.bind(workstreamServiceSingleton),
+        stop: workstreamServiceSingleton.stopActiveRun.bind(workstreamServiceSingleton),
+        listMessages: workstreamMessageServiceSingleton.listMessageHistoryPage.bind(workstreamMessageServiceSingleton),
+        getMessage: async ({ workstreamId, messageId }) => {
+          const messages = await workstreamMessageServiceSingleton.listMessages(
+            ensureRecordId(workstreamId, TABLES.WORKSTREAM),
           )
-        }
+          const message = messages.find((candidate) => candidate.id === messageId)
+          if (!message) {
+            throw new Error(`Workstream message not found: ${messageId}`)
+          }
+          return message
+        },
+        sendMessage: async ({ workstreamId, organizationId, userId, userName, messages }) => {
+          const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+          const workstream = await workstreamServiceSingleton.getWorkstream(workstreamRef)
+          const routed = routeWorkstreamChatMessages(messages)
+          if (routed.kind !== 'turn') {
+            throw new Error(routed.kind === 'invalid' ? routed.message : 'Expected a user turn payload.')
+          }
+
+          return createWorkstreamTurnStreamSingleton({
+            workstream,
+            workstreamRef,
+            orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+            userRef: ensureRecordId(userId, TABLES.USER),
+            userName,
+            inputMessage: routed.inputMessage,
+          })
+        },
+        continueApproval: async ({ workstreamId, organizationId, userId, userName, messages }) => {
+          const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+          const workstream = await workstreamServiceSingleton.getWorkstream(workstreamRef)
+          const routed = routeWorkstreamChatMessages(messages)
+          if (routed.kind !== 'approval-continuation') {
+            throw new Error(
+              routed.kind === 'invalid' ? routed.message : 'Expected approval continuation messages payload.',
+            )
+          }
+
+          return createWorkstreamApprovalContinuationStreamSingleton({
+            workstream,
+            workstreamRef,
+            orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+            userRef: ensureRecordId(userId, TABLES.USER),
+            userName,
+            approvalMessages: routed.approvalMessages,
+          })
+        },
+        uploadAttachment: attachmentServiceSingleton.uploadWorkstreamAttachment.bind(attachmentServiceSingleton),
+      },
+    } satisfies LotaRuntime['lota']
 
-        return await createWorkstreamApprovalContinuationStreamSingleton({
-          workstream,
-          workstreamRef,
-          orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
-          userRef: ensureRecordId(userId, TABLES.USER),
-          userName,
-          approvalMessages: routed.approvalMessages,
-        })
+    let disconnected = false
+
+    return {
+      services: {
+        database: db,
+        redis: redisManager,
+        closeRedisConnection: async () => await redisManager.closeConnection(),
+        attachmentService: attachmentServiceSingleton,
+        documentChunkService: documentChunkServiceSingleton,
+        generatedDocumentStorageService: generatedDocumentStorageServiceSingleton,
+        memoryService: memoryServiceSingleton,
+        verifyMutatingApproval: verifyMutatingApprovalSingleton,
+        organizationService: organizationServiceSingleton,
+        organizationMemberService: organizationMemberServiceSingleton,
+        userService: userServiceSingleton,
+        recentActivityService: recentActivityServiceSingleton,
+        recentActivityTitleService: recentActivityTitleServiceSingleton,
+        executionPlanService: executionPlanServiceSingleton,
+        workstreamMessageService: workstreamMessageServiceSingleton,
+        workstreamService: workstreamServiceSingleton,
+        workstreamTitleService: workstreamTitleServiceSingleton,
+        createWorkstreamApprovalContinuationStream: createWorkstreamApprovalContinuationStreamSingleton,
+        createWorkstreamNativeToolApprovalStream: createWorkstreamNativeToolApprovalStreamSingleton,
+        createWorkstreamTurnStream: createWorkstreamTurnStreamSingleton,
+        isApprovalContinuationRequest: isApprovalContinuationRequestSingleton,
+        runWorkstreamTurnInBackground: runWorkstreamTurnInBackgroundSingleton,
+        syncPlaybookTemplates: playbookRegistryService.syncPlaybookTemplates.bind(playbookRegistryService),
+      },
+      lota,
+      redis: {
+        manager: redisManager,
+        getConnection: () => redisManager.getConnection(),
+        getConnectionForBullMQ: () => redisManager.getConnectionForBullMQ(),
+        closeConnection: async () => await redisManager.closeConnection(),
+      },
+      workers,
+      schemaFiles,
+      contributions: { envKeys: [...new Set(contributionEnvKeys)], schemaFiles: hostContributionSchemaFiles },
+      config: runtimeConfig,
+      plugins: pluginRuntime,
+      systemExecutors,
+      async connectPluginDatabases() {
+        await connectPluginDatabases()
+      },
+      async connect() {
+        await db.connect()
+        const bunFiles = schemaFiles.map((schemaFile) =>
+          schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile),
+        )
+        await db.applySchema(bunFiles)
+        const schemaFingerprint = await computeSchemaFingerprint(schemaFiles)
+        await publishDatabaseBootstrap({ databaseService: db, schemaFingerprint })
       },
-      uploadAttachment: attachmentServiceSingleton.uploadWorkstreamAttachment.bind(attachmentServiceSingleton),
-    },
-  } satisfies LotaRuntime['lota']
+      async disconnect() {
+        if (disconnected) {
+          return
+        }
+        disconnected = true
 
-  return {
-    services: {
-      database: db,
-      redis: redisManager,
-      closeRedisConnection: async () => await redisManager.closeConnection(),
-      attachmentService: attachmentServiceSingleton,
-      documentChunkService: documentChunkServiceSingleton,
-      generatedDocumentStorageService: generatedDocumentStorageServiceSingleton,
-      memoryService: memoryServiceSingleton,
-      verifyMutatingApproval: verifyMutatingApprovalSingleton,
-      organizationService: organizationServiceSingleton,
-      organizationMemberService: organizationMemberServiceSingleton,
-      userService: userServiceSingleton,
-      recentActivityService: recentActivityServiceSingleton,
-      recentActivityTitleService: recentActivityTitleServiceSingleton,
-      executionPlanService: executionPlanServiceSingleton,
-      workstreamMessageService: workstreamMessageServiceSingleton,
-      workstreamService: workstreamServiceSingleton,
-      workstreamTitleService: workstreamTitleServiceSingleton,
-      createWorkstreamApprovalContinuationStream: createWorkstreamApprovalContinuationStreamSingleton,
-      createWorkstreamNativeToolApprovalStream: createWorkstreamNativeToolApprovalStreamSingleton,
-      createWorkstreamTurnStream: createWorkstreamTurnStreamSingleton,
-      isApprovalContinuationRequest: isApprovalContinuationRequestSingleton,
-      runWorkstreamTurnInBackground: runWorkstreamTurnInBackgroundSingleton,
-    },
-    lota,
-    redis: {
-      manager: redisManager,
-      getConnection: () => redisManager.getConnection(),
-      getConnectionForBullMQ: () => redisManager.getConnectionForBullMQ(),
-      closeConnection: async () => await redisManager.closeConnection(),
-    },
-    workers,
-    schemaFiles,
-    contributions: { envKeys: [...new Set(contributionEnvKeys)], schemaFiles: hostContributionSchemaFiles },
-    config: resolvedConfig,
-    plugins: pluginRuntime,
-    async connectPluginDatabases() {
-      await connectPluginDatabases()
-    },
-    async connect() {
-      await db.connect()
-      const bunFiles = schemaFiles.map((schemaFile) =>
-        schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile),
-      )
-      await db.applySchemaAndMigrations(bunFiles)
-      const schemaFingerprint = await computeSchemaFingerprint(schemaFiles)
-      await publishDatabaseBootstrap({ databaseService: db, schemaFingerprint })
-    },
-    async disconnect() {
-      await db.disconnect()
-      await redisManager.closeConnection()
-    },
+        try {
+          await closeSharedSubscriber()
+          await db.disconnect()
+          await redisManager.closeConnection()
+        } finally {
+          releaseRuntimeToken(runtimeToken)
+        }
+      },
+    }
+  } catch (error) {
+    releaseRuntimeToken(runtimeToken)
+    throw error
   }
 }
 

package/src/db/cursor-pagination.ts

@@ -1,4 +1,3 @@
-import { toTimestamp } from '@lota-sdk/shared'
 import type { ChatMessage } from '@lota-sdk/shared'
 import type { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
@@ -7,7 +6,7 @@ import type { RecordIdRef } from './record-id'
 import { databaseService } from './service'
 import type { DatabaseTable } from './tables'
 
-export const CursorRowSchema = z.object({ createdAt: z.union([z.date(), z.string(), z.number()]) })
+export const CursorRowSchema = z.object({ createdAt: z.coerce.date() })
 
 export interface MessageHistoryPage {
   messages: ChatMessage[]
@@ -64,10 +63,8 @@ async function listRowsBefore(
     throw new Error(`Cursor message not found in ${config.table}: ${params.beforeMessageId}`)
   }
 
-  const cursorCreatedAt = new Date(toTimestamp(cursorRow.createdAt) ?? Date.now())
+  const cursorCreatedAt = cursorRow.createdAt
   const cursorId = config.toRowId(params.parentId, params.beforeMessageId)
 
-  return await databaseService.query<unknown>(
-    config.queryBefore(params.parentId, cursorCreatedAt, cursorId, params.take),
-  )
+  return databaseService.query<unknown>(config.queryBefore(params.parentId, cursorCreatedAt, cursorId, params.take))
 }

package/src/db/index.ts

@@ -1,3 +1,4 @@
+export * from './base.service'
 export * from './cursor-pagination'
 export * from './memory'
 export * from './memory-store'
@@ -7,4 +8,5 @@ export * from './record-id'
 export * from './sdk-database'
 export * from './service'
 export * from './startup'
+export * from './surreal-mutation'
 export * from './tables'

package/src/db/memory-store.rows.ts

@@ -13,17 +13,17 @@ export interface SurrealMemoryRow {
   importance: number
   accessCount: number
   needsReview: boolean
-  lastAccessedAt?: Date | string
-  createdAt: Date | string
-  updatedAt?: Date | string
-  validFrom: Date | string
-  validUntil?: Date | string
-  archivedAt?: Date | string
+  lastAccessedAt?: Date
+  createdAt: Date
+  updatedAt?: Date
+  validFrom: Date
+  validUntil?: Date
+  archivedAt?: Date
 }
 
 export interface BasicSearchRow {
   id: RecordIdInput
   content: string
   metadata: Record<string, unknown>
-  createdAt?: Date | string
+  createdAt?: Date
 }

package/src/db/memory-store.ts

@@ -3,6 +3,8 @@ import { BoundQuery, eq, inside } from 'surrealdb'
 import { aiLogger } from '../config/logger'
 import { DEFAULT_MEMORY_SEARCH_LIMIT } from '../config/search'
 import { getDefaultEmbeddings } from '../embeddings/provider'
+import { withTimeout } from '../utils/async'
+import { clampImportance, truncateText } from '../utils/string'
 import { memoryQueryBuilder } from './memory-query-builder'
 import type { RelationCounts } from './memory-store.helpers'
 import { hashContent, mapRowToMemoryRecord, processGraphAwareRows } from './memory-store.helpers'
@@ -92,7 +94,7 @@ export class SurrealMemoryStore {
       LIMIT $limit
     `
 
-    return await databaseService.query<BasicSearchRow>(
+    return databaseService.query<BasicSearchRow>(
       new BoundQuery(sql, { scopeId: options.scopeId, memoryType: options.memoryType, limit: options.limit }),
     )
   }
@@ -184,7 +186,7 @@ export class SurrealMemoryStore {
     const normalized = content.trim()
     if (!normalized) return []
 
-    return await this.embeddings.embedQuery(normalized)
+    return this.embeddings.embedQuery(normalized)
   }
 
   async warmEmbedding(content: string): Promise<void> {
@@ -355,11 +357,11 @@ export class SurrealMemoryStore {
     const hash = hashContent(content, scopeId, memoryType)
     const embedding = await this.generateEmbedding(content)
 
-    importance = Math.max(0, Math.min(1, importance))
+    importance = clampImportance(importance)
 
     const nearDup = await this.findNearDuplicate(embedding, scopeId, content)
     if (nearDup) {
-      const mergedImportance = Math.max(0, Math.min(1, Math.max(nearDup.importance, importance)))
+      const mergedImportance = clampImportance(Math.max(nearDup.importance, importance))
       const keepNew = content.length >= nearDup.content.length
       const winnerContent = keepNew ? content : nearDup.content
       await this.update(nearDup.id, winnerContent, { importance: mergedImportance })
@@ -580,12 +582,11 @@ export class SurrealMemoryStore {
 
     let results: LinearRow[]
     try {
-      results = await Promise.race([
+      results = await withTimeout(
         this.queryFinalStatement<LinearRow>(sql, bindVars),
-        new Promise<never>((_, reject) =>
-          setTimeout(() => reject(new Error('Hybrid search timeout')), SurrealMemoryStore.HYBRID_SEARCH_TIMEOUT_MS),
-        ),
-      ])
+        SurrealMemoryStore.HYBRID_SEARCH_TIMEOUT_MS,
+        'Hybrid search',
+      )
     } catch {
       const elapsed = performance.now() - searchStart
       aiLogger.warn`Hybrid search timed out after ${elapsed.toFixed(0)}ms (scopeId: ${options.scopeId}). Falling back to vector-only.`
@@ -669,18 +670,13 @@ export class SurrealMemoryStore {
 
     const importance =
       typeof options?.importance === 'number'
-        ? Math.max(existing.importance, Math.max(0, Math.min(1, options.importance)))
+        ? Math.max(existing.importance, clampImportance(options.importance))
         : undefined
 
     const durability = options?.durability
     const metadata = options?.metadata ? { ...existing.metadata, ...options.metadata } : undefined
 
-    const updatePayload: Record<string, unknown> = {
-      content: newContent,
-      embedding: newEmbedding,
-      hash: newHash,
-      updatedAt: new Date(),
-    }
+    const updatePayload: Record<string, unknown> = { content: newContent, embedding: newEmbedding, hash: newHash }
     if (importance !== undefined) {
       updatePayload.importance = importance
     }
@@ -760,7 +756,7 @@ export class SurrealMemoryStore {
   }
 
   async addRelation(fromId: string, toId: string, relationType: RelationType, confidence: number = 1.0): Promise<void> {
-    confidence = Math.max(0, Math.min(1, confidence))
+    confidence = clampImportance(confidence)
     const fromRef = ensureRecordId(fromId, TABLES.MEMORY)
     const toRef = ensureRecordId(toId, TABLES.MEMORY)
     await databaseService.relate(fromRef, MEMORY_RELATION_TABLE, toRef, { relationType, confidence })
@@ -953,7 +949,7 @@ export class SurrealMemoryStore {
         if (!neighbor.content || seen.has(neighborId)) continue
         seen.add(neighborId)
         const label = neighbor.relationType ? `[${neighbor.relationType}]` : ''
-        const truncated = neighbor.content.length > 200 ? `${neighbor.content.slice(0, 197)}...` : neighbor.content
+        const truncated = truncateText(neighbor.content, 200)
         contexts.push(`${label} ${truncated}`.trim())
       }
       if (contexts.length > 0) {