@onmars/lunar-core 0.1.0

package/src/lib/router.ts

@@ -0,0 +1,1135 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { AgentEvent, AgentInput } from '../types/agent'
+import type { IncomingMessage, OutgoingMessage } from '../types/channel'
+import type { MemoryProvider } from '../types/memory'
+import type { ChannelPersona } from '../types/moon'
+import { type ClearResult, type CommandContext, CommandHandler } from './command-handler'
+import { clearCommand } from './commands/clear'
+import { compactCommand } from './commands/compact'
+import { configCommand } from './commands/config-show'
+import { cronCommand } from './commands/cron'
+import { createHelpCommand } from './commands/help'
+import { modelCommand } from './commands/model'
+import { pingCommand } from './commands/ping'
+import { remindCommand } from './commands/remind'
+import { statusCommand } from './commands/status'
+import { stopCommand } from './commands/stop'
+import { thinkCommand } from './commands/think'
+import { usageCommand } from './commands/usage'
+import { whoamiCommand } from './commands/whoami'
+import type { LunarConfig } from './config'
+import type { MemoryConfig, RecallConfig, SecurityConfig, VoiceConfig } from './config-loader'
+import { log } from './logger'
+import type { MemoryOrchestrator } from './memory-orchestrator'
+import type { MoonLoader } from './moon-loader'
+import type { PluginRegistry } from './plugin'
+import type { JobPayload, Scheduler } from './scheduler'
+import type { SanitizationResult } from './security'
+import { createRedactor, createSanitizer } from './security'
+import type { SessionStore } from './session'
+import { SessionTracker } from './session-tracker'
+
+export interface RouteOptions {
+  /** Override agent ID */
+  agentId?: string
+}
+
+/**
+ * Router — Handles the flow: incoming message → agent query → outgoing response.
+ *
+ * Responsibilities:
+ * - Session lookup/creation
+ * - Auth check (allowed users)
+ * - Moon resolution per channel (via MoonLoader)
+ * - Memory auto-recall (inject relevant context before query)
+ * - Streaming agent response → channel message
+ * - Typing indicator management
+ * - Output redaction (security)
+ */
+export class Router {
+  private redact: (text: string) => string
+  private sanitize: (text: string) => SanitizationResult
+  private channelIndex: Map<string, ChannelPersona>
+  private memory?: MemoryProvider
+  private recallConfig?: RecallConfig
+  private memoryInstructions?: string
+
+  /**
+   * In-memory message history per session — used for graceful session close.
+   * Capped at MAX_SESSION_HISTORY messages per session to bound memory usage.
+   */
+  private sessionMessages = new Map<string, Array<{ role: string; content: string }>>()
+  private static readonly MAX_SESSION_HISTORY = 200
+
+  /** Tracks cumulative token usage per session */
+  private sessionTracker = new SessionTracker()
+
+  private voiceConfig?: VoiceConfig
+
+  /** Slash command handler */
+  private commandHandler: CommandHandler
+
+  /** Daemon start time — set by Daemon after construction */
+  daemonStartedAt = 0
+
+  constructor(
+    private registry: PluginRegistry,
+    private sessions: SessionStore,
+    private config: LunarConfig,
+    private moonLoader: MoonLoader,
+    channels: ChannelPersona[],
+    security?: SecurityConfig,
+    memory?: MemoryProvider,
+    recallConfig?: RecallConfig,
+    private workspacePath?: string,
+    private memoryConfig?: MemoryConfig,
+    private scheduler?: Scheduler,
+    voiceConfig?: VoiceConfig,
+  ) {
+    this.redact = security ? createRedactor(security) : (t: string) => t
+    this.sanitize = security
+      ? createSanitizer(security.inputSanitization)
+      : (t: string) => ({
+          text: t,
+          stripped: 0,
+          suspicious: [],
+          wasSanitized: false,
+        })
+    this.memory = memory
+    this.recallConfig = recallConfig
+    this.memoryInstructions = this.loadMemoryInstructions()
+    this.voiceConfig = voiceConfig
+
+    // Build index: platform:channelId → ChannelPersona
+    // Also index by bare ID for backward compat (single-platform setups)
+    this.channelIndex = new Map()
+    for (const ch of channels) {
+      this.channelIndex.set(`${ch.platform}:${ch.id}`, ch)
+      // Bare ID as fallback (avoids breaking single-platform setups)
+      if (!this.channelIndex.has(ch.id)) {
+        this.channelIndex.set(ch.id, ch)
+      }
+    }
+
+    if (this.channelIndex.size > 0) {
+      log.info(
+        { channels: channels.map((c) => `${c.platform}:${c.name}→${c.moon ?? 'default'}`) },
+        'Channel → Moon routing configured',
+      )
+    }
+
+    if (memory && recallConfig?.enabled) {
+      log.info(
+        { provider: memory.id, limit: recallConfig.limit, minScore: recallConfig.minScore },
+        'Auto-recall enabled',
+      )
+    }
+
+    // Register slash commands
+    this.commandHandler = new CommandHandler()
+    this.commandHandler.register(
+      'status',
+      'Show session status, tokens, context, and cost',
+      statusCommand,
+    )
+    this.commandHandler.register(
+      'help',
+      'List available commands',
+      createHelpCommand(this.commandHandler),
+    )
+    this.commandHandler.register(
+      'clear',
+      'Clear session: reset tokens, context, and start fresh',
+      clearCommand,
+    )
+    this.commandHandler.register(
+      'remind',
+      'Set a one-shot reminder: /remind in 15m Check oven',
+      remindCommand,
+    )
+    this.commandHandler.register(
+      'cron',
+      'Manage recurring jobs: /cron list|add|remove|enable|disable',
+      cronCommand,
+    )
+    this.commandHandler.register('reset', 'Reset session (alias for /clear)', clearCommand)
+    this.commandHandler.register(
+      'whoami',
+      'Show your identity and current channel info',
+      whoamiCommand,
+    )
+    this.commandHandler.register('ping', 'Latency check and daemon uptime', pingCommand)
+    this.commandHandler.register(
+      'compact',
+      'Force context compaction (clears session)',
+      compactCommand,
+    )
+    this.commandHandler.register('config', 'Show active configuration: /config [show]', configCommand)
+    this.commandHandler.register('usage', 'Show session usage and account quota', usageCommand)
+    this.commandHandler.register('model', 'View or change model: /model [alias|id|clear]', modelCommand)
+    this.commandHandler.register('think', 'Set thinking level: /think [off|low|medium|high]', thinkCommand)
+    this.commandHandler.register('stop', 'Cancel the currently running query', stopCommand)
+  }
+
+  /** Route an incoming message to the appropriate agent and send the response */
+  async route(channelId: string, message: IncomingMessage, options?: RouteOptions): Promise<void> {
+    // Auth check
+    if (!this.isAllowed(message.sender.id)) {
+      log.warn({ sender: message.sender.id }, 'Unauthorized message, ignoring')
+      return
+    }
+
+    const channel = this.registry.getChannel(channelId)
+    if (!channel) {
+      log.error({ channelId }, 'Channel not found in registry')
+      return
+    }
+
+    // Resolve channel persona and moon
+    // Try platform-qualified key first, then bare ID as fallback
+    const channelPersona =
+      this.channelIndex.get(`${channelId}:${message.channelId}`) ??
+      this.channelIndex.get(message.channelId)
+
+    // Priority: explicit RouteOptions.agentId > channel persona agentId > default
+    const resolvedAgentId = options?.agentId ?? channelPersona?.agentId
+    const agent = this.registry.getAgent(resolvedAgentId)
+    if (!agent) {
+      log.error({ agentId: resolvedAgentId, channel: channelPersona?.name }, 'No agent available')
+      return
+    }
+    const moon = this.moonLoader.resolve(channelPersona)
+
+    // Include agent ID in session key to prevent cross-agent session pollution.
+    // When Deimos and Hermes both handle different channels, their sessions
+    // must not interfere even if they share a channel adapter.
+    const sessionKey = `${agent.id}:${channelId}:${message.channelId}`
+    const session = this.sessions.get(sessionKey)
+
+    // ─── Command interception (before system prompt — zero token cost) ───
+    if (this.commandHandler.isCommand(message.text)) {
+      const ctx: CommandContext = {
+        sessionKey,
+        message,
+        tracker: this.sessionTracker,
+        moon,
+        channelPersona,
+        memory: this.memory,
+        daemonStartedAt: this.daemonStartedAt,
+        agent: { id: agent.id, name: agent.name },
+        config: this.config,
+        updateSessionMeta: (updates) => {
+          const existing = this.sessions.getMetadata(sessionKey) ?? {}
+          const merged = { ...existing, ...updates }
+          this.sessions.updateMetadata(sessionKey, JSON.stringify(merged))
+        },
+        getSessionMeta: () => this.sessions.getMetadata(sessionKey),
+        abortAgent: () => agent.abort?.(),
+        clearSession: (opts) => this.performClearSession(sessionKey, opts?.skipHooks),
+        scheduler: this.scheduler,
+      }
+
+      const response = await this.commandHandler.handle(message.text, ctx)
+      if (response) {
+        const outgoing: OutgoingMessage = { text: this.redact(response), replyTo: message.id }
+        await channel.send(message.channelId, outgoing)
+        log.info({ command: message.text.split(/\s+/)[0] }, 'Command handled')
+        return
+      }
+    }
+
+    // ─── Input sanitization ────────────────────────────────────────────
+    const sanitized = this.sanitize(message.text)
+    if (sanitized.wasSanitized) {
+      log.warn(
+        {
+          stripped: sanitized.stripped,
+          suspicious: sanitized.suspicious,
+          sender: message.sender.id,
+          channel: message.channelId,
+        },
+        'Input sanitized — potential prompt injection detected',
+      )
+    }
+
+    // ─── STT: transcribe incoming audio ────────────────────────────────
+    let effectiveText = sanitized.text
+    let hasIncomingAudio = false
+
+    const sttProvider = this.registry.getSTT()
+    if (sttProvider && this.voiceConfig?.stt?.mode !== 'never') {
+      const audioAttachments = message.attachments?.filter((a) => a.type === 'audio') ?? []
+
+      if (audioAttachments.length > 0) {
+        hasIncomingAudio = true
+
+        for (const audio of audioAttachments) {
+          try {
+            const audioBuffer = await this.downloadAttachment(audio.url)
+            const result = await sttProvider.transcribe(audioBuffer, {
+              language: this.voiceConfig?.stt?.language,
+            })
+
+            if (result.text.trim()) {
+              // Sanitize transcribed text too (voice injection is possible)
+              const sttSanitized = this.sanitize(result.text)
+              if (sttSanitized.wasSanitized) {
+                log.warn(
+                  { stripped: sttSanitized.stripped, suspicious: sttSanitized.suspicious },
+                  'STT transcription sanitized',
+                )
+              }
+
+              const cleanTranscription = sttSanitized.text
+              effectiveText = effectiveText
+                ? `[Voice transcription]: ${cleanTranscription}\n\n${effectiveText}`
+                : cleanTranscription
+
+              log.info(
+                {
+                  chars: result.text.length,
+                  language: result.language,
+                  durationMs: result.durationMs,
+                },
+                'Audio transcribed via STT',
+              )
+            }
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err)
+            log.warn({ error: errMsg }, 'STT transcription failed — continuing with text only')
+          }
+        }
+      }
+    }
+
+    // Build system prompt from moon + channel persona
+    let systemPrompt = moon ? this.moonLoader.buildSystemPrompt(moon, channelPersona) : undefined
+
+    // Memory: inject instructions (user file or provider default)
+    if (this.memoryInstructions) {
+      systemPrompt = systemPrompt
+        ? `${systemPrompt}\n\n---\n\n${this.memoryInstructions}`
+        : this.memoryInstructions
+    }
+
+    // Auto-recall: inject relevant memories into system prompt
+    if (this.memory && this.recallConfig?.enabled) {
+      const memoryContext = await this.recallContext(message.text)
+      if (memoryContext) {
+        systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryContext}` : memoryContext
+      }
+    }
+
+    // Read session metadata for per-session overrides (/model, /think commands)
+    const sessionMeta = this.sessions.getMetadata(sessionKey)
+    const sessionModelOverride = sessionMeta?.modelOverride as string | undefined
+    const sessionThinking = sessionMeta?.thinkingLevel as string | undefined
+
+    // Build agent input — session override > channel-level model > moon-level model > global agent config
+    const input: AgentInput = {
+      prompt: effectiveText,
+      sessionId: session?.agentSessionId,
+      systemPrompt,
+      model: sessionModelOverride ?? channelPersona?.model ?? moon?.model,
+      context1m: moon?.context1m,
+      thinking: sessionThinking,
+      metadata: {
+        channelId: message.channelId,
+        channelName: channelPersona?.name,
+        moonName: moon?.name,
+        sender: message.sender,
+      },
+    }
+
+    log.debug(
+      {
+        sessionKey,
+        hasSession: !!session,
+        moon: moon?.name,
+        channel: channelPersona?.name,
+      },
+      'Routing message',
+    )
+
+    // Start typing
+    const typingInterval = this.startTyping(channel, message.channelId)
+
+    try {
+      // Collect response from agent
+      let fullText = ''
+      let newSessionId: string | undefined
+
+      for await (const event of agent.query(input)) {
+        switch (event.type) {
+          case 'text':
+            fullText += event.content
+            break
+          case 'done':
+            newSessionId = event.sessionId
+            if (event.usage) {
+              this.sessionTracker.recordQuery(sessionKey, event.usage)
+              log.info(
+                {
+                  model: event.usage.model,
+                  tokens: event.usage.inputTokens + event.usage.outputTokens,
+                  cacheRead: event.usage.cacheReadTokens,
+                  cacheWrite: event.usage.cacheWriteTokens,
+                  durationMs: event.usage.durationMs,
+                  moon: moon?.name,
+                },
+                'Agent query complete',
+              )
+            }
+            break
+          case 'error':
+            log.error({ error: event.error, recoverable: event.recoverable }, 'Agent error')
+            if (!event.recoverable) {
+              fullText = '⚠️ An error occurred. Please try again.'
+            }
+            break
+        }
+      }
+
+      // Stop typing
+      clearInterval(typingInterval)
+
+      // Send response (with output redaction + optional TTS)
+      if (fullText.trim()) {
+        const redactedText = this.redact(fullText.trim())
+
+        // ─── TTS: synthesize response if conditions met ──────────────────
+        let audioAttachment: import('../types/channel').OutgoingAttachment | undefined
+        const ttsProvider = this.registry.getTTS()
+        const ttsMode = this.voiceConfig?.tts?.mode ?? 'auto'
+        const shouldSpeak =
+          ttsProvider && (ttsMode === 'always' || (ttsMode === 'auto' && hasIncomingAudio))
+
+        if (shouldSpeak) {
+          try {
+            // Cap text length to avoid excessive API cost / timeouts
+            const maxChars = 4000
+            const textToSpeak =
+              redactedText.length > maxChars ? redactedText.slice(0, maxChars) : redactedText
+
+            const ttsResult = await ttsProvider.synthesize(textToSpeak, {
+              language: this.voiceConfig?.tts?.language,
+              speed: this.voiceConfig?.tts?.speed,
+            })
+
+            audioAttachment = {
+              type: 'audio' as const,
+              data: ttsResult.audio,
+              filename: `voice.${ttsResult.format}`,
+              mimeType: `audio/${ttsResult.format}`,
+            }
+
+            log.info(
+              {
+                format: ttsResult.format,
+                bytes: ttsResult.audio.length,
+                durationMs: ttsResult.durationMs,
+              },
+              'TTS audio synthesized',
+            )
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err)
+            log.warn({ error: errMsg }, 'TTS synthesis failed — sending text only')
+          }
+        }
+
+        const outgoing: OutgoingMessage = {
+          text: redactedText,
+          replyTo: message.id,
+          attachments: audioAttachment ? [audioAttachment] : undefined,
+        }
+        await channel.send(message.channelId, outgoing)
+      }
+
+      // Track message history for graceful session close
+      this.sessionTracker.recordMessage(sessionKey)
+      this.trackMessage(sessionKey, 'user', message.text)
+      if (fullText.trim()) {
+        this.trackMessage(sessionKey, 'assistant', fullText.trim())
+      }
+
+      // Update session
+      if (newSessionId) {
+        this.sessions.set(sessionKey, newSessionId)
+      } else {
+        this.sessions.touch(sessionKey)
+      }
+    } catch (error) {
+      clearInterval(typingInterval)
+      log.error({ err: error }, 'Router error')
+
+      await channel.send(message.channelId, {
+        text: '⚠️ Something went wrong. Please try again.',
+        replyTo: message.id,
+      })
+    }
+  }
+
+  // ─── Session lifecycle ─────────────────────────────────────────────
+
+  /**
+   * Clear a single session: run hooks (optional), delete Claude session,
+   * reset tracker, clear message history.
+   *
+   * Called by /clear command. The next agent query will start a fresh
+   * Claude Code session (no --resume flag).
+   */
+  private async performClearSession(sessionKey: string, skipHooks = false): Promise<ClearResult> {
+    let hooksRan = false
+
+    // Run memory lifecycle hooks before clearing (graceful clear)
+    if (!skipHooks && this.memory?.onSessionEnd) {
+      const messages = this.sessionMessages.get(sessionKey) ?? []
+      if (messages.length > 0) {
+        try {
+          const orchestrator = this.memory as unknown as MemoryOrchestrator
+          const clearContext: Record<string, unknown> = {
+            messages,
+            topics: this.extractTopics(messages),
+          }
+          if (orchestrator?.episodeId) clearContext.episodeId = orchestrator.episodeId
+          if (orchestrator?.sessionDate) clearContext.sessionDate = orchestrator.sessionDate
+
+          await this.memory.onSessionEnd(
+            clearContext as Parameters<NonNullable<MemoryProvider['onSessionEnd']>>[0],
+          )
+          hooksRan = true
+          log.info({ sessionKey, messageCount: messages.length }, 'Memory hooks ran before clear')
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err)
+          log.warn({ sessionKey, error: errMsg }, 'Memory hooks failed during /clear')
+        }
+      }
+    }
+
+    // Delete Claude session from store → next query won't use --resume
+    this.sessions.delete(sessionKey)
+
+    // Reset usage counters
+    this.sessionTracker.clear(sessionKey)
+
+    // Clear message history
+    this.sessionMessages.delete(sessionKey)
+
+    log.info({ sessionKey, hooksRan, skipHooks }, 'Session cleared via /clear')
+
+    return { sessionCleared: true, hooksRan }
+  }
+
+  // ─── Scheduler dispatch ─────────────────────────────────────────────
+
+  /**
+   * Dispatch a scheduled job — bypasses auth, uses target channel context.
+   *
+   * For 'query' payloads: resolves moon + channel persona, builds system prompt,
+   * does memory auto-recall, queries the agent, and sends the response.
+   *
+   * For 'message' payloads: sends the text directly to the channel (no agent).
+   *
+   * @param channelName - Channel name from config.yaml (e.g., "orbit")
+   * @param payload - Job payload (query or message)
+   * @param options - Optional moon override, job metadata
+   */
+  async dispatchScheduled(
+    channelName: string,
+    payload: JobPayload,
+    options?: { moon?: string; jobId?: string; jobName?: string },
+  ): Promise<void> {
+    // Find the channel persona by name
+    const channelPersona = [...this.channelIndex.values()].find((c) => c.name === channelName)
+
+    if (!channelPersona) {
+      const available = [...this.channelIndex.values()].map((c) => c.name)
+      log.error({ channelName, available }, 'Scheduler: channel not found in config')
+      return
+    }
+
+    // Find the channel adapter
+    const channel = this.registry.getChannel(channelPersona.platform ?? 'discord')
+    if (!channel) {
+      log.error({ platform: channelPersona.platform }, 'Scheduler: channel adapter not found')
+      return
+    }
+
+    // Handle static message — no agent query needed
+    if (payload.kind === 'message') {
+      await channel.send(channelPersona.id, { text: payload.text })
+      log.info(
+        { channel: channelName, jobId: options?.jobId, jobName: options?.jobName },
+        'Scheduler: static message sent',
+      )
+      return
+    }
+
+    // Handle agent query
+    if (payload.kind === 'query') {
+      // Priority: channelPersona.agentId > default agent
+      const resolvedAgentId = channelPersona?.agentId
+      const agent = this.registry.getAgent(resolvedAgentId)
+      if (!agent) {
+        log.error(
+          { agentId: resolvedAgentId, channel: channelName },
+          'Scheduler: no agent available for query dispatch',
+        )
+        return
+      }
+
+      // Resolve moon (override from job, or channel default)
+      const moon = options?.moon
+        ? (this.moonLoader.get(options.moon) ?? this.moonLoader.resolve(channelPersona))
+        : this.moonLoader.resolve(channelPersona)
+
+      // Build system prompt (same as normal route flow)
+      let systemPrompt = moon ? this.moonLoader.buildSystemPrompt(moon, channelPersona) : undefined
+
+      if (this.memoryInstructions) {
+        systemPrompt = systemPrompt
+          ? `${systemPrompt}\n\n---\n\n${this.memoryInstructions}`
+          : this.memoryInstructions
+      }
+
+      // Auto-recall for the scheduled prompt
+      if (this.memory && this.recallConfig?.enabled) {
+        const memoryContext = await this.recallContext(payload.prompt)
+        if (memoryContext) {
+          systemPrompt = systemPrompt ? `${systemPrompt}\n\n${memoryContext}` : memoryContext
+        }
+      }
+
+      // Session key for scheduled queries — includes agent ID for namespace isolation
+      const sessionKey = `${agent.id}:discord:${channelPersona.id}`
+      const session = this.sessions.get(sessionKey)
+
+      const input: AgentInput = {
+        prompt: payload.prompt,
+        sessionId: session?.agentSessionId,
+        systemPrompt,
+        model: moon?.model,
+        context1m: moon?.context1m,
+        metadata: {
+          channelId: channelPersona.id,
+          channelName: channelPersona.name,
+          moonName: moon?.name,
+          sender: { id: 'scheduler', name: 'Scheduler' },
+          scheduled: true,
+          jobId: options?.jobId,
+          jobName: options?.jobName,
+        },
+      }
+
+      // Start typing indicator
+      const typingInterval = this.startTyping(channel, channelPersona.id)
+
+      try {
+        let fullText = ''
+        let newSessionId: string | undefined
+
+        for await (const event of agent.query(input)) {
+          switch (event.type) {
+            case 'text':
+              fullText += event.content
+              break
+            case 'done':
+              newSessionId = event.sessionId
+              if (event.usage) {
+                this.sessionTracker.recordQuery(sessionKey, event.usage)
+              }
+              break
+            case 'error':
+              log.error({ error: event.error }, 'Scheduler: agent error')
+              if (!event.recoverable) {
+                fullText = ''
+              }
+              break
+          }
+        }
+
+        clearInterval(typingInterval)
+
+        if (fullText.trim()) {
+          const redactedText = this.redact(fullText.trim())
+          await channel.send(channelPersona.id, { text: redactedText })
+
+          // Track for session continuity
+          this.trackMessage(sessionKey, 'user', payload.prompt)
+          this.trackMessage(sessionKey, 'assistant', fullText.trim())
+        }
+
+        if (newSessionId) {
+          this.sessions.set(sessionKey, newSessionId)
+        }
+
+        log.info(
+          { channel: channelName, jobId: options?.jobId, jobName: options?.jobName },
+          'Scheduler: query dispatched and response sent',
+        )
+      } catch (error) {
+        clearInterval(typingInterval)
+        log.error({ err: error, jobId: options?.jobId }, 'Scheduler: dispatch error')
+      }
+    }
+  }
+
+  /**
+   * Gracefully close all active sessions — triggers memory lifecycle hooks.
+   *
+   * Called by Daemon.stop() on SIGINT/SIGTERM. For each session that has
+   * message history, calls memory.onSessionEnd() which triggers:
+   *   - sessionEnd hooks (e.g., summarize)
+   *   - Provider-specific cleanup (Engram: session summary, Brain: extraction)
+   *   - afterSessionEnd hooks (e.g., promote Engram → Brain)
+   *
+   * After closing, message history is cleared.
+   */
+  async closeAllSessions(): Promise<void> {
+    if (!this.memory || this.sessionMessages.size === 0) return
+
+    const sessionCount = this.sessionMessages.size
+    log.info({ sessions: sessionCount }, 'Closing active sessions (graceful shutdown)')
+
+    const closePromises: Promise<void>[] = []
+
+    for (const [sessionKey, messages] of this.sessionMessages) {
+      if (messages.length === 0) continue
+
+      closePromises.push(
+        (async () => {
+          try {
+            // Pass episodeId from orchestrator if available
+            const orchestrator = this.memory as unknown as MemoryOrchestrator
+            const sessionContext: Record<string, unknown> = {
+              messages,
+              topics: this.extractTopics(messages),
+            }
+            if (orchestrator?.episodeId) sessionContext.episodeId = orchestrator.episodeId
+            if (orchestrator?.sessionDate) sessionContext.sessionDate = orchestrator.sessionDate
+
+            await this.memory!.onSessionEnd!(
+              sessionContext as Parameters<NonNullable<MemoryProvider['onSessionEnd']>>[0],
+            )
+            log.info({ sessionKey, messageCount: messages.length }, 'Session closed gracefully')
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err)
+            log.warn(
+              { sessionKey, error: errMsg },
+              'Failed to close session — hooks may not have run',
+            )
+          }
+        })(),
+      )
+    }
+
+    await Promise.allSettled(closePromises)
+    this.sessionMessages.clear()
+    log.info({ sessions: sessionCount }, 'All sessions closed')
+  }
+
+  /**
+   * Get message count for a session (for testing/diagnostics).
+   */
+  getSessionMessageCount(sessionKey: string): number {
+    return this.sessionMessages.get(sessionKey)?.length ?? 0
+  }
+
+  /**
+   * Get total number of active sessions with message history.
+   */
+  get activeSessionCount(): number {
+    return this.sessionMessages.size
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────
+
+  /**
+   * Track a message in session history (capped at MAX_SESSION_HISTORY).
+   */
+  private trackMessage(sessionKey: string, role: string, content: string): void {
+    let history = this.sessionMessages.get(sessionKey)
+    if (!history) {
+      history = []
+      this.sessionMessages.set(sessionKey, history)
+    }
+
+    history.push({ role, content })
+
+    // Cap to prevent unbounded memory growth
+    if (history.length > Router.MAX_SESSION_HISTORY) {
+      // Remove oldest messages (keep the most recent)
+      const excess = history.length - Router.MAX_SESSION_HISTORY
+      history.splice(0, excess)
+    }
+  }
+
+  /**
+   * Extract simple topic keywords from messages.
+   * Lightweight extraction — no LLM needed, just frequent nouns/phrases.
+   */
+  private extractTopics(messages: Array<{ role: string; content: string }>): string[] {
+    // Combine all user messages
+    const text = messages
+      .filter((m) => m.role === 'user')
+      .map((m) => m.content)
+      .join(' ')
+      .toLowerCase()
+
+    // Simple word frequency (skip common words)
+    const stopWords = new Set([
+      'the',
+      'a',
+      'an',
+      'is',
+      'are',
+      'was',
+      'were',
+      'be',
+      'been',
+      'being',
+      'have',
+      'has',
+      'had',
+      'do',
+      'does',
+      'did',
+      'will',
+      'would',
+      'could',
+      'should',
+      'may',
+      'might',
+      'shall',
+      'can',
+      'need',
+      'dare',
+      'ought',
+      'used',
+      'to',
+      'of',
+      'in',
+      'for',
+      'on',
+      'with',
+      'at',
+      'by',
+      'from',
+      'as',
+      'into',
+      'through',
+      'during',
+      'before',
+      'after',
+      'above',
+      'below',
+      'between',
+      'out',
+      'off',
+      'over',
+      'under',
+      'again',
+      'further',
+      'then',
+      'once',
+      'and',
+      'but',
+      'or',
+      'nor',
+      'not',
+      'so',
+      'yet',
+      'both',
+      'either',
+      'neither',
+      'each',
+      'every',
+      'all',
+      'any',
+      'few',
+      'more',
+      'most',
+      'other',
+      'some',
+      'such',
+      'no',
+      'only',
+      'own',
+      'same',
+      'than',
+      'too',
+      'very',
+      'just',
+      'because',
+      'if',
+      'when',
+      'where',
+      'how',
+      'what',
+      'which',
+      'who',
+      'whom',
+      'this',
+      'that',
+      'these',
+      'those',
+      'i',
+      'me',
+      'my',
+      'myself',
+      'we',
+      'our',
+      'you',
+      'your',
+      'he',
+      'him',
+      'she',
+      'her',
+      'it',
+      'its',
+      'they',
+      'them',
+      'their',
+      'que',
+      'de',
+      'la',
+      'el',
+      'en',
+      'y',
+      'un',
+      'una',
+      'los',
+      'las',
+      'es',
+      'se',
+      'del',
+      'lo',
+      'con',
+      'no',
+      'por',
+      'para',
+      'al',
+      'como',
+      'más',
+      'pero',
+      'sus',
+      'le',
+      'ya',
+      'o',
+      'este',
+      'si',
+      'porque',
+      'esta',
+      'entre',
+      'cuando',
+      'muy',
+      'sin',
+      'sobre',
+      'también',
+      'me',
+      'hasta',
+      'hay',
+      'donde',
+      'quien',
+    ])
+
+    const words = text
+      .replace(/[^a-záéíóúñü\s]/g, '')
+      .split(/\s+/)
+      .filter((w) => w.length > 3)
+    const freq = new Map<string, number>()
+    for (const word of words) {
+      if (stopWords.has(word)) continue
+      freq.set(word, (freq.get(word) ?? 0) + 1)
+    }
+
+    // Top 5 most frequent non-stop words
+    return [...freq.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([word]) => word)
+  }
+
+  /**
+   * Load memory instructions for the agent.
+   *
+   * Priority:
+   * 1. config.yaml memory.instructionsFile (explicit path)
+   * 2. prompts/{provider}.md in workspace (convention)
+   * 3. Provider's built-in agentInstructions() (fallback)
+   */
+  private loadMemoryInstructions(): string | undefined {
+    if (!this.memory) return undefined
+
+    const instructions: string[] = []
+
+    // v2: Check each provider's instructions field
+    if (this.memoryConfig?.providers && this.workspacePath) {
+      for (const [name, prov] of Object.entries(this.memoryConfig.providers)) {
+        // 1. Explicit instructions file from provider config
+        if (prov.instructions) {
+          const explicitPath = resolve(this.workspacePath, prov.instructions)
+          if (existsSync(explicitPath)) {
+            const content = readFileSync(explicitPath, 'utf-8').trim()
+            if (content) {
+              log.info(
+                { provider: name, path: explicitPath },
+                'Memory instructions loaded from provider config',
+              )
+              instructions.push(content)
+              continue
+            }
+          } else {
+            log.warn({ provider: name, path: explicitPath }, 'Provider instructions file not found')
+          }
+        }
+
+        // 2. Convention: prompts/{name}.md
+        const conventionPath = resolve(this.workspacePath, 'prompts', `${name}.md`)
+        if (existsSync(conventionPath)) {
+          const content = readFileSync(conventionPath, 'utf-8').trim()
+          if (content) {
+            log.info(
+              { provider: name, path: conventionPath },
+              'Memory instructions loaded from prompts/',
+            )
+            instructions.push(content)
+          }
+        }
+      }
+    }
+
+    if (instructions.length > 0) {
+      return instructions.join('\n\n---\n\n')
+    }
+
+    // 3. Provider built-in default
+    if (this.memory.agentInstructions) {
+      log.debug('Using provider built-in memory instructions')
+      return this.memory.agentInstructions()
+    }
+
+    return undefined
+  }
+
+  /**
+   * Recall relevant memories for the user's message.
+   * Returns formatted context string or undefined if no relevant results.
+   */
+  private async recallContext(query: string): Promise<string | undefined> {
+    if (!this.memory || !this.recallConfig) return undefined
+
+    const minScore = this.recallConfig.minScore
+    const budget = this.recallConfig.budget
+
+    try {
+      const results = await this.memory.recall(query, {
+        limit: this.recallConfig.limit,
+        minScore,
+      })
+
+      if (results.length === 0) return undefined
+
+      // Split: diary entries (always included) vs semantic results (budget-limited)
+      const diaryResults = results.filter((r) => r.source === 'brain:diary')
+      const semanticResults = results.filter((r) => r.source !== 'brain:diary')
+
+      // 1. Always include all diary entries (they're already capped at source)
+      const diaryItems: string[] = []
+      let diaryChars = 0
+      for (const r of diaryResults) {
+        const meta = r.metadata
+        const prefix = meta?.category ? `[${meta.category}]` : '[diary]'
+        const line = `- ${prefix} ${r.content}`
+        diaryItems.push(line)
+        diaryChars += line.length
+      }
+
+      // 2. Fill remaining budget with semantic results
+      const budgetChars = budget * 4
+      const remainingBudget =
+        budget === Infinity ? Infinity : Math.max(budgetChars - diaryChars, budgetChars * 0.3)
+      const semanticItems: string[] = []
+      let semanticChars = 0
+
+      for (const r of semanticResults) {
+        const score = `${(r.score * 100).toFixed(0)}%`
+        const meta = r.metadata
+        const prefix = meta?.type ? `[${meta.type}]` : ''
+        const line = `- ${prefix} ${r.content} (relevance: ${score})`
+
+        if (remainingBudget !== Infinity && semanticChars + line.length > remainingBudget) {
+          log.debug(
+            {
+              budget,
+              diaryChars,
+              semanticChars,
+              dropped: semanticResults.length - semanticItems.length,
+            },
+            'Semantic context truncated by budget (diary preserved)',
+          )
+          break
+        }
+
+        semanticItems.push(line)
+        semanticChars += line.length
+      }
+
+      // Combine: diary section + semantic section
+      const sections: string[] = []
+      if (diaryItems.length > 0) {
+        sections.push(`### Session Diary (today)\n${diaryItems.join('\n')}`)
+      }
+      if (semanticItems.length > 0) {
+        sections.push(`### Relevant Memories\n${semanticItems.join('\n')}`)
+      }
+
+      if (sections.length === 0) return undefined
+
+      const totalChars = diaryChars + semanticChars
+      log.debug(
+        {
+          diary: diaryItems.length,
+          semantic: semanticItems.length,
+          totalResults: results.length,
+          budgetUsed: totalChars,
+        },
+        'Auto-recall injected',
+      )
+
+      return `## Memory Context (auto-recalled)\n${sections.join('\n\n')}`
+    } catch (err) {
+      log.warn({ err }, 'Auto-recall failed, continuing without memory context')
+      return undefined
+    }
+  }
+
+  private isAllowed(senderId: string): boolean {
+    if (!this.config.discordAllowedUsers?.length) return true
+    return this.config.discordAllowedUsers.includes(senderId)
+  }
+
+  private startTyping(
+    channel: { sendTyping(target: string): Promise<void> },
+    target: string,
+  ): ReturnType<typeof setInterval> {
+    // Send typing immediately, then refresh every 8s (Discord expires at 10s)
+    channel.sendTyping(target).catch(() => {})
+    return setInterval(() => {
+      channel.sendTyping(target).catch(() => {})
+    }, 8000)
+  }
+  /**
+   * Download an audio attachment from URL into a Buffer.
+   * Used by STT pipeline to fetch voice messages before transcription.
+   */
+  private async downloadAttachment(url: string): Promise<Buffer> {
+    const response = await fetch(url)
+    if (!response.ok) {
+      throw new Error(`Failed to download attachment: HTTP ${response.status}`)
+    }
+    const arrayBuffer = await response.arrayBuffer()
+    return Buffer.from(arrayBuffer)
+  }
+}