claude-flow 3.28.0 → 3.30.0

package/v3/@claude-flow/guidance/dist/ledger.js

@@ -0,0 +1,375 @@
+/**
+ * Run Ledger + Evaluators
+ *
+ * Logs every run as an event with a minimum schema, then runs evaluators
+ * to assess compliance and quality.
+ *
+ * Objective evaluators:
+ * 1. Tests pass
+ * 2. Lint pass
+ * 3. Forbidden dependency scan
+ * 4. Forbidden command scan
+ * 5. Required sections present in plan
+ *
+ * Subjective evaluators:
+ * 1. Reviewer rating (pass/fail)
+ * 2. Architecture compliance (pass/fail)
+ *
+ * @module @claude-flow/guidance/ledger
+ */
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// Built-in Evaluators
+// ============================================================================
+/**
+ * Tests Pass evaluator - checks test results
+ */
+export class TestsPassEvaluator {
+    name = 'tests-pass';
+    type = 'objective';
+    async evaluate(event) {
+        if (!event.testResults.ran) {
+            return {
+                name: this.name,
+                passed: false,
+                details: 'Tests were not run during this task',
+                score: 0,
+            };
+        }
+        const passed = event.testResults.failed === 0;
+        const total = event.testResults.passed + event.testResults.failed + event.testResults.skipped;
+        return {
+            name: this.name,
+            passed,
+            details: passed
+                ? `All ${event.testResults.passed} tests passed (${event.testResults.skipped} skipped)`
+                : `${event.testResults.failed} of ${total} tests failed`,
+            score: total > 0 ? event.testResults.passed / total : 0,
+        };
+    }
+}
+/**
+ * Forbidden command scan evaluator
+ */
+export class ForbiddenCommandEvaluator {
+    name = 'forbidden-command-scan';
+    type = 'objective';
+    forbiddenPatterns;
+    constructor(forbiddenPatterns) {
+        this.forbiddenPatterns = forbiddenPatterns ?? [
+            /\brm\s+-rf\s+\//,
+            /\bgit\s+push\s+--force\s+origin\s+(?:main|master)\b/,
+            /\bcurl\s+.*\|\s*(?:sh|bash)\b/,
+            /\beval\s*\(/,
+            /\bexec\s*\(/,
+        ];
+    }
+    async evaluate(event) {
+        const violations = [];
+        for (const tool of event.toolsUsed) {
+            for (const pattern of this.forbiddenPatterns) {
+                if (pattern.test(tool)) {
+                    violations.push(`Forbidden command pattern: ${pattern.source} matched in "${tool}"`);
+                }
+            }
+        }
+        return {
+            name: this.name,
+            passed: violations.length === 0,
+            details: violations.length === 0
+                ? 'No forbidden commands detected'
+                : `Found ${violations.length} forbidden command(s): ${violations.join('; ')}`,
+            score: violations.length === 0 ? 1 : 0,
+        };
+    }
+}
+/**
+ * Forbidden dependency scan evaluator
+ */
+export class ForbiddenDependencyEvaluator {
+    name = 'forbidden-dependency-scan';
+    type = 'objective';
+    forbiddenPackages;
+    constructor(forbiddenPackages) {
+        this.forbiddenPackages = forbiddenPackages ?? [];
+    }
+    async evaluate(event) {
+        if (this.forbiddenPackages.length === 0) {
+            return { name: this.name, passed: true, details: 'No forbidden dependencies configured', score: 1 };
+        }
+        // Check if any forbidden packages were introduced in touched files
+        const packageFiles = event.filesTouched.filter(f => f.endsWith('package.json') || f.endsWith('package-lock.json'));
+        return {
+            name: this.name,
+            passed: true,
+            details: packageFiles.length > 0
+                ? `Package files modified: ${packageFiles.join(', ')} - manual review recommended`
+                : 'No package files modified',
+            score: 1,
+        };
+    }
+}
+/**
+ * Violation rate evaluator - checks violation count
+ */
+export class ViolationRateEvaluator {
+    name = 'violation-rate';
+    type = 'objective';
+    maxViolations;
+    constructor(maxViolations = 0) {
+        this.maxViolations = maxViolations;
+    }
+    async evaluate(event) {
+        const count = event.violations.length;
+        const passed = count <= this.maxViolations;
+        return {
+            name: this.name,
+            passed,
+            details: passed
+                ? `${count} violation(s) within threshold (max: ${this.maxViolations})`
+                : `${count} violation(s) exceeds threshold (max: ${this.maxViolations})`,
+            score: Math.max(0, 1 - count / Math.max(this.maxViolations + 1, 1)),
+        };
+    }
+}
+/**
+ * Diff quality evaluator - checks rework ratio
+ */
+export class DiffQualityEvaluator {
+    name = 'diff-quality';
+    type = 'objective';
+    maxReworkRatio;
+    constructor(maxReworkRatio = 0.3) {
+        this.maxReworkRatio = maxReworkRatio;
+    }
+    async evaluate(event) {
+        const totalLines = event.diffSummary.linesAdded + event.diffSummary.linesRemoved;
+        if (totalLines === 0) {
+            return { name: this.name, passed: true, details: 'No diff produced', score: 1 };
+        }
+        const reworkRatio = event.reworkLines / totalLines;
+        const passed = reworkRatio <= this.maxReworkRatio;
+        return {
+            name: this.name,
+            passed,
+            details: `Rework ratio: ${(reworkRatio * 100).toFixed(1)}% (${event.reworkLines}/${totalLines} lines). Threshold: ${(this.maxReworkRatio * 100).toFixed(0)}%`,
+            score: Math.max(0, 1 - reworkRatio),
+        };
+    }
+}
+// ============================================================================
+// Run Ledger
+// ============================================================================
+export class RunLedger {
+    events = [];
+    evaluators = [];
+    maxEvents;
+    /**
+     * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
+     *   When the limit is exceeded the oldest events are evicted.
+     */
+    constructor(maxEvents = 0) {
+        this.maxEvents = maxEvents;
+        // Register default evaluators
+        this.evaluators = [
+            new TestsPassEvaluator(),
+            new ForbiddenCommandEvaluator(),
+            new ForbiddenDependencyEvaluator(),
+            new ViolationRateEvaluator(),
+            new DiffQualityEvaluator(),
+        ];
+    }
+    /**
+     * Add a custom evaluator
+     */
+    addEvaluator(evaluator) {
+        this.evaluators.push(evaluator);
+    }
+    /**
+     * Remove an evaluator by name
+     */
+    removeEvaluator(name) {
+        this.evaluators = this.evaluators.filter(e => e.name !== name);
+    }
+    /**
+     * Log a run event
+     */
+    logEvent(event) {
+        const fullEvent = {
+            ...event,
+            eventId: randomUUID(),
+        };
+        this.events.push(fullEvent);
+        this.evictIfNeeded();
+        return fullEvent;
+    }
+    /**
+     * Create a new run event with defaults
+     */
+    createEvent(taskId, intent, guidanceHash) {
+        return {
+            eventId: randomUUID(),
+            taskId,
+            guidanceHash,
+            retrievedRuleIds: [],
+            toolsUsed: [],
+            filesTouched: [],
+            diffSummary: { linesAdded: 0, linesRemoved: 0, filesChanged: 0 },
+            testResults: { ran: false, passed: 0, failed: 0, skipped: 0 },
+            violations: [],
+            outcomeAccepted: null,
+            reworkLines: 0,
+            intent,
+            timestamp: Date.now(),
+            durationMs: 0,
+        };
+    }
+    /**
+     * Finalize and store an event
+     */
+    finalizeEvent(event) {
+        event.durationMs = Date.now() - event.timestamp;
+        this.events.push(event);
+        this.evictIfNeeded();
+        return event;
+    }
+    /**
+     * Evict oldest events when maxEvents is exceeded.
+     * Trims 10% in a batch to amortize the O(n) splice cost.
+     */
+    evictIfNeeded() {
+        if (this.maxEvents > 0 && this.events.length > this.maxEvents) {
+            const trimCount = Math.max(1, Math.floor(this.maxEvents * 0.1));
+            this.events.splice(0, trimCount);
+        }
+    }
+    /**
+     * Run all evaluators against an event
+     */
+    async evaluate(event) {
+        const results = [];
+        for (const evaluator of this.evaluators) {
+            const result = await evaluator.evaluate(event);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Get all events
+     */
+    getEvents() {
+        return [...this.events];
+    }
+    /**
+     * Get events by task ID
+     */
+    getEventsByTask(taskId) {
+        return this.events.filter(e => e.taskId === taskId);
+    }
+    /**
+     * Get events within a time range
+     */
+    getEventsInRange(startMs, endMs) {
+        return this.events.filter(e => e.timestamp >= startMs && e.timestamp <= endMs);
+    }
+    /**
+     * Get recent events
+     */
+    getRecentEvents(count) {
+        return this.events.slice(-count);
+    }
+    /**
+     * Compute optimization metrics from events
+     */
+    computeMetrics(events) {
+        const evts = events ?? this.events;
+        if (evts.length === 0) {
+            return {
+                violationRate: 0,
+                selfCorrectionRate: 0,
+                reworkLines: 0,
+                clarifyingQuestions: 0,
+                taskCount: 0,
+            };
+        }
+        // Violations per 10 tasks
+        const totalViolations = evts.reduce((sum, e) => sum + e.violations.length, 0);
+        const violationRate = evts.length > 0 ? (totalViolations / evts.length) * 10 : 0;
+        // Self-correction rate: violations that were auto-corrected
+        const totalCorrectable = evts.reduce((sum, e) => sum + e.violations.length, 0);
+        const totalCorrected = evts.reduce((sum, e) => sum + e.violations.filter(v => v.autoCorrected).length, 0);
+        const selfCorrectionRate = totalCorrectable > 0
+            ? totalCorrected / totalCorrectable
+            : 1;
+        // Average rework lines
+        const reworkLines = evts.reduce((sum, e) => sum + e.reworkLines, 0) / evts.length;
+        // Clarifying questions are tracked in metadata (placeholder for now)
+        const clarifyingQuestions = 0;
+        return {
+            violationRate,
+            selfCorrectionRate,
+            reworkLines,
+            clarifyingQuestions,
+            taskCount: evts.length,
+        };
+    }
+    /**
+     * Rank violations by frequency and cost (rework lines)
+     */
+    rankViolations(windowEvents) {
+        const evts = windowEvents ?? this.events;
+        const violationMap = new Map();
+        for (const event of evts) {
+            for (const violation of event.violations) {
+                const existing = violationMap.get(violation.ruleId) ?? { frequency: 0, totalRework: 0 };
+                existing.frequency++;
+                existing.totalRework += event.reworkLines;
+                violationMap.set(violation.ruleId, existing);
+            }
+        }
+        const rankings = [];
+        for (const [ruleId, stats] of violationMap) {
+            const cost = stats.totalRework / stats.frequency;
+            rankings.push({
+                ruleId,
+                frequency: stats.frequency,
+                cost,
+                score: stats.frequency * cost,
+            });
+        }
+        return rankings.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Get event count
+     */
+    get eventCount() {
+        return this.events.length;
+    }
+    /**
+     * Export events for persistence
+     */
+    exportEvents() {
+        return [...this.events];
+    }
+    /**
+     * Import events from persistence
+     */
+    importEvents(events) {
+        this.events.push(...events);
+    }
+    /**
+     * Clear all events
+     */
+    clear() {
+        this.events = [];
+    }
+}
+/**
+ * Create a run ledger instance
+ *
+ * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
+ */
+export function createLedger(maxEvents = 0) {
+    return new RunLedger(maxEvents);
+}
+//# sourceMappingURL=ledger.js.map

package/v3/@claude-flow/guidance/dist/manifest-validator.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Manifest Validator & Conformance Suite
+ *
+ * Validates AgentCellManifest documents against the Agentic Container spec,
+ * computes risk scores, selects execution lanes, and fails closed on any
+ * validation error. The ConformanceSuite runs golden traces through an
+ * evaluator to prove the platform behaves as specified.
+ *
+ * @module @claude-flow/guidance/manifest-validator
+ */
+/** Data sensitivity levels ordered by severity */
+declare const DATA_SENSITIVITY_LEVELS: readonly ["public", "internal", "confidential", "restricted"];
+type DataSensitivity = typeof DATA_SENSITIVITY_LEVELS[number];
+/** Write modes for memory policy */
+declare const WRITE_MODES: readonly ["append", "overwrite", "merge"];
+type WriteMode = typeof WRITE_MODES[number];
+/** Authority scopes for memory policy */
+declare const AUTHORITY_SCOPES: readonly ["self", "team", "tenant", "global"];
+type AuthorityScope = typeof AUTHORITY_SCOPES[number];
+/** Trace levels for observability */
+declare const TRACE_LEVELS: readonly ["none", "errors", "decisions", "full"];
+/** Execution lanes ordered by privilege (lowest to highest) */
+declare const LANES: readonly ["wasm", "sandboxed", "native"];
+type Lane = typeof LANES[number];
+/**
+ * The manifest describing an agent cell per the Agentic Container spec.
+ */
+export interface AgentCellManifest {
+    /** API version string (must be 'agentic_cells.v0_1') */
+    apiVersion: string;
+    /** Cell identity */
+    cell: {
+        name: string;
+        purpose: string;
+        ownerTenant: string;
+        codeRef: {
+            kind: string;
+            digest: string;
+            entry: string;
+        };
+    };
+    /** Lane execution policy */
+    lanePolicy: {
+        portabilityRequired: boolean;
+        needsNativeThreads: boolean;
+        preferredLane: Lane;
+        maxRiskScore: number;
+    };
+    /** Resource budgets */
+    budgets: {
+        maxWallClockSeconds: number;
+        maxToolCalls: number;
+        maxBytesEgress: number;
+        maxTokensInMtok: number;
+        maxTokensOutMtok: number;
+        maxMemoryWrites: number;
+    };
+    /** Data handling policy */
+    dataPolicy: {
+        dataSensitivity: DataSensitivity;
+        piiAllowed: boolean;
+        retentionDays: number;
+        exportControls: {
+            allowedRegions: string[];
+            blockedRegions: string[];
+        };
+    };
+    /** Tool usage policy */
+    toolPolicy: {
+        toolsAllowed: string[];
+        networkAllowlist: string[];
+        writeActionsRequireConfirmation: boolean;
+    };
+    /** Memory system policy */
+    memoryPolicy: {
+        namespace: string;
+        authorityScope: AuthorityScope;
+        writeMode: WriteMode;
+        requiresCoherenceGate: boolean;
+        requiresAntiHallucinationGate: boolean;
+    };
+    /** Observability configuration */
+    observability: {
+        traceLevel: typeof TRACE_LEVELS[number];
+        emitArtifacts: boolean;
+        artifactBucket: string;
+    };
+}
+/**
+ * A single validation error or warning.
+ */
+export interface ValidationError {
+    /** Error code (e.g., 'MISSING_FIELD', 'INVALID_DIGEST', 'BUDGET_EXCEED') */
+    code: string;
+    /** JSON path to the problematic field */
+    field: string;
+    /** Human-readable description */
+    message: string;
+    /** Severity level */
+    severity: 'error';
+}
+/**
+ * A single validation warning.
+ */
+export interface ValidationWarning {
+    /** Warning code */
+    code: string;
+    /** JSON path to the problematic field */
+    field: string;
+    /** Human-readable description */
+    message: string;
+    /** Severity level */
+    severity: 'warning';
+}
+/**
+ * Complete validation result for a manifest.
+ */
+export interface ValidationResult {
+    /** Whether the manifest passed all validation checks */
+    valid: boolean;
+    /** Validation errors (each causes rejection) */
+    errors: ValidationError[];
+    /** Validation warnings (informational, do not block admission) */
+    warnings: ValidationWarning[];
+    /** Admission decision: admit, reject, or review */
+    admissionDecision: 'admit' | 'reject' | 'review';
+    /** Selected execution lane (null if rejected) */
+    laneSelection: Lane | null;
+    /** Computed risk score (0-100) */
+    riskScore: number;
+}
+/**
+ * Validates AgentCellManifest documents against the Agentic Container spec.
+ *
+ * Fails closed: any validation error results in a 'reject' decision.
+ * Warnings alone do not block admission but may trigger a 'review' decision
+ * when the risk score is between thresholds.
+ */
+export declare class ManifestValidator {
+    /** Risk score threshold: below this, admit. Above reject threshold, reject. Between, review. */
+    private readonly admitThreshold;
+    private readonly rejectThreshold;
+    constructor(options?: {
+        admitThreshold?: number;
+        rejectThreshold?: number;
+    });
+    /**
+     * Validate a manifest, compute its risk score, select a lane, and decide admission.
+     *
+     * FAILS CLOSED: any validation error leads to reject.
+     */
+    validate(manifest: AgentCellManifest): ValidationResult;
+    /**
+     * Compute a risk score (0-100) from tool risk, data sensitivity, and privilege surface.
+     *
+     * Components:
+     * - tool_risk (0-40): based on tool types and network access
+     * - data_sensitivity (0-30): based on sensitivity level and PII
+     * - privilege_surface (0-30): based on memory scope, write mode, native threads
+     */
+    computeRiskScore(manifest: AgentCellManifest): number;
+    /**
+     * Select the execution lane based on risk score and manifest policy.
+     *
+     * Lane selection rules:
+     * - If portabilityRequired or risk <= 30: wasm
+     * - If needsNativeThreads and risk > 50: native
+     * - Otherwise: sandboxed
+     * - Always respect preferredLane if risk score allows it
+     * - Risk exceeding maxRiskScore forces the most restrictive lane
+     */
+    selectLane(manifest: AgentCellManifest, riskScore: number): Lane;
+    /**
+     * Validate budget values: no negatives, within sanity limits.
+     */
+    validateBudgets(budgets: AgentCellManifest['budgets']): ValidationError[];
+    /**
+     * Validate tool policy: network allowlist must not contain wildcards
+     * unless the cell explicitly has Bash (privileged).
+     */
+    validateToolPolicy(toolPolicy: AgentCellManifest['toolPolicy']): ValidationError[];
+    /**
+     * Validate data policy fields.
+     */
+    validateDataPolicy(dataPolicy: AgentCellManifest['dataPolicy']): ValidationError[];
+    private validateRequiredFields;
+    private validateApiVersion;
+    private validateDigest;
+    private validateWarnings;
+}
+/**
+ * A single event within a golden trace.
+ */
+export interface GoldenTraceEvent {
+    /** Sequence number within the trace */
+    seq: number;
+    /** Type of event (e.g., 'command', 'tool-use', 'memory-write', 'budget-check') */
+    eventType: string;
+    /** Event payload */
+    payload: Record<string, unknown>;
+    /** Expected outcome from the platform */
+    expectedOutcome: 'allow' | 'deny' | 'warn';
+}
+/**
+ * A complete golden trace including events and expected decisions.
+ */
+export interface GoldenTrace {
+    /** Unique trace identifier */
+    traceId: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what the trace verifies */
+    description: string;
+    /** Ordered sequence of events */
+    events: GoldenTraceEvent[];
+    /** Map from event seq (as string) to expected decision string */
+    expectedDecisions: Record<string, string>;
+    /** Map from memory key to expected parent chain for lineage verification */
+    expectedMemoryLineage: Record<string, string[]>;
+}
+/**
+ * Result of running the conformance suite.
+ */
+export interface ConformanceResult {
+    /** Whether all events matched their expected outcomes */
+    passed: boolean;
+    /** Total number of events evaluated */
+    totalEvents: number;
+    /** Number of events that matched expectations */
+    matchedEvents: number;
+    /** Details of any mismatches */
+    mismatches: Array<{
+        traceId: string;
+        seq: number;
+        expected: string;
+        actual: string;
+        details: unknown;
+    }>;
+}
+/**
+ * Runs golden traces through an evaluator and reports conformance.
+ *
+ * Each trace contains events with expected outcomes. The suite feeds every
+ * event to the evaluator and compares the actual decision to the expectation.
+ */
+export declare class ConformanceSuite {
+    private traces;
+    /**
+     * Add a golden trace to the suite.
+     */
+    addTrace(trace: GoldenTrace): void;
+    /**
+     * Run every event in every trace through the evaluator and compare
+     * actual decisions against expected outcomes.
+     */
+    run(evaluator: (event: GoldenTraceEvent) => {
+        decision: string;
+        details: unknown;
+    }): ConformanceResult;
+    /**
+     * Get all registered traces.
+     */
+    getTraces(): GoldenTrace[];
+    /**
+     * Create built-in default golden traces that verify core platform invariants:
+     *
+     * 1. Destructive command blocked
+     * 2. Secret detected and blocked
+     * 3. Budget exceeded and denied
+     * 4. Memory write without evidence blocked
+     * 5. Valid operation allowed
+     */
+    createDefaultTraces(): GoldenTrace[];
+}
+/**
+ * Create a new ManifestValidator instance.
+ */
+export declare function createManifestValidator(options?: {
+    admitThreshold?: number;
+    rejectThreshold?: number;
+}): ManifestValidator;
+/**
+ * Create a new ConformanceSuite instance, optionally pre-loaded with default traces.
+ */
+export declare function createConformanceSuite(options?: {
+    includeDefaults?: boolean;
+}): ConformanceSuite;
+export {};
+//# sourceMappingURL=manifest-validator.d.ts.map