odd-flow 1.0.0

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * odd-flow CLI - Entry point
+ * Proxies to @claude-flow/cli bin for cross-platform compatibility.
+ */
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(__dirname, '..', 'v3', '@claude-flow', 'cli', 'bin', 'cli.js');
+await import(pathToFileURL(cliPath).href);

package/bin/npx-repair.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// NPX cache repair — no-op (removed in 3.1.0-alpha.53)
+// Kept as empty module for backwards compatibility with older bin/cli.js imports.
+export function repairNpxCache() { return 0; }
+export function repairCacheIntegrity() { return 0; }
+export function removeNpxCacheEntry() { return false; }
+export function nukeNpxCache() { return false; }

package/bin/npx-safe-launch.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Safe NPX launcher — no-op wrapper (cache repair removed in 3.1.0-alpha.53)
+// Proxies directly to the CLI entry point.
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(__dirname, '..', 'v3', '@claude-flow', 'cli', 'bin', 'cli.js');
+await import(pathToFileURL(cliPath).href);

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "odd-flow",
+  "version": "1.0.0",
+  "description": "AI agent orchestration for Claude Code — swarm coordination, vector memory, self-learning hooks, and MCP tools",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "odd-flow": "./bin/cli.js"
+  },
+  "files": [
+    "bin/**",
+    "v3/@claude-flow/cli/bin/**",
+    "v3/@claude-flow/cli/dist/**/*.js",
+    "v3/@claude-flow/cli/dist/**/*.d.ts",
+    "!v3/@claude-flow/cli/dist/**/*.map",
+    "v3/@claude-flow/cli/package.json",
+    "v3/@claude-flow/shared/dist/**/*.js",
+    "v3/@claude-flow/shared/dist/**/*.d.ts",
+    "!v3/@claude-flow/shared/dist/**/*.map",
+    "v3/@claude-flow/shared/package.json",
+    ".claude-plugin/**",
+    ".claude/**",
+    "!.claude/**/*.db",
+    "!.claude/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "build:ts": "cd v3/@claude-flow/cli && npm run build || true",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:security": "vitest run v3/__tests__/security/",
+    "lint": "cd v3/@claude-flow/cli && npm run lint || true",
+    "security:audit": "npm audit --audit-level high",
+    "security:fix": "npm audit fix",
+    "security:test": "npm run test:security"
+  },
+  "dependencies": {
+    "semver": "^7.6.0",
+    "zod": "^3.22.4"
+  },
+  "optionalDependencies": {
+    "agentdb": "^3.0.0-alpha.9"
+  },
+  "overrides": {
+    "hono": ">=4.11.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "odd-flow",
+    "odd-studio",
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai-agents",
+    "multi-agent",
+    "swarm",
+    "mcp",
+    "model-context-protocol",
+    "orchestration",
+    "cli",
+    "developer-tools",
+    "vector-database",
+    "embeddings",
+    "self-learning"
+  ],
+  "author": "odd-studio",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  }
+}

package/v3/@claude-flow/cli/README.md

@@ -0,0 +1,192 @@
+# odd-flow
+
+Agent orchestration for Claude Code. Swarms, memory, hooks, and MCP tools — hardened and minimal.
+
+[![npm version](https://img.shields.io/npm/v/odd-flow?style=flat-square)](https://www.npmjs.com/package/odd-flow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+## What is odd-flow?
+
+odd-flow is a focused agent coordination package for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides:
+
+- **Swarm orchestration** — spawn and coordinate multiple AI agents in hierarchical or mesh topologies
+- **Persistent vector memory** — HNSW-indexed semantic search with sql.js backend (4-9ms queries)
+- **Self-learning hooks** — pattern recognition and Q-learning routing that improves over time
+- **MCP server** — 100+ tools exposed via Model Context Protocol (stdio transport)
+- **Session management** — save, restore, and resume agent sessions
+- **Hive mind consensus** — Byzantine fault-tolerant coordination across agents
+- **Security scanning** — built-in AIDefence integration for prompt injection detection
+- **Embeddings** — ONNX-powered 384-dim vector embeddings with hyperbolic geometry support
+
+## How it differs from ruflo/claude-flow
+
+odd-flow is extracted from the ruflo v3 codebase with a security-first approach:
+
+| | ruflo v3 | odd-flow |
+|---|---|---|
+| **Scope** | Full enterprise platform (60+ packages, WASM kernels, deployment infra, plugins) | Focused CLI + MCP tools for agent coordination |
+| **Security** | Broad surface area, auto-install, terminal execution | Dangerous code removed, path validation on all file ops, file permissions hardened (0o600), prototype pollution prevention |
+| **Dependencies** | Heavy — Rust/WASM binaries, Docker, cloud providers | Minimal — only what the core orchestration needs |
+| **Code removed** | n/a | `terminal_execute` (arbitrary command execution), `auto-install` (silent package installation), WASM agent tools, transfer/guidance tools, MCP bridge Docker infra |
+| **Code hardened** | n/a | `exec()` → `execFileSync()` with arg arrays, input sanitisation on CLI flags, `writeFileSync` with `mode: 0o600`, `validatePath()` on all user-provided file paths, `filterDangerousKeys()` for prototype pollution |
+
+## Quick start
+
+### As an MCP server for Claude Code
+
+```bash
+claude mcp add odd-flow -- npx -y odd-flow
+```
+
+This registers odd-flow as an MCP tool provider. Claude Code will then have access to all orchestration tools (swarm, memory, agents, hooks, etc.).
+
+### As a CLI
+
+```bash
+npx odd-flow init
+npx odd-flow swarm init --topology hierarchical
+npx odd-flow agent spawn -t coder --name my-agent
+npx odd-flow memory store --key "pattern" --value "auth uses JWT refresh tokens"
+npx odd-flow memory search --query "authentication"
+```
+
+### Global install
+
+```bash
+npm install -g odd-flow
+odd-flow doctor --fix
+```
+
+## Core commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialise a project with odd-flow config |
+| `agent` | Spawn, list, terminate agents |
+| `swarm` | Multi-agent swarm coordination |
+| `memory` | Store, search, retrieve vector memory (HNSW) |
+| `task` | Create and manage tasks |
+| `session` | Save/restore session state |
+| `hooks` | Self-learning hook system |
+| `hive-mind` | Byzantine fault-tolerant consensus |
+| `embeddings` | ONNX embedding generation and search |
+| `security` | AIDefence scanning |
+| `doctor` | Diagnose and fix configuration issues |
+| `config` | View and modify settings |
+| `daemon` | Background process management |
+| `workflow` | Multi-step workflow orchestration |
+| `neural` | Neural pattern learning |
+| `performance` | Benchmarking and profiling |
+| `analyze` | Diff analysis and risk assessment |
+| `claims` | Work-stealing task distribution |
+
+## MCP tools
+
+When running as an MCP server, odd-flow exposes tools in these categories:
+
+- **`agent_*`** — spawn, list, terminate, health-check agents
+- **`swarm_*`** — init, status, shutdown swarms
+- **`memory_*`** — store, search, retrieve, list, delete, stats
+- **`task_*`** — create, update, complete, cancel, list tasks
+- **`session_*`** — save, restore, list, delete sessions
+- **`hooks_*`** — lifecycle hooks, intelligence, workers, routing
+- **`hive-mind_*`** — init, join, broadcast, consensus
+- **`workflow_*`** — create, execute, pause, resume workflows
+- **`embeddings_*`** — generate, search, compare embeddings
+- **`config_*`** — get, set, list, reset configuration
+- **`claims_*`** — claim, release, steal, rebalance work items
+- **`analyze_*`** — diff stats, risk assessment, reviewer suggestions
+- **`progress_*`** — check, sync, watch, summary
+- **`security_*`** — scan for prompt injection and manipulation
+- **`system_*`** — health, status, metrics, info
+
+## Memory system
+
+odd-flow uses HNSW (Hierarchical Navigable Small World) indexing for fast semantic search over stored memories:
+
+```bash
+# Store a memory with tags
+odd-flow memory store --key "auth-pattern" --value "JWT with refresh token rotation" --namespace patterns --tags "auth,jwt"
+
+# Semantic search (returns ranked results)
+odd-flow memory search --query "how does authentication work" --namespace patterns --limit 5
+
+# List all memories in a namespace
+odd-flow memory list --namespace patterns
+```
+
+The memory backend uses sql.js (SQLite compiled to WASM) with 384-dimensional embeddings. Query latency is typically 4-9ms.
+
+## Swarm orchestration
+
+Swarms coordinate multiple agents working on a shared task:
+
+```bash
+# Initialise a hierarchical swarm (queen + workers)
+odd-flow swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+# Check swarm status
+odd-flow swarm status
+
+# Shutdown
+odd-flow swarm shutdown
+```
+
+Supported topologies:
+- **hierarchical** — queen coordinator delegates to specialised workers
+- **mesh** — peer-to-peer, every agent communicates directly
+- **ring** — sequential message passing
+- **star** — central hub with spokes
+
+## Self-learning hooks
+
+Hooks observe agent behaviour and learn patterns over time:
+
+```bash
+# View learned patterns
+odd-flow hooks intelligence stats
+
+# Search for patterns
+odd-flow hooks intelligence pattern-search --query "error handling"
+
+# View routing decisions
+odd-flow hooks model-stats
+```
+
+The hook system uses Q-learning to optimise model routing (which model handles which task type) based on observed outcomes.
+
+## Configuration
+
+```bash
+# View current config
+odd-flow config list
+
+# Set a value
+odd-flow config set --key "swarm.maxAgents" --value 12
+
+# Reset to defaults
+odd-flow config reset
+```
+
+Configuration is stored in `.odd-flow/config.json` in the project root with `0o600` file permissions.
+
+## Security model
+
+odd-flow was hardened from the ruflo v3 codebase with these measures:
+
+- **Path containment** — all file operations validated against project root via `validatePath()`
+- **No arbitrary execution** — `terminal_execute` tool removed entirely
+- **No auto-install** — removed silent package installation capability
+- **File permissions** — all state files written with `mode: 0o600` (owner read/write only)
+- **Prototype pollution prevention** — `filterDangerousKeys()` strips `__proto__`, `constructor`, `prototype` from all inputs recursively
+- **Input sanitisation** — CLI flag values sanitised before use in shell commands
+- **execFileSync over exec** — array-based argument passing, no shell interpolation
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code (for MCP integration)
+
+## License
+
+MIT

package/v3/@claude-flow/cli/bin/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * @claude-flow/cli - CLI Entry Point
+ *
+ * Claude Flow V3 Command Line Interface
+ *
+ * Auto-detects MCP mode when stdin is piped and no args provided.
+ * This allows: echo '{"jsonrpc":"2.0",...}' | npx @claude-flow/cli
+ */
+
+import { randomUUID } from 'crypto';
+
+// Check if we should run in MCP server mode
+// Conditions:
+//   1. stdin is being piped AND no CLI arguments provided (auto-detect)
+//   2. stdin is being piped AND args are "mcp start" (explicit, e.g. npx claude-flow@alpha mcp start)
+const cliArgs = process.argv.slice(2);
+const isExplicitMCP = cliArgs.length >= 1 && cliArgs[0] === 'mcp' && (cliArgs.length === 1 || cliArgs[1] === 'start');
+const isMCPMode = !process.stdin.isTTY && (process.argv.length === 2 || isExplicitMCP);
+
+if (isMCPMode) {
+  // Run MCP server mode
+  const { listMCPTools, callMCPTool, hasTool } = await import('../dist/src/mcp-client.js');
+
+  const VERSION = '1.0.0';
+  const sessionId = `mcp-${Date.now()}-${randomUUID().slice(0, 8)}`;
+
+  console.error(
+    `[${new Date().toISOString()}] INFO [odd-flow-mcp] (${sessionId}) Starting in stdio mode`
+  );
+
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk;
+    let lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const message = JSON.parse(line);
+          const response = await handleMessage(message);
+          if (response) {
+            console.log(JSON.stringify(response));
+          }
+        } catch (error) {
+          console.log(JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32700, message: 'Parse error' },
+          }));
+        }
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    process.exit(0);
+  });
+
+  async function handleMessage(message) {
+    if (!message.method) {
+      return {
+        jsonrpc: '2.0',
+        id: message.id,
+        error: { code: -32600, message: 'Invalid Request: missing method' },
+      };
+    }
+
+    const params = message.params || {};
+
+    switch (message.method) {
+      case 'initialize':
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            serverInfo: { name: 'odd-flow', version: VERSION },
+            capabilities: {
+              tools: { listChanged: true },
+              resources: { subscribe: true, listChanged: true },
+            },
+          },
+        };
+
+      case 'tools/list': {
+        const tools = listMCPTools();
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            tools: tools.map(tool => ({
+              name: tool.name,
+              description: tool.description,
+              inputSchema: tool.inputSchema,
+            })),
+          },
+        };
+      }
+
+      case 'tools/call': {
+        const toolName = params.name;
+        const toolParams = params.arguments || {};
+
+        if (!hasTool(toolName)) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: { code: -32601, message: `Tool not found: ${toolName}` },
+          };
+        }
+
+        try {
+          const result = await callMCPTool(toolName, toolParams, { sessionId });
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] },
+          };
+        } catch (error) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32603,
+              message: error instanceof Error ? error.message : 'Tool execution failed',
+            },
+          };
+        }
+      }
+
+      case 'notifications/initialized':
+        return null;
+
+      case 'ping':
+        return { jsonrpc: '2.0', id: message.id, result: {} };
+
+      default:
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32601, message: `Method not found: ${message.method}` },
+        };
+    }
+  }
+} else {
+  // Run normal CLI mode
+  const { CLI } = await import('../dist/src/index.js');
+  const cli = new CLI();
+  cli.run().catch((error) => {
+    console.error('Fatal error:', error.message);
+    process.exit(1);
+  });
+}

package/v3/@claude-flow/cli/bin/mcp-server.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * @claude-flow/cli - MCP Server Entry Point
+ *
+ * Direct stdio MCP server for Claude Code integration.
+ * This entry point handles stdin/stdout directly for MCP protocol
+ * without any CLI formatting output that would corrupt the protocol.
+ */
+
+import { randomUUID } from 'crypto';
+import { listMCPTools, callMCPTool, hasTool } from '../dist/src/mcp-client.js';
+
+const VERSION = '1.0.0';
+const sessionId = `mcp-${Date.now()}-${randomUUID().slice(0, 8)}`;
+
+// Log to stderr (doesn't corrupt stdout for MCP protocol)
+console.error(
+  `[${new Date().toISOString()}] INFO [odd-flow-mcp] (${sessionId}) Starting in stdio mode`
+);
+console.error(JSON.stringify({
+  arch: process.arch,
+  mode: 'mcp-stdio',
+  nodeVersion: process.version,
+  pid: process.pid,
+  platform: process.platform,
+  protocol: 'stdio',
+  sessionId,
+  version: VERSION,
+}));
+
+// Handle stdin messages
+let buffer = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk;
+
+  // Process complete JSON messages (newline-delimited)
+  let lines = buffer.split('\n');
+  buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+  for (const line of lines) {
+    if (line.trim()) {
+      try {
+        const message = JSON.parse(line);
+        const response = await handleMessage(message);
+        if (response) {
+          console.log(JSON.stringify(response));
+        }
+      } catch (error) {
+        console.error(
+          `[${new Date().toISOString()}] ERROR [odd-flow-mcp] Failed to parse:`,
+          error instanceof Error ? error.message : String(error)
+        );
+        // Send parse error response
+        console.log(JSON.stringify({
+          jsonrpc: '2.0',
+          id: null,
+          error: { code: -32700, message: 'Parse error' },
+        }));
+      }
+    }
+  }
+});
+
+process.stdin.on('end', () => {
+  console.error(
+    `[${new Date().toISOString()}] INFO [odd-flow-mcp] (${sessionId}) stdin closed, shutting down...`
+  );
+  process.exit(0);
+});
+
+// Handle process termination
+process.on('SIGINT', () => {
+  console.error(`[${new Date().toISOString()}] INFO [odd-flow-mcp] Received SIGINT`);
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  console.error(`[${new Date().toISOString()}] INFO [odd-flow-mcp] Received SIGTERM`);
+  process.exit(0);
+});
+
+/**
+ * Handle MCP message
+ */
+async function handleMessage(message) {
+  if (!message.method) {
+    return {
+      jsonrpc: '2.0',
+      id: message.id,
+      error: { code: -32600, message: 'Invalid Request: missing method' },
+    };
+  }
+
+  const params = message.params || {};
+
+  try {
+    switch (message.method) {
+      case 'initialize':
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            serverInfo: { name: 'odd-flow', version: VERSION },
+            capabilities: {
+              tools: { listChanged: true },
+              resources: { subscribe: true, listChanged: true },
+            },
+          },
+        };
+
+      case 'tools/list': {
+        const tools = listMCPTools();
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            tools: tools.map(tool => ({
+              name: tool.name,
+              description: tool.description,
+              inputSchema: tool.inputSchema,
+            })),
+          },
+        };
+      }
+
+      case 'tools/call': {
+        const toolName = params.name;
+        const toolParams = params.arguments || {};
+
+        if (!hasTool(toolName)) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: { code: -32601, message: `Tool not found: ${toolName}` },
+          };
+        }
+
+        try {
+          const result = await callMCPTool(toolName, toolParams, { sessionId });
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] },
+          };
+        } catch (error) {
+          return {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32603,
+              message: error instanceof Error ? error.message : 'Tool execution failed',
+            },
+          };
+        }
+      }
+
+      case 'notifications/initialized':
+        console.error(`[${new Date().toISOString()}] INFO [odd-flow-mcp] Client initialized`);
+        return null; // No response for notifications
+
+      case 'ping':
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {},
+        };
+
+      default:
+        return {
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32601, message: `Method not found: ${message.method}` },
+        };
+    }
+  } catch (error) {
+    console.error(`[${new Date().toISOString()}] ERROR [odd-flow-mcp] ${message.method}:`, error);
+    return {
+      jsonrpc: '2.0',
+      id: message.id,
+      error: {
+        code: -32603,
+        message: error instanceof Error ? error.message : 'Internal error',
+      },
+    };
+  }
+}

package/v3/@claude-flow/cli/bin/preinstall.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+// Preinstall hook — no-op (cache repair removed in 3.1.0-alpha.53)