claude-flow 3.28.0 → 3.29.0

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

@@ -0,0 +1,452 @@
+/**
+ * Deterministic Tool Gateway
+ *
+ * Extends EnforcementGates with idempotency, schema validation,
+ * and budget metering. Every tool call passes through a deterministic
+ * pipeline: idempotency check -> schema validation -> budget check ->
+ * enforcement gates -> allow/deny.
+ *
+ * @module @claude-flow/guidance/gateway
+ */
+import { createHash } from 'node:crypto';
+import { EnforcementGates } from './gates.js';
+// ============================================================================
+// Default Budget
+// ============================================================================
+const DEFAULT_BUDGET = {
+    tokenBudget: { used: 0, limit: Infinity },
+    toolCallBudget: { used: 0, limit: Infinity },
+    storageBudget: { usedBytes: 0, limitBytes: Infinity },
+    timeBudget: { usedMs: 0, limitMs: Infinity },
+    costBudget: { usedUsd: 0, limitUsd: Infinity },
+};
+// ============================================================================
+// Deterministic Tool Gateway
+// ============================================================================
+export class DeterministicToolGateway {
+    gates;
+    schemas;
+    budget;
+    idempotencyTtlMs;
+    maxCacheSize;
+    requireEvidence;
+    idempotencyCache = new Map();
+    lastCleanupTime = 0;
+    static CLEANUP_INTERVAL_MS = 30_000; // batch cleanup every 30s
+    constructor(config = {}) {
+        this.gates = new EnforcementGates(config.gateConfig);
+        // Index schemas by tool name
+        this.schemas = new Map();
+        if (config.schemas) {
+            for (const schema of config.schemas) {
+                this.schemas.set(schema.toolName, schema);
+            }
+        }
+        // Merge partial budget with defaults
+        this.budget = this.mergeBudget(config.budget);
+        this.idempotencyTtlMs = config.idempotencyTtlMs ?? 300_000; // 5 minutes default
+        this.maxCacheSize = config.maxCacheSize ?? 10_000;
+        this.requireEvidence = config.requireEvidence ?? false;
+    }
+    // =========================================================================
+    // Public API
+    // =========================================================================
+    /**
+     * Evaluate whether a tool call should be allowed.
+     *
+     * Pipeline:
+     * 1. Check idempotency cache
+     * 2. Validate params against schema
+     * 3. Check budget
+     * 4. Run EnforcementGates checks
+     * 5. Return decision with remaining budget
+     */
+    evaluate(toolName, params, context) {
+        const evidence = {};
+        // Step 1: Idempotency check (batch cleanup on interval, not every call)
+        this.maybeCleanExpiredIdempotency();
+        const idempotencyKey = this.getIdempotencyKey(toolName, params);
+        const cached = this.idempotencyCache.get(idempotencyKey);
+        if (cached) {
+            return {
+                allowed: true,
+                reason: 'Idempotency cache hit; returning cached result',
+                gate: 'idempotency',
+                evidence: { idempotencyKey, cachedAt: cached.timestamp },
+                idempotencyHit: true,
+                cachedResult: cached.result,
+                budgetRemaining: this.cloneBudget(),
+            };
+        }
+        evidence.idempotencyKey = idempotencyKey;
+        evidence.idempotencyHit = false;
+        // Step 2: Schema validation
+        const schemaResult = this.validateSchema(toolName, params);
+        evidence.schemaValidation = schemaResult;
+        if (!schemaResult.valid) {
+            return {
+                allowed: false,
+                reason: `Schema validation failed: ${schemaResult.errors.join('; ')}`,
+                gate: 'schema-validation',
+                evidence,
+                idempotencyHit: false,
+            };
+        }
+        // Step 3: Budget check
+        const budgetStatus = this.checkBudget();
+        evidence.budgetStatus = budgetStatus;
+        if (!budgetStatus.withinBudget) {
+            const exceeded = this.findExceededBudgets();
+            return {
+                allowed: false,
+                reason: `Budget exceeded: ${exceeded.join(', ')}`,
+                gate: 'budget',
+                evidence,
+                idempotencyHit: false,
+                budgetRemaining: this.cloneBudget(),
+            };
+        }
+        // Step 4: EnforcementGates checks
+        const gateResults = this.gates.evaluateToolUse(toolName, params);
+        evidence.gateResults = gateResults;
+        if (gateResults.length > 0) {
+            const aggregated = this.gates.aggregateDecision(gateResults);
+            if (aggregated === 'block') {
+                const blockResult = gateResults.find(r => r.decision === 'block');
+                return {
+                    allowed: false,
+                    reason: blockResult.reason,
+                    gate: `enforcement:${blockResult.gateName}`,
+                    evidence,
+                    idempotencyHit: false,
+                    budgetRemaining: this.cloneBudget(),
+                };
+            }
+            if (aggregated === 'require-confirmation') {
+                const confirmResult = gateResults.find(r => r.decision === 'require-confirmation');
+                return {
+                    allowed: false,
+                    reason: confirmResult.reason,
+                    gate: `enforcement:${confirmResult.gateName}`,
+                    evidence,
+                    idempotencyHit: false,
+                    budgetRemaining: this.cloneBudget(),
+                };
+            }
+            // 'warn' still allows, but note it in evidence
+            evidence.warnings = gateResults
+                .filter(r => r.decision === 'warn')
+                .map(r => r.reason);
+        }
+        // Also run command-level checks if context provides a command string
+        if (context?.command && typeof context.command === 'string') {
+            const commandResults = this.gates.evaluateCommand(context.command);
+            evidence.commandGateResults = commandResults;
+            if (commandResults.length > 0) {
+                const aggregated = this.gates.aggregateDecision(commandResults);
+                if (aggregated === 'block' || aggregated === 'require-confirmation') {
+                    const worst = commandResults.find(r => r.decision === aggregated);
+                    return {
+                        allowed: false,
+                        reason: worst.reason,
+                        gate: `enforcement:${worst.gateName}`,
+                        evidence,
+                        idempotencyHit: false,
+                        budgetRemaining: this.cloneBudget(),
+                    };
+                }
+            }
+        }
+        // Step 5: Allow
+        return {
+            allowed: true,
+            reason: 'All gates passed',
+            gate: 'none',
+            evidence,
+            idempotencyHit: false,
+            budgetRemaining: this.cloneBudget(),
+        };
+    }
+    /**
+     * Record a completed tool call.
+     * Updates budgets and stores the result in the idempotency cache.
+     */
+    recordCall(toolName, params, result, durationMs, tokenCount) {
+        // Update budgets
+        this.budget.toolCallBudget.used += 1;
+        this.budget.timeBudget.usedMs += durationMs;
+        if (tokenCount !== undefined) {
+            this.budget.tokenBudget.used += tokenCount;
+        }
+        // Estimate storage from serialized result
+        const serialized = JSON.stringify(result) ?? '';
+        this.budget.storageBudget.usedBytes += Buffer.byteLength(serialized, 'utf-8');
+        // Estimate cost: simple heuristic based on tokens
+        if (tokenCount !== undefined) {
+            // Rough estimate: $0.003 per 1K tokens (configurable in production)
+            this.budget.costBudget.usedUsd += (tokenCount / 1000) * 0.003;
+        }
+        // Store in idempotency cache with size-based eviction
+        const key = this.getIdempotencyKey(toolName, params);
+        const paramsHash = this.computeParamsHash(params);
+        this.idempotencyCache.set(key, {
+            key,
+            toolName,
+            paramsHash,
+            result,
+            timestamp: Date.now(),
+            ttlMs: this.idempotencyTtlMs,
+        });
+        // Evict oldest entries if cache exceeds max size
+        if (this.idempotencyCache.size > this.maxCacheSize) {
+            // Map iterates in insertion order; delete the first (oldest) entries
+            const excess = this.idempotencyCache.size - this.maxCacheSize;
+            let removed = 0;
+            for (const [k] of this.idempotencyCache) {
+                if (removed >= excess)
+                    break;
+                this.idempotencyCache.delete(k);
+                removed++;
+            }
+        }
+    }
+    /**
+     * Validate tool parameters against the registered schema.
+     * Returns valid:true if no schema is registered for the tool.
+     */
+    validateSchema(toolName, params) {
+        const schema = this.schemas.get(toolName);
+        if (!schema) {
+            // No schema registered; pass through
+            return { valid: true, errors: [] };
+        }
+        const errors = [];
+        // Check required params
+        for (const required of schema.requiredParams) {
+            if (!(required in params) || params[required] === undefined) {
+                errors.push(`Missing required parameter: "${required}"`);
+            }
+        }
+        // Check for unknown params
+        const knownParams = new Set([...schema.requiredParams, ...schema.optionalParams]);
+        for (const key of Object.keys(params)) {
+            if (!knownParams.has(key)) {
+                errors.push(`Unknown parameter: "${key}"`);
+            }
+        }
+        // Check param types
+        for (const [key, expectedType] of Object.entries(schema.paramTypes)) {
+            if (!(key in params) || params[key] === undefined)
+                continue;
+            const value = params[key];
+            const actualType = this.getParamType(value);
+            if (actualType !== expectedType) {
+                errors.push(`Parameter "${key}" expected type "${expectedType}" but got "${actualType}"`);
+            }
+        }
+        // Check param size
+        const serialized = JSON.stringify(params);
+        const sizeBytes = Buffer.byteLength(serialized, 'utf-8');
+        if (sizeBytes > schema.maxParamSize) {
+            errors.push(`Parameters size ${sizeBytes} bytes exceeds limit of ${schema.maxParamSize} bytes`);
+        }
+        // Check allowed values
+        if (schema.allowedValues) {
+            for (const [key, allowed] of Object.entries(schema.allowedValues)) {
+                if (!(key in params) || params[key] === undefined)
+                    continue;
+                const value = params[key];
+                const isAllowed = allowed.some(a => JSON.stringify(a) === JSON.stringify(value));
+                if (!isAllowed) {
+                    errors.push(`Parameter "${key}" value ${JSON.stringify(value)} is not in the allowed values list`);
+                }
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /**
+     * Check whether all budget dimensions are within limits.
+     */
+    checkBudget() {
+        const b = this.budget;
+        const withinBudget = b.tokenBudget.used <= b.tokenBudget.limit &&
+            b.toolCallBudget.used <= b.toolCallBudget.limit &&
+            b.storageBudget.usedBytes <= b.storageBudget.limitBytes &&
+            b.timeBudget.usedMs <= b.timeBudget.limitMs &&
+            b.costBudget.usedUsd <= b.costBudget.limitUsd;
+        return { withinBudget, budgetStatus: this.cloneBudget() };
+    }
+    /**
+     * Compute a deterministic idempotency key from tool name and params.
+     * Uses SHA-256 of `toolName:sortedParamsJSON`.
+     */
+    getIdempotencyKey(toolName, params) {
+        return this.computeIdempotencyKey(toolName, params);
+    }
+    /**
+     * Reset all budget counters to zero.
+     */
+    resetBudget() {
+        this.budget.tokenBudget.used = 0;
+        this.budget.toolCallBudget.used = 0;
+        this.budget.storageBudget.usedBytes = 0;
+        this.budget.timeBudget.usedMs = 0;
+        this.budget.costBudget.usedUsd = 0;
+    }
+    /**
+     * Get a snapshot of the current budget.
+     */
+    getBudget() {
+        return this.cloneBudget();
+    }
+    /**
+     * Get all idempotency records (including expired ones not yet cleaned).
+     */
+    getCallHistory() {
+        return Array.from(this.idempotencyCache.values());
+    }
+    /**
+     * Access the underlying EnforcementGates instance.
+     */
+    getGates() {
+        return this.gates;
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    /**
+     * Remove expired idempotency records (batched on interval to avoid per-call overhead).
+     */
+    maybeCleanExpiredIdempotency() {
+        const now = Date.now();
+        if (now - this.lastCleanupTime < DeterministicToolGateway.CLEANUP_INTERVAL_MS) {
+            return; // Skip cleanup until interval has passed
+        }
+        this.lastCleanupTime = now;
+        for (const [key, record] of this.idempotencyCache) {
+            if (now - record.timestamp > record.ttlMs) {
+                this.idempotencyCache.delete(key);
+            }
+        }
+    }
+    /**
+     * Compute a deterministic SHA-256 key from tool name and sorted params.
+     */
+    computeIdempotencyKey(toolName, params) {
+        const sortedParams = this.sortObject(params);
+        const input = `${toolName}:${JSON.stringify(sortedParams)}`;
+        return createHash('sha256').update(input).digest('hex');
+    }
+    /**
+     * Compute a SHA-256 hash of params only (for the IdempotencyRecord).
+     */
+    computeParamsHash(params) {
+        const sortedParams = this.sortObject(params);
+        return createHash('sha256').update(JSON.stringify(sortedParams)).digest('hex');
+    }
+    /**
+     * Recursively sort object keys for deterministic serialization.
+     */
+    sortObject(obj) {
+        if (obj === null || obj === undefined)
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map(item => this.sortObject(item));
+        if (typeof obj === 'object') {
+            const sorted = {};
+            for (const key of Object.keys(obj).sort()) {
+                sorted[key] = this.sortObject(obj[key]);
+            }
+            return sorted;
+        }
+        return obj;
+    }
+    /**
+     * Determine the type string for a parameter value.
+     */
+    getParamType(value) {
+        if (Array.isArray(value))
+            return 'array';
+        if (value === null)
+            return 'object';
+        return typeof value;
+    }
+    /**
+     * Create a deep clone of the current budget.
+     */
+    cloneBudget() {
+        return {
+            tokenBudget: { ...this.budget.tokenBudget },
+            toolCallBudget: { ...this.budget.toolCallBudget },
+            storageBudget: { ...this.budget.storageBudget },
+            timeBudget: { ...this.budget.timeBudget },
+            costBudget: { ...this.budget.costBudget },
+        };
+    }
+    /**
+     * Merge a partial budget config with defaults.
+     */
+    mergeBudget(partial) {
+        if (!partial)
+            return this.cloneDefaultBudget();
+        return {
+            tokenBudget: partial.tokenBudget
+                ? { ...DEFAULT_BUDGET.tokenBudget, ...partial.tokenBudget }
+                : { ...DEFAULT_BUDGET.tokenBudget },
+            toolCallBudget: partial.toolCallBudget
+                ? { ...DEFAULT_BUDGET.toolCallBudget, ...partial.toolCallBudget }
+                : { ...DEFAULT_BUDGET.toolCallBudget },
+            storageBudget: partial.storageBudget
+                ? { ...DEFAULT_BUDGET.storageBudget, ...partial.storageBudget }
+                : { ...DEFAULT_BUDGET.storageBudget },
+            timeBudget: partial.timeBudget
+                ? { ...DEFAULT_BUDGET.timeBudget, ...partial.timeBudget }
+                : { ...DEFAULT_BUDGET.timeBudget },
+            costBudget: partial.costBudget
+                ? { ...DEFAULT_BUDGET.costBudget, ...partial.costBudget }
+                : { ...DEFAULT_BUDGET.costBudget },
+        };
+    }
+    cloneDefaultBudget() {
+        return {
+            tokenBudget: { ...DEFAULT_BUDGET.tokenBudget },
+            toolCallBudget: { ...DEFAULT_BUDGET.toolCallBudget },
+            storageBudget: { ...DEFAULT_BUDGET.storageBudget },
+            timeBudget: { ...DEFAULT_BUDGET.timeBudget },
+            costBudget: { ...DEFAULT_BUDGET.costBudget },
+        };
+    }
+    /**
+     * Find which budget dimensions have been exceeded.
+     */
+    findExceededBudgets() {
+        const exceeded = [];
+        const b = this.budget;
+        if (b.tokenBudget.used > b.tokenBudget.limit) {
+            exceeded.push(`tokens (${b.tokenBudget.used}/${b.tokenBudget.limit})`);
+        }
+        if (b.toolCallBudget.used > b.toolCallBudget.limit) {
+            exceeded.push(`tool calls (${b.toolCallBudget.used}/${b.toolCallBudget.limit})`);
+        }
+        if (b.storageBudget.usedBytes > b.storageBudget.limitBytes) {
+            exceeded.push(`storage (${b.storageBudget.usedBytes}/${b.storageBudget.limitBytes} bytes)`);
+        }
+        if (b.timeBudget.usedMs > b.timeBudget.limitMs) {
+            exceeded.push(`time (${b.timeBudget.usedMs}/${b.timeBudget.limitMs} ms)`);
+        }
+        if (b.costBudget.usedUsd > b.costBudget.limitUsd) {
+            exceeded.push(`cost ($${b.costBudget.usedUsd.toFixed(4)}/$${b.costBudget.limitUsd.toFixed(4)})`);
+        }
+        return exceeded;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a DeterministicToolGateway instance
+ */
+export function createToolGateway(config) {
+    return new DeterministicToolGateway(config);
+}
+//# sourceMappingURL=gateway.js.map

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

@@ -0,0 +1,153 @@
+/**
+ * CLAUDE.md Generator
+ *
+ * Generates a structured CLAUDE.md file optimized for the Guidance Control Plane.
+ * The output is designed so that when compiled by GuidanceCompiler, it produces
+ * a clean constitution (always-loaded invariants) and well-tagged shards
+ * (task-scoped rules retrievable by intent).
+ *
+ * Structure conventions:
+ * - Lines 1-60: Constitution (always loaded into every task)
+ * - Remaining: Tagged shards (retrieved by intent classification)
+ * - Headings map to shard boundaries
+ * - Keywords in headings drive intent tagging: "test", "build", "security", etc.
+ *
+ * @module @claude-flow/guidance/generators
+ */
+export interface ProjectProfile {
+    /** Project name */
+    name: string;
+    /** Short description */
+    description?: string;
+    /** Primary language(s) */
+    languages: string[];
+    /** Frameworks in use */
+    frameworks?: string[];
+    /** Package manager */
+    packageManager?: 'npm' | 'pnpm' | 'yarn' | 'bun';
+    /** Monorepo? */
+    monorepo?: boolean;
+    /** Build command */
+    buildCommand?: string;
+    /** Test command */
+    testCommand?: string;
+    /** Lint command */
+    lintCommand?: string;
+    /** Source directory */
+    srcDir?: string;
+    /** Test directory */
+    testDir?: string;
+    /** Domain-specific rules */
+    domainRules?: string[];
+    /** Architecture notes */
+    architecture?: string;
+    /** Team conventions */
+    conventions?: string[];
+    /** Forbidden patterns */
+    forbidden?: string[];
+    /** Required patterns */
+    required?: string[];
+    /** Import paths for personal instructions */
+    imports?: string[];
+    /** Enable guidance control plane integration */
+    guidanceControlPlane?: boolean;
+    /** Enable WASM kernel for hot paths */
+    wasmKernel?: boolean;
+    /** Agent swarm configuration */
+    swarm?: {
+        topology?: 'hierarchical' | 'mesh' | 'adaptive';
+        maxAgents?: number;
+        strategy?: 'specialized' | 'balanced';
+    };
+}
+export interface LocalProfile {
+    /** Developer name or identifier */
+    developer?: string;
+    /** Local API URLs */
+    localUrls?: Record<string, string>;
+    /** Local database connection strings */
+    databases?: Record<string, string>;
+    /** Personal preferences */
+    preferences?: string[];
+    /** Machine-specific notes */
+    machineNotes?: string[];
+    /** Editor / IDE */
+    editor?: string;
+    /** OS */
+    os?: string;
+    /** Custom environment variables */
+    envVars?: Record<string, string>;
+    /** Debug settings */
+    debug?: string[];
+}
+export interface SkillDefinition {
+    /** Skill name (kebab-case) */
+    name: string;
+    /** Version */
+    version?: string;
+    /** Description */
+    description: string;
+    /** Category */
+    category: 'core' | 'github' | 'testing' | 'security' | 'deployment' | 'analysis' | 'custom';
+    /** Tags */
+    tags?: string[];
+    /** Required tools */
+    requires?: string[];
+    /** Capabilities list */
+    capabilities?: string[];
+    /** Skill instructions (markdown body) */
+    instructions: string;
+}
+export interface AgentDefinition {
+    /** Agent name (kebab-case) */
+    name: string;
+    /** Agent type */
+    type: 'coordinator' | 'developer' | 'tester' | 'reviewer' | 'security-specialist' | 'researcher' | 'architect' | 'devops' | 'custom';
+    /** Description */
+    description: string;
+    /** Category subdirectory */
+    category?: string;
+    /** Color for UI */
+    color?: string;
+    /** Capabilities */
+    capabilities?: string[];
+    /** Focus areas */
+    focus?: string[];
+    /** Temperature (0.0-1.0) */
+    temperature?: number;
+    /** Priority */
+    priority?: 'high' | 'medium' | 'low';
+    /** System prompt */
+    systemPrompt?: string;
+    /** Pre-execution hook */
+    preHook?: string;
+    /** Post-execution hook */
+    postHook?: string;
+    /** Detailed instructions (markdown body) */
+    instructions?: string;
+}
+export declare function generateClaudeMd(profile: ProjectProfile): string;
+export declare function generateClaudeLocalMd(local: LocalProfile): string;
+export declare function generateSkillMd(skill: SkillDefinition): string;
+export declare function generateAgentMd(agent: AgentDefinition): string;
+export declare function generateAgentIndex(agents: AgentDefinition[]): string;
+export interface ScaffoldOptions {
+    /** Project profile for CLAUDE.md */
+    project: ProjectProfile;
+    /** Local profile for CLAUDE.local.md (optional) */
+    local?: LocalProfile;
+    /** Skills to generate */
+    skills?: SkillDefinition[];
+    /** Agents to generate */
+    agents?: AgentDefinition[];
+    /** Include default agents based on project profile */
+    includeDefaultAgents?: boolean;
+    /** Include default skills based on project profile */
+    includeDefaultSkills?: boolean;
+}
+export interface ScaffoldResult {
+    /** Map of relative file path → content */
+    files: Map<string, string>;
+}
+export declare function scaffold(options: ScaffoldOptions): ScaffoldResult;
+//# sourceMappingURL=generators.d.ts.map