@lota-sdk/core 0.1.9 → 0.1.12

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,32 +4,31 @@ 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
 
+export const BIFROST_REASONING_SUMMARY_LEVEL = 'detailed' as const
+
 export const OPENAI_HIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } as const
 
 export const OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } as const
 
 export const OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'xhigh', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'xhigh', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } as const
 
 export const OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'medium', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'medium', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } as const
 
 export const OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'low', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'low', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } as const
 
 export const OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'minimal', reasoningSummary: 'auto' },
+  openai: { forceReasoning: true, reasoningEffort: 'minimal', reasoningSummary: BIFROST_REASONING_SUMMARY_LEVEL },
 } 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-store.ts

@@ -1,10 +1,8 @@
 import { BoundQuery, eq, inside } from 'surrealdb'
 
-import { getEmbeddingCache } from '../ai/embedding-cache'
-import { env } from '../config/env-shapes'
 import { aiLogger } from '../config/logger'
 import { DEFAULT_MEMORY_SEARCH_LIMIT } from '../config/search'
-import { createDefaultEmbeddings } from '../embeddings/provider'
+import { getDefaultEmbeddings } from '../embeddings/provider'
 import { memoryQueryBuilder } from './memory-query-builder'
 import type { RelationCounts } from './memory-store.helpers'
 import { hashContent, mapRowToMemoryRecord, processGraphAwareRows } from './memory-store.helpers'
@@ -25,8 +23,6 @@ import { TABLES } from './tables'
 const MEMORY_TABLE = TABLES.MEMORY
 const MEMORY_HISTORY_TABLE = TABLES.MEMORY_HISTORY
 const MEMORY_RELATION_TABLE = TABLES.MEMORY_RELATION
-const EMBEDDING_CACHE_TTL_MS = 5 * 60 * 1000
-const EMBEDDING_CACHE_MAX_ENTRIES = 64
 const MIN_RELEVANCE_SCORE = 0.25
 const TOUCH_MEMORIES_MAX_ATTEMPTS = 4
 const TOUCH_MEMORIES_RETRY_BASE_DELAY_MS = 25
@@ -37,9 +33,6 @@ interface EmbeddingClient {
 }
 
 export class SurrealMemoryStore {
-  private embeddingCache = new Map<string, { embedding: number[]; ts: number }>()
-  private embeddingInFlight = new Map<string, Promise<number[]>>()
-
   constructor(private embeddings: EmbeddingClient) {}
 
   private toMetadataFieldPath(key: string): string {
@@ -183,72 +176,11 @@ export class SurrealMemoryStore {
       }))
   }
 
-  private getEmbeddingCacheKey(content: string): string {
-    return content.trim().toLowerCase()
-  }
-
-  private pruneEmbeddingCache(now: number): void {
-    for (const [cacheKey, entry] of this.embeddingCache.entries()) {
-      if (now - entry.ts > EMBEDDING_CACHE_TTL_MS) {
-        this.embeddingCache.delete(cacheKey)
-      }
-    }
-
-    while (this.embeddingCache.size > EMBEDDING_CACHE_MAX_ENTRIES) {
-      const oldest = this.embeddingCache.keys().next().value
-      if (!oldest) break
-      this.embeddingCache.delete(oldest)
-    }
-  }
-
   private async generateEmbedding(content: string): Promise<number[]> {
     const normalized = content.trim()
     if (!normalized) return []
 
-    const cacheKey = this.getEmbeddingCacheKey(normalized)
-    const now = Date.now()
-    this.pruneEmbeddingCache(now)
-
-    // L1: in-memory cache
-    const cached = this.embeddingCache.get(cacheKey)
-    if (cached && now - cached.ts <= EMBEDDING_CACHE_TTL_MS) {
-      return cached.embedding
-    }
-
-    const inFlight = this.embeddingInFlight.get(cacheKey)
-    if (inFlight) {
-      return await inFlight
-    }
-
-    const request = (async () => {
-      // L2: Redis cache
-      const redisCache = getEmbeddingCache()
-      if (redisCache) {
-        const model = env.AI_EMBEDDING_MODEL
-        const redisCached = await redisCache.get(model, normalized)
-        if (redisCached) {
-          this.embeddingCache.set(cacheKey, { embedding: redisCached, ts: Date.now() })
-          return redisCached
-        }
-      }
-
-      // L3: API call
-      const embedding = await this.embeddings.embedQuery(normalized)
-      this.embeddingCache.set(cacheKey, { embedding, ts: Date.now() })
-      this.pruneEmbeddingCache(Date.now())
-
-      // Backfill Redis
-      if (redisCache) {
-        void redisCache.set(env.AI_EMBEDDING_MODEL, normalized, embedding)
-      }
-
-      return embedding
-    })().finally(() => {
-      this.embeddingInFlight.delete(cacheKey)
-    })
-
-    this.embeddingInFlight.set(cacheKey, request)
-    return await request
+    return await this.embeddings.embedQuery(normalized)
   }
 
   async warmEmbedding(content: string): Promise<void> {
@@ -1059,7 +991,7 @@ let defaultMemoryStore: SurrealMemoryStore | null = null
 
 export function getDefaultMemoryStore(): SurrealMemoryStore {
   if (!defaultMemoryStore) {
-    defaultMemoryStore = new SurrealMemoryStore(createDefaultEmbeddings())
+    defaultMemoryStore = new SurrealMemoryStore(getDefaultEmbeddings())
   }
   return defaultMemoryStore
 }

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/db/service.ts

@@ -66,6 +66,8 @@ export type CreateMutationBuilder = {
 export interface DatabaseTransaction {
   query: (query: unknown) => Promise<unknown>
   create: (target: unknown) => CreateMutationBuilder
+  update: (target: unknown) => MutationBuilder
+  delete: (target: unknown) => Promise<unknown>
   relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) => Promise<unknown>
   commit: () => Promise<void>
   cancel: () => Promise<void>
@@ -458,6 +460,38 @@ export class SurrealDBService {
     throw new SurrealDBError('Invalid table value')
   }
 
+  private isRecordIdLike(value: unknown): boolean {
+    if (value instanceof RecordId || value instanceof StringRecordId) {
+      return true
+    }
+
+    if (typeof value === 'string') {
+      return /^[a-zA-Z][a-zA-Z0-9_]*:/.test(value)
+    }
+
+    if (value && typeof value === 'object') {
+      const record = value as { tb?: unknown; id?: unknown }
+      if (typeof record.tb === 'string' && record.id !== undefined) {
+        return true
+      }
+
+      const stringValue = toStringLikeValue(value)
+      if (stringValue) {
+        return /^[a-zA-Z][a-zA-Z0-9_]*:/.test(stringValue)
+      }
+    }
+
+    return false
+  }
+
+  private normalizeCreateTarget(value: unknown): Table | RecordId {
+    if (this.isRecordIdLike(value)) {
+      return ensureRecordId(value as RecordIdInput)
+    }
+
+    return this.normalizeTableValue(value)
+  }
+
   private wrapMutationBuilder(builder: MutationBuilder): MutationBuilder {
     return {
       content: (data) => this.wrapMutationBuilder(builder.content(this.normalizeMutationData(data))),
@@ -478,8 +512,14 @@ export class SurrealDBService {
   private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
     return {
       query: (query: unknown) => tx.query(this.normalizeBoundQuery(query as BoundQuery | BoundQueryLike)),
-      create: (target: unknown) =>
-        this.wrapCreateBuilder(tx.create(this.normalizeTableValue(target)) as unknown as CreateMutationBuilder),
+      create: (target: unknown) => {
+        const normalizedTarget = this.normalizeCreateTarget(target)
+        const builder = normalizedTarget instanceof Table ? tx.create(normalizedTarget) : tx.create(normalizedTarget)
+        return this.wrapCreateBuilder(builder as unknown as CreateMutationBuilder)
+      },
+      update: (target: unknown) =>
+        this.wrapMutationBuilder(tx.update(ensureRecordId(target as RecordIdInput)) as unknown as MutationBuilder),
+      delete: (target: unknown) => tx.delete(ensureRecordId(target as RecordIdInput)),
       relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
         tx.relate(
           ensureRecordId(from as RecordIdInput),

package/src/db/tables.ts

@@ -7,8 +7,15 @@ export const TABLES = {
   MEMORY_RELATION: 'memoryRelation',
   MEMORY_HISTORY: 'memoryHistory',
   LEARNED_SKILL: 'learnedSkill',
-  PLAN: 'plan',
-  PLAN_TASK: 'planTask',
+  PLAN_SPEC: 'planSpec',
+  PLAN_NODE_SPEC: 'planNodeSpec',
+  PLAN_RUN: 'planRun',
+  PLAN_NODE_RUN: 'planNodeRun',
+  PLAN_NODE_ATTEMPT: 'planNodeAttempt',
+  PLAN_ARTIFACT: 'planArtifact',
+  PLAN_APPROVAL: 'planApproval',
+  PLAN_CHECKPOINT: 'planCheckpoint',
+  PLAN_VALIDATION_ISSUE: 'planValidationIssue',
   PLAN_EVENT: 'planEvent',
   ORGANIZATION: 'organization',
   ORGANIZATION_MEMBER: 'organizationMember',

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

@@ -1,10 +1,23 @@
 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
 
+type SharedEmbeddingCache = {
+  get(model: string, text: string): Promise<number[] | null>
+  set(model: string, text: string, embedding: number[]): Promise<void>
+}
+
+type ProviderEmbeddingsOptions = {
+  embedFn?: typeof embed
+  embedManyFn?: typeof embedMany
+  getCache?: () => SharedEmbeddingCache | null
+  modelId?: string
+}
+
 function resolveEmbeddingModel(modelId: string) {
   const normalized = modelId.trim()
   if (!normalized) {
@@ -20,23 +33,63 @@ function resolveEmbeddingModel(modelId: string) {
   return bifrostEmbeddingModel(normalized)
 }
 
-class ProviderEmbeddings {
+function normalizeEmbedding(embedding: readonly number[]): number[] {
+  return embedding.map((value) => Number(value))
+}
+
+export class ProviderEmbeddings {
+  private readonly embedFn: typeof embed
+  private readonly embedManyFn: typeof embedMany
+  private readonly getCache: () => SharedEmbeddingCache | null
+  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.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(env.AI_EMBEDDING_MODEL)
+      this._model = resolveEmbeddingModel(this.getModelId())
     }
     return this._model
   }
 
+  private async loadCachedEmbedding(text: string): Promise<number[] | null> {
+    const redisCache = this.getCache()
+    if (!redisCache) return null
+
+    return await redisCache.get(this.getModelId(), text)
+  }
+
   async embedQuery(text: string): Promise<number[]> {
     const input = text.trim()
     if (!input) return []
 
-    const result = await embed({ model: this.getModel(), value: input, maxRetries: 2 })
+    const cached = await this.loadCachedEmbedding(input)
+    if (cached) return cached
 
-    return result.embedding.map((value) => Number(value))
+    const result = await this.embedFn({ model: this.getModel(), value: input, maxRetries: 2 })
+    const embedding = normalizeEmbedding(result.embedding)
+
+    const redisCache = this.getCache()
+    if (redisCache) {
+      void redisCache.set(this.getModelId(), input, embedding)
+    }
+
+    return embedding
   }
 
   async embedDocuments(values: string[]): Promise<number[][]> {
@@ -51,26 +104,53 @@ class ProviderEmbeddings {
       return normalized.map(() => [])
     }
 
-    const result = await embedMany({
-      model: this.getModel(),
-      values: nonEmptyEntries.map((entry) => entry.value),
-      maxRetries: 2,
-    })
-
-    const embeddingsByIndex = new Map<number, number[]>()
-    result.embeddings.forEach((embedding, index) => {
-      const entry = nonEmptyEntries.at(index)
-      if (!entry) return
-      embeddingsByIndex.set(
-        entry.index,
-        embedding.map((value) => Number(value)),
+    const uniqueTexts = [...new Set(nonEmptyEntries.map((entry) => entry.value))]
+    const embeddingsByText = new Map<string, number[]>()
+    let missingTexts = [...uniqueTexts]
+
+    const redisCache = this.getCache()
+    if (redisCache && missingTexts.length > 0) {
+      const redisResults = await Promise.all(
+        missingTexts.map(async (text) => ({ text, embedding: await redisCache.get(this.getModelId(), text) })),
       )
-    })
 
-    return normalized.map((_, index) => embeddingsByIndex.get(index) ?? [])
+      missingTexts = []
+      for (const result of redisResults) {
+        if (!result.embedding) {
+          missingTexts.push(result.text)
+          continue
+        }
+
+        embeddingsByText.set(result.text, result.embedding)
+      }
+    }
+
+    if (missingTexts.length > 0) {
+      const result = await this.embedManyFn({ model: this.getModel(), values: missingTexts, maxRetries: 2 })
+
+      missingTexts.forEach((text, index) => {
+        const embedding = normalizeEmbedding(result.embeddings[index] ?? [])
+        embeddingsByText.set(text, embedding)
+        if (redisCache) {
+          void redisCache.set(this.getModelId(), text, embedding)
+        }
+      })
+    }
+
+    return normalized.map((text) => (text ? (embeddingsByText.get(text) ?? []) : []))
   }
 }
 
-export function createDefaultEmbeddings(): ProviderEmbeddings {
-  return new ProviderEmbeddings()
+let defaultEmbeddings: ProviderEmbeddings | null = null
+
+export function getDefaultEmbeddings(): ProviderEmbeddings {
+  if (!defaultEmbeddings) {
+    defaultEmbeddings = new ProviderEmbeddings()
+  }
+
+  return defaultEmbeddings
+}
+
+export function resetDefaultEmbeddingsForTests(): void {
+  defaultEmbeddings = null
 }