agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/mcp/agentdb-mcp-server.js

@@ -7,7 +7,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { createDatabase } from '../db-fallback.js';
+import { createDatabase, getDatabaseInfo } from '../db-fallback.js';
+import { NativeAccelerator } from '../backends/rvf/NativeAccelerator.js';
+import { detectBackends } from '../backends/factory.js';
+import { DEFAULT_EXACT_SEARCH_THRESHOLD } from '../backends/VectorBackend.js';
+import { DEFAULT_RERANK_WEIGHTS } from '../controllers/ReasoningBank.js';
 import { CausalMemoryGraph } from '../controllers/CausalMemoryGraph.js';
 import { CausalRecall } from '../controllers/CausalRecall.js';
 import { ReflexionMemory } from '../controllers/ReflexionMemory.js';
@@ -23,9 +27,34 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import { buildMcpToolPolicy, filterMcpTools, isMcpToolAllowed, } from '../security/mcp-policy.js';
+import { resetDatabaseTables } from './reset-database.js';
 // ES module equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const toolPolicy = buildMcpToolPolicy();
+// Request-size limits at the MCP boundary
+const MAX_INSERT_BATCH_ITEMS = 1000;
+const MAX_SEARCH_K = 100;
+const MAX_FEEDBACK_LATENCY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Outcome feedback at the MCP boundary (ADR-015): a boolean success, a reward
+ * in [0, 1], or both. A reward alone counts as a success when >= 0.5.
+ */
+function validateFeedback(args) {
+    const hasReward = args?.reward !== undefined && args?.reward !== null;
+    const hasSuccess = args?.success !== undefined && args?.success !== null;
+    if (!hasReward && !hasSuccess) {
+        throw new ValidationError('success or reward is required', 'MISSING_REQUIRED_FIELD', 'success');
+    }
+    const reward = hasReward ? validateNumericRange(args.reward, 'reward', 0, 1) : undefined;
+    const success = hasSuccess ? validateBoolean(args.success, 'success') : reward >= 0.5;
+    return { success, reward };
+}
+// stdout belongs exclusively to JSON-RPC when running over stdio. Route every
+// transitive diagnostic (including legacy controller console.log calls) to
+// stderr before database and embedding initialization begins.
+console.log = (...args) => console.error(...args);
 // ============================================================================
 // Helper Functions for Core Vector DB Operations
 // ============================================================================
@@ -232,6 +261,40 @@ const learningSystem = new LearningSystem(db, embeddingService);
 const batchOps = new BatchOperations(db, embeddingService);
 const reasoningBank = new ReasoningBank(db, embeddingService);
 const caches = new MCPToolCaches();
+// agentdb_capabilities: native probing is done once, on first request
+let acceleratorProbe = null;
+async function describeCapabilities() {
+    acceleratorProbe ??= (async () => {
+        const accelerator = new NativeAccelerator();
+        await accelerator.initialize();
+        return accelerator;
+    })();
+    const [accelerator, detected] = await Promise.all([acceleratorProbe, detectBackends()]);
+    const exactThreshold = Number(process.env.AGENTDB_EXACT_SEARCH_THRESHOLD);
+    return {
+        nativeAccelerator: accelerator.capabilities(),
+        vectorBackend: {
+            // This server's controllers are built without a vector index: every
+            // search here is an exact cosine scan over the SQL embedding tables.
+            inUse: 'sql-exact-scan',
+            available: detected.available,
+            ruvector: detected.ruvector,
+            rvf: detected.rvf,
+            hnswlib: detected.hnswlib,
+            sqljsRvf: detected.sqljsRvf,
+            ruvectorBackendEnv: process.env.RUVECTOR_BACKEND ?? null,
+        },
+        sqlDriver: getDatabaseInfo(),
+        embedding: embeddingService.getRuntimeInfo(),
+        retrieval: {
+            exactSearchThreshold: Number.isFinite(exactThreshold) && exactThreshold >= 0
+                ? exactThreshold
+                : DEFAULT_EXACT_SEARCH_THRESHOLD,
+            patternRerankWeights: DEFAULT_RERANK_WEIGHTS,
+        },
+        mcpProfile: toolPolicy.profile,
+    };
+}
 // ============================================================================
 // MCP Server Setup
 // ============================================================================
@@ -256,8 +319,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                db_path: { type: 'string', description: 'Database file path (optional, defaults to ./agentdb.db)', default: './agentdb.db' },
-                reset: { type: 'boolean', description: 'Reset database (delete existing)', default: false },
+                reset: { type: 'boolean', description: 'Reset the open database (drop all tables, then recreate the schema)', default: false },
             },
         },
     },
@@ -283,6 +345,7 @@ const tools = [
             properties: {
                 items: {
                     type: 'array',
+                    maxItems: 1000,
                     items: {
                         type: 'object',
                         properties: {
@@ -307,7 +370,7 @@ const tools = [
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query text' },
-                k: { type: 'number', description: 'Number of results to return', default: 10 },
+                k: { type: 'number', description: 'Number of results to return (max 100)', default: 10, minimum: 1, maximum: 100 },
                 min_similarity: { type: 'number', description: 'Minimum similarity threshold (0-1)', default: 0.0 },
                 filters: {
                     type: 'object',
@@ -369,7 +432,7 @@ const tools = [
             type: 'object',
             properties: {
                 task: { type: 'string', description: 'Task to find similar episodes for' },
-                k: { type: 'number', description: 'Number of episodes to retrieve', default: 5 },
+                k: { type: 'number', description: 'Number of episodes to retrieve (max 100)', default: 5, minimum: 1, maximum: 100 },
                 only_failures: { type: 'boolean', description: 'Only retrieve failures' },
                 only_successes: { type: 'boolean', description: 'Only retrieve successes' },
                 min_reward: { type: 'number', description: 'Minimum reward threshold' },
@@ -698,6 +761,41 @@ const tools = [
             properties: {},
         },
     },
+    {
+        name: 'agentdb_pattern_feedback',
+        description: 'Record the outcome of using a reasoning pattern. Updates its success rate and average reward, which agentdb_pattern_search ranks by (0.7 similarity + 0.2 success rate + 0.1 reward). Give success, reward, or both.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern_id: { type: 'integer', minimum: 0, description: 'Pattern ID from agentdb_pattern_store or agentdb_pattern_search' },
+                success: { type: 'boolean', description: 'Whether applying the pattern succeeded' },
+                reward: { type: 'number', minimum: 0, maximum: 1, description: 'Reward in [0, 1]; defaults to 1 for success, 0 for failure. A reward alone counts as success when >= 0.5' },
+            },
+            required: ['pattern_id'],
+        },
+    },
+    {
+        name: 'agentdb_skill_feedback',
+        description: 'Record the outcome of using a skill. Updates its uses, success rate, average reward and (optionally) latency, which skill_search ranks by. Give success, reward, or both.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skill_id: { type: 'integer', minimum: 0, description: 'Skill ID from skill_create or skill_search' },
+                success: { type: 'boolean', description: 'Whether the skill succeeded' },
+                reward: { type: 'number', minimum: 0, maximum: 1, description: 'Reward in [0, 1]; defaults to 1 for success, 0 for failure. A reward alone counts as success when >= 0.5' },
+                latency_ms: { type: 'number', minimum: 0, description: 'Observed latency in milliseconds (optional)' },
+            },
+            required: ['skill_id'],
+        },
+    },
+    {
+        name: 'agentdb_capabilities',
+        description: 'Report what this AgentDB server is running on: native accelerator features that loaded, the vector backend in use and the ones available, the SQL driver, the embedding model and dimension (and whether it is the hash fallback), and the ranking defaults. Read-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
     {
         name: 'agentdb_clear_cache',
         description: 'Clear query cache to refresh statistics and search results',
@@ -829,24 +927,65 @@ const tools = [
             required: ['patterns'],
         },
     },
+    // ==========================================================================
+    // ADR-073 — SOTA roadmap additions (causal traversal · batch delete · on-demand consolidation)
+    // ==========================================================================
+    {
+        name: 'causal_traverse',
+        description: 'Walk the causal graph between two memories. Returns the chain of causal links (with confidence and uplift) up to max_depth hops. Use this to answer "WHY does this memory matter?" / "what chain of causes led here?" — the primary explainability surface beyond a single recall. Wraps CausalMemoryGraph.getCausalChain().',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from_memory_id: { type: 'number', description: 'Starting memory id (the cause / earlier node)' },
+                to_memory_id: { type: 'number', description: 'Ending memory id (the effect / target node)' },
+                max_depth: { type: 'number', description: 'Maximum hops along the causal chain', default: 5, minimum: 1, maximum: 20 },
+            },
+            required: ['from_memory_id', 'to_memory_id'],
+        },
+    },
+    {
+        name: 'agentdb_delete_batch',
+        description: 'Delete many episode/pattern rows by ID list in a single transaction. Faster and safer than looping `agentdb_delete` (one transaction, validated IDs, atomic). Use for bulk cleanup of old sessions / failed experiments.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ids: { type: 'array', items: { type: 'number' }, description: 'Episode IDs to delete (1–1000 per call)', minItems: 1, maxItems: 1000 },
+                table: { type: 'string', enum: ['episodes', 'reasoning_patterns'], default: 'episodes', description: 'Target table (whitelist-validated)' },
+            },
+            required: ['ids'],
+        },
+    },
+    {
+        name: 'consolidate_now',
+        description: 'Run the NightlyLearner consolidation pass on demand — discovers new causal edges, prunes low-confidence edges, and promotes high-reward episodes into skills. Use after a batch of new episodes or when you want consolidated memories available immediately (instead of waiting for a scheduled run). Returns a summary report.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: { type: 'string', description: 'Optional: limit consolidation to this session' },
+            },
+        },
+    },
 ];
 // ============================================================================
 // Tool Handlers
 // ============================================================================
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools };
+    return { tools: filterMcpTools(tools, toolPolicy) };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
+        if (!isMcpToolAllowed(name, toolPolicy)) {
+            throw new Error(`MCP tool "${name}" is not permitted by the active AgentDB capability policy`);
+        }
         switch (name) {
             // ======================================================================
             // CORE VECTOR DB OPERATIONS
             // ======================================================================
             case 'agentdb_init': {
-                const targetDbPath = args?.db_path || dbPath;
-                if (args?.reset && fs.existsSync(targetDbPath)) {
-                    fs.unlinkSync(targetDbPath);
+                // Only ever the open database: a caller-supplied path is never touched
+                if (args?.reset === true) {
+                    resetDatabaseTables(db);
                 }
                 // Initialize schema
                 initializeSchema(db);
@@ -856,7 +995,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         {
                             type: 'text',
                             text: `✅ AgentDB initialized successfully!\n` +
-                                `📍 Database: ${targetDbPath}\n` +
+                                `📍 Database: ${dbPath}\n` +
                                 `📊 Tables created: ${stats.count}\n` +
                                 `⚙️  Optimizations: WAL mode, cache_size=64MB\n` +
                                 `🧠 Embedding service: ${embeddingService.constructor.name} ready`,
@@ -896,7 +1035,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'agentdb_insert_batch': {
-                const items = args?.items || [];
+                const items = validateArrayLength(args?.items ?? [], 'items', 0, MAX_INSERT_BATCH_ITEMS);
                 const batchSize = args?.batch_size || 100;
                 const episodes = items.map((item) => ({
                     sessionId: item.session_id || 'default',
@@ -931,7 +1070,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case 'agentdb_search': {
                 const queryText = args?.query;
-                const k = args?.k || 10;
+                const k = Math.floor(validateNumericRange(args?.k ?? 10, 'k', 1, MAX_SEARCH_K));
                 const minSimilarity = args?.min_similarity || 0.0;
                 const filters = args?.filters;
                 const query = {
@@ -1055,7 +1194,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'reflexion_retrieve': {
                 const episodes = await reflexion.retrieveRelevant({
                     task: args?.task,
-                    k: args?.k || 5,
+                    k: Math.floor(validateNumericRange(args?.k ?? 5, 'k', 1, MAX_SEARCH_K)),
                     onlyFailures: args?.only_failures,
                     onlySuccesses: args?.only_successes,
                     minReward: args?.min_reward,
@@ -1352,6 +1491,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `Top Results:\n` +
                                 patterns.slice(0, 5).map((p, i) => `${i + 1}. [ID: ${p.id}] ${p.taskType}\n` +
                                     `   Similarity: ${(p.similarity || 0).toFixed(3)}\n` +
+                                    (p.score !== undefined ? `   Rank score: ${p.score.toFixed(3)} (similarity + outcome)\n` : '') +
                                     `   Success Rate: ${(p.successRate * 100).toFixed(1)}%\n` +
                                     `   Approach: ${p.approach.substring(0, 80)}${p.approach.length > 80 ? '...' : ''}\n` +
                                     `   Uses: ${p.uses || 0}`).join('\n\n') +
@@ -1396,6 +1536,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'agentdb_pattern_feedback': {
+                const patternId = validateId(args?.pattern_id, 'pattern_id');
+                const { success, reward } = validateFeedback(args);
+                if (!(await reasoningBank.recordOutcome(patternId, success, reward))) {
+                    throw new ValidationError(`Pattern ${patternId} not found`, 'NOT_FOUND', 'pattern_id');
+                }
+                caches.stats.clear();
+                const pattern = reasoningBank.getPattern(patternId);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                patternId,
+                                recorded: { success, reward: reward ?? (success ? 1 : 0) },
+                                uses: pattern.uses,
+                                successRate: pattern.successRate,
+                                avgReward: pattern.avgReward,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case 'agentdb_skill_feedback': {
+                const skillId = validateId(args?.skill_id, 'skill_id');
+                const { success, reward } = validateFeedback(args);
+                const latencyMs = args?.latency_ms === undefined || args?.latency_ms === null
+                    ? undefined
+                    : validateNumericRange(args.latency_ms, 'latency_ms', 0, MAX_FEEDBACK_LATENCY_MS);
+                if (!skills.recordOutcome(skillId, success, reward, latencyMs)) {
+                    throw new ValidationError(`Skill ${skillId} not found`, 'NOT_FOUND', 'skill_id');
+                }
+                const row = db.prepare('SELECT uses, success_rate, avg_reward, avg_latency_ms FROM skills WHERE id = ?').get(skillId);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                skillId,
+                                recorded: { success, reward: reward ?? (success ? 1 : 0), latencyMs },
+                                uses: row.uses,
+                                successRate: row.success_rate,
+                                avgReward: row.avg_reward,
+                                avgLatencyMs: row.avg_latency_ms,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case 'agentdb_capabilities': {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(await describeCapabilities(), null, 2) }],
+                };
+            }
             case 'agentdb_clear_cache': {
                 const cacheType = args?.cache_type || 'all';
                 let cleared = 0;
@@ -2064,6 +2254,68 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            // ======================================================================
+            // ADR-073 — SOTA roadmap handlers
+            // ======================================================================
+            case 'causal_traverse': {
+                const fromId = args?.from_memory_id;
+                const toId = args?.to_memory_id;
+                const maxDepth = args?.max_depth || 5;
+                const chain = await causalGraph.getCausalChain(fromId, toId, maxDepth);
+                const found = chain && Array.isArray(chain.edges) ? chain.edges.length > 0 : false;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: found
+                                ? `🔗 Causal chain ${fromId} → ${toId} (max ${maxDepth} hops):\n${JSON.stringify(chain, null, 2)}`
+                                : `❌ No causal chain found between memory #${fromId} and #${toId} within ${maxDepth} hops.`,
+                        }],
+                };
+            }
+            case 'agentdb_delete_batch': {
+                const ids = args?.ids || [];
+                const requestedTable = args?.table || 'episodes';
+                const allowedTables = new Set(['episodes', 'reasoning_patterns']);
+                if (!allowedTables.has(requestedTable)) {
+                    throw new Error(`Invalid table: ${requestedTable}`);
+                }
+                if (ids.length === 0) {
+                    return { content: [{ type: 'text', text: '⚠️  No IDs supplied — nothing to delete.' }] };
+                }
+                // Validate each id is a positive integer (defense in depth)
+                const safeIds = ids.map((raw) => {
+                    const n = Number(raw);
+                    if (!Number.isInteger(n) || n <= 0)
+                        throw new Error(`Invalid id: ${raw}`);
+                    return n;
+                });
+                const placeholders = safeIds.map(() => '?').join(',');
+                // requestedTable is whitelist-checked above; parameterising values via ?.
+                const stmt = db.prepare(`DELETE FROM ${requestedTable} WHERE id IN (${placeholders})`);
+                const result = stmt.run(...safeIds);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🗑️  Batch delete from \`${requestedTable}\`: ${result.changes}/${safeIds.length} rows removed (atomic).`,
+                        }],
+                };
+            }
+            case 'consolidate_now': {
+                const sessionId = args?.session_id;
+                const t0 = Date.now();
+                // Prefer the session-scoped path when sessionId is given.
+                const report = sessionId
+                    ? await learner.consolidateEpisodes(sessionId)
+                    : await learner.run();
+                const ms = Date.now() - t0;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🌙 Consolidation complete${sessionId ? ` (session=${sessionId})` : ''} in ${ms}ms\n` +
+                                JSON.stringify(report, null, 2),
+                        }],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -2099,13 +2351,63 @@ async function main() {
     const keepAlive = setInterval(() => {
         // Empty interval just to keep event loop alive
     }, 1000 * 60 * 60); // Every hour (basically forever)
-    // Handle graceful shutdown
-    const shutdown = () => {
+    // Periodic auto-save: Save database every 5 minutes to prevent data loss
+    const autoSaveInterval = setInterval(() => {
+        try {
+            if (db && typeof db.save === 'function') {
+                db.save();
+                console.error('💾 Auto-saved database to', dbPath);
+            }
+        }
+        catch (error) {
+            console.error('❌ Auto-save failed:', error.message);
+        }
+    }, 5 * 60 * 1000); // 5 minutes
+    // Handle graceful shutdown with database persistence
+    const shutdown = async () => {
+        console.error('🔄 Shutting down AgentDB MCP Server...');
+        // Clear intervals
         clearInterval(keepAlive);
-        process.exit(0);
+        clearInterval(autoSaveInterval);
+        let persistenceFailed = false;
+        // Save database before exit
+        try {
+            if (db && typeof db.save === 'function') {
+                console.error('💾 Saving database to', dbPath);
+                await db.save();
+                console.error('✅ Database saved successfully');
+            }
+        }
+        catch (error) {
+            persistenceFailed = true;
+            console.error('❌ Error saving database:', error.message);
+        }
+        // Close database connection. close() persists sql.js itself, so only call
+        // it after save when save succeeded; a failed optimistic save must not be
+        // retried against the same stale snapshot.
+        try {
+            if (!persistenceFailed && db && typeof db.close === 'function') {
+                db.close();
+                console.error('✅ Database connection closed');
+            }
+        }
+        catch (error) {
+            persistenceFailed = true;
+            console.error('❌ Error closing database:', error.message);
+        }
+        process.exit(persistenceFailed ? 1 : 0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    // Handle unexpected exits
+    process.on('uncaughtException', (error) => {
+        console.error('❌ Uncaught exception:', error);
+        shutdown();
+    });
+    process.on('unhandledRejection', (error) => {
+        console.error('❌ Unhandled rejection:', error);
+        shutdown();
+    });
     // Return a never-resolving promise
     return new Promise(() => {
         // The setInterval above keeps the event loop alive