@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/mcp-tools/agenticow-loader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Agenticow shared loader + helpers.
+ *
+ * Extracted from `agenticow-tools.ts` so both the MCP tool surface AND the
+ * `SwarmMemoryBranches` service (src/services/swarm-memory-branches.ts) share
+ * one loader, one degradation contract, and one set of path/lineage helpers —
+ * rather than duplicating the optional-dep dance in two places.
+ *
+ * Architectural constraint (ADR-150, mirrors metaharness-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — never a hard runtime dep.
+ *   - When the package is missing, callers get `null` from `loadAgenticow()`
+ *     (or a `{degraded:true}` result via `degradedResult`) and MUST fall back
+ *     gracefully — never throw a MODULE_NOT_FOUND.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-loader
+ */
+export declare const PACKAGE_NAME = "agenticow";
+export interface AgenticowApi {
+    open: (file: string, opts?: {
+        dimension?: number;
+        metric?: string;
+    }) => Promise<any>;
+    openBase?: (file: string, opts?: any) => Promise<any>;
+    AgenticMemory: any;
+}
+/**
+ * Lazily import `agenticow`. Returns the module on success, or `null` when the
+ * package is not installed (the optional-dep degraded path). Any OTHER load
+ * error (e.g. a corrupt install) is re-thrown so it is not silently masked.
+ */
+export declare function loadAgenticow(): Promise<AgenticowApi | null>;
+/** Reset the module-level load cache. Test-only seam. */
+export declare function __resetAgenticowCache(): void;
+export declare function degradedResult(reason: string): {
+    success: true;
+    degraded: true;
+    reason: string;
+};
+/**
+ * Resolve a user-supplied memory path against the project cwd, rejecting path
+ * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
+ */
+export declare function resolveMemoryPath(path: string): string;
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
+ * disappear when the AgenticMemory handle closes.
+ */
+export declare function manifestFor(file: string): string;
+/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
+export declare function validateLabel(label: string): string;
+/**
+ * Open (or create) a memory file, restoring its COW chain from the lineage
+ * manifest when one exists. When neither the `.rvf` nor the manifest exists,
+ * `dimension` is required to create a fresh base.
+ */
+export declare function openWithLineage(api: AgenticowApi, file: string, dimension?: number): Promise<any>;
+//# sourceMappingURL=agenticow-loader.d.ts.map

package/dist/src/mcp-tools/agenticow-loader.js

@@ -0,0 +1,105 @@
+/**
+ * Agenticow shared loader + helpers.
+ *
+ * Extracted from `agenticow-tools.ts` so both the MCP tool surface AND the
+ * `SwarmMemoryBranches` service (src/services/swarm-memory-branches.ts) share
+ * one loader, one degradation contract, and one set of path/lineage helpers —
+ * rather than duplicating the optional-dep dance in two places.
+ *
+ * Architectural constraint (ADR-150, mirrors metaharness-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — never a hard runtime dep.
+ *   - When the package is missing, callers get `null` from `loadAgenticow()`
+ *     (or a `{degraded:true}` result via `degradedResult`) and MUST fall back
+ *     gracefully — never throw a MODULE_NOT_FOUND.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-loader
+ */
+import { existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { getProjectCwd } from './types.js';
+export const PACKAGE_NAME = 'agenticow';
+// Cache: module load is expensive enough to amortize across handler calls.
+// null = not yet attempted; false = attempted and unavailable; module = loaded.
+let _agenticowMod = null;
+let _loadAttempted = false;
+/**
+ * Lazily import `agenticow`. Returns the module on success, or `null` when the
+ * package is not installed (the optional-dep degraded path). Any OTHER load
+ * error (e.g. a corrupt install) is re-thrown so it is not silently masked.
+ */
+export async function loadAgenticow() {
+    if (_loadAttempted)
+        return _agenticowMod || null;
+    _loadAttempted = true;
+    try {
+        _agenticowMod = await import(PACKAGE_NAME);
+        return _agenticowMod;
+    }
+    catch (err) {
+        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
+            /Cannot find (module|package)/i.test(String(err.message)))) {
+            _agenticowMod = false;
+            return null;
+        }
+        throw err;
+    }
+}
+/** Reset the module-level load cache. Test-only seam. */
+export function __resetAgenticowCache() {
+    _agenticowMod = null;
+    _loadAttempted = false;
+}
+export function degradedResult(reason) {
+    return { success: true, degraded: true, reason };
+}
+/**
+ * Resolve a user-supplied memory path against the project cwd, rejecting path
+ * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
+ */
+export function resolveMemoryPath(path) {
+    if (!path || typeof path !== 'string')
+        throw new Error('memory path is required');
+    if (/\.\.[\\/]|\0/.test(path))
+        throw new Error('memory path contains disallowed characters');
+    return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
+}
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
+ * disappear when the AgenticMemory handle closes.
+ */
+export function manifestFor(file) {
+    return `${file}.agenticow.json`;
+}
+/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
+export function validateLabel(label) {
+    if (!label || typeof label !== 'string')
+        throw new Error('label is required');
+    if (label.length > 256)
+        throw new Error('label exceeds 256 chars');
+    if (!/^[A-Za-z0-9_.\-:/@]+$/.test(label)) {
+        throw new Error('label may only contain [A-Za-z0-9_.\\-:/@]');
+    }
+    return label;
+}
+/**
+ * Open (or create) a memory file, restoring its COW chain from the lineage
+ * manifest when one exists. When neither the `.rvf` nor the manifest exists,
+ * `dimension` is required to create a fresh base.
+ */
+export async function openWithLineage(api, file, dimension) {
+    const manifest = manifestFor(file);
+    if (existsSync(manifest)) {
+        return api.AgenticMemory.load(manifest);
+    }
+    const opts = {};
+    if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {
+        opts.dimension = dimension;
+    }
+    else if (!existsSync(file)) {
+        throw new Error('dimension is required when creating a new memory file');
+    }
+    return api.open(file, opts);
+}
+//# sourceMappingURL=agenticow-loader.js.map

package/dist/src/mcp-tools/agenticow-speculate-tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import type { MCPTool } from './types.js';
+export declare const agenticowSpeculateTools: MCPTool[];
+//# sourceMappingURL=agenticow-speculate-tools.d.ts.map

package/dist/src/mcp-tools/agenticow-speculate-tools.js

@@ -0,0 +1,209 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import { loadAgenticow, degradedResult, resolveMemoryPath, openWithLineage, manifestFor, validateLabel, } from './agenticow-loader.js';
+import { explore, } from '../agenticow/speculative-exploration.js';
+/** Turn a validated label into a filesystem-safe branch filename segment. */
+function safeSegment(label) {
+    return label.replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 64) || 'branch';
+}
+export const agenticowSpeculateTools = [
+    {
+        name: 'agenticow_speculate',
+        description: "agenticow — speculative branch-and-promote for parallel A/B memory exploration. " +
+            "Forks a 162-byte COW branch per candidate off a shared base .rvf, ingests each candidate's " +
+            "vectors into its OWN isolated branch, scores every branch (probe-query 'nearest' distance or " +
+            "ingest 'count'), PROMOTES the winning branch's edits into base, and DISCARDS the losers by " +
+            "deleting their branch files. Use when you want to try N competing memory-write strategies and " +
+            "keep only the best — the memory-state analogue of worktree-per-agent code exploration. " +
+            "Copying the base per candidate is wrong (full-copy snapshots grow linearly, the 3.3 GB Darwin " +
+            "bloat); COW forks are constant-size and losers cost ~162 B to throw away. Optional dep — " +
+            "degrades to {degraded:true} when agenticow is missing.",
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'speculative', 'branch', 'promote', 'ab'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Path to base .rvf memory file (absolute or relative to cwd)',
+                },
+                dimension: {
+                    type: 'integer',
+                    description: 'Vector dimension (required only when basePath does not exist yet)',
+                },
+                candidates: {
+                    type: 'array',
+                    description: 'The A/B candidates. Each explores its own COW branch.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string', description: 'Branch label (alnum + _.-:/@ only)' },
+                            ingest: {
+                                type: 'array',
+                                description: 'Vectors to ingest into this candidate branch',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: { type: 'integer', description: 'Explicit vector id (auto when omitted)' },
+                                        vector: { type: 'array', items: { type: 'number' }, description: 'Dense vector' },
+                                        text: { type: 'string', description: 'Optional payload text' },
+                                    },
+                                    required: ['vector'],
+                                },
+                            },
+                            branchPath: {
+                                type: 'string',
+                                description: 'Optional explicit path for this branch file (default: alongside base)',
+                            },
+                        },
+                        required: ['label', 'ingest'],
+                    },
+                },
+                probe: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: "Probe vector for scoreBy='nearest' (scores each branch by best-hit similarity)",
+                },
+                k: { type: 'integer', description: 'Nearest-neighbours to fetch per probe (default 1)' },
+                scoreBy: {
+                    type: 'string',
+                    enum: ['nearest', 'count'],
+                    description: "'nearest' = closest probe distance wins; 'count' = most accepted ingests wins. Default 'nearest'.",
+                },
+                requireClearance: {
+                    type: 'boolean',
+                    description: 'ADR-171 fail-closed gate. When true, the top-scored winner is NOT promoted (base stays unchanged) and a provenance-tagged receipt is emitted — score alone cannot graduate work. Use when speculating over TASK outcomes rather than pure memory A/B. Default false (score-only promotion, tagged `unverified`).',
+                    default: false,
+                },
+            },
+            required: ['basePath', 'candidates'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const basePath = resolveMemoryPath(String(input.basePath));
+            const dimension = input.dimension;
+            const scoreBy = input.scoreBy === 'count' ? 'count' : 'nearest';
+            const k = Number.isInteger(input.k) && input.k > 0 ? input.k : 1;
+            const probe = Array.isArray(input.probe) ? input.probe : null;
+            const rawCandidates = input.candidates;
+            if (!Array.isArray(rawCandidates) || rawCandidates.length === 0) {
+                throw new Error('at least one candidate is required');
+            }
+            if (scoreBy === 'nearest' && !probe) {
+                throw new Error("scoreBy='nearest' requires a probe vector");
+            }
+            // 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,
+                    ...(typeof r.text === 'string' ? { text: r.text } : {}),
+                }));
+                return {
+                    label,
+                    fn: (branch) => {
+                        const res = branch.ingest(records);
+                        const accepted = Number(res?.accepted ?? records.length);
+                        let hits = [];
+                        if (probe) {
+                            hits = (branch.query(probe, k) || []).map((h) => ({
+                                id: h.id,
+                                distance: h.distance,
+                            }));
+                        }
+                        const bestDistance = hits.length ? hits[0].distance : null;
+                        return { accepted, bestDistance, hits };
+                    },
+                };
+            });
+            const score = (r) => {
+                if (scoreBy === 'count')
+                    return r.accepted;
+                // nearest: smaller distance = better. Map to a higher-is-better score.
+                if (r.bestDistance === null)
+                    return -Infinity;
+                return 1 / (1 + Math.max(0, r.bestDistance));
+            };
+            const branchPath = (label) => {
+                const explicit = explicitBranchPaths.get(label);
+                if (explicit)
+                    return resolveMemoryPath(explicit);
+                return `${basePath}.spec-${safeSegment(label)}.rvf`;
+            };
+            // ADR-171 promotion gate. For pure memory A/B the `score` IS the chosen
+            // metric (not a proxy for task correctness), so score-only promotion is
+            // legitimate and stays the default (tagged `unverified`, never
+            // masquerading as ground truth). Callers grafting this onto TASK work
+            // pass requireClearance:true to fail-closed — the winner is then
+            // ineligible unless a real clearance mechanism graduates it.
+            const requireClearance = input.requireClearance === true;
+            const exploreOpts = { branchPath, persist: true };
+            if (requireClearance)
+                exploreOpts.requireClearance = true;
+            // Open base, run the speculative exploration, persist base with the winner promoted.
+            const base = await openWithLineage(api, basePath, dimension);
+            try {
+                const result = await explore(base, candidates, score, exploreOpts);
+                base.save?.(manifestFor(basePath));
+                return {
+                    success: true,
+                    basePath,
+                    scoreBy,
+                    winner: result.winner,
+                    scores: result.scores,
+                    promoted: result.promoted,
+                    promotedBy: result.promotedBy,
+                    promotionDecision: result.promotionDecision,
+                    promoteStats: result.promoteStats,
+                    discarded: result.discarded,
+                    receipts: result.receipts,
+                    branches: result.branches.map((b) => ({
+                        label: b.label,
+                        path: b.path,
+                        score: b.score,
+                        kept: b.kept,
+                        accepted: b.result.accepted,
+                        bestDistance: b.result.bestDistance,
+                    })),
+                };
+            }
+            finally {
+                await base.close?.();
+            }
+        },
+    },
+];
+//# sourceMappingURL=agenticow-speculate-tools.js.map

package/dist/src/mcp-tools/agenticow-tools.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agenticow MCP Tools — Copy-On-Write memory branching surface.
+ *
+ * Exposes `agenticow@~0.2.3` (a sibling RVF-based COW vector store by the same
+ * author as ruflo) as MCP tools so agents can branch, checkpoint, rollback,
+ * and promote memory state without copying GB-scale `.rvf` files.
+ *
+ * Motivation:
+ *   The v3.14.4 release uncovered a tarball-bloat regression where Darwin
+ *   loops' git-worktree-per-agent pattern accumulated 3.3 GB of disk. The
+ *   structural cause was full-copy snapshot semantics. Measured agenticow
+ *   branches are exactly 162 bytes regardless of base size (see
+ *   `docs/agenticow/findings.md` for the bench data).
+ *
+ * Architectural constraint (mirrors metaharness-tools.ts / testgen-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — must NOT be a hard runtime dep
+ *   - When the package is missing, every tool returns
+ *     `{success: true, degraded: true, reason: 'agenticow-not-found'}`
+ *     so callers see one contract regardless of install state
+ *
+ * Measured performance vs published claims (agenticow@0.2.3):
+ *   ✅ 162-byte branches — confirmed exact
+ *   ✅ 3,000×–180,000× smaller than full-copy at N=1k–50k
+ *   ❌ 0.5 ms branch — measured ~10ms (fixed cost, not size-proportional)
+ *   ❌ 83× faster — only beats full-copy past N ≈ 30k crossover
+ *
+ * Use cases (per ADR / findings doc):
+ *   - Per-Darwin-iteration memory branching (eliminates worktree bloat)
+ *   - Per-user / per-session personalization (cheap fork, no full copy)
+ *   - Federation: branch → promote back as merge semantics
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow
+ */
+import type { MCPTool } from './types.js';
+export declare const agenticowTools: MCPTool[];
+//# sourceMappingURL=agenticow-tools.d.ts.map