claude-flow 3.47.1 → 3.49.0

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() {
@@ -654,12 +722,41 @@ const KEYWORD_MATCHERS = Object.entries(KEYWORD_PATTERNS).map(([keyword, result]
     const body = /[\s/]/.test(keyword) ? escaped : `${escaped}(?:s|es|ing|ed)?`;
     return { regex: new RegExp(`\\b${body}\\b`, 'i'), result };
 });
+/**
+ * Confidence for a task nothing matched (#3567). It must rank below every real
+ * signal: keyword hits are >= 0.8, learned outcomes >= 0.7, and a semantic
+ * match is only eligible above 0.4. Matches the helper router's 0.3 fall-through.
+ */
+export const NO_MATCH_CONFIDENCE = 0.3;
+/** True when the task has at least one letter or digit in any script. */
+export function hasRoutableText(task) {
+    return /[\p{L}\p{N}]/u.test(task);
+}
+// Keyword matchers are English regexes; letters outside Latin script can never hit them.
+const NON_LATIN_LETTER = /(?![A-Za-zÀ-ɏ])\p{L}/u;
+function noMatchNote(task) {
+    if (!hasRoutableText(task))
+        return 'Task has no words to match.';
+    if (NON_LATIN_LETTER.test(task)) {
+        return 'Keyword matchers are English-only, so non-English text cannot match them.';
+    }
+    return 'No keyword or learned pattern matched.';
+}
 /** Exported for tests. */
 export function suggestAgentsForTask(task) {
+    const noMatch = () => ({
+        agents: ['coder', 'researcher', 'tester'],
+        confidence: NO_MATCH_CONFIDENCE,
+        matched: false,
+        reason: 'no-match-default',
+        note: noMatchNote(task),
+    });
+    if (!hasRoutableText(task))
+        return noMatch();
     // Check static keyword patterns first
     for (const { regex, result } of KEYWORD_MATCHERS) {
         if (regex.test(task)) {
-            return result;
+            return { ...result, matched: true };
         }
     }
     // Check runtime-learned patterns from successful task outcomes
@@ -679,11 +776,10 @@ export function suggestAgentsForTask(task) {
         }
         // Require at least 2 keyword overlap to prevent false positives
         if (bestAgent && bestOverlap >= 2) {
-            return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85) };
+            return { agents: [bestAgent], confidence: Math.min(0.6 + bestOverlap * 0.05, 0.85), matched: true };
         }
     }
-    // Default fallback
-    return { agents: ['coder', 'researcher', 'tester'], confidence: 0.7 };
+    return noMatch();
 }
 function assessCommandRisk(command) {
     const warnings = [];
@@ -897,13 +993,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 +1018,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');
@@ -1117,6 +1233,7 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
     let agents;
     let confidence;
     let matchedPattern = '';
+    let noMatchDetail = null;
     // Both static and learned patterns are gated on the same similarity
     // score. Learned patterns additionally require support/reliability as a
     // quality guard, but do NOT need a higher score bar — a learned pattern
@@ -1124,7 +1241,9 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
     // (#2864: a 25pp higher threshold made a top-scoring learned-researcher
     // match at 0.57 lose to a static match at 0.52, discarding the learned
     // store's output on the majority of routes).
-    const eligibleSemantic = semanticResult.find((match) => {
+    // A task with no letters or digits has nothing for the embedder to mean;
+    // any similarity it scores is noise, so it never becomes a semantic match.
+    const eligibleSemantic = !hasRoutableText(task) ? undefined : semanticResult.find((match) => {
         if (match.score <= 0.4)
             return false;
         const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
@@ -1144,9 +1263,16 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
         const suggestion = suggestAgentsForTask(task);
         agents = suggestion.agents;
         confidence = suggestion.confidence;
-        matchedPattern = 'keyword-fallback';
         routingMethod = 'keyword';
-        backendInfo = 'keyword matching';
+        if (suggestion.matched) {
+            matchedPattern = 'keyword-fallback';
+            backendInfo = 'keyword matching';
+        }
+        else {
+            matchedPattern = 'no-match-default';
+            backendInfo = 'keyword matching (no match)';
+            noMatchDetail = suggestion.note ?? 'No pattern matched.';
+        }
     }
     // Determine complexity
     const taskLower = task.toLowerCase();
@@ -1164,6 +1290,9 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
             throughput: routingLatencyMs > 0 ? `${Math.round(1000 / routingLatencyMs)} routes/s` : 'N/A',
         },
         matchedPattern,
+        // #3567: callers branch on `matched`; a no-match result is a default, not a decision.
+        matched: noMatchDetail === null,
+        ...(noMatchDetail !== null ? { reason: 'no-match-default', note: noMatchDetail } : {}),
         semanticMatches: semanticResult.slice(0, 3).map(r => ({
             pattern: r.intent,
             score: Math.round(r.score * 100) / 100,
@@ -1173,15 +1302,18 @@ async function routeTaskLocal(task, context, useSemanticRouter, embedderOverride
             confidence: Math.round(confidence * 100) / 100,
             reason: routingMethod.startsWith('semantic')
                 ? `Semantic similarity to "${matchedPattern}" pattern (${Math.round(confidence * 100)}%)`
-                : `Task contains keywords matching ${agents[0]} specialization`,
+                : noMatchDetail !== null
+                    ? `Nothing matched; default suggestion only. ${noMatchDetail}`
+                    : `Task contains keywords matching ${agents[0]} specialization`,
         },
         alternativeAgents: agents.slice(1).map((agent, i) => ({
             type: agent,
-            confidence: Math.round((confidence - (0.1 * (i + 1))) * 100) / 100,
-            reason: `Alternative agent for ${agent} capabilities`,
+            confidence: Math.max(0, Math.round((confidence - (0.1 * (i + 1))) * 100) / 100),
+            reason: noMatchDetail !== null ? 'Default suggestion (nothing matched)' : `Alternative agent for ${agent} capabilities`,
         })),
         estimatedMetrics: {
-            successProbability: Math.round(confidence * 100) / 100,
+            // No pattern means no basis for a success estimate.
+            successProbability: noMatchDetail !== null ? null : Math.round(confidence * 100) / 100,
             estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
             complexity,
         },
@@ -1418,12 +1550,15 @@ export const hooksPreTask = {
         return {
             taskId,
             description,
+            agentsMatched: suggestion.matched,
             suggestedAgents: suggestion.agents.map((agent, i) => ({
                 type: agent,
                 confidence: suggestion.confidence - (0.05 * i),
-                reason: i === 0
-                    ? `Primary agent for ${agent} tasks based on learned patterns`
-                    : `Alternative agent with ${agent} capabilities`,
+                reason: !suggestion.matched
+                    ? 'Default suggestion (nothing matched)'
+                    : i === 0
+                        ? `Primary agent for ${agent} tasks based on learned patterns`
+                        : `Alternative agent with ${agent} capabilities`,
             })),
             complexity,
             estimatedDuration: complexity === 'high' ? '2-4 hours' : complexity === 'medium' ? '30-60 min' : '10-30 min',
@@ -1444,9 +1579,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 +1599,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 +1649,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,
@@ -1756,8 +1903,34 @@ export const hooksExplain = {
         catch {
             // File unreadable; leave as null
         }
+        // #3567: when nothing matched, say so instead of explaining a match that did not happen.
+        if (!suggestion.matched) {
+            return {
+                task,
+                matched: false,
+                reason: 'no-match-default',
+                explanation: `No keyword or learned pattern matched this task. ${suggestion.note ?? ''} ` +
+                    `"${suggestion.agents[0]}" is a default suggestion, not a routing decision.`.trim(),
+                factors: [
+                    { factor: 'Keyword Match', weight: 0.4, value: null, impact: 'No keyword matched' },
+                    { factor: 'Historical Success', weight: 0.3, value: historicalSuccess, impact: historicalNote },
+                    { factor: 'Agent Availability', weight: 0.2, value: null, impact: 'Agent availability tracking not implemented' },
+                    { factor: 'Task Complexity', weight: 0.1, value: task.length > 100 ? 0.8 : 0.3, impact: 'Complexity assessment' },
+                ],
+                patterns: matchedPatterns,
+                decision: {
+                    agent: suggestion.agents[0],
+                    confidence: suggestion.confidence,
+                    reasoning: [
+                        'No pattern matched; the agent is a default suggestion',
+                        `Confidence ${(suggestion.confidence * 100).toFixed(0)}% is below every real match`,
+                    ],
+                },
+            };
+        }
         return {
             task,
+            matched: true,
             explanation: `The routing decision was made based on keyword analysis of the task description. ` +
                 `The task contains keywords that match the "${suggestion.agents[0]}" specialization with ${(suggestion.confidence * 100).toFixed(0)}% confidence.`,
             factors: [
@@ -2754,9 +2927,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 +2987,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 +3010,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 +3038,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 +3047,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 +3079,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 +3098,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 +3110,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 +3136,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 +3362,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 = {

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

@@ -10,5 +10,12 @@
  * @module v3/cli/mcp-tools/memory-tools
  */
 import type { MCPTool } from './types.js';
+export declare const DANGEROUS_KEY_PATTERN: RegExp;
+/**
+ * #3570: the one key rule for every memory write path (MCP store, CLI store,
+ * import). Plain `/` stays legal (`probe/x`); traversal and shell metacharacters
+ * do not. Returns the error message, or null when the key is acceptable.
+ */
+export declare function memoryKeyError(key: string): string | null;
 export declare const memoryTools: MCPTool[];
 //# sourceMappingURL=memory-tools.d.ts.map