agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/controllers/SkillLibrary.js

@@ -7,28 +7,52 @@
  * Based on: "Voyager: An Open-Ended Embodied Agent with Large Language Models"
  * https://arxiv.org/abs/2305.16291
  */
+import { normalizeRowId } from '../types/database.types.js';
+import { searchVectors } from '../backends/VectorBackend.js';
+import { sqlExactSource } from '../backends/ExactSearch.js';
 import { NodeIdMapper } from '../utils/NodeIdMapper.js';
-import { cosineSimilarity } from '../utils/vector-math.js';
+import { QueryCache } from '../core/QueryCache.js';
+import { TopK, squaredNorm, cosineWithQueryNorm, blobToFloat32 } from '../utils/top-k.js';
+/** Vector ids this controller writes: "skill:<rowid>" */
+const SKILL_VECTOR_ID = /^skill:(\d+)$/;
+/** Stay well under SQLite's bound-parameter limit (999 on older builds) */
+const MAX_SQL_PARAMS = 500;
+/** Parse JSON from DB row values without throwing on malformed data. */
+function safeJsonParse(value, fallback) {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
 export class SkillLibrary {
     db;
     embedder;
     vectorBackend;
     graphBackend; // GraphBackend or GraphDatabaseAdapter
-    constructor(db, embedder, vectorBackend, graphBackend) {
+    queryCache;
+    constructor(db, embedder, vectorBackend, graphBackend, cacheConfig) {
         this.db = db;
         this.embedder = embedder;
         this.vectorBackend = vectorBackend || null;
         this.graphBackend = graphBackend;
+        this.queryCache = new QueryCache(cacheConfig);
     }
     /**
      * Create a new skill manually or from an episode
+     * Invalidates skill cache
      */
     async createSkill(skill) {
+        // Invalidate skills cache on write
+        this.queryCache.invalidateCategory('skills');
         // Use GraphDatabaseAdapter if available (AgentDB v2)
         if (this.graphBackend && 'storeSkill' in this.graphBackend) {
             const graphAdapter = this.graphBackend;
             const text = this.buildSkillText(skill);
-            const embedding = await this.embedder.embed(text);
+            const embedding = await this.embedder.embedPassage(text);
             const nodeId = await graphAdapter.storeSkill({
                 id: skill.id ? `skill-${skill.id}` : `skill-${Date.now()}-${Math.random()}`,
                 name: skill.name,
@@ -38,7 +62,7 @@ export class SkillLibrary {
                 avgReward: skill.avgReward ?? 0,
                 createdAt: Date.now(),
                 updatedAt: Date.now(),
-                tags: JSON.stringify(skill.metadata || {})
+                tags: JSON.stringify(skill.metadata || {}),
             }, embedding);
             const numericId = parseInt(nodeId.split('-').pop() || '0', 36);
             NodeIdMapper.getInstance().register(numericId, nodeId);
@@ -57,35 +81,31 @@ export class SkillLibrary {
         const avgReward = skill.avgReward ?? 0;
         const avgLatencyMs = skill.avgLatencyMs ?? 0;
         const result = stmt.run(skill.name, skill.description || null, JSON.stringify(signature), skill.code || null, skill.successRate, uses, avgReward, avgLatencyMs, skill.metadata ? JSON.stringify(skill.metadata) : null);
-        const skillId = result.lastInsertRowid;
+        const skillId = normalizeRowId(result.lastInsertRowid);
         // Generate and store embedding in VectorBackend
         const text = this.buildSkillText(skill);
-        const embedding = await this.embedder.embed(text);
+        const embedding = await this.embedder.embedPassage(text);
         // Store in VectorBackend with skill metadata (if available)
         if (this.vectorBackend) {
-            try {
-                this.vectorBackend.insert(`skill:${skillId}`, embedding, {
-                    name: skill.name,
-                    description: skill.description,
-                    successRate: skill.successRate,
-                    avgReward: skill.avgReward
-                });
-            }
-            catch {
-                // VectorBackend insert failed — fall back to legacy
-                this.storeSkillEmbeddingLegacy(skillId, embedding);
-            }
-        }
-        else {
-            // Legacy: store in database
-            this.storeSkillEmbeddingLegacy(skillId, embedding);
+            this.vectorBackend.insert(`skill:${skillId}`, embedding, {
+                name: skill.name,
+                description: skill.description,
+                successRate: skill.successRate,
+                avgReward: skill.avgReward,
+            });
         }
+        // Always keep the SQL copy: it is the fallback when the vector index
+        // returns nothing (and the only store without a vector backend).
+        this.storeSkillEmbeddingLegacy(skillId, embedding);
         return skillId;
     }
     /**
      * Update skill statistics after use
+     * Invalidates skill cache
      */
     updateSkillStats(skillId, success, reward, latencyMs) {
+        // Invalidate skills cache on update
+        this.queryCache.invalidateCategory('skills');
         const stmt = this.db.prepare(`
       UPDATE skills
       SET
@@ -97,6 +117,35 @@ export class SkillLibrary {
     `);
         stmt.run(success ? 1 : 0, reward, latencyMs, skillId);
     }
+    /**
+     * Record the outcome of using a skill (ADR-015). Updates uses, success
+     * rate and average reward, which retrieveSkills() ranks by; the average
+     * latency only moves when `latencyMs` is given.
+     *
+     * @param reward - defaults to 1 for success, 0 for failure
+     * @returns false when no skill has that id
+     */
+    recordOutcome(skillId, success, reward, latencyMs) {
+        if (reward !== undefined && !Number.isFinite(reward)) {
+            throw new Error('reward must be a finite number');
+        }
+        if (latencyMs !== undefined && (!Number.isFinite(latencyMs) || latencyMs < 0)) {
+            throw new Error('latencyMs must be a non-negative finite number');
+        }
+        this.queryCache.invalidateCategory('skills');
+        const actualReward = reward ?? (success ? 1 : 0);
+        const result = this.db.prepare(`
+      UPDATE skills
+      SET
+        success_rate = (success_rate * uses + ?) / (uses + 1),
+        avg_reward = (avg_reward * uses + ?) / (uses + 1),
+        avg_latency_ms = CASE WHEN ? IS NULL THEN avg_latency_ms
+                              ELSE (avg_latency_ms * uses + ?) / (uses + 1) END,
+        uses = uses + 1
+      WHERE id = ?
+    `).run(success ? 1 : 0, actualReward, latencyMs ?? null, latencyMs ?? null, skillId);
+        return result.changes > 0;
+    }
     /**
      * Retrieve skills relevant to a task
      */
@@ -110,13 +159,20 @@ export class SkillLibrary {
             throw new Error('SkillQuery must provide either task (v2) or query (v1)');
         }
         const { k = 5, minSuccessRate = 0.5, preferRecent = true } = query;
+        // Check cache first
+        const cacheKey = this.queryCache.generateKey('retrieveSkills', [task, k, minSuccessRate, preferRecent], 'skills');
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         // Generate query embedding
-        const queryEmbedding = await this.embedder.embed(task);
+        const queryEmbedding = await this.embedder.embedQuery(task);
         // Use GraphDatabaseAdapter if available (AgentDB v2)
         if (this.graphBackend && 'searchSkills' in this.graphBackend) {
             const graphAdapter = this.graphBackend;
             const searchResults = await graphAdapter.searchSkills(queryEmbedding, k);
-            return searchResults.map(result => {
+            const results = searchResults
+                .map((result) => {
                 // Handle metadata/tags parsing
                 let metadata = undefined;
                 if (result.tags) {
@@ -145,55 +201,77 @@ export class SkillLibrary {
                     successRate: result.avgReward, // Use avgReward as successRate proxy
                     uses: result.usageCount,
                     avgReward: result.avgReward,
-                    metadata
+                    metadata,
                 };
-            }).filter(skill => skill.successRate >= minSuccessRate);
+            })
+                .filter((skill) => skill.successRate >= minSuccessRate);
+            // Cache the results
+            this.queryCache.set(cacheKey, results);
+            return results;
         }
         // Use VectorBackend for semantic search (if available)
         if (this.vectorBackend) {
-            try {
-                const searchResults = this.vectorBackend.search(queryEmbedding, k * 3);
-                // Map results back to skill IDs and fetch full skill data
-                const skillsWithSimilarity = [];
-                // Prepare statement ONCE outside loop (better-sqlite3 best practice)
-                const getSkillStmt = this.db.prepare('SELECT * FROM skills WHERE id = ?');
-                for (const result of searchResults) {
-                    // Extract skill ID from vector ID (format: "skill:123")
-                    const skillId = parseInt(result.id.replace('skill:', ''));
-                    // Fetch full skill data from database
-                    const row = getSkillStmt.get(skillId);
-                    if (!row)
-                        continue;
-                    // Apply filters
-                    if (row.success_rate < minSuccessRate)
-                        continue;
-                    skillsWithSimilarity.push({
-                        id: row.id,
-                        name: row.name,
-                        description: row.description,
-                        signature: JSON.parse(row.signature),
-                        code: row.code,
-                        successRate: row.success_rate,
-                        uses: row.uses,
-                        avgReward: row.avg_reward,
-                        avgLatencyMs: row.avg_latency_ms,
-                        createdFromEpisode: row.created_from_episode,
-                        metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-                        similarity: result.similarity
-                    });
-                }
-                // Compute composite scores
-                skillsWithSimilarity.sort((a, b) => {
-                    const scoreA = this.computeSkillScore(a);
-                    const scoreB = this.computeSkillScore(b);
-                    return scoreB - scoreA;
+            // Small or short index answers are completed by exact cosine over
+            // skill_embeddings (ADR-015)
+            const searchResults = await searchVectors(this.vectorBackend, queryEmbedding, k * 3, undefined, sqlExactSource(this.db, {
+                table: 'skill_embeddings',
+                idColumn: 'skill_id',
+                vectorId: (id) => `skill:${id}`,
+                owns: (hit) => SKILL_VECTOR_ID.test(hit.id),
+            }));
+            // The vector backend may be shared with other controllers (episodes use
+            // bare numeric ids, causal edges "causal-edge:N"); only "skill:N" is ours.
+            const similarityById = new Map();
+            for (const result of searchResults) {
+                const match = SKILL_VECTOR_ID.exec(result.id);
+                if (!match)
+                    continue;
+                const skillId = Number(match[1]);
+                if (!similarityById.has(skillId))
+                    similarityById.set(skillId, result.similarity);
+            }
+            // No usable hits although skills exist (empty or crowded-out index):
+            // answer from the SQL embeddings instead of returning nothing.
+            if (similarityById.size === 0 && this.db.prepare('SELECT 1 FROM skills LIMIT 1').get()) {
+                const results = await this.retrieveSkillsLegacy(query);
+                this.queryCache.set(cacheKey, results);
+                return results;
+            }
+            const skillsWithSimilarity = [];
+            for (const row of this.fetchSkillsByIds([...similarityById.keys()])) {
+                // Apply filters
+                if (row.success_rate < minSuccessRate)
+                    continue;
+                skillsWithSimilarity.push({
+                    id: row.id,
+                    name: row.name,
+                    description: row.description ?? undefined,
+                    signature: safeJsonParse(row.signature, undefined),
+                    code: row.code ?? undefined,
+                    successRate: row.success_rate,
+                    uses: row.uses,
+                    avgReward: row.avg_reward,
+                    avgLatencyMs: row.avg_latency_ms,
+                    createdFromEpisode: row.created_from_episode ?? undefined,
+                    metadata: safeJsonParse(row.metadata, undefined),
+                    similarity: similarityById.get(row.id),
                 });
-                return skillsWithSimilarity.slice(0, k);
             }
-            catch { /* vectorBackend search failed — fall through to SQL */ }
+            // Compute composite scores
+            skillsWithSimilarity.sort((a, b) => {
+                const scoreA = this.computeSkillScore(a);
+                const scoreB = this.computeSkillScore(b);
+                return scoreB - scoreA;
+            });
+            const results = skillsWithSimilarity.slice(0, k);
+            // Cache the results
+            this.queryCache.set(cacheKey, results);
+            return results;
+        }
+        else {
+            // Legacy: use SQL-based similarity search
+            return this.retrieveSkillsLegacy(query);
         }
-        // Legacy: use SQL-based similarity search
-        return this.retrieveSkillsLegacy(query);
     }
     /**
      * Legacy SQL-based skill retrieval (fallback when VectorBackend not available)
@@ -205,7 +283,7 @@ export class SkillLibrary {
             throw new Error('SkillQuery must provide either task (v2) or query (v1)');
         }
         const { k = 5, minSuccessRate = 0.5 } = query;
-        const queryEmbedding = await this.embedder.embed(task);
+        const queryEmbedding = await this.embedder.embedQuery(task);
         // Fetch all skills with embeddings
         const stmt = this.db.prepare(`
       SELECT s.*, e.embedding
@@ -214,35 +292,37 @@ export class SkillLibrary {
       WHERE s.success_rate >= ?
     `);
         const rows = stmt.all(minSuccessRate);
-        // Compute similarities
-        const skillsWithSimilarity = [];
+        // Bounded top-k by composite score; JSON columns are parsed for the
+        // winners only. Ties keep scan order, as the old stable sort did.
+        const queryNorm = Math.sqrt(squaredNorm(queryEmbedding));
+        const top = new TopK(k);
         for (const row of rows) {
             if (!row.embedding)
                 continue;
-            const embedding = new Float32Array(row.embedding.buffer);
-            const similarity = cosineSimilarity(queryEmbedding, embedding);
-            skillsWithSimilarity.push({
-                id: row.id,
+            const similarity = cosineWithQueryNorm(queryEmbedding, queryNorm, blobToFloat32(row.embedding));
+            const score = this.computeSkillScore({
                 name: row.name,
-                description: row.description,
-                signature: JSON.parse(row.signature),
-                code: row.code,
                 successRate: row.success_rate,
                 uses: row.uses,
                 avgReward: row.avg_reward,
-                avgLatencyMs: row.avg_latency_ms,
-                createdFromEpisode: row.created_from_episode,
-                metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-                similarity
+                similarity,
             });
+            top.push(score, { row, similarity });
         }
-        // Sort by composite score
-        skillsWithSimilarity.sort((a, b) => {
-            const scoreA = this.computeSkillScore(a);
-            const scoreB = this.computeSkillScore(b);
-            return scoreB - scoreA;
-        });
-        return skillsWithSimilarity.slice(0, k);
+        return top.sorted().map(({ item: { row, similarity } }) => ({
+            id: row.id,
+            name: row.name,
+            description: row.description ?? undefined,
+            signature: safeJsonParse(row.signature, undefined),
+            code: row.code ?? undefined,
+            successRate: row.success_rate,
+            uses: row.uses,
+            avgReward: row.avg_reward,
+            avgLatencyMs: row.avg_latency_ms,
+            createdFromEpisode: row.created_from_episode ?? undefined,
+            metadata: safeJsonParse(row.metadata, undefined),
+            similarity,
+        }));
     }
     /**
      * Store skill embedding (legacy fallback)
@@ -253,9 +333,38 @@ export class SkillLibrary {
       VALUES (?, ?)
       ON CONFLICT(skill_id) DO UPDATE SET embedding = excluded.embedding
     `);
-        const buffer = Buffer.from(embedding.buffer);
+        const buffer = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
         stmt.run(skillId, buffer);
     }
+    /**
+     * Load skill rows for a set of ids with one IN query per chunk
+     * (instead of one query per vector hit).
+     */
+    fetchSkillsByIds(ids) {
+        const rows = [];
+        for (let i = 0; i < ids.length; i += MAX_SQL_PARAMS) {
+            const chunk = ids.slice(i, i + MAX_SQL_PARAMS);
+            const placeholders = chunk.map(() => '?').join(',');
+            rows.push(...this.db
+                .prepare(`SELECT * FROM skills WHERE id IN (${placeholders})`)
+                .all(...chunk));
+        }
+        return rows;
+    }
+    /**
+     * Cosine similarity between two vectors
+     */
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
     /**
      * Link two skills with a relationship
      */
@@ -342,7 +451,7 @@ export class SkillLibrary {
                     task: candidate.task,
                     commonPatterns: extractedPatterns,
                     successIndicators: successIndicators,
-                    avgReward: candidate.avg_reward
+                    avgReward: candidate.avg_reward,
                 });
             }
             // Check if skill already exists
@@ -354,12 +463,12 @@ export class SkillLibrary {
                     description: enhancedDescription,
                     signature: {
                         inputs: { task: 'string' },
-                        outputs: { result: 'any' }
+                        outputs: { result: 'any' },
                     },
                     successRate: candidate.success_rate,
                     uses: candidate.attempt_count,
                     avgReward: candidate.avg_reward,
-                    avgLatencyMs: candidate.avg_latency || 0,
+                    avgLatencyMs: candidate.avg_latency ?? 0,
                     createdFromEpisode: candidate.latest_episode_id,
                     metadata: {
                         sourceEpisodes: episodeIds,
@@ -367,15 +476,15 @@ export class SkillLibrary {
                         consolidatedAt: Date.now(),
                         extractedPatterns: extractedPatterns,
                         successIndicators: successIndicators,
-                        patternConfidence: this.calculatePatternConfidence(episodeIds.length, candidate.success_rate)
-                    }
+                        patternConfidence: this.calculatePatternConfidence(episodeIds.length, candidate.success_rate),
+                    },
                 };
                 await this.createSkill(skill);
                 created++;
             }
             else {
                 // Update existing skill stats
-                this.updateSkillStats(existing.id, candidate.success_rate > 0.5, candidate.avg_reward, candidate.avg_latency || 0);
+                this.updateSkillStats(existing.id, candidate.success_rate > 0.5, candidate.avg_reward, candidate.avg_latency ?? 0);
                 updated++;
             }
         }
@@ -386,21 +495,21 @@ export class SkillLibrary {
      */
     async extractPatternsFromEpisodes(episodeIds) {
         // Retrieve episodes with their outputs and critiques
-        const episodes = this.db.prepare(`
+        const episodes = this.db
+            .prepare(`
       SELECT id, task, input, output, critique, reward, success, metadata
       FROM episodes
       WHERE id IN (${episodeIds.map(() => '?').join(',')})
       AND success = 1
-    `).all(...episodeIds);
+    `)
+            .all(...episodeIds);
         if (episodes.length === 0) {
             return { commonPatterns: [], successIndicators: [] };
         }
         const commonPatterns = [];
         const successIndicators = [];
         // Pattern 1: Analyze output text for common keywords and phrases
-        const outputTexts = episodes
-            .map(ep => ep.output)
-            .filter(Boolean);
+        const outputTexts = episodes.map((ep) => ep.output).filter(Boolean);
         if (outputTexts.length > 0) {
             const keywordFrequency = this.extractKeywordFrequency(outputTexts);
             const topKeywords = this.getTopKeywords(keywordFrequency, 5);
@@ -409,9 +518,7 @@ export class SkillLibrary {
             }
         }
         // Pattern 2: Analyze critique patterns for successful strategies
-        const critiques = episodes
-            .map(ep => ep.critique)
-            .filter(Boolean);
+        const critiques = episodes.map((ep) => ep.critique).filter(Boolean);
         if (critiques.length > 0) {
             const critiqueKeywords = this.extractKeywordFrequency(critiques);
             const topCritiquePatterns = this.getTopKeywords(critiqueKeywords, 3);
@@ -421,7 +528,7 @@ export class SkillLibrary {
         }
         // Pattern 3: Analyze reward distribution
         const avgReward = episodes.reduce((sum, ep) => sum + ep.reward, 0) / episodes.length;
-        const highRewardCount = episodes.filter(ep => ep.reward > avgReward).length;
+        const highRewardCount = episodes.filter((ep) => ep.reward > avgReward).length;
         const highRewardRatio = highRewardCount / episodes.length;
         if (highRewardRatio > 0.6) {
             successIndicators.push(`High consistency (${(highRewardRatio * 100).toFixed(0)}% above average)`);
@@ -445,10 +552,46 @@ export class SkillLibrary {
         const frequency = new Map();
         // Common stop words to filter out
         const stopWords = new Set([
-            'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
-            'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'been',
-            'be', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should',
-            'could', 'may', 'might', 'must', 'can', 'this', 'that', 'these', 'those'
+            'the',
+            'a',
+            'an',
+            'and',
+            'or',
+            'but',
+            'in',
+            'on',
+            'at',
+            'to',
+            'for',
+            'of',
+            'with',
+            'by',
+            'from',
+            'as',
+            'is',
+            'was',
+            'are',
+            'were',
+            'been',
+            'be',
+            'have',
+            'has',
+            'had',
+            'do',
+            'does',
+            'did',
+            'will',
+            'would',
+            'should',
+            'could',
+            'may',
+            'might',
+            'must',
+            'can',
+            'this',
+            'that',
+            'these',
+            'those',
         ]);
         for (const text of texts) {
             // Extract words (alphanumeric sequences)
@@ -480,9 +623,7 @@ export class SkillLibrary {
         for (const episode of episodes) {
             if (episode.metadata) {
                 try {
-                    const metadata = typeof episode.metadata === 'string'
-                        ? JSON.parse(episode.metadata)
-                        : episode.metadata;
+                    const metadata = typeof episode.metadata === 'string' ? JSON.parse(episode.metadata) : episode.metadata;
                     for (const [key, value] of Object.entries(metadata)) {
                         if (!metadataFields.has(key)) {
                             metadataFields.set(key, new Set());
@@ -513,10 +654,10 @@ export class SkillLibrary {
             return null;
         // Sort by episode ID (temporal order)
         const sorted = [...episodes].sort((a, b) => a.id - b.id);
-        const firstHalfReward = sorted.slice(0, Math.floor(sorted.length / 2))
-            .reduce((sum, ep) => sum + ep.reward, 0) / Math.floor(sorted.length / 2);
-        const secondHalfReward = sorted.slice(Math.floor(sorted.length / 2))
-            .reduce((sum, ep) => sum + ep.reward, 0) / (sorted.length - Math.floor(sorted.length / 2));
+        const firstHalfReward = sorted.slice(0, Math.floor(sorted.length / 2)).reduce((sum, ep) => sum + ep.reward, 0) /
+            Math.floor(sorted.length / 2);
+        const secondHalfReward = sorted.slice(Math.floor(sorted.length / 2)).reduce((sum, ep) => sum + ep.reward, 0) /
+            (sorted.length - Math.floor(sorted.length / 2));
         const improvement = ((secondHalfReward - firstHalfReward) / firstHalfReward) * 100;
         if (improvement > 10) {
             return `Strong learning curve (+${improvement.toFixed(0)}% improvement)`;
@@ -541,6 +682,7 @@ export class SkillLibrary {
     }
     /**
      * Prune underperforming skills
+     * Invalidates cache on completion
      */
     pruneSkills(config) {
         const { minUses = 3, minSuccessRate = 0.4, maxAgeDays = 60 } = config;
@@ -551,8 +693,41 @@ export class SkillLibrary {
         AND created_at < strftime('%s', 'now') - ?
     `);
         const result = stmt.run(minUses, minSuccessRate, maxAgeDays * 86400);
+        // Invalidate cache after pruning
+        if (result.changes > 0) {
+            this.queryCache.invalidateCategory('skills');
+        }
         return result.changes;
     }
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats() {
+        return this.queryCache.getStatistics();
+    }
+    /**
+     * Clear query cache
+     */
+    clearCache() {
+        this.queryCache.clear();
+    }
+    /**
+     * Prune expired cache entries
+     */
+    pruneCache() {
+        return this.queryCache.pruneExpired();
+    }
+    /**
+     * Warm cache with common skill queries
+     */
+    async warmCache(commonTasks) {
+        await this.queryCache.warm(async (cache) => {
+            // Pre-load common skill queries
+            for (const task of commonTasks) {
+                await this.retrieveSkills({ task, k: 5 });
+            }
+        });
+    }
     // ========================================================================
     // Private Helper Methods
     // ========================================================================
@@ -568,14 +743,14 @@ export class SkillLibrary {
             id: row.id,
             name: row.name,
             description: row.description,
-            signature: JSON.parse(row.signature),
+            signature: safeJsonParse(row.signature, undefined),
             code: row.code,
             successRate: row.success_rate,
             uses: row.uses,
             avgReward: row.avg_reward,
             avgLatencyMs: row.avg_latency_ms,
             createdFromEpisode: row.created_from_episode,
-            metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+            metadata: safeJsonParse(row.metadata, undefined),
         };
     }
     buildSkillText(skill) {