@lota-sdk/core 0.1.9 → 0.1.12

package/src/runtime/agent-runtime-policy.ts

@@ -1,3 +1,5 @@
+import { getLeadAgentId } from '../config/agent-defaults'
+import { resolveOnboardingOwnerAgentId } from '../config/workstream-defaults'
 import type { ChatMode } from './agent-types'
 import { resolveReasoningProfile } from './workstream-routing-policy'
 import type { ReasoningProfileName } from './workstream-routing-policy'
@@ -48,6 +50,7 @@ export function resolveActiveAgentSkills<TAgent extends string, TSkill extends P
   getAgentSkills: (agentId: TAgent, mode: ChatMode) => TSkill[]
 }): TSkill[] {
   const mode = params.mode ?? toChatMode(params.workstreamMode)
+  const onboardingOwnerAgentId = resolveOnboardingOwnerAgentId(getLeadAgentId()) as TAgent
   const baseSkills = params
     .getAgentSkills(params.agentId, mode)
     .filter((skill) => (params.linearInstalled ? true : skill !== ('linear' as TSkill)))
@@ -56,7 +59,7 @@ export function resolveActiveAgentSkills<TAgent extends string, TSkill extends P
     return baseSkills
   }
 
-  if (params.agentId !== ('chief' as TAgent)) {
+  if (params.agentId !== onboardingOwnerAgentId) {
     return []
   }
 
@@ -130,6 +133,7 @@ export function buildWorkstreamAgentToolPolicy<TAgent extends string, TSkill ext
   getAgentSkills: (agentId: TAgent, mode: ChatMode) => TSkill[]
 }): AgentToolPolicy<TSkill> {
   const resolvedMode = params.mode ?? toChatMode(params.workstreamMode)
+  const onboardingOwnerAgentId = resolveOnboardingOwnerAgentId(getLeadAgentId()) as TAgent
   const skills = resolveActiveAgentSkills({
     agentId: params.agentId,
     workstreamMode: params.workstreamMode,
@@ -148,10 +152,10 @@ export function buildWorkstreamAgentToolPolicy<TAgent extends string, TSkill ext
     includeOrgActionSearch: !params.onboardingActive,
     includeMemoryBlockAppend: true,
     includeReadFileParts: true,
-    includeInspectWebsite: params.onboardingActive && params.agentId === ('chief' as TAgent),
-    includeProceedInOnboarding: params.onboardingActive && params.agentId === ('chief' as TAgent),
-    includeGithubIntegration: params.onboardingActive && params.agentId === ('chief' as TAgent),
-    includeIndexRepositoryByURL: params.onboardingActive && params.agentId === ('chief' as TAgent),
+    includeInspectWebsite: params.onboardingActive && params.agentId === onboardingOwnerAgentId,
+    includeProceedInOnboarding: params.onboardingActive && params.agentId === onboardingOwnerAgentId,
+    includeGithubIntegration: params.onboardingActive && params.agentId === onboardingOwnerAgentId,
+    includeIndexRepositoryByURL: params.onboardingActive && params.agentId === onboardingOwnerAgentId,
     includeIndexedRepository: params.githubInstalled && params.provideRepoTool,
   }
 }

package/src/runtime/agent-stream-helpers.ts

@@ -1,7 +1,7 @@
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared'
 import type { LanguageModelUsage, UIMessageStreamOptions } from 'ai'
 
-import { agentDisplayNames } from '../config/agent-defaults'
+import { agentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defaults'
 
 export function readFiniteNumber(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined
@@ -108,10 +108,13 @@ export function createTimedAbortSignal(parentSignal: AbortSignal, timeoutMs: num
 
 export function buildSpecialistTaskMessage(params: { agentId: string; task: string }): ChatMessage {
   const displayName = agentDisplayNames[params.agentId] ?? params.agentId
+  const leadAgentDisplayName = getLeadAgentDisplayName()
   return {
     id: Bun.randomUUIDv7(),
     role: 'user',
-    parts: [{ type: 'text', text: [`Chief of Staff request for ${displayName}:`, params.task.trim()].join('\n') }],
+    parts: [
+      { type: 'text', text: [`${leadAgentDisplayName} request for ${displayName}:`, params.task.trim()].join('\n') },
+    ],
     metadata: { createdAt: Date.now() },
   }
 }

package/src/runtime/agent-types.ts

@@ -1,5 +1 @@
-export type {
-  ChatMode,
-  CreateHelperToolLoopAgentOptions,
-  CreateRoutedAgentOptions,
-} from '@lota-sdk/shared/runtime/agent-types'
+export type { ChatMode, CreateHelperToolLoopAgentOptions, CreateRoutedAgentOptions } from '@lota-sdk/shared'

package/src/runtime/approval-continuation.ts

@@ -1,9 +1,49 @@
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared'
+
+import { TABLES } from '../db/tables'
 
 export function hasApprovalRespondedParts(message: ChatMessage): boolean {
   return message.parts.some((part) => 'state' in part && (part as { state: string }).state === 'approval-responded')
 }
 
+export interface ApprovalContinuationResponse {
+  approvalId: string
+  approved: boolean
+  comments?: string
+  requiredEdits: string[]
+}
+
+export function readApprovalContinuationResponse(message: ChatMessage): ApprovalContinuationResponse | null {
+  for (const part of message.parts) {
+    if (!('state' in part) || (part as { state: string }).state !== 'approval-responded') continue
+    const approval = (part as { approval?: unknown }).approval
+    if (!approval || typeof approval !== 'object') continue
+
+    const record = approval as {
+      id?: unknown
+      approved?: unknown
+      reason?: unknown
+      comments?: unknown
+      requiredEdits?: unknown
+    }
+    if (typeof record.id !== 'string' || typeof record.approved !== 'boolean') continue
+
+    const requiredEdits = Array.isArray(record.requiredEdits)
+      ? record.requiredEdits.filter((item): item is string => typeof item === 'string' && item.trim().length > 0)
+      : []
+    const comments =
+      typeof record.comments === 'string' && record.comments.trim().length > 0
+        ? record.comments.trim()
+        : typeof record.reason === 'string' && record.reason.trim().length > 0
+          ? record.reason.trim()
+          : undefined
+
+    return { approvalId: record.id, approved: record.approved, comments, requiredEdits }
+  }
+
+  return null
+}
+
 export function isApprovalContinuationRequest(messages: ChatMessage[]): boolean {
   const lastAssistant = [...messages].reverse().find((message) => message.role === 'assistant')
   if (!lastAssistant) return false
@@ -14,3 +54,30 @@ export function isApprovalContinuationRequest(messages: ChatMessage[]): boolean
 
   return hasApprovalRespondedParts(lastAssistant)
 }
+
+const PLAN_TOOL_NAMES = new Set([
+  'createExecutionPlan',
+  'replaceExecutionPlan',
+  'submitExecutionNodeResult',
+  'getActiveExecutionPlan',
+  'resumeExecutionPlanRun',
+])
+
+function isPlanApprovalId(value: unknown): value is string {
+  return typeof value === 'string' && value.startsWith(`${TABLES.PLAN_APPROVAL}:`)
+}
+
+export function isNativeToolApprovalRequest(messages: ChatMessage[]): boolean {
+  const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant')
+  if (!lastAssistant) return false
+
+  return lastAssistant.parts.some((part) => {
+    if (!('state' in part) || (part as { state: string }).state !== 'approval-responded') return false
+    const approvalId = (part as { approval?: { id?: unknown } }).approval?.id
+    if (isPlanApprovalId(approvalId)) return false
+    const type = (part as { type?: string }).type
+    if (typeof type !== 'string' || !type.startsWith('tool-')) return false
+    const toolName = type.slice(5)
+    return !PLAN_TOOL_NAMES.has(toolName)
+  })
+}

package/src/runtime/chat-attachments.ts

@@ -1,4 +1,4 @@
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared'
 
 import type { ReadableUploadMetadataLike } from './chat-types'
 export type { ReadableUploadMetadataLike } from './chat-types'

package/src/runtime/chat-request-routing.ts

@@ -1,14 +1,18 @@
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared'
 
-import { isApprovalContinuationRequest } from './approval-continuation'
+import { isApprovalContinuationRequest, isNativeToolApprovalRequest } from './approval-continuation'
 
 export type RoutedChatRequest =
   | { kind: 'approval-continuation'; approvalMessages: ChatMessage[] }
+  | { kind: 'native-tool-approval'; messages: ChatMessage[] }
   | { kind: 'turn'; inputMessage: ChatMessage }
   | { kind: 'invalid'; message: string }
 
 export function routeWorkstreamChatMessages(messages: ChatMessage[]): RoutedChatRequest {
   if (isApprovalContinuationRequest(messages)) {
+    if (isNativeToolApprovalRequest(messages)) {
+      return { kind: 'native-tool-approval', messages }
+    }
     return { kind: 'approval-continuation', approvalMessages: messages }
   }
 

package/src/runtime/context-compaction-runtime.ts

@@ -18,12 +18,12 @@ import {
 import type { GenerateHelperStructuredParams, GenerateHelperTextParams } from './helper-model'
 import { StructuredCompactionOutputSchema } from './workstream-state'
 
-export interface HelperModelRuntime {
+interface HelperModelRuntime {
   generateHelperStructured<T>(params: GenerateHelperStructuredParams<T>): Promise<T>
   generateHelperText(params: GenerateHelperTextParams): Promise<string>
 }
 
-export interface CreateContextCompactionRuntimeDeps {
+interface CreateContextCompactionRuntimeDeps {
   helperModelRuntime: HelperModelRuntime
   now?: () => number
   randomId?: () => string

package/src/runtime/context-compaction.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto'
 
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { ChatMessage } from '@lota-sdk/shared'
 
 import { readString } from '../utils/string'
 import {

package/src/runtime/execution-plan.ts

@@ -1,14 +1,13 @@
-import type { SerializableExecutionPlan } from '@lota-sdk/shared/schemas/execution-plan'
+import type { SerializableExecutionPlan } from '@lota-sdk/shared'
 
 export const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
-- Before doing multi-step work, create an execution plan instead of tracking steps only in prose.
-- Keep plans short and operational. Prefer 2 to 7 tasks unless the work truly needs more.
-- Use execution-plan tools to create, replace, update, inspect, and restart the plan.
-- Only one execution-plan task may be active at a time.
-- Every task should have a concrete rationale and a concise output summary when work happens.
-- Treat prior task output summaries and carried tasks in <execution-plan-state> as observed facts.
-- If the ordered steps materially change, replace the plan instead of silently rewriting it in prose.
-- If the active plan is blocked, do not continue blindly. Replan, restart a task, ask for user input, or abort.
+- Before doing multi-step work, create a contract-driven execution plan instead of tracking steps only in prose.
+- Plans are graph-capable workflow contracts. Every execution node must define objective, instructions, deliverables, success criteria, completion checks, retry policy, failure policy, and tool/context policy.
+- The runtime executor owns lifecycle truth. Do not claim that a node is complete until submitExecutionNodeResult succeeds.
+- Use execution-plan tools to create, replace, inspect, submit node results, and resume runs.
+- Treat the active execution run in <execution-plan-state> as authoritative. Do not mutate run or node status in prose.
+- Work only on nodes that are active or explicitly ready for your executor. If a node is awaiting human input or approval, stop and let the runtime resume it.
+- If the graph, contracts, or success criteria materially change, replace the plan instead of silently drifting.
 </execution-plan-protocol>`
 
 export function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | undefined): string | undefined {
@@ -16,11 +15,11 @@ export function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | n
 
   const payload = {
     policy: {
-      activePlanIsAuthoritative: true,
-      priorOutputSummariesAreObservedFacts: true,
-      singleActiveTask: true,
-      explicitReplanRequired: true,
-      failureBudget: 2,
+      executorOwnsLifecycleTruth: true,
+      contractDrivenExecution: true,
+      humanGatesAreDurable: true,
+      artifactsAreFirstClassOutputs: true,
+      checkpointRecoveryEnabled: true,
     },
     plan,
   }
@@ -43,16 +42,24 @@ export function createExecutionPlanInstructionSectionCache(params: {
   disabled?: boolean
   loadPlan: () => Promise<SerializableExecutionPlan | null | undefined>
 }) {
+  let planPromise: Promise<SerializableExecutionPlan | null | undefined> | null = null
   let sectionsPromise: Promise<string[] | undefined> | null = null
 
   return {
     invalidate() {
+      planPromise = null
       sectionsPromise = null
     },
+    async getPlan(): Promise<SerializableExecutionPlan | null | undefined> {
+      if (params.disabled) return undefined
+
+      planPromise ??= params.loadPlan()
+      return await planPromise
+    },
     async getSections(): Promise<string[] | undefined> {
       if (params.disabled) return undefined
 
-      sectionsPromise ??= params.loadPlan().then((plan) => buildExecutionPlanInstructionSections(plan))
+      sectionsPromise ??= this.getPlan().then((plan) => buildExecutionPlanInstructionSections(plan))
       return await sectionsPromise
     },
   }

package/src/runtime/index.ts

@@ -0,0 +1,26 @@
+export * from './approval-continuation'
+export * from './agent-runtime-policy'
+export * from './agent-stream-helpers'
+export * from './agent-types'
+export * from './chat-request-routing'
+export * from './chat-run-registry'
+export * from './context-compaction'
+export * from './execution-plan'
+export * from './helper-model'
+export * from './indexed-repositories-policy'
+export * from './instruction-sections'
+export * from './memory-block'
+export * from './memory-digest-policy'
+export * from './memory-scope'
+export * from './llm-content'
+export * from './plugin-types'
+export * from './runtime-config'
+export * from './runtime-extensions'
+export * from './runtime-worker-registry'
+export * from './skill-extraction-policy'
+export * from './team-consultation-orchestrator'
+export * from './team-consultation-prompts'
+export * from './turn-lifecycle'
+export * from './workstream-chat-helpers'
+export * from './workstream-routing-policy'
+export * from './workstream-state'

package/src/runtime/indexed-repositories-policy.ts

@@ -1,3 +1,5 @@
+import { agentRoster } from '../config/agent-defaults'
+
 export type IndexedRepoAgentName = string
 
 export const REPO_SECTION_NAMES = [
@@ -13,16 +15,14 @@ export type RepoSectionName = (typeof REPO_SECTION_NAMES)[number]
 
 const ALL_REPO_SECTIONS: RepoSectionName[] = [...REPO_SECTION_NAMES]
 
-export const DEFAULT_REPO_SECTIONS_BY_AGENT: Record<IndexedRepoAgentName, RepoSectionName[]> = {
-  chief: [...ALL_REPO_SECTIONS],
-  ceo: [...ALL_REPO_SECTIONS],
-  cto: [...ALL_REPO_SECTIONS],
-  cpo: [...ALL_REPO_SECTIONS],
-  cmo: [...ALL_REPO_SECTIONS],
-  cfo: [...ALL_REPO_SECTIONS],
-  mentor: [...ALL_REPO_SECTIONS],
+export function buildDefaultRepoSectionsByAgent(
+  roster: readonly IndexedRepoAgentName[] = agentRoster,
+): Record<IndexedRepoAgentName, RepoSectionName[]> {
+  return Object.fromEntries(roster.map((agentId) => [agentId, [...ALL_REPO_SECTIONS]]))
 }
 
-export function emptyAgentContextMap(): Record<IndexedRepoAgentName, string> {
-  return { chief: '', ceo: '', cto: '', cpo: '', cmo: '', cfo: '', mentor: '' }
+export function emptyAgentContextMap(
+  roster: readonly IndexedRepoAgentName[] = agentRoster,
+): Record<IndexedRepoAgentName, string> {
+  return Object.fromEntries(roster.map((agentId) => [agentId, '']))
 }

package/src/runtime/memory-pipeline.ts

@@ -1,5 +1,3 @@
-export { agentScopeId, ORG_SCOPE_PREFIX, scopeId } from './memory-scope'
-
 interface MemoryFactInput {
   content: string
   confidence: number

package/src/runtime/runtime-config.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod'
+
+import type { CoreWorkstreamProfile } from '../config/agent-defaults'
+import type { LotaWorkstreamConfig, WorkstreamBootstrapWelcomeConfig } from '../config/workstream-defaults'
+import type { LotaPlugin } from './plugin-types'
+import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from './runtime-extensions'
+import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
+
+const logLevelValues = ['trace', 'debug', 'info', 'warning', 'error', 'fatal'] as const
+
+type LotaAgentFactoryRegistry = Record<string, (...args: unknown[]) => unknown>
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
+
+function isStringOrUrl(value: unknown): value is string | URL {
+  return typeof value === 'string' || value instanceof URL
+}
+
+function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
+  return typeof value === 'function'
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string')
+}
+
+function isAgentFactoryRegistry(value: unknown): value is LotaAgentFactoryRegistry {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'function')
+}
+
+function isPluginRuntimeRecord(value: unknown): value is Record<string, LotaPlugin> {
+  return isRecord(value)
+}
+
+function isToolProviderRecord(value: unknown): value is Record<string, unknown> {
+  return isRecord(value)
+}
+
+function isWorkerExtensionRecord(value: unknown): value is LotaRuntimeWorkerExtensions {
+  if (!isRecord(value)) return false
+
+  for (const key of ['start', 'schedule'] as const) {
+    const entry = value[key]
+    if (entry !== undefined && !isRecord(entry)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+const workstreamBootstrapWelcomeConfigSchema = z.object({
+  directAgentId: z.string().trim().min(1),
+  buildMessageText: z.custom<WorkstreamBootstrapWelcomeConfig['buildMessageText']>(isFunction, {
+    error: 'onboardingWelcome.buildMessageText must be a function',
+  }),
+})
+
+const workstreamConfigSchema = z.object({
+  bootstrap: z
+    .object({
+      onboardingDirectAgents: z.array(z.string().trim().min(1)).optional(),
+      completedDirectAgents: z.array(z.string().trim().min(1)).optional(),
+      coreTypesAfterOnboarding: z.array(z.string().trim().min(1)).optional(),
+      ensureDefaultGroupOnCompleted: z.boolean().optional(),
+      onboardingWelcome: workstreamBootstrapWelcomeConfigSchema.optional(),
+    })
+    .optional(),
+})
+
+const agentsConfigSchema = z
+  .object({
+    roster: z.array(z.string().trim().min(1)).min(1),
+    leadAgentId: z.string().trim().min(1),
+    displayNames: z.custom<Record<string, string>>(isStringRecord, {
+      error: 'agents.displayNames must be a string record',
+    }),
+    shortDisplayNames: z
+      .custom<Record<string, string>>(isStringRecord, { error: 'agents.shortDisplayNames must be a string record' })
+      .optional(),
+    teamConsultParticipants: z.array(z.string().trim().min(1)),
+    getCoreWorkstreamProfile: z
+      .custom<(coreType: string) => CoreWorkstreamProfile>(isFunction, {
+        error: 'agents.getCoreWorkstreamProfile must be a function',
+      })
+      .optional(),
+    createAgent: z
+      .custom<LotaAgentFactoryRegistry>(isAgentFactoryRegistry, {
+        error: 'agents.createAgent must be a function registry',
+      })
+      .optional(),
+    buildAgentTools: z
+      .custom<(...args: unknown[]) => unknown>(isFunction, { error: 'agents.buildAgentTools must be a function' })
+      .optional(),
+    getAgentRuntimeConfig: z
+      .custom<(...args: unknown[]) => unknown>(isFunction, { error: 'agents.getAgentRuntimeConfig must be a function' })
+      .optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (!value.roster.includes(value.leadAgentId)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['leadAgentId'],
+        message: 'agents.leadAgentId must be present in agents.roster',
+      })
+    }
+
+    for (const agentId of value.roster) {
+      if (!value.displayNames[agentId]) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['displayNames', agentId],
+          message: `Missing display name for agent "${agentId}"`,
+        })
+      }
+    }
+  })
+
+export const LotaRuntimeConfigSchema = z.object({
+  database: z.object({
+    url: z.string().trim().min(1),
+    namespace: z.string().trim().min(1),
+    username: z.string().trim().min(1),
+    password: z.string().trim().min(1),
+  }),
+  redis: z.object({ url: z.string().trim().min(1) }),
+  aiGateway: z.object({
+    url: z.string().trim().min(1),
+    key: z.string().trim().min(1),
+    admin: z.string().trim().min(1).optional(),
+    pass: z.string().trim().min(1).optional(),
+    embeddingModel: z.string().trim().min(1).default('openai/text-embedding-3-small'),
+  }),
+  s3: z.object({
+    endpoint: z.string().trim().min(1),
+    bucket: z.string().trim().min(1),
+    region: z.string().trim().min(1).default('garage'),
+    accessKeyId: z.string().trim().min(1),
+    secretAccessKey: z.string().trim().min(1),
+    attachmentUrlExpiresIn: z.coerce.number().positive().default(1800),
+  }),
+  firecrawl: z.object({
+    apiKey: z
+      .string()
+      .min(1, 'Firecrawl API key is required')
+      .refine((value) => value.startsWith('fc-'), 'Firecrawl API key must start with fc-')
+      .refine((value) => value !== 'dev-fire-key', 'Firecrawl API key placeholder is not allowed'),
+    apiBaseUrl: z.string().trim().url().optional(),
+  }),
+  logging: z.object({ level: z.enum(logLevelValues).default('info') }).default({ level: 'info' }),
+  memory: z
+    .object({
+      searchK: z.coerce.number().int().positive().default(6),
+      embeddingCacheTtlSeconds: z.coerce.number().int().positive().default(3600),
+    })
+    .default({ searchK: 6, embeddingCacheTtlSeconds: 3600 }),
+  workstreams: workstreamConfigSchema.default({}),
+  backgroundProcessing: z
+    .object({
+      memoryExtractionFrequency: z.coerce.number().int().positive().default(3),
+      skillExtractionFrequency: z.coerce.number().int().positive().default(5),
+      memoryDigestFrequency: z.coerce.number().int().positive().default(1),
+      memoryConsolidationFrequency: z.coerce.number().int().positive().default(10),
+    })
+    .default({
+      memoryExtractionFrequency: 3,
+      skillExtractionFrequency: 5,
+      memoryDigestFrequency: 1,
+      memoryConsolidationFrequency: 10,
+    }),
+  agents: agentsConfigSchema,
+  toolProviders: z.custom<Record<string, unknown>>(isToolProviderRecord).optional(),
+  extraSchemaFiles: z.array(z.custom<string | URL>(isStringOrUrl)).optional(),
+  extraWorkers: z.custom<LotaRuntimeWorkerExtensions>(isWorkerExtensionRecord).optional(),
+  pluginRuntime: z.custom<Record<string, LotaPlugin>>(isPluginRuntimeRecord).optional(),
+  runtimeAdapters: z.custom<LotaRuntimeAdapters>(isRecord).optional(),
+  turnHooks: z.custom<LotaRuntimeTurnHooks>(isRecord).optional(),
+})
+
+export type LotaRuntimeConfig = z.input<typeof LotaRuntimeConfigSchema>
+export type ResolvedLotaRuntimeConfig = z.infer<typeof LotaRuntimeConfigSchema>
+
+export const WORKER_BOOTSTRAP_ENV_SCHEMA = z.object({
+  SURREALDB_URL: z.string().trim().min(1),
+  SURREALDB_NAMESPACE: z.string().trim().min(1),
+  SURREALDB_USER: z.string().trim().min(1),
+  SURREALDB_PASSWORD: z.string().trim().min(1),
+  DB_SCHEMA_FINGERPRINT: z.string().trim().min(1).optional(),
+})
+
+export type WorkerBootstrapEnv = z.infer<typeof WORKER_BOOTSTRAP_ENV_SCHEMA>
+
+export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
+  'SURREALDB_URL',
+  'SURREALDB_NAMESPACE',
+  'SURREALDB_USER',
+  'SURREALDB_PASSWORD',
+  'REDIS_URL',
+  'AI_GATEWAY_URL',
+  'AI_GATEWAY_KEY',
+  'AI_GATEWAY_ADMIN',
+  'AI_GATEWAY_PASS',
+  'AI_EMBEDDING_MODEL',
+  'S3_ENDPOINT',
+  'S3_BUCKET',
+  'S3_REGION',
+  'S3_ACCESS_KEY_ID',
+  'S3_SECRET_ACCESS_KEY',
+  'ATTACHMENT_URL_EXPIRES_IN',
+  'FIRECRAWL_API_KEY',
+  'FIRECRAWL_API_BASE_URL',
+  'LOG_LEVEL',
+  'MEMORY_SEARCH_K',
+])
+
+let runtimeConfig: ResolvedLotaRuntimeConfig | null = null
+
+export function parseLotaRuntimeConfig(config: LotaRuntimeConfig): ResolvedLotaRuntimeConfig {
+  return LotaRuntimeConfigSchema.parse(config)
+}
+
+export function configureRuntimeConfig(config: ResolvedLotaRuntimeConfig): void {
+  runtimeConfig = config
+}
+
+export function getRuntimeConfig(): ResolvedLotaRuntimeConfig {
+  if (!runtimeConfig) {
+    throw new Error('Lota runtime config not configured. Call createLotaRuntime() first.')
+  }
+
+  return runtimeConfig
+}
+
+export function parseWorkerBootstrapEnv(env: Record<string, string | undefined>): WorkerBootstrapEnv {
+  return WORKER_BOOTSTRAP_ENV_SCHEMA.parse(env)
+}
+
+export type { LotaAgentFactoryRegistry, LotaWorkstreamConfig }

package/src/runtime/runtime-extensions.ts

@@ -2,6 +2,7 @@ import type { ToolSet } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
 import type { ReadableUploadMetadata } from '../services/attachment.service'
+import type { LotaRuntimeWorkerExtensions } from './runtime-worker-registry'
 
 export interface LotaRuntimeBackgroundCursor {
   createdAt: Date
@@ -102,7 +103,7 @@ interface RuntimeExtensionsState {
   adapters: LotaRuntimeAdapters
   turnHooks: LotaRuntimeTurnHooks
   toolProviders: ToolSet
-  extraWorkers: Record<string, unknown>
+  extraWorkers: LotaRuntimeWorkerExtensions
 }
 
 const EMPTY_TOOLS = {} as ToolSet
@@ -118,7 +119,7 @@ export function configureRuntimeExtensions(params?: {
   adapters?: LotaRuntimeAdapters
   turnHooks?: LotaRuntimeTurnHooks
   toolProviders?: ToolSet
-  extraWorkers?: Record<string, unknown>
+  extraWorkers?: LotaRuntimeWorkerExtensions
 }): void {
   runtimeExtensionsState = {
     adapters: params?.adapters ?? {},

package/src/runtime/runtime-worker-registry.ts

@@ -0,0 +1,47 @@
+import { startContextCompactionWorker } from '../queues/context-compaction.queue'
+import { scheduleRecurringConsolidation, startMemoryConsolidationWorker } from '../queues/memory-consolidation.queue'
+import { startPostChatMemoryWorker } from '../queues/post-chat-memory.queue'
+import { startRecentActivityTitleRefinementWorker } from '../queues/recent-activity-title-refinement.queue'
+import { startRegularChatMemoryDigestWorker } from '../queues/regular-chat-memory-digest.queue'
+import { startSkillExtractionWorker } from '../queues/skill-extraction.queue'
+import { startWorkstreamTitleGenerationWorker } from '../queues/workstream-title-generation.queue'
+
+export interface LotaRuntimeWorkerStartRegistry {
+  contextCompaction: typeof startContextCompactionWorker
+  memoryConsolidation: typeof startMemoryConsolidationWorker
+  postChatMemory: typeof startPostChatMemoryWorker
+  regularChatMemoryDigest: typeof startRegularChatMemoryDigestWorker
+  skillExtraction: typeof startSkillExtractionWorker
+  workstreamTitleGeneration: typeof startWorkstreamTitleGenerationWorker
+  recentActivityTitleRefinement: typeof startRecentActivityTitleRefinementWorker
+}
+
+export interface LotaRuntimeWorkerScheduleRegistry {
+  recurringConsolidation: typeof scheduleRecurringConsolidation
+}
+
+export interface LotaRuntimeWorkers {
+  start: LotaRuntimeWorkerStartRegistry & Record<string, unknown>
+  schedule: LotaRuntimeWorkerScheduleRegistry & Record<string, unknown>
+}
+
+export interface LotaRuntimeWorkerExtensions {
+  start?: Record<string, unknown>
+  schedule?: Record<string, unknown>
+}
+
+export function buildRuntimeWorkerRegistry(extraWorkers?: LotaRuntimeWorkerExtensions): LotaRuntimeWorkers {
+  return {
+    start: {
+      contextCompaction: startContextCompactionWorker,
+      memoryConsolidation: startMemoryConsolidationWorker,
+      postChatMemory: startPostChatMemoryWorker,
+      regularChatMemoryDigest: startRegularChatMemoryDigestWorker,
+      skillExtraction: startSkillExtractionWorker,
+      workstreamTitleGeneration: startWorkstreamTitleGenerationWorker,
+      recentActivityTitleRefinement: startRecentActivityTitleRefinementWorker,
+      ...extraWorkers?.start,
+    },
+    schedule: { recurringConsolidation: scheduleRecurringConsolidation, ...extraWorkers?.schedule },
+  }
+}