claude-flow 3.20.0 → 3.21.1

package/v3/@claude-flow/cli/dist/src/services/checkpoint-gate.js

@@ -0,0 +1,223 @@
+/**
+ * CheckpointGate — agenticow-backed checkpoint/rollback gate for autopilot
+ * loops and long-horizon workflows (agenticow integration, step 3).
+ *
+ * ── The pattern ───────────────────────────────────────────────────────────
+ * Before a risky loop tick that mutates `.rvf` memory, take an O(1) agenticow
+ * checkpoint (162 bytes, fixed cost — see mcp-tools/agenticow-tools.ts). Run
+ * the tick. If it regresses — throws, or the caller's verdict says the outcome
+ * got worse (verifier fail / error / worse metric) — roll the memory back to
+ * the checkpoint. Rollback is O(edits-since-checkpoint), NOT an O(N) rebuild,
+ * and the earlier history stays intact via the `.agenticow.json` lineage
+ * manifest. On success the checkpoint is simply kept as the new good baseline.
+ *
+ * The three lifecycle verbs (checkpoint / rollback / promote) already exist in
+ * the `agenticow` package and are surfaced as MCP tools in
+ * `mcp-tools/agenticow-tools.ts`. This module is the *orchestration hook* that
+ * calls them from inside a loop — the MCP surface is for agents, this is for
+ * the in-process loop.
+ *
+ * ── Architectural constraint (ADR-150) ────────────────────────────────────
+ * `agenticow` lives in `optionalDependencies` and must NEVER be a hard runtime
+ * dependency. This gate degrades gracefully in three ways, each of which runs
+ * the tick UNGUARDED rather than failing:
+ *   1. package missing            → { degraded: true, reason: 'agenticow-not-found' }
+ *   2. kill-switch env set         → { degraded: true, reason: 'kill-switch' }
+ *   3. no memory path configured   → { degraded: true, reason: 'no-memory-path' }
+ * The package is lazy-loaded on the first guard() call, so importing this
+ * module has zero startup cost.
+ *
+ * The optional-dep loader + path/label/lineage helpers are the canonical ones
+ * from `mcp-tools/agenticow-loader.ts` — one implementation shared across every
+ * agenticow consumer (verbs, swarm branches, speculative, oracle, this gate).
+ *
+ * @module @claude-flow/cli/services/checkpoint-gate
+ */
+import { loadAgenticow, __resetAgenticowCache, resolveMemoryPath, manifestFor, validateLabel, openWithLineage, } from '../mcp-tools/agenticow-loader.js';
+/**
+ * Env var pointing at the `.rvf` memory file that a long-horizon loop mutates.
+ * When set, the autopilot loop opts in to checkpoint/rollback around each tick.
+ * When unset, the gate is a transparent pass-through.
+ */
+export const CHECKPOINT_MEM_ENV = 'CLAUDE_FLOW_AUTOPILOT_CHECKPOINT_MEM';
+/**
+ * Kill switch. When truthy (`1`/`true`/`yes`), the gate never touches agenticow
+ * and every guard() runs the tick unguarded. Lets an operator disable the
+ * feature without changing config or code.
+ */
+export const KILL_SWITCH_ENV = 'CLAUDE_FLOW_AGENTICOW_DISABLE';
+function defaultIsRegression(result) {
+    if (!result || typeof result !== 'object')
+        return false;
+    const r = result;
+    return r.success === false || r.ok === false || r.regressed === true;
+}
+// ── The gate ────────────────────────────────────────────────────────────────
+export class CheckpointGate {
+    /** True when the kill-switch env is set to a truthy value. */
+    static isKillSwitchSet() {
+        const v = (process.env[KILL_SWITCH_ENV] || '').trim().toLowerCase();
+        return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+    }
+    /** The configured loop memory path, or undefined when the feature is off. */
+    static configuredMemPath() {
+        const p = (process.env[CHECKPOINT_MEM_ENV] || '').trim();
+        return p || undefined;
+    }
+    /**
+     * Lazy-load agenticow. Returns null when the package is absent (optional dep)
+     * or the kill switch is set. Any *other* import error is re-thrown — a broken
+     * install should be loud, a missing optional dep should be silent.
+     */
+    async load() {
+        if (CheckpointGate.isKillSwitchSet())
+            return null;
+        // Delegates to the canonical loader (#22) — one cache, one degradation
+        // policy shared across every agenticow consumer.
+        return loadAgenticow();
+    }
+    /** True when agenticow can be engaged (present + not killed). */
+    async available() {
+        return (await this.load()) !== null;
+    }
+    /**
+     * Take a checkpoint on the given `.rvf` memory file. Non-throwing except for
+     * validation errors (path traversal, bad label) — those are surfaced so a
+     * misconfiguration is caught early.
+     */
+    async checkpoint(memPath, label) {
+        const api = await this.load();
+        if (!api)
+            return { ok: false, degraded: true, reason: CheckpointGate.isKillSwitchSet() ? 'kill-switch' : 'agenticow-not-found' };
+        const path = resolveMemoryPath(String(memPath));
+        const lbl = validateLabel(String(label));
+        const mem = await openWithLineage(api, path);
+        try {
+            const cp = await mem.checkpoint(lbl);
+            await mem.save?.(manifestFor(path));
+            return { ok: true, degraded: false, checkpoint: cp };
+        }
+        finally {
+            await mem.close?.();
+        }
+    }
+    /**
+     * Roll the given `.rvf` memory file back to a checkpoint. Discards edits made
+     * since (O(edits-since-checkpoint)). Omit `checkpointId` to target the most
+     * recent checkpoint.
+     */
+    async rollback(memPath, checkpointId) {
+        const api = await this.load();
+        if (!api)
+            return { ok: false, degraded: true, reason: CheckpointGate.isKillSwitchSet() ? 'kill-switch' : 'agenticow-not-found' };
+        const path = resolveMemoryPath(String(memPath));
+        const mem = await openWithLineage(api, path);
+        try {
+            const r = checkpointId ? await mem.rollback(checkpointId) : await mem.rollback();
+            await mem.save?.(manifestFor(path));
+            return { ok: true, degraded: false, result: r };
+        }
+        finally {
+            await mem.close?.();
+        }
+    }
+    /**
+     * Guard a risky loop tick with a checkpoint/rollback bracket.
+     *
+     *   const outcome = await gate.guard(memPath, 'iter-7', async () => runTick());
+     *
+     * Behaviour:
+     *   - No memPath / kill-switch / agenticow-absent → run fn unguarded, degraded:true.
+     *   - Checkpoint fails to engage (degraded) → run fn unguarded, degraded:true.
+     *   - fn throws → roll back to checkpoint, then re-throw (unless rethrow:false).
+     *   - fn returns a regression verdict → roll back, return result with rolledBack:true.
+     *   - fn succeeds → keep the checkpoint, return result with rolledBack:false.
+     *
+     * The gate is non-fatal: an internal agenticow failure never masks fn()'s own
+     * result — if checkpointing throws, fn still runs unguarded.
+     */
+    async guard(memPath, label, fn, opts = {}) {
+        const rethrow = opts.rethrow !== false;
+        const isRegression = opts.isRegression ?? defaultIsRegression;
+        // Fast paths: feature off → transparent pass-through.
+        if (!memPath) {
+            const result = await fn();
+            return { result, checkpointed: false, rolledBack: false, degraded: true, reason: 'no-memory-path' };
+        }
+        if (CheckpointGate.isKillSwitchSet()) {
+            const result = await fn();
+            return { result, checkpointed: false, rolledBack: false, degraded: true, reason: 'kill-switch' };
+        }
+        // Try to checkpoint. Any failure here degrades to unguarded — the loop must
+        // never break because memory branching is unavailable.
+        let checkpointed = false;
+        try {
+            const cp = await this.checkpoint(memPath, label);
+            if (!cp.ok) {
+                const result = await fn();
+                return { result, checkpointed: false, rolledBack: false, degraded: true, reason: cp.reason };
+            }
+            checkpointed = true;
+        }
+        catch (err) {
+            const result = await fn();
+            return {
+                result,
+                checkpointed: false,
+                rolledBack: false,
+                degraded: true,
+                reason: `checkpoint-error: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        // Run the tick under the checkpoint.
+        let result;
+        try {
+            result = await fn();
+        }
+        catch (err) {
+            const rb = await this.safeRollback(memPath, opts.checkpointId);
+            if (rethrow)
+                throw err;
+            return {
+                result: undefined,
+                checkpointed,
+                rolledBack: rb,
+                degraded: false,
+                reason: 'tick-threw',
+                checkpointLabel: label,
+                error: err,
+            };
+        }
+        // Verdict: regression → roll back, keep the returned result for the caller.
+        if (isRegression(result)) {
+            const rb = await this.safeRollback(memPath, opts.checkpointId);
+            return { result, checkpointed, rolledBack: rb, degraded: false, reason: 'regression-verdict', checkpointLabel: label };
+        }
+        // Success → keep the checkpoint as the new baseline.
+        return { result, checkpointed, rolledBack: false, degraded: false, checkpointLabel: label };
+    }
+    /** Roll back without throwing — used on the failure path so a rollback error
+     *  never masks the original tick failure. */
+    async safeRollback(memPath, checkpointId) {
+        try {
+            const r = await this.rollback(memPath, checkpointId);
+            return r.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** Shared process-wide gate instance. */
+let _shared = null;
+export function getCheckpointGate() {
+    if (!_shared)
+        _shared = new CheckpointGate();
+    return _shared;
+}
+/** Reset the lazy-load cache — test-only. */
+export function __resetCheckpointGateForTests() {
+    __resetAgenticowCache();
+    _shared = null;
+}
+//# sourceMappingURL=checkpoint-gate.js.map

package/v3/@claude-flow/cli/dist/src/services/distill-oracle.d.ts

@@ -0,0 +1,190 @@
+/**
+ * distill-oracle.ts — Tiered `resolved` oracle for distill / weight-EFT SFT data.
+ *
+ * THE PROBLEM: weight-EFT's SFT data wants a gold `resolved: boolean` per
+ * trajectory. Ruflo has no SWE-bench oracle, so today `resolved` is
+ * structural-confidence — a proxy that risks distilling plausible-but-wrong
+ * completions. This module replaces that single proxy with a TIERED labeler,
+ * where every label carries HONEST PROVENANCE (ADR-169 reporting integrity — a
+ * proxy is never presented as ground truth).
+ *
+ * ── TIERS (tried in order, per trajectory) ──────────────────────────────────
+ *   TIER 1 — MECHANICAL ORACLE  (provenance `oracle:test-exec`, real ground truth)
+ *     When a trajectory carries a test spec (SWE-bench FAIL_TO_PASS shape) or
+ *     maps to a metaharness/darwin bench-suite case, EXECUTE the real eval and
+ *     set resolved = tests-pass. This needs Docker/compute, so it runs on a
+ *     REMOTE host over SSH (host parameterized via `remote` / env
+ *     RUFLO_DISTILL_REMOTE — never hard-coded). DRY-RUN by default: it prints
+ *     the ssh/darwin-bench/eval commands + a preflight plan and does NOT touch
+ *     the network; only `execute: true` runs the real eval (with a wrapped,
+ *     non-fatal preflight probe first).
+ *
+ *   TIER 2 — FABLE JUDGE  (provenance `judge:fable`, smarter proxy)
+ *     For trajectories with no mechanical spec, judge via the cost-disciplined
+ *     headless Fable harness (fable-harness.ts). Opt-in and OFF by default;
+ *     spends nothing unless `fableJudge: true` AND a `maxBudgetUsd` cap is set.
+ *
+ *   TIER 3 — STRUCTURAL PROXY  (provenance `proxy:structural`, weakest)
+ *     The existing output-verifier structural confidence. Always available,
+ *     $0, no external calls. Explicitly the weakest signal, clearly labeled.
+ *
+ * DEFAULT (no opts): dry-run oracle preflight + structural-proxy fallback.
+ * ZERO spend, no SSH exec, no Fable call. Everything degrades gracefully
+ * (ADR-150) — a missing remote or a failed probe is reported, never fatal.
+ *
+ * @module services/distill-oracle
+ */
+import { type VerifyTaskKind } from '../ruvector/output-verifier.js';
+import { FableHarness, type ReflectItem, type ReflectResult } from './fable-harness.js';
+export type ResolvedProvenance = 'oracle:test-exec' | 'judge:fable' | 'proxy:structural';
+/** SWE-bench-shaped / bench-suite-mapped test spec that Tier 1 can execute. */
+export interface TestSpec {
+    /** SWE-bench FAIL_TO_PASS tests — must go red→green for `resolved`. */
+    failToPass?: string[];
+    /** SWE-bench PASS_TO_PASS tests — must stay green (no regressions). */
+    passToPass?: string[];
+    /** Repo identifier (for the remote checkout). */
+    repo?: string;
+    /** Base commit the patch applies onto. */
+    baseCommit?: string;
+    /** Candidate patch/diff to apply before evaluating. */
+    patch?: string;
+    /** An explicit eval command that returns 0 iff the task is resolved. */
+    evalCommand?: string;
+    /** metaharness/darwin bench-suite this case belongs to. */
+    benchSuite?: string;
+    /** Case id within the bench suite. */
+    benchCase?: string;
+    /** Working directory on the remote host (default derived). */
+    workdir?: string;
+}
+/**
+ * Minimal trajectory contract. Extra fields are preserved verbatim on output
+ * (the labeler spreads `...trajectory`). `task`/`output` feed the fable judge
+ * and structural proxy; `testSpec` (when present) unlocks Tier 1.
+ */
+export interface Trajectory {
+    id: string;
+    task?: string;
+    output?: string;
+    testSpec?: TestSpec;
+    /** Hint for the structural verifier's task-kind detection. */
+    taskKind?: VerifyTaskKind;
+    [key: string]: unknown;
+}
+export interface LabelOptions {
+    /** SSH host for Tier-1 execution. Falls back to env RUFLO_DISTILL_REMOTE. Never hard-coded. */
+    remote?: string;
+    /** Run the REAL Tier-1 eval over SSH. Default false → dry-run preflight only. */
+    execute?: boolean;
+    /** Enable the Tier-2 Fable judge. Default false. Requires maxBudgetUsd to spend. */
+    fableJudge?: boolean;
+    /** Hard budget cap (USD) for the Fable tier. No cap ⇒ no Fable spend. */
+    maxBudgetUsd?: number;
+    /** Items per Fable call (default 20 — see FABLE_COST_MODEL). */
+    fableBatchSize?: number;
+    /** Structural verifier: min score to call a trajectory resolved (default: strict — confident only). */
+    minStructuralConfidence?: number;
+    /** Injected Tier-1 runner (tests). Defaults to a real SSH command runner. */
+    runner?: OracleRunner;
+    /** Injected Tier-2 harness (tests). Defaults to a real FableHarness. */
+    harness?: FableHarness;
+}
+/** A trajectory with its resolved label + honest provenance. */
+export type LabeledTrajectory<T extends Trajectory = Trajectory> = T & {
+    resolved: boolean;
+    resolvedBy: ResolvedProvenance;
+    resolvedConfidence?: number;
+    resolvedReason?: string;
+    /** Present for trajectories that had a mechanical spec — the Tier-1 plan/outcome. */
+    oraclePreflight?: OraclePreflight;
+};
+export type OracleKind = 'ssh-darwin-bench' | 'ssh-swebench-eval' | 'ssh-eval' | 'local-eval';
+/** The concrete command plan for executing a trajectory's eval on the remote. */
+export interface OraclePlan {
+    kind: OracleKind;
+    /** Resolved remote host, or null when none is configured. */
+    remote: string | null;
+    /** Preflight probe commands (reachability, docker/darwin presence). */
+    probeCommands: string[];
+    /** The eval commands whose success ⇒ resolved. */
+    evalCommands: string[];
+    /** Human note describing how the resolved boolean is derived. */
+    parseHint: string;
+}
+/** Preflight/dry-run record attached to labeled trajectories that had a spec. */
+export interface OraclePreflight {
+    /** True when nothing was executed (default path). */
+    dryRun: boolean;
+    plan: OraclePlan;
+    /** Probe outcome when executed (execute:true); absent in dry-run. */
+    probe?: {
+        ok: boolean;
+        reason: string;
+    };
+    /** Why Tier 1 did not produce the final label (e.g. dry-run, no remote, probe failed). */
+    fellThroughBecause?: string;
+}
+/** Outcome of a real Tier-1 eval. */
+export interface OracleOutcome {
+    resolved: boolean;
+    reason: string;
+}
+/** Result of a shelled command. */
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}
+/** Injectable command executor (tests mock this instead of touching SSH). */
+export type CommandExec = (cmd: string, args: string[], opts: {
+    timeoutMs: number;
+}) => Promise<CommandResult>;
+/** Tier-1 runner contract: probe the remote, then run the eval. */
+export interface OracleRunner {
+    preflight(plan: OraclePlan): Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
+    runEval(plan: OraclePlan, spec: TestSpec): Promise<OracleOutcome>;
+}
+/**
+ * Label each trajectory with `resolved` + honest provenance, trying the tiers
+ * in order per trajectory. See the module header for tier semantics and the
+ * zero-spend default guarantee.
+ */
+export declare function labelResolved<T extends Trajectory>(trajectories: T[], opts?: LabelOptions): Promise<Array<LabeledTrajectory<T>>>;
+/**
+ * Reflective failure analysis (GEPA/evolve mutation input). Thin, cost-
+ * disciplined pass-through to the Fable harness. Opt-in: returns [] unless a
+ * harness with a budget cap is provided/configured.
+ */
+export declare function reflectFailures(items: ReflectItem[], opts?: {
+    maxBudgetUsd?: number;
+    fableBatchSize?: number;
+    harness?: FableHarness;
+}): Promise<ReflectResult[]>;
+/** A trajectory can be mechanically evaluated iff it carries an actionable spec. */
+export declare function hasMechanicalSpec(t: Trajectory): boolean;
+/** Resolve the remote host from opts → env, never a hard-coded host. */
+export declare function resolveRemote(remote?: string): string | null;
+/**
+ * Build the concrete command plan for a spec. Pure — constructs command strings
+ * only; executes nothing. `remote` is always substituted from the parameter,
+ * never hard-coded.
+ */
+export declare function buildOraclePlan(spec: TestSpec, remote: string | null): OraclePlan;
+/**
+ * Default command executor: shells out, piping any heredoc/stdin via argv only
+ * (commands are self-contained strings run through `sh -c`). Never invoked on
+ * the default (dry-run) path.
+ */
+export declare const defaultCommandExec: CommandExec;
+/**
+ * Build a real SSH-backed oracle runner. `exec` is injectable so tests assert
+ * command construction without ever touching a network. Each plan command is
+ * run via `sh -c <command-string>` so the fully-rendered ssh line executes as-is.
+ */
+export declare function createSshOracleRunner(exec?: CommandExec, timeoutMs?: number): OracleRunner;
+export default labelResolved;
+//# sourceMappingURL=distill-oracle.d.ts.map