claude-flow 3.6.26 → 3.6.28

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"1dba3b8c-1f1f-4718-bab4-9ffba5f49578","pid":20633,"procStart":"Mon May  4 17:00:40 2026","acquiredAt":1777938041240}

package/README.md

@@ -43,9 +43,17 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
 
 ## Quick Start
 
-### Claude Code Plugin (Recommended)
+There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):
 
-Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, and MCP tools directly:
+| | **Claude Code Plugin** | **CLI install (`npx ruflo init`)** |
+|---|---|---|
+| What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
+| Files in your workspace | **Zero** | `.claude/`, `.claude-flow/`, `CLAUDE.md`, helpers, settings |
+| MCP server registered | **No** (`memory_store`, `swarm_init`, etc. unavailable to Claude) | Yes |
+| Hooks installed | No | Yes |
+| Best for | Try a single plugin's commands without committing to the full install | Production use — everything works as documented |
+
+### Path A — Claude Code Plugins (lite, slash commands only)
 
 ```bash
 # Add the marketplace
@@ -58,6 +66,8 @@ Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, a
 /plugin install ruflo-federation@ruflo
 ```
 
+This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so `memory_store`, `swarm_init`, `agent_spawn`, etc. won't be callable from Claude. For the full loop, use Path B below.
+
 <details>
 <summary><strong>All 32 plugins</strong></summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.6.26",
+  "version": "3.6.28",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

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

@@ -43,9 +43,17 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
 
 ## Quick Start
 
-### Claude Code Plugin (Recommended)
+There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):
 
-Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, and MCP tools directly:
+| | **Claude Code Plugin** | **CLI install (`npx ruflo init`)** |
+|---|---|---|
+| What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
+| Files in your workspace | **Zero** | `.claude/`, `.claude-flow/`, `CLAUDE.md`, helpers, settings |
+| MCP server registered | **No** (`memory_store`, `swarm_init`, etc. unavailable to Claude) | Yes |
+| Hooks installed | No | Yes |
+| Best for | Try a single plugin's commands without committing to the full install | Production use — everything works as documented |
+
+### Path A — Claude Code Plugins (lite, slash commands only)
 
 ```bash
 # Add the marketplace
@@ -58,6 +66,8 @@ Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, a
 /plugin install ruflo-federation@ruflo
 ```
 
+This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so `memory_store`, `swarm_init`, `agent_spawn`, etc. won't be callable from Claude. For the full loop, use Path B below.
+
 <details>
 <summary><strong>All 32 plugins</strong></summary>
 

package/v3/@claude-flow/cli/dist/src/commands/init.js

@@ -145,6 +145,7 @@ const initAction = async (ctx) => {
     const full = ctx.flags.full;
     const skipClaude = ctx.flags['skip-claude'];
     const onlyClaude = ctx.flags['only-claude'];
+    const noGlobal = ctx.flags['no-global'];
     const codexMode = ctx.flags.codex;
     const dualMode = ctx.flags.dual;
     const cwd = ctx.cwd;
@@ -203,6 +204,12 @@ const initAction = async (ctx) => {
     if (onlyClaude) {
         options.components.runtime = false;
     }
+    // #1744 — opt-out of the user-global ~/.claude/CLAUDE.md "Ruflo Integration"
+    // pointer block. Default behavior (off) preserves current install for users
+    // who rely on it; opting in via --no-global keeps the global file pristine.
+    if (noGlobal) {
+        options.skipGlobalClaudeMd = true;
+    }
     // Create spinner
     const spinner = output.createSpinner({ text: 'Initializing...' });
     spinner.start();
@@ -919,6 +926,12 @@ export const initCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            name: 'no-global',
+            description: 'Skip the ~/.claude/CLAUDE.md "Ruflo Integration" pointer block (#1744)',
+            type: 'boolean',
+            default: false,
+        },
         {
             name: 'start-all',
             description: 'Auto-start daemon, memory, and swarm after init',

package/v3/@claude-flow/cli/dist/src/commands/performance.js

@@ -498,7 +498,7 @@ const optimizeCommand = {
             data: [
                 { priority: output.error('P0'), area: 'Memory', recommendation: 'Enable HNSW index quantization', impact: '+50% reduction' },
                 { priority: output.warning('P1'), area: 'CPU', recommendation: 'Enable WASM SIMD acceleration', impact: '+4x speedup' },
-                { priority: output.warning('P1'), area: 'Latency', recommendation: 'Enable Flash Attention', impact: '+2.49x speedup' },
+                { priority: output.warning('P1'), area: 'Latency', recommendation: 'Flash Attention WASM (in progress, currently JS reference)', impact: '+2.49x target' },
                 { priority: output.info('P2'), area: 'Cache', recommendation: 'Increase pattern cache size', impact: '+15% hit rate' },
                 { priority: output.info('P2'), area: 'Network', recommendation: 'Enable request batching', impact: '-30% latency' },
             ],
@@ -536,7 +536,7 @@ const bottleneckCommand = {
             ],
             data: [
                 { component: 'Vector Search', bottleneck: 'Linear scan O(n)', severity: output.error('High'), solution: 'Enable HNSW indexing' },
-                { component: 'Neural Inference', bottleneck: 'Sequential attention', severity: output.warning('Medium'), solution: 'Enable Flash Attention' },
+                { component: 'Neural Inference', bottleneck: 'Sequential attention', severity: output.warning('Medium'), solution: 'Flash Attention WASM (in progress)' },
                 { component: 'Memory Store', bottleneck: 'Lock contention', severity: output.info('Low'), solution: 'Use sharded storage' },
             ],
         });
@@ -571,7 +571,7 @@ export const performanceCommand = {
         output.writeln('Performance Targets:');
         output.printList([
             'HNSW Search: 150x-12,500x faster than brute force',
-            'Flash Attention: 2.49x-7.47x speedup',
+            'Flash Attention: 2.49x-7.47x target (in progress; ships JS reference impl)',
             'Memory: 50-75% reduction with quantization',
         ]);
         output.writeln();

package/v3/@claude-flow/cli/dist/src/commands/providers.js

@@ -11,6 +11,9 @@ const PROVIDER_CATALOG = [
     { name: 'OpenAI', type: 'LLM', models: 'gpt-4o, gpt-4-turbo', envVar: 'OPENAI_API_KEY', configName: 'openai' },
     { name: 'OpenAI', type: 'Embedding', models: 'text-embedding-3-small/large', envVar: 'OPENAI_API_KEY', configName: 'openai' },
     { name: 'Google', type: 'LLM', models: 'gemini-pro, gemini-ultra', envVar: 'GOOGLE_API_KEY', configName: 'google' },
+    // #1725: Ollama Cloud — Tier-2 default per ADR-026 (~$100/mo flat-rate alternative
+    // to per-token pricing). OpenAI-compat API at https://ollama.com/v1/chat/completions.
+    { name: 'Ollama', type: 'LLM', models: 'gpt-oss:120b-cloud, llama3:70b-cloud, qwen2.5-coder:32b-cloud', envVar: 'OLLAMA_API_KEY', configName: 'ollama' },
     { name: 'Transformers.js', type: 'Embedding', models: 'Xenova/all-MiniLM-L6-v2' },
     { name: 'Agentic Flow', type: 'Embedding', models: 'ONNX optimized' },
     { name: 'Mock', type: 'All', models: 'mock-*' },
@@ -30,6 +33,7 @@ function resolveApiKey(providerName, configuredProviders) {
         anthropic: 'ANTHROPIC_API_KEY',
         openai: 'OPENAI_API_KEY',
         google: 'GOOGLE_API_KEY',
+        ollama: 'OLLAMA_API_KEY', // #1725 — Tier-2 routing
     };
     const envVar = envMapping[providerName.toLowerCase()];
     if (envVar && process.env[envVar]) {
@@ -60,6 +64,13 @@ async function testProviderConnectivity(providerName, apiKey) {
             url: `https://generativelanguage.googleapis.com/v1beta/models?key=${apiKey}`,
             headers: {},
         },
+        // #1725 — Ollama Cloud uses an OpenAI-compatible /v1 surface.
+        ollama: {
+            url: 'https://ollama.com/api/tags',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+            },
+        },
     };
     const endpointConfig = endpoints[providerName.toLowerCase()];
     if (!endpointConfig) {

package/v3/@claude-flow/cli/dist/src/init/executor.js

@@ -1662,9 +1662,11 @@ async function writeClaudeMd(targetDir, options, result) {
         fs.writeFileSync(claudeMdPath, content, 'utf-8');
         result.created.files.push('CLAUDE.md');
     }
-    // Also write/append global ~/.claude/CLAUDE.md so ruflo tools are used automatically (#1497)
+    // Also write/append global ~/.claude/CLAUDE.md so ruflo tools are used automatically (#1497).
+    // Opt-out via --no-global / options.skipGlobalClaudeMd (#1744 — keeps global rules file pristine
+    // for users who don't want a per-machine pointer block).
     const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    if (homeDir) {
+    if (homeDir && !options.skipGlobalClaudeMd) {
         const globalClaudeDir = path.join(homeDir, '.claude');
         const globalClaudeMd = path.join(globalClaudeDir, 'CLAUDE.md');
         const rufloBlock = [
@@ -1695,6 +1697,9 @@ async function writeClaudeMd(targetDir, options, result) {
             // Non-critical — global CLAUDE.md is best-effort
         }
     }
+    else if (options.skipGlobalClaudeMd) {
+        result.skipped.push('~/.claude/CLAUDE.md (--no-global)');
+    }
 }
 /**
  * Find source directory for skills/commands/agents

package/v3/@claude-flow/cli/dist/src/init/settings-generator.js

@@ -8,8 +8,13 @@ import { detectPlatform } from './types.js';
  */
 export function generateSettings(options) {
     const settings = {};
-    // Add hooks if enabled
-    if (options.components.settings) {
+    // Add hooks if enabled. CRITICAL (#1744 #3): only emit the hooks block when
+    // the helpers directory will also be bundled. The hook commands point at
+    // .claude/helpers/hook-handler.cjs; if that file isn't created (as in
+    // --minimal where components.helpers=false), every hook fires and silently
+    // fails to find its handler. Either bundle the helpers OR drop the hooks —
+    // the option this fix takes is the latter (minimal stays minimal).
+    if (options.components.settings && options.components.helpers) {
         settings.hooks = generateHooksConfig(options.hooks);
     }
     // Add statusLine configuration if enabled

package/v3/@claude-flow/cli/dist/src/init/types.d.ts

@@ -260,6 +260,12 @@ export interface InitOptions {
     runtime: RuntimeConfig;
     /** Embeddings configuration */
     embeddings: EmbeddingsConfig;
+    /**
+     * Skip the user-global ~/.claude/CLAUDE.md "Ruflo Integration" pointer block.
+     * Defaults to false (current behavior — block is appended once, idempotent).
+     * Set true via --no-global to keep the global Claude rules file pristine (#1744).
+     */
+    skipGlobalClaudeMd?: boolean;
 }
 /**
  * Default init options - full V3 setup

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

@@ -32,6 +32,7 @@ import { githubTools } from './mcp-tools/github-tools.js';
 import { daaTools } from './mcp-tools/daa-tools.js';
 import { coordinationTools } from './mcp-tools/coordination-tools.js';
 import { browserTools } from './mcp-tools/browser-tools.js';
+import { browserSessionTools } from './mcp-tools/browser-session-tools.js';
 import { execFileSync } from 'node:child_process';
 // Phase 6: AgentDB v3 controller tools
 import { agentdbTools } from './mcp-tools/agentdb-tools.js';
@@ -54,6 +55,15 @@ function getBrowserTools() {
     }
     return _browserAvailable ? browserTools : [];
 }
+/**
+ * Lifecycle MCP tools for ruflo-browser session-as-skill architecture
+ * (ADR-0001 ruflo-browser §7). Always registered: their handlers shell out
+ * to ruvector + agent-browser + claude-flow memory and degrade gracefully
+ * when those CLIs are missing.
+ */
+function getBrowserSessionTools() {
+    return browserSessionTools;
+}
 /**
  * MCP Tool Registry
  * Maps tool names to their handler functions
@@ -91,6 +101,7 @@ registerTools([
     ...daaTools,
     ...coordinationTools,
     ...getBrowserTools(),
+    ...getBrowserSessionTools(),
     // Phase 6: AgentDB v3 controller tools
     ...agentdbTools,
     // RuVector WASM tools

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.d.ts

@@ -47,6 +47,12 @@ export interface AnthropicCallResult {
  * Generic Anthropic Messages API call. No agent registry coupling — used
  * by agent_execute (with the agent's configured model) and by the WASM
  * agent runtime (G4) when the bundled WASM only echoes input.
+ *
+ * #1725 — falls back to Ollama Cloud (Tier-2, OpenAI-compat) when
+ * ANTHROPIC_API_KEY is unset and OLLAMA_API_KEY is present, or when
+ * RUFLO_PROVIDER=ollama is explicitly set. Response shape is normalized
+ * to the Anthropic-flavored AnthropicCallResult so existing callers
+ * don't need to know which provider answered.
  */
 export declare function callAnthropicMessages(input: AnthropicCallInput): Promise<AnthropicCallResult>;
 /**

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js

@@ -42,11 +42,26 @@ const MODEL_MAP = {
  * Generic Anthropic Messages API call. No agent registry coupling — used
  * by agent_execute (with the agent's configured model) and by the WASM
  * agent runtime (G4) when the bundled WASM only echoes input.
+ *
+ * #1725 — falls back to Ollama Cloud (Tier-2, OpenAI-compat) when
+ * ANTHROPIC_API_KEY is unset and OLLAMA_API_KEY is present, or when
+ * RUFLO_PROVIDER=ollama is explicitly set. Response shape is normalized
+ * to the Anthropic-flavored AnthropicCallResult so existing callers
+ * don't need to know which provider answered.
  */
 export async function callAnthropicMessages(input) {
-    const apiKey = process.env.ANTHROPIC_API_KEY;
-    if (!apiKey) {
-        return { success: false, error: 'ANTHROPIC_API_KEY not set in environment' };
+    const explicitProvider = (process.env.RUFLO_PROVIDER || '').toLowerCase();
+    const ollamaKey = process.env.OLLAMA_API_KEY;
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const useOllama = explicitProvider === 'ollama' || (!anthropicKey && !!ollamaKey);
+    if (useOllama && ollamaKey) {
+        return callOllamaCompat({ ...input, apiKey: ollamaKey });
+    }
+    if (!anthropicKey) {
+        return {
+            success: false,
+            error: 'No LLM provider configured. Set ANTHROPIC_API_KEY (Tier-3) or OLLAMA_API_KEY (Tier-2 Ollama Cloud — see issue #1725).',
+        };
     }
     const model = input.model || 'claude-3-5-sonnet-latest';
     const startedAt = Date.now();
@@ -56,7 +71,7 @@ export async function callAnthropicMessages(input) {
         const res = await fetch('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
-                'x-api-key': apiKey,
+                'x-api-key': anthropicKey,
                 'anthropic-version': '2023-06-01',
                 'content-type': 'application/json',
             },
@@ -102,6 +117,98 @@ export async function callAnthropicMessages(input) {
         };
     }
 }
+/**
+ * Ollama Cloud / OpenAI-compat provider — Tier-2 routing per ADR-026 + #1725.
+ *
+ * Endpoint: https://ollama.com/v1/chat/completions
+ * Auth: Authorization: Bearer <OLLAMA_API_KEY>
+ *
+ * Translates the Anthropic-flavored input shape onto OpenAI chat-completions
+ * and translates the response back so callers never see provider-specific
+ * fields. Logical model names are mapped to Ollama Cloud defaults:
+ *   - 'haiku'  / 'sonnet'  → 'gpt-oss:120b-cloud' (sensible single default)
+ *   - 'opus'              → 'gpt-oss:120b-cloud' (no opus tier on Ollama)
+ *   - explicit 'ollama:<model>' or bare provider-native name → passed through
+ */
+async function callOllamaCompat(input) {
+    const model = resolveOllamaModel(input.model);
+    const startedAt = Date.now();
+    // OLLAMA_BASE_URL lets users point at local/self-hosted endpoints
+    // (e.g. http://ruvultra:11434, http://localhost:11434) instead of
+    // Ollama Cloud. Default is the public cloud endpoint.
+    const base = (process.env.OLLAMA_BASE_URL || 'https://ollama.com').replace(/\/+$/, '');
+    const url = `${base}/v1/chat/completions`;
+    // Self-hosted endpoints typically don't need an Authorization header
+    // (the daemon binds to 11434 with no auth by default), but Ollama Cloud
+    // does. Send the bearer when the key is non-empty AND looks cloud-shaped.
+    const sendAuth = input.apiKey && input.apiKey !== 'local';
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), input.timeoutMs || 60000);
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                ...(sendAuth ? { Authorization: `Bearer ${input.apiKey}` } : {}),
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: input.maxTokens || 1024,
+                temperature: typeof input.temperature === 'number' ? input.temperature : 0.7,
+                messages: [
+                    ...(input.systemPrompt
+                        ? [{ role: 'system', content: input.systemPrompt }]
+                        : []),
+                    { role: 'user', content: input.prompt },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+            const errText = await res.text().catch(() => '<unreadable error body>');
+            return { success: false, model, error: `Ollama API error ${res.status} at ${url}: ${errText.slice(0, 400)}` };
+        }
+        const data = (await res.json());
+        const textOut = data.choices?.[0]?.message?.content ?? '';
+        const usage = data.usage ?? {};
+        return {
+            success: true,
+            model: data.model ?? model,
+            messageId: data.id ?? `ollama-${Date.now()}`,
+            stopReason: data.choices?.[0]?.finish_reason ?? 'end_turn',
+            output: textOut,
+            usage: {
+                inputTokens: usage.prompt_tokens ?? 0,
+                outputTokens: usage.completion_tokens ?? 0,
+                totalTokens: usage.total_tokens ?? 0,
+            },
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            model,
+            error: err instanceof Error ? err.message : String(err),
+            durationMs: Date.now() - startedAt,
+        };
+    }
+}
+function resolveOllamaModel(input) {
+    const DEFAULT = 'gpt-oss:120b-cloud';
+    if (!input)
+        return DEFAULT;
+    // Logical → cloud default
+    if (input === 'haiku' || input === 'sonnet' || input === 'opus' || input === 'inherit') {
+        return DEFAULT;
+    }
+    // Explicit provider prefix
+    if (input.startsWith('ollama:'))
+        return input.slice('ollama:'.length);
+    // Bare name with cloud suffix (e.g. 'llama3:70b-cloud') passes through
+    return input;
+}
 /**
  * Resolve a model identifier to an Anthropic model ID. Accepts:
  * - logical names: 'haiku', 'sonnet', 'opus', 'inherit'

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

@@ -0,0 +1,23 @@
+/**
+ * Browser Session Lifecycle MCP Tools (ADR-0001 ruflo-browser §7).
+ *
+ * Five lifecycle tools that wrap the 23 raw `browser_*` interaction tools
+ * with RVF cognitive containers, ruvector trajectory recording, AgentDB
+ * indexing, and AIDefence gates. Implements the contract from
+ * `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md`.
+ *
+ * Design notes:
+ *   - These tools orchestrate at the *primitive* level — they shell out to
+ *     the existing `agent-browser` CLI (for browser actions), `ruvector` CLI
+ *     (for trajectory hooks + RVF), and the bridged `memory` namespace (for
+ *     AgentDB index). They do not inline a replay engine; replay
+ *     enumerates trajectory steps and returns them for the caller to dispatch.
+ *   - Pinned to ruvector@0.2.25 to match `ruflo-ruvector` ADR-0001.
+ *   - Best-effort: missing dependencies (no `ruvector`, no `agent-browser`,
+ *     no AgentDB controller) degrade gracefully with a structured error
+ *     rather than a process crash.
+ */
+import type { MCPTool } from './types.js';
+export declare const browserSessionTools: MCPTool[];
+export default browserSessionTools;
+//# sourceMappingURL=browser-session-tools.d.ts.map

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

@@ -0,0 +1,313 @@
+/**
+ * Browser Session Lifecycle MCP Tools (ADR-0001 ruflo-browser §7).
+ *
+ * Five lifecycle tools that wrap the 23 raw `browser_*` interaction tools
+ * with RVF cognitive containers, ruvector trajectory recording, AgentDB
+ * indexing, and AIDefence gates. Implements the contract from
+ * `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md`.
+ *
+ * Design notes:
+ *   - These tools orchestrate at the *primitive* level — they shell out to
+ *     the existing `agent-browser` CLI (for browser actions), `ruvector` CLI
+ *     (for trajectory hooks + RVF), and the bridged `memory` namespace (for
+ *     AgentDB index). They do not inline a replay engine; replay
+ *     enumerates trajectory steps and returns them for the caller to dispatch.
+ *   - Pinned to ruvector@0.2.25 to match `ruflo-ruvector` ADR-0001.
+ *   - Best-effort: missing dependencies (no `ruvector`, no `agent-browser`,
+ *     no AgentDB controller) degrade gracefully with a structured error
+ *     rather than a process crash.
+ */
+import { validateIdentifier, validateText } from './validate-input.js';
+const RUVECTOR_PIN = 'ruvector@0.2.25';
+const RVF_DIR_DEFAULT = '.ruflo/browser-sessions';
+async function shell(cmd, args, opts = {}) {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const run = promisify(execFile);
+    try {
+        const { stdout, stderr } = await run(cmd, args, {
+            timeout: opts.timeout ?? 30000,
+            encoding: 'utf-8',
+        });
+        return { success: true, stdout, stderr };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.code === 'ENOENT' ? `command not found: ${cmd}` : err.message,
+            stdout: err.stdout,
+            stderr: err.stderr,
+        };
+    }
+}
+async function ensureSessionsDir() {
+    const { mkdir } = await import('node:fs/promises');
+    const path = await import('node:path');
+    const dir = path.resolve(process.cwd(), RVF_DIR_DEFAULT);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+function makeSessionId(taskSlug) {
+    const stamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    const slug = taskSlug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 32) || 'session';
+    return `${stamp}-${slug}`;
+}
+function ok(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, ...payload }, null, 2) }] };
+}
+function fail(error, extra = {}) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ success: false, error, ...extra }, null, 2) }],
+        isError: true,
+    };
+}
+export const browserSessionTools = [
+    // ==========================================================================
+    // browser_session_record — open a recorded session
+    // ==========================================================================
+    {
+        name: 'browser_session_record',
+        description: 'Open a named, traced browser session: allocate an RVF cognitive container, begin a ruvector trajectory, then open the URL via agent-browser. Returns the session id and rvf path.',
+        category: 'browser-session',
+        tags: ['session', 'rvf', 'trajectory', 'lifecycle'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Target URL to open' },
+                task: { type: 'string', description: 'Human-readable task description (recorded in trajectory)' },
+                session: { type: 'string', description: 'Optional explicit session id; otherwise auto-generated' },
+                rvf_dir: { type: 'string', description: 'Override the default .ruflo/browser-sessions directory' },
+            },
+            required: ['url', 'task'],
+        },
+        handler: async (input) => {
+            const vUrl = validateText(input.url, 'url');
+            if (!vUrl.valid)
+                return fail(vUrl.error || 'invalid url');
+            const vTask = validateText(input.task, 'task');
+            if (!vTask.valid)
+                return fail(vTask.error || 'invalid task');
+            const path = await import('node:path');
+            const explicitSession = input.session;
+            if (explicitSession) {
+                const v = validateIdentifier(explicitSession, 'session');
+                if (!v.valid)
+                    return fail(v.error || 'invalid session');
+            }
+            const sessionId = explicitSession ?? makeSessionId(input.task);
+            const dir = input.rvf_dir ?? (await ensureSessionsDir());
+            const rvfPath = path.join(dir, `${sessionId}.rvf`);
+            // 1. RVF allocate
+            const rvf = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'create', rvfPath, '--kind', 'browser-session'], { timeout: 60000 });
+            if (!rvf.success)
+                return fail('rvf create failed', { detail: rvf.error, stderr: rvf.stderr, sessionId, rvfPath });
+            // 2. trajectory-begin
+            const tb = await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-begin', '--session-id', sessionId, '--task', input.task]);
+            if (!tb.success)
+                return fail('trajectory-begin failed', { detail: tb.error, stderr: tb.stderr, sessionId, rvfPath });
+            // 3. browser_open via agent-browser
+            const bo = await shell('agent-browser', ['--session', sessionId, '--json', 'open', input.url], { timeout: 30000 });
+            if (!bo.success) {
+                const npxBo = await shell('npx', ['--yes', 'agent-browser', '--session', sessionId, '--json', 'open', input.url], { timeout: 60000 });
+                if (!npxBo.success) {
+                    return fail('browser open failed', { detail: npxBo.error, stderr: npxBo.stderr, sessionId, rvfPath });
+                }
+            }
+            // 4. log the open as the first trajectory step
+            await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-step',
+                '--session-id', sessionId,
+                '--action', 'browser_open',
+                '--args', JSON.stringify({ url: input.url }),
+                '--result', 'ok']);
+            return ok({
+                sessionId,
+                rvfPath,
+                url: input.url,
+                task: input.task,
+                ruvectorPin: RUVECTOR_PIN,
+            });
+        },
+    },
+    // ==========================================================================
+    // browser_session_end — commit a recorded session
+    // ==========================================================================
+    {
+        name: 'browser_session_end',
+        description: 'End a recorded browser session: trajectory-end with verdict, rvf compact, AIDefence pre-store gate (best-effort), and AgentDB index in the browser-sessions namespace.',
+        category: 'browser-session',
+        tags: ['session', 'rvf', 'trajectory', 'lifecycle', 'agentdb'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session: { type: 'string', description: 'Session id (returned from browser_session_record)' },
+                rvf_path: { type: 'string', description: 'Path to the .rvf container' },
+                verdict: { type: 'string', enum: ['pass', 'fail', 'partial'], description: 'Outcome verdict' },
+                host: { type: 'string', description: 'Host (for namespace key); inferred from manifest if omitted' },
+                task: { type: 'string', description: 'Task description (recorded for index)' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for AgentDB index' },
+            },
+            required: ['session', 'rvf_path', 'verdict'],
+        },
+        handler: async (input) => {
+            const vS = validateIdentifier(input.session, 'session');
+            if (!vS.valid)
+                return fail(vS.error || 'invalid session');
+            const verdict = input.verdict;
+            if (!['pass', 'fail', 'partial'].includes(verdict))
+                return fail(`invalid verdict: ${verdict}`);
+            // 1. trajectory-end
+            const te = await shell('npx', ['-y', RUVECTOR_PIN, 'hooks', 'trajectory-end',
+                '--session-id', input.session,
+                '--verdict', verdict]);
+            if (!te.success)
+                return fail('trajectory-end failed', { detail: te.error, stderr: te.stderr });
+            // 2. rvf compact
+            const compact = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'compact', input.rvf_path]);
+            if (!compact.success)
+                return fail('rvf compact failed', { detail: compact.error, stderr: compact.stderr });
+            // 3. AgentDB index — best-effort via memory store (claude-flow bridges)
+            const indexValue = JSON.stringify({
+                rvf_id: input.session,
+                rvf_path: input.rvf_path,
+                host: input.host ?? null,
+                task: input.task ?? null,
+                verdict,
+                tags: input.tags ?? [],
+                ended_at: new Date().toISOString(),
+            });
+            const idx = await shell('npx', ['-y', '@claude-flow/cli@latest', 'memory', 'store',
+                '--namespace', 'browser-sessions',
+                '--key', input.session,
+                '--value', indexValue], { timeout: 60000 });
+            // Index failure is non-fatal — the RVF container is the source of truth.
+            return ok({
+                sessionId: input.session,
+                rvfPath: input.rvf_path,
+                verdict,
+                indexed: idx.success,
+                indexError: idx.success ? undefined : (idx.stderr || idx.error),
+            });
+        },
+    },
+    // ==========================================================================
+    // browser_session_replay — load a trajectory for caller-level dispatch
+    // ==========================================================================
+    {
+        name: 'browser_session_replay',
+        description: 'Load a recorded session trajectory and return its steps so the caller can dispatch them through the 23 browser_* tools. Does NOT itself drive the browser — replay execution is caller-orchestrated to keep this tool a primitive (ADR-0001 §7).',
+        category: 'browser-session',
+        tags: ['session', 'replay', 'trajectory', 'lifecycle'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session: { type: 'string', description: 'Source session id to replay' },
+                rvf_path: { type: 'string', description: 'Path to source .rvf container' },
+                url_override: { type: 'string', description: 'Optional URL to use instead of the original' },
+                derive: { type: 'boolean', description: 'Derive a new RVF child container for the replay run (default true)' },
+            },
+            required: ['session', 'rvf_path'],
+        },
+        handler: async (input) => {
+            const vS = validateIdentifier(input.session, 'session');
+            if (!vS.valid)
+                return fail(vS.error || 'invalid session');
+            // 1. Verify RVF container exists
+            const status = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'status', input.rvf_path]);
+            if (!status.success)
+                return fail('rvf status failed', { detail: status.error, stderr: status.stderr });
+            // 2. Derive child container if requested
+            let replayId = null;
+            let replayPath = null;
+            const derive = input.derive !== false;
+            if (derive) {
+                const path = await import('node:path');
+                const dir = path.dirname(input.rvf_path);
+                replayId = `${input.session}-replay-${Date.now()}`;
+                replayPath = path.join(dir, `${replayId}.rvf`);
+                const dr = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'derive', input.rvf_path, replayPath]);
+                if (!dr.success)
+                    return fail('rvf derive failed', { detail: dr.error, stderr: dr.stderr });
+            }
+            // 3. Surface the trajectory steps from the segments listing — the caller is
+            //    expected to read trajectory.ndjson from the RVF container and dispatch.
+            const segments = await shell('npx', ['-y', RUVECTOR_PIN, 'rvf', 'segments', input.rvf_path]);
+            return ok({
+                sourceSession: input.session,
+                sourceRvfPath: input.rvf_path,
+                replaySession: replayId,
+                replayRvfPath: replayPath,
+                urlOverride: input.url_override ?? null,
+                rvfStatus: status.stdout?.slice(0, 4000) ?? null,
+                rvfSegments: segments.stdout?.slice(0, 4000) ?? null,
+                nextStep: 'Caller MUST: (a) read trajectory.ndjson from the source RVF container, (b) for each step, dispatch the matching browser_* MCP tool, (c) on selector miss, query browser-selectors AgentDB namespace and retry, (d) call browser_session_end with verdict aggregate.',
+            });
+        },
+    },
+    // ==========================================================================
+    // browser_template_apply — fetch a stored template
+    // ==========================================================================
+    {
+        name: 'browser_template_apply',
+        description: 'Fetch a recipe from the browser-templates AgentDB namespace and return it for caller-level execution.',
+        category: 'browser-session',
+        tags: ['template', 'agentdb', 'extract'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Template name (key in browser-templates namespace)' },
+            },
+            required: ['name'],
+        },
+        handler: async (input) => {
+            const vN = validateText(input.name, 'name');
+            if (!vN.valid)
+                return fail(vN.error || 'invalid name');
+            const r = await shell('npx', ['-y', '@claude-flow/cli@latest', 'memory', 'retrieve',
+                '--namespace', 'browser-templates',
+                '--key', input.name], { timeout: 60000 });
+            if (!r.success)
+                return fail('template fetch failed', { detail: r.error, stderr: r.stderr });
+            return ok({
+                templateName: input.name,
+                recipe: r.stdout,
+                nextStep: 'Caller dispatches the recipe via browser_* tools; persist updated selectors to browser-selectors on success.',
+            });
+        },
+    },
+    // ==========================================================================
+    // browser_cookie_use — fetch a vaulted cookie handle
+    // ==========================================================================
+    {
+        name: 'browser_cookie_use',
+        description: 'Fetch a vault handle for a host from the browser-cookies AgentDB namespace. Raw cookie values are NEVER returned — only the opaque handle plus expiry / AIDefence verdict.',
+        category: 'browser-session',
+        tags: ['cookie', 'agentdb', 'aidefence', 'auth'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                host: { type: 'string', description: 'Host (e.g. "example.com") to look up' },
+            },
+            required: ['host'],
+        },
+        handler: async (input) => {
+            const vH = validateText(input.host, 'host');
+            if (!vH.valid)
+                return fail(vH.error || 'invalid host');
+            const r = await shell('npx', ['-y', '@claude-flow/cli@latest', 'memory', 'retrieve',
+                '--namespace', 'browser-cookies',
+                '--key', input.host], { timeout: 60000 });
+            if (!r.success)
+                return fail('cookie lookup failed', { detail: r.error, stderr: r.stderr });
+            // The contract: the value blob includes a vault_handle, expiry, aidefence_verdict.
+            // Raw values do not enter this namespace (browser-login is responsible).
+            return ok({
+                host: input.host,
+                vault: r.stdout,
+                nextStep: 'Caller mounts the handle via the browser runner; the raw cookie is materialized only inside the browser process, never returned to the model.',
+            });
+        },
+    },
+];
+export default browserSessionTools;
+//# sourceMappingURL=browser-session-tools.js.map

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

@@ -63,25 +63,11 @@ try {
             }
         }
     }
-    // Tier 4: mock fallback (last resort — embeddings are not semantic)
-    if (!realEmbeddings) {
-        const embeddingsModule = await import('@claude-flow/embeddings').catch(() => null);
-        if (embeddingsModule?.createEmbeddingService) {
-            try {
-                const service = embeddingsModule.createEmbeddingService({ provider: 'mock' });
-                realEmbeddings = {
-                    embed: async (text) => {
-                        const result = await service.embed(text);
-                        return Array.from(result.embedding);
-                    },
-                };
-                embeddingServiceName = 'mock-fallback';
-            }
-            catch {
-                // No embedding service available at all
-            }
-        }
-    }
+    // No Tier 4 mock fallback. If Tier 1 (agentic-flow) and Tier 3 (onnx)
+    // both failed to import, leave realEmbeddings null and let downstream
+    // code use the explicit hash-fallback path with a clear _embeddingNote
+    // in stats. Silently substituting mock embeddings would hide a missing
+    // production dependency from callers.
 }
 catch {
     // No embedding provider available, will use fallback

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.6.26",
+  "version": "3.6.28",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",