@lota-sdk/core 0.4.13 → 0.4.15

package/src/tools/research-topic.tool.ts

@@ -1,6 +1,7 @@
 import type Firecrawl from '@mendable/firecrawl-js'
+import type { Effect } from 'effect'
 
-import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayStrictSemanticCacheHeaders } from '../ai-gateway/cache-headers'
 import {
   OPENROUTER_FAST_REASONING_MODEL_ID,
@@ -13,19 +14,22 @@ import { searchWebTool } from './search-web.tool'
 
 export interface ResearchTopicToolContext {
   firecrawl: Firecrawl
+  aiGatewayModels: AiGatewayModels
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }
 
 export const researchTopicTool = createDelegatedAgentToolWithContext<ResearchTopicToolContext>({
   id: 'researchTopic',
   description:
     'Delegate a research task to a dedicated research agent that searches the web, fetches pages, and returns a synthesized markdown report.',
-  model: () => aiGatewayChatModel(OPENROUTER_FAST_REASONING_MODEL_ID),
+  model: ({ aiGatewayModels }) => aiGatewayModels.chatModel(OPENROUTER_FAST_REASONING_MODEL_ID),
   providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
   headers: buildAiGatewayStrictSemanticCacheHeaders('researchTopic'),
   instructions: RESEARCHER_PROMPT,
-  createTools: ({ firecrawl }) => ({
-    searchWeb: searchWebTool.create({ firecrawl }),
-    fetchWebpage: fetchWebpageTool.create({ firecrawl }),
+  createTools: ({ firecrawl, runPromise }) => ({
+    searchWeb: searchWebTool.create({ firecrawl, runPromise }),
+    fetchWebpage: fetchWebpageTool.create({ firecrawl, runPromise }),
   }),
   maxSteps: 6,
+  getRunPromise: (context) => context.runPromise,
 })

package/src/tools/search-web.tool.ts

@@ -4,6 +4,7 @@ import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
+import { ERROR_TAGS } from '../effect/errors'
 import { withTimeout } from '../utils/async'
 import { nowIsoDateTimeString } from '../utils/date-time'
 import { readStringField, truncateOptionalText } from '../utils/string'
@@ -12,9 +13,10 @@ import { toRecord, WEB_TOOL_TIMEOUT_MS } from './web-tool-shared'
 
 export interface SearchWebToolContext {
   firecrawl: Firecrawl
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }
 
-class SearchWebToolError extends Schema.TaggedErrorClass<SearchWebToolError>()('@lota-sdk/core/SearchWebToolError', {
+class SearchWebToolError extends Schema.TaggedErrorClass<SearchWebToolError>()(ERROR_TAGS.SearchWebToolError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
@@ -139,7 +141,7 @@ function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?
 
 export const searchWebTool = {
   name: 'searchWeb',
-  create: ({ firecrawl }: SearchWebToolContext) =>
+  create: ({ firecrawl, runPromise }: SearchWebToolContext) =>
     tool({
       description: 'Search the web for real-time information.',
       inputSchema: z
@@ -151,20 +153,17 @@ export const searchWebTool = {
           tbs: z.string().optional(),
         })
         .strict(),
-      execute: ({
-        query,
-        limit,
-        sources,
-        location,
-        tbs,
-      }: {
-        query: string
-        limit?: number
-        sources?: ('web' | 'news' | 'images')[]
-        location?: string
-        tbs?: string
-      }) =>
-        Effect.runPromise(
+      execute: (
+        {
+          query,
+          limit,
+          sources,
+          location,
+          tbs,
+        }: { query: string; limit?: number; sources?: ('web' | 'news' | 'images')[]; location?: string; tbs?: string },
+        { abortSignal }: { abortSignal?: AbortSignal } = {},
+      ) =>
+        runPromise(
           Effect.gen(function* () {
             const results = yield* Effect.tryPromise({
               try: () =>
@@ -185,6 +184,7 @@ export const searchWebTool = {
               citations: buildWebCitations(results),
             }
           }).pipe(Effect.withSpan('tool.searchWeb.execute')),
+          abortSignal ? { signal: abortSignal } : undefined,
         ),
     }),
 } as const satisfies ToolDefinition<SearchWebToolContext>

package/src/tools/search.tool.ts

@@ -15,18 +15,24 @@ const ConversationSearchInputSchema = z.object({ query: z.string().min(1), type:
 type MemorySearchService = Pick<ReturnType<typeof createMemoryService>, 'searchAllMemoriesBatched'>
 type ConversationSearchService = Pick<ReturnType<typeof makeThreadMessageService>, 'searchMessagesEffect'>
 
+type SearchToolRunPromise = <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
+
 export function createMemorySearchTool(
   agentConfig: ResolvedAgentConfig,
   orgIdString: string,
   memoryService: MemorySearchService,
+  runPromise: SearchToolRunPromise,
   agentName?: string,
   options?: { fastMode?: boolean; allowMultiScopeRerank?: boolean },
 ) {
   return tool({
     description: 'Search organization and agent memories relevant to a query.',
     inputSchema: MemorySearchInputSchema,
-    execute: ({ query }: z.infer<typeof MemorySearchInputSchema>) =>
-      Effect.runPromise(
+    execute: (
+      { query }: z.infer<typeof MemorySearchInputSchema>,
+      { abortSignal }: { abortSignal?: AbortSignal } = {},
+    ) =>
+      runPromise(
         Effect.gen(function* () {
           const normalizedQuery = query.trim()
           const retrieval = yield* memoryService.searchAllMemoriesBatched({
@@ -41,16 +47,24 @@ export function createMemorySearchTool(
           const reminder = `Remember: you searched for "${normalizedQuery}". Use the highest-relevance retrieved lines above to answer.`
           return { query: normalizedQuery, retrieval, reminder }
         }),
+        abortSignal ? { signal: abortSignal } : undefined,
       ),
   })
 }
 
-export function createConversationSearchTool(threadId: RecordIdRef, threadMessageService: ConversationSearchService) {
+export function createConversationSearchTool(
+  threadId: RecordIdRef,
+  threadMessageService: ConversationSearchService,
+  runPromise: SearchToolRunPromise,
+) {
   return tool({
     description: 'Search prior chat messages by role and query text.',
     inputSchema: ConversationSearchInputSchema,
-    execute: ({ query, type }: z.infer<typeof ConversationSearchInputSchema>) =>
-      Effect.runPromise(
+    execute: (
+      { query, type }: z.infer<typeof ConversationSearchInputSchema>,
+      { abortSignal }: { abortSignal?: AbortSignal } = {},
+    ) =>
+      runPromise(
         Effect.gen(function* () {
           const normalizedQuery = query.trim()
           const results = yield* threadMessageService.searchMessagesEffect({
@@ -61,6 +75,7 @@ export function createConversationSearchTool(threadId: RecordIdRef, threadMessag
           })
           return { query: normalizedQuery, type, count: results.length, results }
         }),
+        abortSignal ? { signal: abortSignal } : undefined,
       ),
   })
 }

package/src/tools/team-think.tool.ts

@@ -7,7 +7,7 @@ import { aiLogger } from '../config/logger'
 import type { RecordIdRef } from '../db/record-id'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
-import { effectTryMaybeAsync as effectTryMaybeAsyncShared } from '../effect/helpers'
+import { ERROR_TAGS } from '../effect/errors'
 import {
   AgentConfigServiceTag,
   AgentFactoryServiceTag,
@@ -35,29 +35,25 @@ function buildTeamThinkAgentToolsEffect(
     return Effect.succeed({ tools: {} })
   }
 
-  return effectTryMaybeAsync(() => builder(params), 'Failed to build team-think agent tools.')
+  return Effect.tryPromise({
+    try: () => builder(params),
+    catch: (error) => new TeamThinkRuntimeError({ message: 'Failed to build team-think agent tools.', cause: error }),
+  })
 }
 
 const TEAM_THINK_AGENT_MAX_RETRIES = 1
 const TEAM_THINK_AGENT_MAX_STEPS = 3
 
 class TeamThinkAgentFactoryNotConfiguredError extends Schema.TaggedErrorClass<TeamThinkAgentFactoryNotConfiguredError>()(
-  'TeamThinkAgentFactoryNotConfiguredError',
+  '@lota-sdk/core/TeamThinkAgentFactoryNotConfiguredError',
   { agentId: Schema.String },
 ) {}
 
-class TeamThinkRuntimeError extends Schema.TaggedErrorClass<TeamThinkRuntimeError>()('TeamThinkRuntimeError', {
+class TeamThinkRuntimeError extends Schema.TaggedErrorClass<TeamThinkRuntimeError>()(ERROR_TAGS.TeamThinkRuntimeError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
 
-function effectTryMaybeAsync<A>(
-  evaluate: () => A | PromiseLike<A>,
-  message: string,
-): Effect.Effect<A, TeamThinkRuntimeError> {
-  return effectTryMaybeAsyncShared(evaluate, (error) => new TeamThinkRuntimeError({ message, cause: error }))
-}
-
 export function createTeamThinkTool(params: {
   historyMessages: ChatMessage[]
   latestUserMessageId: string
@@ -76,6 +72,7 @@ export function createTeamThinkTool(params: {
   context?: unknown
   toolProviders?: ToolSet
   abortSignal: AbortSignal
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
 }) {
   return Effect.gen(function* () {
     const turnHooks = yield* TurnHooksServiceTag
@@ -87,35 +84,54 @@ export function createTeamThinkTool(params: {
     )
     const participantRunner: TeamConsultationParticipantRunner = {
       buildParticipantAgent(agentId, runParams) {
-        return Effect.runPromise(
+        return params.runPromise(
           Effect.gen(function* () {
+            // Capture the fiber context of the managed runtime and replay it
+            // for observer callbacks that cross the Effect → Promise boundary
+            // (AI SDK agent observers). This preserves spans/loggers across
+            // the callback edge — it is NOT an ambient-runtime slot; the
+            // captured context lives only for this participant's fiber.
             const currentContext = yield* Effect.context()
             const runPromiseWithCurrentContext = Effect.runPromiseWith(currentContext)
-            const dynamicInstructionSections = yield* effectTryMaybeAsync(
-              () => params.getAdditionalInstructionSections?.(),
-              'Failed to load dynamic team-think instruction sections.',
-            )
+            const getAdditionalInstructionSections = params.getAdditionalInstructionSections
+            const dynamicInstructionSections = getAdditionalInstructionSections
+              ? yield* Effect.tryPromise({
+                  try: () => getAdditionalInstructionSections(),
+                  catch: (error) =>
+                    new TeamThinkRuntimeError({
+                      message: 'Failed to load dynamic team-think instruction sections.',
+                      cause: error,
+                    }),
+                })
+              : undefined
+            const resolveAgent = turnHooks.resolveAgent
             const agentResolution = asRecord(
-              yield* effectTryMaybeAsync(
-                () =>
-                  turnHooks.resolveAgent?.({
-                    agentId,
-                    mode: 'fixedThreadMode',
-                    thread: null,
-                    threadRef: params.threadId,
-                    orgRef: params.orgId,
-                    userRef: params.userId,
-                    onboardingActive: false,
-                    linearInstalled: false,
-                    githubInstalled: params.githubInstalled,
-                    additionalInstructionSections: mergeInstructionSections(
-                      dynamicInstructionSections,
-                      params.additionalInstructionSections,
-                    ),
-                    context: (params.context as Record<string, unknown> | null | undefined) ?? null,
-                  }),
-                'Failed to resolve team-think participant agent.',
-              ),
+              resolveAgent
+                ? yield* Effect.tryPromise({
+                    try: () =>
+                      resolveAgent({
+                        agentId,
+                        mode: 'fixedThreadMode',
+                        thread: null,
+                        threadRef: params.threadId,
+                        orgRef: params.orgId,
+                        userRef: params.userId,
+                        onboardingActive: false,
+                        linearInstalled: false,
+                        githubInstalled: params.githubInstalled,
+                        additionalInstructionSections: mergeInstructionSections(
+                          dynamicInstructionSections,
+                          params.additionalInstructionSections,
+                        ),
+                        context: (params.context as Record<string, unknown> | null | undefined) ?? null,
+                      }),
+                    catch: (error) =>
+                      new TeamThinkRuntimeError({
+                        message: 'Failed to resolve team-think participant agent.',
+                        cause: error,
+                      }),
+                  })
+                : undefined,
             )
             const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
             const config = agentFactoryConfig.getAgentRuntimeConfig({
@@ -169,9 +185,16 @@ export function createTeamThinkTool(params: {
               stopWhen: [stepCountIs(maxSteps)],
             })
             const observer = {
-              run: <T>(fn: () => T | Promise<T>): Promise<T> =>
+              run: <T>(fn: () => Promise<T>): Promise<T> =>
                 runPromiseWithCurrentContext(
-                  effectTryMaybeAsync(fn, `Team-think participant run failed (${agentId}).`),
+                  Effect.tryPromise({
+                    try: () => fn(),
+                    catch: (error) =>
+                      new TeamThinkRuntimeError({
+                        message: `Team-think participant run failed (${agentId}).`,
+                        cause: error,
+                      }),
+                  }),
                 ),
               recordError: (error: unknown) => {
                 aiLogger.error`Team-think participant failed (${agentId}): ${error}`

package/src/utils/async.ts

@@ -1,16 +1,16 @@
 import { Cause, Duration, Effect, Exit, Schema } from 'effect'
 
 import { serverLogger } from '../config/logger'
-import { TimeoutError } from '../effect/errors'
+import { ERROR_TAGS, TimeoutError } from '../effect/errors'
 import { getErrorMessage, toError } from './errors'
 
-class TimedOperationError extends Schema.TaggedErrorClass<TimedOperationError>()('TimedOperationError', {
+class TimedOperationError extends Schema.TaggedErrorClass<TimedOperationError>()(ERROR_TAGS.TimedOperationError, {
   operation: Schema.String,
   cause: Schema.Defect,
 }) {}
 
 function isTimedOperationError(error: unknown): error is TimedOperationError {
-  return typeof error === 'object' && error !== null && '_tag' in error && error._tag === 'TimedOperationError'
+  return typeof error === 'object' && error !== null && '_tag' in error && error._tag === ERROR_TAGS.TimedOperationError
 }
 
 export function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {
@@ -46,8 +46,8 @@ export function createSafeEnqueue(logger: { warn: (message: string) => void }) {
 
 const _defaultSafeEnqueue = createSafeEnqueue({ warn: (message: string) => serverLogger.warn`${message}` })
 export function safeEnqueue<T>(
-  operation: () => T | Promise<T>,
+  operation: () => Promise<T>,
   options: { operationName: string; onError?: (error: unknown) => void; logPrefix?: string },
 ): Promise<T | void> {
-  return _defaultSafeEnqueue(() => Promise.resolve(operation()), options)
+  return _defaultSafeEnqueue(operation, options)
 }

package/src/utils/errors.ts

@@ -1,8 +1,8 @@
 export { getErrorMessage } from '@lota-sdk/shared'
 import { Data, Match } from 'effect'
 
-import type { EffectError, ValidationIssue } from '../effect/errors'
-import { BaseServicePersistenceError, isEffectError } from '../effect/errors'
+import type { BaseServicePersistenceError, EffectError, ValidationIssue } from '../effect/errors'
+import { ERROR_TAGS, isEffectError } from '../effect/errors'
 
 export function toError(value: unknown): Error {
   return value instanceof Error ? value : new Error(String(value))
@@ -129,29 +129,30 @@ export function toAppErrorResponse(error: AppErrorLike): AppErrorResponse {
 }
 
 function isBaseServicePersistenceError(error: EffectError): error is BaseServicePersistenceError {
-  return error._tag === BaseServicePersistenceError.name
+  return error._tag === ERROR_TAGS.BaseServicePersistenceError
 }
 
 const toHttpErrorMatch = Match.type<Exclude<EffectError, BaseServicePersistenceError>>().pipe(
-  Match.tag('NotFoundError', (e) => httpError(e.message, 'NOT_FOUND', 404)),
-  Match.tag('BadRequestError', (e) => httpError(e.message, 'BAD_REQUEST', 400)),
-  Match.tag('ValidationError', (e) => httpError(e.message, 'VALIDATION_ERROR', 400)),
-  Match.tag('ConflictError', (e) => httpError(e.message, 'CONFLICT', 409)),
-  Match.tag('ForbiddenError', (e) => httpError(e.message, 'FORBIDDEN', 403)),
-  Match.tag('ThreadTurnError', (e) =>
+  Match.tag(ERROR_TAGS.NotFoundError, (e) => httpError(e.message, 'NOT_FOUND', 404)),
+  Match.tag(ERROR_TAGS.BadRequestError, (e) => httpError(e.message, 'BAD_REQUEST', 400)),
+  Match.tag(ERROR_TAGS.ValidationError, (e) => httpError(e.message, 'VALIDATION_ERROR', 400)),
+  Match.tag(ERROR_TAGS.ConflictError, (e) => httpError(e.message, 'CONFLICT', 409)),
+  Match.tag(ERROR_TAGS.ForbiddenError, (e) => httpError(e.message, 'FORBIDDEN', 403)),
+  Match.tag(ERROR_TAGS.ThreadTurnError, (e) =>
     httpError(e.message, e.reason === 'conflict' ? 'CONFLICT' : 'BAD_REQUEST', e.reason === 'conflict' ? 409 : 400),
   ),
-  Match.tag('ActiveThreadRunConflictError', (e) => httpError(e.message, 'CONFLICT', 409)),
-  Match.tag('ConfigurationError', (e) => httpError(e.message, 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('DatabaseError', () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('RedisError', () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('TimeoutError', (e) =>
+  Match.tag(ERROR_TAGS.ActiveThreadRunConflictError, (e) => httpError(e.message, 'CONFLICT', 409)),
+  Match.tag(ERROR_TAGS.ConfigurationError, (e) => httpError(e.message, 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.DatabaseError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.RedisError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.RuntimeLifecycleError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.TimeoutError, (e) =>
     httpError(`Operation "${e.operation}" timed out after ${e.ms}ms`, 'INTERNAL_SERVER_ERROR', 500),
   ),
-  Match.tag('LockAcquisitionError', () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('LockLostError', () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('AiGenerationError', (e) => httpError(e.message, 'INTERNAL_SERVER_ERROR', 500)),
-  Match.tag('ServiceError', () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.LockAcquisitionError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.LockLostError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.AiGenerationError, (e) => httpError(e.message, 'INTERNAL_SERVER_ERROR', 500)),
+  Match.tag(ERROR_TAGS.ServiceError, () => httpError('Internal server error', 'INTERNAL_SERVER_ERROR', 500)),
   Match.exhaustive,
 )
 

package/src/utils/sse-keepalive.ts

@@ -1,12 +1,25 @@
-import { Duration, Effect, Fiber } from 'effect'
+import type { Fiber } from 'effect'
+import { Duration, Effect, Exit, Schema, Scope } from 'effect'
+
+import { ERROR_TAGS } from '../effect/errors'
 
 const KEEPALIVE_COMMENT = new TextEncoder().encode(': keepalive\n\n')
 const DEFAULT_KEEPALIVE_INTERVAL_MS = 20_000
 
+class SseKeepaliveError extends Schema.TaggedErrorClass<SseKeepaliveError>()(ERROR_TAGS.SseKeepaliveError, {
+  phase: Schema.Literals(['read']),
+  cause: Schema.Defect,
+}) {}
+
 /**
  * Wraps an SSE Response body with periodic keepalive comments.
  * SSE comments (`: keepalive\n\n`) are ignored by standard SSE parsers,
  * so no client changes are needed.
+ *
+ * Lifecycle: a function-local `Scope` owns both the keepalive and body-pump
+ * fibers via `Effect.forkScoped`. Stream `cancel` closes the scope, which
+ * auto-interrupts both fibers and runs their `ensuring` finalizers. No
+ * manual `Fiber.interrupt` bookkeeping.
  */
 export function wrapResponseWithKeepalive(response: Response, intervalMs = DEFAULT_KEEPALIVE_INTERVAL_MS): Response {
   const body = response.body
@@ -14,24 +27,10 @@ export function wrapResponseWithKeepalive(response: Response, intervalMs = DEFAU
 
   let closed = false
   let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
-  let keepaliveFiber: ReturnType<typeof Effect.runFork> | null = null
-  let bodyPumpFiber: ReturnType<typeof Effect.runFork> | null = null
-
-  const interruptFiber = (fiber: ReturnType<typeof Effect.runFork> | null) => {
-    if (!fiber) return
-    void Effect.runFork(Fiber.interrupt(fiber))
-  }
+  const scope = Scope.makeUnsafe()
 
-  const stopKeepalive = () => {
-    const fiber = keepaliveFiber
-    keepaliveFiber = null
-    interruptFiber(fiber)
-  }
-
-  const stopBodyPump = () => {
-    const fiber = bodyPumpFiber
-    bodyPumpFiber = null
-    interruptFiber(fiber)
+  const closeScope = () => {
+    void Effect.runPromise(Scope.close(scope, Exit.void))
   }
 
   const releaseReader = (bodyReader: ReadableStreamDefaultReader<Uint8Array>) => {
@@ -90,7 +89,10 @@ export function wrapResponseWithKeepalive(response: Response, intervalMs = DEFAU
       for (;;) {
         if (closed) return
 
-        const { done, value } = yield* Effect.tryPromise(() => bodyReader.read())
+        const { done, value } = yield* Effect.tryPromise({
+          try: () => bodyReader.read(),
+          catch: (cause) => new SseKeepaliveError({ phase: 'read', cause }),
+        })
         if (done) {
           yield* Effect.sync(() => closeStream(controller))
           return
@@ -105,25 +107,26 @@ export function wrapResponseWithKeepalive(response: Response, intervalMs = DEFAU
       Effect.ensuring(
         Effect.sync(() => {
           closed = true
-          stopKeepalive()
-          bodyPumpFiber = null
           reader = null
           releaseReader(bodyReader)
+          closeScope()
         }),
       ),
     )
 
+  const startFiber = <A, E>(effect: Effect.Effect<A, E>): Fiber.Fiber<Fiber.Fiber<A, E>, never> =>
+    Effect.runFork(Scope.provide(Effect.forkScoped(effect), scope))
+
   const transformed = new ReadableStream<Uint8Array>({
     start(controller) {
       const bodyReader = body.getReader()
       reader = bodyReader
-      keepaliveFiber = Effect.runFork(keepaliveEffect(controller))
-      bodyPumpFiber = Effect.runFork(pumpBodyEffect(bodyReader, controller))
+      startFiber(keepaliveEffect(controller))
+      startFiber(pumpBodyEffect(bodyReader, controller))
     },
     cancel(reason) {
       closed = true
-      stopKeepalive()
-      stopBodyPump()
+      closeScope()
 
       const bodyReader = reader
       reader = null

package/src/workers/bootstrap.ts

@@ -1,17 +1,25 @@
-import { ConfigProvider, Option, Schema, Effect, Layer, ManagedRuntime, Redacted } from 'effect'
-
-import { AiGatewayLive } from '../ai-gateway/ai-gateway'
+import { ConfigProvider, Deferred, Option, Schema, Effect, Layer, ManagedRuntime, Redacted } from 'effect'
+
+import {
+  AiGatewayModelsTag,
+  AiGatewayTag,
+  RuntimeBridgeTag,
+  createAiGatewayModels,
+  makeAiGatewayService,
+} from '../ai-gateway/ai-gateway'
+import type { AiGatewayModels, RuntimeBridge } from '../ai-gateway/ai-gateway'
 import { EmbeddingCacheLive } from '../ai/embedding-cache'
 import { serverLogger } from '../config/logger'
 import { connectWithStartupRetry, waitForDatabaseBootstrap } from '../db/startup'
 import { buildWorkerInfrastructureLayer } from '../effect'
+import { ERROR_TAGS } from '../effect/errors'
 import { DatabaseServiceTag, RuntimeAdaptersServiceTag } from '../effect/services'
 import { lotaRuntimeEnvConfig, parseLotaRuntimeConfig, parseWorkerBootstrapEnv } from '../runtime/runtime-config'
 import { FirecrawlLive } from '../tools/firecrawl-client'
 import { getErrorMessage } from '../utils/errors'
 
 class SandboxedWorkerBootstrapError extends Schema.TaggedErrorClass<SandboxedWorkerBootstrapError>()(
-  'SandboxedWorkerBootstrapError',
+  ERROR_TAGS.SandboxedWorkerBootstrapError,
   {
     stage: Schema.Literals(['setup', 'initialize', 'connect-db', 'connect-plugin-db', 'bootstrap-wait']),
     message: Schema.String,
@@ -86,12 +94,35 @@ function ensureSandboxedWorkerRuntimeConfigured(): Promise<WorkerManagedRuntime>
       const runtimeConfig = yield* buildSandboxedWorkerRuntimeConfigEffect()
 
       const infrastructureLayer = buildWorkerInfrastructureLayer(runtimeConfig)
-
-      const layer = Layer.mergeAll(infrastructureLayer, Layer.provide(AiGatewayLive, infrastructureLayer))
-
-      const fullLayer = Layer.mergeAll(layer, Layer.provide(Layer.mergeAll(EmbeddingCacheLive, FirecrawlLive), layer))
+      const aiGateway = yield* makeAiGatewayService(runtimeConfig).pipe(
+        Effect.mapError((error) => toSandboxedWorkerBootstrapError('setup', error)),
+      )
+      const aiGatewayModelsDeferred = yield* Deferred.make<AiGatewayModels>()
+      const runtimeBridgeDeferred = yield* Deferred.make<RuntimeBridge>()
+      const bridgeLayer = Layer.mergeAll(
+        Layer.succeed(AiGatewayTag, aiGateway),
+        Layer.effect(AiGatewayModelsTag, Deferred.await(aiGatewayModelsDeferred)),
+        Layer.effect(RuntimeBridgeTag, Deferred.await(runtimeBridgeDeferred)),
+      )
+      const layerWithBridge = Layer.mergeAll(infrastructureLayer, bridgeLayer)
+      const fullLayer = Layer.mergeAll(
+        layerWithBridge,
+        Layer.provide(Layer.mergeAll(EmbeddingCacheLive, FirecrawlLive), layerWithBridge),
+      )
 
       const managedRuntime = ManagedRuntime.make(fullLayer)
+      const runtimeBridge: RuntimeBridge = {
+        runPromise: (effect, options) => managedRuntime.runPromise(effect, options),
+        runFork: (effect) => managedRuntime.runFork(effect),
+      }
+      const aiGatewayModels = createAiGatewayModels({
+        gateway: aiGateway,
+        runtimeConfig,
+        runPromise: runtimeBridge.runPromise,
+        runFork: runtimeBridge.runFork,
+      })
+      yield* Deferred.succeed(runtimeBridgeDeferred, runtimeBridge)
+      yield* Deferred.succeed(aiGatewayModelsDeferred, aiGatewayModels)
 
       return managedRuntime
     }),
@@ -111,7 +142,10 @@ export function initializeSandboxedWorkerRuntime(): Promise<WorkerManagedRuntime
   // Assign before the async kicks off so concurrent callers observe the in-flight promise.
   sandboxedWorkerInitPromise = Effect.runPromise(
     Effect.gen(function* () {
-      const env = parseWorkerBootstrapEnv(Bun.env)
+      const env = yield* Effect.try({
+        try: () => parseWorkerBootstrapEnv(Bun.env),
+        catch: (error) => toSandboxedWorkerBootstrapError('setup', error),
+      })
       const runtime = yield* Effect.tryPromise({
         try: () => ensureSandboxedWorkerRuntimeConfigured(),
         catch: (error) => toSandboxedWorkerBootstrapError('setup', error),
@@ -124,7 +158,7 @@ export function initializeSandboxedWorkerRuntime(): Promise<WorkerManagedRuntime
       yield* Effect.tryPromise({
         try: () =>
           connectWithStartupRetry({
-            connect: () => db.connect(),
+            connect: () => runtime.runPromise(db.connect()),
             label: 'sandboxed worker AI database runtime',
             logger: serverLogger,
           }),
@@ -156,7 +190,7 @@ export function initializeSandboxedWorkerRuntime(): Promise<WorkerManagedRuntime
             expectedFingerprint: env.DB_SCHEMA_FINGERPRINT,
             label: 'sandboxed worker runtime',
             logger: serverLogger,
-            connect: () => db.connect(),
+            connect: () => runtime.runPromise(db.connect()),
           }),
         catch: (error) => toSandboxedWorkerBootstrapError('bootstrap-wait', error),
       })
@@ -170,3 +204,33 @@ export function initializeSandboxedWorkerRuntime(): Promise<WorkerManagedRuntime
 
   return sandboxedWorkerInitPromise
 }
+
+/**
+ * Dispose the sandboxed worker runtime and clear both module-level caches so
+ * a subsequent initialize call rebuilds a fresh runtime. Registered as a
+ * SIGTERM/SIGINT handler when the worker process runs as the main entrypoint.
+ */
+// @effect-diagnostics-next-line asyncFunction:off -- host-boundary dispose handler returns Promise by design.
+export async function disposeSandboxedWorkerRuntime(): Promise<void> {
+  const setupPromise = sandboxedWorkerSetupPromise
+  sandboxedWorkerSetupPromise = null
+  sandboxedWorkerInitPromise = null
+  if (!setupPromise) return
+  try {
+    const runtime = await setupPromise
+    await runtime.dispose()
+  } catch (error) {
+    serverLogger.warn`Failed to dispose sandboxed worker runtime: ${error}`
+  }
+}
+
+let sandboxedWorkerShutdownHandlersRegistered = false
+export function registerSandboxedWorkerShutdownHandlers(): void {
+  if (sandboxedWorkerShutdownHandlersRegistered) return
+  sandboxedWorkerShutdownHandlersRegistered = true
+  const handle = () => {
+    void disposeSandboxedWorkerRuntime().catch(() => undefined)
+  }
+  process.once('SIGTERM', handle)
+  process.once('SIGINT', handle)
+}