claude-flow 3.47.1 → 3.48.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-tools.js

@@ -1,15 +1,4 @@
-/**
- * AgentDB MCP Tools — Phase 6 of ADR-053
- *
- * Exposes AgentDB v3 controller operations as MCP tools.
- * Provides direct access to ReasoningBank, CausalGraph, SkillLibrary,
- * AttestationLog, and bridge health through the MCP protocol.
- *
- * Security: All handlers validate input types, enforce length bounds,
- * and sanitize error messages before returning to MCP callers.
- *
- * @module v3/cli/mcp-tools/agentdb-tools
- */
+import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feedback-patterns.js';
 import { validateIdentifier, validateText } from './validate-input.js';
 // ===== Shared validation helpers =====
 const MAX_STRING_LENGTH = 100_000; // 100KB max for any string input
@@ -66,12 +55,6 @@ async function getBridge() {
 // Lazy-cached modules used by graph-query / graph-pathfinder dispatch.
 // Caching the resolved namespace avoids per-call dynamic-import overhead
 // in the ADR-130 hot path (smoke harness measures elapsedMs of every call).
-let graphBackendMod = null;
-async function getGraphBackend() {
-    if (!graphBackendMod)
-        graphBackendMod = await import('../ruvector/graph-backend.js');
-    return graphBackendMod;
-}
 let graphEdgeWriterMod = null;
 async function getGraphEdgeWriter() {
     if (!graphEdgeWriterMod)
@@ -396,6 +379,7 @@ export const agentdbFeedback = {
         type: 'object',
         properties: {
             taskId: { type: 'string', description: 'Task identifier' },
+            patterns: feedbackPatternsSchema,
             success: { type: 'boolean', description: 'Whether task succeeded' },
             quality: { type: 'number', description: 'Quality score (0-1)' },
             agent: { type: 'string', description: 'Agent that performed the task' },
@@ -415,9 +399,11 @@ export const agentdbFeedback = {
             const taskId = validateString(params.taskId, 'taskId', 500);
             if (!taskId)
                 return { success: false, error: 'taskId is required (non-empty string, max 500 chars)' };
+            const patterns = validateFeedbackPatterns(params.patterns);
             const bridge = await getBridge();
             const result = await bridge.bridgeRecordFeedback({
                 taskId,
+                patterns,
                 success: params.success === true,
                 quality: validateScore(params.quality, 0.85),
                 agent: validateString(params.agent, 'agent', 200) ?? undefined,
@@ -802,21 +788,18 @@ export const agentdbHierarchicalRecall = {
 // ===== agentdb_consolidate — Run memory consolidation =====
 export const agentdbConsolidate = {
     name: 'agentdb_consolidate',
-    description: 'Run memory consolidation to promote entries across tiers and compress old data Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
+    description: 'Request memory consolidation. Use when checking whether AgentDB can consolidate retained memories; native file edits cannot perform controller consolidation. Currently returns unsupported when the installed controller is a no-op stub; no entries are promoted or compressed in that case.',
     inputSchema: {
         type: 'object',
-        properties: {
-            minAge: { type: 'number', description: 'Minimum age in hours since store (optional)' },
-            maxEntries: { type: 'number', description: 'Maximum entries to consolidate (optional)' },
-        },
+        properties: {},
     },
     handler: async (params) => {
         try {
+            if (Object.keys(params).length > 0) {
+                return { success: false, status: 'unsupported', error: 'agentdb_consolidate does not support options' };
+            }
             const bridge = await getBridge();
-            const result = await bridge.bridgeConsolidate({
-                minAge: typeof params.minAge === 'number' ? Math.max(0, params.minAge) : undefined,
-                maxEntries: validatePositiveInt(params.maxEntries, 1000, 10_000),
-            });
+            const result = await bridge.bridgeConsolidate({});
             return result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
         }
         catch (error) {
@@ -1060,7 +1043,7 @@ export const agentdbCausalNodeDelete = {
 };
 export const agentdbGraphQuery = {
     name: 'agentdb_graph-query',
-    description: 'Unified graph traversal across the knowledge graph (ADR-130). Native graph-node k-hop cannot filter by relation and returns an explicit unsupported error for that request; the SQL fallback can filter by relation. Inspect appliedDepth/truncated because SQL is bounded at 3 hops. Semantic and PageRank modes use their own backends. Use when you need structured graph traversal beyond flat memory search.',
+    description: 'Unified graph traversal across the knowledge graph (ADR-130). K-hop queries read committed graph_edges relationships through SQL; a separately populated native graph is not evidence of retained-history coverage. Inspect appliedDepth/truncated because SQL is bounded at 3 hops. maxNodesVisited bounds returned rows, not traversal work or elapsed time. Semantic and PageRank modes use their own backends. Use when you need relationship traversal beyond flat memory search.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1101,53 +1084,38 @@ export const agentdbGraphQuery = {
             }
             const budgetRaw = (params.complexityBudget ?? {});
             const budget = {
-                maxNodesVisited: budgetRaw.maxNodesVisited ?? 10_000,
-                maxDepth: budgetRaw.maxDepth ?? 5,
+                maxNodesVisited: validatePositiveInt(budgetRaw.maxNodesVisited, 10_000, 10_000),
+                maxDepth: validatePositiveInt(budgetRaw.maxDepth, 5, 5),
                 maxMillis: budgetRaw.maxMillis ?? 50,
                 maxMemoryMB: budgetRaw.maxMemoryMB ?? 32,
             };
-            const depth = Math.min(validatePositiveInt(params.depth, 2, budget.maxDepth), budget.maxDepth);
+            const requestedDepth = validatePositiveInt(params.depth, 2, 5);
+            const depth = Math.min(requestedDepth, budget.maxDepth);
             const topK = validatePositiveInt(params.topK, 10, MAX_TOP_K);
             const relation = validateString(params.relation, 'relation', 200) ?? undefined;
             // ── k-hop mode ──────────────────────────────────────────────────────────
             if (mode === 'k-hop') {
-                // graph-node's kHopNeighbors API has no relation parameter. Its graph
-                // and the SQL graph are separate stores, and SQL writes can be async;
-                // switching stores here could report a false negative. Refuse the
-                // unsupported native query instead of silently widening it.
-                try {
-                    const graphBackend = await getGraphBackend();
-                    if (await graphBackend.isGraphBackendAvailable()) {
-                        if (relation) {
-                            return { success: false, error: 'Native graph-node k-hop does not support relation filtering', unsupported: 'relation', mode, nodeId, relation, backend: 'graph-node' };
-                        }
-                        const neighbors = await graphBackend.getNeighbors(nodeId, depth);
-                        return {
-                            success: true, mode, nodeId, depth, appliedDepth: depth,
-                            results: neighbors.map(id => ({ nodeId: id })),
-                            count: neighbors.length,
-                            backend: 'graph-node',
-                            elapsedMs: Date.now() - t0,
-                        };
-                    }
-                }
-                catch { /* fall through to SQL */ }
-                // SQL CTE fallback is bounded at depth 3. Report that bound so callers
-                // cannot mistake an incomplete depth-5 cycle check for a complete one.
+                // #3315: graph-node and retained SQL are populated independently.
+                // Native availability does not establish historical coverage. Query
+                // the committed relationship source, and fail if it cannot be read.
                 try {
                     const { getBridgeDb } = await getGraphEdgeWriter();
                     const db = await getBridgeDb();
                     if (db) {
                         const appliedDepth = Math.min(depth, 3);
-                        const cteSql = buildKHopCTE(nodeId, appliedDepth, relation, budget.maxNodesVisited);
+                        const cteSql = buildKHopCTE(nodeId, appliedDepth, relation, budget.maxNodesVisited + 1);
                         // graph-edge-writer returns a better-sqlite3 Database after #2431.
                         // `db.exec(sql, params)` (sql.js style) is a runner with no result
                         // on better-sqlite3 — use `prepare(sql).raw().all(...)` to get the
                         // same array-of-arrays shape the downstream code expects.
-                        const rows = db.prepare(cteSql).raw().all();
+                        const allRows = db.prepare(cteSql).raw().all();
+                        const resultLimitReached = allRows.length > budget.maxNodesVisited;
+                        const rows = allRows.slice(0, budget.maxNodesVisited);
+                        const depthLimited = appliedDepth < requestedDepth;
                         return {
-                            success: true, mode, nodeId, depth, appliedDepth,
-                            ...(appliedDepth < depth ? { truncated: true } : {}),
+                            success: true, mode, nodeId, depth, requestedDepth, appliedDepth,
+                            depthLimited, resultLimitReached, truncated: depthLimited || resultLimitReached,
+                            resultLimit: budget.maxNodesVisited,
                             results: rows.map((r) => ({ nodeId: r[0], depth: r[1] })),
                             count: rows.length,
                             backend: 'sql-cte',
@@ -1155,11 +1123,10 @@ export const agentdbGraphQuery = {
                         };
                     }
                 }
-                catch { /* db unavailable */ }
-                if (relation) {
-                    return { success: false, error: 'Relation-filtered k-hop query requires the SQL graph_edges backend', mode, nodeId, relation };
+                catch (error) {
+                    return { success: false, error: `Retained SQL graph query failed: ${sanitizeError(error)}`, mode, nodeId };
                 }
-                return { success: false, error: 'No graph backend available for k-hop query', mode, nodeId };
+                return { success: false, error: 'Retained SQL graph_edges backend is unavailable for k-hop query', mode, nodeId };
             }
             // ── semantic mode ────────────────────────────────────────────────────────
             if (mode === 'semantic') {

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.d.ts

@@ -1,7 +1,3 @@
-/**
- * Hooks MCP Tools
- * Provides intelligent hooks functionality via MCP protocol
- */
 import { type MCPTool } from './types.js';
 import { type RouterEmbedderKind } from '../ruvector/router-embedder.js';
 /**

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -1,3 +1,4 @@
+import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feedback-patterns.js';
 /**
  * Hooks MCP Tools
  * Provides intelligent hooks functionality via MCP protocol
@@ -410,8 +411,75 @@ async function getLoRAAdapter() {
     }
     return loraAdapter;
 }
-// In-memory trajectory tracking (persisted on end)
+// Cache pending trajectories; the existing memory store also persists checkpoints.
 const activeTrajectories = new Map();
+const dirtyTrajectories = new Set();
+const trajectoryOperations = new Map();
+/** Serialize read/modify/checkpoint operations for a trajectory in this process. */
+async function withTrajectoryOperation(id, operation) {
+    const previous = trajectoryOperations.get(id) ?? Promise.resolve();
+    let release;
+    const gate = new Promise(resolve => { release = resolve; });
+    const current = previous.then(() => gate);
+    trajectoryOperations.set(id, current);
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+        if (trajectoryOperations.get(id) === current)
+            trajectoryOperations.delete(id);
+    }
+}
+async function persistPendingTrajectory(trajectory) {
+    dirtyTrajectories.add(trajectory.id);
+    try {
+        const store = await getRealStoreFunction();
+        const result = await store?.({
+            key: `trajectory-pending-${trajectory.id}`, value: JSON.stringify(trajectory),
+            namespace: 'trajectories', tags: [trajectory.agent, 'pending', 'sona-trajectory'], upsert: true,
+        });
+        if (result?.success === true)
+            dirtyTrajectories.delete(trajectory.id);
+        return result?.success === true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadPendingTrajectory(id) {
+    try {
+        const { getEntry } = await import('../memory/memory-initializer.js');
+        // A completed record is authoritative even if pending-record cleanup failed
+        // or another process still has an old cache entry.
+        const completed = await getEntry({ key: `trajectory-${id}`, namespace: 'trajectories' });
+        if (completed.success && completed.found) {
+            activeTrajectories.delete(id);
+            dirtyTrajectories.delete(id);
+            return undefined;
+        }
+        // Failed checkpoints must not erase already-acknowledged live steps.
+        // Clean caches still reload so another process's later checkpoint is seen.
+        if (dirtyTrajectories.has(id) && activeTrajectories.has(id))
+            return activeTrajectories.get(id);
+        const pending = await getEntry({ key: `trajectory-pending-${id}`, namespace: 'trajectories' });
+        if (pending.success && pending.found) {
+            const value = JSON.parse(pending.entry?.content ?? 'null');
+            if (!value || value.id !== id || typeof value.task !== 'string' || typeof value.agent !== 'string'
+                || typeof value.startedAt !== 'string' || !Number.isFinite(Date.parse(value.startedAt))
+                || !Array.isArray(value.steps) || !value.steps.every((step) => step
+                && typeof step.action === 'string' && typeof step.result === 'string'
+                && typeof step.quality === 'number' && Number.isFinite(step.quality)
+                && typeof step.timestamp === 'string'))
+                return undefined;
+            activeTrajectories.set(id, value);
+            return value;
+        }
+    }
+    catch { /* store unavailable: retain same-process best-effort tracking */ }
+    return activeTrajectories.get(id);
+}
 const MEMORY_DIR = '.claude-flow/memory';
 const MEMORY_FILE = 'store.json';
 function getMemoryPath() {
@@ -897,13 +965,19 @@ export const hooksPostCommand = {
         properties: {
             command: { type: 'string', description: 'Executed command' },
             exitCode: { type: 'number', description: 'Command exit code' },
+            success: { type: 'boolean', description: 'Explicit execution outcome; false records a failure even without a nonzero exit code' },
+            ttl: { type: 'integer', minimum: 1, maximum: 2147483647, description: 'Command history lifetime in seconds (default: 30 days)' },
         },
         required: ['command'],
     },
     handler: async (params) => {
         const command = params.command;
         const exitCode = params.exitCode || 0;
-        const success = exitCode === 0;
+        const success = exitCode === 0 && params.success !== false;
+        const ttl = params.ttl ?? 30 * 24 * 60 * 60;
+        if (typeof ttl !== 'number' || !Number.isSafeInteger(ttl) || ttl < 1 || ttl > 2147483647) {
+            return { success: false, recorded: false, error: 'ttl must be a positive integer number of seconds (at most 2147483647)' };
+        }
         {
             const v = validateText(command, 'command');
             if (!v.valid)
@@ -916,21 +990,35 @@ export const hooksPostCommand = {
         let _storedIn = 'none';
         try {
             const bridge = await import('../memory/memory-bridge.js');
-            await bridge.bridgeStoreEntry({
+            const stored = await bridge.bridgeStoreEntry({
                 key: `cmd-${Date.now()}`,
                 value: JSON.stringify({ command, exitCode, success }),
                 namespace: 'commands',
                 tags: [success ? 'success' : 'error'],
+                ttl,
+                generateEmbeddingFlag: false,
             });
+            if (!stored?.success)
+                throw new Error(stored?.error || 'Native bridge did not store the command');
             _storedIn = 'agentdb';
         }
         catch {
             // AgentDB not available — store in JSON
             try {
                 const store = loadMemoryStore();
-                const key = `cmd-${Date.now()}`;
-                store.entries[key] = { key, value: JSON.stringify({ command, exitCode, success }), namespace: 'commands', createdAt: new Date().toISOString() };
-                const memDir = resolve(MEMORY_DIR);
+                const now = Date.now();
+                for (const [entryKey, entry] of Object.entries(store.entries)) {
+                    if (entry.namespace === 'commands' && entry.expiresAt && Date.parse(entry.expiresAt) <= now) {
+                        delete store.entries[entryKey];
+                    }
+                }
+                const key = `cmd-${now}`;
+                store.entries[key] = {
+                    key, value: JSON.stringify({ command, exitCode, success }), namespace: 'commands',
+                    storedAt: new Date(now).toISOString(), lastAccessed: new Date(now).toISOString(), accessCount: 0,
+                    expiresAt: new Date(now + ttl * 1000).toISOString(),
+                };
+                const memDir = dirname(getMemoryPath());
                 if (!existsSync(memDir))
                     mkdirSync(memDir, { recursive: true });
                 writeFileSync(getMemoryPath(), JSON.stringify(store, null, 2), 'utf-8');
@@ -1444,9 +1532,10 @@ export const hooksPostTask = {
         type: 'object',
         properties: {
             taskId: { type: 'string', description: 'Task identifier' },
+            patterns: feedbackPatternsSchema,
             success: { type: 'boolean', description: 'Whether task was successful' },
             agent: { type: 'string', description: 'Agent that completed the task' },
-            quality: { type: 'number', description: 'Quality score (0-1)' },
+            quality: { type: 'number', minimum: 0, maximum: 1, description: 'Quality score (0-1)' },
             task: { type: 'string', description: 'Task description text (used for learning keyword extraction)' },
             duration: { type: 'number', description: 'Observed task duration in milliseconds (used by pheromone-adaptive topology)' },
             latencyBudgetMs: { type: 'number', description: 'Latency budget used to normalize duration (default 60000ms)' },
@@ -1463,8 +1552,19 @@ export const hooksPostTask = {
         const taskId = params.taskId;
         const success = params.success !== false;
         const agent = params.agent;
-        const quality = params.quality || (success ? 0.85 : 0.3);
+        if (params.quality !== undefined && (typeof params.quality !== 'number'
+            || !Number.isFinite(params.quality) || params.quality < 0 || params.quality > 1)) {
+            return { success: false, error: 'quality must be a finite number between 0 and 1' };
+        }
+        const quality = params.quality === undefined ? (success ? 0.85 : 0.3) : params.quality;
         const startTime = Date.now();
+        let patterns;
+        try {
+            patterns = validateFeedbackPatterns(params.patterns);
+        }
+        catch (error) {
+            return { success: false, error: error.message };
+        }
         {
             const v = validateIdentifier(taskId, 'taskId');
             if (!v.valid)
@@ -1502,7 +1602,7 @@ export const hooksPostTask = {
                 quality,
                 agent,
                 duration: params.duration || undefined,
-                patterns: params.patterns || undefined,
+                patterns,
                 // ADR-147 P2: forward spawn-tree lineage so it lands in feedback + memory
                 parentAgentId,
                 depth,
@@ -2754,9 +2854,8 @@ export const hooksIntelligenceReset = {
                 // Directory read failed
             }
         }
-        // Clear in-memory trajectories
-        cleared.trajectories = activeTrajectories.size;
-        activeTrajectories.clear();
+        // Reset learned state without abandoning tasks still recording outcomes.
+        cleared.trajectories = 0;
         return {
             reset: true,
             cleared,
@@ -2815,27 +2914,15 @@ export const hooksTrajectoryStart = {
             getTrajectoryTree().openTrajectory({ sessionId, trajectoryId, task, agent });
         }
         catch { /* prototype path — never blocks trajectory recording */ }
-        // Persist pending trajectory to disk so it survives MCP restarts
-        const storeFn = await getRealStoreFunction();
-        if (storeFn) {
-            try {
-                await storeFn({
-                    key: `trajectory-pending-${trajectoryId}`,
-                    value: JSON.stringify(trajectory),
-                    namespace: 'trajectories',
-                    tags: [agent, 'pending', 'sona-trajectory'],
-                });
-            }
-            catch {
-                // Best-effort persistence — trajectory still lives in-memory
-            }
-        }
+        // Checkpoint before handing the id to another process.
+        const persisted = await persistPendingTrajectory(trajectory);
         return {
             trajectoryId,
             task,
             agent,
             started: startedAt,
             status: 'recording',
+            persisted,
             implementation: 'real-trajectory-tracking',
             activeCount: activeTrajectories.size,
         };
@@ -2850,17 +2937,21 @@ export const hooksTrajectoryStep = {
             trajectoryId: { type: 'string', description: 'Trajectory ID' },
             action: { type: 'string', description: 'Action taken' },
             result: { type: 'string', description: 'Action result' },
-            quality: { type: 'number', description: 'Quality score (0-1)' },
+            quality: { type: 'number', minimum: 0, maximum: 1, description: 'Quality score (0-1)' },
         },
         required: ['trajectoryId', 'action'],
     },
-    handler: async (params) => {
+    handler: async (params) => withTrajectoryOperation(params.trajectoryId, async () => {
         const trajectoryId = params.trajectoryId;
         // #14: scrub extended-thinking blocks so reasoning tokens don't contaminate
         // the learning signal (DISTILL embeds this text).
         const action = scrubReasoningBlocks(params.action);
         const result = scrubReasoningBlocks(params.result || 'success');
-        const quality = params.quality || 0.85;
+        if (params.quality !== undefined && (typeof params.quality !== 'number'
+            || !Number.isFinite(params.quality) || params.quality < 0 || params.quality > 1)) {
+            return { success: false, error: 'quality must be a finite number between 0 and 1' };
+        }
+        const quality = params.quality === undefined ? 0.85 : params.quality;
         const timestamp = new Date().toISOString();
         const stepId = `step-${Date.now()}`;
         {
@@ -2874,7 +2965,7 @@ export const hooksTrajectoryStep = {
                 return { success: false, error: v.error };
         }
         // Add step to real trajectory if it exists
-        const trajectory = activeTrajectories.get(trajectoryId);
+        const trajectory = await loadPendingTrajectory(trajectoryId);
         if (trajectory) {
             trajectory.steps.push({
                 action,
@@ -2883,6 +2974,7 @@ export const hooksTrajectoryStep = {
                 timestamp,
             });
         }
+        const persisted = trajectory ? await persistPendingTrajectory(trajectory) : false;
         // MAGE-style execution-state-tree mirror (prototype, non-fatal)
         try {
             const { getTrajectoryTree } = await import('../ruvector/trajectory-tree.js');
@@ -2914,11 +3006,12 @@ export const hooksTrajectoryStep = {
             result,
             quality,
             recorded: !!trajectory,
+            persisted,
             timestamp,
             totalSteps: trajectory?.steps.length || 0,
             implementation: trajectory ? 'real-step-recording' : 'trajectory-not-found',
         };
-    },
+    }),
 };
 export const hooksTrajectoryEnd = {
     name: 'hooks_intelligence_trajectory-end',
@@ -2932,7 +3025,7 @@ export const hooksTrajectoryEnd = {
         },
         required: ['trajectoryId'],
     },
-    handler: async (params) => {
+    handler: async (params) => withTrajectoryOperation(params.trajectoryId, async () => {
         const trajectoryId = params.trajectoryId;
         {
             const v = validateIdentifier(trajectoryId, 'trajectoryId');
@@ -2944,7 +3037,7 @@ export const hooksTrajectoryEnd = {
         const endedAt = new Date().toISOString();
         const startTime = Date.now();
         // Get and finalize real trajectory
-        const trajectory = activeTrajectories.get(trajectoryId);
+        const trajectory = await loadPendingTrajectory(trajectoryId);
         let persistResult = { success: false };
         if (trajectory) {
             trajectory.success = success;
@@ -2970,8 +3063,17 @@ export const hooksTrajectoryEnd = {
                     persistResult = { success: false, error: error instanceof Error ? error.message : String(error) };
                 }
             }
-            // Remove from active trajectories
-            activeTrajectories.delete(trajectoryId);
+            // Failed writes remain retryable. A completed row prevents stale pending
+            // data from being replayed even if cleanup itself fails.
+            if (persistResult.success) {
+                activeTrajectories.delete(trajectoryId);
+                dirtyTrajectories.delete(trajectoryId);
+                try {
+                    const { deleteEntry } = await import('../memory/memory-initializer.js');
+                    await deleteEntry({ key: `trajectory-pending-${trajectoryId}`, namespace: 'trajectories' });
+                }
+                catch { /* completed record is the replay guard */ }
+            }
         }
         // MAGE-style execution-state-tree mirror (prototype, non-fatal)
         try {
@@ -3187,7 +3289,7 @@ export const hooksTrajectoryEnd = {
                 ? `SONA learned pattern "${sonaResult.patternKey}" with ${(sonaResult.confidence * 100).toFixed(1)}% confidence`
                 : (persistResult.success ? 'Trajectory persisted for future learning' : (persistResult.error || 'Trajectory not found')),
         };
-    },
+    }),
 };
 // Pattern store/search hooks - REAL implementation using storeEntry
 export const hooksPatternStore = {