@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/memory/rerank.service.ts

@@ -0,0 +1,209 @@
+import { Context, Effect, Layer } from 'effect'
+import * as Schema from 'effect/Schema'
+import { z } from 'zod'
+
+import { OPENROUTER_FAST_RERANK_MODEL_ID } from '../../config/model-constants'
+import { RuntimeConfigServiceTag } from '../../effect/services'
+import { toValidationError } from '../../effect/zod'
+import { normalizeDirectOpenRouterModelId, resolveOpenRouterApiKey } from '../../openrouter/direct-provider'
+import type { ResolvedLotaRuntimeConfig } from '../../runtime/runtime-config'
+
+const OPENROUTER_RERANK_URL = 'https://openrouter.ai/api/v1/rerank' as const
+
+class RerankServiceError extends Schema.TaggedErrorClass<RerankServiceError>()('RerankServiceError', {
+  operation: Schema.String,
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function toRerankServiceError(operation: string, message: string, cause: unknown): RerankServiceError {
+  return new RerankServiceError({ operation, message, cause })
+}
+
+function tryRerankPromise<A>(
+  operation: string,
+  message: string,
+  thunk: () => PromiseLike<A> | A,
+): Effect.Effect<A, RerankServiceError> {
+  return Effect.tryPromise({
+    try: () => Promise.resolve(thunk()),
+    catch: (cause) => toRerankServiceError(operation, message, cause),
+  })
+}
+
+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 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
+}
+
+export function makeRerankService(config: ResolvedLotaRuntimeConfig) {
+  function readConfiguredRerankModelId(): string | null {
+    const configured = config.memory.rerankerModelId
+    if (typeof configured !== 'string') return null
+    const trimmed = configured.trim()
+    return trimmed.length > 0 ? trimmed : 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
+  }
+
+  return {
+    rerankDocuments(params: { query: string; documents: RerankDocument[]; topN?: number; modelId?: string }) {
+      return Effect.gen(function* () {
+        if (params.documents.length === 0) {
+          return { modelId: resolveRerankModelId(params.modelId), results: [] as RerankResultItem[] }
+        }
+
+        const apiKey = resolveOpenRouterApiKey(config.aiGateway.openRouterApiKey)
+        const modelId = resolveRerankModelId(params.modelId)
+        const topN = clampTopN(params.topN, params.documents.length)
+
+        const response = yield* tryRerankPromise('fetch-rerank', 'Failed to fetch rerank results.', () =>
+          Bun.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 = yield* tryRerankPromise(
+          'read-rerank-response',
+          'Failed to read rerank response body.',
+          () => response.text(),
+        )
+
+        if (!response.ok) {
+          return yield* new RerankServiceError({
+            operation: 'fetch-rerank',
+            message: `OpenRouter rerank failed (${response.status}): ${responseText}`,
+            cause: responseText,
+          })
+        }
+
+        const payload = yield* Schema.decodeUnknownEffect(Schema.UnknownFromJsonString)(responseText).pipe(
+          Effect.mapError((cause) =>
+            toRerankServiceError(
+              'parse-rerank-json',
+              `Rerank service returned invalid JSON (status ${response.status}): ${responseText.slice(0, 200)}`,
+              cause,
+            ),
+          ),
+        )
+
+        const parsedResponse = RerankResponseSchema.safeParse(payload)
+        if (!parsedResponse.success) {
+          return yield* toValidationError(parsedResponse.error, 'Rerank service returned an invalid response payload')
+        }
+        const parsed = parsedResponse.data
+        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 class RerankServiceTag extends Context.Service<RerankServiceTag, ReturnType<typeof makeRerankService>>()(
+  'RerankService',
+) {}
+
+export const RerankServiceLive = Layer.effect(
+  RerankServiceTag,
+  Effect.gen(function* () {
+    const runtimeConfig = yield* RuntimeConfigServiceTag
+    return makeRerankService(runtimeConfig)
+  }),
+)

package/src/services/monitoring-window.service.ts

@@ -1,86 +1,108 @@
 import type { MonitoringWindowConfig } from '@lota-sdk/shared'
+import { Context, Effect, Layer } from 'effect'
 
-import { planSchedulerService } from './plan-scheduler.service'
+import { ValidationError } from '../effect/errors'
+import type { makePlanSchedulerService } from './plan/plan-scheduler.service'
+import { PlanSchedulerServiceTag } from './plan/plan-scheduler.service'
 
-class MonitoringWindowService {
-  computeCheckTimes(config: MonitoringWindowConfig): { offsetMs: number; intervalMs: number }[] {
-    const times: { offsetMs: number; intervalMs: number }[] = []
-    let currentInterval = config.initialIntervalMs
-    let elapsed = 0
-    while (elapsed < config.durationMs) {
-      times.push({ offsetMs: elapsed, intervalMs: currentInterval })
-      elapsed += currentInterval
-      currentInterval = Math.min(currentInterval / config.decayFactor, config.maxIntervalMs)
-    }
-    return times
+function computeCheckTimes(config: MonitoringWindowConfig): { offsetMs: number; intervalMs: number }[] {
+  const times: { offsetMs: number; intervalMs: number }[] = []
+  let currentInterval = config.initialIntervalMs
+  let elapsed = 0
+  while (elapsed < config.durationMs) {
+    times.push({ offsetMs: elapsed, intervalMs: currentInterval })
+    elapsed += currentInterval
+    currentInterval = Math.min(currentInterval / config.decayFactor, config.maxIntervalMs)
   }
+  return times
+}
 
-  async startMonitoringWindow(params: {
-    runId: string
-    nodeId: string
-    config: MonitoringWindowConfig
-    organizationId: string
-    threadId: string
-  }): Promise<void> {
-    await planSchedulerService.createSchedule({
-      organizationId: params.organizationId,
-      threadId: params.threadId,
-      runId: params.runId,
-      nodeId: params.nodeId,
-      scheduleSpec: {
-        type: 'monitoring',
-        intervalMs: params.config.initialIntervalMs,
-        maxFires: this.computeCheckTimes(params.config).length,
-        missedPolicy: 'skip',
-      },
-    })
-  }
+function evaluateTerminationEffect(params: {
+  samples: unknown[]
+  config: MonitoringWindowConfig
+}): Effect.Effect<boolean, ValidationError> {
+  if (!params.config.earlyTermination) return Effect.succeed(false)
+  if (params.samples.length < params.config.earlyTermination.minSamples) return Effect.succeed(false)
 
-  evaluateTermination(params: { samples: unknown[]; config: MonitoringWindowConfig }): boolean {
-    if (!params.config.earlyTermination) return false
-    if (params.samples.length < params.config.earlyTermination.minSamples) return false
+  const { condition, minSamples } = params.config.earlyTermination
+  const numericSamples = params.samples
+    .map((s) =>
+      typeof s === 'number'
+        ? s
+        : typeof s === 'object' && s !== null && 'value' in s
+          ? Number((s as Record<string, unknown>).value)
+          : NaN,
+    )
+    .filter((n) => !isNaN(n))
 
-    const { condition, minSamples } = params.config.earlyTermination
-    const numericSamples = params.samples
-      .map((s) =>
-        typeof s === 'number'
-          ? s
-          : typeof s === 'object' && s !== null && 'value' in s
-            ? Number((s as Record<string, unknown>).value)
-            : NaN,
-      )
-      .filter((n) => !isNaN(n))
+  if (numericSamples.length === 0) return Effect.succeed(false)
 
-    // No numeric data to evaluate against — don't terminate
-    if (numericSamples.length === 0) return false
+  if (condition === 'stable') {
+    const recent = numericSamples.slice(-minSamples)
+    if (recent.length < 2) return Effect.succeed(false)
+    const mean = recent.reduce((a, b) => a + b, 0) / recent.length
+    const variance = recent.reduce((a, b) => a + (b - mean) ** 2, 0) / recent.length
+    const cv = mean !== 0 ? Math.sqrt(variance) / Math.abs(mean) : 0
+    return Effect.succeed(cv < 0.1)
+  }
 
-    if (condition === 'stable') {
-      const recent = numericSamples.slice(-minSamples)
-      if (recent.length < 2) return false
-      const mean = recent.reduce((a, b) => a + b, 0) / recent.length
-      const variance = recent.reduce((a, b) => a + (b - mean) ** 2, 0) / recent.length
-      const cv = mean !== 0 ? Math.sqrt(variance) / Math.abs(mean) : 0
-      return cv < 0.1
-    }
+  const thresholdMatch = condition.match(/^threshold:(\d+(?:\.\d+)?)$/)
+  if (thresholdMatch?.[1]) {
+    const threshold = parseFloat(thresholdMatch[1])
+    return Effect.succeed(numericSamples.some((v) => v >= threshold))
+  }
 
-    const thresholdMatch = condition.match(/^threshold:(\d+(?:\.\d+)?)$/)
-    if (thresholdMatch?.[1]) {
-      const threshold = parseFloat(thresholdMatch[1])
-      return numericSamples.some((v) => v >= threshold)
-    }
+  if (condition === 'trend:declining') {
+    const recent = numericSamples.slice(-minSamples)
+    return Effect.succeed(recent.length >= 2 && recent.every((v, i) => i === 0 || v <= (recent[i - 1] ?? v)))
+  }
 
-    if (condition === 'trend:declining') {
-      const recent = numericSamples.slice(-minSamples)
-      return recent.length >= 2 && recent.every((v, i) => i === 0 || v <= (recent[i - 1] ?? v))
-    }
+  if (condition === 'trend:increasing') {
+    const recent = numericSamples.slice(-minSamples)
+    return Effect.succeed(recent.length >= 2 && recent.every((v, i) => i === 0 || v >= (recent[i - 1] ?? v)))
+  }
 
-    if (condition === 'trend:increasing') {
-      const recent = numericSamples.slice(-minSamples)
-      return recent.length >= 2 && recent.every((v, i) => i === 0 || v >= (recent[i - 1] ?? v))
-    }
+  return Effect.fail(new ValidationError({ message: `Unknown monitoring termination condition: ${condition}` }))
+}
 
-    throw new Error(`Unknown monitoring termination condition: ${condition}`)
+export function makeMonitoringWindowService(planSchedulerService: ReturnType<typeof makePlanSchedulerService>) {
+  return {
+    computeCheckTimes,
+    startMonitoringWindow(params: {
+      runId: string
+      nodeId: string
+      config: MonitoringWindowConfig
+      organizationId: string
+      threadId: string
+    }) {
+      return Effect.asVoid(
+        planSchedulerService.createSchedule({
+          organizationId: params.organizationId,
+          threadId: params.threadId,
+          runId: params.runId,
+          nodeId: params.nodeId,
+          scheduleSpec: {
+            type: 'monitoring',
+            intervalMs: params.config.initialIntervalMs,
+            maxFires: computeCheckTimes(params.config).length,
+            missedPolicy: 'skip',
+          },
+        }),
+      )
+    },
+    evaluateTermination: evaluateTerminationEffect,
   }
 }
 
-export const monitoringWindowService = new MonitoringWindowService()
+export class MonitoringWindowServiceTag extends Context.Service<
+  MonitoringWindowServiceTag,
+  ReturnType<typeof makeMonitoringWindowService>
+>()('MonitoringWindowService') {}
+
+export const MonitoringWindowServiceLive = Layer.effect(
+  MonitoringWindowServiceTag,
+  Effect.gen(function* () {
+    const planSchedulerService = yield* PlanSchedulerServiceTag
+    return makeMonitoringWindowService(planSchedulerService)
+  }),
+)

package/src/services/mutating-approval.service.ts

@@ -1,18 +1,13 @@
-import type { RecordIdRef } from '../db/record-id'
+import { Context, Effect, Layer } from 'effect'
+
 import { ensureRecordId } from '../db/record-id'
 import { TABLES } from '../db/tables'
 import { extractMessageText } from '../runtime/thread-chat-helpers'
-import { threadMessageService } from './thread-message.service'
+import type { makeThreadMessageService } from './thread/thread-message.service'
+import { ThreadMessageServiceTag } from './thread/thread-message.service'
 
 const APPROVAL_VERIFICATION_MESSAGE_WINDOW = 20
 
-type VerifyMutatingApproval = (params: {
-  threadId: string
-  approvalReason: string
-  approvalToken: string
-  approvalMessageId?: string
-}) => Promise<{ ok: true } | { ok: false; reason: string }>
-
 function extractQuotedValue(value: string): string {
   const trimmed = value.trim()
   if (
@@ -58,50 +53,64 @@ function messageContainsExactApproval(messageText: string, approvalToken: string
   return extracted.token === approvalToken && extracted.reason === approvalReason
 }
 
-async function verifyMutatingApprovalForThread(
-  threadId: RecordIdRef,
-  params: { approvalReason: string; approvalToken: string; approvalMessageId?: string },
-): Promise<{ ok: true } | { ok: false; reason: string }> {
-  const token = extractQuotedValue(params.approvalToken)
-  const reason = extractQuotedValue(params.approvalReason)
-  const approvalMessageId = params.approvalMessageId?.trim()
-  if (!token || !reason) {
-    return { ok: false, reason: 'Mutating approval metadata is incomplete.' }
-  }
-  if (params.approvalMessageId !== undefined && !approvalMessageId) {
-    return { ok: false, reason: 'approvalMessageId cannot be empty when provided.' }
-  }
-
-  const recentMessages = await threadMessageService.listRecentMessages(threadId, APPROVAL_VERIFICATION_MESSAGE_WINDOW)
-  const userMessages = recentMessages.filter((message) => message.role === 'user')
-  if (userMessages.length === 0) {
-    return { ok: false, reason: 'No user message history available to verify mutating approval.' }
-  }
-
-  const latestUserMessage = userMessages.at(-1)
-  if (!latestUserMessage) {
-    return { ok: false, reason: 'Latest user message was not found for mutating approval verification.' }
-  }
-
-  if (approvalMessageId && approvalMessageId !== latestUserMessage.id) {
-    return {
-      ok: false,
-      reason:
-        'approvalMessageId must reference the latest user message for mutating approval verification; stale approvals are not accepted.',
-    }
+export function makeMutatingApprovalService(threadMessageService: ReturnType<typeof makeThreadMessageService>) {
+  return (params: { threadId: string; approvalReason: string; approvalToken: string; approvalMessageId?: string }) => {
+    const threadId = ensureRecordId(params.threadId, TABLES.THREAD)
+    return Effect.gen(function* () {
+      const token = extractQuotedValue(params.approvalToken)
+      const reason = extractQuotedValue(params.approvalReason)
+      const approvalMessageId = params.approvalMessageId?.trim()
+      if (!token || !reason) {
+        return { ok: false as const, reason: 'Mutating approval metadata is incomplete.' }
+      }
+      if (params.approvalMessageId !== undefined && !approvalMessageId) {
+        return { ok: false as const, reason: 'approvalMessageId cannot be empty when provided.' }
+      }
+
+      const recentMessages = yield* threadMessageService.listRecentMessages(
+        threadId,
+        APPROVAL_VERIFICATION_MESSAGE_WINDOW,
+      )
+      const userMessages = recentMessages.filter((message) => message.role === 'user')
+      if (userMessages.length === 0) {
+        return { ok: false as const, reason: 'No user message history available to verify mutating approval.' }
+      }
+
+      const latestUserMessage = userMessages.at(-1)
+      if (!latestUserMessage) {
+        return { ok: false as const, reason: 'Latest user message was not found for mutating approval verification.' }
+      }
+
+      if (approvalMessageId && approvalMessageId !== latestUserMessage.id) {
+        return {
+          ok: false as const,
+          reason:
+            'approvalMessageId must reference the latest user message for mutating approval verification; stale approvals are not accepted.',
+        }
+      }
+
+      if (!messageContainsExactApproval(extractMessageText(latestUserMessage), token, reason)) {
+        return {
+          ok: false as const,
+          reason:
+            'Referenced approval message must contain exact approval fields: "Approval Token: <token>" and "Approval Reason: <reason>".',
+        }
+      }
+
+      return { ok: true as const }
+    })
   }
-
-  if (!messageContainsExactApproval(extractMessageText(latestUserMessage), token, reason)) {
-    return {
-      ok: false,
-      reason:
-        'Referenced approval message must contain exact approval fields: "Approval Token: <token>" and "Approval Reason: <reason>".',
-    }
-  }
-
-  return { ok: true }
 }
 
-export const verifyMutatingApproval: VerifyMutatingApproval = async (params) => {
-  return verifyMutatingApprovalForThread(ensureRecordId(params.threadId, TABLES.THREAD), params)
-}
+export class MutatingApprovalServiceTag extends Context.Service<
+  MutatingApprovalServiceTag,
+  ReturnType<typeof makeMutatingApprovalService>
+>()('MutatingApprovalService') {}
+
+export const MutatingApprovalServiceLive = Layer.effect(
+  MutatingApprovalServiceTag,
+  Effect.gen(function* () {
+    const threadMessageService = yield* ThreadMessageServiceTag
+    return makeMutatingApprovalService(threadMessageService)
+  }),
+)