@lota-sdk/core 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -28,19 +28,19 @@
   },
   "dependencies": {
     "@ai-sdk/devtools": "^0.0.15",
-    "@ai-sdk/openai": "^3.0.41",
+    "@ai-sdk/openai": "^3.0.47",
     "@logtape/logtape": "^2.0.4",
-    "@lota-sdk/shared": "0.1.13",
+    "@lota-sdk/shared": "0.1.15",
     "@mendable/firecrawl-js": "^4.16.0",
     "@surrealdb/node": "^3.0.3",
-    "ai": "^6.0.116",
+    "ai": "^6.0.134",
     "bullmq": "^5.71.0",
     "hono": "^4.12.8",
     "ioredis": "5.9.3",
     "mammoth": "^1.12.0",
     "pdf-parse": "^2.4.5",
     "resumable-stream": "^2.2.12",
-    "surrealdb": "^2.0.2",
+    "surrealdb": "^2.0.3",
     "zod": "^4.3.6"
   }
 }

package/src/ai/embedding-cache.ts

@@ -4,17 +4,18 @@ import type IORedis from 'ioredis'
 
 import { aiLogger } from '../config/logger'
 
-const DEFAULT_TTL_SECONDS = 3600
+export const DEFAULT_EMBEDDING_CACHE_TTL_SECONDS = 3600
+const EMBEDDING_CACHE_KEY_PREFIX = 'emb'
 
 export class EmbeddingCache {
   constructor(
     private redis: IORedis,
-    private ttlSeconds: number = DEFAULT_TTL_SECONDS,
+    private ttlSeconds: number = DEFAULT_EMBEDDING_CACHE_TTL_SECONDS,
   ) {}
 
   private buildKey(model: string, text: string): string {
     const hash = createHash('sha256').update(text).digest('hex')
-    return `emb:${model}:${hash}`
+    return `${EMBEDDING_CACHE_KEY_PREFIX}:${model}:${hash}`
   }
 
   async get(model: string, text: string): Promise<number[] | null> {
@@ -23,7 +24,7 @@ export class EmbeddingCache {
       if (!cached) return null
       return JSON.parse(cached.toString()) as number[]
     } catch (error) {
-      aiLogger.debug`Embedding cache get failed: ${error}`
+      aiLogger.warn`Embedding cache get failed: ${error}`
       return null
     }
   }
@@ -32,7 +33,7 @@ export class EmbeddingCache {
     try {
       await this.redis.set(this.buildKey(model, text), JSON.stringify(embedding), 'EX', this.ttlSeconds)
     } catch (error) {
-      aiLogger.debug`Embedding cache set failed: ${error}`
+      aiLogger.warn`Embedding cache set failed: ${error}`
     }
   }
 }
@@ -40,7 +41,7 @@ export class EmbeddingCache {
 let embeddingCacheInstance: EmbeddingCache | null = null
 
 export function configureEmbeddingCache(redis: IORedis, ttlSeconds?: number): void {
-  embeddingCacheInstance = new EmbeddingCache(redis, ttlSeconds ?? DEFAULT_TTL_SECONDS)
+  embeddingCacheInstance = new EmbeddingCache(redis, ttlSeconds ?? DEFAULT_EMBEDDING_CACHE_TTL_SECONDS)
 }
 
 export function getEmbeddingCache(): EmbeddingCache | null {

package/src/ai/index.ts

@@ -1,3 +1,4 @@
 export * from './definitions'
 export * from './embedding-cache'
+// Re-exported for backwards compatibility — embeddings provider is part of the AI module surface
 export * from '../embeddings/provider'

package/src/bifrost/bifrost.ts

@@ -5,6 +5,7 @@ import type { LanguageModelMiddleware } from 'ai'
 
 import { isRecord, readString } from '../utils/string'
 
+type BifrostLanguageModel = Parameters<typeof wrapLanguageModel>[0]['model']
 type BifrostExtraParams = Record<string, unknown>
 type BifrostChatResponse = { body?: unknown }
 type BifrostTransformParamsOptions = Parameters<NonNullable<LanguageModelMiddleware['transformParams']>>[0]
@@ -131,7 +132,7 @@ export function injectBifrostChatReasoningStream(
         const closeReasoning = () => {
           if (!reasoningOpen || reasoningClosed) return
 
-          controller.enqueue({ type: 'reasoning-end', id: reasoningId } as BifrostStreamPart)
+          controller.enqueue({ type: 'reasoning-end', id: reasoningId } satisfies BifrostStreamPart)
           reasoningClosed = true
         }
 
@@ -141,11 +142,15 @@ export function injectBifrostChatReasoningStream(
 
           if (reasoningDelta) {
             if (!reasoningOpen) {
-              controller.enqueue({ type: 'reasoning-start', id: reasoningId } as BifrostStreamPart)
+              controller.enqueue({ type: 'reasoning-start', id: reasoningId } satisfies BifrostStreamPart)
               reasoningOpen = true
             }
 
-            controller.enqueue({ type: 'reasoning-delta', id: reasoningId, delta: reasoningDelta } as BifrostStreamPart)
+            controller.enqueue({
+              type: 'reasoning-delta',
+              id: reasoningId,
+              delta: reasoningDelta,
+            } satisfies BifrostStreamPart)
           }
           return
         }
@@ -158,7 +163,7 @@ export function injectBifrostChatReasoningStream(
       },
       flush(controller) {
         if (!reasoningOpen || reasoningClosed) return
-        controller.enqueue({ type: 'reasoning-end', id: reasoningId } as BifrostStreamPart)
+        controller.enqueue({ type: 'reasoning-end', id: reasoningId } satisfies BifrostStreamPart)
       },
     }),
   )
@@ -182,7 +187,7 @@ export function injectBifrostResponsesReasoningStream(
           id: reasoningDelta.id,
           delta: reasoningDelta.delta,
           providerMetadata: { openai: { itemId: reasoningDelta.itemId } },
-        } as BifrostStreamPart)
+        } satisfies BifrostStreamPart)
       },
     }),
   )
@@ -242,12 +247,12 @@ function createBifrostProvider(extraParams?: BifrostExtraParams) {
   })
 }
 
-function withBifrostDevTools<TModel>(model: TModel): TModel {
+function withBifrostDevTools<TModel extends BifrostLanguageModel>(model: TModel): TModel {
   if (process.env.NODE_ENV === 'production') {
     return model
   }
 
-  return wrapLanguageModel({ model: model as never, middleware: devToolsMiddleware() }) as unknown as TModel
+  return wrapLanguageModel({ model, middleware: devToolsMiddleware() }) as TModel
 }
 
 let provider: ReturnType<typeof createOpenAI> | null = null

package/src/config/agent-defaults.ts

@@ -51,7 +51,7 @@ export function configureAgents(config: {
   }
 }
 
-export function isAgentName(value: unknown): boolean {
+export function isAgentName(value: unknown): value is string {
   return typeof value === 'string' && new Set(agentRoster).has(value)
 }
 

package/src/config/logger.ts

@@ -1,7 +1,9 @@
 import type { LogLevel } from '@logtape/logtape'
 import { configure, getAnsiColorFormatter, getConsoleSink, getLogger as getLogTapeLogger } from '@logtape/logtape'
 
-export async function configureLotaLogger(logLevel: LogLevel): Promise<void> {
+const LOG_CATEGORY = 'lota-sdk'
+
+export async function configureLotaLogger(logLevel: LogLevel = 'info'): Promise<void> {
   const formatter = getAnsiColorFormatter({ level: 'FULL' })
 
   await configure({
@@ -10,7 +12,7 @@ export async function configureLotaLogger(logLevel: LogLevel): Promise<void> {
     loggers: [
       { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: ['console'] },
       { category: ['server'], lowestLevel: logLevel, sinks: ['console'] },
-      { category: ['lota-sdk'], lowestLevel: logLevel, sinks: ['console'] },
+      { category: [LOG_CATEGORY], lowestLevel: logLevel, sinks: ['console'] },
       { category: ['hono'], lowestLevel: logLevel, sinks: ['console'] },
     ],
   })
@@ -20,10 +22,6 @@ export function getLogger(category: readonly string[]) {
   return getLogTapeLogger([...category])
 }
 
-export async function configureLogger(logLevel?: LogLevel): Promise<void> {
-  await configureLotaLogger(logLevel ?? 'info')
-}
-
-export const serverLogger = getLogger(['lota-sdk'])
-export const chatLogger = getLogger(['lota-sdk', 'chat'])
-export const aiLogger = getLogger(['lota-sdk', 'ai'])
+export const serverLogger = getLogger([LOG_CATEGORY])
+export const chatLogger = getLogger([LOG_CATEGORY, 'chat'])
+export const aiLogger = getLogger([LOG_CATEGORY, 'ai'])

package/src/{runtime.ts → create-runtime.ts}

@@ -1,7 +1,9 @@
+import type { ChatMessage } from '@lota-sdk/shared'
+
 import { configureEmbeddingCache } from './ai/embedding-cache'
 import { configureAgentFactory, configureAgents } from './config/agent-defaults'
 import { configureBackgroundProcessing } from './config/background-processing'
-import { configureLogger } from './config/logger'
+import { configureLotaLogger } from './config/logger'
 import { configureWorkstreams } from './config/workstream-defaults'
 import { ensureRecordId } from './db/record-id'
 import { computeSchemaFingerprint } from './db/schema-fingerprint'
@@ -76,7 +78,6 @@ type UnarchiveSdkWorkstream = (
 export interface LotaRuntime {
   services: {
     database: SurrealDBService
-    databaseService: SurrealDBService
     redis: RedisConnectionManager
     closeRedisConnection: () => Promise<void>
     attachmentService: typeof attachmentService
@@ -132,7 +133,7 @@ export interface LotaRuntime {
       delete: typeof workstreamServiceSingleton.deleteWorkstream
       stop: typeof workstreamServiceSingleton.stopActiveRun
       listMessages: typeof workstreamMessageServiceSingleton.listMessageHistoryPage
-      getMessage: (params: { workstreamId: string; messageId: string }) => Promise<unknown>
+      getMessage: (params: { workstreamId: string; messageId: string }) => Promise<ChatMessage>
       sendMessage: (params: {
         workstreamId: string
         organizationId: string
@@ -170,7 +171,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
   const resolvedConfig = parseLotaRuntimeConfig(config)
   configureRuntimeConfig(resolvedConfig)
 
-  await configureLogger(resolvedConfig.logging.level)
+  await configureLotaLogger(resolvedConfig.logging.level)
 
   const db = new SurrealDBServiceClass({
     url: resolvedConfig.database.url,
@@ -306,7 +307,6 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
   return {
     services: {
       database: db,
-      databaseService: db,
       redis: redisManager,
       closeRedisConnection: async () => await redisManager.closeConnection(),
       attachmentService: attachmentServiceSingleton,
@@ -375,7 +375,7 @@ function getBuiltInSchemaFiles(): URL[] {
 function createPluginDatabaseConnector(pluginRuntime: Record<string, LotaPlugin>): () => Promise<void> {
   return async () => {
     for (const plugin of Object.values(pluginRuntime)) {
-      const services = plugin.services as Record<string, unknown>
+      const services = plugin.services
       const connectDatabase = services.connectDatabase
       if (typeof connectDatabase !== 'function') {
         continue

package/src/db/cursor-pagination.ts

@@ -64,7 +64,7 @@ async function listRowsBefore(
     throw new Error(`Cursor message not found in ${config.table}: ${params.beforeMessageId}`)
   }
 
-  const cursorCreatedAt = new Date(toTimestamp(cursorRow.createdAt))
+  const cursorCreatedAt = new Date(toTimestamp(cursorRow.createdAt) ?? Date.now())
   const cursorId = config.toRowId(params.parentId, params.beforeMessageId)
 
   return await databaseService.query<unknown>(

package/src/db/memory-store.ts

@@ -24,6 +24,10 @@ const MEMORY_TABLE = TABLES.MEMORY
 const MEMORY_HISTORY_TABLE = TABLES.MEMORY_HISTORY
 const MEMORY_RELATION_TABLE = TABLES.MEMORY_RELATION
 const MIN_RELEVANCE_SCORE = 0.25
+const STRONG_GRAPH_BOOSTS = { support: 0.1, contradict: 0.2 } as const
+const WEAK_GRAPH_BOOSTS = { support: 0.05, contradict: 0.1 } as const
+const CANDIDATE_FANOUT_MULTIPLIER = 4
+const CANDIDATE_SLICE_FLOOR = 50
 const TOUCH_MEMORIES_MAX_ATTEMPTS = 4
 const TOUCH_MEMORIES_RETRY_BASE_DELAY_MS = 25
 const TOUCH_MEMORIES_RETRY_JITTER_MS = 20
@@ -153,7 +157,7 @@ export class SurrealMemoryStore {
       relationCounts,
       options.limit,
       (row) => 1 / (1 + row.distance),
-      { support: 0.1, contradict: 0.2 },
+      STRONG_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -317,7 +321,7 @@ export class SurrealMemoryStore {
         if (b.textScore !== a.textScore) return b.textScore - a.textScore
         return a.index - b.index
       })
-      .slice(0, Math.max(options.limit * 4, 50))
+      .slice(0, Math.max(options.limit * CANDIDATE_FANOUT_MULTIPLIER, CANDIDATE_SLICE_FLOOR))
 
     if (options.fastMode) {
       return this.mapFastRows(scoredRows, options.limit, (row) => row.textScore)
@@ -330,7 +334,7 @@ export class SurrealMemoryStore {
       recentRelationCounts,
       options.limit,
       (row) => row.textScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -483,7 +487,7 @@ export class SurrealMemoryStore {
       relationCounts,
       limit,
       (row) => 1 / (1 + row.distance),
-      { support: 0.1, contradict: 0.2 },
+      STRONG_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -520,7 +524,7 @@ export class SurrealMemoryStore {
       relationCounts,
       limit,
       (row) => row.rrfScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -619,7 +623,7 @@ export class SurrealMemoryStore {
       relationCounts,
       options.limit,
       (row) => row.linearScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 

package/src/db/memory.ts

@@ -12,6 +12,7 @@ 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 { compactWhitespace } from '../utils/string'
 import type { SurrealMemoryStore } from './memory-store'
 import { getDefaultMemoryStore } from './memory-store'
 import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
@@ -39,6 +40,7 @@ const MEMORY_DELTA_MAX_CANDIDATE_MEMORIES = 80
 const MEMORY_DELTA_MAX_CANDIDATES_PER_FACT = 10
 const MEMORY_DELTA_MIN_BASELINE_CANDIDATES = 12
 const MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS = 400
+const CANDIDATE_FANOUT_MULTIPLIER = 4
 const helperModelRuntime = createHelperModelRuntime()
 
 interface PreparedScopeUpdate {
@@ -277,7 +279,7 @@ export class Memory {
         typeof extractionOptions?.maxFacts === 'number' ? { maxFacts: extractionOptions.maxFacts } : {},
       )
     } catch (error) {
-      aiLogger.error`Failed to extract facts: ${error}`
+      aiLogger.warn`Failed to extract facts: ${error}`
       return []
     }
   }
@@ -313,7 +315,7 @@ export class Memory {
   }
 
   private normalizeMemoryDeltaText(value: string, maxChars?: number): string {
-    const normalized = value.replace(/\s+/g, ' ').trim()
+    const normalized = compactWhitespace(value)
     if (!normalized) return ''
     if (typeof maxChars !== 'number' || normalized.length <= maxChars) return normalized
     return `${normalized.slice(0, maxChars - 3)}...`
@@ -384,7 +386,7 @@ export class Memory {
     const targetCandidateCount = Math.min(MEMORY_DELTA_MAX_CANDIDATE_MEMORIES, normalizedExisting.length)
     const baselineCount = Math.min(
       targetCandidateCount,
-      Math.max(MEMORY_DELTA_MIN_BASELINE_CANDIDATES, newFacts.length * 4),
+      Math.max(MEMORY_DELTA_MIN_BASELINE_CANDIDATES, newFacts.length * CANDIDATE_FANOUT_MULTIPLIER),
     )
 
     const selectedIds = new Set<string>(
@@ -502,7 +504,7 @@ export class Memory {
         await this.store.addRelation(fromId, toId, relation.relation)
         aiLogger.debug`Created ${relation.relation} relation: ${fromId} -> ${toId}`
       } catch (error) {
-        aiLogger.warn`Failed to create relation: ${error}`
+        aiLogger.warn`Failed to create memory relation (non-fatal, graph may be incomplete): ${error}`
       }
     }
   }

package/src/db/schema-fingerprint.ts

@@ -7,6 +7,7 @@ function toSchemaFilePath(value: string | URL): string {
 export async function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
   const hash = createHash('sha256')
 
+  // Sequential reads required: hash must be computed in deterministic file order
   for (const schemaFile of schemaFiles) {
     const sortKey = toSchemaFilePath(schemaFile)
     const file = schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile)