@lota-sdk/core 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -32,7 +32,7 @@
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.4.6",
+    "@lota-sdk/shared": "0.4.8",
     "@mendable/firecrawl-js": "^4.18.1",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.145",

package/src/config/model-constants.ts

@@ -2,6 +2,7 @@ export {
   AI_GATEWAY_REASONING_SUMMARY_LEVEL,
   OPENAI_HIGH_REASONING_PROVIDER_OPTIONS,
   OPENAI_REASONING_MODEL_ID,
+  OPENROUTER_FAST_RERANK_MODEL_ID,
   OPENROUTER_FAST_REASONING_MODEL_ID,
   OPENROUTER_GEMINI_FLASH_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,

package/src/create-runtime.ts

@@ -63,6 +63,8 @@ import type { recentActivityTitleService } from './services/recent-activity-titl
 import { recentActivityTitleService as recentActivityTitleServiceSingleton } from './services/recent-activity-title.service'
 import type { recentActivityService } from './services/recent-activity.service'
 import { recentActivityService as recentActivityServiceSingleton } from './services/recent-activity.service'
+import type { rerankService } from './services/rerank.service'
+import { rerankService as rerankServiceSingleton } from './services/rerank.service'
 import {
   configureSocialChatHistory,
   socialChatHistoryService as socialChatHistoryServiceSingleton,
@@ -134,6 +136,7 @@ export interface LotaRuntime {
     documentChunkService: typeof documentChunkService
     generatedDocumentStorageService: typeof generatedDocumentStorageService
     memoryService: typeof memoryService
+    rerankService: typeof rerankService
     verifyMutatingApproval: typeof verifyMutatingApproval
     organizationService: typeof organizationService
     organizationMemberService: typeof organizationMemberService
@@ -403,6 +406,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
         documentChunkService: documentChunkServiceSingleton,
         generatedDocumentStorageService: generatedDocumentStorageServiceSingleton,
         memoryService: memoryServiceSingleton,
+        rerankService: rerankServiceSingleton,
         verifyMutatingApproval: verifyMutatingApprovalSingleton,
         organizationService: organizationServiceSingleton,
         organizationMemberService: organizationMemberServiceSingleton,

package/src/embeddings/provider.ts

@@ -1,7 +1,11 @@
 import { embed, embedMany } from 'ai'
 
-import { aiGatewayEmbeddingModel } from '../ai-gateway/ai-gateway'
 import { getEmbeddingCache } from '../ai/embedding-cache'
+import {
+  getDirectOpenRouterProvider,
+  normalizeDirectOpenRouterModelId,
+  resetDirectOpenRouterProviderForTests,
+} from '../openrouter/direct-provider'
 import { getRuntimeConfig } from '../runtime/runtime-config'
 
 const SUPPORTED_EMBEDDING_PREFIXES = ['openai/', 'openrouter/'] as const
@@ -30,7 +34,7 @@ function resolveEmbeddingModel(modelId: string) {
     )
   }
 
-  return aiGatewayEmbeddingModel(normalized)
+  return getDirectOpenRouterProvider().embeddingModel(normalizeDirectOpenRouterModelId(normalized))
 }
 
 function normalizeEmbedding(embedding: readonly number[]): number[] {
@@ -153,4 +157,5 @@ export function getDefaultEmbeddings(): ProviderEmbeddings {
 
 export function resetDefaultEmbeddingsForTests(): void {
   defaultEmbeddings = null
+  resetDirectOpenRouterProviderForTests()
 }

package/src/openrouter/direct-provider.ts

@@ -0,0 +1,53 @@
+import { createOpenAI } from '@ai-sdk/openai'
+
+import { getRuntimeConfig } from '../runtime/runtime-config'
+
+const DIRECT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1' as const
+const OPENROUTER_MODEL_PREFIX = 'openrouter/' as const
+
+let directOpenRouterProvider: ReturnType<typeof createOpenAI> | null = null
+let directOpenRouterProviderKey: string | null = null
+
+function readConfiguredOpenRouterApiKey(): string | null {
+  try {
+    return getRuntimeConfig().aiGateway.openRouterApiKey?.trim() || null
+  } catch {
+    return null
+  }
+}
+
+export function resolveOpenRouterApiKey(): string {
+  const configured = readConfiguredOpenRouterApiKey()
+  if (configured) return configured
+
+  const envKey = process.env.OPENROUTER_API_KEY?.trim()
+  if (envKey) return envKey
+
+  throw new Error('Missing OpenRouter API key. Set aiGateway.openRouterApiKey or OPENROUTER_API_KEY.')
+}
+
+export function normalizeDirectOpenRouterModelId(modelId: string): string {
+  const normalized = modelId.trim()
+  if (!normalized) {
+    throw new Error('OpenRouter model id is required.')
+  }
+
+  return normalized.startsWith(OPENROUTER_MODEL_PREFIX) ? normalized.slice(OPENROUTER_MODEL_PREFIX.length) : normalized
+}
+
+export function getDirectOpenRouterProvider() {
+  const apiKey = resolveOpenRouterApiKey()
+  if (directOpenRouterProvider && directOpenRouterProviderKey === apiKey) {
+    return directOpenRouterProvider
+  }
+
+  directOpenRouterProvider = createOpenAI({ baseURL: DIRECT_OPENROUTER_BASE_URL, apiKey })
+  directOpenRouterProviderKey = apiKey
+
+  return directOpenRouterProvider
+}
+
+export function resetDirectOpenRouterProviderForTests(): void {
+  directOpenRouterProvider = null
+  directOpenRouterProviderKey = null
+}

package/src/runtime/execution-plan.ts

@@ -10,6 +10,8 @@ const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - During plan-triggered turns, use the dedicated result-submission tool.
 - Treat the active execution runs in <execution-plan-state> as authoritative for whether a plan already exists.
 - If contracts or criteria materially change, replace the plan.
+- Never append status labels in brackets to plan or node titles (e.g. "[blocked]", "[failed]", "[running]"). Use plain prose to describe status.
+- Never expose raw run IDs (planRun:..., Run: UUID) in user-facing messages. Reference plans by their title only.
 </execution-plan-protocol>`
 
 function toExecutionPlanPromptSummaries(plans: SerializableExecutionPlan[]): ExecutionPlanPromptSummary[] {

package/src/runtime/runtime-config.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 
 import type { CoreThreadProfile } from '../config/agent-defaults'
 import type { AgentFactory, AgentRuntimeConfigProvider, AgentToolBuilder } from '../config/agent-types'
+import { OPENROUTER_FAST_RERANK_MODEL_ID } from '../config/model-constants'
 import type { LotaThreadConfig, ThreadBootstrapWelcomeConfig } from '../config/thread-defaults'
 import type { RecordIdRef } from '../db/record-id'
 import type { NotificationService } from '../services/notification.service'
@@ -216,6 +217,9 @@ const agentsConfigSchema = z
     }
   })
 
+export const MemoryRerankerStrategySchema = z.enum(['helper-model', 'rerank'])
+export type MemoryRerankerStrategy = z.infer<typeof MemoryRerankerStrategySchema>
+
 export const LotaRuntimeConfigSchema = z.object({
   database: z.object({
     url: z.string().trim().min(1),
@@ -228,6 +232,7 @@ export const LotaRuntimeConfigSchema = z.object({
     url: z.string().trim().min(1),
     key: z.string().trim().min(1),
     embeddingModel: z.string().trim().min(1).default('openai/text-embedding-3-small'),
+    openRouterApiKey: z.string().trim().min(1).optional(),
   }),
   s3: z.object({
     endpoint: z.string().trim().min(1),
@@ -250,8 +255,15 @@ export const LotaRuntimeConfigSchema = z.object({
     .object({
       searchK: z.coerce.number().int().positive().default(6),
       embeddingCacheTtlSeconds: z.coerce.number().int().positive().default(7200),
+      rerankerStrategy: MemoryRerankerStrategySchema.default('rerank'),
+      rerankerModelId: z.string().trim().min(1).default(OPENROUTER_FAST_RERANK_MODEL_ID),
     })
-    .default({ searchK: 6, embeddingCacheTtlSeconds: 7200 }),
+    .default({
+      searchK: 6,
+      embeddingCacheTtlSeconds: 7200,
+      rerankerStrategy: 'rerank',
+      rerankerModelId: OPENROUTER_FAST_RERANK_MODEL_ID,
+    }),
   threads: threadConfigSchema.default({}),
   agents: agentsConfigSchema,
   toolProviders: z.custom<Record<string, unknown>>(isToolProviderRecord).optional(),
@@ -288,6 +300,7 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'AI_GATEWAY_URL',
   'AI_GATEWAY_KEY',
   'AI_EMBEDDING_MODEL',
+  'OPENROUTER_API_KEY',
   'S3_ENDPOINT',
   'S3_BUCKET',
   'S3_REGION',
@@ -298,6 +311,8 @@ export const LOTA_RUNTIME_ENV_KEYS = Object.freeze([
   'FIRECRAWL_API_BASE_URL',
   'LOG_LEVEL',
   'MEMORY_SEARCH_K',
+  'MEMORY_RERANKER_STRATEGY',
+  'MEMORY_RERANKER_MODEL_ID',
 ])
 
 let runtimeConfig: ResolvedLotaRuntimeConfig | null = null

package/src/services/index.ts

@@ -16,6 +16,7 @@ export * from './notification.service'
 export * from './ownership-dispatcher.service'
 export * from './organization-member.service'
 export * from './organization.service'
+export * from './rerank.service'
 export * from './plan-coordination.service'
 export * from './plan-cycle.service'
 export * from './plan-deadline.service'

package/src/services/memory.service.ts

@@ -23,11 +23,13 @@ import {
   executeScopedRetrieval,
   scopedRetrievalToMap,
 } from '../runtime/retrieval-adapters'
+import type { MemoryRerankerStrategy } from '../runtime/runtime-config'
 import { getRuntimeConfig } from '../runtime/runtime-config'
 import { createMemoryRerankerAgent, MEMORY_RERANKER_PROMPT } from '../system-agents/memory-reranker.agent'
 import { createOrgMemoryAgent, ORG_MEMORY_PROMPT } from '../system-agents/memory.agent'
 import { clampImportance, compactWhitespace, truncateText } from '../utils/string'
 import { formatMemoryResults, formatRerankedResults, getCandidateLimit } from './memory-utils'
+import { rerankService } from './rerank.service'
 
 const ORG_MEMORY_TYPE = 'fact'
 const RERANK_CANDIDATE_MAX_CHARS = 500
@@ -47,6 +49,7 @@ const ONBOARDING_MEMORY_EXTRACTION_PROMPT =
   'Onboarding mode is active. Extract multiple concrete startup facts from user-provided context: company mission, product capabilities, customer segments, pricing, traction, go-to-market plans, roadmap, team composition, technical stack, risks, and referenced URLs. Prefer one fact per concrete claim.'
 const DIRECT_MEMORY_ASSESSMENT_PROMPT =
   'The user is submitting a direct memory candidate. Keep the wording faithful. Return one fact only when the statement is durable enough for memory; otherwise return no facts.'
+const RERANK_SECTION_TITLE = 'Most relevant memories'
 
 const helperModelRuntime = createHelperModelRuntime()
 
@@ -234,26 +237,9 @@ class MemoryService {
     if (candidates.length === 0) return null
 
     try {
-      return await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-reranker',
-        createAgent: createMemoryRerankerAgent,
-        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
-        messages: [
-          {
-            role: 'user',
-            content: JSON.stringify({
-              query,
-              maxItems,
-              candidates: candidates.map((candidate) => ({
-                id: candidate.id,
-                text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
-                score: candidate.score,
-              })),
-            }),
-          },
-        ],
-        schema: MemoryRerankOutputSchema,
-      })
+      return this.getRerankerStrategy() === 'rerank'
+        ? await this.rerankCandidatesWithRerankService(query, candidates, maxItems)
+        : await this.rerankCandidatesWithHelper(query, candidates, maxItems)
     } catch (error) {
       aiLogger.warn`Memory reranker failed: ${error}`
       return null
@@ -271,33 +257,117 @@ class MemoryService {
     if (flattened.length === 0 || flattened.length <= maxItems) return null
 
     try {
-      return await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-reranker-multi-scope',
-        createAgent: createMemoryRerankerAgent,
-        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
-        messages: [
-          {
-            role: 'user',
-            content: JSON.stringify({
-              query,
-              maxItems,
-              candidates: flattened.map((candidate) => ({
-                id: candidate.id,
-                text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
-                score: candidate.score,
-                scope: candidate.scopeTag,
-              })),
-            }),
-          },
-        ],
-        schema: MemoryRerankOutputSchema,
-      })
+      return this.getRerankerStrategy() === 'rerank'
+        ? await this.rerankCandidatesMultiScopeWithRerankService(query, flattened, maxItems)
+        : await this.rerankCandidatesMultiScopeWithHelper(query, flattened, maxItems)
     } catch (error) {
       aiLogger.warn`Multi-scope memory reranker failed: ${error}`
       return null
     }
   }
 
+  private getRerankerStrategy(): MemoryRerankerStrategy {
+    return getRuntimeConfig().memory.rerankerStrategy
+  }
+
+  private buildRerankOutput(ids: string[], title = RERANK_SECTION_TITLE): MemoryRerankOutput {
+    return { sections: [{ title, items: ids.map((id) => ({ id, relevance: '' })) }] }
+  }
+
+  private async rerankCandidatesWithHelper(
+    query: string,
+    candidates: MemorySearchResult[],
+    maxItems: number,
+  ): Promise<MemoryRerankOutput> {
+    return await helperModelRuntime.generateHelperStructured({
+      tag: 'memory-reranker',
+      createAgent: createMemoryRerankerAgent,
+      defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
+      messages: [
+        {
+          role: 'user',
+          content: JSON.stringify({
+            query,
+            maxItems,
+            candidates: candidates.map((candidate) => ({
+              id: candidate.id,
+              text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
+              score: candidate.score,
+            })),
+          }),
+        },
+      ],
+      schema: MemoryRerankOutputSchema,
+    })
+  }
+
+  private async rerankCandidatesWithRerankService(
+    query: string,
+    candidates: MemorySearchResult[],
+    maxItems: number,
+  ): Promise<MemoryRerankOutput> {
+    const reranked = await rerankService.rerankDocuments({
+      query,
+      topN: maxItems,
+      documents: candidates.map((candidate) => ({
+        id: candidate.id,
+        text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
+      })),
+    })
+
+    return this.buildRerankOutput(reranked.results.map((item) => item.id))
+  }
+
+  private async rerankCandidatesMultiScopeWithHelper(
+    query: string,
+    flattenedCandidates: Array<MemorySearchResult & { scopeTag: string }>,
+    maxItems: number,
+  ): Promise<MemoryRerankOutput> {
+    return await helperModelRuntime.generateHelperStructured({
+      tag: 'memory-reranker-multi-scope',
+      createAgent: createMemoryRerankerAgent,
+      defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
+      messages: [
+        {
+          role: 'user',
+          content: JSON.stringify({
+            query,
+            maxItems,
+            candidates: flattenedCandidates.map((candidate) => ({
+              id: candidate.id,
+              text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
+              score: candidate.score,
+              scope: candidate.scopeTag,
+            })),
+          }),
+        },
+      ],
+      schema: MemoryRerankOutputSchema,
+    })
+  }
+
+  private async rerankCandidatesMultiScopeWithRerankService(
+    query: string,
+    flattenedCandidates: Array<MemorySearchResult & { scopeTag: string }>,
+    maxItems: number,
+  ): Promise<MemoryRerankOutput> {
+    const reranked = await rerankService.rerankDocuments({
+      query,
+      topN: maxItems,
+      documents: flattenedCandidates.map((candidate) => ({
+        id: candidate.id,
+        text: this.truncateCandidateText(
+          `${this.buildRerankerCandidateText(candidate)}\n\nScope: ${candidate.scopeTag}`,
+        ),
+      })),
+    })
+
+    return this.buildRerankOutput(
+      reranked.results.map((item) => item.id),
+      'Top matches across memory scopes',
+    )
+  }
+
   private async searchMemories({
     query,
     memory,

package/src/services/rerank.service.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod'
+
+import { OPENROUTER_FAST_RERANK_MODEL_ID } from '../config/model-constants'
+import { normalizeDirectOpenRouterModelId, resolveOpenRouterApiKey } from '../openrouter/direct-provider'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+
+const OPENROUTER_RERANK_URL = 'https://openrouter.ai/api/v1/rerank' as const
+
+const RerankResponseSchema = z
+  .object({
+    model: z.string().optional(),
+    results: z.array(
+      z
+        .object({
+          index: z.number().int().nonnegative().optional(),
+          relevance_score: z.number().optional(),
+          document: z.union([z.string(), z.object({ text: z.string().optional() }).passthrough()]).optional(),
+        })
+        .passthrough(),
+    ),
+    usage: z.object({ search_units: z.number().optional(), cost: z.number().optional() }).passthrough().optional(),
+  })
+  .passthrough()
+
+export interface RerankDocument {
+  id: string
+  text: string
+}
+
+export interface RerankResultItem extends RerankDocument {
+  index: number
+  relevanceScore: number | null
+}
+
+export interface RerankUsage {
+  searchUnits?: number
+  cost?: number
+}
+
+export interface RerankResult {
+  modelId: string
+  results: RerankResultItem[]
+  usage?: RerankUsage
+}
+
+function clampTopN(topN: number | undefined, total: number): number {
+  if (!Number.isFinite(topN)) return total
+  return Math.max(1, Math.min(total, Math.trunc(topN as number)))
+}
+
+function readConfiguredRerankModelId(): string | null {
+  try {
+    return getRuntimeConfig().memory.rerankerModelId.trim()
+  } catch {
+    return null
+  }
+}
+
+function resolveRerankModelId(modelId?: string): string {
+  const explicit = modelId?.trim()
+  if (explicit) return normalizeDirectOpenRouterModelId(explicit)
+
+  const configured = readConfiguredRerankModelId()
+  if (configured) return normalizeDirectOpenRouterModelId(configured)
+
+  return OPENROUTER_FAST_RERANK_MODEL_ID
+}
+
+function matchRerankedDocument(
+  candidate: z.infer<typeof RerankResponseSchema>['results'][number],
+  documents: RerankDocument[],
+): RerankDocument | null {
+  if (typeof candidate.index === 'number' && candidate.index >= 0 && candidate.index < documents.length) {
+    return documents[candidate.index] ?? null
+  }
+
+  const text =
+    typeof candidate.document === 'string'
+      ? candidate.document
+      : typeof candidate.document?.text === 'string'
+        ? candidate.document.text
+        : null
+  if (!text) return null
+
+  return documents.find((document) => document.text === text) ?? null
+}
+
+class RerankService {
+  async rerankDocuments(params: {
+    query: string
+    documents: RerankDocument[]
+    topN?: number
+    modelId?: string
+  }): Promise<RerankResult> {
+    if (params.documents.length === 0) {
+      return { modelId: resolveRerankModelId(params.modelId), results: [] }
+    }
+
+    const apiKey = resolveOpenRouterApiKey()
+    const modelId = resolveRerankModelId(params.modelId)
+    const topN = clampTopN(params.topN, params.documents.length)
+
+    const response = await fetch(OPENROUTER_RERANK_URL, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: modelId,
+        query: params.query,
+        documents: params.documents.map((document) => document.text),
+        top_n: topN,
+      }),
+    })
+
+    const responseText = await response.text()
+    let payload: unknown = responseText
+    try {
+      payload = JSON.parse(responseText)
+    } catch {}
+
+    if (!response.ok) {
+      throw new Error(`OpenRouter rerank failed (${response.status}): ${responseText}`)
+    }
+
+    const parsed = RerankResponseSchema.parse(payload)
+    const seen = new Set<string>()
+    const results: RerankResultItem[] = []
+
+    for (const item of parsed.results) {
+      const matched = matchRerankedDocument(item, params.documents)
+      if (!matched || seen.has(matched.id)) continue
+      seen.add(matched.id)
+
+      results.push({
+        id: matched.id,
+        text: matched.text,
+        index: item.index ?? params.documents.findIndex((document) => document.id === matched.id),
+        relevanceScore: typeof item.relevance_score === 'number' ? item.relevance_score : null,
+      })
+
+      if (results.length >= topN) break
+    }
+
+    return {
+      modelId: parsed.model?.trim() || modelId,
+      results,
+      usage: parsed.usage
+        ? {
+            ...(parsed.usage.search_units !== undefined ? { searchUnits: parsed.usage.search_units } : {}),
+            ...(parsed.usage.cost !== undefined ? { cost: parsed.usage.cost } : {}),
+          }
+        : undefined,
+    }
+  }
+}
+
+export const rerankService = new RerankService()