Types

This page documents the key TypeScript types exported by the Lota SDK.

Runtime Types

LotaRuntimeConfig

The configuration object passed to createLotaRuntime(). See Configuration for field-level documentation.

interface LotaRuntimeConfig {
  database: { url: string; namespace: string; username: string; password: string }
  redis: { url: string }
  aiGateway: { url: string; key: string; admin?: string; pass?: string; embeddingModel?: string }
  s3: {
    endpoint: string; bucket: string; region?: string
    accessKeyId: string; secretAccessKey: string; attachmentUrlExpiresIn?: number
  }
  firecrawl: { apiKey: string; apiBaseUrl?: string }
  logging?: { level?: 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'fatal' }
  memory?: { searchK?: number }
  workstreams?: LotaWorkstreamConfig
  agents: {
    roster: readonly string[]
    displayNames: Record<string, string>
    shortDisplayNames?: Record<string, string>
    teamConsultParticipants: readonly string[]
    getCoreWorkstreamProfile?: (coreType: string) => CoreWorkstreamProfile
    createAgent?: Record<string, (...args: unknown[]) => unknown>
    buildAgentTools?: (...args: unknown[]) => unknown
    getAgentRuntimeConfig?: (...args: unknown[]) => unknown
  }
  toolProviders?: Record<string, unknown>
  extraSchemaFiles?: Array<string | URL>
  extraWorkers?: Record<string, unknown>
  pluginRuntime?: Record<string, LotaPlugin>
  runtimeAdapters?: LotaRuntimeAdapters
  turnHooks?: {
    buildContext?: (params: unknown) => Promise<Record<string, unknown> | void>
    afterTurn?: (params: unknown) => Promise<void>
    resolveAgent?: (params: unknown) => Promise<Record<string, unknown> | void>
    buildExtraInstructionSections?: (params: unknown) => Promise<string[] | void>
  }
}

LotaRuntime

The runtime instance returned by createLotaRuntime().

interface LotaRuntime {
  services: {
    database: SurrealDBService
    databaseService: SurrealDBService
    redis: RedisConnectionManager
    closeRedisConnection(): Promise<void>
    attachmentService: typeof attachmentService
    generatedDocumentStorageService: typeof generatedDocumentStorageService
    memoryService: typeof memoryService
    verifyMutatingApproval: typeof verifyMutatingApproval
    recentActivityService: typeof recentActivityService
    recentActivityTitleService: typeof recentActivityTitleService
    executionPlanService: typeof executionPlanService
    workstreamMessageService: typeof workstreamMessageService
    workstreamService: typeof workstreamService
    workstreamTitleService: typeof workstreamTitleService
    createWorkstreamApprovalContinuationStream: typeof createWorkstreamApprovalContinuationStream
    createWorkstreamTurnStream: typeof createWorkstreamTurnStream
    isApprovalContinuationRequest: typeof isApprovalContinuationRequest
    runWorkstreamTurnInBackground: typeof runWorkstreamTurnInBackground
  }
  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>
}

LotaRuntimeAdapters

Host-owned bridges for product-specific behavior that the generic SDK runtime can call into.

interface LotaRuntimeAdapters {
  services?: { workspaceProvider?: LotaRuntimeWorkspaceProvider }
  workstream?: {
    buildIndexedRepositoriesContext?: (workspaceId: string) => Promise<LotaRuntimeIndexedRepositoriesContext>
    buildTeamThinkAgentTools?: (params: LotaRuntimeTeamThinkToolsParams) => Promise<{ tools: ToolSet }>
  }
  queues?: {
    enqueuePostChatOrgAction?: (job: Record<string, unknown>) => Promise<void> | void
    enqueueOnboardingRepoIndexFollowUp?: (job: Record<string, unknown>) => Promise<void> | void
  }
  workers?: {
    connectPluginDatabases?: () => Promise<void>
    withWorkspaceMemoryLock?: <T>(workspaceId: string, fn: () => Promise<T>) => Promise<T>
  }
}

LotaRuntimeTurnHooks

Optional lifecycle hooks supplied through LotaRuntimeConfig.turnHooks.

interface LotaRuntimeTurnHooks {
  buildContext?: (params: Record<string, unknown>) => Promise<Record<string, unknown> | void>
  afterTurn?: (params: Record<string, unknown>) => Promise<void>
  resolveAgent?: (params: Record<string, unknown>) => Promise<Record<string, unknown> | void>
  buildExtraInstructionSections?: (params: Record<string, unknown>) => Promise<string[] | void>
}

Plugin Types

LotaPlugin

A plugin that contributes services, tools, and infrastructure to the runtime.

interface LotaPlugin<TServices = unknown, TTools = unknown> {
  services: TServices
  tools?: TTools
  contributions: LotaPluginContributions
}

LotaPluginContributions

Declares what a plugin contributes to the runtime.

interface LotaPluginContributions {
  envKeys: readonly string[]            // Environment variable names this plugin requires
  schemaFiles: readonly (string | URL)[] // SurrealDB schema files to apply
}

Agent Types

CoreWorkstreamProfile

Configuration for a core workstream type, returned by getCoreWorkstreamProfile().

interface CoreWorkstreamProfile {
  config: {
    coreType: string   // e.g., 'daily-activities'
    agentId: string    // Lead agent for this core workstream
    title: string      // Display title
  }
  tools: readonly string[]    // Tool names available in this workstream
  skills: readonly string[]   // Skill names active in this workstream
  instructions: string        // Additional instructions for the lead agent
}

ChatMode

The mode in which an agent operates.

type ChatMode = 'direct' | 'workstreamMode' | 'fixedWorkstreamMode'

CreateRoutedAgentOptions

Options for creating a routed agent instance.

interface CreateRoutedAgentOptions<TTools extends ToolSet = ToolSet> {
  mode: ChatMode
  tools: TTools
  extraInstructions?: string
  stopWhen?: StopCondition<TTools> | Array<StopCondition<TTools>>
  prepareStep?: PrepareStepFunction<TTools>
  maxRetries?: number
  modelOverride?: { model: unknown; providerOptions?: Record<string, unknown> }
  onFinish?: ToolLoopAgentOnFinishCallback<TTools>
}

Definition Types

SkillDefinition

Defines an agent skill with tool bindings.

interface SkillDefinition<TToolName extends string = string> {
  name: string
  description: string
  instructions: string
  tools: readonly TToolName[]
}

RuleDefinition

Defines a behavioral rule for agents.

interface RuleDefinition {
  name: string
  instructions: string
}

PromptDefinition

Defines a reusable prompt template.

interface PromptDefinition {
  name: string
  instructions: string
}

ToolDefinition

Defines a tool that can be created with runtime context.

interface ToolDefinition<TContext> {
  name: string
  create: (context: TContext) => ToolSet[string]
}

LearnedSkillEntry

A skill learned from conversation history.

interface LearnedSkillEntry {
  name: string
  instructions: string
}

Memory Types

MemoryBlockEntry

A single entry in a workstream's memory block.

interface MemoryBlockEntry {
  role: string       // Agent or system label
  content: string    // The note content
  timestamp: string  // ISO timestamp
}

MemoryBlockRuntime

Runtime operations for memory block management.

interface MemoryBlockRuntime {
  normalizeMemoryBlockEntry: (entry: string) => string
  validateMemoryBlockEntry: (entry: string) => { ok: boolean; reason?: string }
  hasMemoryBlockEntry: (raw: string | null | undefined, role: string, entry: string) => boolean
  parseMemoryBlock: (raw: string | null | undefined) => MemoryBlockEntry[]
  serializeMemoryBlock: (entries: MemoryBlockEntry[]) => string
  formatMemoryBlockForPrompt: (entries: MemoryBlockEntry[]) => string
  appendToMemoryBlock: (entries: MemoryBlockEntry[], role: string, content: string) => MemoryBlockEntry[]
}

Context Compaction Types

ContextCompactionRuntime

The compaction runtime interface.

interface ContextCompactionRuntime {
  createSummaryMessage: (summaryText: string) => ChatMessage | null
  prependSummaryMessage: (summaryText: string, liveMessages: ChatMessage[]) => ChatMessage[]
  formatWorkstreamStateForPrompt: (state: WorkstreamState | null | undefined) => string | undefined
  estimateThreshold: (contextSize?: number) => number
  shouldCompactHistory: (params: {
    summaryText: string
    liveMessages: ChatMessage[]
    contextSize?: number
  }) => CompactionAssessment
  compactHistory: (params: CompactHistoryParams) => Promise<CompactHistoryResult>
}

CompactionAssessment

Result of checking whether compaction is needed.

interface CompactionAssessment {
  estimatedTokens: number
  threshold: number
  shouldCompact: boolean
}

Service Types

SurrealDBService

The SurrealDB database service. Provides connect(), disconnect(), query(), CRUD operations, and transaction support.

RedisConnectionManager

The Redis connection manager.

interface RedisConnectionManager {
  getConnection(): IORedis
  getConnectionForBullMQ(): IORedis
  isConnectionHealthy(): boolean
  closeConnection(): Promise<void>
}

Worker Types

WorkerHandle

Returned by worker start functions.

interface WorkerHandle {
  worker: Worker        // BullMQ Worker instance
  shutdown: () => Promise<void>  // Graceful shutdown function
}