claude-flow 3.20.0 → 3.21.1

package/v3/@claude-flow/cli/dist/src/services/fable-harness.js

@@ -0,0 +1,347 @@
+/**
+ * fable-harness.ts — Cost-disciplined headless Fable LLM-as-judge harness.
+ *
+ * This is TIER 2 of the tiered `resolved` oracle (see distill-oracle.ts). When
+ * a trajectory has NO mechanical test spec to execute, we judge whether its
+ * completion actually resolved the task with a headless Fable model — a smarter
+ * proxy than the structural verifier, but still a proxy (provenance tag
+ * `judge:fable`, never presented as ground truth per ADR-169).
+ *
+ * ── MEASURED COST DATA (load-bearing — this file is built around it) ────────
+ * `claude -p --model claude-fable-5 --output-format json` costs, per call:
+ *   • ~$1.56  when launched FROM THE PROJECT DIR — it auto-loads CLAUDE.md and
+ *             ~56k cache tokens of project context we do NOT want for judging.
+ *   • ~$0.34  from a CLEAN empty cwd with `--append-system-prompt` for the role.
+ *   • ~$0.02/item when we BATCH ~20 items into a single call (context amortizes
+ *             ~free across the batch).
+ *
+ * Therefore this harness MUST, and does:
+ *   1. run `claude -p` from a FRESH EMPTY TEMP cwd — never the project dir, so
+ *      no CLAUDE.md / project context is loaded (the 5x cost driver);
+ *   2. carry the judge/reflect role via `--append-system-prompt`, not a project
+ *      system prompt;
+ *   3. BATCH N items per call (default 20) so per-item cost collapses to ~$0.02;
+ *   4. pass `--max-budget-usd` as a hard per-call cap and stop launching batches
+ *      once the cumulative measured spend reaches the caller's budget;
+ *   5. be OPT-IN and OFF BY DEFAULT — nothing here runs unless a caller
+ *      explicitly constructs the harness AND provides a budget cap.
+ *
+ * SAFETY: constructing this class spends nothing. Only `judgeBatch` /
+ * `reflectFailures` spawn `claude`, and only when `maxBudgetUsd > 0`. The
+ * `spawnClaude` implementation is injectable so tests never touch the real CLI.
+ *
+ * @module services/fable-harness
+ */
+import { spawn } from 'child_process';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+// ── Cost model (measured — exported so callers/docs share one source) ────────
+export const FABLE_COST_MODEL = {
+    /** Measured $/call when launched from the project dir (loads CLAUDE.md). Anti-pattern. */
+    perCallProjectCwdUsd: 1.56,
+    /** Measured $/call from a clean cwd with --append-system-prompt. */
+    perCallCleanCwdUsd: 0.34,
+    /** Measured amortized $/item when batching ~20 items per call. */
+    perItemBatchedUsd: 0.02,
+    /** Default items per `claude -p` call. */
+    defaultBatchSize: 20,
+    /** The judge model. */
+    model: 'claude-fable-5',
+};
+/**
+ * Estimate the USD cost of judging `itemCount` items in batches of `batchSize`.
+ * Uses the measured amortized per-item figure; callers use this to size a
+ * budget cap before opting in.
+ */
+export function estimateFableCostUsd(itemCount, batchSize = FABLE_COST_MODEL.defaultBatchSize) {
+    if (itemCount <= 0)
+        return 0;
+    const batches = Math.ceil(itemCount / Math.max(1, batchSize));
+    // Amortized per-item dominates; add a tiny floor per batch for the base call.
+    const perItem = itemCount * FABLE_COST_MODEL.perItemBatchedUsd;
+    const perBatchFloor = batches * 0.0; // per-item figure already includes base amortization
+    return Number((perItem + perBatchFloor).toFixed(4));
+}
+// ── Prompt templates (carried via --append-system-prompt) ────────────────────
+const JUDGE_SYSTEM_PROMPT = [
+    'You are a strict evaluator judging whether an agent trajectory RESOLVED its task.',
+    'You receive a JSON array of items: [{id, task, output}].',
+    'For each item decide if `output` genuinely and correctly resolves `task`.',
+    'Be conservative: plausible-but-unverified or partial completions are NOT resolved.',
+    'Reply with ONLY a JSON array, one object per input id, no prose:',
+    '[{"id": "...", "resolved": true|false, "confidence": 0.0-1.0, "reason": "<one sentence>"}]',
+].join('\n');
+const REFLECT_SYSTEM_PROMPT = [
+    'You are a failure-analysis expert supporting reflective mutation (GEPA/evolve).',
+    'You receive a JSON array of items: [{id, task, output, failureHint?}].',
+    'For each item, classify the failure and propose a concrete mutation hint.',
+    'Reply with ONLY a JSON array, one object per input id, no prose:',
+    '[{"id":"...","failureClass":"<short label>","diagnosis":"<one sentence>","mutationHint":"<actionable>"}]',
+].join('\n');
+// ── Default spawner (real CLI) ───────────────────────────────────────────────
+/**
+ * Default `claude -p` spawner. Pipes the prompt via stdin (never as an argv
+ * positional — mirrors the #1852 fix so shell metachars in prompts are never
+ * re-tokenized), runs in the provided (temp) cwd, and returns stdout/stderr.
+ * Parses `total_cost_usd` from the `--output-format json` envelope when present.
+ */
+export const defaultSpawnClaude = (argv, stdinPrompt, cwd, opts) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spawn('claude', argv, {
+            cwd,
+            env: { ...process.env, CLAUDE_ENTRYPOINT: 'fable-judge' },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        resolve({ stdout: '', stderr: err instanceof Error ? err.message : String(err), code: null });
+        return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let done = false;
+    const finish = (r) => {
+        if (done)
+            return;
+        done = true;
+        clearTimeout(timer);
+        resolve(r);
+    };
+    const timer = setTimeout(() => {
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* already dead */ }
+        finish({ stdout, stderr: stderr || `timed out after ${opts.timeoutMs}ms`, code: null });
+    }, opts.timeoutMs);
+    timer.unref?.();
+    try {
+        child.stdin?.end(stdinPrompt);
+    }
+    catch { /* surfaced via error */ }
+    child.stdout?.on('data', (d) => { stdout += d.toString(); });
+    child.stderr?.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (e) => finish({ stdout, stderr: e.message, code: null }));
+    child.on('close', (code) => {
+        finish({ stdout, stderr, code, costUsd: parseCostFromEnvelope(stdout) });
+    });
+});
+/** Pull `total_cost_usd`/`cost_usd` out of a claude `--output-format json` envelope. */
+export function parseCostFromEnvelope(stdout) {
+    const env = tryParseJson(stdout);
+    if (env && typeof env === 'object') {
+        const o = env;
+        for (const k of ['total_cost_usd', 'cost_usd', 'costUsd']) {
+            if (typeof o[k] === 'number')
+                return o[k];
+        }
+    }
+    return undefined;
+}
+// ── Harness ──────────────────────────────────────────────────────────────
+export class FableHarness {
+    model;
+    batchSize;
+    maxBudgetUsd;
+    timeoutMs;
+    spawnClaude;
+    spentUsd = 0;
+    constructor(opts = {}) {
+        this.model = opts.model ?? FABLE_COST_MODEL.model;
+        this.batchSize = Math.max(1, opts.batchSize ?? FABLE_COST_MODEL.defaultBatchSize);
+        this.maxBudgetUsd = opts.maxBudgetUsd ?? 0;
+        this.timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000;
+        this.spawnClaude = opts.spawnClaude ?? defaultSpawnClaude;
+    }
+    /** Cumulative measured spend across all calls this harness has made. */
+    getSpentUsd() {
+        return Number(this.spentUsd.toFixed(4));
+    }
+    /** True when a positive budget cap is configured (a precondition for any spend). */
+    isEnabled() {
+        return this.maxBudgetUsd > 0;
+    }
+    /**
+     * Judge a set of items in batches. Returns one JudgeResult per input id that
+     * the model returned. Items that fall outside the budget, or that the model
+     * omits, are simply absent from the result — the caller (distill-oracle) is
+     * responsible for falling back to the structural proxy for those.
+     *
+     * Spends $0 and returns [] when no budget cap is configured.
+     */
+    async judgeBatch(items) {
+        if (items.length === 0)
+            return [];
+        if (!this.isEnabled())
+            return [];
+        const out = [];
+        for (const batch of chunk(items, this.batchSize)) {
+            if (this.spentUsd >= this.maxBudgetUsd)
+                break;
+            const parsed = await this.runBatch(JUDGE_SYSTEM_PROMPT, batch);
+            for (const raw of parsed) {
+                const r = normalizeJudge(raw);
+                if (r)
+                    out.push(r);
+            }
+        }
+        return out;
+    }
+    /**
+     * Reflective failure analysis over items — the second cost-disciplined entry
+     * point, used by GEPA/evolve for mutation hints. Same batching + budget
+     * discipline as judgeBatch. Returns [] when no budget cap is configured.
+     */
+    async reflectFailures(items) {
+        if (items.length === 0)
+            return [];
+        if (!this.isEnabled())
+            return [];
+        const out = [];
+        for (const batch of chunk(items, this.batchSize)) {
+            if (this.spentUsd >= this.maxBudgetUsd)
+                break;
+            const parsed = await this.runBatch(REFLECT_SYSTEM_PROMPT, batch);
+            for (const raw of parsed) {
+                const r = normalizeReflect(raw);
+                if (r)
+                    out.push(r);
+            }
+        }
+        return out;
+    }
+    /** Build the argv for a `claude -p` call. Exposed shape for testability. */
+    buildArgv(systemPrompt) {
+        const perCallCap = Math.max(0, this.maxBudgetUsd - this.spentUsd);
+        return [
+            '-p',
+            '--model', this.model,
+            '--output-format', 'json',
+            '--append-system-prompt', systemPrompt,
+            '--max-budget-usd', String(round(perCallCap)),
+        ];
+    }
+    /**
+     * Run one batch: create a FRESH EMPTY temp cwd (critical — no project
+     * context), spawn `claude -p` there with the role via --append-system-prompt,
+     * pipe the batch JSON to stdin, parse the verdict array out of the envelope,
+     * and account the measured spend.
+     */
+    async runBatch(systemPrompt, batch) {
+        const argv = this.buildArgv(systemPrompt);
+        const stdinPrompt = JSON.stringify(batch);
+        const cwd = await mkdtemp(join(tmpdir(), 'ruflo-fable-'));
+        try {
+            const res = await this.spawnClaude(argv, stdinPrompt, cwd, { timeoutMs: this.timeoutMs });
+            // Account spend: prefer measured envelope cost, else the amortized estimate.
+            this.spentUsd += typeof res.costUsd === 'number'
+                ? res.costUsd
+                : estimateFableCostUsd(batch.length, this.batchSize);
+            if (res.code !== 0 && !res.stdout)
+                return [];
+            return extractVerdictArray(res.stdout);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}
+// ── Parsing helpers ──────────────────────────────────────────────────────
+/**
+ * Extract the model's verdict array. `claude -p --output-format json` wraps the
+ * assistant text in an envelope `{ result: "<text>", ... }`; the text is itself
+ * the JSON array we asked for. Handle both the enveloped and bare forms, and
+ * arrays fenced in ```json blocks.
+ */
+export function extractVerdictArray(stdout) {
+    const trimmed = (stdout ?? '').trim();
+    if (!trimmed)
+        return [];
+    // 1. Enveloped: parse envelope, then its `result` field.
+    const env = tryParseJson(trimmed);
+    if (env && typeof env === 'object' && !Array.isArray(env)) {
+        const result = env.result;
+        if (typeof result === 'string') {
+            const inner = findJsonArray(result);
+            if (inner)
+                return inner;
+        }
+        // Some envelopes embed the array directly.
+        const direct = env.results;
+        if (Array.isArray(direct))
+            return direct;
+    }
+    if (Array.isArray(env))
+        return env;
+    // 2. Bare text: find a JSON array anywhere in stdout.
+    const arr = findJsonArray(trimmed);
+    return arr ?? [];
+}
+function findJsonArray(text) {
+    const fenced = text.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
+    if (fenced) {
+        const v = tryParseJson(fenced[1]);
+        if (Array.isArray(v))
+            return v;
+    }
+    const bare = text.match(/\[[\s\S]*\]/);
+    if (bare) {
+        const v = tryParseJson(bare[0]);
+        if (Array.isArray(v))
+            return v;
+    }
+    return null;
+}
+function normalizeJudge(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (typeof o.id !== 'string')
+        return null;
+    return {
+        id: o.id,
+        resolved: o.resolved === true || o.resolved === 'true',
+        confidence: clamp01(typeof o.confidence === 'number' ? o.confidence : Number(o.confidence)),
+        reason: typeof o.reason === 'string' ? o.reason : '',
+    };
+}
+function normalizeReflect(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (typeof o.id !== 'string')
+        return null;
+    return {
+        id: o.id,
+        failureClass: typeof o.failureClass === 'string' ? o.failureClass : 'unknown',
+        diagnosis: typeof o.diagnosis === 'string' ? o.diagnosis : '',
+        mutationHint: typeof o.mutationHint === 'string' ? o.mutationHint : '',
+    };
+}
+function tryParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+function chunk(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+export default FableHarness;
+//# sourceMappingURL=fable-harness.js.map

package/v3/@claude-flow/cli/dist/src/services/swarm-memory-branches.d.ts

@@ -0,0 +1,135 @@
+/**
+ * SwarmMemoryBranches — per-agent Copy-On-Write memory branching for swarms.
+ *
+ * ## Why this exists
+ *
+ * The v3.14.4 release uncovered a tarball-bloat regression: the Darwin
+ * git-worktree-per-agent pattern accumulated 3.3 GB of disk because each
+ * agent got a *full copy* of shared state. `agenticow` (a sibling RVF-based
+ * COW vector store by the same author) forks a branch in a measured **162
+ * bytes** regardless of base size — read-through semantics (parent ∪ edits,
+ * child wins) instead of a linear-growth snapshot.
+ *
+ * This service is the swarm-facing consumer of that primitive. The pattern
+ * mirrors `agenticow`'s own `examples/parallel-agents`:
+ *
+ *   shared base .rvf
+ *     → each agent forks a 162-byte COW branch (nativeAnn:true) at spawn
+ *     → the agent reads/writes its branch in isolation
+ *     → on success: promote branch → base (merge its edits back)
+ *     → on failure: discard the branch file (throw the edits away)
+ *
+ * ## Honest scope (the seam)
+ *
+ * The current `agent_spawn` MCP path (src/mcp-tools/agent-tools.ts) stores an
+ * agent as pure JSON metadata — it does **not** create, copy, or hold any
+ * per-agent `.rvf` workspace today. So there is no full-copy for a COW branch
+ * to "replace" inline. This service therefore wires in as an **opt-in**: a
+ * swarm/agent that actually wants an isolated memory workspace passes a base
+ * memory path, and only then does a branch get forked. Default behavior is
+ * unchanged.
+ *
+ * ## Non-fatal + kill-switch (ADR-150)
+ *
+ *   - `agenticow` is an optional dependency — every method degrades to
+ *     `{ degraded: true }` when it is absent (never throws MODULE_NOT_FOUND).
+ *   - The `CLAUDE_FLOW_NO_COW_MEMORY=1` env var hard-disables branching so an
+ *     operator can kill the feature without a redeploy.
+ *   - agenticow is loaded lazily (dynamic import inside `loadAgenticow`), so
+ *     importing this module does NOT pull agenticow onto the CLI startup path.
+ *
+ * @module @claude-flow/cli/services/swarm-memory-branches
+ */
+/** Env var that hard-disables per-agent COW branching (operator kill switch). */
+export declare const COW_KILL_SWITCH_ENV = "CLAUDE_FLOW_NO_COW_MEMORY";
+/** True unless the operator set the kill switch. */
+export declare function cowMemoryEnabled(): boolean;
+/** Persisted mapping so promote/discard (a later, separate call) can find the branch. */
+export interface BranchRecord {
+    agentId: string;
+    basePath: string;
+    branchPath: string;
+    label: string;
+    createdAt: string;
+}
+export interface BranchResult {
+    success: boolean;
+    agentId: string;
+    basePath?: string;
+    branchPath?: string;
+    label?: string;
+    /** Set when the operation was a no-op because COW is unavailable/disabled. */
+    degraded?: true;
+    reason?: string;
+}
+export interface PromoteResult {
+    success: boolean;
+    agentId: string;
+    promoted: boolean;
+    branchPath?: string;
+    basePath?: string;
+    degraded?: true;
+    reason?: string;
+}
+export interface DiscardResult {
+    success: boolean;
+    agentId: string;
+    discarded: boolean;
+    branchPath?: string;
+    reason?: string;
+}
+/**
+ * Manages the branch→base COW lifecycle for a swarm's agents. One instance per
+ * project cwd; state is persisted to `.claude-flow/swarm/cow-branches.json` so
+ * a branch forked in `branchForAgent` survives to a later `promoteAgent` /
+ * `discardAgent` call in a different process.
+ */
+export declare class SwarmMemoryBranches {
+    private readonly registryPath;
+    /**
+     * @param registryPath Override the registry location (tests point this at a
+     *   temp dir). Defaults to `<cwd>/.claude-flow/swarm/cow-branches.json`.
+     */
+    constructor(registryPath?: string);
+    private loadRegistry;
+    private saveRegistry;
+    /** Look up the branch record for an agent, if one was forked. */
+    getBranch(agentId: string): BranchRecord | undefined;
+    /**
+     * Deterministic per-agent branch path: `<baseDir>/.swarm-cow/<base>.<agentId>.rvf`.
+     * Keeps branch files namespaced next to their base so cleanup is obvious.
+     */
+    private branchPathFor;
+    /**
+     * Fork a 162-byte COW branch off `base` for `agentId`. The agent then owns
+     * an isolated read/write view (parent ∪ its own edits). Idempotent: a second
+     * call for the same agent returns the existing branch record.
+     *
+     * @param base      Path to the shared base `.rvf` (absolute or cwd-relative).
+     * @param agentId   Agent that owns the branch (used as the COW label).
+     * @param opts.dimension  Required only when `base` does not yet exist.
+     * @param opts.nativeAnn  Fork with the native Rust ANN path (default true —
+     *   agent branches are meant to be queried).
+     */
+    branchForAgent(base: string, agentId: string, opts?: {
+        dimension?: number;
+        nativeAnn?: boolean;
+    }): Promise<BranchResult>;
+    /**
+     * Promote an agent's branch back into its base (merge its edits + tombstones
+     * atomically), then delete the branch file and drop it from the registry.
+     * Call on agent success. No-op (`promoted:false`) when the agent has no
+     * branch.
+     */
+    promoteAgent(agentId: string): Promise<PromoteResult>;
+    /**
+     * Discard an agent's branch — delete the branch file + lineage manifest and
+     * drop the registry entry, WITHOUT merging anything into base. Call on agent
+     * failure. No-op (`discarded:false`) when the agent has no branch. Never
+     * touches agenticow (pure filesystem), so it works even in the degraded path.
+     */
+    discardAgent(agentId: string): Promise<DiscardResult>;
+    private removeBranchFiles;
+    private forgetBranch;
+}
+//# sourceMappingURL=swarm-memory-branches.d.ts.map