@lota-sdk/core 0.4.8 → 0.4.10

package/src/runtime/post-turn-side-effects.ts

@@ -1,19 +1,26 @@
 import type { ChatMessage } from '@lota-sdk/shared'
+import { Schema, Effect } from 'effect'
 
-import { agentDisplayNames } from '../config/agent-defaults'
+import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import type { RecordIdRef } from '../db/record-id'
+import { runPromise } from '../effect/runtime'
+import { AgentConfigServiceTag, RuntimeAdaptersServiceTag } from '../effect/services'
 import { enqueueMemoryConsolidation } from '../queues/memory-consolidation.queue'
 import { enqueueRegularChatMemoryDigest, enqueueSkillExtraction } from '../queues/organization-learning.queue'
 import { enqueuePostChatMemory } from '../queues/post-chat-memory.queue'
 import { enqueueRecentActivityTitleRefinement } from '../queues/title-generation.queue'
+import { RecentActivityServiceTag } from '../services/recent-activity.service'
+import { ThreadServiceTag } from '../services/thread/thread.service'
+import type { NormalizedThread, ThreadRecord } from '../services/thread/thread.types'
+import { safeEnqueue } from '../utils/async'
+import { nowEpochMillis, toIsoDateTimeString } from '../utils/date-time'
 import {
   shouldEnqueueMemoryConsolidation,
   shouldEnqueueMemoryExtraction,
   shouldEnqueueOnboardingPostChatMemory,
   shouldEnqueueRegularDigestForThread,
-} from '../runtime/memory-digest-policy'
-import { getRuntimeAdapters } from '../runtime/runtime-extensions'
-import { shouldEnqueueSkillExtraction } from '../runtime/skill-extraction-policy'
+} from './memory/memory-digest-policy'
+import { shouldEnqueueSkillExtraction } from './skill-extraction-policy'
 import {
   appendPersistedThreadContextToHistoryMessages,
   buildAgentHistoryMessages,
@@ -22,14 +29,28 @@ import {
   extractMessageText,
   readOptionalString,
   toHistoryMessages,
-} from '../runtime/thread-chat-helpers'
-import { recentActivityService } from '../services/recent-activity.service'
-import { threadService } from '../services/thread.service'
-import type { NormalizedThread, ThreadRecord } from '../services/thread.types'
-import { safeEnqueue } from '../utils/async'
-import { toIsoDateTimeString } from '../utils/date-time'
+} from './thread-chat-helpers'
+
+class PostTurnSideEffectsError extends Schema.TaggedErrorClass<PostTurnSideEffectsError>()('PostTurnSideEffectsError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function tryPostTurnSideEffect<A>(
+  message: string,
+  thunk: () => PromiseLike<A>,
+): Effect.Effect<A, PostTurnSideEffectsError> {
+  return Effect.tryPromise({
+    try: () => Promise.resolve(thunk()),
+    catch: (cause) => new PostTurnSideEffectsError({ message, cause }),
+  })
+}
 
-function resolveDisplayName(agentId: string, overrides?: Partial<Record<string, string>>): string {
+function resolveDisplayName(
+  agentConfig: ResolvedAgentConfig,
+  agentId: string,
+  overrides?: Partial<Record<string, string>>,
+): string {
   if (overrides && Object.hasOwn(overrides, agentId)) {
     const override = overrides[agentId]
     if (override !== undefined) {
@@ -37,7 +58,7 @@ function resolveDisplayName(agentId: string, overrides?: Partial<Record<string,
     }
   }
 
-  return agentDisplayNames[agentId] ?? agentId
+  return agentConfig.displayNames[agentId] ?? agentId
 }
 
 function buildRecentActivityChatDeepLink(params: {
@@ -53,12 +74,13 @@ function buildRecentActivityChatDeepLink(params: {
 }
 
 function buildRecentActivityChatSystemTitle(params: {
+  agentConfig: ResolvedAgentConfig
   thread: NormalizedThread
   visibleAgentId: string
   agentDisplayNamesById?: Partial<Record<string, string>>
 }): string {
   if (params.thread.type === 'default') {
-    return `Conversation with ${resolveDisplayName(params.visibleAgentId, params.agentDisplayNamesById)}`
+    return `Conversation with ${resolveDisplayName(params.agentConfig, params.visibleAgentId, params.agentDisplayNamesById)}`
   }
 
   return params.thread.title.trim() || 'Thread update'
@@ -92,132 +114,157 @@ interface PostTurnSideEffectsParams {
   agentDisplayNamesById?: Partial<Record<string, string>>
 }
 
-export async function runPostTurnSideEffects(params: PostTurnSideEffectsParams): Promise<void> {
-  const recentHistory = await params.loadRecentHistory()
-  const turnCount = await threadService.incrementTurnCount(params.threadRef)
-  const agentMessages = buildAgentHistoryMessages(params.allAssistantMessages)
-  const historyMessagesForMemory = appendPersistedThreadContextToHistoryMessages(toHistoryMessages(recentHistory), {
-    compactionSummary: params.latestThreadRecord.compactionSummary,
-  })
-
-  const userMessageText = params.referenceUserMessage ? extractMessageText(params.referenceUserMessage).trim() : ''
-  const readableUploads = params.listReadableUploads()
-  const attachmentMetadataContext = buildReadableUploadMetadataContext(readableUploads)
-  const hasAttachmentContext = Boolean(attachmentMetadataContext)
-  const shouldExtractMemory = params.onboardingActive
-    ? shouldEnqueueOnboardingPostChatMemory({
-        onboardingActive: params.onboardingActive,
-        userMessageText,
-        hasAttachmentContext,
-        agentMessageCount: agentMessages.length,
-      })
-    : shouldEnqueueMemoryExtraction({ onboardingActive: params.onboardingActive, turnCount }) &&
-      userMessageText.length > 0
-
-  if (shouldExtractMemory) {
-    const memoryUserMessage = userMessageText || 'User uploaded attachment(s).'
-    await safeEnqueue(
-      () =>
-        enqueuePostChatMemory({
-          orgId: params.orgIdString,
-          threadId: params.threadIdString,
-          sourceId: params.referenceUserMessageId,
-          onboardStatus: readOptionalString((params.workspace as { onboardStatus?: unknown }).onboardStatus),
-          userMessage: memoryUserMessage,
-          historyMessages: historyMessagesForMemory,
-          agentMessages,
-          memoryBlock: params.memoryBlock.trim() ? params.memoryBlock : undefined,
-          attachmentContext: attachmentMetadataContext,
-        }),
-      { operationName: 'post-chat memory extraction enqueue' },
+const runPostTurnSideEffectsEffect = (params: PostTurnSideEffectsParams) =>
+  Effect.gen(function* () {
+    const recentActivityService = yield* RecentActivityServiceTag
+    const threadService = yield* ThreadServiceTag
+    const agentConfig: ResolvedAgentConfig = yield* AgentConfigServiceTag
+    const runtimeAdapters = yield* RuntimeAdaptersServiceTag
+    const recentHistory = yield* tryPostTurnSideEffect('Failed to load recent thread history.', () =>
+      params.loadRecentHistory(),
     )
-  }
-
-  if (params.isUserTurn && params.referenceUserMessage) {
-    const conversationSummary = buildConversationSummary({
-      userMessageText,
-      assistantMessages: params.allAssistantMessages,
+    const turnCount = yield* threadService.incrementTurnCount(params.threadRef)
+    const agentMessages = buildAgentHistoryMessages(params.allAssistantMessages)
+    const historyMessagesForMemory = appendPersistedThreadContextToHistoryMessages(toHistoryMessages(recentHistory), {
+      compactionSummary: params.latestThreadRecord.compactionSummary,
     })
-    if (conversationSummary) {
-      const effectiveAgentId = params.visibleThreadAgentId ?? params.defaultLeadAgentId
-      const recentActivityResult = await recentActivityService.recordEvent({
-        orgId: params.orgRef,
-        userId: params.userRef,
-        source: 'system',
-        event: {
-          sourceEventId: `chat-turn:${params.referenceUserMessageId}`,
-          kind: 'chat.turn.completed',
-          targetKind: 'thread',
-          targetId: params.threadIdString,
-          mergeKey: `thread:${params.threadIdString}`,
-          title: buildRecentActivityChatSystemTitle({
-            thread: params.thread,
-            visibleAgentId: effectiveAgentId,
-            agentDisplayNamesById: params.agentDisplayNamesById,
-          }),
-          sourceLabel: resolveDisplayName(effectiveAgentId, params.agentDisplayNamesById),
-          deepLink: buildRecentActivityChatDeepLink({
-            thread: params.thread,
-            threadId: params.threadIdString,
-            visibleAgentId: effectiveAgentId,
-          }),
-          metadata: {
-            agentId: effectiveAgentId,
-            agentName: resolveDisplayName(effectiveAgentId, params.agentDisplayNamesById),
-            threadId: params.threadIdString,
-            threadTitle: params.latestThreadRecord.title ?? params.thread.title,
-            threadType: params.thread.type,
-            ...(params.thread.threadType ? { coreType: params.thread.threadType } : {}),
-            userMessageText,
-            assistantSummary: conversationSummary,
-            messageId: params.referenceUserMessageId,
-          },
-          occurredAt: toIsoDateTimeString(params.referenceUserMessage.metadata?.createdAt ?? Date.now()),
-        },
-      })
 
-      await safeEnqueue(
-        async () => {
-          const enqueuePostChatOrgAction = getRuntimeAdapters().enqueuePostChatOrgAction
-          if (!enqueuePostChatOrgAction) {
-            return
-          }
-          const sourceCreatedAt = params.referenceUserMessage?.metadata?.createdAt ?? Date.now()
-
-          await enqueuePostChatOrgAction({
-            orgId: params.orgIdString,
-            threadId: params.threadIdString,
-            sourceId: params.referenceUserMessageId,
-            sourceCreatedAt,
-            conversationSummary,
-          })
-        },
-        { operationName: 'post-chat org action enqueue' },
+    const userMessageText = params.referenceUserMessage ? extractMessageText(params.referenceUserMessage).trim() : ''
+    const readableUploads = params.listReadableUploads()
+    const attachmentMetadataContext = buildReadableUploadMetadataContext(readableUploads)
+    const hasAttachmentContext = Boolean(attachmentMetadataContext)
+    const shouldExtractMemory = params.onboardingActive
+      ? shouldEnqueueOnboardingPostChatMemory({
+          onboardingActive: params.onboardingActive,
+          userMessageText,
+          hasAttachmentContext,
+          agentMessageCount: agentMessages.length,
+        })
+      : shouldEnqueueMemoryExtraction({ onboardingActive: params.onboardingActive, turnCount }) &&
+        userMessageText.length > 0
+
+    if (shouldExtractMemory) {
+      const memoryUserMessage = userMessageText || 'User uploaded attachment(s).'
+      yield* tryPostTurnSideEffect('Failed to enqueue post-chat memory extraction.', () =>
+        safeEnqueue(
+          () =>
+            enqueuePostChatMemory({
+              orgId: params.orgIdString,
+              threadId: params.threadIdString,
+              sourceId: params.referenceUserMessageId,
+              onboardStatus: readOptionalString((params.workspace as { onboardStatus?: unknown }).onboardStatus),
+              userMessage: memoryUserMessage,
+              historyMessages: historyMessagesForMemory,
+              agentMessages,
+              memoryBlock: params.memoryBlock.trim() ? params.memoryBlock : undefined,
+              attachmentContext: attachmentMetadataContext,
+            }),
+          { operationName: 'post-chat memory extraction enqueue' },
+        ),
       )
+    }
 
-      if (recentActivityService.isMeaningfulRefinementCandidate(recentActivityResult.item)) {
-        await safeEnqueue(() => enqueueRecentActivityTitleRefinement({ activityId: recentActivityResult.item.id }), {
-          operationName: 'recent activity title refinement enqueue',
+    const referenceUserMessage = params.referenceUserMessage
+    if (params.isUserTurn && referenceUserMessage) {
+      const conversationSummary = buildConversationSummary({
+        userMessageText,
+        assistantMessages: params.allAssistantMessages,
+      })
+      if (conversationSummary) {
+        const effectiveAgentId = params.visibleThreadAgentId ?? params.defaultLeadAgentId
+        const recentActivityResult = yield* recentActivityService.recordEvent({
+          orgId: params.orgRef,
+          userId: params.userRef,
+          source: 'system',
+          event: {
+            sourceEventId: `chat-turn:${params.referenceUserMessageId}`,
+            kind: 'chat.turn.completed',
+            targetKind: 'thread',
+            targetId: params.threadIdString,
+            mergeKey: `thread:${params.threadIdString}`,
+            title: buildRecentActivityChatSystemTitle({
+              agentConfig,
+              thread: params.thread,
+              visibleAgentId: effectiveAgentId,
+              agentDisplayNamesById: params.agentDisplayNamesById,
+            }),
+            sourceLabel: resolveDisplayName(agentConfig, effectiveAgentId, params.agentDisplayNamesById),
+            deepLink: buildRecentActivityChatDeepLink({
+              thread: params.thread,
+              threadId: params.threadIdString,
+              visibleAgentId: effectiveAgentId,
+            }),
+            metadata: {
+              agentId: effectiveAgentId,
+              agentName: resolveDisplayName(agentConfig, effectiveAgentId, params.agentDisplayNamesById),
+              threadId: params.threadIdString,
+              threadTitle: params.latestThreadRecord.title ?? params.thread.title,
+              threadType: params.thread.type,
+              ...(params.thread.threadType ? { coreType: params.thread.threadType } : {}),
+              userMessageText,
+              assistantSummary: conversationSummary,
+              messageId: params.referenceUserMessageId,
+            },
+            occurredAt: toIsoDateTimeString(referenceUserMessage.metadata?.createdAt ?? nowEpochMillis()),
+          },
         })
+
+        yield* tryPostTurnSideEffect('Failed to enqueue post-chat org action.', () =>
+          safeEnqueue(
+            () => {
+              const enqueuePostChatOrgAction = runtimeAdapters.enqueuePostChatOrgAction
+              if (!enqueuePostChatOrgAction) {
+                return
+              }
+
+              const sourceCreatedAt = referenceUserMessage.metadata?.createdAt ?? nowEpochMillis()
+              return enqueuePostChatOrgAction({
+                orgId: params.orgIdString,
+                threadId: params.threadIdString,
+                sourceId: params.referenceUserMessageId,
+                sourceCreatedAt,
+                conversationSummary,
+              })
+            },
+            { operationName: 'post-chat org action enqueue' },
+          ),
+        )
+
+        if (recentActivityService.isMeaningfulRefinementCandidate(recentActivityResult.item)) {
+          yield* tryPostTurnSideEffect('Failed to enqueue recent activity title refinement.', () =>
+            safeEnqueue(() => enqueueRecentActivityTitleRefinement({ activityId: recentActivityResult.item.id }), {
+              operationName: 'recent activity title refinement enqueue',
+            }),
+          )
+        }
       }
     }
-  }
 
-  if (shouldEnqueueRegularDigestForThread({ onboardingActive: params.onboardingActive, turnCount })) {
-    await safeEnqueue(() => enqueueRegularChatMemoryDigest({ orgId: params.orgIdString }), {
-      operationName: 'regular chat memory digest enqueue',
-    })
-  }
+    if (shouldEnqueueRegularDigestForThread({ onboardingActive: params.onboardingActive, turnCount })) {
+      yield* tryPostTurnSideEffect('Failed to enqueue regular chat memory digest.', () =>
+        safeEnqueue(() => enqueueRegularChatMemoryDigest({ orgId: params.orgIdString }), {
+          operationName: 'regular chat memory digest enqueue',
+        }),
+      )
+    }
 
-  if (shouldEnqueueSkillExtraction({ onboardingActive: params.onboardingActive, turnCount })) {
-    await safeEnqueue(() => enqueueSkillExtraction({ orgId: params.orgIdString }), {
-      operationName: 'skill extraction enqueue',
-    })
-  }
+    if (shouldEnqueueSkillExtraction({ onboardingActive: params.onboardingActive, turnCount })) {
+      yield* tryPostTurnSideEffect('Failed to enqueue skill extraction.', () =>
+        safeEnqueue(() => enqueueSkillExtraction({ orgId: params.orgIdString }), {
+          operationName: 'skill extraction enqueue',
+        }),
+      )
+    }
 
-  if (shouldEnqueueMemoryConsolidation({ onboardingActive: params.onboardingActive, turnCount })) {
-    await safeEnqueue(() => enqueueMemoryConsolidation({ scopeId: params.orgIdString }), {
-      operationName: 'memory consolidation enqueue',
-    })
-  }
+    if (shouldEnqueueMemoryConsolidation({ onboardingActive: params.onboardingActive, turnCount })) {
+      yield* tryPostTurnSideEffect('Failed to enqueue memory consolidation.', () =>
+        safeEnqueue(() => enqueueMemoryConsolidation({ scopeId: params.orgIdString }), {
+          operationName: 'memory consolidation enqueue',
+        }),
+      )
+    }
+  })
+
+export function runPostTurnSideEffects(params: PostTurnSideEffectsParams): Promise<void> {
+  return runPromise(runPostTurnSideEffectsEffect(params))
 }

package/src/runtime/retrieval-adapters.ts

@@ -1,6 +1,8 @@
-interface ScopedRetrievalTask<TCandidate> {
+import { Schema, Effect } from 'effect'
+
+interface ScopedRetrievalTask<TCandidate, E = never> {
   scopeTag: string
-  retrieve: () => Promise<TCandidate[]>
+  retrieve: () => PromiseLike<TCandidate[]> | Effect.Effect<TCandidate[], E>
 }
 
 interface ScopedRetrievalResult<TCandidate> {
@@ -8,10 +10,42 @@ interface ScopedRetrievalResult<TCandidate> {
   candidates: TCandidate[]
 }
 
-export async function executeScopedRetrieval<TCandidate>(
-  tasks: ScopedRetrievalTask<TCandidate>[],
-): Promise<ScopedRetrievalResult<TCandidate>[]> {
-  return Promise.all(tasks.map(async (task) => ({ scopeTag: task.scopeTag, candidates: await task.retrieve() })))
+class ScopedRetrievalError extends Schema.TaggedErrorClass<ScopedRetrievalError>()('ScopedRetrievalError', {
+  scopeTag: Schema.String,
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function toScopedRetrievalError(scopeTag: string, cause: unknown): ScopedRetrievalError {
+  return new ScopedRetrievalError({ scopeTag, message: cause instanceof Error ? cause.message : String(cause), cause })
+}
+
+export function executeScopedRetrieval<TCandidate, E>(
+  tasks: ScopedRetrievalTask<TCandidate, E>[],
+): Effect.Effect<ScopedRetrievalResult<TCandidate>[], ScopedRetrievalError> {
+  return Effect.forEach(
+    tasks,
+    (task) =>
+      Effect.suspend(() => {
+        try {
+          const result = task.retrieve()
+          if (Effect.isEffect(result)) {
+            return result.pipe(
+              Effect.mapError((cause) => toScopedRetrievalError(task.scopeTag, cause)),
+              Effect.map((candidates) => ({ scopeTag: task.scopeTag, candidates })),
+            )
+          }
+
+          return Effect.tryPromise({
+            try: () => result,
+            catch: (cause) => toScopedRetrievalError(task.scopeTag, cause),
+          }).pipe(Effect.map((candidates) => ({ scopeTag: task.scopeTag, candidates })))
+        } catch (cause) {
+          return Effect.fail(toScopedRetrievalError(task.scopeTag, cause))
+        }
+      }),
+    { concurrency: 'unbounded' },
+  )
 }
 
 export function countScopedRetrievalCandidates<TCandidate>(scoped: ScopedRetrievalResult<TCandidate>[]): number {

package/src/runtime/runtime-accessors.ts

@@ -0,0 +1,92 @@
+/**
+ * Installs and tears down the SDK's module-level runtime accessors.
+ *
+ * Several SDK modules expose `configure*`/`clear*` pairs so host code can read
+ * runtime-resolved services synchronously (AI gateway, agent defaults,
+ * firecrawl, graph designer, queue jobs, runtime extensions, redis, thread
+ * defaults). `createLotaRuntime` wires them once at boot and clears them on
+ * disconnect; this module keeps both phases in a single place so they stay
+ * symmetric.
+ */
+
+import type { Context, ManagedRuntime } from 'effect'
+import { Effect } from 'effect'
+
+import {
+  AiGatewayTag,
+  clearAiGatewayRuntimeAccessors,
+  configureAiGatewayRuntimeAccessors,
+} from '../ai-gateway/ai-gateway'
+import { clearAgentRuntimeDefaults, configureAgentRuntimeDefaults } from '../config/agent-defaults'
+import { clearThreadRuntimeDefaults, configureThreadRuntimeDefaults } from '../config/thread-defaults'
+import {
+  AgentConfigServiceTag,
+  AgentFactoryServiceTag,
+  RuntimeAdaptersServiceTag,
+  RuntimeWorkerExtensionsServiceTag,
+  ThreadConfigServiceTag,
+  ToolProvidersServiceTag,
+  TurnHooksServiceTag,
+} from '../effect'
+import type { RedisConnectionManager } from '../redis/connection'
+import { clearRuntimeRedisManager, configureRuntimeRedisManager } from '../redis/runtime-connection'
+import { QueueJobServiceTag } from '../services/queue-job.service'
+import { FirecrawlTag, clearFirecrawlClient, configureFirecrawlClient } from '../tools/firecrawl-client'
+import { clearQueueJobService, configureQueueJobService } from '../workers/worker-utils'
+import { clearGraphDesigner, configureGraphDesigner } from './graph-designer'
+import type { ResolvedLotaRuntimeConfig } from './runtime-config'
+import { clearRuntimeExtensionsAccessors, configureRuntimeExtensionsAccessors } from './runtime-extensions'
+
+// eslint-disable-next-line typescript-eslint/no-explicit-any -- ManagedRuntime is contravariant in R; `any` is the only valid wildcard
+type SdkManagedRuntime = ManagedRuntime.ManagedRuntime<any, any>
+
+interface ConfigureRuntimeAccessorsInput {
+  managedRuntime: SdkManagedRuntime
+  runtimeConfig: ResolvedLotaRuntimeConfig
+  redisManager: RedisConnectionManager
+}
+
+/**
+ * Resolve every service the SDK exposes through module-level accessors and
+ * install them. Must be called after `setLotaSdkRuntime(managedRuntime)`.
+ */
+export function configureRuntimeModuleAccessors(input: ConfigureRuntimeAccessorsInput): void {
+  const { managedRuntime, runtimeConfig, redisManager } = input
+  const resolve = <I, T>(tag: Context.Key<I, T>): T =>
+    // We know every tag is provided by the managed runtime; the cast bridges
+    // the erased service-set carried by `SdkManagedRuntime`.
+    managedRuntime.runSync(Effect.service(tag) as Effect.Effect<T, never, never>)
+
+  configureAiGatewayRuntimeAccessors({ aiGateway: resolve(AiGatewayTag), runtimeConfig })
+  configureAgentRuntimeDefaults({
+    agentConfig: resolve(AgentConfigServiceTag),
+    agentFactoryConfig: resolve(AgentFactoryServiceTag),
+  })
+  configureThreadRuntimeDefaults(resolve(ThreadConfigServiceTag))
+  configureRuntimeExtensionsAccessors({
+    adapters: resolve(RuntimeAdaptersServiceTag),
+    turnHooks: resolve(TurnHooksServiceTag),
+    toolProviders: resolve(ToolProvidersServiceTag),
+    extraWorkers: resolve(RuntimeWorkerExtensionsServiceTag),
+  })
+  configureFirecrawlClient(resolve(FirecrawlTag))
+  configureQueueJobService(resolve(QueueJobServiceTag))
+  configureRuntimeRedisManager(redisManager)
+  configureGraphDesigner(runtimeConfig.graphDesigner)
+}
+
+/**
+ * Clears every module-level accessor installed by
+ * `configureRuntimeModuleAccessors`. Always safe to call (idempotent per clear
+ * function).
+ */
+export function clearRuntimeModuleAccessors(): void {
+  clearAiGatewayRuntimeAccessors()
+  clearAgentRuntimeDefaults()
+  clearFirecrawlClient()
+  clearGraphDesigner()
+  clearQueueJobService()
+  clearRuntimeExtensionsAccessors()
+  clearRuntimeRedisManager()
+  clearThreadRuntimeDefaults()
+}