cf-doctor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoxFlow Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# cf-doctor
+
+> Setup validator, auto-fixer, and learning persistence for [claude-flow](https://github.com/ruvnet/claude-flow) + [ruvector](https://github.com/ruvnet/ruvector) integration.
+
+Fixes the top integration-layer bugs that prevent claude-flow and ruvector from working together on Linux/Ubuntu.
+
+## Features
+
+- **Environment validation** — Checks Node.js, pnpm, Rust, @claude-flow/cli, MCP handshake, @ruvector packages, database drivers
+- **Auto-fix mode** — Installs missing packages, creates directories, generates config
+- **Learning persistence** — Q-learning tables, SONA patterns, and episode history survive restarts
+- **MCP server** — Use as a Claude Code MCP server for integrated tooling
+- **Git patches** — Ready-to-apply fixes for broken @ruvector imports in claude-flow
+
+## Quick Start
+
+### CLI
+
+```bash
+# Install globally
+npm install -g cf-doctor
+
+# Run diagnostic
+cf-doctor
+
+# Auto-fix issues
+cf-doctor --fix
+
+# JSON output (for CI)
+cf-doctor --json
+```
+
+### As MCP Server (Claude Code)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cf-doctor": {
+      "command": "node",
+      "args": ["node_modules/cf-doctor/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+This exposes 5 tools to Claude:
+- `cf_doctor_check` — Run environment validation
+- `cf_doctor_fix` — Auto-fix environment issues
+- `cf_recall_episodes` — Search past agent episodes by similarity
+- `cf_store_episode` — Store agent episode for future recall
+- `cf_q_update` — Update Q-learning state
+
+### As Library
+
+```typescript
+import { runDoctor, recallRelevantEpisodes, PersistentSonaEngine } from 'cf-doctor';
+
+// Run diagnostic programmatically
+const result = runDoctor();
+console.log(result.counts); // { green: 7, yellow: 1, red: 1 }
+
+// Recall relevant past episodes
+const episodes = recallRelevantEpisodes('fix authentication bug', 3);
+
+// Persistent SONA engine
+const sona = new PersistentSonaEngine();
+await sona.store('auth-pattern', { type: 'jwt', refresh: true });
+```
+
+### One-liner Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/foxflow/cf-doctor/main/install.sh | bash
+```
+
+## What It Fixes
+
+| Bug | Impact | Fix |
+|-----|--------|-----|
+| `@ruvector/sona` static import crashes | Neural module unusable without WASM | Dynamic import + mock fallback |
+| `@ruvector/attention` static import | Performance tests crash | Dynamic import + mock |
+| claude-flow v2/v3 version mismatch | ruvector hooks fail silently | Auto-detect version, adjust CLI args |
+| Q-learning state lost on restart | Agents don't learn from experience | File-based persistence with atomic writes |
+| SONA patterns lost on restart | Pattern recognition resets every session | JSON persistence with debounced saves |
+| No episode recall | New agents start from scratch | TF-IDF similarity search over past episodes |
+
+## Applying Git Patches
+
+To fix the source imports directly in your clone:
+
+```bash
+# claude-flow patches
+cd claude-flow
+git apply node_modules/cf-doctor/patches/sona-integration.patch
+git apply node_modules/cf-doctor/patches/neural-index.patch
+git apply node_modules/cf-doctor/patches/quick-test.patch
+
+# ruvector patch
+cd ruvector
+git apply node_modules/cf-doctor/patches/version-bridge.patch
+```
+
+Or programmatically:
+
+```typescript
+import { applyPatches } from 'cf-doctor/patches';
+const results = applyPatches('/path/to/claude-flow', 'claude-flow');
+```
+
+## Traffic Light Output
+
+```
+cf-doctor — claude-flow + ruvector installation validator
+
+── Prerequisites ──
+  ✅ Node.js 22.11.0
+  ✅ pnpm 9.15.0
+  ⚠️  Rust not installed (optional)
+
+── Installation Validation ──
+  ✅ @claude-flow/cli v3.1.0
+  ✅ MCP handshake OK
+
+── @ruvector Packages ──
+  ⚠️  0/8 installed (all using mock fallback)
+
+── Environment ──
+  ✅ Directories OK
+  ✅ Database: sql.js (WASM)
+  ✅ Config generated
+
+╔═══════════════════════════════════╗
+║ Result: READY (2 warnings)        ║
+╚═══════════════════════════════════╝
+```
+
+## Claude Code Skills
+
+Drop the skills into your project:
+
+```bash
+cp -r node_modules/cf-doctor/skills/ .claude/skills/
+```
+
+Then use `/cf-doctor`, `/cf-patch`, or `/cf-learn` in Claude Code.
+
+## Development
+
+```bash
+git clone https://github.com/foxflow/cf-doctor
+cd cf-doctor
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/bin/cf-doctor.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { execFileSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const scriptPath = join(__dirname, '..', 'scripts', 'cf-doctor.sh');
+
+try {
+  execFileSync('bash', [scriptPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/dist/doctor.d.ts

@@ -0,0 +1,21 @@
+export interface CheckResult {
+    status: 'green' | 'yellow' | 'red';
+    detail: string;
+}
+export interface DoctorResult {
+    result: 'READY' | 'READY_WITH_WARNINGS' | 'NOT_READY';
+    counts: {
+        green: number;
+        yellow: number;
+        red: number;
+    };
+    checks: Record<string, CheckResult>;
+    summary: Array<{
+        status: string;
+        label: string;
+    }>;
+}
+export declare function runDoctor(options?: {
+    fix?: boolean;
+}): DoctorResult;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,WAAW,CAAC;IACtD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAwBnE"}

package/dist/doctor.js

@@ -0,0 +1,33 @@
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export function runDoctor(options) {
+    const scriptPath = join(__dirname, '..', 'scripts', 'cf-doctor.sh');
+    const args = ['--json'];
+    if (options?.fix)
+        args.push('--fix');
+    try {
+        const output = execFileSync('bash', [scriptPath, ...args], {
+            encoding: 'utf-8',
+            timeout: 30000,
+            env: { ...process.env },
+        });
+        return JSON.parse(output);
+    }
+    catch (err) {
+        // cf-doctor exits 1 on RED checks but still produces valid JSON
+        const execErr = err;
+        if (execErr.stdout) {
+            try {
+                return JSON.parse(execErr.stdout);
+            }
+            catch {
+                // Fall through
+            }
+        }
+        throw new Error(`cf-doctor failed: ${execErr.message ?? 'unknown error'}`);
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AActC,MAAM,UAAU,SAAS,CAAC,OAA2B;IACnD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,OAAO,EAAE,GAAG;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE;YACzD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;YACd,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;SACxB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAiB,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,gEAAgE;QAChE,MAAM,OAAO,GAAG,GAA4C,CAAC;QAC7D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAiB,CAAC;YACpD,CAAC;YAAC,MAAM,CAAC;gBACP,eAAe;YACjB,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qBAAqB,OAAO,CAAC,OAAO,IAAI,eAAe,EAAE,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * cf-doctor — Setup validator and learning persistence for claude-flow + ruvector
+ */
+export { runDoctor, type DoctorResult, type CheckResult } from './doctor.js';
+export { startMCPServer } from './mcp-server.js';
+export { loadQTable, saveQTable, updateQValue, getBestAction, epsilonGreedyAction, } from './persistence/q-table.js';
+export { PersistentSonaEngine, loadSonaPatterns, saveSonaPatterns, registerSonaExitHandler, } from './persistence/sona.js';
+export { saveEpisode, loadEpisodes, recallRelevantEpisodes, formatEpisodesAsContext, } from './persistence/episodes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * cf-doctor — Setup validator and learning persistence for claude-flow + ruvector
+ */
+export { runDoctor } from './doctor.js';
+export { startMCPServer } from './mcp-server.js';
+export { loadQTable, saveQTable, updateQValue, getBestAction, epsilonGreedyAction, } from './persistence/q-table.js';
+export { PersistentSonaEngine, loadSonaPatterns, saveSonaPatterns, registerSonaExitHandler, } from './persistence/sona.js';
+export { saveEpisode, loadEpisodes, recallRelevantEpisodes, formatEpisodesAsContext, } from './persistence/episodes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAuC,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,2BAA2B,CAAC"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Server for cf-doctor
+ *
+ * Exposes tools:
+ * - cf_doctor_check: Run environment validation
+ * - cf_doctor_fix: Auto-fix environment issues
+ * - cf_recall_episodes: Search past agent episodes
+ * - cf_store_episode: Store a new agent episode
+ * - cf_q_update: Update Q-learning state
+ */
+export declare function startMCPServer(): void;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAwMH,wBAAgB,cAAc,IAAI,IAAI,CAsBrC"}

package/dist/mcp-server.js

@@ -0,0 +1,200 @@
+/**
+ * MCP Server for cf-doctor
+ *
+ * Exposes tools:
+ * - cf_doctor_check: Run environment validation
+ * - cf_doctor_fix: Auto-fix environment issues
+ * - cf_recall_episodes: Search past agent episodes
+ * - cf_store_episode: Store a new agent episode
+ * - cf_q_update: Update Q-learning state
+ */
+import { fileURLToPath } from 'url';
+import { createInterface } from 'readline';
+import { runDoctor } from './doctor.js';
+import { recallRelevantEpisodes, saveEpisode, formatEpisodesAsContext } from './persistence/episodes.js';
+import { loadQTable, saveQTable, updateQValue } from './persistence/q-table.js';
+const TOOLS = [
+    {
+        name: 'cf_doctor_check',
+        description: 'Run cf-doctor environment validation. Returns GREEN/YELLOW/RED status for each check.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'cf_doctor_fix',
+        description: 'Run cf-doctor with --fix flag to auto-repair environment issues.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'cf_recall_episodes',
+        description: 'Search past agent episodes by text similarity. Returns relevant episodes for context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                context: { type: 'string', description: 'Text describing what the agent needs to do' },
+                topK: { type: 'number', description: 'Number of episodes to return (default: 5)' },
+            },
+            required: ['context'],
+        },
+    },
+    {
+        name: 'cf_store_episode',
+        description: 'Store a new agent episode for future recall.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'Agent identifier' },
+                input: { type: 'string', description: 'Task description' },
+                outcome: { type: 'string', description: 'What happened' },
+                reward: { type: 'number', description: 'Success score (-1 to 1)' },
+                taskId: { type: 'string', description: 'Optional task ID' },
+            },
+            required: ['agentId', 'input', 'outcome', 'reward'],
+        },
+    },
+    {
+        name: 'cf_q_update',
+        description: 'Update Q-learning table with a state-action-reward observation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                state: { type: 'string', description: 'Current state identifier' },
+                action: { type: 'string', description: 'Action taken' },
+                reward: { type: 'number', description: 'Reward received' },
+            },
+            required: ['state', 'action', 'reward'],
+        },
+    },
+];
+function handleRequest(req) {
+    const id = req.id ?? 0;
+    const { method, params } = req;
+    switch (method) {
+        case 'initialize':
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'cf-doctor', version: '1.0.0' },
+                },
+            };
+        case 'tools/list':
+            return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+        case 'tools/call': {
+            const toolName = (params?.name ?? '');
+            const toolArgs = (params?.arguments ?? {});
+            switch (toolName) {
+                case 'cf_doctor_check': {
+                    const result = runDoctor();
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        },
+                    };
+                }
+                case 'cf_doctor_fix': {
+                    const result = runDoctor({ fix: true });
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        },
+                    };
+                }
+                case 'cf_recall_episodes': {
+                    const episodes = recallRelevantEpisodes(toolArgs.context, toolArgs.topK || 5);
+                    const formatted = formatEpisodesAsContext(episodes);
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: formatted || 'No relevant episodes found.' }],
+                        },
+                    };
+                }
+                case 'cf_store_episode': {
+                    saveEpisode({
+                        id: `ep-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                        agentId: toolArgs.agentId,
+                        taskId: toolArgs.taskId,
+                        input: toolArgs.input,
+                        outcome: toolArgs.outcome,
+                        reward: toolArgs.reward,
+                        timestamp: Date.now(),
+                    });
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: 'Episode stored successfully.' }],
+                        },
+                    };
+                }
+                case 'cf_q_update': {
+                    const table = loadQTable();
+                    const entry = updateQValue(table, toolArgs.state, toolArgs.action, toolArgs.reward);
+                    saveQTable(table, table.size);
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [{ type: 'text', text: `Q-value updated: ${entry.action} = ${entry.value.toFixed(4)} (visits: ${entry.visits})` }],
+                        },
+                    };
+                }
+                default:
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        error: { code: -32601, message: `Unknown tool: ${toolName}` },
+                    };
+            }
+        }
+        case 'notifications/initialized':
+            return { jsonrpc: '2.0', id, result: {} };
+        default:
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `Method not found: ${method}` },
+            };
+    }
+}
+export function startMCPServer() {
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        try {
+            const req = JSON.parse(line);
+            const response = handleRequest(req);
+            // Don't respond to notifications (no id)
+            if (req.id !== undefined) {
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+        }
+        catch {
+            const errorResp = {
+                jsonrpc: '2.0',
+                id: 0,
+                error: { code: -32700, message: 'Parse error' },
+            };
+            process.stdout.write(JSON.stringify(errorResp) + '\n');
+        }
+    });
+    rl.on('close', () => process.exit(0));
+}
+// If run directly, start MCP server
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && currentFile.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+    startMCPServer();
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/patches/apply.d.ts

@@ -0,0 +1,7 @@
+export interface PatchResult {
+    name: string;
+    applied: boolean;
+    error?: string;
+}
+export declare function applyPatches(repoPath: string, target?: 'claude-flow' | 'ruvector' | 'all'): PatchResult[];
+//# sourceMappingURL=apply.d.ts.map

package/dist/patches/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/patches/apply.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAYD,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,aAAa,GAAG,UAAU,GAAG,KAAa,GACjD,WAAW,EAAE,CAoCf"}

package/dist/patches/apply.js

@@ -0,0 +1,51 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PATCHES_DIR = join(__dirname, '..', '..', 'patches');
+const CLAUDE_FLOW_PATCHES = [
+    'sona-integration.patch',
+    'neural-index.patch',
+    'quick-test.patch',
+];
+const RUVECTOR_PATCHES = [
+    'version-bridge.patch',
+];
+export function applyPatches(repoPath, target = 'all') {
+    const results = [];
+    const patches = target === 'claude-flow' ? CLAUDE_FLOW_PATCHES
+        : target === 'ruvector' ? RUVECTOR_PATCHES
+            : [...CLAUDE_FLOW_PATCHES, ...RUVECTOR_PATCHES];
+    for (const patchFile of patches) {
+        const patchPath = join(PATCHES_DIR, patchFile);
+        if (!existsSync(patchPath)) {
+            results.push({ name: patchFile, applied: false, error: 'Patch file not found' });
+            continue;
+        }
+        try {
+            // Dry run first
+            execFileSync('git', ['apply', '--check', patchPath], {
+                cwd: repoPath,
+                encoding: 'utf-8',
+            });
+            // Apply for real
+            execFileSync('git', ['apply', patchPath], {
+                cwd: repoPath,
+                encoding: 'utf-8',
+            });
+            results.push({ name: patchFile, applied: true });
+        }
+        catch (err) {
+            const execErr = err;
+            results.push({
+                name: patchFile,
+                applied: false,
+                error: execErr.stderr || execErr.message || 'Unknown error',
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=apply.js.map

package/dist/patches/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/patches/apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AAQ3D,MAAM,mBAAmB,GAAG;IAC1B,wBAAwB;IACxB,oBAAoB;IACpB,kBAAkB;CACnB,CAAC;AAEF,MAAM,gBAAgB,GAAG;IACvB,sBAAsB;CACvB,CAAC;AAEF,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,SAA6C,KAAK;IAElD,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,mBAAmB;QAC5D,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,gBAAgB;YAC1C,CAAC,CAAC,CAAC,GAAG,mBAAmB,EAAE,GAAG,gBAAgB,CAAC,CAAC;IAElD,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,CAAC;YACjF,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,gBAAgB;YAChB,YAAY,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE;gBACnD,GAAG,EAAE,QAAQ;gBACb,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;YACH,iBAAiB;YACjB,YAAY,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE;gBACxC,GAAG,EAAE,QAAQ;gBACb,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAA4C,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,eAAe;aAC5D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/persistence/episodes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Episode Recall with TF-IDF Similarity
+ *
+ * Searches past agent episodes by text similarity to provide
+ * relevant context to newly spawned agents.
+ */
+export interface Episode {
+    id: string;
+    agentId: string;
+    taskId?: string;
+    input: string;
+    outcome: string;
+    reward: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+export interface EpisodeStore {
+    version: 1;
+    episodes: Episode[];
+    idf: Record<string, number>;
+    lastRecomputed: number;
+}
+export declare function loadEpisodes(): Episode[];
+export declare function saveEpisode(episode: Episode): void;
+/**
+ * Recall episodes relevant to the given context using TF-IDF similarity.
+ *
+ * @param context - Text describing what the agent needs to do
+ * @param topK - Number of episodes to return (default: 5)
+ * @param minSimilarity - Minimum similarity threshold (default: 0.1)
+ * @returns Array of relevant episodes sorted by similarity (descending)
+ */
+export declare function recallRelevantEpisodes(context: string, topK?: number, minSimilarity?: number): Array<Episode & {
+    similarity: number;
+}>;
+/**
+ * Format episodes as context string for injection into agent prompts.
+ */
+export declare function formatEpisodesAsContext(episodes: Array<Episode & {
+    similarity: number;
+}>): string;
+//# sourceMappingURL=episodes.d.ts.map

package/dist/persistence/episodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodes.d.ts","sourceRoot":"","sources":["../../src/persistence/episodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB;AAoFD,wBAAgB,YAAY,IAAI,OAAO,EAAE,CAcxC;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+BlD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAU,EAChB,aAAa,GAAE,MAAY,GAC1B,KAAK,CAAC,OAAO,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CA+BzC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,KAAK,CAAC,OAAO,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAChD,MAAM,CAeR"}