@lota-sdk/core 0.4.9 → 0.4.11

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

@@ -1,15 +1,10 @@
 import type { ChatMessage } from '@lota-sdk/shared'
 import { Schema, Effect } from 'effect'
-import type { Context } from 'effect'
 
 import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import type { RecordIdRef } from '../db/record-id'
-import { getCurrentRuntime } from '../effect/runtime-ref'
 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 { LotaQueuesServiceTag } from '../queues/queues.service'
 import { RecentActivityServiceTag } from '../services/recent-activity.service'
 import { ThreadServiceTag } from '../services/thread/thread.service'
 import type { NormalizedThread, ThreadRecord } from '../services/thread/thread.types'
@@ -21,7 +16,6 @@ import {
   shouldEnqueueOnboardingPostChatMemory,
   shouldEnqueueRegularDigestForThread,
 } from './memory/memory-digest-policy'
-import type { LotaRuntimeAdapters } from './runtime-extensions'
 import { shouldEnqueueSkillExtraction } from './skill-extraction-policy'
 import {
   appendPersistedThreadContextToHistoryMessages,
@@ -33,13 +27,6 @@ import {
   toHistoryMessages,
 } from './thread-chat-helpers'
 
-interface PostTurnSideEffectsServices {
-  recentActivityService: Context.Service.Shape<typeof RecentActivityServiceTag>
-  threadService: Context.Service.Shape<typeof ThreadServiceTag>
-  agentConfig: ResolvedAgentConfig
-  runtimeAdapters: LotaRuntimeAdapters
-}
-
 class PostTurnSideEffectsError extends Schema.TaggedErrorClass<PostTurnSideEffectsError>()('PostTurnSideEffectsError', {
   message: Schema.String,
   cause: Schema.Defect,
@@ -55,20 +42,6 @@ function tryPostTurnSideEffect<A>(
   })
 }
 
-function getPostTurnSideEffectsServices(): PostTurnSideEffectsServices {
-  const runtime = getCurrentRuntime()
-  return runtime.runSync(
-    Effect.gen(function* () {
-      return {
-        recentActivityService: yield* RecentActivityServiceTag,
-        threadService: yield* ThreadServiceTag,
-        agentConfig: yield* AgentConfigServiceTag,
-        runtimeAdapters: yield* RuntimeAdaptersServiceTag,
-      }
-    }),
-  )
-}
-
 function resolveDisplayName(
   agentConfig: ResolvedAgentConfig,
   agentId: string,
@@ -137,154 +110,159 @@ interface PostTurnSideEffectsParams {
   agentDisplayNamesById?: Partial<Record<string, string>>
 }
 
-const runPostTurnSideEffectsEffect = (params: PostTurnSideEffectsParams) =>
-  Effect.gen(function* () {
-    const { recentActivityService, threadService, agentConfig, runtimeAdapters } = getPostTurnSideEffectsServices()
-    const recentHistory = yield* tryPostTurnSideEffect('Failed to load recent thread history.', () =>
-      params.loadRecentHistory(),
+export const runPostTurnSideEffects = Effect.fn('PostTurnSideEffects.run')(function* (
+  params: PostTurnSideEffectsParams,
+) {
+  const recentActivityService = yield* RecentActivityServiceTag
+  const threadService = yield* ThreadServiceTag
+  const agentConfig: ResolvedAgentConfig = yield* AgentConfigServiceTag
+  const runtimeAdapters = yield* RuntimeAdaptersServiceTag
+  const queues = yield* LotaQueuesServiceTag
+  const recentHistory = yield* tryPostTurnSideEffect('Failed to load recent thread history.', () =>
+    params.loadRecentHistory(),
+  )
+  const turnCount = yield* threadService.incrementTurnCount(params.threadRef)
+  const agentMessages = buildAgentHistoryMessages(agentConfig, params.allAssistantMessages)
+  const historyMessagesForMemory = appendPersistedThreadContextToHistoryMessages(
+    toHistoryMessages(agentConfig, 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).'
+    yield* tryPostTurnSideEffect('Failed to enqueue post-chat memory extraction.', () =>
+      safeEnqueue(
+        () =>
+          queues.postChatMemory.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 turnCount = yield* 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
+  const referenceUserMessage = params.referenceUserMessage
+  if (params.isUserTurn && referenceUserMessage) {
+    const conversationSummary = buildConversationSummary({
+      agentConfig,
+      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()),
+        },
+      })
 
-    if (shouldExtractMemory) {
-      const memoryUserMessage = userMessageText || 'User uploaded attachment(s).'
-      yield* tryPostTurnSideEffect('Failed to enqueue post-chat memory extraction.', () =>
+      yield* tryPostTurnSideEffect('Failed to enqueue post-chat org action.', () =>
         safeEnqueue(
-          () =>
-            enqueuePostChatMemory({
+          () => {
+            const enqueuePostChatOrgAction = runtimeAdapters.enqueuePostChatOrgAction
+            if (!enqueuePostChatOrgAction) {
+              return
+            }
+
+            const sourceCreatedAt = referenceUserMessage.metadata?.createdAt ?? nowEpochMillis()
+            return enqueuePostChatOrgAction({
               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' },
+              sourceCreatedAt,
+              conversationSummary,
+            })
+          },
+          { operationName: 'post-chat org action 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.', () =>
+      if (recentActivityService.isMeaningfulRefinementCandidate(recentActivityResult.item)) {
+        yield* tryPostTurnSideEffect('Failed to enqueue recent activity title refinement.', () =>
           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' },
+            () =>
+              queues.titleGeneration.enqueueRecentActivityTitleRefinement({ activityId: recentActivityResult.item.id }),
+            { operationName: 'recent activity title refinement 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 })) {
-      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 })) {
-      yield* tryPostTurnSideEffect('Failed to enqueue skill extraction.', () =>
-        safeEnqueue(() => enqueueSkillExtraction({ orgId: params.orgIdString }), {
-          operationName: 'skill extraction enqueue',
-        }),
-      )
-    }
+  if (shouldEnqueueRegularDigestForThread({ onboardingActive: params.onboardingActive, turnCount })) {
+    yield* tryPostTurnSideEffect('Failed to enqueue regular chat memory digest.', () =>
+      safeEnqueue(() => queues.organizationLearning.enqueueRegularChatMemoryDigest({ orgId: params.orgIdString }), {
+        operationName: 'regular chat memory digest enqueue',
+      }),
+    )
+  }
 
-    if (shouldEnqueueMemoryConsolidation({ onboardingActive: params.onboardingActive, turnCount })) {
-      yield* tryPostTurnSideEffect('Failed to enqueue memory consolidation.', () =>
-        safeEnqueue(() => enqueueMemoryConsolidation({ scopeId: params.orgIdString }), {
-          operationName: 'memory consolidation enqueue',
-        }),
-      )
-    }
-  })
+  if (shouldEnqueueSkillExtraction({ onboardingActive: params.onboardingActive, turnCount })) {
+    yield* tryPostTurnSideEffect('Failed to enqueue skill extraction.', () =>
+      safeEnqueue(() => queues.organizationLearning.enqueueSkillExtraction({ orgId: params.orgIdString }), {
+        operationName: 'skill extraction enqueue',
+      }),
+    )
+  }
 
-export function runPostTurnSideEffects(params: PostTurnSideEffectsParams): Promise<void> {
-  return Effect.runPromise(runPostTurnSideEffectsEffect(params))
-}
+  if (shouldEnqueueMemoryConsolidation({ onboardingActive: params.onboardingActive, turnCount })) {
+    yield* tryPostTurnSideEffect('Failed to enqueue memory consolidation.', () =>
+      safeEnqueue(() => queues.memoryConsolidation.enqueueMemoryConsolidation({ scopeId: params.orgIdString }), {
+        operationName: 'memory consolidation enqueue',
+      }),
+    )
+  }
+})

package/src/runtime/retrieval-adapters.ts

@@ -1,8 +1,8 @@
 import { Schema, Effect } from 'effect'
 
-interface ScopedRetrievalTask<TCandidate> {
+interface ScopedRetrievalTask<TCandidate, E = never> {
   scopeTag: string
-  retrieve: () => PromiseLike<TCandidate[]> | Effect.Effect<TCandidate[], unknown>
+  retrieve: () => PromiseLike<TCandidate[]> | Effect.Effect<TCandidate[], E>
 }
 
 interface ScopedRetrievalResult<TCandidate> {
@@ -20,8 +20,8 @@ function toScopedRetrievalError(scopeTag: string, cause: unknown): ScopedRetriev
   return new ScopedRetrievalError({ scopeTag, message: cause instanceof Error ? cause.message : String(cause), cause })
 }
 
-export function executeScopedRetrieval<TCandidate>(
-  tasks: ScopedRetrievalTask<TCandidate>[],
+export function executeScopedRetrieval<TCandidate, E>(
+  tasks: ScopedRetrievalTask<TCandidate, E>[],
 ): Effect.Effect<ScopedRetrievalResult<TCandidate>[], ScopedRetrievalError> {
   return Effect.forEach(
     tasks,

package/src/runtime/runtime-config.ts

@@ -8,8 +8,6 @@ import { DEFAULT_AI_GATEWAY_URL } from '../config/constants'
 import { OPENROUTER_FAST_RERANK_MODEL_ID } from '../config/model-constants'
 import type { LotaThreadConfig, ThreadBootstrapWelcomeConfig } from '../config/thread-defaults'
 import type { RecordIdRef } from '../db/record-id'
-import { getCurrentRuntime } from '../effect/runtime-ref'
-import { RuntimeConfigServiceTag } from '../effect/services'
 import type { NotificationService } from '../services/notification.service'
 import { isRecord } from '../utils/string'
 import type { GraphDesigner } from './graph-designer'
@@ -329,7 +327,7 @@ export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>)
   return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
 }
 
-const runtimeEnvironmentConfig = Config.all({
+export const lotaRuntimeEnvConfig = Config.all({
   surrealdbUrl: Config.string('SURREALDB_URL'),
   surrealdbNamespace: Config.string('SURREALDB_NAMESPACE'),
   surrealdbUser: Config.string('SURREALDB_USER'),
@@ -369,7 +367,7 @@ export function loadLotaRuntimeConfigFromEnv(
   overrides: LotaRuntimeEnvironmentOverrides,
   options: { configProvider?: ConfigProvider.ConfigProvider } = {},
 ) {
-  return runtimeEnvironmentConfig
+  return lotaRuntimeEnvConfig
     .parse(options.configProvider ?? ConfigProvider.fromEnv())
     .pipe(
       Effect.map((env) =>
@@ -403,7 +401,7 @@ export function loadLotaRuntimeConfigFromEnv(
             apiKey: Redacted.value(env.firecrawlApiKey),
             ...(Option.isSome(env.firecrawlApiBaseUrl) ? { apiBaseUrl: env.firecrawlApiBaseUrl.value } : {}),
           },
-          logging: overrides.logging ?? { level: env.logLevel as (typeof logLevelValues)[number] },
+          logging: overrides.logging ?? { level: z.enum(logLevelValues).parse(env.logLevel) },
           memory: {
             searchK: env.memorySearchK,
             rerankerStrategy: env.memoryRerankerStrategy as MemoryRerankerStrategy,
@@ -422,8 +420,4 @@ export function loadLotaRuntimeConfigFromEnv(
     )
 }
 
-export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
-  return getCurrentRuntime().runSync(Effect.service(RuntimeConfigServiceTag))
-}
-
 export type { LotaThreadConfig }

package/src/runtime/runtime-extensions.ts

@@ -6,19 +6,9 @@ import type {
   PlanSpecRecord,
 } from '@lota-sdk/shared'
 import type { ToolSet } from 'ai'
-import { Effect } from 'effect'
-import type { Context } from 'effect'
 
 import type { RecordIdRef } from '../db/record-id'
-import { getCurrentRuntime } from '../effect/runtime-ref'
-import {
-  RuntimeAdaptersServiceTag,
-  RuntimeWorkerExtensionsServiceTag,
-  ToolProvidersServiceTag,
-  TurnHooksServiceTag,
-} from '../effect/services'
 import type { ReadableUploadMetadata } from '../storage/attachment-types'
-import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
 export interface LotaRuntimeBackgroundCursor {
   createdAt: Date
@@ -201,36 +191,3 @@ export interface LotaRuntimeAdapters {
   connectPluginDatabases?: () => Promise<void>
   withWorkspaceMemoryLock?: <T>(workspaceId: string, fn: () => Promise<T>) => Promise<T>
 }
-
-function resolveFromRuntime<I, T>(tag: Context.Key<I, T>): T {
-  return getCurrentRuntime().runSync(Effect.service(tag))
-}
-
-export function getRuntimeAdapters(): LotaRuntimeAdapters {
-  return resolveFromRuntime(RuntimeAdaptersServiceTag)
-}
-
-export function getTurnHooks(): LotaRuntimeTurnHooks {
-  return resolveFromRuntime(TurnHooksServiceTag)
-}
-
-export function getToolProviders(): ToolSet {
-  return resolveFromRuntime(ToolProvidersServiceTag)
-}
-
-export function getConfiguredPluginDatabaseConnector(): (() => Promise<void>) | undefined {
-  return getRuntimeAdapters().connectPluginDatabases
-}
-
-export function getExtraWorkers(): LotaRuntimeWorkerExtensions {
-  return resolveFromRuntime(RuntimeWorkerExtensionsServiceTag)
-}
-
-export function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
-  const adapter = getRuntimeAdapters().withWorkspaceMemoryLock
-  if (!adapter) {
-    return fn()
-  }
-
-  return adapter(workspaceId, fn)
-}

package/src/runtime/runtime-lifecycle.ts

@@ -0,0 +1,124 @@
+/**
+ * Plugin database connect/disconnect helpers and runtime disconnect assembly.
+ *
+ * The plugin connect/disconnect helpers run inside the supplied
+ * `ManagedRuntime` so spans, logging, and layer context stay consistent with
+ * the rest of the SDK runtime. `createRuntimeDisconnect` instead drives the
+ * shutdown sequence through the caller-supplied `runPromiseWithCurrentContext`
+ * (currently `Effect.runPromiseWith(Context.empty())`), which intentionally
+ * does not preserve the SDK runtime context — by then the runtime is being
+ * torn down.
+ */
+
+import type { ManagedRuntime } from 'effect'
+import { Effect } from 'effect'
+
+import { clearAiGatewayRuntime } from '../ai-gateway/ai-gateway'
+import { effectTryPromise } from '../effect/helpers'
+import type { LotaPlugin } from './plugin-types'
+
+// 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>
+
+function getPluginLifecycleServices(plugin: LotaPlugin): Record<string, unknown> {
+  return plugin.services
+}
+
+/**
+ * Build a plugin database connector that iterates the configured plugins and
+ * calls each `services.connectDatabase()` once, tracking completion in
+ * `connectedPluginDatabases` so repeated calls are idempotent.
+ */
+export function createPluginDatabaseConnector(
+  managedRuntime: SdkManagedRuntime,
+  pluginRuntime: Record<string, LotaPlugin>,
+  connectedPluginDatabases: Set<string>,
+): () => Promise<void> {
+  return () =>
+    managedRuntime.runPromise(
+      Effect.gen(function* () {
+        for (const [pluginName, plugin] of Object.entries(pluginRuntime)) {
+          if (connectedPluginDatabases.has(pluginName)) {
+            continue
+          }
+
+          const services = getPluginLifecycleServices(plugin)
+          const connectDatabase = Reflect.get(services, 'connectDatabase')
+          if (typeof connectDatabase !== 'function') {
+            continue
+          }
+
+          const connectDatabaseFn = connectDatabase as (this: typeof services) => Promise<void>
+          yield* effectTryPromise(() => connectDatabaseFn.call(services))
+          connectedPluginDatabases.add(pluginName)
+        }
+      }),
+    )
+}
+
+/**
+ * Build a plugin database disconnector. Clears `connectedPluginDatabases`
+ * entries regardless of whether the plugin provides a `disconnectDatabase`
+ * hook, so the set stays in sync with actual connection state.
+ */
+export function createPluginDatabaseDisconnector(
+  managedRuntime: SdkManagedRuntime,
+  pluginRuntime: Record<string, LotaPlugin>,
+  connectedPluginDatabases: Set<string>,
+): () => Promise<void> {
+  return () =>
+    managedRuntime.runPromise(
+      Effect.gen(function* () {
+        for (const [pluginName, plugin] of Object.entries(pluginRuntime)) {
+          if (!connectedPluginDatabases.has(pluginName)) {
+            continue
+          }
+
+          const services = getPluginLifecycleServices(plugin)
+          const disconnectDatabase = Reflect.get(services, 'disconnectDatabase')
+          if (typeof disconnectDatabase !== 'function') {
+            connectedPluginDatabases.delete(pluginName)
+            continue
+          }
+
+          const disconnectDatabaseFn = disconnectDatabase as (this: typeof services) => Promise<void>
+          yield* effectTryPromise(() => disconnectDatabaseFn.call(services))
+          connectedPluginDatabases.delete(pluginName)
+        }
+      }),
+    )
+}
+
+interface CreateDisconnectInput {
+  managedRuntime: SdkManagedRuntime
+  runPromiseWithCurrentContext: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
+  socialChatShutdown: () => Promise<void>
+  disconnectPluginDatabases: () => Promise<void>
+}
+
+/**
+ * Compose the runtime `disconnect()` function. The returned function is
+ * idempotent: the first call starts the shutdown sequence, subsequent calls
+ * return the same in-flight promise.
+ */
+export function createRuntimeDisconnect(input: CreateDisconnectInput): () => Promise<void> {
+  const { managedRuntime, runPromiseWithCurrentContext, socialChatShutdown, disconnectPluginDatabases } = input
+
+  let disconnectPromise: Promise<void> | null = null
+
+  return () => {
+    if (disconnectPromise) {
+      return disconnectPromise
+    }
+
+    disconnectPromise = runPromiseWithCurrentContext(
+      Effect.gen(function* () {
+        yield* Effect.ignore(effectTryPromise(() => socialChatShutdown()))
+        yield* Effect.ignore(effectTryPromise(() => disconnectPluginDatabases()))
+        yield* effectTryPromise(() => managedRuntime.dispose())
+        yield* Effect.sync(() => clearAiGatewayRuntime())
+      }),
+    )
+    return disconnectPromise
+  }
+}