claude-flow 3.21.1 → 3.22.0

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

@@ -0,0 +1,175 @@
+/**
+ * Version-stamped critical-helper auto-refresh.
+ *
+ * The Claude Code hooks run the PROJECT-LOCAL `.claude/helpers/*.cjs` copies,
+ * not the installed npm package — so `npx ruflo@latest` does NOT update them,
+ * and users don't know to re-run `init`. This module stamps the helpers with
+ * the installed CLI version and, on the next CLI command, silently re-copies
+ * them when the stamp is stale. Hook fixes (e.g. the ADR-174 failure-capture
+ * change) then propagate to every user on their next `ruflo` command with zero
+ * action required.
+ *
+ * This file is intentionally LIGHTWEIGHT — it is imported on every CLI startup,
+ * so it depends only on `fs`/`path`/`module` at load time and lazily imports the
+ * heavy generators only on the rare fallback path (source dir unresolvable).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const HELPERS_STAMP_FILE = '.helpers-version';
+/** ruflo-owned helpers that carry hook logic and must track the package version. */
+export const CRITICAL_HELPERS = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export function getInstalledCliVersion() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(esmRequire.resolve('@claude-flow/cli/package.json'), 'utf-8'));
+        return String(pkg.version || '0.0.0');
+    }
+    catch {
+        // dist/src/init → package root
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+            return String(pkg.version || '0.0.0');
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
+function findPackageHelpersDir() {
+    const candidates = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = path.dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
+    }
+    catch { /* not resolvable */ }
+    candidates.push(path.resolve(__dirname, '..', '..', '..', '.claude', 'helpers'));
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
+            return c;
+    }
+    return null;
+}
+/**
+ * Re-copy the critical helpers into `helpersDir` and stamp `version`.
+ *
+ * SECURITY (fail-closed): when copying from the installed package, every source
+ * helper is verified against ruflo's Ed25519-signed manifest FIRST — nothing is
+ * copied unless the manifest signature is valid AND each helper's SHA-256
+ * matches. A tampered helper or manifest (e.g. a sibling package's postinstall
+ * overwriting on-disk hook code) is REFUSED, not propagated. The generator
+ * fallback needs no manifest — that content comes from the CLI's own compiled
+ * code, which is already the trust root.
+ */
+async function writeCriticalHelpers(helpersDir, version) {
+    const source = findPackageHelpersDir();
+    if (source) {
+        // 1. Verify the signed manifest against the baked public key.
+        let trusted = null;
+        try {
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'));
+        }
+        catch {
+            trusted = null;
+        }
+        if (!trusted)
+            return { wrote: false, blocked: 'signed helpers manifest missing or signature invalid' };
+        // 2. Verify EVERY source helper's hash before copying ANYTHING (atomic gate).
+        const toCopy = [];
+        for (const name of CRITICAL_HELPERS) {
+            const sp = path.join(source, name);
+            if (!fs.existsSync(sp))
+                continue;
+            const expected = trusted.files[name];
+            if (!expected || sha256Hex(fs.readFileSync(sp)) !== expected) {
+                return { wrote: false, blocked: `integrity check failed for ${name} — refusing to install` };
+            }
+            toCopy.push(name);
+        }
+        // 3. All verified — copy, plus the signed manifest itself as an audit trail.
+        let wrote = false;
+        for (const name of toCopy) {
+            const tp = path.join(helpersDir, name);
+            fs.copyFileSync(path.join(source, name), tp);
+            try {
+                fs.chmodSync(tp, '755');
+            }
+            catch { /* non-fatal */ }
+            wrote = true;
+        }
+        try {
+            fs.copyFileSync(path.join(source, HELPERS_MANIFEST_FILE), path.join(helpersDir, HELPERS_MANIFEST_FILE));
+        }
+        catch { /* non-fatal */ }
+        if (wrote) {
+            try {
+                fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+            }
+            catch { /* non-fatal */ }
+        }
+        return { wrote };
+    }
+    // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
+    // OWN compiled generators (the trust root; no external file to verify).
+    const gen = await import('./helpers-generator.js');
+    const files = {
+        'hook-handler.cjs': gen.generateHookHandler(),
+        'intelligence.cjs': gen.generateIntelligenceStub(),
+        'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+    };
+    let wrote = false;
+    for (const [name, content] of Object.entries(files)) {
+        const tp = path.join(helpersDir, name);
+        fs.writeFileSync(tp, content, 'utf-8');
+        try {
+            fs.chmodSync(tp, '755');
+        }
+        catch { /* non-fatal */ }
+        wrote = true;
+    }
+    if (wrote) {
+        try {
+            fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+        }
+        catch { /* non-fatal */ }
+    }
+    return { wrote };
+}
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ */
+export async function autoRefreshHelpersIfStale(cwd) {
+    try {
+        const helpersDir = path.join(cwd, '.claude', 'helpers');
+        if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
+            return { refreshed: false };
+        const version = getInstalledCliVersion();
+        let stamped = '';
+        try {
+            stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
+        }
+        catch { /* pre-feature: unstamped */ }
+        if (stamped === version)
+            return { refreshed: false }; // up to date — fast path
+        const res = await writeCriticalHelpers(helpersDir, version);
+        // A blocked refresh is a SECURITY signal (tampered source/manifest) — surface
+        // it, don't advance the stamp, and leave the project's existing helpers intact.
+        if (res.blocked)
+            return { refreshed: false, blocked: res.blocked };
+        return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+    }
+    catch {
+        return { refreshed: false };
+    }
+}
+//# sourceMappingURL=helper-refresh.js.map

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

@@ -0,0 +1,30 @@
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export declare const RUFLO_HELPERS_PUBKEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=\n-----END PUBLIC KEY-----";
+export declare const HELPERS_MANIFEST_FILE = "helpers.manifest.json";
+export interface HelpersManifest {
+    version: string;
+    files: Record<string, string>;
+}
+export interface SignedHelpersManifest {
+    manifest: HelpersManifest;
+    signature: string;
+    algorithm: 'ed25519';
+}
+export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export declare function canonicalManifestBytes(m: HelpersManifest): Buffer;
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export declare function verifyHelpersManifest(signedJson: string, pubkeyPem?: string): HelpersManifest | null;
+//# sourceMappingURL=helper-signing.d.ts.map

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

@@ -0,0 +1,60 @@
+/**
+ * Ed25519 provenance for the auto-refreshed critical helpers (ADR-174 security).
+ *
+ * The helper auto-refresh copies auto-EXECUTING hook code (`hook-handler.cjs`
+ * etc.) from the installed package into a project. npm verifies the tarball at
+ * INSTALL time, but not the files on disk afterward — a sibling package's
+ * postinstall (or disk tampering) could overwrite them, and the refresh would
+ * faithfully propagate the tampered code. This gate closes that: every helper
+ * is verified against a ruflo-signed manifest before install, and a mismatch is
+ * REFUSED (fail-closed). The public key is baked in below; the private key is
+ * never in the repo (see scripts/sign-helpers.mjs).
+ *
+ * Native Node crypto (RFC 8032 Ed25519), zero external deps — same primitive as
+ * src/appliance/rvfa-signing.ts.
+ */
+import { createHash, verify as edVerify } from 'crypto';
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export const RUFLO_HELPERS_PUBKEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=
+-----END PUBLIC KEY-----`;
+export const HELPERS_MANIFEST_FILE = 'helpers.manifest.json';
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export function canonicalManifestBytes(m) {
+    const files = {};
+    for (const k of Object.keys(m.files).sort())
+        files[k] = m.files[k];
+    return Buffer.from(JSON.stringify({ version: m.version, files }), 'utf-8');
+}
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export function verifyHelpersManifest(signedJson, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    try {
+        const signed = JSON.parse(signedJson);
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        if (!signed.manifest.files || typeof signed.manifest.files !== 'object')
+            return null;
+        const bytes = canonicalManifestBytes(signed.manifest);
+        const ok = edVerify(null, bytes, pubkeyPem, Buffer.from(signed.signature, 'base64'));
+        return ok ? signed.manifest : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=helper-signing.js.map

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

@@ -4,6 +4,22 @@
  */
 import type { InitOptions } from './types.js';
 export declare const ATTRIBUTION_FOOTER = "\uD83E\uDD16 Generated with [RuFlo](https://github.com/ruvnet/ruflo)";
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export declare function isToolFailure(hookInput: unknown): boolean;
 /**
  * Generate pre-commit hook script
  */

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

@@ -9,6 +9,58 @@ import { generateStatuslineScript, generateStatuslineHook } from './statusline-g
 // PR body templates and release notes.  It is NEVER hard-wired into the
 // static command-file templates — those are user-owned content.
 export const ATTRIBUTION_FOOTER = '🤖 Generated with [RuFlo](https://github.com/ruvnet/ruflo)';
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export function isToolFailure(hookInput) {
+    if (!hookInput || typeof hookInput !== 'object')
+        return false;
+    const h = hookInput;
+    const tr = (h.tool_response ?? h.toolResponse ?? h.result);
+    if (tr == null)
+        return false;
+    if (typeof tr === 'string') {
+        return /\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\b/i.test(tr);
+    }
+    if (typeof tr === 'object') {
+        const o = tr;
+        if (o.is_error === true || o.isError === true || o.success === false || o.error != null)
+            return true;
+        // Bash tool: non-zero exit code is a failure.
+        const code = (o.exit_code ?? o.exitCode ?? o.code);
+        if (typeof code === 'number' && code !== 0)
+            return true;
+        // Nested content array (Claude tool result shape): {content:[...], is_error:true}
+        if (Array.isArray(o.content) && o.is_error === true)
+            return true;
+    }
+    return false;
+}
+// The exact predicate the generated hook inlines — kept in sync with
+// isToolFailure() above (mirrored, since the generated .cjs has no imports).
+const TOOL_FAILURE_EXPR = '(function(hi){' +
+    'if(!hi||typeof hi!=="object")return false;' +
+    'var tr=hi.tool_response!=null?hi.tool_response:(hi.toolResponse!=null?hi.toolResponse:hi.result);' +
+    'if(tr==null)return false;' +
+    'if(typeof tr==="string")return /\\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\\b/i.test(tr);' +
+    'if(typeof tr==="object"){' +
+    'if(tr.is_error===true||tr.isError===true||tr.success===false||tr.error!=null)return true;' +
+    'var code=tr.exit_code!=null?tr.exit_code:(tr.exitCode!=null?tr.exitCode:tr.code);' +
+    'if(typeof code==="number"&&code!==0)return true;' +
+    'if(Array.isArray(tr.content)&&tr.is_error===true)return true;' +
+    '}return false;})(hookInput)';
 /**
  * Generate pre-commit hook script
  */
@@ -459,6 +511,9 @@ export function generateHookHandler() {
         '  // hook (#1944). Pull `.command` off whichever stdin shape Claude Code sent.',
         '  var toolInputObj = hookInput.toolInput || hookInput.tool_input || {};',
         "  var prompt = hookInput.prompt || hookInput.command || toolInputObj.command || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';",
+        '  // Capture FAILURES, not just successes, so the learning substrate has',
+        '  // negative examples (see ADR-174 / DB analysis). Mirrors isToolFailure().',
+        '  var toolFailed = ' + TOOL_FAILURE_EXPR + ';',
         '',
         'const handlers = {',
         "  'route': () => {",
@@ -503,10 +558,10 @@ export function generateHookHandler() {
         '    if (intelligence && intelligence.recordEdit) {',
         '      try {',
         "        var file = process.env.TOOL_INPUT_file_path || args[0] || '';",
-        '        intelligence.recordEdit(file);',
+        '        intelligence.recordEdit(file, !toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Edit recorded');",
+        "    console.log(toolFailed ? '[LEARN] Edit FAILURE recorded' : '[OK] Edit recorded');",
         '  },',
         '',
         "  'session-restore': () => {",
@@ -562,10 +617,10 @@ export function generateHookHandler() {
         "  'post-task': () => {",
         '    if (intelligence && intelligence.feedback) {',
         '      try {',
-        '        intelligence.feedback(true);',
+        '        intelligence.feedback(!toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Task completed');",
+        "    console.log(toolFailed ? '[LEARN] Task FAILURE recorded' : '[OK] Task completed');",
         '  },',
         '',
         "  'compact-manual': () => {",
@@ -809,10 +864,12 @@ export function generateIntelligenceStub() {
         '    return lines2.join("\\n");',
         '  },',
         '',
-        '  recordEdit: function(file) {',
+        '  recordEdit: function(file, success) {',
         '    if (!file) return;',
         '    ensureDir(DATA_DIR);',
-        '    var line = JSON.stringify({ type: "edit", file: file, timestamp: Date.now() }) + "\\n";',
+        '    // success defaults to true; an explicit false (failed edit) is recorded',
+        '    // so consolidation/distillation gets a negative example (ADR-174).',
+        '    var line = JSON.stringify({ type: "edit", file: file, success: success !== false, timestamp: Date.now() }) + "\\n";',
         '    fs.appendFileSync(PENDING_PATH, line, "utf-8");',
         '  },',
         '',

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

@@ -211,13 +211,24 @@ function getLocalAgentDB() {
     const memDb = path.join(CWD, '.swarm', 'memory.db');
     if (fs.existsSync(memDb)) {
       const Q = String.fromCharCode(34);
-      const sql = Q + 'SELECT (SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL)||' + "'|'" + '||(SELECT COUNT(*) FROM vector_indexes);' + Q;
-      const out = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + sql, 1500);
-      if (out && out.indexOf('|') !== -1) {
-        const parts = out.split('|');
-        result.vectorCount = parseInt(parts[0], 10) || 0;
-        result.hasHnsw = (parseInt(parts[1], 10) || 0) > 0;
-      }
+      // Two INDEPENDENT statements -- do NOT combine into one. Coupling the
+      // vector count with the vector_indexes row count in a single statement
+      // meant that on a DB missing the vector_indexes table (older/agentdb-
+      // written DBs), the whole statement failed at PREPARE time (SQLite
+      // compiles the full SQL before running), so the valid memory_entries
+      // count was discarded too and the statusline showed Vectors 0 despite
+      // thousands of real vectors. Split so a missing table can only zero the
+      // HNSW flag, never the count. The init self-heal provisions the table so
+      // the flag recovers on the next ruflo init / MCP start.
+      const countSql = Q + 'SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL;' + Q;
+      const vc = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + countSql, 1500);
+      if (vc) result.vectorCount = parseInt(vc, 10) || 0;
+      // HNSW flag: separate statement. If vector_indexes is absent, sqlite3
+      // exits non-zero and safeExec returns empty -- hasHnsw stays false (exact
+      // original semantics: at least one index-config row present).
+      const hnswSql = Q + 'SELECT COUNT(*) FROM vector_indexes;' + Q;
+      const hn = safeExec("sqlite3 'file:" + memDb + "?mode=ro' " + hnswSql, 1500);
+      if (hn) result.hasHnsw = (parseInt(hn, 10) || 0) > 0;
     }
   } catch { /* ignore */ }
   return result;

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

@@ -33,6 +33,10 @@ 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';
+// ADR-175 — page-agent natural-language intent layer (browser_act). Always
+// registered; degrades to {degraded:true} at call time when page-agent or an
+// OpenAI-compatible LLM provider isn't available.
+import { browserIntentTools } from './mcp-tools/browser-intent-tools.js';
 import { execFileSync } from 'node:child_process';
 // Phase 6: AgentDB v3 controller tools
 import { agentdbTools } from './mcp-tools/agentdb-tools.js';
@@ -89,6 +93,14 @@ function getBrowserTools() {
 function getBrowserSessionTools() {
     return browserSessionTools;
 }
+/**
+ * ADR-175 `browser_act` — always registered like browserSessionTools; the
+ * handler itself resolves page-agent + LLM-provider availability at call
+ * time and returns `{degraded: true}` rather than throwing.
+ */
+function getBrowserIntentTools() {
+    return browserIntentTools;
+}
 /**
  * MCP Tool Registry
  * Maps tool names to their handler functions
@@ -127,6 +139,7 @@ registerTools([
     ...coordinationTools,
     ...getBrowserTools(),
     ...getBrowserSessionTools(),
+    ...getBrowserIntentTools(),
     // Phase 6: AgentDB v3 controller tools
     ...agentdbTools,
     // RuVector WASM tools

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

@@ -115,11 +115,18 @@ export const agenticowSpeculateTools = [
             }
             // Build the generic {label, fn} candidates. Each fn ingests into its own
             // branch handle, then (for 'nearest') probes it so we can score.
+            // Map validated label → explicit branchPath so the branchPath() resolver
+            // below is O(1) instead of re-scanning + re-validating rawCandidates per
+            // candidate (explore() calls branchPath once per candidate → was O(n²)).
+            const explicitBranchPaths = new Map();
             const candidates = rawCandidates.map((c) => {
                 const label = validateLabel(String(c.label));
                 if (!Array.isArray(c.ingest) || c.ingest.length === 0) {
                     throw new Error(`candidate ${label} must ingest at least one vector`);
                 }
+                if (typeof c.branchPath === 'string' && c.branchPath) {
+                    explicitBranchPaths.set(label, c.branchPath);
+                }
                 const records = c.ingest.map((r) => ({
                     ...(Number.isInteger(r.id) ? { id: r.id } : {}),
                     vector: r.vector,
@@ -151,9 +158,9 @@ export const agenticowSpeculateTools = [
                 return 1 / (1 + Math.max(0, r.bestDistance));
             };
             const branchPath = (label) => {
-                const explicit = rawCandidates.find((c) => validateLabel(String(c.label)) === label)?.branchPath;
+                const explicit = explicitBranchPaths.get(label);
                 if (explicit)
-                    return resolveMemoryPath(String(explicit));
+                    return resolveMemoryPath(explicit);
                 return `${basePath}.spec-${safeSegment(label)}.rvf`;
             };
             // ADR-171 promotion gate. For pure memory A/B the `score` IS the chosen

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

@@ -0,0 +1,162 @@
+/**
+ * Browser Intent MCP Tools — ADR-175 page-agent integration.
+ *
+ * Adds a natural-language INTENT layer on top of the low-level selector-based
+ * `browser_*` tools (browser-tools.ts, driven by the `agent-browser` CLI).
+ * `browser_act({ task })` lets a caller say "Click the login button" instead
+ * of chaining browser_snapshot + browser_click.
+ *
+ * Backing library: `page-agent` (npm, MIT, https://github.com/alibaba/page-agent)
+ * — in-page injected JS that turns the DOM into text and lets an LLM execute
+ * natural-language intents via `agent.execute('Click login')`.
+ *
+ * ============================================================================
+ * VERIFIED API (recorded 2026-07-04 against page-agent@1.11.0 — `npm view
+ * page-agent`, the published README, and the actual npm tarball contents).
+ * Deviations from the original integration brief are called out inline.
+ * ============================================================================
+ *
+ * - Package layout changed since the brief was written: `page-agent` is now a
+ *   thin composition of `@page-agent/core` + `@page-agent/llms` +
+ *   `@page-agent/page-controller` + `@page-agent/ui`. The npm package is
+ *   ESM-only (`"type":"module"`) and ships two builds:
+ *     - `dist/esm/page-agent.js` — the Node/bundler ESM entry.
+ *     - `dist/iife/page-agent.demo.js` — a self-contained browser IIFE that
+ *       sets `window.PageAgent = <class>` (this is what we inject).
+ *
+ * - DEVIATION #1 (load-bearing): `await import('page-agent')` is NOT a safe
+ *   availability probe in Node. Empirically, importing the ESM entry throws
+ *   `ReferenceError: window is not defined` — even when the package IS
+ *   correctly installed — because `@page-agent/core`'s module graph touches
+ *   DOM globals at import time (it's designed to run in a browser, not Node).
+ *   This differs from the agenticow-loader.ts pattern used elsewhere in this
+ *   repo (dynamic `import()` + catch `ERR_MODULE_NOT_FOUND`), which only
+ *   works for pure-Node optional deps. Instead we detect availability via
+ *   `require.resolve('page-agent')` — path resolution only, never executes
+ *   module code — the same technique `browser-session-tools.ts` already uses
+ *   to resolve the local `ruvector` CLI bin without invoking it.
+ *
+ * - DEVIATION #2: the IIFE bundle unconditionally (also) auto-constructs a
+ *   DEMO `PageAgent` instance via `setTimeout`, pointed at Alibaba's public
+ *   sandbox endpoint (`model: 'qwen3.5-plus'`, a `page-ag-testing-*.run`
+ *   baseURL, `apiKey: 'NA'`) UNLESS the bundle is loaded via a real
+ *   `<script src="...?autoInit=false">` tag — the guard reads
+ *   `document.currentScript.src`, which is `null` when the bundle runs via
+ *   `eval`/CDP (our only injection path through the `agent-browser`
+ *   primitive set). Left alone, every `browser_act` call would leak page
+ *   content to Alibaba's test endpoint using a placeholder key. We strip the
+ *   demo auto-init tail (`stripDemoAutoInit`) before injecting rather than
+ *   relying on the query-param guard.
+ *
+ * - Constructor: `new PageAgent({ model, baseURL, apiKey, language })` —
+ *   `apiKey` is OPTIONAL on the type (`LLMConfig.apiKey?: string`), confirmed
+ *   in `@page-agent/llms`' `LLMConfig` interface.
+ *
+ * - `execute(task: string): Promise<ExecutionResult>` where
+ *   `ExecutionResult = { success: boolean; data: string; history: HistoricalEvent[] }`
+ *   — DEVIATION #3: NOT `{ success, result, steps }` as sketched in the
+ *   original brief. We map `data` → `result` and `history.length` → `steps`
+ *   in the tool's own return shape, and also pass `history` through for
+ *   callers that want the full step trace.
+ *
+ * - LLM transport: confirmed via `@page-agent/llms`' `OpenAIClient` — a
+ *   single non-streaming `POST ${baseURL}/chat/completions` with
+ *   `Authorization: Bearer ${apiKey}` and OpenAI tool-calling JSON. This is
+ *   why a bare `ANTHROPIC_API_KEY` cannot be handed to page-agent directly:
+ *   Anthropic's native API is a different shape (`/v1/messages`, different
+ *   tool-call format). We require an OpenAI-*compatible* endpoint — reusing
+ *   this CLI's own Tier-3 fallback ladder from `agent-execute-core.ts`
+ *   (OpenRouter, then Ollama Cloud), or an explicit override.
+ *
+ * ARCHITECTURAL CONSTRAINT (mirrors metaharness-tools.ts / agenticow-tools.ts)
+ * `page-agent` lives in `optionalDependencies`. Every code path degrades to
+ * `{ degraded: true }` — never throws — when the package or an LLM provider
+ * isn't available.
+ *
+ * KEY-SAFETY CONSTRAINT (load-bearing): page-agent's LLM calls happen FROM
+ * the browser page context (it's client-side injected JS), so its `apiKey`
+ * config field is necessarily visible to whatever we inject into the page.
+ * To avoid ever placing a real provider key into a page-context string, we
+ * start a short-lived local HTTP proxy (`startLocalLLMProxy`) bound to
+ * 127.0.0.1 that holds the REAL key server-side and injects the real
+ * `Authorization` header itself; the page only ever sees the proxy's
+ * loopback URL plus a constant placeholder string (`PLACEHOLDER_API_KEY`).
+ *
+ * @module @claude-flow/cli/mcp-tools/browser-intent
+ */
+import type { MCPTool } from './types.js';
+export interface PageAgentBundle {
+    /** Package root directory (contains package.json). */
+    root: string;
+    /** Absolute path to the browser-injectable IIFE bundle. */
+    iifePath: string;
+    version: string;
+}
+/**
+ * Locate the installed `page-agent` package's browser bundle without ever
+ * executing its module code. `resolvePkg` is injectable for tests (DI over
+ * module mocking, since `vi.mock('page-agent', ...)` cannot simulate absence
+ * for a package we deliberately never `import()`).
+ */
+export declare function locatePageAgentBundle(resolvePkg?: (id: string) => string): PageAgentBundle | null;
+export interface ResolvedLLMConfig {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    source: 'explicit' | 'openrouter' | 'ollama';
+}
+export declare function resolvePageAgentLLMConfig(env?: NodeJS.ProcessEnv): ResolvedLLMConfig | null;
+export declare const PLACEHOLDER_API_KEY = "ruflo-proxied-key";
+export interface LLMProxyHandle {
+    url: string;
+    close: () => void;
+}
+export declare function startLocalLLMProxy(real: {
+    baseURL: string;
+    apiKey: string;
+}): Promise<LLMProxyHandle>;
+/** Thrown when a bundle still contains a demo/sandbox endpoint after stripping. */
+export declare class DemoLeakError extends Error {
+    readonly signature: string;
+    constructor(signature: string);
+}
+/** Returns the first demo-leak signature found in `source`, or null if clean. */
+export declare function findDemoLeak(source: string): string | null;
+/**
+ * Strip the demo bundle's auto-init tail so injecting it via eval doesn't spin
+ * up a second `window.pageAgent` pointed at Alibaba's sandbox endpoint. This is
+ * best-effort at the text level; the real guarantee is the fail-closed
+ * `findDemoLeak` firewall enforced in `buildPageAgentInjection`, NOT this strip.
+ */
+export declare function stripDemoAutoInit(iifeSource: string): string;
+export declare const BROWSER_ACT_RESULT_GLOBAL = "__ruflo_browser_act_result__";
+export interface PageAgentPageConfig {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    language?: string;
+}
+/**
+ * Build the full script to hand to `browser_eval` / `agent-browser eval`:
+ * the (demo-stripped) IIFE bundle, followed by our own controlled
+ * construction + `execute()` call whose settled result lands on a window
+ * global we can poll for.
+ *
+ * KEY-SAFETY: `pageConfig.apiKey` MUST be `PLACEHOLDER_API_KEY` (or another
+ * non-secret placeholder) — callers are responsible for routing the real key
+ * through `startLocalLLMProxy` first. This function only assembles strings;
+ * it does not itself guarantee key safety, so callers MUST NOT pass a real
+ * key here (see `browserIntentTools` handler for the enforced call site).
+ */
+export declare function buildPageAgentInjection(iifeSource: string, pageConfig: PageAgentPageConfig, task: string): string;
+export declare function recordBrowserTrajectory(entry: {
+    task: string;
+    url?: string;
+    success: boolean;
+    dataPreview: string;
+    steps: number;
+    source: string;
+}): Promise<boolean>;
+export declare const browserIntentTools: MCPTool[];
+export default browserIntentTools;
+//# sourceMappingURL=browser-intent-tools.d.ts.map