@onmars/lunar-core 0.1.0

package/src/lib/logger.ts

@@ -0,0 +1,55 @@
+import { createWriteStream, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import pino from 'pino'
+
+export interface LoggerOptions {
+  level?: string
+  pretty?: boolean
+  name?: string
+  /** When set, logs are written to BOTH stdout and this file path */
+  logPath?: string
+}
+
+export function createLogger(options: LoggerOptions = {}): pino.Logger {
+  const { level = 'info', name = 'lunar', logPath } = options
+
+  // Bun doesn't support pino transports well — use basic pino
+  const pinoOpts: pino.LoggerOptions = {
+    name,
+    level,
+    // Readable timestamps in dev
+    timestamp: pino.stdTimeFunctions.isoTime,
+  }
+
+  if (logPath) {
+    // Ensure log directory exists
+    const dir = dirname(logPath)
+    mkdirSync(dir, { recursive: true })
+
+    const fileStream = createWriteStream(logPath, { flags: 'a' })
+    const streams = pino.multistream([
+      { stream: process.stdout, level: level as pino.Level },
+      { stream: fileStream, level: 'debug' as pino.Level },
+    ])
+    // Logger level must be the lowest of all stream levels so that
+    // debug messages reach the file even when stdout is at info.
+    pinoOpts.level = 'debug'
+    return pino.pino(pinoOpts, streams)
+  }
+
+  return pino(pinoOpts)
+}
+
+/** Mutable logger singleton — call reconfigureLogger() to update */
+export let log: pino.Logger = createLogger()
+
+/**
+ * Replace the shared logger instance with a new one.
+ *
+ * ESM `export let` creates a live binding — all modules that
+ * imported `{ log }` will see the new value on next access.
+ */
+export function reconfigureLogger(options: LoggerOptions): pino.Logger {
+  log = createLogger(options)
+  return log
+}

package/src/lib/memory-orchestrator.ts

@@ -0,0 +1,415 @@
+/**
+ * MemoryOrchestrator — Coordinates multiple MemoryProviders
+ *
+ * Implements MemoryProvider itself so it plugs into the existing Router
+ * as a single provider that internally manages many.
+ *
+ * Features:
+ * - Parallel recall across all providers
+ * - Deduplication of merged results (using dedup module)
+ * - Token budget enforcement
+ * - Lifecycle hooks (HookRunner) at every stage
+ * - Session lifecycle broadcast (onSessionEnd → all providers)
+ * - Health aggregation
+ * - Non-fatal: individual provider failures don't block others
+ */
+
+import type { Fact, MemoryProvider, MemoryResult } from '../types/memory'
+import type { HooksConfig } from './config-loader'
+import { createStrategy, type DedupConfig, deduplicate } from './dedup'
+import { type HookContext, HookRunner, type LLMFunction } from './hook-runner'
+import { log } from './logger'
+
+export interface OrchestratorConfig {
+  /** Max results after dedup. Default: 10 */
+  maxResults?: number
+  /** Dedup configuration */
+  dedup?: DedupConfig
+  /** Lifecycle hooks configuration (optional) */
+  hooks?: HooksConfig
+  /** Optional LLM function for intelligent hook actions (summarize, promote) */
+  llm?: LLMFunction
+}
+
+export class MemoryOrchestrator implements MemoryProvider {
+  readonly id = 'orchestrator'
+  readonly name = 'Memory Orchestrator'
+
+  private providers: MemoryProvider[] = []
+  private providersByName = new Map<string, MemoryProvider>()
+  private config: Required<Pick<OrchestratorConfig, 'maxResults' | 'dedup'>>
+  private strategy
+  private hookRunner?: HookRunner
+
+  constructor(config: OrchestratorConfig = {}) {
+    this.config = {
+      maxResults: config.maxResults ?? 10,
+      dedup: config.dedup ?? { strategy: 'adaptive', threshold: 0.85 },
+    }
+    this.strategy = createStrategy(this.config.dedup)
+
+    // HookRunner is created when hooks config is provided
+    // Providers are added later via addProvider(), so the runner
+    // is updated with the provider map after all providers are added.
+    if (config.hooks && Object.keys(config.hooks).length > 0) {
+      this.hookRunner = new HookRunner(config.hooks, this.providersByName, {
+        llm: config.llm,
+      })
+      log.info(
+        { events: this.hookRunner.activeEvents, hasLLM: !!config.llm },
+        'HookRunner initialized',
+      )
+    }
+  }
+
+  /**
+   * Add a provider to the orchestrator.
+   *
+   * @param provider - The memory provider
+   * @param configName - Optional config key name (defaults to provider.id)
+   */
+  addProvider(provider: MemoryProvider, configName?: string): void {
+    this.providers.push(provider)
+    this.providersByName.set(configName ?? provider.id, provider)
+
+    // Keep HookRunner's provider map in sync
+    if (this.hookRunner) {
+      this.hookRunner.updateProviders(this.providersByName)
+    }
+  }
+
+  /**
+   * Number of active providers.
+   */
+  get providerCount(): number {
+    return this.providers.length
+  }
+
+  /**
+   * List provider IDs.
+   */
+  get providerIds(): string[] {
+    return this.providers.map((p) => p.id)
+  }
+
+  /**
+   * Whether hooks are configured.
+   */
+  get hasHooks(): boolean {
+    return this.hookRunner !== undefined
+  }
+
+  /**
+   * Initialize all providers + run sessionStart hooks.
+   */
+  /** Episode ID for the current session (set by episode hook at sessionStart) */
+  private currentEpisodeId?: string
+  private currentSessionDate?: string
+  /** Diary results loaded at sessionStart — prepended to every recall */
+  private diaryResults: MemoryResult[] = []
+
+  async init(channel?: string): Promise<void> {
+    await Promise.allSettled(this.providers.map((p) => p.init?.() ?? Promise.resolve()))
+
+    // Run sessionStart hooks (episode creation, diary recall, context pre-loading)
+    if (this.hookRunner?.hasHooks('sessionStart')) {
+      const context: HookContext = {
+        messageCount: 0,
+        channel,
+        sessionDate: new Date().toISOString().split('T')[0],
+      }
+      const result = await this.hookRunner.run('sessionStart', context)
+      // Store episode info for session lifecycle
+      if (result.episodeId) {
+        this.currentEpisodeId = result.episodeId
+        this.currentSessionDate = result.sessionDate
+        log.info({ episodeId: result.episodeId }, 'Session linked to episode')
+      }
+      // Store diary results for injection into every recall
+      if (result.results?.length) {
+        this.diaryResults = result.results
+        log.info(
+          { count: this.diaryResults.length },
+          'Diary context loaded — will prepend to all recalls',
+        )
+      }
+    }
+  }
+
+  /** Get the current episode ID (if episode hook ran at sessionStart) */
+  get episodeId(): string | undefined {
+    return this.currentEpisodeId
+  }
+
+  /** Get the current session date */
+  get sessionDate(): string | undefined {
+    return this.currentSessionDate
+  }
+
+  /**
+   * Destroy all providers.
+   */
+  async destroy(): Promise<void> {
+    await Promise.allSettled(this.providers.map((p) => p.destroy?.() ?? Promise.resolve()))
+  }
+
+  /**
+   * Recall from ALL providers in parallel, deduplicate, and return merged results.
+   *
+   * Lifecycle:
+   *   1. beforeRecall hooks (can modify query)
+   *   2. Parallel recall from all providers
+   *   3. Merge, sort, filter, deduplicate
+   *   4. afterRecall hooks (can boost scores, modify results)
+   *   5. Return final results
+   *
+   * Individual provider failures are caught — other providers still contribute.
+   */
+  async recall(
+    query: string,
+    options?: { limit?: number; minScore?: number },
+  ): Promise<MemoryResult[]> {
+    const limit = options?.limit ?? this.config.maxResults
+    let activeQuery = query
+
+    // ── beforeRecall hooks ──
+    if (this.hookRunner?.hasHooks('beforeRecall')) {
+      const ctx: HookContext = { messageCount: 0, query: activeQuery }
+      await this.hookRunner.run('beforeRecall', ctx)
+      // Use modified query if hook changed it
+      if (ctx.query && ctx.query !== activeQuery) {
+        log.debug(
+          { original: activeQuery, modified: ctx.query },
+          'beforeRecall: query modified by hook',
+        )
+        activeQuery = ctx.query
+      }
+    }
+
+    // ── Parallel recall from all providers ──
+    const allResults = await Promise.allSettled(
+      this.providers.map(async (provider) => {
+        try {
+          const results = await provider.recall(activeQuery, options)
+          // Tag results with provider source if not already tagged
+          return results.map((r) => ({
+            ...r,
+            source: r.source || provider.id,
+          }))
+        } catch {
+          // Non-fatal — skip this provider
+          return [] as MemoryResult[]
+        }
+      }),
+    )
+
+    // Flatten results from all providers
+    const flat: MemoryResult[] = []
+    for (const result of allResults) {
+      if (result.status === 'fulfilled') {
+        flat.push(...result.value)
+      }
+    }
+
+    // Sort by score (highest first)
+    flat.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+
+    // Filter by minimum score
+    const minScore = options?.minScore ?? 0
+    const filtered = minScore > 0 ? flat.filter((r) => (r.score ?? 0) >= minScore) : flat
+
+    // Deduplicate
+    const { kept } = deduplicate(filtered, this.strategy, {
+      threshold: this.config.dedup.threshold ?? 0.85,
+      maxResults: limit,
+      textExtractor: (item: unknown) => (item as MemoryResult).content,
+    })
+
+    // ── afterRecall hooks (can boost scores, modify results) ──
+    if (this.hookRunner?.hasHooks('afterRecall')) {
+      const ctx: HookContext = { messageCount: 0, results: kept }
+      await this.hookRunner.run('afterRecall', ctx)
+      const afterResults = ctx.results ?? kept
+      // Prepend diary context (always first, deduplicated)
+      return this.prependDiary(afterResults)
+    }
+
+    // Prepend diary context (always first, deduplicated)
+    return this.prependDiary(kept)
+  }
+
+  /**
+   * Save facts to ALL providers that support it.
+   *
+   * Lifecycle:
+   *   1. beforeSave hooks (can modify/classify facts)
+   *   2. Parallel save to all providers
+   *   3. afterSave hooks (can trigger cross-promotion)
+   */
+  async save(facts: Array<{ content: string; [key: string]: unknown }>): Promise<void> {
+    let activeFacts = facts as Fact[]
+
+    // Auto-inject episodeId and sessionDate into all facts
+    if (this.currentEpisodeId || this.currentSessionDate) {
+      activeFacts = activeFacts.map((f) => ({
+        ...f,
+        ...(!f.episodeId && this.currentEpisodeId ? { episodeId: this.currentEpisodeId } : {}),
+        ...(!f.sessionDate && this.currentSessionDate
+          ? { sessionDate: this.currentSessionDate }
+          : {}),
+      })) as Fact[]
+    }
+
+    // ── beforeSave hooks ──
+    if (this.hookRunner?.hasHooks('beforeSave')) {
+      const ctx: HookContext = { messageCount: 0, facts: activeFacts }
+      await this.hookRunner.run('beforeSave', ctx)
+      activeFacts = ctx.facts ?? activeFacts
+    }
+
+    // ── Parallel save ──
+    await Promise.allSettled(this.providers.map((p) => p.save?.(activeFacts) ?? Promise.resolve()))
+
+    // ── afterSave hooks ──
+    if (this.hookRunner?.hasHooks('afterSave')) {
+      const ctx: HookContext = { messageCount: 0, facts: activeFacts }
+      await this.hookRunner.run('afterSave', ctx)
+    }
+  }
+
+  /**
+   * Broadcast session end to ALL providers + run lifecycle hooks.
+   *
+   * Lifecycle:
+   *   1. sessionEnd hooks (summarize → saves summary to provider)
+   *   2. onSessionEnd → all providers (each decides what to do)
+   *   3. afterSessionEnd hooks (promote → Engram facts → Brain)
+   */
+  async onSessionEnd(context: {
+    messages: Array<{ role: string; content: string }>
+    sessionSummary?: string
+    topics?: string[]
+    episodeId?: string
+    sessionDate?: string
+    channel?: string
+  }): Promise<void> {
+    const messageCount = context.messages.length
+
+    // ── sessionEnd hooks (e.g., summarize, journal, experience) ──
+    if (this.hookRunner?.hasHooks('sessionEnd')) {
+      const ctx: HookContext = {
+        messageCount,
+        messages: context.messages,
+        sessionSummary: context.sessionSummary,
+        topics: context.topics,
+        episodeId: context.episodeId,
+        sessionDate: context.sessionDate,
+        channel: context.channel,
+        createdFactIds: [],
+      }
+      const result = await this.hookRunner.run('sessionEnd', ctx)
+      // Pass updated values to downstream
+      if (result.sessionSummary) {
+        context.sessionSummary = result.sessionSummary
+      }
+      // Carry episodeId and createdFactIds forward
+      if (result.episodeId) context.episodeId = result.episodeId
+    }
+
+    // ── Broadcast to all providers ──
+    await Promise.allSettled(
+      this.providers.map((p) => p.onSessionEnd?.(context) ?? Promise.resolve()),
+    )
+
+    // ── afterSessionEnd hooks (e.g., reconcile, episodeClose) ──
+    if (this.hookRunner?.hasHooks('afterSessionEnd')) {
+      const ctx: HookContext = {
+        messageCount,
+        messages: context.messages,
+        sessionSummary: context.sessionSummary,
+        topics: context.topics,
+        episodeId: context.episodeId,
+        sessionDate: context.sessionDate,
+        channel: context.channel,
+        createdFactIds: [],
+      }
+      await this.hookRunner.run('afterSessionEnd', ctx)
+    }
+  }
+
+  /**
+   * Prepend diary results to recall output (deduplicating by content).
+   * Diary entries always come first with their original high scores.
+   */
+  private prependDiary(results: MemoryResult[]): MemoryResult[] {
+    if (this.diaryResults.length === 0) return results
+
+    // Build a set of diary content for dedup
+    const diaryContent = new Set(this.diaryResults.map((r) => r.content))
+
+    // Filter out any recall results that duplicate diary content
+    const filtered = results.filter((r) => !diaryContent.has(r.content))
+
+    return [...this.diaryResults, ...filtered]
+  }
+
+  /**
+   * Aggregate health from all providers.
+   */
+  async health(): Promise<{ ok: boolean; error?: string }> {
+    const results = await Promise.allSettled(
+      this.providers.map(async (p) => {
+        const h = await p.health()
+        return { id: p.id, ...h }
+      }),
+    )
+
+    const statuses = results
+      .filter(
+        (r): r is PromiseFulfilledResult<{ id: string; ok: boolean; error?: string }> =>
+          r.status === 'fulfilled',
+      )
+      .map((r) => r.value)
+
+    const allOk = statuses.every((s) => s.ok)
+    const errors = statuses.filter((s) => !s.ok).map((s) => `${s.id}: ${s.error}`)
+
+    return {
+      ok: allOk,
+      error: errors.length > 0 ? errors.join('; ') : undefined,
+    }
+  }
+
+  /**
+   * Merge agent instructions from all providers.
+   * Includes current episodeId for agents that save facts directly.
+   */
+  agentInstructions(): string {
+    const providerInstructions = this.providers
+      .map((p) => p.agentInstructions?.() ?? '')
+      .filter(Boolean)
+      .join('\n\n')
+
+    // Inject episodeId info for direct API usage
+    const episodeInfo = this.currentEpisodeId
+      ? [
+          '',
+          '### Current Session',
+          `- **Episode ID**: \`${this.currentEpisodeId}\``,
+          `- **Session Date**: \`${this.currentSessionDate}\``,
+          '- Include `"episodeId": "<id>"` and `"sessionDate": "<date>"` in all POST /facts calls.',
+        ].join('\n')
+      : ''
+
+    return providerInstructions + episodeInfo
+  }
+
+  /**
+   * Trigger compaction hooks (called when context window is compacted).
+   */
+  async onCompaction(context: HookContext): Promise<void> {
+    if (this.hookRunner?.hasHooks('compaction')) {
+      await this.hookRunner.run('compaction', context)
+    }
+  }
+}

package/src/lib/model-catalog.ts

@@ -0,0 +1,240 @@
+/**
+ * Model Catalog — Static metadata for known AI models.
+ *
+ * Provides context window sizes, pricing, and display names.
+ * Used by SessionTracker and /status command to calculate
+ * context usage percentages and cost estimates.
+ *
+ * Pricing is per million tokens (USD). Context is in tokens.
+ * Data source: Anthropic pricing pages, last updated 2026-03.
+ */
+
+export interface ModelInfo {
+  /** Human-readable display name */
+  displayName: string
+  /** Max context window in tokens */
+  contextWindow: number
+  /** Max output tokens */
+  maxOutput: number
+  /** Input price per million tokens (USD) */
+  inputPricePerM: number
+  /** Output price per million tokens (USD) */
+  outputPricePerM: number
+  /** Cache read price per million tokens (USD) — typically 10% of input */
+  cacheReadPricePerM: number
+  /** Cache write price per million tokens (USD) — typically 25% more than input */
+  cacheWritePricePerM: number
+}
+
+/**
+ * Known model catalog.
+ *
+ * Keys are normalized: we strip date suffixes and match on the base name.
+ * e.g., "claude-sonnet-4-5-20250514" → matches "claude-sonnet-4-5"
+ */
+const CATALOG: Record<string, ModelInfo> = {
+  // ═══════════════════════════════════════════
+  // Claude 4.x family
+  // ═══════════════════════════════════════════
+
+  'claude-sonnet-4-5': {
+    displayName: 'Claude Sonnet 4.5',
+    contextWindow: 200_000,
+    maxOutput: 16_384,
+    inputPricePerM: 3.0,
+    outputPricePerM: 15.0,
+    cacheReadPricePerM: 0.3,
+    cacheWritePricePerM: 3.75,
+  },
+
+  'claude-sonnet-4-6': {
+    displayName: 'Claude Sonnet 4.6',
+    contextWindow: 200_000,
+    maxOutput: 16_384,
+    inputPricePerM: 3.0,
+    outputPricePerM: 15.0,
+    cacheReadPricePerM: 0.3,
+    cacheWritePricePerM: 3.75,
+  },
+
+  'claude-sonnet-4-6[1m]': {
+    displayName: 'Claude Sonnet 4.6 (1M)',
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPricePerM: 6.0,
+    outputPricePerM: 22.5,
+    cacheReadPricePerM: 0.6,
+    cacheWritePricePerM: 7.5,
+  },
+
+  'claude-opus-4-5': {
+    displayName: 'Claude Opus 4.5',
+    contextWindow: 200_000,
+    maxOutput: 32_768,
+    inputPricePerM: 15.0,
+    outputPricePerM: 75.0,
+    cacheReadPricePerM: 1.5,
+    cacheWritePricePerM: 18.75,
+  },
+
+  'claude-opus-4-6': {
+    displayName: 'Claude Opus 4.6',
+    contextWindow: 200_000,
+    maxOutput: 32_768,
+    inputPricePerM: 15.0,
+    outputPricePerM: 75.0,
+    cacheReadPricePerM: 1.5,
+    cacheWritePricePerM: 18.75,
+  },
+
+  // 1M context variant — same base model, extended window.
+  // Pricing: 2x input, 1.5x output for tokens beyond 200K.
+  // We use the premium rate as worst-case for cost estimates.
+  'claude-opus-4-6[1m]': {
+    displayName: 'Claude Opus 4.6 (1M)',
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPricePerM: 30.0,
+    outputPricePerM: 112.5,
+    cacheReadPricePerM: 3.0,
+    cacheWritePricePerM: 37.5,
+  },
+
+  'claude-haiku-4-5': {
+    displayName: 'Claude Haiku 4.5',
+    contextWindow: 200_000,
+    maxOutput: 16_384,
+    inputPricePerM: 0.8,
+    outputPricePerM: 4.0,
+    cacheReadPricePerM: 0.08,
+    cacheWritePricePerM: 1.0,
+  },
+
+  // ═══════════════════════════════════════════
+  // Claude 3.x legacy
+  // ═══════════════════════════════════════════
+
+  'claude-3-5-sonnet': {
+    displayName: 'Claude 3.5 Sonnet',
+    contextWindow: 200_000,
+    maxOutput: 8_192,
+    inputPricePerM: 3.0,
+    outputPricePerM: 15.0,
+    cacheReadPricePerM: 0.3,
+    cacheWritePricePerM: 3.75,
+  },
+
+  'claude-3-opus': {
+    displayName: 'Claude 3 Opus',
+    contextWindow: 200_000,
+    maxOutput: 4_096,
+    inputPricePerM: 15.0,
+    outputPricePerM: 75.0,
+    cacheReadPricePerM: 1.5,
+    cacheWritePricePerM: 18.75,
+  },
+
+  'claude-3-haiku': {
+    displayName: 'Claude 3 Haiku',
+    contextWindow: 200_000,
+    maxOutput: 4_096,
+    inputPricePerM: 0.25,
+    outputPricePerM: 1.25,
+    cacheReadPricePerM: 0.03,
+    cacheWritePricePerM: 0.3,
+  },
+}
+
+/** Default model info for unknown models */
+const DEFAULT_MODEL: ModelInfo = {
+  displayName: 'Unknown Model',
+  contextWindow: 200_000,
+  maxOutput: 16_384,
+  inputPricePerM: 3.0,
+  outputPricePerM: 15.0,
+  cacheReadPricePerM: 0.3,
+  cacheWritePricePerM: 3.75,
+}
+
+/**
+ * Normalize a model ID by stripping the date suffix.
+ * Preserves bracket suffixes like [1m] for extended context variants.
+ *
+ * Examples:
+ *   "claude-sonnet-4-5-20250514"      → "claude-sonnet-4-5"
+ *   "claude-opus-4-6-20260301"        → "claude-opus-4-6"
+ *   "claude-opus-4-6-20260301[1m]"    → "claude-opus-4-6[1m]"
+ *   "claude-opus-4-6[1m]"            → "claude-opus-4-6[1m]"
+ */
+function normalizeModelId(modelId: string): string {
+  // Separate bracket suffix (e.g., [1m]) before normalizing
+  const bracketMatch = modelId.match(/(\[[^\]]+\])$/)
+  const suffix = bracketMatch ? bracketMatch[1] : ''
+  const base = suffix ? modelId.slice(0, -suffix.length) : modelId
+
+  return base.replace(/-\d{8}$/, '') + suffix
+}
+
+/**
+ * Look up model info. Tries exact match first, then normalized (without date suffix).
+ * Falls back to DEFAULT_MODEL for unknown models.
+ */
+export function getModelInfo(modelId: string): ModelInfo {
+  if (CATALOG[modelId]) return CATALOG[modelId]
+
+  const normalized = normalizeModelId(modelId)
+  if (CATALOG[normalized]) return CATALOG[normalized]
+
+  for (const [key, info] of Object.entries(CATALOG)) {
+    if (normalized.startsWith(key)) return info
+  }
+
+  return { ...DEFAULT_MODEL, displayName: modelId }
+}
+
+/**
+ * Get display name for a model ID.
+ */
+export function getModelDisplayName(modelId: string): string {
+  return getModelInfo(modelId).displayName
+}
+
+/**
+ * Get context window size for a model ID.
+ */
+export function getContextWindowSize(modelId: string): number {
+  return getModelInfo(modelId).contextWindow
+}
+
+/**
+ * Calculate cost in USD from token counts.
+ */
+export function calculateCost(
+  modelId: string,
+  tokens: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens?: number
+    cacheWriteTokens?: number
+  },
+): number {
+  const info = getModelInfo(modelId)
+  const { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0 } = tokens
+
+  // Regular input tokens = total input minus cache tokens
+  const regularInput = Math.max(0, inputTokens - cacheReadTokens - cacheWriteTokens)
+
+  return (
+    (regularInput / 1_000_000) * info.inputPricePerM +
+    (outputTokens / 1_000_000) * info.outputPricePerM +
+    (cacheReadTokens / 1_000_000) * info.cacheReadPricePerM +
+    (cacheWriteTokens / 1_000_000) * info.cacheWritePricePerM
+  )
+}
+
+/**
+ * List all known model IDs.
+ */
+export function listModels(): string[] {
+  return Object.keys(CATALOG)
+}