@lota-sdk/core 0.4.9 → 0.4.10

package/src/create-runtime.ts

@@ -1,281 +1,53 @@
-import type { ChatMessage } from '@lota-sdk/shared'
-import type { Context } from 'effect'
-import { Effect, Layer, ManagedRuntime } from 'effect'
-import { DevTools } from 'effect/unstable/devtools'
-import { FetchHttpClient } from 'effect/unstable/http'
-import { Otlp } from 'effect/unstable/observability'
+import { Effect, ManagedRuntime } from 'effect'
 import type { Subscriber } from 'resumable-stream/ioredis'
 
-import { AiGatewayLive } from './ai-gateway/ai-gateway'
-import { EmbeddingCacheLive } from './ai/embedding-cache'
-import { ensureRecordId } from './db/record-id'
 import { computeSchemaFingerprint } from './db/schema-fingerprint'
-import type { SurrealDBService } from './db/service'
 import { publishDatabaseBootstrapEffect } from './db/startup'
-import { TABLES } from './db/tables'
 import {
   buildInfrastructureLayer,
   clearLotaSdkRuntime,
   DatabaseServiceTag as EffectDatabaseService,
   RedisServiceTag as EffectRedisService,
-  runPromise,
   setLotaSdkRuntime,
 } from './effect'
-import type { AwaitableService, AwaitableValue } from './effect/awaitable-effect'
-import { toAwaitableService } from './effect/awaitable-effect'
-import { BadRequestError, ConfigurationError, NotFoundError, ServiceError } from './effect/errors'
+import { ConfigurationError, ServiceError } from './effect/errors'
 import { effectTryPromise } from './effect/helpers'
 import type { RedisConnectionManager } from './redis/connection'
-import { SharedThreadStreamSubscriberLive, SharedThreadStreamSubscriberTag } from './redis/stream-context'
-import type { isApprovalContinuationRequest } from './runtime/approval-continuation'
-import { routeThreadChatMessages } from './runtime/chat-request-routing'
-import { CompactionCoordinationLive } from './runtime/chat-run-orchestration'
-import { HelperModelLive } from './runtime/helper-model'
-import type { LotaPlugin, PluginLifecycleServices, SystemNodeExecutor } from './runtime/plugin-types'
+import { SharedThreadStreamSubscriberTag } from './redis/stream-context'
+import { buildDomainServiceLayer } from './runtime/domain-layer'
+import type { LotaPlugin, SystemNodeExecutor } from './runtime/plugin-types'
+import { clearRuntimeModuleAccessors, configureRuntimeModuleAccessors } from './runtime/runtime-accessors'
 import { LOTA_RUNTIME_ENV_KEYS, loadLotaRuntimeConfigFromEnv, parseLotaRuntimeConfig } from './runtime/runtime-config'
 import type { LotaRuntimeConfig, ResolvedLotaRuntimeConfig } from './runtime/runtime-config'
+import {
+  createPluginDatabaseConnector,
+  createPluginDatabaseDisconnector,
+  createRuntimeDisconnect,
+} from './runtime/runtime-lifecycle'
+import { buildRuntimeServiceSurface } from './runtime/runtime-services'
+import type { LotaRuntimeLota, LotaRuntimeServices } from './runtime/runtime-services'
+import { acquireRuntimeTokenEffect, isRuntimeTokenActive, releaseRuntimeToken } from './runtime/runtime-token'
 import type { LotaRuntimeWorkers } from './runtime/runtime-worker-registry'
 import { buildRuntimeWorkerRegistry } from './runtime/runtime-worker-registry'
 import type { LotaRuntimeSocialChat } from './runtime/social-chat/social-chat'
 import { createSocialChatRuntime } from './runtime/social-chat/social-chat'
-// ── Service Layer & Tag imports ────────────────────────────────────────
-import { AgentActivityServiceLive, AgentActivityServiceTag } from './services/agent-activity.service'
-import { AgentExecutorServiceLive } from './services/agent-executor.service'
-import { ArtifactServiceLive, ArtifactServiceTag } from './services/artifact.service'
-import { AttachmentServiceLive, AttachmentServiceTag } from './services/attachment.service'
-import { AutonomousJobServiceLive, AutonomousJobServiceTag } from './services/autonomous-job.service'
-import { ChatRunRegistryLive } from './services/chat-run-registry.service'
-import { ContextCompactionServiceLive, ContextCompactionServiceTag } from './services/context-compaction.service'
-import { DocumentChunkServiceLive, DocumentChunkServiceTag } from './services/document-chunk.service'
-import { ExecutionPlanServiceLive, ExecutionPlanServiceTag } from './services/execution-plan/execution-plan.service'
-import { FeedbackLoopServiceLive } from './services/feedback-loop.service'
-import { GlobalOrchestratorServiceLive } from './services/global-orchestrator.service'
-import { InstitutionalMemoryServiceLive } from './services/institutional-memory.service'
-import { LearnedSkillServiceLive, LearnedSkillServiceTag } from './services/learned-skill.service'
-import { MemoryServiceLive, MemoryServiceTag } from './services/memory/memory.service'
-import { RerankServiceLive, RerankServiceTag } from './services/memory/rerank.service'
-import { MonitoringWindowServiceLive } from './services/monitoring-window.service'
-import { MutatingApprovalServiceLive, MutatingApprovalServiceTag } from './services/mutating-approval.service'
-import { NodeWorkspaceServiceLive } from './services/node-workspace.service'
-import { NotificationServiceLive } from './services/notification.service'
-import { OrganizationMemberServiceLive, OrganizationMemberServiceTag } from './services/organization-member.service'
-import { OrganizationServiceLive, OrganizationServiceTag } from './services/organization.service'
-import { OwnershipDispatcherServiceLive } from './services/ownership-dispatcher.service'
-import {
-  PlanAgentHeartbeatServiceLive,
-  PlanAgentHeartbeatServiceTag,
-} from './services/plan/plan-agent-heartbeat.service'
-import { PlanAgentQueryServiceLive, PlanAgentQueryServiceTag } from './services/plan/plan-agent-query.service'
-import { PlanApprovalServiceLive } from './services/plan/plan-approval.service'
-import { PlanArtifactServiceLive } from './services/plan/plan-artifact.service'
-import { PlanBuilderServiceLive } from './services/plan/plan-builder.service'
-import { PlanCheckpointServiceLive } from './services/plan/plan-checkpoint.service'
-import { PlanCompilerServiceLive } from './services/plan/plan-compiler.service'
-import { PlanCoordinationServiceLive, PlanCoordinationServiceTag } from './services/plan/plan-coordination.service'
-import { PlanCycleServiceLive, PlanCycleServiceTag } from './services/plan/plan-cycle.service'
-import { PlanDeadlineServiceLive, PlanDeadlineServiceTag } from './services/plan/plan-deadline.service'
-import { PlanEventDeliveryServiceLive } from './services/plan/plan-event-delivery.service'
-import { PlanExecutorServiceLive, PlanExecutorServiceTag } from './services/plan/plan-executor.service'
-import { PlanRunServiceLive, PlanRunServiceTag } from './services/plan/plan-run.service'
-import { PlanSchedulerServiceLive, PlanSchedulerServiceTag } from './services/plan/plan-scheduler.service'
-import { PlanTemplateServiceLive, PlanTemplateServiceTag } from './services/plan/plan-template.service'
-import { PlanValidatorServiceLive } from './services/plan/plan-validator.service'
-import { PlanWorkspaceServiceLive } from './services/plan/plan-workspace.service'
-import { PluginExecutorServiceLive } from './services/plugin-executor.service'
-import { QualityMetricsServiceLive } from './services/quality-metrics.service'
-import { QueueJobServiceLive } from './services/queue-job.service'
-import { RecentActivityTitleServiceLive, RecentActivityTitleServiceTag } from './services/recent-activity-title.service'
-import { RecentActivityServiceLive, RecentActivityServiceTag } from './services/recent-activity.service'
-import { SkillResolverServiceLive } from './services/skill-resolver.service'
-import type { makeSocialChatHistoryService } from './services/social-chat-history.service'
-import { SocialChatHistoryServiceLive, SocialChatHistoryServiceTag } from './services/social-chat-history.service'
-import { getBuiltInSystemExecutors, SystemExecutorServiceLive } from './services/system-executor.service'
-import { ThreadMessageServiceLive, ThreadMessageServiceTag } from './services/thread/thread-message.service'
-import { ThreadTitleServiceLive, ThreadTitleServiceTag } from './services/thread/thread-title.service'
-import type {
-  createThreadApprovalContinuationStream,
-  createThreadNativeToolApprovalStream,
-  createThreadTurnStream,
-  runThreadTurnInBackground,
-  triggerPlanNodeTurn,
-} from './services/thread/thread-turn'
-import {
-  isApprovalContinuationRequest as isApprovalContinuationRequestFn,
-  ThreadTurnServiceLive,
-  ThreadTurnServiceTag,
-} from './services/thread/thread-turn'
-import { ThreadTurnPreparationServiceLive } from './services/thread/thread-turn-preparation.service'
-import { ThreadServiceLive, ThreadServiceTag } from './services/thread/thread.service'
-import { UserServiceLive, UserServiceTag } from './services/user.service'
-import { WriteIntentValidatorServiceLive } from './services/write-intent-validator.service'
-import { AttachmentStorageServiceLive } from './storage/attachment-storage.service'
-import {
-  GeneratedDocumentStorageServiceLive,
-  GeneratedDocumentStorageServiceTag,
-} from './storage/generated-document-storage.service'
-import { FirecrawlLive } from './tools/firecrawl-client'
-
-// ── Type helpers ────────────────────────────────────────────────────────
-type Svc<T extends { readonly Service: unknown }> = T['Service']
-type HostSvc<T extends { readonly Service: object }> = AwaitableService<T['Service']>
-type AwaitableThreadService = HostSvc<typeof ThreadServiceTag> &
-  Pick<Svc<typeof ThreadServiceTag>, 'withActiveRunLease'>
-type AwaitableDocumentChunkService = HostSvc<typeof DocumentChunkServiceTag> &
-  Pick<Svc<typeof DocumentChunkServiceTag>, 'syncVersionedChunks'>
-
-type ArchiveSdkThread = (
-  threadId: Parameters<Svc<typeof ThreadServiceTag>['updateStatus']>[0],
-  status?: 'archived',
-) => ReturnType<Svc<typeof ThreadServiceTag>['updateStatus']>
-
-type UnarchiveSdkThread = (
-  threadId: Parameters<Svc<typeof ThreadServiceTag>['updateStatus']>[0],
-  status?: 'active',
-) => ReturnType<Svc<typeof ThreadServiceTag>['updateStatus']>
-
-let activeRuntimeToken: symbol | null = null
-
-function claimRuntimeToken(): Effect.Effect<symbol, ConfigurationError> {
-  return Effect.gen(function* () {
-    if (activeRuntimeToken) {
-      return yield* new ConfigurationError({
-        message: 'createLotaRuntime() is process-scoped. Disconnect the active runtime before creating another one.',
-      })
-    }
-
-    const token = Symbol('lota-runtime')
-    activeRuntimeToken = token
-    return token
-  })
-}
+import { LearnedSkillServiceTag } from './services/learned-skill.service'
+import { MemoryServiceTag } from './services/memory/memory.service'
+import { SocialChatHistoryServiceTag } from './services/social-chat-history.service'
+import { getBuiltInSystemExecutors } from './services/system-executor.service'
+import { ThreadTurnServiceTag } from './services/thread/thread-turn'
 
-function releaseRuntimeToken(token: symbol) {
-  if (activeRuntimeToken === token) {
-    activeRuntimeToken = null
-  }
-}
-
-function buildObservabilityLayer(runtimeConfig: ResolvedLotaRuntimeConfig): Layer.Layer<never> {
-  let layer = Layer.empty
-  const observability = runtimeConfig.observability
-
-  if (observability.otlpBaseUrl) {
-    layer = Layer.merge(
-      layer,
-      Otlp.layerJson({
-        baseUrl: observability.otlpBaseUrl,
-        resource: {
-          serviceName: observability.serviceName,
-          ...(observability.serviceVersion ? { serviceVersion: observability.serviceVersion } : {}),
-        },
-        ...(observability.otlpHeaders ? { headers: observability.otlpHeaders } : {}),
-      }).pipe(Layer.provide(FetchHttpClient.layer)),
-    )
-  }
-
-  if (observability.devToolsUrl && Bun.env.NODE_ENV !== 'production') {
-    layer = Layer.merge(layer, DevTools.layer(observability.devToolsUrl))
-  }
-
-  return layer
-}
+// Re-exported for consumers that reason about the runtime slot without
+// instantiating one (e.g., diagnostic harnesses).
+export { isRuntimeTokenActive }
 
 export interface LotaRuntime {
   /** Run an Effect as a Promise through the SDK runtime (carries OTLP context). */
   runPromise: <A, E>(effect: Effect.Effect<A, E>, options?: { readonly signal?: AbortSignal }) => Promise<A>
   /** Run an Effect synchronously through the SDK runtime. */
   runSync: <A, E>(effect: Effect.Effect<A, E>) => A
-  services: {
-    database: SurrealDBService
-    redis: RedisConnectionManager
-    closeRedisConnection: () => Promise<void>
-    agentActivityService: HostSvc<typeof AgentActivityServiceTag>
-    artifactService: HostSvc<typeof ArtifactServiceTag>
-    attachmentService: HostSvc<typeof AttachmentServiceTag>
-    autonomousJobService: HostSvc<typeof AutonomousJobServiceTag>
-    contextCompactionService: HostSvc<typeof ContextCompactionServiceTag>
-    documentChunkService: AwaitableDocumentChunkService
-    generatedDocumentStorageService: HostSvc<typeof GeneratedDocumentStorageServiceTag>
-    memoryService: HostSvc<typeof MemoryServiceTag>
-    rerankService: HostSvc<typeof RerankServiceTag>
-    verifyMutatingApproval: HostSvc<typeof MutatingApprovalServiceTag>
-    organizationService: HostSvc<typeof OrganizationServiceTag>
-    organizationMemberService: HostSvc<typeof OrganizationMemberServiceTag>
-    userService: HostSvc<typeof UserServiceTag>
-    recentActivityService: HostSvc<typeof RecentActivityServiceTag>
-    recentActivityTitleService: HostSvc<typeof RecentActivityTitleServiceTag>
-    socialChatHistoryService: ReturnType<typeof makeSocialChatHistoryService>
-    executionPlanService: HostSvc<typeof ExecutionPlanServiceTag>
-    planDeadlineService: HostSvc<typeof PlanDeadlineServiceTag>
-    planExecutorService: HostSvc<typeof PlanExecutorServiceTag>
-    planRunService: HostSvc<typeof PlanRunServiceTag>
-    planTemplateService: HostSvc<typeof PlanTemplateServiceTag>
-    planCoordinationService: HostSvc<typeof PlanCoordinationServiceTag>
-    planSchedulerService: HostSvc<typeof PlanSchedulerServiceTag>
-    planAgentHeartbeatService: HostSvc<typeof PlanAgentHeartbeatServiceTag>
-    planAgentQueryService: HostSvc<typeof PlanAgentQueryServiceTag>
-    planCycleService: HostSvc<typeof PlanCycleServiceTag>
-    threadMessageService: HostSvc<typeof ThreadMessageServiceTag>
-    threadService: AwaitableThreadService
-    threadTitleService: HostSvc<typeof ThreadTitleServiceTag>
-    createThreadApprovalContinuationStream: typeof createThreadApprovalContinuationStream
-    createThreadNativeToolApprovalStream: typeof createThreadNativeToolApprovalStream
-    createThreadTurnStream: typeof createThreadTurnStream
-    isApprovalContinuationRequest: typeof isApprovalContinuationRequest
-    runThreadTurnInBackground: typeof runThreadTurnInBackground
-    triggerPlanNodeTurn: typeof triggerPlanNodeTurn
-  }
-  lota: {
-    organizations: {
-      create: AwaitableValue<Svc<typeof OrganizationServiceTag>['createOrganization']>
-      upsert: AwaitableValue<Svc<typeof OrganizationServiceTag>['upsertOrganization']>
-      get: AwaitableValue<Svc<typeof OrganizationServiceTag>['getOrganization']>
-      list: AwaitableValue<Svc<typeof OrganizationServiceTag>['listOrganizations']>
-      update: AwaitableValue<Svc<typeof OrganizationServiceTag>['updateOrganization']>
-      delete: AwaitableValue<Svc<typeof OrganizationServiceTag>['deleteOrganization']>
-    }
-    users: {
-      upsert: AwaitableValue<Svc<typeof UserServiceTag>['upsertUser']>
-      get: AwaitableValue<Svc<typeof UserServiceTag>['getUser']>
-      list: AwaitableValue<Svc<typeof UserServiceTag>['listUsers']>
-      update: AwaitableValue<Svc<typeof UserServiceTag>['updateUser']>
-      delete: AwaitableValue<Svc<typeof UserServiceTag>['deleteUser']>
-    }
-    memberships: {
-      add: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['addMembership']>
-      listForOrganization: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['listMembershipsForOrganization']>
-      listForUser: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['listMembershipsForUser']>
-      remove: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['removeMembership']>
-      isMember: AwaitableValue<Svc<typeof OrganizationMemberServiceTag>['isMember']>
-    }
-    threads: {
-      create: AwaitableValue<Svc<typeof ThreadServiceTag>['createThread']>
-      list: AwaitableValue<Svc<typeof ThreadServiceTag>['listThreads']>
-      get: AwaitableValue<Svc<typeof ThreadServiceTag>['getThread']>
-      update: AwaitableValue<Svc<typeof ThreadServiceTag>['updateTitle']>
-      archive: AwaitableValue<ArchiveSdkThread>
-      unarchive: AwaitableValue<UnarchiveSdkThread>
-      delete: AwaitableValue<Svc<typeof ThreadServiceTag>['deleteThread']>
-      stop: AwaitableValue<Svc<typeof ThreadServiceTag>['stopActiveRun']>
-      listMessages: AwaitableValue<Svc<typeof ThreadMessageServiceTag>['listMessageHistoryPage']>
-      getMessage: (params: { threadId: string; messageId: string }) => Promise<ChatMessage>
-      sendMessage: (params: {
-        threadId: string
-        organizationId: string
-        userId: string
-        userName: string
-        messages: Parameters<typeof routeThreadChatMessages>[0]
-      }) => Promise<Awaited<ReturnType<typeof createThreadTurnStream>>>
-      continueApproval: (params: {
-        threadId: string
-        organizationId: string
-        userId: string
-        userName: string
-        messages: Parameters<typeof routeThreadChatMessages>[0]
-      }) => Promise<Awaited<ReturnType<typeof createThreadApprovalContinuationStream>>>
-      uploadAttachment: AwaitableValue<Svc<typeof AttachmentServiceTag>['uploadThreadAttachment']>
-    }
-  }
+  services: LotaRuntimeServices
+  lota: LotaRuntimeLota
   redis: {
     manager: RedisConnectionManager
     subscriber: Subscriber
@@ -310,7 +82,9 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
 
   return Effect.runPromise(
     Effect.gen(function* () {
-      runtimeToken = yield* claimRuntimeToken()
+      // Fail fast if another runtime is already active in this process.
+      runtimeToken = yield* acquireRuntimeTokenEffect()
+
       const resolvedConfig = parseLotaRuntimeConfig(config)
       const systemExecutors = { ...getBuiltInSystemExecutors(), ...resolvedConfig.systemExecutors }
       const runtimeConfig = { ...resolvedConfig, systemExecutors } satisfies ResolvedLotaRuntimeConfig
@@ -327,121 +101,14 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
         ? { ...runtimeConfig.agents.displayNames, [socialChatAgentId]: socialChatAgentDisplayName }
         : runtimeConfig.agents.displayNames
 
-      // ── Infrastructure layers ───────────────────────────────────────────
-      const infrastructureLayer = buildInfrastructureLayer(runtimeConfig, {
-        resolvedAgentDisplayNames,
-        observabilityLayer: buildObservabilityLayer(runtimeConfig),
-      })
-
-      // ── Domain service layers ───────────────────────────────────────────
-      function provide<A, E, R extends RCtx, RCtx, E2>(
-        layer: Layer.Layer<A, E, R>,
-        ctx: Layer.Layer<RCtx, E2, never>,
-      ): Layer.Layer<A, E | E2, never> {
-        return Layer.provideMerge(ctx)(layer)
-      }
-
-      const tier0 = provide(
-        Layer.mergeAll(
-          ChatRunRegistryLive,
-          CompactionCoordinationLive,
-          DocumentChunkServiceLive,
-          NodeWorkspaceServiceLive,
-          NotificationServiceLive,
-          PlanArtifactServiceLive,
-          PlanBuilderServiceLive,
-          WriteIntentValidatorServiceLive,
-        ),
-        infrastructureLayer,
-      )
-      const ctx0 = Layer.mergeAll(
-        infrastructureLayer,
-        provide(Layer.mergeAll(AiGatewayLive, EmbeddingCacheLive, FirecrawlLive, HelperModelLive), infrastructureLayer),
-        tier0,
-      )
-
-      const tier1 = provide(
-        Layer.mergeAll(
-          SharedThreadStreamSubscriberLive,
-          AgentExecutorServiceLive,
-          AttachmentStorageServiceLive,
-          GeneratedDocumentStorageServiceLive,
-          LearnedSkillServiceLive,
-          OrganizationServiceLive,
-          OrganizationMemberServiceLive,
-          PlanApprovalServiceLive,
-          PlanRunServiceLive,
-          PlanSchedulerServiceLive,
-          PlanWorkspaceServiceLive,
-          PluginExecutorServiceLive,
-          QualityMetricsServiceLive,
-          QueueJobServiceLive,
-          RecentActivityServiceLive,
-          RerankServiceLive,
-          SocialChatHistoryServiceLive,
-          SystemExecutorServiceLive,
-          ThreadMessageServiceLive,
-          UserServiceLive,
-        ),
-        ctx0,
-      )
-      const ctx1 = Layer.mergeAll(ctx0, tier1)
-
-      const tier2 = provide(
-        Layer.mergeAll(
-          ArtifactServiceLive,
-          AttachmentServiceLive,
-          ContextCompactionServiceLive,
-          FeedbackLoopServiceLive,
-          InstitutionalMemoryServiceLive,
-          MemoryServiceLive,
-          MonitoringWindowServiceLive,
-          MutatingApprovalServiceLive,
-          PlanAgentQueryServiceLive,
-          PlanCheckpointServiceLive,
-          PlanCoordinationServiceLive,
-          PlanEventDeliveryServiceLive,
-          SkillResolverServiceLive,
-          RecentActivityTitleServiceLive,
-        ),
-        ctx1,
-      )
-      const ctx2 = Layer.mergeAll(ctx1, tier2)
-
-      const tier3 = provide(Layer.mergeAll(PlanValidatorServiceLive, ThreadServiceLive), ctx2)
-      const ctx3 = Layer.mergeAll(ctx2, tier3)
-
-      const tier4 = provide(Layer.mergeAll(PlanCompilerServiceLive, ThreadTitleServiceLive), ctx3)
-      const ctx4 = Layer.mergeAll(ctx3, tier4)
-
-      const tier5 = provide(PlanExecutorServiceLive, ctx4)
-      const ctx5 = Layer.mergeAll(ctx4, tier5)
-
-      const tier6 = provide(
-        Layer.mergeAll(OwnershipDispatcherServiceLive, PlanAgentHeartbeatServiceLive, PlanDeadlineServiceLive),
-        ctx5,
-      )
-      const ctx6 = Layer.mergeAll(ctx5, tier6)
-
-      const tier7 = provide(Layer.mergeAll(ExecutionPlanServiceLive, GlobalOrchestratorServiceLive), ctx6)
-      const ctx7 = Layer.mergeAll(ctx6, tier7)
-
-      const tier8 = provide(
-        Layer.mergeAll(
-          PlanTemplateServiceLive,
-          AutonomousJobServiceLive,
-          AgentActivityServiceLive,
-          ThreadTurnPreparationServiceLive,
-        ),
-        ctx7,
-      )
-      const ctx8 = Layer.mergeAll(ctx7, tier8)
-
-      const tier9 = provide(Layer.mergeAll(PlanCycleServiceLive, ThreadTurnServiceLive), ctx8)
-      const fullLayer = Layer.mergeAll(ctx8, tier9)
+      // ── Infrastructure + domain layer composition ─────────────────────
+      const infrastructureLayer = buildInfrastructureLayer(runtimeConfig, { resolvedAgentDisplayNames })
+      const fullLayer = buildDomainServiceLayer(infrastructureLayer)
 
       const managedRuntime = ManagedRuntime.make(fullLayer)
       effectRuntime = managedRuntime
+
+      // Eagerly resolve the services the outer entrypoint needs directly.
       const resolvedServices = yield* Effect.tryPromise({
         try: () =>
           managedRuntime.runPromise(
@@ -474,15 +141,9 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
       } = resolvedServices
 
       setLotaSdkRuntime(managedRuntime)
+      configureRuntimeModuleAccessors({ managedRuntime, runtimeConfig, redisManager })
 
-      type RuntimeServices = Layer.Success<typeof fullLayer>
-      const resolve = <I extends RuntimeServices, T>(tag: Context.Key<I, T>): T =>
-        managedRuntime.runSync(Effect.service(tag))
-      const resolveAwaitableService = <I extends RuntimeServices, T extends object>(
-        tag: Context.Key<I, T>,
-      ): AwaitableService<T> =>
-        toAwaitableService(resolve(tag), { runPromise: (effect) => managedRuntime.runPromise(effect) })
-
+      // ── Schema + plugin + worker + social-chat composition ────────────
       const pluginRuntime = runtimeConfig.pluginRuntime ?? {}
       const pluginContributions = Object.values(pluginRuntime).map((plugin) => plugin.contributions)
       const hostContributionSchemaFiles = pluginContributions.flatMap((plugin) => plugin.schemaFiles)
@@ -493,8 +154,16 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
       ]
       const contributionEnvKeys = [...LOTA_RUNTIME_ENV_KEYS, ...pluginContributions.flatMap((plugin) => plugin.envKeys)]
       const connectedPluginDatabases = new Set<string>()
-      const connectPluginDatabases = createPluginDatabaseConnector(pluginRuntime, connectedPluginDatabases)
-      const disconnectPluginDatabases = createPluginDatabaseDisconnector(pluginRuntime, connectedPluginDatabases)
+      const connectPluginDatabases = createPluginDatabaseConnector(
+        managedRuntime,
+        pluginRuntime,
+        connectedPluginDatabases,
+      )
+      const disconnectPluginDatabases = createPluginDatabaseDisconnector(
+        managedRuntime,
+        pluginRuntime,
+        connectedPluginDatabases,
+      )
       const workers = buildRuntimeWorkerRegistry(runtimeConfig.extraWorkers)
       const socialChat = createSocialChatRuntime({
         redisClient: redisManager.getConnection() as unknown as Parameters<
@@ -503,210 +172,30 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
         socialChat: runtimeConfig.socialChat,
         services: { learnedSkillService, memoryService, socialChatHistoryService },
       })
+      const currentContext = yield* Effect.context()
+      const runPromiseWithCurrentContext = Effect.runPromiseWith(currentContext)
 
-      const services: LotaRuntime['services'] = {
-        database: db,
-        redis: redisManager,
-        closeRedisConnection: () => runPromise(effectTryPromise(() => redisManager.closeConnection())),
-        get agentActivityService() {
-          return resolveAwaitableService(AgentActivityServiceTag)
-        },
-        get artifactService() {
-          return resolveAwaitableService(ArtifactServiceTag)
-        },
-        get attachmentService() {
-          return resolveAwaitableService(AttachmentServiceTag)
-        },
-        get autonomousJobService() {
-          return resolveAwaitableService(AutonomousJobServiceTag)
-        },
-        get contextCompactionService() {
-          return resolveAwaitableService(ContextCompactionServiceTag)
-        },
-        get documentChunkService() {
-          return resolveAwaitableService(DocumentChunkServiceTag) as AwaitableDocumentChunkService
-        },
-        get generatedDocumentStorageService() {
-          return resolveAwaitableService(GeneratedDocumentStorageServiceTag)
-        },
-        get memoryService() {
-          return resolveAwaitableService(MemoryServiceTag)
-        },
-        get rerankService() {
-          return resolveAwaitableService(RerankServiceTag)
-        },
-        get verifyMutatingApproval() {
-          return resolveAwaitableService(MutatingApprovalServiceTag)
-        },
-        get organizationService() {
-          return resolveAwaitableService(OrganizationServiceTag)
-        },
-        get organizationMemberService() {
-          return resolveAwaitableService(OrganizationMemberServiceTag)
-        },
-        get userService() {
-          return resolveAwaitableService(UserServiceTag)
-        },
-        get recentActivityService() {
-          return resolveAwaitableService(RecentActivityServiceTag)
-        },
-        get recentActivityTitleService() {
-          return resolveAwaitableService(RecentActivityTitleServiceTag)
-        },
+      // ── Service surface (eager, plain-property) ───────────────────────
+      const { services, lota } = buildRuntimeServiceSurface({
+        managedRuntime,
+        db,
+        redisManager,
+        sharedSubscriber,
+        threadTurnService,
         socialChatHistoryService,
-        get executionPlanService() {
-          return resolveAwaitableService(ExecutionPlanServiceTag)
-        },
-        get planDeadlineService() {
-          return resolveAwaitableService(PlanDeadlineServiceTag)
-        },
-        get planExecutorService() {
-          return resolveAwaitableService(PlanExecutorServiceTag)
-        },
-        get planRunService() {
-          return resolveAwaitableService(PlanRunServiceTag)
-        },
-        get planTemplateService() {
-          return resolveAwaitableService(PlanTemplateServiceTag)
-        },
-        get planCoordinationService() {
-          return resolveAwaitableService(PlanCoordinationServiceTag)
-        },
-        get planSchedulerService() {
-          return resolveAwaitableService(PlanSchedulerServiceTag)
-        },
-        get planAgentHeartbeatService() {
-          return resolveAwaitableService(PlanAgentHeartbeatServiceTag)
-        },
-        get planAgentQueryService() {
-          return resolveAwaitableService(PlanAgentQueryServiceTag)
-        },
-        get planCycleService() {
-          return resolveAwaitableService(PlanCycleServiceTag)
-        },
-        get threadMessageService() {
-          return resolveAwaitableService(ThreadMessageServiceTag)
-        },
-        get threadService() {
-          return resolveAwaitableService(ThreadServiceTag) as AwaitableThreadService
-        },
-        get threadTitleService() {
-          return resolveAwaitableService(ThreadTitleServiceTag)
-        },
-        createThreadApprovalContinuationStream: (...args) =>
-          runPromise(threadTurnService.createThreadApprovalContinuationStream(...args)),
-        createThreadNativeToolApprovalStream: (...args) =>
-          runPromise(threadTurnService.createThreadNativeToolApprovalStream(...args)),
-        createThreadTurnStream: (...args) => runPromise(threadTurnService.createThreadTurnStream(...args)),
-        isApprovalContinuationRequest: isApprovalContinuationRequestFn,
-        runThreadTurnInBackground: (...args) => runPromise(threadTurnService.runThreadTurnInBackground(...args)),
-        triggerPlanNodeTurn: (...args) => runPromise(threadTurnService.triggerPlanNodeTurn(...args)),
-      }
-
-      const lota: LotaRuntime['lota'] = {
-        organizations: {
-          create: (...args) => resolveAwaitableService(OrganizationServiceTag).createOrganization(...args),
-          upsert: (...args) => resolveAwaitableService(OrganizationServiceTag).upsertOrganization(...args),
-          get: (...args) => resolveAwaitableService(OrganizationServiceTag).getOrganization(...args),
-          list: (...args) => resolveAwaitableService(OrganizationServiceTag).listOrganizations(...args),
-          update: (...args) => resolveAwaitableService(OrganizationServiceTag).updateOrganization(...args),
-          delete: (...args) => resolveAwaitableService(OrganizationServiceTag).deleteOrganization(...args),
-        },
-        users: {
-          upsert: (...args) => resolveAwaitableService(UserServiceTag).upsertUser(...args),
-          get: (...args) => resolveAwaitableService(UserServiceTag).getUser(...args),
-          list: (...args) => resolveAwaitableService(UserServiceTag).listUsers(...args),
-          update: (...args) => resolveAwaitableService(UserServiceTag).updateUser(...args),
-          delete: (...args) => resolveAwaitableService(UserServiceTag).deleteUser(...args),
-        },
-        memberships: {
-          add: (...args) => resolveAwaitableService(OrganizationMemberServiceTag).addMembership(...args),
-          listForOrganization: (...args) =>
-            resolveAwaitableService(OrganizationMemberServiceTag).listMembershipsForOrganization(...args),
-          listForUser: (...args) =>
-            resolveAwaitableService(OrganizationMemberServiceTag).listMembershipsForUser(...args),
-          remove: (...args) => resolveAwaitableService(OrganizationMemberServiceTag).removeMembership(...args),
-          isMember: (...args) => resolveAwaitableService(OrganizationMemberServiceTag).isMember(...args),
-        },
-        threads: {
-          create: (...args) => resolveAwaitableService(ThreadServiceTag).createThread(...args),
-          list: (...args) => resolveAwaitableService(ThreadServiceTag).listThreads(...args),
-          get: (...args) => resolveAwaitableService(ThreadServiceTag).getThread(...args),
-          update: (...args) => resolveAwaitableService(ThreadServiceTag).updateTitle(...args),
-          archive: (threadId, status = 'archived') =>
-            resolveAwaitableService(ThreadServiceTag).updateStatus(threadId, status),
-          unarchive: (threadId, status = 'active') =>
-            resolveAwaitableService(ThreadServiceTag).updateStatus(threadId, status),
-          delete: (...args) => resolveAwaitableService(ThreadServiceTag).deleteThread(...args),
-          stop: (...args) => resolveAwaitableService(ThreadServiceTag).stopActiveRun(...args),
-          listMessages: (...args) => resolveAwaitableService(ThreadMessageServiceTag).listMessageHistoryPage(...args),
-          getMessage: ({ threadId, messageId }) =>
-            runPromise(
-              Effect.gen(function* () {
-                const messages = yield* resolve(ThreadMessageServiceTag).listMessages(
-                  ensureRecordId(threadId, TABLES.THREAD),
-                )
-                const message = messages.find((candidate: ChatMessage) => candidate.id === messageId)
-                if (!message) {
-                  return yield* new NotFoundError({
-                    resource: 'Thread message',
-                    id: messageId,
-                    message: `Thread message not found: ${messageId}`,
-                  })
-                }
-                return message
-              }),
-            ),
-          sendMessage: ({ threadId, organizationId, userId, userName, messages }) =>
-            runPromise(
-              Effect.gen(function* () {
-                const threadRef = ensureRecordId(threadId, TABLES.THREAD)
-                const thread = yield* resolve(ThreadServiceTag).getThread(threadRef)
-                const routed = routeThreadChatMessages(messages)
-                if (routed.kind !== 'turn') {
-                  return yield* new BadRequestError({
-                    message: routed.kind === 'invalid' ? routed.message : 'Expected a user turn payload.',
-                  })
-                }
-
-                return yield* threadTurnService.createThreadTurnStream({
-                  thread,
-                  threadRef,
-                  orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
-                  userRef: ensureRecordId(userId, TABLES.USER),
-                  userName,
-                  inputMessage: routed.inputMessage,
-                })
-              }),
-            ),
-          continueApproval: ({ threadId, organizationId, userId, userName, messages }) =>
-            runPromise(
-              Effect.gen(function* () {
-                const threadRef = ensureRecordId(threadId, TABLES.THREAD)
-                const thread = yield* resolve(ThreadServiceTag).getThread(threadRef)
-                const routed = routeThreadChatMessages(messages)
-                if (routed.kind !== 'approval-continuation') {
-                  return yield* new BadRequestError({
-                    message:
-                      routed.kind === 'invalid' ? routed.message : 'Expected approval continuation messages payload.',
-                  })
-                }
+      })
 
-                return yield* threadTurnService.createThreadApprovalContinuationStream({
-                  thread,
-                  threadRef,
-                  orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
-                  userRef: ensureRecordId(userId, TABLES.USER),
-                  userName,
-                  approvalMessages: routed.approvalMessages,
-                })
-              }),
-            ),
-          uploadAttachment: (...args) => resolveAwaitableService(AttachmentServiceTag).uploadThreadAttachment(...args),
+      const disconnect = createRuntimeDisconnect({
+        managedRuntime,
+        runPromiseWithCurrentContext,
+        socialChatShutdown: () => socialChat.shutdown(),
+        disconnectPluginDatabases,
+        onFinalize: () => {
+          clearRuntimeModuleAccessors()
+          clearLotaSdkRuntime()
+          if (runtimeToken) releaseRuntimeToken(runtimeToken)
         },
-      }
-
-      let disconnectPromise: Promise<void> | null = null
+      })
 
       const lotaRuntime: LotaRuntime = {
         runPromise: (effect, options) => managedRuntime.runPromise(effect, options),
@@ -718,7 +207,7 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
           subscriber: sharedSubscriber.subscriber,
           getConnection: () => redisManager.getConnection(),
           getConnectionForBullMQ: () => redisManager.getConnectionForBullMQ(),
-          closeConnection: () => runPromise(effectTryPromise(() => redisManager.closeConnection())),
+          closeConnection: () => managedRuntime.runPromise(effectTryPromise(() => redisManager.closeConnection())),
         },
         workers,
         socialChat,
@@ -727,9 +216,9 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
         config: runtimeConfig,
         plugins: pluginRuntime,
         systemExecutors,
-        connectPluginDatabases: () => runPromise(effectTryPromise(() => connectPluginDatabases())),
+        connectPluginDatabases,
         connect: () =>
-          runPromise(
+          managedRuntime.runPromise(
             Effect.gen(function* () {
               yield* db.connect()
               const bunFiles = schemaFiles.map((schemaFile) =>
@@ -740,32 +229,13 @@ export function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntim
               yield* publishDatabaseBootstrapEffect({ databaseService: db, schemaFingerprint })
             }),
           ),
-        disconnect: () => {
-          if (disconnectPromise) {
-            return disconnectPromise
-          }
-
-          disconnectPromise = Effect.runPromise(
-            Effect.gen(function* () {
-              yield* Effect.ignore(effectTryPromise(() => socialChat.shutdown()))
-              yield* Effect.ignore(effectTryPromise(() => disconnectPluginDatabases()))
-              yield* effectTryPromise(() => managedRuntime.dispose())
-            }).pipe(
-              Effect.ensuring(
-                Effect.sync(() => {
-                  clearLotaSdkRuntime()
-                  if (runtimeToken) releaseRuntimeToken(runtimeToken)
-                }),
-              ),
-            ),
-          )
-          return disconnectPromise
-        },
+        disconnect,
       }
       return lotaRuntime
     }),
   ).catch((error) => {
     if (effectRuntime) {
+      clearRuntimeModuleAccessors()
       clearLotaSdkRuntime()
       void effectRuntime.dispose().catch(() => undefined)
     }
@@ -790,60 +260,3 @@ function getBuiltInSchemaFiles(): URL[] {
     new URL('../infrastructure/schema/10_autonomous_job.surql', import.meta.url),
   ]
 }
-
-function getPluginLifecycleServices(plugin: LotaPlugin): PluginLifecycleServices {
-  return plugin.services as PluginLifecycleServices
-}
-
-function createPluginDatabaseConnector(
-  pluginRuntime: Record<string, LotaPlugin>,
-  connectedPluginDatabases: Set<string>,
-): () => Promise<void> {
-  return () =>
-    Effect.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)
-        }
-      }),
-    )
-}
-
-function createPluginDatabaseDisconnector(
-  pluginRuntime: Record<string, LotaPlugin>,
-  connectedPluginDatabases: Set<string>,
-): () => Promise<void> {
-  return () =>
-    Effect.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)
-        }
-      }),
-    )
-}