@lota-sdk/core 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -13,91 +13,6 @@
       "bun": "./src/index.ts",
       "import": "./src/index.ts",
       "types": "./src/index.ts"
-    },
-    "./ai/*": {
-      "bun": "./src/ai/*.ts",
-      "import": "./src/ai/*.ts",
-      "types": "./src/ai/*.ts"
-    },
-    "./bifrost": {
-      "bun": "./src/bifrost/bifrost.ts",
-      "import": "./src/bifrost/bifrost.ts",
-      "types": "./src/bifrost/bifrost.ts"
-    },
-    "./bifrost/*": {
-      "bun": "./src/bifrost/*.ts",
-      "import": "./src/bifrost/*.ts",
-      "types": "./src/bifrost/*.ts"
-    },
-    "./runtime/*": {
-      "bun": "./src/runtime/*.ts",
-      "import": "./src/runtime/*.ts",
-      "types": "./src/runtime/*.ts"
-    },
-    "./tools/*": {
-      "bun": "./src/tools/*.ts",
-      "import": "./src/tools/*.ts",
-      "types": "./src/tools/*.ts"
-    },
-    "./storage/*": {
-      "bun": "./src/storage/*.ts",
-      "import": "./src/storage/*.ts",
-      "types": "./src/storage/*.ts"
-    },
-    "./document/*": {
-      "bun": "./src/document/*.ts",
-      "import": "./src/document/*.ts",
-      "types": "./src/document/*.ts"
-    },
-    "./system-agents/*": {
-      "bun": "./src/system-agents/*.ts",
-      "import": "./src/system-agents/*.ts",
-      "types": "./src/system-agents/*.ts"
-    },
-    "./db/*": {
-      "bun": "./src/db/*.ts",
-      "import": "./src/db/*.ts",
-      "types": "./src/db/*.ts"
-    },
-    "./redis": {
-      "bun": "./src/redis/index.ts",
-      "import": "./src/redis/index.ts",
-      "types": "./src/redis/index.ts"
-    },
-    "./redis/*": {
-      "bun": "./src/redis/*.ts",
-      "import": "./src/redis/*.ts",
-      "types": "./src/redis/*.ts"
-    },
-    "./services/*": {
-      "bun": "./src/services/*.ts",
-      "import": "./src/services/*.ts",
-      "types": "./src/services/*.ts"
-    },
-    "./config/*": {
-      "bun": "./src/config/*.ts",
-      "import": "./src/config/*.ts",
-      "types": "./src/config/*.ts"
-    },
-    "./utils/*": {
-      "bun": "./src/utils/*.ts",
-      "import": "./src/utils/*.ts",
-      "types": "./src/utils/*.ts"
-    },
-    "./queues/*": {
-      "bun": "./src/queues/*.ts",
-      "import": "./src/queues/*.ts",
-      "types": "./src/queues/*.ts"
-    },
-    "./workers/*": {
-      "bun": "./src/workers/*.ts",
-      "import": "./src/workers/*.ts",
-      "types": "./src/workers/*.ts"
-    },
-    "./embeddings": {
-      "bun": "./src/embeddings/provider.ts",
-      "import": "./src/embeddings/provider.ts",
-      "types": "./src/embeddings/provider.ts"
     }
   },
   "scripts": {
@@ -115,7 +30,7 @@
     "@ai-sdk/devtools": "^0.0.15",
     "@ai-sdk/openai": "^3.0.41",
     "@logtape/logtape": "^2.0.4",
-    "@lota-sdk/shared": "0.1.9",
+    "@lota-sdk/shared": "0.1.13",
     "@mendable/firecrawl-js": "^4.16.0",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.116",

package/src/ai/index.ts

@@ -0,0 +1,3 @@
+export * from './definitions'
+export * from './embedding-cache'
+export * from '../embeddings/provider'

package/src/bifrost/index.ts

@@ -0,0 +1 @@
+export * from './bifrost'

package/src/config/agent-defaults.ts

@@ -1,9 +1,18 @@
 type LotaAgentFactoryRegistry = Record<string, (...args: unknown[]) => unknown>
 
+function defaultBuildAgentTools(): Record<string, never> {
+  return {}
+}
+
+function defaultGetAgentRuntimeConfig(): Record<string, never> {
+  return {}
+}
+
 // Agent configuration — these are defaults that consumers override via createLotaRuntime config
 export let agentDisplayNames: Record<string, string> = {}
 export let agentShortDisplayNames: Record<string, string> = {}
 export let agentRoster: readonly string[] = []
+export let leadAgentId = ''
 export let teamConsultParticipants: readonly string[] = []
 
 export interface CoreWorkstreamProfile {
@@ -22,12 +31,18 @@ export let getCoreWorkstreamProfile: (coreType: string) => CoreWorkstreamProfile
 
 export function configureAgents(config: {
   roster: readonly string[]
+  leadAgentId: string
   displayNames: Record<string, string>
   shortDisplayNames?: Record<string, string>
   teamConsultParticipants: readonly string[]
   getCoreWorkstreamProfile?: (coreType: string) => CoreWorkstreamProfile
 }): void {
+  if (!config.roster.includes(config.leadAgentId)) {
+    throw new Error(`Lead agent "${config.leadAgentId}" must be present in the configured roster.`)
+  }
+
   agentRoster = config.roster
+  leadAgentId = config.leadAgentId
   agentDisplayNames = config.displayNames
   agentShortDisplayNames = config.shortDisplayNames ?? {}
   teamConsultParticipants = config.teamConsultParticipants
@@ -40,6 +55,14 @@ export function isAgentName(value: unknown): boolean {
   return typeof value === 'string' && new Set(agentRoster).has(value)
 }
 
+export function getLeadAgentId(): string {
+  return leadAgentId
+}
+
+export function getLeadAgentDisplayName(): string {
+  return agentDisplayNames[leadAgentId] ?? leadAgentId
+}
+
 export function resolveAgentNameAlias(value: unknown): string | undefined {
   if (typeof value !== 'string') return undefined
   const lowered = value.trim().toLowerCase()
@@ -56,20 +79,20 @@ export function resolveAgentNameAlias(value: unknown): string | undefined {
 
 export let createAgent: LotaAgentFactoryRegistry = {}
 
-export let buildAgentTools: (...args: unknown[]) => unknown = () => ({})
-export let getAgentRuntimeConfig: (...args: unknown[]) => unknown = () => ({})
+export let buildAgentTools: (...args: unknown[]) => unknown = defaultBuildAgentTools
+export let getAgentRuntimeConfig: (...args: unknown[]) => unknown = defaultGetAgentRuntimeConfig
 export let pluginRuntime: unknown = undefined
 
 export function configureAgentFactory(config: {
-  createAgent: LotaAgentFactoryRegistry
+  createAgent?: LotaAgentFactoryRegistry
   buildAgentTools?: (...args: unknown[]) => unknown
   getAgentRuntimeConfig?: (...args: unknown[]) => unknown
   pluginRuntime?: unknown
 }): void {
-  createAgent = config.createAgent
-  if (config.buildAgentTools) buildAgentTools = config.buildAgentTools
-  if (config.getAgentRuntimeConfig) getAgentRuntimeConfig = config.getAgentRuntimeConfig
-  if (config.pluginRuntime !== undefined) pluginRuntime = config.pluginRuntime
+  createAgent = config.createAgent ?? {}
+  buildAgentTools = config.buildAgentTools ?? defaultBuildAgentTools
+  getAgentRuntimeConfig = config.getAgentRuntimeConfig ?? defaultGetAgentRuntimeConfig
+  pluginRuntime = config.pluginRuntime
 }
 
 const AGENT_MENTION_REGEX = /(^|[^\w])@([a-z][a-z0-9_-]*)\b/gi

package/src/config/constants.ts

@@ -22,12 +22,3 @@ export const MEMORY = {
 export function validateKnnLimit(limit: unknown): number {
   return z.number().int().positive().max(MEMORY.MAX_KNN_LIMIT).parse(limit)
 }
-
-/**
- * Creates a KNN query string with validated limit
- * Example: createKnnQuery(10) returns "<|10|>"
- */
-export function createKnnQuery(limit: unknown): string {
-  const validatedLimit = validateKnnLimit(limit)
-  return `<|${validatedLimit}|>`
-}

package/src/config/debug-logger.ts

@@ -0,0 +1,43 @@
+import { chatLogger } from './logger'
+
+const isDebug = () => process.env.LOG_LEVEL === 'debug' || process.env.LOTA_DEBUG === '1'
+
+interface DebugTimer {
+  step(name: string): void
+  elapsed(): number
+}
+
+const NOOP_TIMER: DebugTimer = { step() {}, elapsed: () => 0 }
+
+function createTimer(label: string): DebugTimer {
+  const start = performance.now()
+  let lastStep = start
+
+  return {
+    step(name: string) {
+      const now = performance.now()
+      const stepMs = now - lastStep
+      const totalMs = now - start
+      chatLogger.debug`[ttft:${label}] ${name}: ${stepMs.toFixed(1)}ms (elapsed: ${totalMs.toFixed(1)}ms)`
+      lastStep = now
+    },
+    elapsed() {
+      return performance.now() - start
+    },
+  }
+}
+
+export const lotaDebugLogger = {
+  get enabled() {
+    return isDebug()
+  },
+
+  timer(label: string): DebugTimer {
+    return isDebug() ? createTimer(label) : NOOP_TIMER
+  },
+
+  step(name: string) {
+    if (!isDebug()) return
+    chatLogger.debug`[ttft] ${name}`
+  },
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+export * from './agent-defaults'
+export * from './background-processing'
+export * from './logger'
+export * from './model-constants'
+export * from './workstream-defaults'

package/src/config/model-constants.ts

@@ -4,9 +4,6 @@ export const OPENROUTER_TEAM_AGENT_MODEL_ID = 'openrouter/google/gemini-3.1-pro-
 export const OPENROUTER_STRUCTURED_HELPER_MODEL_ID = 'openrouter/google/gemini-3-flash-preview:exacto' as const
 export const OPENROUTER_DELEGATED_REASONING_MODEL_ID = 'openrouter/google/gemini-3-flash-preview:exacto' as const
 export const OPENROUTER_WEB_RESEARCH_MODEL_ID = 'openrouter/stepfun/step-3.5-flash' as const
-export const OPENROUTER_ARTIFACT_GENERATOR_MODEL_ID = 'openrouter/qwen/qwen3.5-flash-02-23' as const
-export const OPENROUTER_REPO_INDEXER_MODEL_ID = 'openrouter/qwen/qwen3.5-flash-02-23:nitro' as const
-export const OPENROUTER_CODE_ANALYSIS_MODEL_ID = 'openrouter/xiaomi/mimo-v2-flash' as const
 export const OPENROUTER_FAST_REASONING_MODEL_ID = 'openrouter/openai/gpt-oss-120b:nitro' as const
 export const OPENROUTER_STRUCTURED_REASONING_MODEL_ID = 'openrouter/openai/gpt-oss-120b:exacto' as const
 

package/src/config/workstream-defaults.ts

@@ -66,3 +66,7 @@ export function configureWorkstreams(params: { agentRoster: readonly string[]; c
 export function getWorkstreamBootstrapConfig(): ResolvedWorkstreamBootstrapConfig {
   return resolvedWorkstreamBootstrapConfig
 }
+
+export function resolveOnboardingOwnerAgentId(defaultLeadAgentId: string): string {
+  return resolvedWorkstreamBootstrapConfig.onboardingWelcome?.directAgentId ?? defaultLeadAgentId
+}

package/src/db/cursor-pagination.ts

@@ -1,5 +1,5 @@
-import { toTimestamp } from '@lota-sdk/shared/runtime/chat-message-metadata'
-import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import { toTimestamp } from '@lota-sdk/shared'
+import type { ChatMessage } from '@lota-sdk/shared'
 import type { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
 

package/src/db/index.ts

@@ -0,0 +1,10 @@
+export * from './cursor-pagination'
+export * from './memory'
+export * from './memory-store'
+export * from './memory-store.helpers'
+export * from './memory-types'
+export * from './record-id'
+export * from './sdk-database'
+export * from './service'
+export * from './startup'
+export * from './tables'

package/src/db/memory.ts

@@ -1,4 +1,3 @@
-import { env } from '../config/env-shapes'
 import { aiLogger } from '../config/logger'
 import type { CreateHelperAgentFn } from '../runtime/helper-model'
 import { createHelperModelRuntime } from '../runtime/helper-model'
@@ -12,6 +11,7 @@ import {
 import { getFactRetrievalMessages } from '../runtime/memory-prompts-fact'
 import { parseMessages } from '../runtime/memory-prompts-parse'
 import { getClassifyMemoryDeltaPrompt } from '../runtime/memory-prompts-update'
+import { getRuntimeConfig } from '../runtime/runtime-config'
 import type { SurrealMemoryStore } from './memory-store'
 import { getDefaultMemoryStore } from './memory-store'
 import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
@@ -91,23 +91,15 @@ export class Memory {
   }
 
   async search(query: string, options: SearchOptions): Promise<string> {
-    const results = await this.store.search(
-      query,
-      options.scopeId,
-      options.limit ?? env.MEMORY_SEARCH_K,
-      options.memoryType,
-    )
+    const limit = options.limit ?? getRuntimeConfig().memory.searchK
+    const results = await this.store.search(query, options.scopeId, limit, options.memoryType)
 
     return formatResults(results)
   }
 
   async hybridSearch(query: string, options: SearchOptions): Promise<string> {
-    const results = await this.store.hybridSearch(
-      query,
-      options.scopeId,
-      options.limit ?? env.MEMORY_SEARCH_K,
-      options.memoryType,
-    )
+    const limit = options.limit ?? getRuntimeConfig().memory.searchK
+    const results = await this.store.hybridSearch(query, options.scopeId, limit, options.memoryType)
 
     return formatResults(results)
   }
@@ -116,9 +108,10 @@ export class Memory {
     query: string,
     options: SearchOptions & { weights?: [number, number]; normalization?: 'minmax' | 'zscore' },
   ): Promise<string> {
+    const limit = options.limit ?? getRuntimeConfig().memory.searchK
     const results = await this.store.hybridSearchWeighted(query, {
       scopeId: options.scopeId,
-      limit: options.limit ?? env.MEMORY_SEARCH_K,
+      limit,
       memoryType: options.memoryType,
       weights: options.weights,
       normalization: options.normalization,
@@ -128,9 +121,10 @@ export class Memory {
   }
 
   async searchCandidates(query: string, options: WeightedSearchOptions): Promise<MemorySearchResult[]> {
+    const limit = options.limit ?? getRuntimeConfig().memory.searchK
     const results = await this.store.hybridSearchWeighted(query, {
       scopeId: options.scopeId,
-      limit: options.limit ?? env.MEMORY_SEARCH_K,
+      limit,
       memoryType: options.memoryType,
       weights: options.weights,
       normalization: options.normalization,

package/src/document/index.ts

@@ -0,0 +1,2 @@
+export * from './org-document-chunking'
+export * from './parsing'

package/src/document/parsing.ts

@@ -13,28 +13,3 @@ export function normalizeKey(value: string): string {
     .replace(/\s+/g, '-')
     .slice(0, 120)
 }
-
-export function makeMemoryKey(kind: string, rawKey: string): string {
-  const normalized = normalizeKey(rawKey)
-  return normalized ? `${kind}:${normalized}` : `${kind}:item`
-}
-
-export function truncateForModel(value: string, maxChars: number): string {
-  if (value.length <= maxChars) return value
-  return `${value.slice(0, maxChars)}\n\n[...truncated due to size...]`
-}
-
-export function dedupeStrings(items: string[], limit: number): string[] {
-  const out: string[] = []
-  const seen = new Set<string>()
-  for (const raw of items) {
-    const value = normalizeWhitespace(raw)
-    if (!value) continue
-    const key = value.toLowerCase()
-    if (seen.has(key)) continue
-    seen.add(key)
-    out.push(value)
-    if (out.length >= limit) break
-  }
-  return out
-}

package/src/embeddings/provider.ts

@@ -2,7 +2,7 @@ import { embed, embedMany } from 'ai'
 
 import { getEmbeddingCache } from '../ai/embedding-cache'
 import { bifrostEmbeddingModel } from '../bifrost/bifrost'
-import { env } from '../config/env-shapes'
+import { getRuntimeConfig } from '../runtime/runtime-config'
 
 const SUPPORTED_EMBEDDING_PREFIXES = ['openai/', 'openrouter/'] as const
 
@@ -41,19 +41,28 @@ export class ProviderEmbeddings {
   private readonly embedFn: typeof embed
   private readonly embedManyFn: typeof embedMany
   private readonly getCache: () => SharedEmbeddingCache | null
-  private readonly modelId: string
+  private readonly configuredModelId?: string
+  private resolvedModelId: string | null = null
   private _model: ReturnType<typeof resolveEmbeddingModel> | null = null
 
   constructor(options: ProviderEmbeddingsOptions = {}) {
     this.embedFn = options.embedFn ?? embed
     this.embedManyFn = options.embedManyFn ?? embedMany
     this.getCache = options.getCache ?? getEmbeddingCache
-    this.modelId = options.modelId ?? env.AI_EMBEDDING_MODEL
+    this.configuredModelId = options.modelId
+  }
+
+  private getModelId(): string {
+    if (!this.resolvedModelId) {
+      this.resolvedModelId = this.configuredModelId ?? getRuntimeConfig().aiGateway.embeddingModel
+    }
+
+    return this.resolvedModelId
   }
 
   private getModel() {
     if (!this._model) {
-      this._model = resolveEmbeddingModel(this.modelId)
+      this._model = resolveEmbeddingModel(this.getModelId())
     }
     return this._model
   }
@@ -62,7 +71,7 @@ export class ProviderEmbeddings {
     const redisCache = this.getCache()
     if (!redisCache) return null
 
-    return await redisCache.get(this.modelId, text)
+    return await redisCache.get(this.getModelId(), text)
   }
 
   async embedQuery(text: string): Promise<number[]> {
@@ -77,7 +86,7 @@ export class ProviderEmbeddings {
 
     const redisCache = this.getCache()
     if (redisCache) {
-      void redisCache.set(this.modelId, input, embedding)
+      void redisCache.set(this.getModelId(), input, embedding)
     }
 
     return embedding
@@ -102,7 +111,7 @@ export class ProviderEmbeddings {
     const redisCache = this.getCache()
     if (redisCache && missingTexts.length > 0) {
       const redisResults = await Promise.all(
-        missingTexts.map(async (text) => ({ text, embedding: await redisCache.get(this.modelId, text) })),
+        missingTexts.map(async (text) => ({ text, embedding: await redisCache.get(this.getModelId(), text) })),
       )
 
       missingTexts = []
@@ -123,7 +132,7 @@ export class ProviderEmbeddings {
         const embedding = normalizeEmbedding(result.embeddings[index] ?? [])
         embeddingsByText.set(text, embedding)
         if (redisCache) {
-          void redisCache.set(this.modelId, text, embedding)
+          void redisCache.set(this.getModelId(), text, embedding)
         }
       })
     }