Runtime API

The runtime entrypoint lives in @lota-sdk/core.

createLotaRuntime()

import { createLotaRuntime } from '@lota-sdk/core'
import type { LotaRuntime, LotaRuntimeConfig } from '@lota-sdk/core'

createLotaRuntime(config) creates an isolated runtime instance with:

• SurrealDB and Redis wiring
• agent roster and workstream bootstrap configuration
• runtime-backed service and Redis accessors for host code
• built-in schema file discovery plus plugin and host contributions
• built-in workers plus consumer-provided extra workers
• runtime adapters, tool providers, plugins, and turn hooks

LotaRuntime

interface LotaRuntime {
  services: { ...runtime-owned services... }
  redis: {
    manager: RedisConnectionManager
    getConnection(): IORedis
    getConnectionForBullMQ(): IORedis
    closeConnection(): Promise<void>
  }
  workers: Record<string, unknown>
  schemaFiles: Array<string | URL>
  contributions: { envKeys: readonly string[]; schemaFiles: Array<string | URL> }
  config: LotaRuntimeConfig
  plugins: Record<string, LotaPlugin>
  connectPluginDatabases(): Promise<void>
  connect(): Promise<void>
  disconnect(): Promise<void>
}

Public Runtime Boundary

const runtime = await createLotaRuntime(config)

await runtime.connect()
await runtime.connectPluginDatabases()

const { workstreamService, memoryService } = runtime.services
const queueConnection = runtime.redis.getConnectionForBullMQ()
const shutdown = runtime.workers.startContextCompactionWorker?.()

Preferred host usage:

• use runtime.services.* for SDK-owned services
• use runtime.redis.* for Redis and BullMQ access
• use runtime.workers.* for built-in worker startup
• use runtime.plugins and runtime.contributions for plugin-owned metadata

The lower-level @lota-sdk/core/redis accessors and direct service imports remain runtime internals and shared implementation plumbing, not the consumer-facing integration surface.

Startup helpers

import {
  connectWithStartupRetry,
  publishDatabaseBootstrap,
  waitForDatabaseBootstrap,
} from '@lota-sdk/core/db/startup'

These helpers live in core/src/db/startup.ts and support retry, readiness waiting, and bootstrap publication for schema setup.