@lota-sdk/core 0.4.8 → 0.4.9

package/src/index.ts

@@ -6,10 +6,55 @@ export * from './db'
 export * from './document'
 export * from './queues'
 export * from './redis'
-export * from './runtime/index'
+export * from './runtime'
 export * from './services'
 export * from './storage'
 export * from './system-agents'
 export * from './tools'
 export * from './utils'
 export * from './workers'
+export { Effect } from 'effect'
+export {
+  AgentConfigLive,
+  AgentFactoryLive,
+  AppLoggerTag,
+  AppLoggerLive,
+  EffectBadRequestError,
+  clearLotaSdkRuntime,
+  ConfigurationError,
+  ConflictError,
+  DatabaseError,
+  DatabaseLive,
+  DatabaseServiceTag as EffectDatabaseService,
+  EffectNotFoundError,
+  EffectThreadTurnError,
+  EffectValidationError,
+  getLotaSdkRuntime,
+  isEffectError,
+  LockAcquisitionError,
+  LockLostError,
+  ActiveThreadRunConflictError,
+  RedisError,
+  RedisLive,
+  RedisServiceTag as EffectRedisService,
+  RuntimeAdaptersServiceTag,
+  RuntimeConfigLive,
+  RuntimeConfigServiceTag,
+  RuntimeExtensionsLive,
+  RuntimeWorkerExtensionsServiceTag,
+  setLotaSdkRuntime,
+  ThreadConfigLive,
+  ThreadConfigServiceTag,
+  TimeoutError,
+  ToolProvidersServiceTag,
+  TurnHooksServiceTag,
+  toAwaitableEffect,
+  toAwaitableService,
+  summarizeZodIssues,
+  toValidationError,
+  toValidationIssues,
+  zodParse,
+} from './effect'
+export { AppError, BadRequestError, NotFoundError } from './utils'
+export type { AppErrorLike, AppErrorResponse } from './utils'
+export type { EffectError, ValidationIssue } from './effect'

package/src/openrouter/direct-provider.ts

@@ -1,53 +1,29 @@
 import { createOpenAI } from '@ai-sdk/openai'
 
-import { getRuntimeConfig } from '../runtime/runtime-config'
+import { ConfigurationError } from '../effect/errors'
 
 const DIRECT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1' as const
 const OPENROUTER_MODEL_PREFIX = 'openrouter/' as const
 
-let directOpenRouterProvider: ReturnType<typeof createOpenAI> | null = null
-let directOpenRouterProviderKey: string | null = null
+export function resolveOpenRouterApiKey(openRouterApiKey: string | undefined): string {
+  const key = openRouterApiKey?.trim()
+  if (key) return key
 
-function readConfiguredOpenRouterApiKey(): string | null {
-  try {
-    return getRuntimeConfig().aiGateway.openRouterApiKey?.trim() || null
-  } catch {
-    return null
-  }
-}
-
-export function resolveOpenRouterApiKey(): string {
-  const configured = readConfiguredOpenRouterApiKey()
-  if (configured) return configured
-
-  const envKey = process.env.OPENROUTER_API_KEY?.trim()
-  if (envKey) return envKey
-
-  throw new Error('Missing OpenRouter API key. Set aiGateway.openRouterApiKey or OPENROUTER_API_KEY.')
+  throw new ConfigurationError({
+    message: 'Missing OpenRouter API key. Configure createLotaRuntime({ aiGateway: { openRouterApiKey } }).',
+    key: 'aiGateway.openRouterApiKey',
+  })
 }
 
 export function normalizeDirectOpenRouterModelId(modelId: string): string {
   const normalized = modelId.trim()
   if (!normalized) {
-    throw new Error('OpenRouter model id is required.')
+    throw new ConfigurationError({ message: 'OpenRouter model id is required.', key: 'openRouterModelId' })
   }
 
   return normalized.startsWith(OPENROUTER_MODEL_PREFIX) ? normalized.slice(OPENROUTER_MODEL_PREFIX.length) : normalized
 }
 
-export function getDirectOpenRouterProvider() {
-  const apiKey = resolveOpenRouterApiKey()
-  if (directOpenRouterProvider && directOpenRouterProviderKey === apiKey) {
-    return directOpenRouterProvider
-  }
-
-  directOpenRouterProvider = createOpenAI({ baseURL: DIRECT_OPENROUTER_BASE_URL, apiKey })
-  directOpenRouterProviderKey = apiKey
-
-  return directOpenRouterProvider
-}
-
-export function resetDirectOpenRouterProviderForTests(): void {
-  directOpenRouterProvider = null
-  directOpenRouterProviderKey = null
+export function getDirectOpenRouterProvider(openRouterApiKey?: string) {
+  return createOpenAI({ baseURL: DIRECT_OPENROUTER_BASE_URL, apiKey: resolveOpenRouterApiKey(openRouterApiKey) })
 }

package/src/queues/autonomous-job.queue.ts

@@ -1,14 +1,18 @@
 import type { AutonomousJobSchedule } from '@lota-sdk/shared'
 import type { Job } from 'bullmq'
+import { Effect } from 'effect'
+import type { Context } from 'effect'
+import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
-import { databaseService } from '../db/service'
-import { autonomousJobService } from '../services/autonomous-job.service'
-import { queueJobService } from '../services/queue-job.service'
+import { ConfigurationError } from '../effect/errors'
+import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import { AutonomousJobServiceTag } from '../services/autonomous-job.service'
 import { buildAutonomousAtJobId } from '../utils/autonomous-job-ids'
 import type { WorkerHandle } from '../workers/worker-utils'
-import { DEFAULT_JOB_RETENTION } from '../workers/worker-utils'
+import { DEFAULT_JOB_RETENTION, getQueueJobService } from '../workers/worker-utils'
 import { createQueueFactory } from './queue-factory'
+import { runStandaloneQueueWorker } from './standalone-worker'
 
 export interface AutonomousJobQueuePayload {
   autonomousJobId: string
@@ -18,17 +22,29 @@ export interface AutonomousJobQueuePayload {
 
 export const AUTONOMOUS_JOB_QUEUE = 'autonomous-job'
 
+interface AutonomousJobQueueDeps {
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
+  autonomousJobService: Context.Service.Shape<typeof AutonomousJobServiceTag>
+}
+
+let _deps: AutonomousJobQueueDeps | null = null
+function getDeps(): AutonomousJobQueueDeps {
+  if (!_deps)
+    throw new ConfigurationError({
+      message: 'Autonomous job queue is not configured. Initialize the runtime before starting the worker.',
+      key: 'queue-deps',
+    })
+  return _deps
+}
+
 const DEFAULT_AUTONOMOUS_JOB_OPTIONS = {
   ...DEFAULT_JOB_RETENTION,
   attempts: 3,
   backoff: { type: 'exponential', delay: 5_000 },
 } as const
 
-async function processAutonomousJob(
-  job: Job<AutonomousJobQueuePayload>,
-): Promise<{ status: string; summary?: string }> {
-  await databaseService.connect()
-  return autonomousJobService.executeQueuedRun(job)
+function processAutonomousJob(job: Job<AutonomousJobQueuePayload>): Promise<{ status: string; summary?: string }> {
+  return Effect.runPromise(getDeps().autonomousJobService.executeQueuedRun(job))
 }
 
 const autonomousJobQueue = createQueueFactory<AutonomousJobQueuePayload>({
@@ -37,6 +53,7 @@ const autonomousJobQueue = createQueueFactory<AutonomousJobQueuePayload>({
   jobName: 'run-autonomous-job',
   concurrency: 2,
   defaultJobOptions: DEFAULT_AUTONOMOUS_JOB_OPTIONS,
+  prepare: () => getDeps().databaseService.connect(),
   processor: processAutonomousJob,
 })
 
@@ -44,91 +61,130 @@ function buildAutonomousSchedulerId(autonomousJobId: string): string {
   return `autonomous:${autonomousJobId}`
 }
 
-export async function enqueueAutonomousJobRun(params: {
+export function enqueueAutonomousJobRun(params: {
   payload: AutonomousJobQueuePayload
   delayMs?: number
   jobId?: string
 }): Promise<{ bullmqJobId: string; queueJobId?: string }> {
-  const queuedJob = await autonomousJobQueue
-    .getQueue()
-    .add('run-autonomous-job', params.payload, {
-      ...(typeof params.delayMs === 'number' ? { delay: Math.max(0, params.delayMs) } : {}),
-      ...(params.jobId ? { jobId: params.jobId } : {}),
-    })
-
-  const bullmqJobId = String(queuedJob.id)
-  let queueJobId: string | undefined
-
-  try {
-    queueJobId = await queueJobService.recordEnqueued({
-      queueName: AUTONOMOUS_JOB_QUEUE,
-      id: queuedJob.id,
-      name: queuedJob.name,
-      data: queuedJob.data,
-      opts: queuedJob.opts,
-      attemptsMade: queuedJob.attemptsMade,
-      timestamp: queuedJob.timestamp,
-    })
-  } catch (error) {
-    serverLogger.error`Failed to persist queued job metadata (queue=${AUTONOMOUS_JOB_QUEUE}, job=${queuedJob.id}): ${error}`
-  }
-
-  return { bullmqJobId, queueJobId }
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const queuedJob = yield* Effect.tryPromise(() =>
+        autonomousJobQueue
+          .getQueue()
+          .add('run-autonomous-job', params.payload, {
+            ...(typeof params.delayMs === 'number' ? { delay: Math.max(0, params.delayMs) } : {}),
+            ...(params.jobId ? { jobId: params.jobId } : {}),
+          }),
+      )
+
+      const bullmqJobId = String(queuedJob.id)
+      const queueJobId = yield* Effect.catch(
+        getQueueJobService().recordEnqueued({
+          queueName: AUTONOMOUS_JOB_QUEUE,
+          id: queuedJob.id,
+          name: queuedJob.name,
+          data: queuedJob.data,
+          opts: queuedJob.opts,
+          attemptsMade: queuedJob.attemptsMade,
+          timestamp: queuedJob.timestamp,
+        }),
+        (error) =>
+          Effect.sync(() => {
+            serverLogger.error`Failed to persist queued job metadata (queue=${AUTONOMOUS_JOB_QUEUE}, job=${queuedJob.id}): ${error}`
+            return undefined
+          }),
+      )
+      return { bullmqJobId, queueJobId }
+    }),
+  )
 }
 
-export async function upsertAutonomousJobScheduler(params: {
+export function upsertAutonomousJobScheduler(params: {
   autonomousJobId: string
   schedule: Extract<AutonomousJobSchedule, { kind: 'cron' | 'every' }>
 }): Promise<void> {
   const repeatOpts =
     params.schedule.kind === 'cron' ? { pattern: params.schedule.cron } : { every: params.schedule.intervalMs }
-  const queuedJob = await autonomousJobQueue
-    .getQueue()
-    .upsertJobScheduler(buildAutonomousSchedulerId(params.autonomousJobId), repeatOpts, {
-      name: 'run-autonomous-job',
-      data: { autonomousJobId: params.autonomousJobId, trigger: 'scheduled' },
-      opts: DEFAULT_AUTONOMOUS_JOB_OPTIONS,
-    })
-
-  try {
-    await queueJobService.recordEnqueued({
-      queueName: AUTONOMOUS_JOB_QUEUE,
-      id: queuedJob.id,
-      name: queuedJob.name,
-      data: queuedJob.data,
-      opts: queuedJob.opts,
-      attemptsMade: queuedJob.attemptsMade,
-      timestamp: queuedJob.timestamp,
-    })
-  } catch (error) {
-    serverLogger.error`Failed to persist queued job metadata (queue=${AUTONOMOUS_JOB_QUEUE}, job=${queuedJob.id}): ${error}`
-  }
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const queuedJob = yield* Effect.tryPromise(() =>
+        autonomousJobQueue
+          .getQueue()
+          .upsertJobScheduler(buildAutonomousSchedulerId(params.autonomousJobId), repeatOpts, {
+            name: 'run-autonomous-job',
+            data: { autonomousJobId: params.autonomousJobId, trigger: 'scheduled' },
+            opts: DEFAULT_AUTONOMOUS_JOB_OPTIONS,
+          }),
+      )
+
+      yield* Effect.catch(
+        getQueueJobService().recordEnqueued({
+          queueName: AUTONOMOUS_JOB_QUEUE,
+          id: queuedJob.id,
+          name: queuedJob.name,
+          data: queuedJob.data,
+          opts: queuedJob.opts,
+          attemptsMade: queuedJob.attemptsMade,
+          timestamp: queuedJob.timestamp,
+        }),
+        (error) =>
+          Effect.sync(() => {
+            serverLogger.error`Failed to persist queued job metadata (queue=${AUTONOMOUS_JOB_QUEUE}, job=${queuedJob.id}): ${error}`
+          }),
+      )
+    }),
+  )
 }
 
-export async function removeAutonomousJobScheduler(autonomousJobId: string): Promise<void> {
-  await autonomousJobQueue.getQueue().removeJobScheduler(buildAutonomousSchedulerId(autonomousJobId))
+export function removeAutonomousJobScheduler(autonomousJobId: string): Promise<void> {
+  return Effect.runPromise(
+    Effect.asVoid(
+      Effect.tryPromise(() =>
+        autonomousJobQueue.getQueue().removeJobScheduler(buildAutonomousSchedulerId(autonomousJobId)),
+      ),
+    ),
+  )
 }
 
-export async function removeAutonomousAtJob(autonomousJobId: string): Promise<void> {
-  try {
-    await autonomousJobQueue.getQueue().remove(buildAutonomousAtJobId(autonomousJobId))
-  } catch {
-    // The delayed job may have already fired or never existed.
-  }
+export function removeAutonomousAtJob(autonomousJobId: string): Promise<void> {
+  return Effect.runPromise(
+    Effect.catch(
+      Effect.asVoid(
+        Effect.tryPromise(() => autonomousJobQueue.getQueue().remove(buildAutonomousAtJobId(autonomousJobId))),
+      ),
+      () => Effect.void,
+    ),
+  )
 }
 
-type AutonomousJobWorkerOptions = Parameters<typeof autonomousJobQueue.startWorker>[0]
-
-export function startAutonomousJobWorker(options: AutonomousJobWorkerOptions = {}): WorkerHandle {
-  const handle = autonomousJobQueue.startWorker(options)
+interface AutonomousJobWorkerOptions {
+  registerSignals?: boolean
+  connectionProvider: () => IORedis
+  deps: AutonomousJobQueueDeps
+}
 
-  autonomousJobService.recoverActiveJobs().catch((error: unknown) => {
-    serverLogger.error`Autonomous job startup recovery failed: ${error}`
+export function startAutonomousJobWorker(options: AutonomousJobWorkerOptions): WorkerHandle {
+  _deps = options.deps
+  const handle = autonomousJobQueue.startWorker({
+    registerSignals: options.registerSignals,
+    connectionProvider: options.connectionProvider,
   })
 
+  void Effect.runPromise(
+    Effect.catch(options.deps.autonomousJobService.recoverActiveJobs(), (error) =>
+      Effect.sync(() => {
+        serverLogger.error`Autonomous job startup recovery failed: ${error}`
+      }),
+    ),
+  )
+
   return handle
 }
 
-if (import.meta.main) {
-  startAutonomousJobWorker()
-}
+runStandaloneQueueWorker((runtime) => {
+  const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))
+  startAutonomousJobWorker({
+    connectionProvider: () => resolve(RedisServiceTag).getConnectionForBullMQ(),
+    deps: { databaseService: resolve(DatabaseServiceTag), autonomousJobService: resolve(AutonomousJobServiceTag) },
+  })
+})

package/src/queues/context-compaction.queue.ts

@@ -1,11 +1,16 @@
 import type { Job } from 'bullmq'
+import { Effect } from 'effect'
+import type { Context } from 'effect'
+import type IORedis from 'ioredis'
 
 import { ensureRecordId } from '../db/record-id'
-import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
-import { contextCompactionService } from '../services/context-compaction.service'
-import { threadService } from '../services/thread.service'
+import { ConfigurationError } from '../effect/errors'
+import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import { ContextCompactionServiceTag } from '../services/context-compaction.service'
+import { ThreadServiceTag } from '../services/thread/thread.service'
 import { createQueueFactory } from './queue-factory'
+import { runStandaloneQueueWorker } from './standalone-worker'
 
 interface ContextCompactionJob {
   domain: 'thread'
@@ -13,17 +18,38 @@ interface ContextCompactionJob {
   contextSize?: number
 }
 
-async function processContextCompactionJob(job: Job<ContextCompactionJob>): Promise<void> {
-  await databaseService.connect()
+interface ContextCompactionQueueDeps {
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
+  threadService: Context.Service.Shape<typeof ThreadServiceTag>
+  contextCompactionService: Context.Service.Shape<typeof ContextCompactionServiceTag>
+}
+
+let _deps: ContextCompactionQueueDeps | null = null
+function getDeps(): ContextCompactionQueueDeps {
+  if (!_deps)
+    throw new ConfigurationError({
+      message: 'Context compaction queue is not configured. Initialize the runtime before starting the worker.',
+      key: 'queue-deps',
+    })
+  return _deps
+}
+
+function processContextCompactionJob(job: Job<ContextCompactionJob>): Promise<void> {
+  const { threadService, contextCompactionService } = getDeps()
 
   const { entityId, contextSize } = job.data
   const threadRef = ensureRecordId(entityId, TABLES.THREAD)
-  await threadService.setCompacting(threadRef, true)
-  try {
-    await contextCompactionService.compactThreadHistory({ threadId: threadRef, contextSize })
-  } finally {
-    await threadService.setCompacting(threadRef, false)
-  }
+  return Effect.runPromise(
+    Effect.ensuring(
+      Effect.asVoid(
+        Effect.gen(function* () {
+          yield* threadService.setCompacting(threadRef, true)
+          yield* contextCompactionService.compactThreadHistory({ threadId: threadRef, contextSize })
+        }),
+      ),
+      Effect.ignore(threadService.setCompacting(threadRef, false)),
+    ),
+  )
 }
 
 const contextCompaction = createQueueFactory<ContextCompactionJob>({
@@ -33,6 +59,7 @@ const contextCompaction = createQueueFactory<ContextCompactionJob>({
   concurrency: 2,
   lockDuration: 300_000,
   defaultJobOptions: { attempts: 2, backoff: { type: 'exponential', delay: 3_000 } },
+  prepare: () => getDeps().databaseService.connect(),
   processor: processContextCompactionJob,
 })
 
@@ -40,8 +67,26 @@ export function enqueueContextCompaction(job: ContextCompactionJob) {
   return contextCompaction.enqueue(job, { deduplication: { id: `compact:${job.domain}:${job.entityId}` } })
 }
 
-export const startContextCompactionWorker = contextCompaction.startWorker
-
-if (import.meta.main) {
-  startContextCompactionWorker()
+export function startContextCompactionWorker(options: {
+  registerSignals?: boolean
+  connectionProvider: () => IORedis
+  deps: ContextCompactionQueueDeps
+}): ReturnType<typeof contextCompaction.startWorker> {
+  _deps = options.deps
+  return contextCompaction.startWorker({
+    registerSignals: options.registerSignals,
+    connectionProvider: options.connectionProvider,
+  })
 }
+
+runStandaloneQueueWorker((runtime) => {
+  const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))
+  startContextCompactionWorker({
+    connectionProvider: () => resolve(RedisServiceTag).getConnectionForBullMQ(),
+    deps: {
+      databaseService: resolve(DatabaseServiceTag),
+      threadService: resolve(ThreadServiceTag),
+      contextCompactionService: resolve(ContextCompactionServiceTag),
+    },
+  })
+})

package/src/queues/delayed-node-promotion.queue.ts

@@ -1,8 +1,13 @@
 import type { Job } from 'bullmq'
+import { Effect } from 'effect'
+import type { Context } from 'effect'
+import type IORedis from 'ioredis'
 
-import { databaseService } from '../db/service'
-import { planExecutorService } from '../services/plan-executor.service'
+import { ConfigurationError } from '../effect/errors'
+import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import { PlanExecutorServiceTag } from '../services/plan/plan-executor.service'
 import { createQueueFactory } from './queue-factory'
+import { runStandaloneQueueWorker } from './standalone-worker'
 
 export interface DelayedNodePromotionJob {
   runId: string
@@ -12,13 +17,30 @@ export interface DelayedNodePromotionJob {
 
 export const DELAYED_NODE_PROMOTION_QUEUE = 'delayed-node-promotion'
 
-async function processDelayedNodePromotionJob(job: Job<DelayedNodePromotionJob>): Promise<void> {
-  await databaseService.connect()
-  await planExecutorService.promoteDelayedNode({
-    runId: job.data.runId,
-    nodeId: job.data.nodeId,
-    emittedBy: job.data.emittedBy,
-  })
+interface DelayedNodePromotionQueueDeps {
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
+  planExecutorService: Context.Service.Shape<typeof PlanExecutorServiceTag>
+}
+
+let _deps: DelayedNodePromotionQueueDeps | null = null
+function getDeps(): DelayedNodePromotionQueueDeps {
+  if (!_deps)
+    throw new ConfigurationError({
+      message: 'Delayed node promotion queue is not configured. Initialize the runtime before starting the worker.',
+      key: 'queue-deps',
+    })
+  return _deps
+}
+
+function processDelayedNodePromotionJob(job: Job<DelayedNodePromotionJob>): Promise<void> {
+  const { planExecutorService } = getDeps()
+  return Promise.resolve(
+    planExecutorService.promoteDelayedNode({
+      runId: job.data.runId,
+      nodeId: job.data.nodeId,
+      emittedBy: job.data.emittedBy,
+    }),
+  ).then(() => undefined)
 }
 
 const delayedNodePromotion = createQueueFactory<DelayedNodePromotionJob>({
@@ -27,15 +49,30 @@ const delayedNodePromotion = createQueueFactory<DelayedNodePromotionJob>({
   jobName: 'promote-node',
   concurrency: 1,
   defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 5000 } },
+  prepare: () => getDeps().databaseService.connect(),
   processor: processDelayedNodePromotionJob,
 })
 
-export async function enqueueDelayedNodePromotion(job: DelayedNodePromotionJob, delayMs: number) {
-  await delayedNodePromotion.enqueue(job, { delay: delayMs, jobId: `promote:${job.runId}:${job.nodeId}` })
+export function enqueueDelayedNodePromotion(job: DelayedNodePromotionJob, delayMs: number) {
+  return delayedNodePromotion.enqueue(job, { delay: delayMs, jobId: `promote:${job.runId}:${job.nodeId}` })
 }
 
-export const startDelayedNodePromotionWorker = delayedNodePromotion.startWorker
-
-if (import.meta.main) {
-  startDelayedNodePromotionWorker()
+export function startDelayedNodePromotionWorker(options: {
+  registerSignals?: boolean
+  connectionProvider: () => IORedis
+  deps: DelayedNodePromotionQueueDeps
+}): ReturnType<typeof delayedNodePromotion.startWorker> {
+  _deps = options.deps
+  return delayedNodePromotion.startWorker({
+    registerSignals: options.registerSignals,
+    connectionProvider: options.connectionProvider,
+  })
 }
+
+runStandaloneQueueWorker((runtime) => {
+  const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))
+  startDelayedNodePromotionWorker({
+    connectionProvider: () => resolve(RedisServiceTag).getConnectionForBullMQ(),
+    deps: { databaseService: resolve(DatabaseServiceTag), planExecutorService: resolve(PlanExecutorServiceTag) },
+  })
+})