@lota-sdk/core 0.4.8 → 0.4.10

package/src/effect/layers.ts

@@ -0,0 +1,238 @@
+import type { ToolSet } from 'ai'
+import { Effect, Layer, Logger, References } from 'effect'
+import { DevTools } from 'effect/unstable/devtools'
+import { FetchHttpClient } from 'effect/unstable/http'
+import { Otlp } from 'effect/unstable/observability'
+
+import type { CoreThreadProfile } from '../config/agent-defaults'
+import { resolveAgentConfig, resolveAgentFactoryConfig } from '../config/agent-defaults'
+import type { AgentFactory, AgentRuntimeConfigProvider, AgentToolBuilder } from '../config/agent-types'
+import { configureLotaLogger, getLotaLoggers, toEffectLogLevel } from '../config/logger'
+import type { LotaLogLevel } from '../config/logger'
+import { resolveThreadConfig } from '../config/thread-defaults'
+import type { LotaThreadConfig } from '../config/thread-defaults'
+import { LOTA_SDK_DATABASE_NAME } from '../db/sdk-database'
+import type { SurrealDatabaseConfig } from '../db/service'
+import { SurrealDBService } from '../db/service'
+import type { CreateRedisConnectionManagerOptions } from '../redis/connection'
+import { makeRedisConnectionManager } from '../redis/connection'
+import type { ResolvedLotaRuntimeConfig } from '../runtime/runtime-config'
+import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from '../runtime/runtime-extensions'
+import type { LotaRuntimeWorkerExtensions } from '../runtime/runtime-worker-registry'
+import { QueueJobServiceLive } from '../services/queue-job.service'
+import { getErrorMessage } from '../utils/errors'
+import { DatabaseError } from './errors'
+import {
+  AppLoggerTag,
+  AgentConfigServiceTag,
+  AgentFactoryServiceTag,
+  DatabaseServiceTag,
+  RedisServiceTag,
+  RuntimeAdaptersServiceTag,
+  RuntimeConfigServiceTag,
+  RuntimeWorkerExtensionsServiceTag,
+  ThreadConfigServiceTag,
+  ToolProvidersServiceTag,
+  TurnHooksServiceTag,
+} from './services'
+
+const EMPTY_TOOLS = {} as ToolSet
+const EMPTY_WORKERS: LotaRuntimeWorkerExtensions = {}
+
+export function DatabaseLive(config: SurrealDatabaseConfig) {
+  return Layer.effect(
+    DatabaseServiceTag,
+    Effect.acquireRelease(
+      Effect.try({
+        try: () => new SurrealDBService(config),
+        catch: (error) =>
+          new DatabaseError({ message: `Failed to create database service: ${getErrorMessage(error)}`, cause: error }),
+      }),
+      (databaseService) =>
+        Effect.ignore(
+          databaseService
+            .disconnect()
+            .pipe(
+              Effect.tapError((error) =>
+                Effect.logWarning(`Failed to clean up database service: ${getErrorMessage(error)}`),
+              ),
+            ),
+        ),
+    ),
+  )
+}
+
+export function RedisLive(config: CreateRedisConnectionManagerOptions) {
+  return Layer.effect(RedisServiceTag, makeRedisConnectionManager(config))
+}
+
+export function AppLoggerLive(level: LotaLogLevel = 'info') {
+  // Sequence `configureLotaLogger(level)` before `getLotaLoggers()` inside a
+  // single Effect.sync so the log-level mutation is observed when the loggers
+  // are assembled. `Layer.mergeAll` builds in parallel, so splitting these
+  // across two sub-layers is an ordering hazard.
+  const AppLoggersLayer = Layer.effect(
+    AppLoggerTag,
+    Effect.sync(() => {
+      configureLotaLogger(level)
+      return getLotaLoggers()
+    }),
+  )
+  return Layer.mergeAll(
+    AppLoggersLayer,
+    Logger.layer([Logger.consolePretty()]),
+    Layer.succeed(References.MinimumLogLevel, toEffectLogLevel(level)),
+  )
+}
+
+export function RuntimeConfigLive(config: ResolvedLotaRuntimeConfig) {
+  return Layer.succeed(RuntimeConfigServiceTag, config)
+}
+
+export function AgentConfigLive(config: {
+  roster: readonly string[]
+  leadAgentId: string
+  displayNames: Record<string, string>
+  shortDisplayNames?: Record<string, string>
+  descriptions?: Record<string, string>
+  routerModelId?: string
+  teamConsultParticipants: readonly string[]
+  getCoreThreadProfile?: (coreType: string) => CoreThreadProfile
+}) {
+  return Layer.succeed(AgentConfigServiceTag, resolveAgentConfig(config))
+}
+
+export function AgentFactoryLive(config: {
+  createAgent?: AgentFactory
+  buildAgentTools?: AgentToolBuilder
+  getAgentRuntimeConfig?: AgentRuntimeConfigProvider
+  pluginRuntime?: Record<string, unknown>
+}) {
+  return Layer.succeed(AgentFactoryServiceTag, resolveAgentFactoryConfig(config))
+}
+
+export function ThreadConfigLive(params: { agentRoster: readonly string[]; config?: LotaThreadConfig }) {
+  return Layer.succeed(ThreadConfigServiceTag, resolveThreadConfig(params))
+}
+
+export function RuntimeExtensionsLive(params: {
+  adapters?: LotaRuntimeAdapters
+  turnHooks?: LotaRuntimeTurnHooks
+  toolProviders?: ToolSet
+  extraWorkers?: LotaRuntimeWorkerExtensions
+}) {
+  return Layer.mergeAll(
+    Layer.succeed(RuntimeAdaptersServiceTag, params.adapters ?? {}),
+    Layer.succeed(TurnHooksServiceTag, params.turnHooks ?? {}),
+    Layer.succeed(ToolProvidersServiceTag, params.toolProviders ?? EMPTY_TOOLS),
+    Layer.succeed(RuntimeWorkerExtensionsServiceTag, params.extraWorkers ?? EMPTY_WORKERS),
+  )
+}
+
+// ── Shared Infrastructure Layer Builders ─────────────────────────────
+
+/**
+ * Common config-to-Layer conversions shared by the runtime and sandboxed
+ * worker infrastructure builders. Covers logging, runtime config, agents,
+ * threads, database, and redis. Agent display names are overridable for
+ * the socialChat agent injection flow.
+ */
+function buildBaseConfigLayers(
+  runtimeConfig: ResolvedLotaRuntimeConfig,
+  options: {
+    resolvedAgentDisplayNames?: Record<string, string>
+    runtimeExtensions: Parameters<typeof RuntimeExtensionsLive>[0]
+  },
+) {
+  return Layer.mergeAll(
+    AppLoggerLive(runtimeConfig.logging.level),
+    RuntimeConfigLive(runtimeConfig),
+    AgentConfigLive({
+      roster: runtimeConfig.agents.roster,
+      leadAgentId: runtimeConfig.agents.leadAgentId,
+      displayNames: options.resolvedAgentDisplayNames ?? runtimeConfig.agents.displayNames,
+      shortDisplayNames: runtimeConfig.agents.shortDisplayNames,
+      descriptions: runtimeConfig.agents.descriptions,
+      routerModelId: runtimeConfig.agents.routerModelId,
+      teamConsultParticipants: runtimeConfig.agents.teamConsultParticipants,
+      getCoreThreadProfile: runtimeConfig.agents.getCoreThreadProfile,
+    }),
+    AgentFactoryLive({
+      createAgent: runtimeConfig.agents.createAgent,
+      buildAgentTools: runtimeConfig.agents.buildAgentTools,
+      getAgentRuntimeConfig: runtimeConfig.agents.getAgentRuntimeConfig,
+      pluginRuntime: runtimeConfig.pluginRuntime,
+    }),
+    ThreadConfigLive({ agentRoster: runtimeConfig.agents.roster, config: runtimeConfig.threads }),
+    RuntimeExtensionsLive(options.runtimeExtensions),
+    DatabaseLive({
+      url: runtimeConfig.database.url,
+      namespace: runtimeConfig.database.namespace,
+      database: LOTA_SDK_DATABASE_NAME,
+      username: runtimeConfig.database.username,
+      password: runtimeConfig.database.password,
+    }),
+    RedisLive({ url: runtimeConfig.redis.url }),
+  )
+}
+
+/**
+ * Builds the observability layer (OTLP + DevTools) from a runtime config.
+ * Returns an empty layer when no observability endpoints are configured.
+ */
+function buildObservabilityLayer(runtimeConfig: ResolvedLotaRuntimeConfig): Layer.Layer<never> {
+  let layer: Layer.Layer<never> = Layer.empty
+  const observability = runtimeConfig.observability
+
+  if (observability.otlpBaseUrl) {
+    layer = Layer.merge(
+      layer,
+      Otlp.layerJson({
+        baseUrl: observability.otlpBaseUrl,
+        resource: {
+          serviceName: observability.serviceName,
+          ...(observability.serviceVersion ? { serviceVersion: observability.serviceVersion } : {}),
+        },
+        ...(observability.otlpHeaders ? { headers: observability.otlpHeaders } : {}),
+      }).pipe(Layer.provide(FetchHttpClient.layer)),
+    )
+  }
+
+  if (observability.devToolsUrl && Bun.env.NODE_ENV !== 'production') {
+    layer = Layer.merge(layer, DevTools.layer(observability.devToolsUrl))
+  }
+
+  return layer
+}
+
+/**
+ * Builds the full infrastructure layer used by `createLotaRuntime`. Combines
+ * all config, database, redis, agent, thread, and extension layers with the
+ * observability layer computed from the runtime config.
+ */
+export function buildInfrastructureLayer(
+  runtimeConfig: ResolvedLotaRuntimeConfig,
+  options: { resolvedAgentDisplayNames: Record<string, string> },
+) {
+  return Layer.mergeAll(
+    buildBaseConfigLayers(runtimeConfig, {
+      resolvedAgentDisplayNames: options.resolvedAgentDisplayNames,
+      runtimeExtensions: {
+        adapters: runtimeConfig.runtimeAdapters,
+        turnHooks: runtimeConfig.turnHooks,
+        toolProviders: runtimeConfig.toolProviders ?? {},
+        extraWorkers: runtimeConfig.extraWorkers,
+      },
+    }),
+    buildObservabilityLayer(runtimeConfig),
+  )
+}
+
+/**
+ * Builds the minimal infrastructure layer used by sandboxed workers.
+ * Omits observability and uses empty runtime extensions.
+ */
+export function buildWorkerInfrastructureLayer(runtimeConfig: ResolvedLotaRuntimeConfig) {
+  const infrastructureLayer = buildBaseConfigLayers(runtimeConfig, { runtimeExtensions: {} })
+  return QueueJobServiceLive.pipe(Layer.provideMerge(infrastructureLayer))
+}

package/src/effect/runtime-ref.ts

@@ -0,0 +1,25 @@
+import type { ManagedRuntime } from 'effect'
+
+// eslint-disable-next-line typescript-eslint/no-explicit-any -- ManagedRuntime is contravariant in R; `any` is the only valid wildcard
+type SdkManagedRuntime = ManagedRuntime.ManagedRuntime<any, any>
+
+let currentRuntime: SdkManagedRuntime | null = null
+
+export function setCurrentRuntime<R, E>(runtime: ManagedRuntime.ManagedRuntime<R, E>): void {
+  currentRuntime = runtime as SdkManagedRuntime
+}
+
+export function clearCurrentRuntime(): void {
+  currentRuntime = null
+}
+
+export function getCurrentRuntime(): SdkManagedRuntime {
+  if (!currentRuntime) {
+    throw new Error('Lota Effect runtime is not configured. Call createLotaRuntime() first.')
+  }
+  return currentRuntime
+}
+
+export function getOptionalCurrentRuntime(): SdkManagedRuntime | null {
+  return currentRuntime
+}

package/src/effect/runtime.ts

@@ -0,0 +1,46 @@
+import { Effect } from 'effect'
+import type { Context, ManagedRuntime } from 'effect'
+
+import { clearCurrentRuntime, getCurrentRuntime, getOptionalCurrentRuntime, setCurrentRuntime } from './runtime-ref'
+
+export function setLotaSdkRuntime<R, E>(runtime: ManagedRuntime.ManagedRuntime<R, E>): void {
+  setCurrentRuntime(runtime)
+}
+
+export function clearLotaSdkRuntime(): void {
+  clearCurrentRuntime()
+}
+
+export function getOptionalLotaSdkRuntime() {
+  return getOptionalCurrentRuntime()
+}
+
+/** Returns the current managed runtime or throws. */
+export function getLotaSdkRuntime() {
+  return getCurrentRuntime()
+}
+
+export function resolveLotaService<I, T>(tag: Context.Key<I, T>): T {
+  return getCurrentRuntime().runSync(Effect.service(tag))
+}
+
+export function resolveOptionalLotaService<I, T>(tag: Context.Key<I, T>): T | null {
+  const runtime = getOptionalCurrentRuntime()
+  return runtime ? runtime.runSync(Effect.service(tag)) : null
+}
+
+export function runPromiseWithOptionalLotaRuntime<A, E>(effect: Effect.Effect<A, E, never>): Promise<A> {
+  const runtime = getOptionalCurrentRuntime()
+  return runtime ? runtime.runPromise(effect) : Effect.runPromise(effect)
+}
+
+/**
+ * Run an effect as a Promise using the current managed runtime's context.
+ * The runtime must be initialized via `createLotaRuntime()` before any call.
+ */
+export function runPromise<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  options?: { readonly signal?: AbortSignal },
+): Promise<A> {
+  return getCurrentRuntime().runPromise(effect, options)
+}

package/src/effect/services.ts

@@ -0,0 +1,61 @@
+import type { ToolSet } from 'ai'
+import { Context } from 'effect'
+
+import type { ResolvedAgentConfig } from '../config/agent-defaults'
+import type { AgentFactory, AgentRuntimeConfigProvider, AgentToolBuilder } from '../config/agent-types'
+import type { LotaLoggerSet } from '../config/logger'
+import type { ResolvedThreadBootstrapConfig } from '../config/thread-defaults'
+import type { SurrealDBService } from '../db/service'
+import type { RedisConnectionManager } from '../redis/connection'
+import type { ResolvedLotaRuntimeConfig } from '../runtime/runtime-config'
+import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from '../runtime/runtime-extensions'
+import type { LotaRuntimeWorkerExtensions } from '../runtime/runtime-worker-registry'
+
+export class DatabaseServiceTag extends Context.Service<DatabaseServiceTag, SurrealDBService>()(
+  '@lota-sdk/core/DatabaseService',
+) {}
+
+export class RedisServiceTag extends Context.Service<RedisServiceTag, RedisConnectionManager>()(
+  '@lota-sdk/core/RedisService',
+) {}
+
+export class AppLoggerTag extends Context.Service<AppLoggerTag, LotaLoggerSet>()('@lota-sdk/core/AppLogger') {}
+
+export class RuntimeConfigServiceTag extends Context.Service<RuntimeConfigServiceTag, ResolvedLotaRuntimeConfig>()(
+  '@lota-sdk/core/RuntimeConfigService',
+) {}
+
+export class AgentConfigServiceTag extends Context.Service<AgentConfigServiceTag, ResolvedAgentConfig>()(
+  '@lota-sdk/core/AgentConfigService',
+) {}
+
+export class AgentFactoryServiceTag extends Context.Service<
+  AgentFactoryServiceTag,
+  {
+    readonly createAgent: AgentFactory
+    readonly buildAgentTools: AgentToolBuilder
+    readonly getAgentRuntimeConfig: AgentRuntimeConfigProvider
+    readonly pluginRuntime?: Record<string, unknown>
+  }
+>()('@lota-sdk/core/AgentFactoryService') {}
+
+export class ThreadConfigServiceTag extends Context.Service<ThreadConfigServiceTag, ResolvedThreadBootstrapConfig>()(
+  '@lota-sdk/core/ThreadConfigService',
+) {}
+
+export class RuntimeAdaptersServiceTag extends Context.Service<RuntimeAdaptersServiceTag, LotaRuntimeAdapters>()(
+  '@lota-sdk/core/RuntimeAdaptersService',
+) {}
+
+export class TurnHooksServiceTag extends Context.Service<TurnHooksServiceTag, LotaRuntimeTurnHooks>()(
+  '@lota-sdk/core/TurnHooksService',
+) {}
+
+export class ToolProvidersServiceTag extends Context.Service<ToolProvidersServiceTag, ToolSet>()(
+  '@lota-sdk/core/ToolProvidersService',
+) {}
+
+export class RuntimeWorkerExtensionsServiceTag extends Context.Service<
+  RuntimeWorkerExtensionsServiceTag,
+  LotaRuntimeWorkerExtensions
+>()('@lota-sdk/core/RuntimeWorkerExtensionsService') {}

package/src/effect/zod.ts

@@ -0,0 +1,43 @@
+import { Effect } from 'effect'
+import { ZodError } from 'zod'
+import type { z } from 'zod'
+
+import { ValidationError } from './errors'
+import type { ValidationIssue } from './errors'
+
+type ZodIssueLike = { readonly path: ReadonlyArray<PropertyKey>; readonly message: string }
+
+function toValidationIssuePath(path: ReadonlyArray<PropertyKey>): string {
+  return path.map((segment) => String(segment)).join('.') || 'root'
+}
+
+function getZodIssues(error: Pick<ZodError, 'issues'> | ReadonlyArray<ZodIssueLike>): ReadonlyArray<ZodIssueLike> {
+  return 'issues' in error ? error.issues : error
+}
+
+export function toValidationIssues(
+  error: Pick<ZodError, 'issues'> | ReadonlyArray<ZodIssueLike>,
+): ReadonlyArray<ValidationIssue> {
+  return getZodIssues(error).map((issue) => ({ path: toValidationIssuePath(issue.path), message: issue.message }))
+}
+
+export function summarizeZodIssues(issues: ReadonlyArray<ZodIssueLike>, maxIssues = 5): string {
+  return issues
+    .slice(0, maxIssues)
+    .map((issue) => `${toValidationIssuePath(issue.path)}: ${issue.message}`)
+    .join('; ')
+}
+
+export function toValidationError(error: unknown, message?: string): ValidationError {
+  return new ValidationError({
+    message: message ?? (error instanceof ZodError ? 'Schema validation failed' : 'Validation failed'),
+    issues: error instanceof ZodError ? toValidationIssues(error) : undefined,
+  })
+}
+
+export function zodParse<TSchema extends z.ZodTypeAny>(
+  schema: TSchema,
+  value: unknown,
+): Effect.Effect<z.infer<TSchema>, ValidationError> {
+  return Effect.try({ try: () => schema.parse(value), catch: toValidationError })
+}