@lota-sdk/core 0.4.12 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -31,13 +31,13 @@
     "@ai-sdk/openai": "^3.0.53",
     "@chat-adapter/slack": "^4.26.0",
     "@chat-adapter/state-ioredis": "^4.26.0",
-    "@lota-sdk/shared": "0.4.12",
+    "@lota-sdk/shared": "0.4.14",
     "@mendable/firecrawl-js": "^4.18.3",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.168",
-    "bullmq": "^5.74.1",
+    "bullmq": "^5.74.2",
     "chat": "^4.26.0",
-    "effect": "^4.0.0-beta.50",
+    "effect": "^4.0.0-beta.52",
     "hono": "^4.12.14",
     "ioredis": "5.9.3",
     "mammoth": "^1.12.0",

package/src/ai/embedding-cache.ts

@@ -1,7 +1,9 @@
 import { Context, Effect, Layer, Schema } from 'effect'
 import type IORedis from 'ioredis'
 
+import { RuntimeBridgeTag } from '../ai-gateway/ai-gateway'
 import { aiLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import { RedisServiceTag, RuntimeConfigServiceTag } from '../effect/services'
 import { sha256Hex } from '../utils/crypto'
 
@@ -9,7 +11,7 @@ export const DEFAULT_EMBEDDING_CACHE_TTL_SECONDS = 7200
 const EMBEDDING_CACHE_KEY_PREFIX = 'emb'
 const EmbeddingCacheJsonSchema = Schema.fromJsonString(Schema.Array(Schema.Number))
 
-class EmbeddingCacheError extends Schema.TaggedErrorClass<EmbeddingCacheError>()('EmbeddingCacheError', {
+class EmbeddingCacheError extends Schema.TaggedErrorClass<EmbeddingCacheError>()(ERROR_TAGS.EmbeddingCacheError, {
   message: Schema.String,
   operation: Schema.Literals(['get', 'set']),
   cause: Schema.optional(Schema.Defect),
@@ -29,7 +31,8 @@ export class EmbeddingCache {
 
   constructor(
     private redis: IORedis,
-    private ttlSeconds: number = DEFAULT_EMBEDDING_CACHE_TTL_SECONDS,
+    private ttlSeconds: number,
+    private readonly runPromise: <A, E = never>(effect: Effect.Effect<A, E>) => Promise<A>,
   ) {}
 
   private buildKey(model: string, text: string): string {
@@ -37,10 +40,6 @@ export class EmbeddingCache {
     return `${EMBEDDING_CACHE_KEY_PREFIX}:${model}:${hash}`
   }
 
-  private runEffect<A>(effect: Effect.Effect<A>): Promise<A> {
-    return Effect.runPromise(effect)
-  }
-
   private fetchFromRedisEffect(key: string): Effect.Effect<number[] | null> {
     const redis = this.redis
 
@@ -58,7 +57,7 @@ export class EmbeddingCache {
           new EmbeddingCacheError({ message: 'Embedding cache parse failed.', operation: 'get', cause }),
       })
     }).pipe(
-      Effect.catchTag('EmbeddingCacheError', (error) => {
+      Effect.catchTag(ERROR_TAGS.EmbeddingCacheError, (error) => {
         aiLogger.warn`${error.message}: ${error.cause}`
         return Effect.succeed<number[] | null>(null)
       }),
@@ -71,7 +70,7 @@ export class EmbeddingCache {
     const pending = this.inflight.get(key)
     if (pending) return pending
 
-    const promise = this.runEffect(this.fetchFromRedisEffect(key))
+    const promise = this.runPromise(this.fetchFromRedisEffect(key))
     this.inflight.set(key, promise)
     void promise.finally(() => this.inflight.delete(key))
 
@@ -95,7 +94,7 @@ export class EmbeddingCache {
       })
     }).pipe(
       Effect.asVoid,
-      Effect.catchTag('EmbeddingCacheError', (error) => {
+      Effect.catchTag(ERROR_TAGS.EmbeddingCacheError, (error) => {
         aiLogger.warn`${error.message}: ${error.cause}`
         return Effect.void
       }),
@@ -103,7 +102,7 @@ export class EmbeddingCache {
   }
 
   set(model: string, text: string, embedding: number[]): Promise<void> {
-    return this.runEffect(this.setEffect(model, text, embedding))
+    return this.runPromise(this.setEffect(model, text, embedding))
   }
 }
 
@@ -111,11 +110,18 @@ export class EmbeddingCacheTag extends Context.Service<EmbeddingCacheTag, Embedd
   '@lota-sdk/core/EmbeddingCache',
 ) {}
 
+/**
+ * `EmbeddingCache` needs a `runPromise` to convert internal Effect chains into
+ * the Promise API that AI SDK `embed` / `embedMany` expect. The layer yields
+ * `RuntimeBridgeTag` once and captures it — callers never prop-drill
+ * `runPromise` through this module.
+ */
 export const EmbeddingCacheLive = Layer.effect(
   EmbeddingCacheTag,
   Effect.gen(function* () {
     const redis = yield* RedisServiceTag
     const config = yield* RuntimeConfigServiceTag
-    return new EmbeddingCache(redis.getConnection(), config.memory.embeddingCacheTtlSeconds)
+    const bridge = yield* RuntimeBridgeTag
+    return new EmbeddingCache(redis.getConnection(), config.memory.embeddingCacheTtlSeconds, bridge.runPromise)
   }),
 )

package/src/ai-gateway/ai-gateway.ts

@@ -5,7 +5,7 @@ import type { LanguageModelMiddleware } from 'ai'
 import { Cause, Clock, Context, Duration, Effect, ExecutionPlan, Fiber, Layer, Semaphore } from 'effect'
 
 import { DEFAULT_AI_GATEWAY_URL } from '../config/constants'
-import { AiGenerationError, ConfigurationError } from '../effect/errors'
+import { ERROR_TAGS, AiGenerationError, ConfigurationError } from '../effect/errors'
 import { RuntimeConfigServiceTag } from '../effect/services'
 import { getDirectOpenRouterProvider, normalizeDirectOpenRouterModelId } from '../openrouter/direct-provider'
 import { isRecord, readString } from '../utils/string'
@@ -26,15 +26,15 @@ type AiGatewayAttemptResult<A> = { source: string; result: A }
 // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
 type AiGatewayRunFork = <A, E>(effect: Effect.Effect<A, E, never>) => Fiber.Fiber<A, E | unknown>
 
-class AiGatewayGenerateAttempt extends Context.Service<
-  AiGatewayGenerateAttempt,
+class AiGatewayGenerateAttemptTag extends Context.Service<
+  AiGatewayGenerateAttemptTag,
   { readonly execute: Effect.Effect<AiGatewayAttemptResult<AiGatewayGenerateResult>, AiGenerationError> }
->()('@lota-sdk/core/internal/AiGatewayGenerateAttempt') {}
+>()('@lota-sdk/core/internal/AiGatewayGenerateAttemptTag') {}
 
-class AiGatewayStreamAttempt extends Context.Service<
-  AiGatewayStreamAttempt,
+class AiGatewayStreamAttemptTag extends Context.Service<
+  AiGatewayStreamAttemptTag,
   { readonly execute: Effect.Effect<AiGatewayAttemptResult<AiGatewayStreamResult>, AiGenerationError> }
->()('@lota-sdk/core/internal/AiGatewayStreamAttempt') {}
+>()('@lota-sdk/core/internal/AiGatewayStreamAttemptTag') {}
 
 const EXPECTED_GATEWAY_KEY_PREFIX = 'sk-bf-'
 const AI_GATEWAY_VIRTUAL_KEY_HEADER = 'x-bf-vk'
@@ -71,7 +71,7 @@ const RETRYABLE_NETWORK_ERROR_PATTERNS = [
 ]
 
 function isAiGenerationError(error: unknown): error is AiGenerationError {
-  return isRecord(error) && error._tag === 'AiGenerationError'
+  return isRecord(error) && error._tag === ERROR_TAGS.AiGenerationError
 }
 
 function getNumericField(value: Record<string, unknown>, key: string): number | null {
@@ -244,7 +244,7 @@ function withAiGatewayResilience<A>(source: string, effect: Effect.Effect<A, AiG
   const retryEffect = Effect.gen(function* () {
     const runAttempt = (attempt: number): Effect.Effect<A, AiGenerationError> =>
       effect.pipe(
-        Effect.catchTag('AiGenerationError', (error) =>
+        Effect.catchTag(ERROR_TAGS.AiGenerationError, (error) =>
           Effect.gen(function* () {
             if (!isRetryableAiGatewayError(error) || attempt >= AI_GATEWAY_MAX_RETRIES - 1) {
               return yield* error
@@ -371,7 +371,15 @@ function withAiGatewayStreamIdleTimeout(
             reader = null
             if (!streamReader) return
 
-            yield* Effect.tryPromise(() => streamReader.cancel(timeoutError)).pipe(Effect.catch(() => Effect.void))
+            yield* Effect.tryPromise({
+              try: () => streamReader.cancel(timeoutError),
+              catch: (cause) =>
+                new AiGenerationError({
+                  source,
+                  message: `[${source}] Stream cancel failed.`,
+                  ...(cause instanceof Error ? { providerData: cause.message } : {}),
+                }),
+            }).pipe(Effect.catch(() => Effect.void))
           }),
         ),
       ),
@@ -388,7 +396,15 @@ function withAiGatewayStreamIdleTimeout(
       for (;;) {
         if (closed) return
 
-        const { done, value } = yield* Effect.tryPromise(() => streamReader.read())
+        const { done, value } = yield* Effect.tryPromise({
+          try: () => streamReader.read(),
+          catch: (cause) =>
+            new AiGenerationError({
+              source,
+              message: `[${source}] Stream read failed.`,
+              ...(cause instanceof Error ? { providerData: cause.message } : {}),
+            }),
+        })
         if (done) {
           stopIdleTimeout()
           yield* Effect.sync(() => closeStream(controller))
@@ -434,7 +450,15 @@ function withAiGatewayStreamIdleTimeout(
       }
 
       return Effect.runPromise(
-        Effect.tryPromise(() => streamReader.cancel(reason)).pipe(Effect.catch(() => Effect.void)),
+        Effect.tryPromise({
+          try: () => streamReader.cancel(reason),
+          catch: (cause) =>
+            new AiGenerationError({
+              source,
+              message: `[${source}] Stream cancel failed.`,
+              ...(cause instanceof Error ? { providerData: cause.message } : {}),
+            }),
+        }).pipe(Effect.catch(() => Effect.void)),
       )
     },
   })
@@ -457,12 +481,22 @@ function withDefaultAiGatewayCacheHeaders(params: AiGatewayCallOptions): AiGatew
   return { ...params, headers: mergeAiGatewayHeaders(params.headers, buildAiGatewayCacheHeaders('lota-sdk')) }
 }
 
+function normalizeAiGatewayUrlEffect(value: string): Effect.Effect<string, ConfigurationError> {
+  const trimmed = value.trim()
+  if (!trimmed) {
+    return Effect.fail(
+      new ConfigurationError({ message: '[ai-gateway] AI gateway URL is required.', key: 'aiGateway.url' }),
+    )
+  }
+  const normalized = trimmed.replace(/\/+$/, '')
+  return Effect.succeed(normalized.endsWith('/v1') ? normalized : `${normalized}/v1`)
+}
+
 function normalizeAiGatewayUrl(value: string): string {
   const trimmed = value.trim()
   if (!trimmed) {
     throw new ConfigurationError({ message: '[ai-gateway] AI gateway URL is required.', key: 'aiGateway.url' })
   }
-
   const normalized = trimmed.replace(/\/+$/, '')
   return normalized.endsWith('/v1') ? normalized : `${normalized}/v1`
 }
@@ -473,10 +507,10 @@ export class AiGatewayTag extends Context.Service<
   { readonly semaphore: Semaphore.Semaphore; readonly provider: ReturnType<typeof createOpenAI> }
 >()('@lota-sdk/core/AiGateway') {}
 
-export const AiGatewayLive = Layer.effect(
-  AiGatewayTag,
-  Effect.gen(function* () {
-    const config = yield* RuntimeConfigServiceTag
+export function makeAiGatewayService(
+  config: AiGatewayRuntimeConfig,
+): Effect.Effect<Context.Service.Shape<typeof AiGatewayTag>, ConfigurationError> {
+  return Effect.gen(function* () {
     const semaphore = yield* Semaphore.make(config.aiGateway.maxConcurrency)
 
     const apiKey = config.aiGateway.key.trim()
@@ -486,10 +520,18 @@ export const AiGatewayLive = Layer.effect(
         key: 'aiGateway.key',
       })
     }
-    const baseURL = normalizeAiGatewayUrl(config.aiGateway.url)
+    const baseURL = yield* normalizeAiGatewayUrlEffect(config.aiGateway.url)
     const provider = createOpenAI({ baseURL, apiKey, headers: { [AI_GATEWAY_VIRTUAL_KEY_HEADER]: apiKey } })
 
     return AiGatewayTag.of({ semaphore, provider })
+  })
+}
+
+export const AiGatewayLive = Layer.effect(
+  AiGatewayTag,
+  Effect.gen(function* () {
+    const config = yield* RuntimeConfigServiceTag
+    return yield* makeAiGatewayService(config)
   }),
 )
 
@@ -514,11 +556,26 @@ function withAiGatewayStreamConcurrency(
       const currentContext = yield* Effect.context<never>()
       yield* semaphore.take(1)
 
-      // NOTE: manual release intentional — permit outlives Effect scope for the
-      // stream lifetime. The stream consumer drains asynchronously after this
-      // Effect resolves; the permit is released by either the idle-timeout
-      // finalize callback or the error path below. The `released` guard makes
-      // the release idempotent across those paths.
+      // Permit-release impedance bridge. The semaphore permit MUST outlive
+      // the surrounding Effect because the returned ReadableStream is drained
+      // by an external consumer (AI SDK middleware → fetch consumer) on a
+      // promise/callback timeline that has no Effect scope to attach to.
+      //
+      // We considered Layer.scoped + Effect.acquireRelease here. It does not
+      // fit: the stream's close/cancel/idle-timeout callbacks fire from
+      // outside any Effect, so a Scope-bound finalizer cannot observe them
+      // without running the close itself through `Effect.runFork(Scope.close)`
+      // — which is the same imperative shape as the latch below, just more
+      // ceremony.
+      //
+      // The `released = false` latch keeps `release()` idempotent across the
+      // three callback edges that can fire it:
+      //   1. error path        — Effect.catchTag + Effect.sync(release)
+      //   2. interrupt path    — Effect.onInterrupt + Effect.sync(release)
+      //   3. idle-timeout path — withAiGatewayStreamIdleTimeout's onFinalize
+      //
+      // `Effect.runForkWith(currentContext)(semaphore.release(1))` preserves
+      // span/logger context across the boundary so observability stays intact.
       let released = false
       const release = () => {
         if (released) return
@@ -527,7 +584,9 @@ function withAiGatewayStreamConcurrency(
       }
 
       const attempt = yield* restore(effect).pipe(
-        Effect.catchTag('AiGenerationError', (error) => Effect.sync(release).pipe(Effect.andThen(Effect.fail(error)))),
+        Effect.catchTag(ERROR_TAGS.AiGenerationError, (error) =>
+          Effect.sync(release).pipe(Effect.andThen(Effect.fail(error))),
+        ),
         Effect.onInterrupt(() => Effect.sync(release)),
       )
 
@@ -736,11 +795,11 @@ function executeGenerateAttemptPlan(
   params: AiGatewayCallOptions,
   doGenerate: () => PromiseLike<AiGatewayGenerateResult>,
 ): Effect.Effect<AiGatewayAttemptResult<AiGatewayGenerateResult>, AiGenerationError> {
-  const primary = Layer.succeed(AiGatewayGenerateAttempt, {
+  const primary = Layer.succeed(AiGatewayGenerateAttemptTag, {
     execute: attemptAiGatewayGenerate('ai-gateway.generate', doGenerate),
   })
   const effect = Effect.gen(function* () {
-    const attempt = yield* AiGatewayGenerateAttempt
+    const attempt = yield* AiGatewayGenerateAttemptTag
     return yield* attempt.execute
   })
 
@@ -757,7 +816,7 @@ function executeGenerateAttemptPlan(
       ExecutionPlan.make(
         { provide: primary },
         {
-          provide: Layer.succeed(AiGatewayGenerateAttempt, {
+          provide: Layer.succeed(AiGatewayGenerateAttemptTag, {
             execute: attemptDirectOpenRouterGenerate(config, modelId, params),
           }),
           while: (error: AiGenerationError) => shouldFallbackToDirectOpenRouter(config, modelId, error),
@@ -775,11 +834,11 @@ function executeStreamAttemptPlan(
   params: AiGatewayCallOptions,
   doStream: () => PromiseLike<AiGatewayStreamResult>,
 ): Effect.Effect<AiGatewayAttemptResult<AiGatewayStreamResult>, AiGenerationError> {
-  const primary = Layer.succeed(AiGatewayStreamAttempt, {
+  const primary = Layer.succeed(AiGatewayStreamAttemptTag, {
     execute: attemptAiGatewayStream('ai-gateway.stream', doStream),
   })
   const effect = Effect.gen(function* () {
-    const attempt = yield* AiGatewayStreamAttempt
+    const attempt = yield* AiGatewayStreamAttemptTag
     return yield* attempt.execute
   })
 
@@ -796,7 +855,7 @@ function executeStreamAttemptPlan(
       ExecutionPlan.make(
         { provide: primary },
         {
-          provide: Layer.succeed(AiGatewayStreamAttempt, {
+          provide: Layer.succeed(AiGatewayStreamAttemptTag, {
             execute: attemptDirectOpenRouterStream(config, modelId, params),
           }),
           while: (error: AiGenerationError) => shouldFallbackToDirectOpenRouter(config, modelId, error),
@@ -911,48 +970,18 @@ function resolveProviderModel(
   return providerId === OPENAI_CHAT_PROVIDER_ID ? provider.chat(modelId) : provider(modelId)
 }
 
-// Module-level Promise slot that `createLotaRuntime` populates during boot.
-// This is a legitimate per-process singleton (mirrors the worker bootstrap
-// pattern in `workers/bootstrap.ts`): the AI gateway middleware is dispatched
-// by AI SDK callers that live outside Effect context, so the middleware needs
-// a way to run gateway Effects without capturing a `ManagedRuntime` through
-// every `aiGatewayModel(modelId)` call site.
-//
-// Only `createLotaRuntime` writes to the slot; resetting on disconnect is a
-// Phase 3b concern — for now it stays alive for the process lifetime.
-let aiGatewayRuntimeReady: Promise<{
-  gateway: Context.Service.Shape<typeof AiGatewayTag>
-  runtimeConfig: Context.Service.Shape<typeof RuntimeConfigServiceTag>
-  runPromise: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
-  runFork: AiGatewayRunFork
-}> | null = null
-
-export function bindAiGatewayRuntime(params: {
-  gateway: Context.Service.Shape<typeof AiGatewayTag>
-  runtimeConfig: Context.Service.Shape<typeof RuntimeConfigServiceTag>
-  runPromise: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
-  runFork: AiGatewayRunFork
-}): void {
-  aiGatewayRuntimeReady = Promise.resolve(params)
-}
-
-export function clearAiGatewayRuntime(): void {
-  aiGatewayRuntimeReady = null
-}
-
-async function getAiGatewayRuntime(): Promise<{
+export type AiGatewayDeps = {
   gateway: Context.Service.Shape<typeof AiGatewayTag>
   runtimeConfig: Context.Service.Shape<typeof RuntimeConfigServiceTag>
   runPromise: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>
   runFork: AiGatewayRunFork
-}> {
-  if (!aiGatewayRuntimeReady) {
-    throw new Error('AI gateway runtime has not been initialized. Call createLotaRuntime() first.')
-  }
-  return aiGatewayRuntimeReady
 }
 
-function createAiGatewayLanguageModelMiddleware(modelId: string, providerId: string): LanguageModelMiddleware {
+function createAiGatewayLanguageModelMiddleware(
+  modelId: string,
+  providerId: string,
+  deps: AiGatewayDeps,
+): LanguageModelMiddleware {
   return {
     specificationVersion: 'v3',
     transformParams: ({ params, type }) =>
@@ -961,12 +990,11 @@ function createAiGatewayLanguageModelMiddleware(modelId: string, providerId: str
           addAiGatewayReasoningRawChunks(normalizeAiGatewayChatProviderOptions(params, modelId), type),
         ),
       ),
-    wrapGenerate: async ({ params }) => {
-      const { gateway, runtimeConfig, runPromise } = await getAiGatewayRuntime()
-      const model = resolveProviderModel(gateway.provider, modelId, providerId)
-      return runPromise(
+    wrapGenerate: ({ params }) => {
+      const model = resolveProviderModel(deps.gateway.provider, modelId, providerId)
+      return deps.runPromise(
         withAiGatewayConcurrency(
-          executeGenerateAttemptPlan(runtimeConfig, modelId, params, () => model.doGenerate(params)).pipe(
+          executeGenerateAttemptPlan(deps.runtimeConfig, modelId, params, () => model.doGenerate(params)).pipe(
             Effect.map(({ result }) => ({
               ...result,
               content: injectAiGatewayChatReasoningContent(
@@ -975,15 +1003,14 @@ function createAiGatewayLanguageModelMiddleware(modelId: string, providerId: str
               ),
             })),
           ),
-        ).pipe(Effect.provideService(AiGatewayTag, gateway)),
+        ).pipe(Effect.provideService(AiGatewayTag, deps.gateway)),
       )
     },
-    wrapStream: async ({ params }) => {
-      const { gateway, runtimeConfig, runPromise, runFork } = await getAiGatewayRuntime()
-      const model = resolveProviderModel(gateway.provider, modelId, providerId)
-      return runPromise(
+    wrapStream: ({ params }) => {
+      const model = resolveProviderModel(deps.gateway.provider, modelId, providerId)
+      return deps.runPromise(
         withAiGatewayStreamConcurrency(
-          executeStreamAttemptPlan(runtimeConfig, modelId, params, () => model.doStream(params)).pipe(
+          executeStreamAttemptPlan(deps.runtimeConfig, modelId, params, () => model.doStream(params)).pipe(
             Effect.map((attempt) => ({
               ...attempt,
               result: isReasoningEnabled(params)
@@ -991,10 +1018,11 @@ function createAiGatewayLanguageModelMiddleware(modelId: string, providerId: str
                 : attempt.result,
             })),
           ),
-          runFork,
-        )
-          .pipe(Effect.map(({ result }) => result))
-          .pipe(Effect.provideService(AiGatewayTag, gateway)),
+          deps.runFork,
+        ).pipe(
+          Effect.map(({ result }) => result),
+          Effect.provideService(AiGatewayTag, deps.gateway),
+        ),
       )
     },
   }
@@ -1069,41 +1097,40 @@ function createAiGatewayEmbeddingModelPlaceholder(modelId: string): AiGatewayEmb
   }
 }
 
-export function aiGatewayModel(modelId: string) {
+export function aiGatewayModel(modelId: string, deps: AiGatewayDeps) {
   if (isOpenRouterModel(modelId)) {
-    return aiGatewayChatModel(modelId)
+    return aiGatewayChatModel(modelId, deps)
   }
 
   return withAiGatewayDevTools(
     wrapLanguageModel({
       model: createAiGatewayLanguageModelPlaceholder(modelId, OPENAI_RESPONSES_PROVIDER_ID),
-      middleware: createAiGatewayLanguageModelMiddleware(modelId, OPENAI_RESPONSES_PROVIDER_ID),
+      middleware: createAiGatewayLanguageModelMiddleware(modelId, OPENAI_RESPONSES_PROVIDER_ID, deps),
     }),
   )
 }
 
-export function aiGatewayOpenRouterResponseHealingModel(modelId: string) {
-  return aiGatewayChatModel(modelId)
+export function aiGatewayOpenRouterResponseHealingModel(modelId: string, deps: AiGatewayDeps) {
+  return aiGatewayChatModel(modelId, deps)
 }
 
-export function aiGatewayChatModel(modelId: string) {
+export function aiGatewayChatModel(modelId: string, deps: AiGatewayDeps) {
   return withAiGatewayDevTools(
     wrapLanguageModel({
       model: createAiGatewayLanguageModelPlaceholder(modelId, OPENAI_CHAT_PROVIDER_ID),
-      middleware: createAiGatewayLanguageModelMiddleware(modelId, OPENAI_CHAT_PROVIDER_ID),
+      middleware: createAiGatewayLanguageModelMiddleware(modelId, OPENAI_CHAT_PROVIDER_ID, deps),
     }),
   )
 }
 
-export function aiGatewayEmbeddingModel(modelId: string) {
+export function aiGatewayEmbeddingModel(modelId: string, deps: AiGatewayDeps) {
   return wrapEmbeddingModel({
     model: createAiGatewayEmbeddingModelPlaceholder(modelId),
     middleware: {
       specificationVersion: 'v3',
-      wrapEmbed: async ({ params }) => {
-        const { gateway, runPromise } = await getAiGatewayRuntime()
-        const embeddingModel = gateway.provider.embeddingModel(modelId)
-        return runPromise(
+      wrapEmbed: ({ params }) => {
+        const embeddingModel = deps.gateway.provider.embeddingModel(modelId)
+        return deps.runPromise(
           withAiGatewayConcurrency(
             withAiGatewayResilience(
               'ai-gateway.embed',
@@ -1112,11 +1139,54 @@ export function aiGatewayEmbeddingModel(modelId: string) {
                 catch: (cause) => classifyAiGatewayError('ai-gateway.embed', cause),
               }),
             ).pipe(Effect.withSpan('AiGateway.embed'), Effect.annotateSpans({ modelId })),
-          ).pipe(Effect.provideService(AiGatewayTag, gateway)),
+          ).pipe(Effect.provideService(AiGatewayTag, deps.gateway)),
         )
       },
     },
   })
 }
 
+/**
+ * Pre-bound AI gateway model surface. Produced once per `LotaRuntime` in
+ * `createLotaRuntime` and provided via `AiGatewayModelsTag` so services and
+ * system-agent factories consume it through standard DI rather than an
+ * ambient module slot.
+ */
+export type AiGatewayModels = {
+  model(modelId: string): ReturnType<typeof aiGatewayModel>
+  chatModel(modelId: string): ReturnType<typeof aiGatewayChatModel>
+  embeddingModel(modelId: string): ReturnType<typeof aiGatewayEmbeddingModel>
+  openRouterResponseHealingModel(modelId: string): ReturnType<typeof aiGatewayOpenRouterResponseHealingModel>
+}
+
+export function createAiGatewayModels(deps: AiGatewayDeps): AiGatewayModels {
+  return {
+    model: (modelId: string) => aiGatewayModel(modelId, deps),
+    chatModel: (modelId: string) => aiGatewayChatModel(modelId, deps),
+    embeddingModel: (modelId: string) => aiGatewayEmbeddingModel(modelId, deps),
+    openRouterResponseHealingModel: (modelId: string) => aiGatewayOpenRouterResponseHealingModel(modelId, deps),
+  }
+}
+
+export class AiGatewayModelsTag extends Context.Service<AiGatewayModelsTag, AiGatewayModels>()(
+  '@lota-sdk/core/AiGatewayModels',
+) {}
+
+/**
+ * Runtime bridge surface. Services and tool factories that need to convert
+ * Effects to Promises at a host boundary (AI SDK tool callbacks, BullMQ worker
+ * processors, etc.) yield this tag to obtain the `runPromise` and `runFork`
+ * bound to the outer `ManagedRuntime`. Provided once in `createLotaRuntime`
+ * via a function-local holder so services DI their runtime bridge rather than
+ * capturing context with `Effect.runPromiseWith`.
+ */
+export type RuntimeBridge = {
+  runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: { signal?: AbortSignal }) => Promise<A>
+  runFork: AiGatewayRunFork
+}
+
+export class RuntimeBridgeTag extends Context.Service<RuntimeBridgeTag, RuntimeBridge>()(
+  '@lota-sdk/core/RuntimeBridge',
+) {}
+
 export { DEFAULT_AI_GATEWAY_URL, normalizeAiGatewayUrl }

package/src/ai-gateway/index.ts

@@ -1,12 +1,14 @@
 export {
   AiGatewayLive,
+  AiGatewayModelsTag,
   AiGatewayTag,
   DEFAULT_AI_GATEWAY_URL,
+  RuntimeBridgeTag,
   aiGatewayChatModel,
   aiGatewayEmbeddingModel,
   aiGatewayModel,
   aiGatewayOpenRouterResponseHealingModel,
-  bindAiGatewayRuntime,
+  createAiGatewayModels,
   extractAiGatewayChatReasoningDeltaText,
   extractAiGatewayChatReasoningText,
   injectAiGatewayChatReasoningContent,
@@ -14,4 +16,5 @@ export {
   normalizeAiGatewayChatProviderOptions,
   normalizeAiGatewayUrl,
 } from './ai-gateway'
+export type { AiGatewayDeps, AiGatewayModels, RuntimeBridge } from './ai-gateway'
 export * from './cache-headers'

package/src/config/agent-defaults.ts

@@ -8,8 +8,8 @@ import type {
   AgentToolBuilder,
 } from './agent-types'
 
-function defaultBuildAgentTools(): ToolSet {
-  return {}
+function defaultBuildAgentTools(): Promise<ToolSet> {
+  return Promise.resolve({})
 }
 
 function defaultGetAgentRuntimeConfig(params: AgentRuntimeConfigParams) {

package/src/config/agent-types.ts

@@ -55,7 +55,7 @@ export type AgentCreator = <TTools extends ToolSet>(
 export type AgentFactory = Partial<Record<string, AgentCreator>>
 
 /** Builds the tool set for a given agent. */
-export type AgentToolBuilder = (params: AgentToolBuilderParams) => ToolSet | Promise<ToolSet>
+export type AgentToolBuilder = (params: AgentToolBuilderParams) => Promise<ToolSet>
 
 /** Returns runtime configuration for a given agent. */
 export type AgentRuntimeConfigProvider = (params: AgentRuntimeConfigParams) => AgentRuntimeConfig<string>