@lota-sdk/core 0.4.12 → 0.4.14

package/src/runtime/context-compaction/context-compaction.ts

@@ -2,7 +2,7 @@ import type { ChatMessage } from '@lota-sdk/shared'
 import { Duration, Effect, Schedule, Schema } from 'effect'
 import { z } from 'zod'
 
-import { iterateEffect } from '../../effect/helpers'
+import { ERROR_TAGS } from '../../effect/errors'
 import { nowEpochMillis } from '../../utils/date-time'
 import {
   CHARS_PER_TOKEN_ESTIMATE,
@@ -60,12 +60,12 @@ export interface ContextCompactionRunnerParams {
   transcript: string
 }
 
-class CompactionError extends Schema.TaggedErrorClass<CompactionError>()('CompactionError', {
+class CompactionError extends Schema.TaggedErrorClass<CompactionError>()(ERROR_TAGS.CompactionError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
 
-class CompactionParseError extends Schema.TaggedErrorClass<CompactionParseError>()('CompactionParseError', {
+class CompactionParseError extends Schema.TaggedErrorClass<CompactionParseError>()(ERROR_TAGS.CompactionParseError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
@@ -88,9 +88,11 @@ export interface CompactionOutput {
   summary: string
 }
 
+type ContextCompactionRunnerError = { readonly _tag: string; readonly message?: string }
+
 export type ContextCompactionRunner = (
   params: ContextCompactionRunnerParams,
-) => Effect.Effect<CompactionOutput, unknown>
+) => Effect.Effect<CompactionOutput, ContextCompactionRunnerError, never>
 
 export interface CreateContextCompactionRuntimeOptions {
   runCompacter: ContextCompactionRunner
@@ -342,22 +344,29 @@ export function createContextCompactionRuntime(
     const chunks = splitByCharBudget(params.newMessages, compactionChunkMaxChars)
     const initialSummary = normalizeSummary(params.previousSummary)
 
-    const finalSummary = yield* iterateEffect<{ summary: string; index: number }, CompactionError, never>(
-      { summary: initialSummary, index: 0 },
-      {
-        while: (state) => state.index < chunks.length,
-        body: (state) =>
-          Effect.gen(function* () {
+    const stepSummary = (state: {
+      summary: string
+      index: number
+    }): Effect.Effect<{ summary: string; index: number }, CompactionError> =>
+      state.index >= chunks.length
+        ? Effect.succeed(state)
+        : Effect.gen(function* () {
             const chunk = chunks[state.index]
             const transcript = toCompactionTranscript(chunk)
             const output = yield* options.runCompacter({ previousSummary: state.summary, chunk, transcript }).pipe(
-              Effect.mapError((error) => new CompactionError({ message: String(error), cause: error })),
+              Effect.mapError(
+                (error) =>
+                  new CompactionError({
+                    message: error.message ?? `Context compaction runner failed with ${error._tag}.`,
+                    cause: error,
+                  }),
+              ),
               Effect.retry(COMPACTION_RUNNER_RETRY_OPTIONS),
             )
-            return { summary: normalizeSummary(output.summary), index: state.index + 1 }
-          }),
-      },
-    )
+            return yield* stepSummary({ summary: normalizeSummary(output.summary), index: state.index + 1 })
+          })
+
+    const finalSummary = yield* stepSummary({ summary: initialSummary, index: 0 })
 
     return { summary: finalSummary.summary }
   })
@@ -419,59 +428,62 @@ export function createContextCompactionRuntime(
         done: false,
       }
 
-      const finalState = yield* iterateEffect<CompactionLoopState, CompactionError, never>(initialState, {
-        while: (state) => !state.done,
-        body: (state) =>
-          Effect.gen(function* () {
-            const assessment = shouldCompactHistory({
-              summaryText: state.summaryText,
-              liveMessages: state.remainingMessages,
-              contextSize: params.contextSize,
+      const stepHistory = (state: CompactionLoopState): Effect.Effect<CompactionLoopState, CompactionError> =>
+        state.done
+          ? Effect.succeed(state)
+          : Effect.gen(function* () {
+              const assessment = shouldCompactHistory({
+                summaryText: state.summaryText,
+                liveMessages: state.remainingMessages,
+                contextSize: params.contextSize,
+              })
+
+              if (!assessment.shouldCompact) {
+                return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
+              }
+
+              const boundary = Math.max(0, state.remainingMessages.length - params.tailMessageCount)
+              if (boundary <= 0) {
+                return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
+              }
+
+              const candidatePrefix = state.remainingMessages.slice(0, boundary)
+              const messagesToCompact = candidatePrefix.filter((message) => !readIsCompacted(message))
+              const contextMessages = messagesToCompact
+                .map(toContextMessageFromChatMessage)
+                .filter((message) => compactWhitespace(message.text).length > 0)
+              const sourceText = toCompactionTranscript(contextMessages)
+
+              if (!compactWhitespace(sourceText)) {
+                return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
+              }
+
+              const compacted = yield* compactContextMessagesEffect({
+                previousSummary: state.summaryText,
+                newMessages: contextMessages,
+              })
+              const rolledSummary = yield* rollupSummaryIfOversizedEffect(normalizeSummary(compacted.summary))
+
+              if (rolledSummary.length >= sourceText.length) {
+                return yield* new CompactionError({
+                  message: 'Compaction summary is not shorter than compacted source',
+                })
+              }
+
+              return yield* stepHistory({
+                summaryText: rolledSummary,
+                remainingMessages: state.remainingMessages.slice(boundary),
+                compactedMessages: [
+                  ...state.compactedMessages,
+                  ...candidatePrefix.map((message) => markMessageCompacted(message, now)),
+                ],
+                lastCompactedMessageId: candidatePrefix.at(-1)?.id ?? state.lastCompactedMessageId,
+                estimatedTokens: assessment.estimatedTokens,
+                done: false,
+              })
             })
 
-            if (!assessment.shouldCompact) {
-              return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
-            }
-
-            const boundary = Math.max(0, state.remainingMessages.length - params.tailMessageCount)
-            if (boundary <= 0) {
-              return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
-            }
-
-            const candidatePrefix = state.remainingMessages.slice(0, boundary)
-            const messagesToCompact = candidatePrefix.filter((message) => !readIsCompacted(message))
-            const contextMessages = messagesToCompact
-              .map(toContextMessageFromChatMessage)
-              .filter((message) => compactWhitespace(message.text).length > 0)
-            const sourceText = toCompactionTranscript(contextMessages)
-
-            if (!compactWhitespace(sourceText)) {
-              return { ...state, estimatedTokens: assessment.estimatedTokens, done: true }
-            }
-
-            const compacted = yield* compactContextMessagesEffect({
-              previousSummary: state.summaryText,
-              newMessages: contextMessages,
-            })
-            const rolledSummary = yield* rollupSummaryIfOversizedEffect(normalizeSummary(compacted.summary))
-
-            if (rolledSummary.length >= sourceText.length) {
-              return yield* new CompactionError({ message: 'Compaction summary is not shorter than compacted source' })
-            }
-
-            return {
-              summaryText: rolledSummary,
-              remainingMessages: state.remainingMessages.slice(boundary),
-              compactedMessages: [
-                ...state.compactedMessages,
-                ...candidatePrefix.map((message) => markMessageCompacted(message, now)),
-              ],
-              lastCompactedMessageId: candidatePrefix.at(-1)?.id ?? state.lastCompactedMessageId,
-              estimatedTokens: assessment.estimatedTokens,
-              done: false,
-            }
-          }),
-      })
+      const finalState = yield* stepHistory(initialState)
 
       return buildExitResult(finalState)
     })

package/src/runtime/domain-layer.ts

@@ -10,7 +10,7 @@
 import type { Layer as LayerType } from 'effect'
 import { Layer } from 'effect'
 
-import { AiGatewayLive } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModelsTag, AiGatewayTag, RuntimeBridgeTag } from '../ai-gateway/ai-gateway'
 import { EmbeddingCacheLive } from '../ai/embedding-cache'
 import type { buildInfrastructureLayer } from '../effect/layers'
 import { LotaQueuesLive } from '../queues/queues.service'
@@ -85,12 +85,18 @@ function provide<A, E, R extends RCtx, RCtx, E2>(
 
 type InfrastructureLayer = ReturnType<typeof buildInfrastructureLayer>
 
+type BridgeLayer = LayerType.Layer<AiGatewayTag | AiGatewayModelsTag | RuntimeBridgeTag, never, never>
+
 /**
  * Compose the domain service layer tree on top of the supplied infrastructure
- * layer. The returned layer has no remaining requirements and can be fed
- * straight into `ManagedRuntime.make`.
+ * layer. `bridgeLayer` provides `AiGatewayModelsTag` and `RuntimeBridgeTag`
+ * — these are constructed at the host boundary (`createLotaRuntime`) via
+ * `Deferred` because they reference the `ManagedRuntime` that is being built.
+ * They are threaded into the domain context so service layers that need them
+ * can `yield*` the tags directly instead of prop-drilling `runPromise`.
  */
-export function buildDomainServiceLayer(infrastructureLayer: InfrastructureLayer) {
+export function buildDomainServiceLayer(infrastructureLayer: InfrastructureLayer, bridgeLayer: BridgeLayer) {
+  const baseCtx = Layer.mergeAll(infrastructureLayer, bridgeLayer)
   const tier0 = provide(
     Layer.mergeAll(
       BackgroundWorkServiceLive,
@@ -103,11 +109,11 @@ export function buildDomainServiceLayer(infrastructureLayer: InfrastructureLayer
       PlanBuilderServiceLive,
       WriteIntentValidatorServiceLive,
     ),
-    infrastructureLayer,
+    baseCtx,
   )
   const ctx0 = Layer.mergeAll(
-    infrastructureLayer,
-    provide(Layer.mergeAll(AiGatewayLive, EmbeddingCacheLive, FirecrawlLive, HelperModelLive), infrastructureLayer),
+    baseCtx,
+    provide(Layer.mergeAll(EmbeddingCacheLive, FirecrawlLive, HelperModelLive), baseCtx),
     tier0,
   )
 

package/src/runtime/execution-plan.ts

@@ -26,7 +26,7 @@ function formatExecutionPlansForPrompt(plans: SerializableExecutionPlan[]): stri
 }
 
 export class ExecutionPlanCacheError extends Schema.TaggedErrorClass<ExecutionPlanCacheError>()(
-  'ExecutionPlanCacheError',
+  '@lota-sdk/core/ExecutionPlanCacheError',
   { message: Schema.String, cause: Schema.Defect },
 ) {}
 
@@ -42,7 +42,11 @@ export function buildExecutionPlanInstructionSections(plans: SerializableExecuti
 export function createExecutionPlanInstructionSectionCache(params: {
   disabled?: boolean
   loadPlansEffect: () => Effect.Effect<SerializableExecutionPlan[], ExecutionPlanCacheError>
+  /** Promise adapter used by the `getPlans()` / `getSections()` Promise API.
+   * Required so this module never reaches for an ambient `Effect.runPromise`. */
+  runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>
 }) {
+  const runPromise = params.runPromise
   const [getPlansCachedEffect, invalidatePlansEffect] = Effect.runSync(
     Effect.cachedInvalidateWithTTL(
       Effect.suspend(() => (params.disabled ? Effect.succeed([]) : params.loadPlansEffect())),
@@ -75,10 +79,10 @@ export function createExecutionPlanInstructionSectionCache(params: {
     getPlansEffect,
     getSectionsEffect,
     getPlans() {
-      return Effect.runPromise(getPlansEffect())
+      return runPromise(getPlansEffect())
     },
     getSections() {
-      return Effect.runPromise(getSectionsEffect())
+      return runPromise(getSectionsEffect())
     },
   }
 }

package/src/runtime/live-turn-trace.ts

@@ -56,30 +56,6 @@ function readHeadingTitle(line: string): string | null {
   return null
 }
 
-function readLeadLineTitle(line: string): string | null {
-  const trimmed = stripMarkdownTitleDecorators(line)
-  if (!trimmed) return null
-  if (trimmed.length > 90) return null
-  if (/[.!?]$/.test(trimmed)) return null
-  return trimmed
-}
-
-function readFirstCompleteSentence(chunk: string): string | null {
-  const compact = normalizeWhitespace(chunk)
-  if (!compact) return null
-  const sentenceMatch = compact.match(/^(.+?[.!?])(?:\s|$)/)
-  if (sentenceMatch?.[1]) {
-    return sentenceMatch[1]
-  }
-  return null
-}
-
-function isStableReasoningChunk(chunk: string, isLastChunk: boolean, isFinal: boolean): boolean {
-  if (!isLastChunk || isFinal) return true
-  if (chunk.includes('\n')) return true
-  return /[.!?:]\s*$/.test(chunk.trim())
-}
-
 export function extractThinkingTitlesFromReasoning(params: { text: string; isFinal?: boolean }): string[] {
   const cleaned = sanitizeReasoningText(params.text).trim()
   if (cleaned.length === 0) return []
@@ -91,35 +67,16 @@ export function extractThinkingTitlesFromReasoning(params: { text: string; isFin
 
   const titles: string[] = []
 
-  for (const [index, chunk] of chunks.entries()) {
-    const isLastChunk = index === chunks.length - 1
-    if (!isStableReasoningChunk(chunk, isLastChunk, params.isFinal === true)) {
-      continue
-    }
-
-    const lines = chunk
+  for (const chunk of chunks) {
+    const firstLine = chunk
       .split('\n')
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0)
-    if (lines.length === 0) continue
+      .find((line) => line.trim().length > 0)
+      ?.trim()
+    if (!firstLine) continue
 
-    const headingTitle = readHeadingTitle(lines[0])
+    const headingTitle = readHeadingTitle(firstLine)
     if (headingTitle) {
       titles.push(normalizeThinkingTitle(headingTitle))
-      continue
-    }
-
-    if (lines.length > 1 || params.isFinal === true) {
-      const leadLineTitle = readLeadLineTitle(lines[0])
-      if (leadLineTitle) {
-        titles.push(normalizeThinkingTitle(leadLineTitle))
-        continue
-      }
-    }
-
-    const sentenceTitle = readFirstCompleteSentence(chunk)
-    if (sentenceTitle) {
-      titles.push(normalizeThinkingTitle(sentenceTitle))
     }
   }
 

package/src/runtime/memory/memory-block.ts

@@ -5,7 +5,7 @@ import { nowDate } from '../../utils/date-time'
 import { compactWhitespace } from '../../utils/string'
 
 export class MemoryBlockCompactError extends Schema.TaggedErrorClass<MemoryBlockCompactError>()(
-  'MemoryBlockCompactError',
+  '@lota-sdk/core/MemoryBlockCompactError',
   { message: Schema.String, cause: Schema.Defect },
 ) {}
 
@@ -65,7 +65,7 @@ export interface CompactMemoryBlockEntriesParams {
   compact: (params: {
     previousSummary: string
     newEntriesText: string
-  }) => PromiseLike<string> | Effect.Effect<string, MemoryBlockCompactError>
+  }) => Effect.Effect<string, MemoryBlockCompactError>
 }
 
 export interface CompactMemoryBlockEntriesResult {
@@ -119,13 +119,7 @@ export function compactMemoryBlockEntries(
     while (entries.length >= params.triggerEntries) {
       const chunk = entries.slice(0, params.chunkEntries)
       const compactParams = { previousSummary: summary, newEntriesText: toMemoryBlockEntriesSource(chunk) }
-      const value = params.compact(compactParams)
-      const raw = yield* Effect.isEffect(value)
-        ? value
-        : Effect.tryPromise({
-            try: () => Promise.resolve(value),
-            catch: (cause) => new MemoryBlockCompactError({ message: 'compact callback failed', cause }),
-          })
+      const raw = yield* params.compact(compactParams)
       const nextSummary = raw.trim()
 
       if (!nextSummary) {

package/src/runtime/memory/memory-scope.ts

@@ -1,11 +1,13 @@
 import { Effect, Schema } from 'effect'
 
+import { ERROR_TAGS } from '../../effect/errors'
+
 export const ORG_SCOPE_PREFIX = 'org'
 
 const SCOPE_ID_MAX_LENGTH = 255
 const SCOPE_PREFIX_REGEX = /^[a-z][a-z0-9_]*$/
 
-export class MemoryScopeError extends Schema.TaggedErrorClass<MemoryScopeError>()('MemoryScopeError', {
+export class MemoryScopeError extends Schema.TaggedErrorClass<MemoryScopeError>()(ERROR_TAGS.MemoryScopeError, {
   message: Schema.String,
 }) {}
 

package/src/runtime/plugin-resolution.ts

@@ -1,13 +1,14 @@
 import { Schema, Effect } from 'effect'
 
 import type { RecordIdRef } from '../db/record-id'
+import { ERROR_TAGS } from '../effect/errors'
 import type { LotaRuntimeAdapters, LotaRuntimeIndexedRepositoriesContext } from './runtime-extensions'
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }
 
-class PluginResolutionError extends Schema.TaggedErrorClass<PluginResolutionError>()('PluginResolutionError', {
+class PluginResolutionError extends Schema.TaggedErrorClass<PluginResolutionError>()(ERROR_TAGS.PluginResolutionError, {
   stage: Schema.Literals([
     'configuration',
     'linear-installation',

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

@@ -3,6 +3,7 @@ import { Schema, Effect } from 'effect'
 
 import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import type { RecordIdRef } from '../db/record-id'
+import { ERROR_TAGS } from '../effect/errors'
 import { AgentConfigServiceTag, RuntimeAdaptersServiceTag } from '../effect/services'
 import { LotaQueuesServiceTag } from '../queues/queues.service'
 import { RecentActivityServiceTag } from '../services/recent-activity.service'
@@ -27,10 +28,10 @@ import {
   toHistoryMessages,
 } from './thread-chat-helpers'
 
-class PostTurnSideEffectsError extends Schema.TaggedErrorClass<PostTurnSideEffectsError>()('PostTurnSideEffectsError', {
-  message: Schema.String,
-  cause: Schema.Defect,
-}) {}
+class PostTurnSideEffectsError extends Schema.TaggedErrorClass<PostTurnSideEffectsError>()(
+  ERROR_TAGS.PostTurnSideEffectsError,
+  { message: Schema.String, cause: Schema.Defect },
+) {}
 
 function tryPostTurnSideEffect<A>(
   message: string,
@@ -214,7 +215,7 @@ export const runPostTurnSideEffects = Effect.fn('PostTurnSideEffects.run')(funct
           () => {
             const enqueuePostChatOrgAction = runtimeAdapters.enqueuePostChatOrgAction
             if (!enqueuePostChatOrgAction) {
-              return
+              return Promise.resolve()
             }
 
             const sourceCreatedAt = referenceUserMessage.metadata?.createdAt ?? nowEpochMillis()

package/src/runtime/retrieval-adapters.ts

@@ -1,8 +1,10 @@
 import { Schema, Effect } from 'effect'
 
+import { ERROR_TAGS } from '../effect/errors'
+
 interface ScopedRetrievalTask<TCandidate, E = never> {
   scopeTag: string
-  retrieve: () => PromiseLike<TCandidate[]> | Effect.Effect<TCandidate[], E>
+  retrieve: () => Effect.Effect<TCandidate[], E>
 }
 
 interface ScopedRetrievalResult<TCandidate> {
@@ -10,7 +12,7 @@ interface ScopedRetrievalResult<TCandidate> {
   candidates: TCandidate[]
 }
 
-class ScopedRetrievalError extends Schema.TaggedErrorClass<ScopedRetrievalError>()('ScopedRetrievalError', {
+class ScopedRetrievalError extends Schema.TaggedErrorClass<ScopedRetrievalError>()(ERROR_TAGS.ScopedRetrievalError, {
   scopeTag: Schema.String,
   message: Schema.String,
   cause: Schema.Defect,
@@ -26,24 +28,10 @@ export function executeScopedRetrieval<TCandidate, E>(
   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))
-        }
-      }),
+      task.retrieve().pipe(
+        Effect.mapError((cause) => toScopedRetrievalError(task.scopeTag, cause)),
+        Effect.map((candidates) => ({ scopeTag: task.scopeTag, candidates })),
+      ),
     { concurrency: 'unbounded' },
   )
 }

package/src/runtime/runtime-config.ts

@@ -105,16 +105,10 @@ export interface LotaRuntimeSocialChatConfig {
   slack?: LotaSocialChatSlackConfig
   historyRedisKeyPrefix?: string
   stateRedisKeyPrefix?: string
-  resolveContext: (
-    params: LotaSocialChatResolveContextParams,
-  ) => LotaSocialChatResolvedContext | Promise<LotaSocialChatResolvedContext>
-  buildAgentTools: (params: BuildSocialChatAgentToolsParams) => ToolSet | Promise<ToolSet>
+  resolveContext: (params: LotaSocialChatResolveContextParams) => Promise<LotaSocialChatResolvedContext>
+  buildAgentTools: (params: BuildSocialChatAgentToolsParams) => Promise<ToolSet>
   getConsultParticipants?:
-    | ((params: {
-        workspaceId: RecordIdRef
-        workspaceIdString: string
-        platform: 'slack'
-      }) => string[] | Promise<string[]>)
+    | ((params: { workspaceId: RecordIdRef; workspaceIdString: string; platform: 'slack' }) => Promise<string[]>)
     | undefined
 }
 

package/src/runtime/runtime-extensions.ts

@@ -35,12 +35,10 @@ export interface LotaRuntimeProfileProjection {
 
 export interface LotaRuntimeWorkspaceProvider {
   getWorkspace(workspaceId: RecordIdRef): Promise<Record<string, unknown>>
-  getLifecycleState?(
-    workspace: Record<string, unknown>,
-  ): Promise<LotaRuntimeWorkspaceLifecycleState> | LotaRuntimeWorkspaceLifecycleState
+  getLifecycleState?(workspace: Record<string, unknown>): Promise<LotaRuntimeWorkspaceLifecycleState>
   readProfileProjectionState?(
     workspace: Record<string, unknown>,
-  ): Promise<LotaRuntimeWorkspaceProjectionState | undefined> | LotaRuntimeWorkspaceProjectionState | undefined
+  ): Promise<LotaRuntimeWorkspaceProjectionState | undefined>
   buildPromptSummary?(workspaceId: RecordIdRef): Promise<string | undefined>
   listRecentDomainEvents?(workspaceId: RecordIdRef, limit?: number): Promise<Array<Record<string, unknown>>>
   hasActiveKnowledgeSources?(workspaceId: string): Promise<boolean>

package/src/runtime/runtime-lifecycle.ts

@@ -3,18 +3,15 @@
  *
  * 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.
+ * the rest of the SDK runtime. Disconnect runs its teardown sequence as a
+ * plain `Effect.runPromise` — the services it yields have no layer
+ * requirements because they are closure-captured shutdown thunks.
  */
 
 import type { ManagedRuntime } from 'effect'
 import { Effect } from 'effect'
 
-import { clearAiGatewayRuntime } from '../ai-gateway/ai-gateway'
-import { effectTryPromise } from '../effect/helpers'
+import { RuntimeLifecycleError } from '../effect/errors'
 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
@@ -24,6 +21,26 @@ function getPluginLifecycleServices(plugin: LotaPlugin): Record<string, unknown>
   return plugin.services
 }
 
+function toRuntimeLifecycleError(
+  operation: RuntimeLifecycleError['operation'],
+  cause: unknown,
+  pluginName?: string,
+): RuntimeLifecycleError {
+  const detail = pluginName ? ` "${pluginName}"` : ''
+  const action =
+    operation === 'connect-plugin-database'
+      ? `connect plugin database${detail}`
+      : operation === 'disconnect-plugin-database'
+        ? `disconnect plugin database${detail}`
+        : operation === 'shutdown-social-chat'
+          ? 'shut down social chat'
+          : operation === 'disconnect-plugin-databases'
+            ? 'disconnect plugin databases'
+            : 'dispose managed runtime'
+
+  return new RuntimeLifecycleError({ operation, message: `Failed to ${action}.`, cause })
+}
+
 /**
  * Build a plugin database connector that iterates the configured plugins and
  * calls each `services.connectDatabase()` once, tracking completion in
@@ -49,7 +66,10 @@ export function createPluginDatabaseConnector(
           }
 
           const connectDatabaseFn = connectDatabase as (this: typeof services) => Promise<void>
-          yield* effectTryPromise(() => connectDatabaseFn.call(services))
+          yield* Effect.tryPromise({
+            try: () => connectDatabaseFn.call(services),
+            catch: (cause) => toRuntimeLifecycleError('connect-plugin-database', cause, pluginName),
+          })
           connectedPluginDatabases.add(pluginName)
         }
       }),
@@ -82,7 +102,10 @@ export function createPluginDatabaseDisconnector(
           }
 
           const disconnectDatabaseFn = disconnectDatabase as (this: typeof services) => Promise<void>
-          yield* effectTryPromise(() => disconnectDatabaseFn.call(services))
+          yield* Effect.tryPromise({
+            try: () => disconnectDatabaseFn.call(services),
+            catch: (cause) => toRuntimeLifecycleError('disconnect-plugin-database', cause, pluginName),
+          })
           connectedPluginDatabases.delete(pluginName)
         }
       }),
@@ -91,7 +114,6 @@ export function createPluginDatabaseDisconnector(
 
 interface CreateDisconnectInput {
   managedRuntime: SdkManagedRuntime
-  runPromiseWithCurrentContext: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
   socialChatShutdown: () => Promise<void>
   disconnectPluginDatabases: () => Promise<void>
 }
@@ -100,9 +122,15 @@ interface CreateDisconnectInput {
  * 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.
+ *
+ * Teardown order:
+ *   1. socialChat shutdown (user-facing bots must go quiet first)
+ *   2. plugin database disconnect (release external connections)
+ *   3. clear AI gateway runtime slot BEFORE dispose (no new fibers)
+ *   4. managedRuntime.dispose() (release all scoped layer resources)
  */
 export function createRuntimeDisconnect(input: CreateDisconnectInput): () => Promise<void> {
-  const { managedRuntime, runPromiseWithCurrentContext, socialChatShutdown, disconnectPluginDatabases } = input
+  const { managedRuntime, socialChatShutdown, disconnectPluginDatabases } = input
 
   let disconnectPromise: Promise<void> | null = null
 
@@ -111,12 +139,24 @@ export function createRuntimeDisconnect(input: CreateDisconnectInput): () => Pro
       return disconnectPromise
     }
 
-    disconnectPromise = runPromiseWithCurrentContext(
+    disconnectPromise = Effect.runPromise(
       Effect.gen(function* () {
-        yield* Effect.ignore(effectTryPromise(() => socialChatShutdown()))
-        yield* Effect.ignore(effectTryPromise(() => disconnectPluginDatabases()))
-        yield* effectTryPromise(() => managedRuntime.dispose())
-        yield* Effect.sync(() => clearAiGatewayRuntime())
+        yield* Effect.ignore(
+          Effect.tryPromise({
+            try: () => socialChatShutdown(),
+            catch: (cause) => toRuntimeLifecycleError('shutdown-social-chat', cause),
+          }),
+        )
+        yield* Effect.ignore(
+          Effect.tryPromise({
+            try: () => disconnectPluginDatabases(),
+            catch: (cause) => toRuntimeLifecycleError('disconnect-plugin-databases', cause),
+          }),
+        )
+        yield* Effect.tryPromise({
+          try: () => managedRuntime.dispose(),
+          catch: (cause) => toRuntimeLifecycleError('dispose-managed-runtime', cause),
+        })
       }),
     )
     return disconnectPromise