@lota-sdk/core 0.4.14 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -31,7 +31,7 @@
     "@ai-sdk/openai": "^3.0.53",
     "@chat-adapter/slack": "^4.26.0",
     "@chat-adapter/state-ioredis": "^4.26.0",
-    "@lota-sdk/shared": "0.4.14",
+    "@lota-sdk/shared": "0.4.16",
     "@mendable/firecrawl-js": "^4.18.3",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.168",

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

@@ -977,10 +977,26 @@ export type AiGatewayDeps = {
   runFork: AiGatewayRunFork
 }
 
+let defaultAiGatewayDeps: AiGatewayDeps | undefined
+
+export function setDefaultAiGatewayDeps(deps: AiGatewayDeps): void {
+  defaultAiGatewayDeps = deps
+}
+
+function resolveAiGatewayDeps(deps: AiGatewayDeps | undefined): AiGatewayDeps {
+  if (deps) return deps
+  if (defaultAiGatewayDeps) return defaultAiGatewayDeps
+
+  throw new Error(
+    '[ai-gateway] aiGatewayModel(...) was used before createLotaRuntime initialized the AI gateway. ' +
+      'Create a LotaRuntime first, or use runtime.ai.model/chatModel/embeddingModel.',
+  )
+}
+
 function createAiGatewayLanguageModelMiddleware(
   modelId: string,
   providerId: string,
-  deps: AiGatewayDeps,
+  deps?: AiGatewayDeps,
 ): LanguageModelMiddleware {
   return {
     specificationVersion: 'v3',
@@ -991,10 +1007,11 @@ function createAiGatewayLanguageModelMiddleware(
         ),
       ),
     wrapGenerate: ({ params }) => {
-      const model = resolveProviderModel(deps.gateway.provider, modelId, providerId)
-      return deps.runPromise(
+      const resolvedDeps = resolveAiGatewayDeps(deps)
+      const model = resolveProviderModel(resolvedDeps.gateway.provider, modelId, providerId)
+      return resolvedDeps.runPromise(
         withAiGatewayConcurrency(
-          executeGenerateAttemptPlan(deps.runtimeConfig, modelId, params, () => model.doGenerate(params)).pipe(
+          executeGenerateAttemptPlan(resolvedDeps.runtimeConfig, modelId, params, () => model.doGenerate(params)).pipe(
             Effect.map(({ result }) => ({
               ...result,
               content: injectAiGatewayChatReasoningContent(
@@ -1003,14 +1020,15 @@ function createAiGatewayLanguageModelMiddleware(
               ),
             })),
           ),
-        ).pipe(Effect.provideService(AiGatewayTag, deps.gateway)),
+        ).pipe(Effect.provideService(AiGatewayTag, resolvedDeps.gateway)),
       )
     },
     wrapStream: ({ params }) => {
-      const model = resolveProviderModel(deps.gateway.provider, modelId, providerId)
-      return deps.runPromise(
+      const resolvedDeps = resolveAiGatewayDeps(deps)
+      const model = resolveProviderModel(resolvedDeps.gateway.provider, modelId, providerId)
+      return resolvedDeps.runPromise(
         withAiGatewayStreamConcurrency(
-          executeStreamAttemptPlan(deps.runtimeConfig, modelId, params, () => model.doStream(params)).pipe(
+          executeStreamAttemptPlan(resolvedDeps.runtimeConfig, modelId, params, () => model.doStream(params)).pipe(
             Effect.map((attempt) => ({
               ...attempt,
               result: isReasoningEnabled(params)
@@ -1018,10 +1036,10 @@ function createAiGatewayLanguageModelMiddleware(
                 : attempt.result,
             })),
           ),
-          deps.runFork,
+          resolvedDeps.runFork,
         ).pipe(
           Effect.map(({ result }) => result),
-          Effect.provideService(AiGatewayTag, deps.gateway),
+          Effect.provideService(AiGatewayTag, resolvedDeps.gateway),
         ),
       )
     },
@@ -1097,7 +1115,7 @@ function createAiGatewayEmbeddingModelPlaceholder(modelId: string): AiGatewayEmb
   }
 }
 
-export function aiGatewayModel(modelId: string, deps: AiGatewayDeps) {
+export function aiGatewayModel(modelId: string, deps?: AiGatewayDeps) {
   if (isOpenRouterModel(modelId)) {
     return aiGatewayChatModel(modelId, deps)
   }
@@ -1110,11 +1128,11 @@ export function aiGatewayModel(modelId: string, deps: AiGatewayDeps) {
   )
 }
 
-export function aiGatewayOpenRouterResponseHealingModel(modelId: string, deps: AiGatewayDeps) {
+export function aiGatewayOpenRouterResponseHealingModel(modelId: string, deps?: AiGatewayDeps) {
   return aiGatewayChatModel(modelId, deps)
 }
 
-export function aiGatewayChatModel(modelId: string, deps: AiGatewayDeps) {
+export function aiGatewayChatModel(modelId: string, deps?: AiGatewayDeps) {
   return withAiGatewayDevTools(
     wrapLanguageModel({
       model: createAiGatewayLanguageModelPlaceholder(modelId, OPENAI_CHAT_PROVIDER_ID),
@@ -1123,14 +1141,15 @@ export function aiGatewayChatModel(modelId: string, deps: AiGatewayDeps) {
   )
 }
 
-export function aiGatewayEmbeddingModel(modelId: string, deps: AiGatewayDeps) {
+export function aiGatewayEmbeddingModel(modelId: string, deps?: AiGatewayDeps) {
   return wrapEmbeddingModel({
     model: createAiGatewayEmbeddingModelPlaceholder(modelId),
     middleware: {
       specificationVersion: 'v3',
       wrapEmbed: ({ params }) => {
-        const embeddingModel = deps.gateway.provider.embeddingModel(modelId)
-        return deps.runPromise(
+        const resolvedDeps = resolveAiGatewayDeps(deps)
+        const embeddingModel = resolvedDeps.gateway.provider.embeddingModel(modelId)
+        return resolvedDeps.runPromise(
           withAiGatewayConcurrency(
             withAiGatewayResilience(
               'ai-gateway.embed',
@@ -1139,7 +1158,7 @@ export function aiGatewayEmbeddingModel(modelId: string, deps: AiGatewayDeps) {
                 catch: (cause) => classifyAiGatewayError('ai-gateway.embed', cause),
               }),
             ).pipe(Effect.withSpan('AiGateway.embed'), Effect.annotateSpans({ modelId })),
-          ).pipe(Effect.provideService(AiGatewayTag, deps.gateway)),
+          ).pipe(Effect.provideService(AiGatewayTag, resolvedDeps.gateway)),
         )
       },
     },

package/src/config/constants.ts

@@ -6,7 +6,7 @@ export const MEMORY = {
   MAX_KNN_LIMIT: 100,
 } as const
 
-export const DEFAULT_AI_GATEWAY_URL = 'https://ai-gateway.gobrainy.ai' as const
+export const DEFAULT_AI_GATEWAY_URL = 'https://aigateway.dev.ventur-os.com' as const
 
 /** Validates that a value is a safe integer for KNN queries. Throws if validation fails. */
 export function validateKnnLimit(limit: unknown): number {

package/src/create-runtime.ts

@@ -8,6 +8,7 @@ import {
   RuntimeBridgeTag,
   createAiGatewayModels,
   makeAiGatewayService,
+  setDefaultAiGatewayDeps,
 } from './ai-gateway/ai-gateway'
 import type { AiGatewayModels, RuntimeBridge } from './ai-gateway/ai-gateway'
 import { computeSchemaFingerprint } from './db/schema-fingerprint'
@@ -79,9 +80,9 @@ export interface LotaRuntime {
   config: ResolvedLotaRuntimeConfig
   plugins: Record<string, LotaPlugin>
   systemExecutors: Record<string, SystemNodeExecutor>
-  /** Pre-bound AI gateway model factories. Use instead of the legacy
-   * `aiGatewayChatModel(modelId)` / `aiGatewayModel(modelId)` module-level
-   * helpers — those now require a `deps` argument. */
+  /** Pre-bound AI gateway model factories. Prefer these inside runtime-bound
+   * services; the module-level helpers are bound during runtime creation for
+   * module-scope agent definitions. */
   ai: AiGatewayModels
   connectPluginDatabases(): Promise<void>
   connect(): Promise<void>
@@ -130,12 +131,14 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     runPromise: (effect, options) => managedRuntime.runPromise(effect, options),
     runFork: (effect) => managedRuntime.runFork(effect),
   }
-  const aiGatewayModels = createAiGatewayModels({
+  const aiGatewayDeps = {
     gateway: aiGateway,
     runtimeConfig,
     runPromise: runtimeBridge.runPromise,
     runFork: runtimeBridge.runFork,
-  })
+  }
+  const aiGatewayModels = createAiGatewayModels(aiGatewayDeps)
+  setDefaultAiGatewayDeps(aiGatewayDeps)
 
   if (!Effect.runSync(Deferred.succeed(runtimeBridgeDeferred, runtimeBridge))) {
     throw new ServiceError({ message: 'Failed to initialize the runtime bridge.' })

package/src/queues/plan-agent-heartbeat.queue.ts

@@ -1,4 +1,4 @@
-import type { Job } from 'bullmq'
+import type { Job, JobsOptions } from 'bullmq'
 import { Effect, Schema } from 'effect'
 import type { Context } from 'effect'
 import type IORedis from 'ioredis'
@@ -44,6 +44,7 @@ export type PlanAgentHeartbeatJob = PlanAgentHeartbeatWakeJob | PlanAgentHeartbe
 export const PLAN_AGENT_HEARTBEAT_QUEUE = 'plan-agent-heartbeat'
 const PLAN_AGENT_HEARTBEAT_SWEEP_INTERVAL_MS = 30_000
 const PLAN_AGENT_HEARTBEAT_SWEEP_JOB_ID = 'plan-agent-heartbeat-sweep'
+const REUSABLE_HEARTBEAT_JOB_STATES = new Set(['completed', 'failed'])
 
 export interface PlanAgentHeartbeatWorkerDeps {
   databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
@@ -84,35 +85,50 @@ export function makePlanAgentHeartbeatQueueRuntime(
 ): PlanAgentHeartbeatQueueRuntime {
   const { connectionProvider, queueJobService } = params
 
+  const enqueueReusableHeartbeatJob = async (job: PlanAgentHeartbeatJob, options: JobsOptions): Promise<void> => {
+    const jobId = typeof options.jobId === 'string' ? options.jobId : null
+    if (jobId) {
+      const existing = await queue.getQueue().getJob(jobId)
+      if (existing) {
+        const state = await existing.getState()
+        if (REUSABLE_HEARTBEAT_JOB_STATES.has(state)) {
+          await existing.remove()
+          serverLogger.info`Removed terminal Plan agent heartbeat job before re-enqueue (${jobId}, state=${state})`
+        }
+      }
+    }
+
+    await queue.enqueue(job, options)
+  }
+
   const enqueueDelayedSweep = (delayMs = PLAN_AGENT_HEARTBEAT_SWEEP_INTERVAL_MS): Promise<void> =>
-    queue.enqueue({ type: 'sweep' }, { delay: delayMs, jobId: PLAN_AGENT_HEARTBEAT_SWEEP_JOB_ID })
+    enqueueReusableHeartbeatJob({ type: 'sweep' }, { delay: delayMs, jobId: PLAN_AGENT_HEARTBEAT_SWEEP_JOB_ID })
 
   const processPlanAgentHeartbeatJob = (
     deps: PlanAgentHeartbeatWorkerDeps,
     job: Job<PlanAgentHeartbeatJob>,
   ): Promise<void> => {
     const { planAgentHeartbeatService: service } = deps
-    return Effect.runPromise(
-      Effect.gen(function* () {
-        if (job.data.type === 'wake-node') {
-          const wakeJob: PlanAgentHeartbeatWakeJob = job.data
-          yield* service.wakeNode(wakeJob)
-          return
-        }
-
-        yield* service.sweep({ organizationId: job.data.organizationId })
-        if (!job.data.organizationId) {
-          yield* Effect.tryPromise({
-            try: () => enqueueDelayedSweep(),
-            catch: (cause) =>
-              new PlanAgentHeartbeatQueueError({
-                message: 'Failed to enqueue delayed plan-agent heartbeat sweep.',
-                cause,
-              }),
-          })
-        }
-      }),
-    )
+    const program: Effect.Effect<void, unknown, never> = Effect.gen(function* () {
+      if (job.data.type === 'wake-node') {
+        const wakeJob: PlanAgentHeartbeatWakeJob = job.data
+        yield* service.wakeNode(wakeJob)
+        return
+      }
+
+      yield* service.sweep({ organizationId: job.data.organizationId })
+      if (!job.data.organizationId) {
+        yield* Effect.tryPromise({
+          try: () => enqueueDelayedSweep(),
+          catch: (cause) =>
+            new PlanAgentHeartbeatQueueError({
+              message: 'Failed to enqueue delayed plan-agent heartbeat sweep.',
+              cause,
+            }),
+        })
+      }
+    })
+    return Effect.runPromise(program)
   }
 
   const queue = createQueueFactoryWithDeps<PlanAgentHeartbeatJob, PlanAgentHeartbeatWorkerDeps>({
@@ -130,7 +146,7 @@ export function makePlanAgentHeartbeatQueueRuntime(
 
   return {
     enqueuePlanAgentHeartbeatWake: (wakeParams) =>
-      queue.enqueue({ type: 'wake-node', ...wakeParams }, { jobId: buildWakeJobId(wakeParams) }),
+      enqueueReusableHeartbeatJob({ type: 'wake-node', ...wakeParams }, { jobId: buildWakeJobId(wakeParams) }),
     startWorker: (options) => {
       const handle = queue.startWorker({
         deps: options.deps,

package/src/runtime/domain-layer.ts

@@ -1,7 +1,7 @@
 /**
  * Builds the domain-service Layer tree for `createLotaRuntime`.
  *
- * The services form a 9-tier dependency graph on top of the infrastructure
+ * The services form a tiered dependency graph on top of the infrastructure
  * layer (config, logging, database, redis, agents, threads, extensions).
  * Each tier is provided with the accumulated context of earlier tiers so
  * every service resolves cleanly when the ManagedRuntime eagerly loads them.
@@ -184,10 +184,7 @@ export function buildDomainServiceLayer(infrastructureLayer: InfrastructureLayer
   const tier5 = provide(PlanExecutorServiceLive, ctx4)
   const ctx5 = Layer.mergeAll(ctx4, tier5)
 
-  const tier6 = provide(
-    Layer.mergeAll(OwnershipDispatcherServiceLive, PlanAgentHeartbeatServiceLive, PlanDeadlineServiceLive),
-    ctx5,
-  )
+  const tier6 = provide(Layer.mergeAll(OwnershipDispatcherServiceLive, PlanDeadlineServiceLive), ctx5)
   const ctx6 = Layer.mergeAll(ctx5, tier6)
 
   const tier7 = provide(Layer.mergeAll(ExecutionPlanServiceLive, GlobalOrchestratorServiceLive), ctx6)
@@ -205,5 +202,8 @@ export function buildDomainServiceLayer(infrastructureLayer: InfrastructureLayer
   const ctx8 = Layer.mergeAll(ctx7, tier8)
 
   const tier9 = provide(Layer.mergeAll(PlanCycleServiceLive, ThreadTurnServiceLive), ctx8)
-  return Layer.mergeAll(ctx8, tier9)
+  const ctx9 = Layer.mergeAll(ctx8, tier9)
+
+  const tier10 = provide(PlanAgentHeartbeatServiceLive, ctx9)
+  return Layer.mergeAll(ctx9, tier10)
 }

package/src/services/plan/plan-agent-heartbeat.service.ts

@@ -11,6 +11,8 @@ import { LotaQueuesServiceTag } from '../../queues/queues.service'
 import type { RedisConnectionManager } from '../../redis/connection'
 import { withLeaseLock } from '../../redis/redis-lease-lock'
 import { resolvePlanNodeExecutionVisibility } from '../../runtime/execution-plan-visibility'
+import type { makeThreadTurnService } from '../thread/thread-turn'
+import { ThreadTurnServiceTag } from '../thread/thread-turn'
 import type { makeThreadService } from '../thread/thread.service'
 import { ThreadServiceTag } from '../thread/thread.service'
 import type { makePlanAgentQueryService } from './plan-agent-query.service'
@@ -51,24 +53,24 @@ function heartbeatServiceEffect<A, E, R = never>(
 
 interface PlanAgentHeartbeatDeps {
   agentConfig: ResolvedAgentConfig
-  provideCurrentContext: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, never>
   redis: RedisConnectionManager
   planAgentQueryService: ReturnType<typeof makePlanAgentQueryService>
   planExecutorService: ReturnType<typeof makePlanExecutorService>
   planRunService: ReturnType<typeof makePlanRunService>
   threadService: ReturnType<typeof makeThreadService>
+  threadTurnService: ReturnType<typeof makeThreadTurnService>
   planAgentHeartbeatQueue: PlanAgentHeartbeatQueueRuntime
 }
 
 export function makePlanAgentHeartbeatService(deps: PlanAgentHeartbeatDeps) {
   const {
     agentConfig,
-    provideCurrentContext,
     planExecutorService,
     planRunService,
     redis,
     planAgentQueryService,
     threadService,
+    threadTurnService,
     planAgentHeartbeatQueue,
   } = deps
 
@@ -149,14 +151,9 @@ export function makePlanAgentHeartbeatService(deps: PlanAgentHeartbeatDeps) {
               )
             }
 
-            const { triggerPlanNodeTurn } = yield* Effect.tryPromise({
-              try: () => import('../thread/thread-turn'),
-              catch: (cause) => new PlanAgentHeartbeatError({ operation: 'import-thread-turn', cause }),
-            })
-
             yield* heartbeatServiceEffect(
               'trigger-plan-node-turn',
-              provideCurrentContext(triggerPlanNodeTurn({ runId: params.runId, nodeId: params.nodeId })),
+              threadTurnService.triggerPlanNodeTurn({ runId: params.runId, nodeId: params.nodeId }),
             )
             return true
           }),
@@ -227,24 +224,22 @@ export class PlanAgentHeartbeatServiceTag extends Context.Service<
 export const PlanAgentHeartbeatServiceLive = Layer.effect(
   PlanAgentHeartbeatServiceTag,
   Effect.gen(function* () {
-    const currentContext = yield* Effect.context()
-    const provideCurrentContext = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, never> =>
-      effect.pipe(Effect.provide(currentContext)) as Effect.Effect<A, E, never>
     const agentConfig = yield* AgentConfigServiceTag
     const redis = yield* RedisServiceTag
     const planAgentQueryService = yield* PlanAgentQueryServiceTag
     const planRunService = yield* PlanRunServiceTag
     const planExecutor = yield* PlanExecutorServiceTag
     const threadSvc = yield* ThreadServiceTag
+    const threadTurnSvc = yield* ThreadTurnServiceTag
     const queues = yield* LotaQueuesServiceTag
     return makePlanAgentHeartbeatService({
       agentConfig,
-      provideCurrentContext,
       redis,
       planAgentQueryService,
       planExecutorService: planExecutor,
       planRunService,
       threadService: threadSvc,
+      threadTurnService: threadTurnSvc,
       planAgentHeartbeatQueue: queues.planAgentHeartbeat,
     })
   }),

package/src/services/thread/thread-turn-streaming.ts

@@ -74,7 +74,7 @@ function isTextTokenChunkType(chunkType: string | undefined): boolean {
   return chunkType === 'text-delta'
 }
 
-function buildFallbackResponseMessage(
+export function buildFallbackResponseMessage(
   result: ToolLoopGenerateResult,
 ): Effect.Effect<ChatMessage, ThreadTurnStreamingError> {
   const parts: ChatMessage['parts'] = []
@@ -96,12 +96,6 @@ function buildFallbackResponseMessage(
     parts.push({ type: 'text', text })
   }
 
-  if (parts.length === 0) {
-    return Effect.fail(
-      new ThreadTurnStreamingError({ message: 'Agent generate fallback did not produce any response parts.' }),
-    )
-  }
-
   return Effect.succeed({ id: Bun.randomUUIDv7(), role: 'assistant', parts })
 }
 

package/src/services/thread/thread-turn.ts

@@ -428,14 +428,16 @@ function triggerPlanNodeTurnWith(
   deps: ThreadTurnDeps,
   params: { runId: string; nodeId: string; abortSignal?: AbortSignal; streamId?: string },
 ) {
-  return triggerPlanNodeTurnEffect(deps, params).pipe(
-    Effect.annotateSpans(
-      compactSpanAttributes({
-        turnKind: 'planTurn',
-        streamId: params.streamId,
-        planRunId: params.runId,
-        planNodeId: params.nodeId,
-      }),
+  return deps.provideCurrentContext(
+    triggerPlanNodeTurnEffect(deps, params).pipe(
+      Effect.annotateSpans(
+        compactSpanAttributes({
+          turnKind: 'planTurn',
+          streamId: params.streamId,
+          planRunId: params.runId,
+          planNodeId: params.nodeId,
+        }),
+      ),
     ),
   )
 }

package/src/system-agents/thread-router.agent.ts

@@ -176,14 +176,13 @@ function generateRouterObjectEffect<TSchema extends z.ZodTypeAny>(params: {
   prompt: string
   label: 'triage' | 'check'
 }): Effect.Effect<z.infer<TSchema> | null, never> {
-  const modelId = params.agentConfig.routerModelId ?? 'openrouter/openai/gpt-5.4-nano'
+  const modelId = params.agentConfig.routerModelId ?? 'gpt-5.4-nano'
 
   return Effect.tryPromise({
     try: () =>
       generateObject({
         model: params.aiGatewayModels.chatModel(modelId),
         headers: buildAiGatewayDirectCacheHeaders('lota-sdk'),
-        providerOptions: { openai: { reasoningEffort: 'low' } },
         schema: params.schema,
         system: params.system,
         prompt: params.prompt,