@claude-flow/cli 3.32.2 → 3.32.3

package/dist/src/services/checkpoint-gate.d.ts

@@ -1,140 +0,0 @@
-/**
- * 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
- */
-/**
- * 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 declare 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 declare const KILL_SWITCH_ENV = "CLAUDE_FLOW_AGENTICOW_DISABLE";
-/** Outcome of a guarded tick. `result` is undefined only when the tick threw
- *  AND `rethrow` was disabled. */
-export interface CheckpointGuardResult<T> {
-    /** The value fn() returned (undefined if it threw with rethrow:false). */
-    result: T | undefined;
-    /** True when a checkpoint was actually taken before running fn. */
-    checkpointed: boolean;
-    /** True when memory was rolled back to the checkpoint (throw or regression). */
-    rolledBack: boolean;
-    /** True when the gate could not engage agenticow and ran fn unguarded. */
-    degraded: boolean;
-    /** Machine-readable reason for degraded / rollback. */
-    reason?: string;
-    /** The checkpoint label, when one was taken. */
-    checkpointLabel?: string;
-    /** The error fn() threw, when rethrow was disabled. */
-    error?: unknown;
-}
-export interface GuardOptions<T> {
-    /**
-     * Verdict function: return true when `result` represents a regression that
-     * should trigger a rollback. Defaults to treating `{success:false}` /
-     * `{ok:false}` / `{regressed:true}` as regressions.
-     */
-    isRegression?: (result: T) => boolean;
-    /**
-     * When the tick throws: roll back, then re-throw the original error
-     * (default true). Set false to swallow the error and return it on the
-     * result object instead — useful when the loop must never crash.
-     */
-    rethrow?: boolean;
-    /** Optional checkpoint id to roll back to (defaults to most recent). */
-    checkpointId?: string;
-}
-export declare class CheckpointGate {
-    /** True when the kill-switch env is set to a truthy value. */
-    static isKillSwitchSet(): boolean;
-    /** The configured loop memory path, or undefined when the feature is off. */
-    static configuredMemPath(): string | 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.
-     */
-    private load;
-    /** True when agenticow can be engaged (present + not killed). */
-    available(): Promise<boolean>;
-    /**
-     * 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.
-     */
-    checkpoint(memPath: string, label: string): Promise<{
-        ok: boolean;
-        degraded: boolean;
-        reason?: string;
-        checkpoint?: unknown;
-    }>;
-    /**
-     * 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.
-     */
-    rollback(memPath: string, checkpointId?: string): Promise<{
-        ok: boolean;
-        degraded: boolean;
-        reason?: string;
-        result?: unknown;
-    }>;
-    /**
-     * 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.
-     */
-    guard<T>(memPath: string | undefined, label: string, fn: () => Promise<T>, opts?: GuardOptions<T>): Promise<CheckpointGuardResult<T>>;
-    /** Roll back without throwing — used on the failure path so a rollback error
-     *  never masks the original tick failure. */
-    private safeRollback;
-}
-export declare function getCheckpointGate(): CheckpointGate;
-/** Reset the lazy-load cache — test-only. */
-export declare function __resetCheckpointGateForTests(): void;
-//# sourceMappingURL=checkpoint-gate.d.ts.map

package/dist/src/services/checkpoint-gate.js

@@ -1,223 +0,0 @@
-/**
- * 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/dist/src/services/claim-service.d.ts

@@ -1,204 +0,0 @@
-/**
- * V3 Collaborative Issue Claims Service
- *
- * Implements ADR-016: Collaborative Issue Claims for Human-Agent Workflows
- *
- * Features:
- * - Issue claiming/releasing for humans and agents
- * - Handoff mechanisms between humans and agents
- * - Work stealing for idle agents
- * - Load balancing across swarm
- * - GitHub integration
- *
- * @see /v3/implementation/adrs/ADR-016-collaborative-issue-claims.md
- */
-import { EventEmitter } from 'events';
-export type Claimant = {
-    type: 'human';
-    userId: string;
-    name: string;
-} | {
-    type: 'agent';
-    agentId: string;
-    agentType: string;
-};
-export type ClaimStatus = 'active' | 'paused' | 'handoff-pending' | 'review-requested' | 'blocked' | 'stealable' | 'completed';
-export type StealReason = 'overloaded' | 'stale' | 'blocked-timeout' | 'voluntary';
-export interface IssueClaim {
-    issueId: string;
-    claimant: Claimant;
-    claimedAt: Date;
-    status: ClaimStatus;
-    statusChangedAt: Date;
-    expiresAt?: Date;
-    handoffTo?: Claimant;
-    handoffReason?: string;
-    blockReason?: string;
-    progress: number;
-    context?: string;
-}
-export interface StealableInfo {
-    reason: StealReason;
-    stealableAt: Date;
-    preferredTypes?: string[];
-    progress: number;
-    context?: string;
-}
-export interface ClaimResult {
-    success: boolean;
-    claim?: IssueClaim;
-    error?: string;
-}
-export interface StealResult {
-    success: boolean;
-    claim?: IssueClaim;
-    previousOwner?: Claimant;
-    context?: StealableInfo;
-    error?: string;
-}
-export interface AgentLoadInfo {
-    agentId: string;
-    agentType: string;
-    claimCount: number;
-    maxClaims: number;
-    utilization: number;
-    claims: IssueClaim[];
-    avgCompletionTime: number;
-    currentBlockedCount: number;
-}
-export interface RebalanceResult {
-    moved: Array<{
-        issueId: string;
-        from: Claimant;
-        to: Claimant;
-    }>;
-    suggested: Array<{
-        issueId: string;
-        currentOwner: Claimant;
-        suggestedOwner: Claimant;
-        reason: string;
-    }>;
-}
-export interface WorkStealingConfig {
-    staleThresholdMinutes: number;
-    blockedThresholdMinutes: number;
-    overloadThreshold: number;
-    gracePeriodMinutes: number;
-    minProgressToProtect: number;
-    contestWindowMinutes: number;
-    requireSameType: boolean;
-    allowCrossTypeSteal: string[][];
-}
-export interface IssueFilters {
-    status?: ClaimStatus[];
-    labels?: string[];
-    agentTypes?: string[];
-    priority?: string[];
-}
-export interface GitHubIssue {
-    number: number;
-    title: string;
-    body: string;
-    state: 'open' | 'closed';
-    labels: string[];
-    assignees: string[];
-    url: string;
-    createdAt: Date;
-    updatedAt: Date;
-}
-export interface GitHubSyncConfig {
-    enabled: boolean;
-    repo?: string;
-    syncLabels: boolean;
-    claimLabel: string;
-    autoAssign: boolean;
-    commentOnClaim: boolean;
-    commentOnRelease: boolean;
-}
-export interface GitHubSyncResult {
-    success: boolean;
-    synced: number;
-    errors: string[];
-    issues?: GitHubIssue[];
-}
-export type ClaimEventType = 'issue:claimed' | 'issue:released' | 'issue:handoff:requested' | 'issue:handoff:accepted' | 'issue:handoff:rejected' | 'issue:status:changed' | 'issue:review:requested' | 'issue:expired' | 'issue:stealable' | 'issue:stolen' | 'issue:steal:contested' | 'issue:steal:resolved' | 'swarm:rebalanced' | 'agent:overloaded' | 'agent:underloaded';
-export interface ClaimEvent {
-    type: ClaimEventType;
-    timestamp: Date;
-    issueId?: string;
-    claimant?: Claimant;
-    previousClaimant?: Claimant;
-    data?: Record<string, unknown>;
-}
-export declare class ClaimService extends EventEmitter {
-    private claims;
-    private stealableInfo;
-    private storagePath;
-    private config;
-    private eventLog;
-    constructor(projectRoot: string, config?: Partial<WorkStealingConfig>);
-    initialize(): Promise<void>;
-    private loadClaims;
-    private saveClaims;
-    claim(issueId: string, claimant: Claimant): Promise<ClaimResult>;
-    release(issueId: string, claimant: Claimant): Promise<void>;
-    requestHandoff(issueId: string, from: Claimant, to: Claimant, reason: string): Promise<void>;
-    acceptHandoff(issueId: string, claimant: Claimant): Promise<void>;
-    rejectHandoff(issueId: string, claimant: Claimant, reason: string): Promise<void>;
-    updateStatus(issueId: string, status: ClaimStatus, note?: string): Promise<void>;
-    updateProgress(issueId: string, progress: number): Promise<void>;
-    requestReview(issueId: string, reviewers: Claimant[]): Promise<void>;
-    markStealable(issueId: string, info: StealableInfo): Promise<void>;
-    steal(issueId: string, stealer: Claimant): Promise<StealResult>;
-    getStealable(agentType?: string): Promise<IssueClaim[]>;
-    contestSteal(issueId: string, originalClaimant: Claimant, reason: string): Promise<void>;
-    getAgentLoad(agentId: string): Promise<AgentLoadInfo>;
-    rebalance(swarmId: string): Promise<RebalanceResult>;
-    getClaimedBy(claimant: Claimant): Promise<IssueClaim[]>;
-    getAvailableIssues(_filters?: IssueFilters): Promise<string[]>;
-    getIssueStatus(issueId: string): Promise<IssueClaim | null>;
-    getAllClaims(): Promise<IssueClaim[]>;
-    getByStatus(status: ClaimStatus): Promise<IssueClaim[]>;
-    expireStale(maxAgeMinutes?: number): Promise<IssueClaim[]>;
-    private formatClaimant;
-    private isSameClaimant;
-    private emitEvent;
-    getEventLog(limit?: number): ClaimEvent[];
-}
-export declare class GitHubSync {
-    private config;
-    private claimService;
-    constructor(claimService: ClaimService, config?: Partial<GitHubSyncConfig>);
-    /**
-     * Check if GitHub CLI is available
-     */
-    isGhAvailable(): boolean;
-    /**
-     * Get the current repository from git remote
-     */
-    getRepo(): string | null;
-    /**
-     * Sync issues from GitHub
-     */
-    syncIssues(state?: 'open' | 'closed' | 'all'): Promise<GitHubSyncResult>;
-    /**
-     * Sync a local claim to GitHub (add label/assignee/comment)
-     */
-    claimOnGitHub(issueNumber: number, claimant: Claimant): Promise<GitHubSyncResult>;
-    /**
-     * Release claim on GitHub (remove label/assignee/comment)
-     */
-    releaseOnGitHub(issueNumber: number, claimant: Claimant): Promise<GitHubSyncResult>;
-    /**
-     * Bulk sync all local claims to GitHub
-     */
-    syncAllClaimsToGitHub(): Promise<GitHubSyncResult>;
-    /**
-     * Get GitHub issues that are claimed locally
-     */
-    getClaimedGitHubIssues(): Promise<GitHubIssue[]>;
-}
-export declare function createClaimService(projectRoot: string, config?: Partial<WorkStealingConfig>): ClaimService;
-export declare function createGitHubSync(claimService: ClaimService, config?: Partial<GitHubSyncConfig>): GitHubSync;
-export default ClaimService;
-//# sourceMappingURL=claim-service.d.ts.map