@claude-flow/cli 3.32.1 → 3.32.3

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

@@ -1,59 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1,209 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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