@animalabs/connectome-host 0.3.1

package/src/modules/mcpl-admin-module.ts

@@ -0,0 +1,345 @@
+/**
+ * McplAdminModule — lets the agent deploy, restart, and unload its own MCPL
+ * servers at runtime, without a host restart.
+ *
+ * Tools:
+ *   - mcpl_list                → configured servers + live connection status
+ *   - mcpl_deploy {id, ...}    → add/update a server and hot-connect it
+ *   - mcpl_restart {id}        → kill + respawn a server (picks up rebuilt dist)
+ *   - mcpl_unload {id}         → disconnect a server and remove its tools
+ *
+ * Persistence model (agent overlay):
+ *   Agent deployments are written to `mcpl-servers.agent.json` (cwd), which
+ *   index.ts merges over the recipe/file server list at startup — so agent
+ *   deployments survive host restarts without touching human-owned recipe
+ *   files or mcpl-servers.json. Unloading a recipe/file server writes a
+ *   `{disabled: true}` tombstone to the overlay; unloading an agent-deployed
+ *   server just deletes its overlay entry.
+ *
+ * Security: enabling this module in a recipe grants the agent the ability to
+ * spawn arbitrary commands as the host user (mcpl_deploy). Recipe opt-in
+ * (`modules: { mcplAdmin: true }`) is the permission gate.
+ */
+
+import type {
+  Module,
+  ModuleContext,
+  ProcessEvent,
+  ProcessState,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+  AgentFramework,
+  McplServerConfig,
+} from '@animalabs/agent-framework';
+import {
+  DEFAULT_CONFIG_PATH,
+  DEFAULT_AGENT_OVERLAY_PATH,
+  readMcplServersFile,
+  readAgentOverlay,
+  saveAgentOverlay,
+  resolveOverlayEntry,
+  type AgentOverlayEntry,
+} from '../mcpl-config.js';
+
+export interface McplAdminModuleConfig {
+  /** Path to the agent overlay file. Default: `mcpl-servers.agent.json` in cwd. */
+  overlayPath?: string;
+  /** Path to the human-owned server config file (read-only here). */
+  configPath?: string;
+}
+
+function ok(text: string): ToolResult {
+  return { success: true, data: text };
+}
+
+function fail(text: string): ToolResult {
+  return { success: false, error: text, isError: true };
+}
+
+export class McplAdminModule implements Module {
+  readonly name = 'mcpl-admin';
+
+  private framework: AgentFramework | null = null;
+  private overlayPath: string;
+  private configPath: string;
+
+  constructor(config?: McplAdminModuleConfig) {
+    this.overlayPath = config?.overlayPath ?? DEFAULT_AGENT_OVERLAY_PATH;
+    this.configPath = config?.configPath ?? DEFAULT_CONFIG_PATH;
+  }
+
+  /** Post-creation wiring (called from index.ts, mirrors ActivityModule.setFramework). */
+  setFramework(framework: AgentFramework): void {
+    this.framework = framework;
+  }
+
+  async start(_ctx: ModuleContext): Promise<void> {}
+
+  async stop(): Promise<void> {
+    this.framework = null;
+  }
+
+  getTools(): ToolDefinition[] {
+    return [
+      {
+        name: 'mcpl_list',
+        description:
+          'List all MCPL servers: id, live connection status, tool count, command/url, ' +
+          'and where each is defined (recipe/file vs your own agent overlay).',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'mcpl_deploy',
+        description:
+          'Deploy an MCPL server: persist it to your agent overlay (survives host ' +
+          'restarts) and hot-connect it now — its tools become available immediately. ' +
+          'If a server with this id is already running it is restarted with the new ' +
+          'config. Provide either `command` (stdio, spawned as the host user) or `url` ' +
+          '(WebSocket). Relative ./ args resolve against the host working directory.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Unique server id (also the default tool prefix: mcpl--<id>).' },
+            command: { type: 'string', description: 'Executable to spawn (stdio transport). Mutually exclusive with url.' },
+            args: { type: 'array', items: { type: 'string' }, description: 'Arguments for the command.' },
+            env: { type: 'object', description: 'Environment variables for the spawned process.' },
+            url: { type: 'string', description: 'WebSocket URL (websocket transport). Mutually exclusive with command.' },
+            token: { type: 'string', description: 'Bearer token for WebSocket auth.' },
+            toolPrefix: { type: 'string', description: 'Tool namespace prefix. Default: mcpl--<id>.' },
+            reconnect: { type: 'boolean', description: 'Auto-reconnect on transport failure (default false). Note: does NOT respawn a crashed child — use mcpl_restart for that.' },
+            channelSubscription: {
+              type: 'string',
+              enum: ['auto', 'manual'],
+              description: "Channel auto-open policy: 'auto' (default) opens every channel the server registers; 'manual' opens none. For an allow-list, use channelAllowlist instead.",
+            },
+            channelAllowlist: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Allow-list of channel ids to auto-open (overrides channelSubscription).',
+            },
+            enabledFeatureSets: { type: 'array', items: { type: 'string' } },
+            disabledFeatureSets: { type: 'array', items: { type: 'string' } },
+            enabledTools: { type: 'array', items: { type: 'string' }, description: 'Tool allow-list (bare names, * wildcard).' },
+            disabledTools: { type: 'array', items: { type: 'string' }, description: 'Tool deny-list; wins over enabledTools.' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'mcpl_restart',
+        description:
+          'Restart an MCPL server: kill the process and respawn it with its current ' +
+          'config. Use after rebuilding a server\'s dist, or to recover a crashed ' +
+          'server (reconnect:true does not respawn dead children — this does). ' +
+          'CAUTION: restarting the server that carries your active conversation ' +
+          '(e.g. discord) briefly interrupts your own message delivery; it reconnects ' +
+          'within a few seconds.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Server id to restart.' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'mcpl_unload',
+        description:
+          'Unload an MCPL server: disconnect it and remove its tools from your ' +
+          'toolset. By default this persists (an unloaded recipe server stays ' +
+          'unloaded after host restarts; an agent-deployed server is deleted from ' +
+          'your overlay). Pass persist:false to unload for this session only. ' +
+          'WARNING: unloading the server that carries your conversation (e.g. ' +
+          'discord) cuts your own communication channel — you would need another ' +
+          'route (or a human) to get it back.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Server id to unload.' },
+            persist: { type: 'boolean', description: 'Persist across host restarts (default true).' },
+          },
+          required: ['id'],
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    const input = (call.input ?? {}) as Record<string, unknown>;
+    try {
+      switch (call.name) {
+        case 'mcpl_list':
+          return this.handleList();
+        case 'mcpl_deploy':
+          return await this.handleDeploy(input);
+        case 'mcpl_restart':
+          return await this.handleRestart(input);
+        case 'mcpl_unload':
+          return await this.handleUnload(input);
+        default:
+          return fail(`Unknown tool: ${call.name}`);
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      return fail(`${call.name} failed: ${err.message}`);
+    }
+  }
+
+  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    return {};
+  }
+
+  // --------------------------------------------------------------------------
+  // Handlers
+  // --------------------------------------------------------------------------
+
+  private requireFramework(): AgentFramework {
+    if (!this.framework) {
+      throw new Error('mcpl-admin module is not wired to the framework yet');
+    }
+    return this.framework;
+  }
+
+  private handleList(): ToolResult {
+    const framework = this.requireFramework();
+    const live = framework.listMcplServers();
+    const overlay = readAgentOverlay(this.overlayPath);
+    const fileServers = readMcplServersFile(this.configPath);
+
+    const lines: string[] = [];
+    for (const s of live) {
+      const source = overlay[s.id] && !overlay[s.id]!.disabled
+        ? 'agent-overlay'
+        : s.id in fileServers ? 'file/recipe' : 'recipe';
+      const target = s.command ?? s.url ?? '?';
+      lines.push(
+        `${s.id}: ${s.connected ? 'CONNECTED' : 'DISCONNECTED'} — ${s.toolCount} tools, ` +
+        `prefix=${s.toolPrefix}, source=${source}, ${target}`,
+      );
+    }
+
+    // Tombstoned / overlay-only entries that aren't currently loaded
+    const liveIds = new Set(live.map(s => s.id));
+    for (const [id, entry] of Object.entries(overlay)) {
+      if (entry.disabled) {
+        lines.push(`${id}: UNLOADED (tombstoned in your overlay — redeploy with mcpl_deploy to restore)`);
+      } else if (!liveIds.has(id)) {
+        lines.push(`${id}: NOT LOADED (in your overlay but not connected — try mcpl_deploy again)`);
+      }
+    }
+
+    if (lines.length === 0) {
+      return ok('No MCPL servers configured. Use mcpl_deploy to add one.');
+    }
+    return ok(`MCPL servers (${lines.length}):\n` + lines.map(l => `  ${l}`).join('\n'));
+  }
+
+  private async handleDeploy(input: Record<string, unknown>): Promise<ToolResult> {
+    const framework = this.requireFramework();
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!id) return fail('mcpl_deploy requires a non-empty string `id`.');
+    if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+      return fail('`id` must match [a-zA-Z0-9_-]+ (it becomes part of tool names).');
+    }
+
+    const command = typeof input.command === 'string' ? input.command : undefined;
+    const url = typeof input.url === 'string' ? input.url : undefined;
+    if (!command && !url) return fail('mcpl_deploy requires either `command` (stdio) or `url` (websocket).');
+    if (command && url) return fail('`command` and `url` are mutually exclusive.');
+
+    // Build the overlay entry from recognized fields only.
+    const entry: AgentOverlayEntry = {};
+    if (command) entry.command = command;
+    if (url) { entry.url = url; entry.transport = 'websocket'; }
+    if (Array.isArray(input.args)) entry.args = input.args.map(String);
+    if (input.env && typeof input.env === 'object') entry.env = input.env as Record<string, string>;
+    if (typeof input.token === 'string') entry.token = input.token;
+    if (typeof input.toolPrefix === 'string') entry.toolPrefix = input.toolPrefix;
+    if (typeof input.reconnect === 'boolean') entry.reconnect = input.reconnect;
+    if (Array.isArray(input.channelAllowlist)) {
+      entry.channelSubscription = input.channelAllowlist.map(String);
+    } else if (input.channelSubscription === 'auto' || input.channelSubscription === 'manual') {
+      entry.channelSubscription = input.channelSubscription;
+    }
+    if (Array.isArray(input.enabledFeatureSets)) entry.enabledFeatureSets = input.enabledFeatureSets.map(String);
+    if (Array.isArray(input.disabledFeatureSets)) entry.disabledFeatureSets = input.disabledFeatureSets.map(String);
+    if (Array.isArray(input.enabledTools)) entry.enabledTools = input.enabledTools.map(String);
+    if (Array.isArray(input.disabledTools)) entry.disabledTools = input.disabledTools.map(String);
+
+    // Persist to the overlay first — a connect failure still leaves the entry
+    // in place so the agent can fix the server and mcpl_restart it.
+    const overlay = readAgentOverlay(this.overlayPath);
+    overlay[id] = entry;
+    saveAgentOverlay(this.overlayPath, overlay);
+
+    const config = resolveOverlayEntry(id, entry, this.overlayPath) as unknown as McplServerConfig;
+
+    const alreadyLoaded = framework.listMcplServers().some(s => s.id === id);
+    try {
+      if (alreadyLoaded) {
+        await framework.restartMcplServer(id, config);
+      } else {
+        await framework.connectMcplServer(config);
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      return fail(
+        `Server "${id}" was saved to your overlay but failed to connect: ${err.message}. ` +
+        'Fix the server (check command/path/build) and run mcpl_restart, or mcpl_unload to remove it.',
+      );
+    }
+
+    const status = framework.listMcplServers().find(s => s.id === id);
+    return ok(
+      `${alreadyLoaded ? 'Redeployed' : 'Deployed'} server "${id}" — connected, ` +
+      `${status?.toolCount ?? 0} tools under prefix ${status?.toolPrefix ?? `mcpl--${id}`}. ` +
+      'Persisted to your agent overlay (survives host restarts).',
+    );
+  }
+
+  private async handleRestart(input: Record<string, unknown>): Promise<ToolResult> {
+    const framework = this.requireFramework();
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!id) return fail('mcpl_restart requires `id`.');
+
+    await framework.restartMcplServer(id);
+    const status = framework.listMcplServers().find(s => s.id === id);
+    return ok(
+      `Restarted server "${id}" — ${status?.connected ? 'connected' : 'NOT connected'}, ` +
+      `${status?.toolCount ?? 0} tools.`,
+    );
+  }
+
+  private async handleUnload(input: Record<string, unknown>): Promise<ToolResult> {
+    const framework = this.requireFramework();
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!id) return fail('mcpl_unload requires `id`.');
+    const persist = input.persist !== false;
+
+    const known = framework.listMcplServers().some(s => s.id === id);
+    const overlay = readAgentOverlay(this.overlayPath);
+    if (!known && !(id in overlay)) {
+      return fail(`Server "${id}" is not loaded and not in your overlay.`);
+    }
+
+    await framework.disconnectMcplServer(id);
+
+    let persistNote = 'Session-only: it will load again on the next host restart.';
+    if (persist) {
+      if (overlay[id] && !overlay[id]!.disabled) {
+        // Agent-deployed server: forget it entirely.
+        delete overlay[id];
+        persistNote = 'Removed from your agent overlay.';
+      } else {
+        // Recipe/file server: tombstone it so it stays unloaded across restarts.
+        overlay[id] = { disabled: true };
+        persistNote = 'Tombstoned in your overlay — it stays unloaded across host restarts; redeploy with mcpl_deploy to restore.';
+      }
+      saveAgentOverlay(this.overlayPath, overlay);
+    }
+
+    return ok(`Unloaded server "${id}" — its tools are gone from your toolset. ${persistNote}`);
+  }
+}

package/src/modules/retrieval-module.ts

@@ -0,0 +1,327 @@
+/**
+ * RetrievalModule — LLM-as-retriever for semantic memory.
+ *
+ * Three-step retrieval pipeline running in gatherContext():
+ *   1. Flag concepts (Haiku): identify concepts being discussed that might
+ *      benefit from background knowledge
+ *   2. Mechanical query: keyword-match against LessonsModule
+ *   3. Validate relevance (Haiku): filter to actually relevant lessons
+ *
+ * Steps 1 and 3 use cheap Haiku calls (~$0.001 each).
+ * Results are cached to avoid redundant calls on unchanged context.
+ */
+
+import type {
+  Module,
+  ModuleContext,
+  ProcessState,
+  ProcessEvent,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '@animalabs/agent-framework';
+import type { Membrane, NormalizedRequest } from '@animalabs/membrane';
+import type { ContextInjection } from '@animalabs/context-manager';
+import type { LessonsModule, Lesson } from './lessons-module.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface RetrievalModuleConfig {
+  /** Membrane instance for Haiku calls */
+  membrane: Membrane;
+  /** Model to use for retrieval calls (default: claude-haiku-4-5-20251001) */
+  retrievalModel?: string;
+  /** Max lessons to inject (default: 5) */
+  maxInjectedLessons?: number;
+  /** Minimum lesson confidence for injection (default: 0.3) */
+  minConfidence?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+
+const CONCEPT_FLAG_PROMPT = `You are a knowledge retrieval assistant. Given the recent conversation below, identify concepts, entities, topics, or themes that might benefit from background knowledge or lessons learned from previous research.
+
+Return ONLY a JSON array of keyword strings, nothing else. Example: ["RFC process", "authentication", "team lead"]
+
+If nothing would benefit from background knowledge, return an empty array: []`;
+
+const RELEVANCE_VALIDATION_PROMPT = `You are a relevance filter. Given the current conversation context and a set of candidate knowledge lessons, determine which lessons are actually relevant to the current discussion.
+
+Return ONLY a JSON array of lesson IDs that are relevant, nothing else. Example: ["a1b2c3d4", "e5f6g7h8"]
+
+If none are relevant, return an empty array: []`;
+
+// ---------------------------------------------------------------------------
+// Module
+// ---------------------------------------------------------------------------
+
+export class RetrievalModule implements Module {
+  readonly name = 'retrieval';
+
+  private ctx: ModuleContext | null = null;
+  private config: RetrievalModuleConfig;
+  private lastContextHash = '';
+  private cachedInjections: ContextInjection[] = [];
+
+  constructor(config: RetrievalModuleConfig) {
+    this.config = config;
+  }
+
+  async start(ctx: ModuleContext): Promise<void> {
+    this.ctx = ctx;
+  }
+
+  async stop(): Promise<void> {
+    this.ctx = null;
+  }
+
+  getTools(): ToolDefinition[] {
+    // RetrievalModule is passive — no tools, only gatherContext
+    return [];
+  }
+
+  async handleToolCall(_call: ToolCall): Promise<ToolResult> {
+    return { success: false, error: 'RetrievalModule has no tools', isError: true };
+  }
+
+  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    return {};
+  }
+
+  /**
+   * Run the 3-step retrieval pipeline before each inference.
+   */
+  async gatherContext(_agentName: string): Promise<ContextInjection[]> {
+    if (!this.ctx) return [];
+
+    // Get the LessonsModule to query
+    const lessonsModule = this.ctx.getModule<LessonsModule>('lessons');
+    if (!lessonsModule) return [];
+
+    const lessons = lessonsModule.getLessons().filter(
+      l => !l.deprecated && l.confidence >= (this.config.minConfidence ?? 0.3)
+    );
+    if (lessons.length === 0) return [];
+
+    // Get recent context for concept extraction
+    const recentMessages = this.getRecentContext();
+    if (!recentMessages) return [];
+
+    // Check cache: if context hasn't changed, reuse cached results
+    const contextHash = this.hashContext(recentMessages);
+    if (contextHash === this.lastContextHash && this.cachedInjections.length > 0) {
+      return this.cachedInjections;
+    }
+
+    try {
+      // Step 1: Flag concepts (Haiku call)
+      const concepts = await this.flagConcepts(recentMessages);
+      if (concepts.length === 0) {
+        this.lastContextHash = contextHash;
+        this.cachedInjections = [];
+        return [];
+      }
+
+      // Step 2: Mechanical query (keyword matching)
+      const candidates = this.queryCandidates(concepts, lessons);
+      if (candidates.length === 0) {
+        this.lastContextHash = contextHash;
+        this.cachedInjections = [];
+        return [];
+      }
+
+      // Step 3: Validate relevance (Haiku call)
+      const relevant = await this.validateRelevance(recentMessages, candidates);
+
+      // Build injection
+      const maxLessons = this.config.maxInjectedLessons ?? 5;
+      const injected = relevant.slice(0, maxLessons);
+
+      if (injected.length === 0) {
+        this.lastContextHash = contextHash;
+        this.cachedInjections = [];
+        return [];
+      }
+
+      const text = injected
+        .map(l => `- [${(l.confidence * 100).toFixed(0)}%] ${l.content} (tags: ${l.tags.join(', ')})`)
+        .join('\n');
+
+      const injections: ContextInjection[] = [{
+        namespace: 'retrieval',
+        position: 'system',
+        content: [{ type: 'text', text: `## Retrieved Knowledge\n${text}` }],
+      }];
+
+      this.lastContextHash = contextHash;
+      this.cachedInjections = injections;
+      return injections;
+    } catch (err) {
+      // Fail open — don't block inference if retrieval fails
+      console.error('RetrievalModule: retrieval failed:', err);
+      return [];
+    }
+  }
+
+  // =========================================================================
+  // Pipeline Steps
+  // =========================================================================
+
+  /**
+   * Step 1: Use Haiku to identify concepts that might benefit from background knowledge.
+   */
+  private async flagConcepts(recentContext: string): Promise<string[]> {
+    const model = this.config.retrievalModel ?? 'claude-haiku-4-5-20251001';
+
+    const request: NormalizedRequest = {
+      messages: [
+        {
+          participant: 'user',
+          content: [{ type: 'text', text: `Recent conversation:\n${recentContext}` }],
+        },
+      ],
+      system: CONCEPT_FLAG_PROMPT,
+      config: { model, maxTokens: 500, temperature: 0 },
+    };
+
+    const response = await this.config.membrane.complete(request);
+    const text = response.content
+      .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+      .map(b => b.text)
+      .join('');
+
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((s): s is string => typeof s === 'string');
+      }
+    } catch {
+      // Try to extract from markdown code block
+      const match = text.match(/\[([^\]]*)\]/);
+      if (match) {
+        try {
+          return JSON.parse(`[${match[1]}]`);
+        } catch { /* fall through */ }
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Step 2: Mechanical keyword matching against lessons.
+   */
+  private queryCandidates(concepts: string[], lessons: Lesson[]): Lesson[] {
+    const seen = new Set<string>();
+    const candidates: Lesson[] = [];
+
+    for (const concept of concepts) {
+      const keywords = concept.toLowerCase().split(/\s+/);
+
+      for (const lesson of lessons) {
+        if (seen.has(lesson.id)) continue;
+
+        const text = lesson.content.toLowerCase();
+        const tags = lesson.tags.map(t => t.toLowerCase());
+
+        // Match if any keyword appears in content or tags
+        const matches = keywords.some(kw =>
+          text.includes(kw) || tags.some(tag => tag.includes(kw))
+        );
+
+        if (matches) {
+          seen.add(lesson.id);
+          candidates.push(lesson);
+        }
+      }
+    }
+
+    // Sort by confidence
+    candidates.sort((a, b) => b.confidence - a.confidence);
+    return candidates.slice(0, 20); // Cap at 20 candidates for validation
+  }
+
+  /**
+   * Step 3: Use Haiku to validate which candidates are actually relevant.
+   */
+  private async validateRelevance(recentContext: string, candidates: Lesson[]): Promise<Lesson[]> {
+    if (candidates.length <= 3) {
+      // If only a few candidates, skip validation — they're probably all relevant
+      return candidates;
+    }
+
+    const model = this.config.retrievalModel ?? 'claude-haiku-4-5-20251001';
+
+    const candidateList = candidates.map(l =>
+      `[${l.id}] (${l.confidence.toFixed(2)}) ${l.content}`
+    ).join('\n');
+
+    const request: NormalizedRequest = {
+      messages: [
+        {
+          participant: 'user',
+          content: [{ type: 'text', text: `Current conversation:\n${recentContext}\n\nCandidate lessons:\n${candidateList}` }],
+        },
+      ],
+      system: RELEVANCE_VALIDATION_PROMPT,
+      config: { model, maxTokens: 500, temperature: 0 },
+    };
+
+    const response = await this.config.membrane.complete(request);
+    const text = response.content
+      .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+      .map(b => b.text)
+      .join('');
+
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed)) {
+        const relevantIds = new Set(parsed.filter((s): s is string => typeof s === 'string'));
+        return candidates.filter(l => relevantIds.has(l.id));
+      }
+    } catch {
+      // On parse failure, return top 5 by confidence (fail open)
+      return candidates.slice(0, 5);
+    }
+    return candidates.slice(0, 5);
+  }
+
+  // =========================================================================
+  // Helpers
+  // =========================================================================
+
+  private getRecentContext(): string | null {
+    if (!this.ctx) return null;
+
+    // Get the last few messages from the conversation
+    const { messages } = this.ctx.queryMessages({});
+    if (messages.length === 0) return null;
+
+    // Take the last 10 messages for context
+    const recent = messages.slice(-10);
+    return recent
+      .map(m => {
+        const text = m.content
+          .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+          .map(b => b.text)
+          .join('\n');
+        return `${m.participant}: ${text}`;
+      })
+      .join('\n\n');
+  }
+
+  private hashContext(text: string): string {
+    // Simple hash for cache invalidation
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+      const chr = text.charCodeAt(i);
+      hash = ((hash << 5) - hash) + chr;
+      hash |= 0;
+    }
+    return hash.toString(36);
+  }
+}