@lota-sdk/core 0.4.8 → 0.4.10

package/src/runtime/runtime-config.ts

@@ -1,11 +1,15 @@
 import type { ToolSet } from 'ai'
+import { Config, ConfigProvider, Effect, Option, Redacted } from 'effect'
 import { z } from 'zod'
 
 import type { CoreThreadProfile } from '../config/agent-defaults'
 import type { AgentFactory, AgentRuntimeConfigProvider, AgentToolBuilder } from '../config/agent-types'
+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'
@@ -14,6 +18,11 @@ import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from './runtime-extens
 import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
 const logLevelValues = ['trace', 'debug', 'info', 'warning', 'error', 'fatal'] as const
+const nonEmptyStringSchema = z.string().trim().min(1)
+const stringRecordSchema = z.record(z.string(), z.string())
+function objectRecordSchema<T extends object>() {
+  return z.custom<T>(isRecord)
+}
 
 function isStringOrUrl(value: unknown): value is string | URL {
   return typeof value === 'string' || value instanceof URL
@@ -23,26 +32,14 @@ function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
   return typeof value === 'function'
 }
 
-function isStringRecord(value: unknown): value is Record<string, string> {
-  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string')
+function isToolSet(value: unknown): value is ToolSet {
+  return isRecord(value)
 }
 
 function isAgentFactoryRegistry(value: unknown): value is AgentFactory {
   return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'function')
 }
 
-function isPluginRuntimeRecord(value: unknown): value is Record<string, LotaPlugin> {
-  return isRecord(value)
-}
-
-function isSystemExecutorRecord(value: unknown): value is Record<string, SystemNodeExecutor> {
-  return isRecord(value)
-}
-
-function isToolProviderRecord(value: unknown): value is Record<string, unknown> {
-  return isRecord(value)
-}
-
 function isNotificationService(value: unknown): value is NotificationService {
   return isRecord(value) && isFunction(value.notify) && isFunction(value.remind) && isFunction(value.escalate)
 }
@@ -146,7 +143,7 @@ function isSocialChatConfig(value: unknown): value is LotaRuntimeSocialChatConfi
 }
 
 const threadBootstrapWelcomeConfigSchema = z.object({
-  defaultAgentId: z.string().trim().min(1),
+  defaultAgentId: nonEmptyStringSchema,
   buildMessageText: z.custom<ThreadBootstrapWelcomeConfig['buildMessageText']>(isFunction, {
     error: 'onboardingWelcome.buildMessageText must be a function',
   }),
@@ -156,9 +153,9 @@ const threadConfigSchema = z
   .object({
     bootstrap: z
       .object({
-        onboardingDefaultAgents: z.array(z.string().trim().min(1)).optional(),
-        completedDefaultAgents: z.array(z.string().trim().min(1)).optional(),
-        threadTypesAfterOnboarding: z.array(z.string().trim().min(1)).optional(),
+        onboardingDefaultAgents: z.array(nonEmptyStringSchema).optional(),
+        completedDefaultAgents: z.array(nonEmptyStringSchema).optional(),
+        threadTypesAfterOnboarding: z.array(nonEmptyStringSchema).optional(),
         ensureDefaultGroupOnCompleted: z.boolean().optional(),
         onboardingWelcome: threadBootstrapWelcomeConfigSchema.optional(),
       })
@@ -169,19 +166,13 @@ const threadConfigSchema = z
 
 const agentsConfigSchema = z
   .object({
-    roster: z.array(z.string().trim().min(1)).min(1),
-    leadAgentId: z.string().trim().min(1),
-    displayNames: z.custom<Record<string, string>>(isStringRecord, {
-      error: 'agents.displayNames must be a string record',
-    }),
-    shortDisplayNames: z
-      .custom<Record<string, string>>(isStringRecord, { error: 'agents.shortDisplayNames must be a string record' })
-      .optional(),
-    descriptions: z
-      .custom<Record<string, string>>(isStringRecord, { error: 'agents.descriptions must be a string record' })
-      .optional(),
-    routerModelId: z.string().trim().min(1).optional(),
-    teamConsultParticipants: z.array(z.string().trim().min(1)),
+    roster: z.array(nonEmptyStringSchema).min(1),
+    leadAgentId: nonEmptyStringSchema,
+    displayNames: stringRecordSchema,
+    shortDisplayNames: stringRecordSchema.optional(),
+    descriptions: stringRecordSchema.optional(),
+    routerModelId: nonEmptyStringSchema.optional(),
+    teamConsultParticipants: z.array(nonEmptyStringSchema),
     getCoreThreadProfile: z
       .custom<(coreType: string) => CoreThreadProfile>(isFunction, {
         error: 'agents.getCoreThreadProfile must be a function',
@@ -222,24 +213,25 @@ export type MemoryRerankerStrategy = z.infer<typeof MemoryRerankerStrategySchema
 
 export const LotaRuntimeConfigSchema = z.object({
   database: z.object({
-    url: z.string().trim().min(1),
-    namespace: z.string().trim().min(1),
-    username: z.string().trim().min(1),
-    password: z.string().trim().min(1),
+    url: nonEmptyStringSchema,
+    namespace: nonEmptyStringSchema,
+    username: nonEmptyStringSchema,
+    password: nonEmptyStringSchema,
   }),
-  redis: z.object({ url: z.string().trim().min(1) }),
+  redis: z.object({ url: nonEmptyStringSchema }),
   aiGateway: z.object({
-    url: z.string().trim().min(1),
-    key: z.string().trim().min(1),
-    embeddingModel: z.string().trim().min(1).default('openai/text-embedding-3-small'),
-    openRouterApiKey: z.string().trim().min(1).optional(),
+    url: nonEmptyStringSchema,
+    key: nonEmptyStringSchema,
+    embeddingModel: nonEmptyStringSchema.default('openai/text-embedding-3-small'),
+    openRouterApiKey: nonEmptyStringSchema.optional(),
+    maxConcurrency: z.coerce.number().int().positive().default(8),
   }),
   s3: z.object({
-    endpoint: z.string().trim().min(1),
-    bucket: z.string().trim().min(1),
-    region: z.string().trim().min(1).default('garage'),
-    accessKeyId: z.string().trim().min(1),
-    secretAccessKey: z.string().trim().min(1),
+    endpoint: nonEmptyStringSchema,
+    bucket: nonEmptyStringSchema,
+    region: nonEmptyStringSchema.default('garage'),
+    accessKeyId: nonEmptyStringSchema,
+    secretAccessKey: nonEmptyStringSchema,
     attachmentUrlExpiresIn: z.coerce.number().positive().default(1800),
   }),
   firecrawl: z.object({
@@ -266,16 +258,25 @@ export const LotaRuntimeConfigSchema = z.object({
     }),
   threads: threadConfigSchema.default({}),
   agents: agentsConfigSchema,
-  toolProviders: z.custom<Record<string, unknown>>(isToolProviderRecord).optional(),
+  toolProviders: z.custom<ToolSet>(isToolSet, { error: 'toolProviders must be a tool registry object' }).optional(),
   extraSchemaFiles: z.array(z.custom<string | URL>(isStringOrUrl)).optional(),
   extraWorkers: z.custom<LotaRuntimeWorkerExtensions>(isWorkerExtensionRecord).optional(),
-  pluginRuntime: z.custom<Record<string, LotaPlugin>>(isPluginRuntimeRecord).optional(),
-  systemExecutors: z.custom<Record<string, SystemNodeExecutor>>(isSystemExecutorRecord).optional(),
+  pluginRuntime: objectRecordSchema<Record<string, LotaPlugin>>().optional(),
+  systemExecutors: objectRecordSchema<Record<string, SystemNodeExecutor>>().optional(),
   notificationService: z.custom<NotificationService>(isNotificationService).optional(),
-  runtimeAdapters: z.custom<LotaRuntimeAdapters>(isRecord).optional(),
-  turnHooks: z.custom<LotaRuntimeTurnHooks>(isRecord).optional(),
+  runtimeAdapters: objectRecordSchema<LotaRuntimeAdapters>().optional(),
+  turnHooks: objectRecordSchema<LotaRuntimeTurnHooks>().optional(),
   graphDesigner: z.custom<GraphDesigner>(isGraphDesigner).optional(),
   socialChat: z.custom<LotaRuntimeSocialChatConfig>(isSocialChatConfig).optional(),
+  observability: z
+    .object({
+      otlpBaseUrl: nonEmptyStringSchema.optional(),
+      otlpHeaders: stringRecordSchema.optional(),
+      serviceName: nonEmptyStringSchema.default('lota-sdk'),
+      serviceVersion: nonEmptyStringSchema.optional(),
+      devToolsUrl: nonEmptyStringSchema.optional(),
+    })
+    .default({ serviceName: 'lota-sdk' }),
 })
 
 export type LotaRuntimeConfig = z.input<typeof LotaRuntimeConfigSchema>
@@ -301,6 +302,7 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'AI_GATEWAY_KEY',
   'AI_EMBEDDING_MODEL',
   'OPENROUTER_API_KEY',
+  'AI_GATEWAY_MAX_CONCURRENCY',
   'S3_ENDPOINT',
   'S3_BUCKET',
   'S3_REGION',
@@ -313,28 +315,115 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'MEMORY_SEARCH_K',
   'MEMORY_RERANKER_STRATEGY',
   'MEMORY_RERANKER_MODEL_ID',
+  'OTLP_BASE_URL',
+  'OTLP_SERVICE_NAME',
+  'OTLP_SERVICE_VERSION',
+  'DEVTOOLS_URL',
 ])
 
-let runtimeConfig: ResolvedLotaRuntimeConfig | null = null
-
 export function parseLotaRuntimeConfig(config: LotaRuntimeConfig): ResolvedLotaRuntimeConfig {
   return LotaRuntimeConfigSchema.parse(config)
 }
 
-export function configureRuntimeConfig(config: ResolvedLotaRuntimeConfig): void {
-  runtimeConfig = config
+export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>): WorkerBootstrapEnv {
+  return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
 }
 
-export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
-  if (!runtimeConfig) {
-    throw new Error('Lota runtime config not configured. Call createLotaRuntime() first.')
-  }
+export const lotaRuntimeEnvConfig = Config.all({
+  surrealdbUrl: Config.string('SURREALDB_URL'),
+  surrealdbNamespace: Config.string('SURREALDB_NAMESPACE'),
+  surrealdbUser: Config.string('SURREALDB_USER'),
+  surrealdbPassword: Config.redacted('SURREALDB_PASSWORD'),
+  redisUrl: Config.string('REDIS_URL'),
+  aiGatewayUrl: Config.string('AI_GATEWAY_URL').pipe(Config.withDefault(DEFAULT_AI_GATEWAY_URL)),
+  aiGatewayKey: Config.redacted('AI_GATEWAY_KEY'),
+  aiEmbeddingModel: Config.string('AI_EMBEDDING_MODEL').pipe(Config.withDefault('openai/text-embedding-3-small')),
+  openRouterApiKey: Config.redacted('OPENROUTER_API_KEY').pipe(Config.option),
+  aiGatewayMaxConcurrency: Config.number('AI_GATEWAY_MAX_CONCURRENCY').pipe(Config.withDefault(8)),
+  s3Endpoint: Config.string('S3_ENDPOINT'),
+  s3Bucket: Config.string('S3_BUCKET'),
+  s3Region: Config.string('S3_REGION').pipe(Config.withDefault('garage')),
+  s3AccessKeyId: Config.redacted('S3_ACCESS_KEY_ID'),
+  s3SecretAccessKey: Config.redacted('S3_SECRET_ACCESS_KEY'),
+  attachmentUrlExpiresIn: Config.number('ATTACHMENT_URL_EXPIRES_IN').pipe(Config.withDefault(1800)),
+  firecrawlApiKey: Config.redacted('FIRECRAWL_API_KEY'),
+  firecrawlApiBaseUrl: Config.string('FIRECRAWL_API_BASE_URL').pipe(Config.option),
+  logLevel: Config.string('LOG_LEVEL').pipe(Config.withDefault('info')),
+  memorySearchK: Config.number('MEMORY_SEARCH_K').pipe(Config.withDefault(6)),
+  memoryRerankerStrategy: Config.string('MEMORY_RERANKER_STRATEGY').pipe(Config.withDefault('rerank')),
+  memoryRerankerModelId: Config.string('MEMORY_RERANKER_MODEL_ID').pipe(
+    Config.withDefault(OPENROUTER_FAST_RERANK_MODEL_ID),
+  ),
+  otlpBaseUrl: Config.string('OTLP_BASE_URL').pipe(Config.option),
+  otlpServiceName: Config.string('OTLP_SERVICE_NAME').pipe(Config.withDefault('lota-sdk')),
+  otlpServiceVersion: Config.string('OTLP_SERVICE_VERSION').pipe(Config.option),
+  devToolsUrl: Config.string('DEVTOOLS_URL').pipe(Config.option),
+})
 
-  return runtimeConfig
+export type LotaRuntimeEnvironmentOverrides = Omit<
+  LotaRuntimeConfig,
+  'database' | 'redis' | 'aiGateway' | 's3' | 'firecrawl' | 'logging' | 'memory'
+> & { logging?: LotaRuntimeConfig['logging']; memory?: LotaRuntimeConfig['memory'] }
+
+export function loadLotaRuntimeConfigFromEnv(
+  overrides: LotaRuntimeEnvironmentOverrides,
+  options: { configProvider?: ConfigProvider.ConfigProvider } = {},
+) {
+  return lotaRuntimeEnvConfig
+    .parse(options.configProvider ?? ConfigProvider.fromEnv())
+    .pipe(
+      Effect.map((env) =>
+        parseLotaRuntimeConfig({
+          ...overrides,
+          database: {
+            url: env.surrealdbUrl,
+            namespace: env.surrealdbNamespace,
+            username: env.surrealdbUser,
+            password: Redacted.value(env.surrealdbPassword),
+          },
+          redis: { url: env.redisUrl },
+          aiGateway: {
+            url: env.aiGatewayUrl,
+            key: Redacted.value(env.aiGatewayKey),
+            embeddingModel: env.aiEmbeddingModel,
+            maxConcurrency: env.aiGatewayMaxConcurrency,
+            ...(Option.isSome(env.openRouterApiKey)
+              ? { openRouterApiKey: Redacted.value(env.openRouterApiKey.value) }
+              : {}),
+          },
+          s3: {
+            endpoint: env.s3Endpoint,
+            bucket: env.s3Bucket,
+            region: env.s3Region,
+            accessKeyId: Redacted.value(env.s3AccessKeyId),
+            secretAccessKey: Redacted.value(env.s3SecretAccessKey),
+            attachmentUrlExpiresIn: env.attachmentUrlExpiresIn,
+          },
+          firecrawl: {
+            apiKey: Redacted.value(env.firecrawlApiKey),
+            ...(Option.isSome(env.firecrawlApiBaseUrl) ? { apiBaseUrl: env.firecrawlApiBaseUrl.value } : {}),
+          },
+          logging: overrides.logging ?? { level: z.enum(logLevelValues).parse(env.logLevel) },
+          memory: {
+            searchK: env.memorySearchK,
+            rerankerStrategy: env.memoryRerankerStrategy as MemoryRerankerStrategy,
+            rerankerModelId: env.memoryRerankerModelId,
+            ...overrides.memory,
+          },
+          observability: {
+            serviceName: env.otlpServiceName,
+            ...(Option.isSome(env.otlpBaseUrl) ? { otlpBaseUrl: env.otlpBaseUrl.value } : {}),
+            ...(Option.isSome(env.otlpServiceVersion) ? { serviceVersion: env.otlpServiceVersion.value } : {}),
+            ...(Option.isSome(env.devToolsUrl) ? { devToolsUrl: env.devToolsUrl.value } : {}),
+            ...overrides.observability,
+          },
+        }),
+      ),
+    )
 }
 
-export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>): WorkerBootstrapEnv {
-  return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
+export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
+  return getCurrentRuntime().runSync(Effect.service(RuntimeConfigServiceTag))
 }
 
 export type { LotaThreadConfig }

package/src/runtime/runtime-extensions.ts

@@ -8,6 +8,13 @@ import type {
 import type { ToolSet } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
+import { resolveLotaService } from '../effect/runtime'
+import {
+  RuntimeAdaptersServiceTag,
+  RuntimeWorkerExtensionsServiceTag,
+  ToolProvidersServiceTag,
+  TurnHooksServiceTag,
+} from '../effect/services'
 import type { ReadableUploadMetadata } from '../storage/attachment-types'
 import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
@@ -193,54 +200,45 @@ export interface LotaRuntimeAdapters {
   withWorkspaceMemoryLock?: <T>(workspaceId: string, fn: () => Promise<T>) => Promise<T>
 }
 
-interface RuntimeExtensionsState {
+interface RuntimeExtensionsAccessors {
   adapters: LotaRuntimeAdapters
   turnHooks: LotaRuntimeTurnHooks
   toolProviders: ToolSet
   extraWorkers: LotaRuntimeWorkerExtensions
 }
 
-const EMPTY_TOOLS = {} as ToolSet
+let runtimeExtensionsAccessors: RuntimeExtensionsAccessors | null = null
 
-let runtimeExtensionsState: RuntimeExtensionsState = {
-  adapters: {},
-  turnHooks: {},
-  toolProviders: EMPTY_TOOLS,
-  extraWorkers: {},
+export function configureRuntimeExtensionsAccessors(accessors: RuntimeExtensionsAccessors): void {
+  runtimeExtensionsAccessors = accessors
 }
 
-export function configureRuntimeExtensions(params: {
-  adapters?: LotaRuntimeAdapters
-  turnHooks?: LotaRuntimeTurnHooks
-  toolProviders?: ToolSet
-  extraWorkers?: LotaRuntimeWorkerExtensions
-}): void {
-  runtimeExtensionsState = {
-    adapters: params.adapters ?? {},
-    turnHooks: params.turnHooks ?? {},
-    toolProviders: params.toolProviders ?? EMPTY_TOOLS,
-    extraWorkers: params.extraWorkers ?? {},
-  }
+export function clearRuntimeExtensionsAccessors(): void {
+  runtimeExtensionsAccessors = null
 }
 
 export function getRuntimeAdapters(): LotaRuntimeAdapters {
-  return runtimeExtensionsState.adapters
+  return runtimeExtensionsAccessors?.adapters ?? resolveLotaService(RuntimeAdaptersServiceTag)
 }
 
 export function getTurnHooks(): LotaRuntimeTurnHooks {
-  return runtimeExtensionsState.turnHooks
+  return runtimeExtensionsAccessors?.turnHooks ?? resolveLotaService(TurnHooksServiceTag)
 }
 
 export function getToolProviders(): ToolSet {
-  return runtimeExtensionsState.toolProviders
+  return runtimeExtensionsAccessors?.toolProviders ?? resolveLotaService(ToolProvidersServiceTag)
 }
 
 export function getConfiguredPluginDatabaseConnector(): (() => Promise<void>) | undefined {
-  return runtimeExtensionsState.adapters.connectPluginDatabases
+  return getRuntimeAdapters().connectPluginDatabases
+}
+
+export function getExtraWorkers(): LotaRuntimeWorkerExtensions {
+  return runtimeExtensionsAccessors?.extraWorkers ?? resolveLotaService(RuntimeWorkerExtensionsServiceTag)
 }
 
-export async function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
-  const adapter = runtimeExtensionsState.adapters.withWorkspaceMemoryLock
+export function withConfiguredWorkspaceMemoryLock<T>(workspaceId: string, fn: () => Promise<T>): Promise<T> {
+  const adapter = getRuntimeAdapters().withWorkspaceMemoryLock
   if (!adapter) {
     return 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 { 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>
+  onFinalize: () => 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, onFinalize } =
+    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())
+      }).pipe(Effect.ensuring(Effect.sync(onFinalize))),
+    )
+    return disconnectPromise
+  }
+}