claude-flow 3.28.0 → 3.30.0

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

@@ -0,0 +1,370 @@
+/**
+ * RuvBot Integration Bridge
+ *
+ * Bridges ruvbot (npm: ruvbot@0.1.8) with the @claude-flow/guidance control
+ * plane. Wires ruvbot events to guidance hooks, wraps AIDefence as an
+ * enforcement gate, governs memory operations, and feeds trust accumulation.
+ *
+ * ruvbot is an optional peer dependency. All types and classes are exported
+ * regardless of whether ruvbot is installed. Runtime calls that require the
+ * ruvbot package will throw a clear error if the package is missing.
+ *
+ * Components:
+ * 1. RuvBotGuidanceBridge  - Event wiring, gate delegation, trust tracking
+ * 2. AIDefenceGate         - Prompt injection, jailbreak, PII detection gate
+ * 3. RuvBotMemoryAdapter   - Governed memory read/write with proof logging
+ *
+ * @module @claude-flow/guidance/ruvbot-integration
+ */
+import type { GateResult } from './types.js';
+import type { MemoryAuthority, MemoryEntry, WriteDecision } from './memory-gate.js';
+/**
+ * Minimal interface for a ruvbot instance. Mirrors the event-emitter surface
+ * exposed by `createRuvBot()` without importing the package at compile time.
+ */
+export interface RuvBotInstance {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    emit?(event: string, ...args: unknown[]): void;
+}
+/**
+ * Minimal interface for ruvbot's AIDefence guard returned by
+ * `createAIDefenceGuard()`.
+ */
+export interface RuvBotAIDefenceGuard {
+    check(input: string): Promise<{
+        safe: boolean;
+        threats: Array<{
+            type: string;
+            severity: string;
+            detail: string;
+        }>;
+        sanitizedInput?: string;
+    }>;
+}
+/**
+ * Minimal interface for ruvbot's memory subsystem.
+ */
+export interface RuvBotMemory {
+    read(key: string, namespace?: string): Promise<unknown>;
+    write(key: string, value: unknown, namespace?: string): Promise<void>;
+    delete?(key: string, namespace?: string): Promise<void>;
+    search?(query: string, options?: Record<string, unknown>): Promise<unknown[]>;
+}
+/**
+ * Threat detected by the AIDefence layer.
+ */
+export interface AIDefenceThreat {
+    type: 'prompt-injection' | 'jailbreak' | 'pii' | 'control-chars' | 'homoglyph';
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    detail: string;
+}
+/**
+ * Result of an AIDefence evaluation.
+ */
+export interface AIDefenceResult {
+    safe: boolean;
+    threats: AIDefenceThreat[];
+    sanitizedInput?: string;
+    latencyMs: number;
+}
+/**
+ * Configuration for the AIDefenceGate.
+ */
+export interface AIDefenceGateConfig {
+    detectPromptInjection: boolean;
+    detectJailbreak: boolean;
+    detectPII: boolean;
+    blockThreshold: 'low' | 'medium' | 'high';
+}
+/**
+ * Configuration for the RuvBotGuidanceBridge.
+ */
+export interface RuvBotBridgeConfig {
+    enableAIDefence: boolean;
+    enableMemoryGovernance: boolean;
+    enableTrustTracking: boolean;
+    enableProofChain: boolean;
+    /** HMAC signing key for proof chains. Required when enableProofChain is true. */
+    proofSigningKey?: string;
+}
+/**
+ * A normalized ruvbot event for internal processing.
+ */
+export interface RuvBotEvent {
+    type: string;
+    timestamp: number;
+    sessionId?: string;
+    agentId?: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Wraps ruvbot's 6-layer AIDefence as an enforcement gate compatible with the
+ * guidance control plane's GateResult / GateDecision interface.
+ *
+ * Supports:
+ * - Prompt injection detection
+ * - Jailbreak detection
+ * - PII detection
+ * - Control character and homoglyph detection (via ruvbot internals)
+ * - Configurable sensitivity / block threshold
+ *
+ * Evaluates both input (pre-processing) and output (post-processing) text.
+ */
+export declare class AIDefenceGate {
+    private config;
+    private guard;
+    private guardInitPromise;
+    constructor(config?: Partial<AIDefenceGateConfig>);
+    /**
+     * Lazily initialize the underlying ruvbot AIDefence guard.
+     * Safe to call multiple times; only the first call creates the guard.
+     */
+    private ensureGuard;
+    /**
+     * Evaluate input text for threats (pre-processing gate).
+     *
+     * Checks for prompt injection, jailbreak attempts, and PII based
+     * on the configured sensitivity.
+     */
+    evaluateInput(input: string): Promise<AIDefenceResult>;
+    /**
+     * Evaluate output text for threats (post-processing gate).
+     *
+     * Primarily checks for PII leakage and secret exposure in responses.
+     */
+    evaluateOutput(output: string): Promise<AIDefenceResult>;
+    /**
+     * Convert an AIDefenceResult into a GateResult compatible with the
+     * guidance enforcement pipeline.
+     *
+     * Decision logic:
+     * - If no threats: 'allow'
+     * - If threats above block threshold: 'block'
+     * - Otherwise: 'warn'
+     */
+    toGateResult(result: AIDefenceResult, context?: string): GateResult;
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): AIDefenceGateConfig;
+    /**
+     * Update configuration. Resets the guard so the next evaluation
+     * re-initializes with the new settings.
+     */
+    updateConfig(config: Partial<AIDefenceGateConfig>): void;
+    private normalizeThreats;
+    private buildRemediation;
+}
+/**
+ * Wraps ruvbot's memory read/write operations with guidance control plane
+ * governance. Every write passes through the MemoryWriteGate for authority
+ * and coherence checks. All operations are logged to a proof chain.
+ */
+export declare class RuvBotMemoryAdapter {
+    private readonly memoryGate;
+    private readonly coherenceScheduler;
+    private proofChain;
+    private ruvbotMemory;
+    private operationLog;
+    constructor(memoryGate: import('./memory-gate.js').MemoryWriteGate, coherenceScheduler: import('./coherence.js').CoherenceScheduler);
+    /**
+     * Attach a ruvbot memory instance for proxied operations.
+     */
+    attachMemory(memory: RuvBotMemory): void;
+    /**
+     * Attach a proof chain for operation logging.
+     */
+    attachProofChain(proofChain: import('./proof.js').ProofChain): void;
+    /**
+     * Governed read: reads through ruvbot memory, logs to proof chain.
+     */
+    read(key: string, namespace?: string): Promise<unknown>;
+    /**
+     * Governed write: runs through MemoryWriteGate, checks coherence,
+     * logs to proof chain, then delegates to ruvbot memory.
+     *
+     * Returns the WriteDecision. If denied, the write is not performed.
+     */
+    write(key: string, namespace: string, value: unknown, authority: MemoryAuthority, existingEntries?: MemoryEntry[]): Promise<WriteDecision>;
+    /**
+     * Governed delete: checks authority, logs, then delegates.
+     */
+    delete(key: string, namespace: string, authority: MemoryAuthority): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
+    /**
+     * Get the operation log for audit/proof purposes.
+     */
+    getOperationLog(): ReadonlyArray<{
+        operation: 'read' | 'write' | 'delete';
+        key: string;
+        namespace: string;
+        timestamp: number;
+        decision?: WriteDecision;
+    }>;
+    /**
+     * Get the count of governed operations.
+     */
+    get operationCount(): number;
+    /**
+     * Clear the operation log.
+     */
+    clearLog(): void;
+    private ensureMemoryAttached;
+}
+/**
+ * Bridges a ruvbot instance with the @claude-flow/guidance control plane.
+ *
+ * Wires ruvbot event hooks to guidance enforcement and trust systems:
+ *
+ * - `message`        -> EnforcementGates (secrets, destructive ops) + AIDefence
+ * - `agent:spawn`    -> ManifestValidator
+ * - `session:create` -> ProofChain initialization
+ * - `session:end`    -> ProofChain finalization and ledger persistence
+ * - `ready`          -> Trust accumulator initialization
+ * - `error`          -> Trust 'deny' outcome recording
+ *
+ * All gate outcomes are fed into the TrustAccumulator so that ruvbot agents
+ * build (or lose) trust over time.
+ */
+export declare class RuvBotGuidanceBridge {
+    private readonly config;
+    private ruvbot;
+    private gates;
+    private manifestValidator;
+    private trustSystem;
+    private aiDefenceGate;
+    private memoryAdapter;
+    private sessionChains;
+    private boundHandlers;
+    private eventLog;
+    private static readonly MAX_EVENT_LOG;
+    constructor(config?: Partial<RuvBotBridgeConfig>);
+    /**
+     * Attach guidance control plane components.
+     *
+     * Accepts either a full GuidanceControlPlane instance (from which
+     * sub-components are extracted) or individual components.
+     */
+    attachGuidance(components: {
+        gates?: import('./gates.js').EnforcementGates;
+        manifestValidator?: import('./manifest-validator.js').ManifestValidator;
+        trustSystem?: import('./trust.js').TrustSystem;
+        aiDefenceGate?: AIDefenceGate;
+        memoryAdapter?: RuvBotMemoryAdapter;
+    }): void;
+    /**
+     * Connect to a ruvbot instance and wire all event handlers.
+     *
+     * This is the primary entry point. Once called, the bridge will
+     * intercept ruvbot events and route them through guidance gates.
+     */
+    connect(ruvbot: RuvBotInstance): void;
+    /**
+     * Disconnect from the ruvbot instance, removing all event handlers.
+     */
+    disconnect(): void;
+    /**
+     * Evaluate a ruvbot AIDefence result and return a GateResult-compatible
+     * decision. Can be called independently of event wiring.
+     */
+    evaluateAIDefence(input: string): Promise<GateResult>;
+    /**
+     * Get the proof chain for a specific session.
+     */
+    getSessionProofChain(sessionId: string): import('./proof.js').ProofChain | undefined;
+    /**
+     * Get all active session IDs.
+     */
+    getActiveSessionIds(): string[];
+    /**
+     * Get the event log for diagnostics.
+     */
+    getEventLog(): ReadonlyArray<RuvBotEvent>;
+    /**
+     * Get the current bridge configuration.
+     */
+    getConfig(): RuvBotBridgeConfig;
+    /**
+     * Whether the bridge is currently connected to a ruvbot instance.
+     */
+    get connected(): boolean;
+    /**
+     * Handle `message` events: run content through enforcement gates
+     * and optionally through AIDefence.
+     */
+    private handleMessage;
+    /**
+     * Handle `agent:spawn` events: validate agent manifest.
+     */
+    private handleAgentSpawn;
+    /**
+     * Handle `session:create` events: initialize a proof chain for the session.
+     */
+    private handleSessionCreate;
+    /**
+     * Handle `session:end` events: finalize the proof chain and persist.
+     */
+    private handleSessionEnd;
+    /**
+     * Handle `ready` events: log bridge activation.
+     */
+    private handleReady;
+    /**
+     * Handle `shutdown` events: clean up all session proof chains.
+     */
+    private handleShutdown;
+    /**
+     * Handle `error` events: record a deny outcome in trust tracking.
+     */
+    private handleError;
+    /**
+     * Handle `agent:stop` events: record final trust snapshot.
+     */
+    private handleAgentStop;
+    private wireEvent;
+    private logEvent;
+}
+/**
+ * Create a fully wired RuvBotGuidanceBridge.
+ *
+ * Connects the bridge to a ruvbot instance and attaches the guidance
+ * control plane components. The bridge immediately begins intercepting
+ * ruvbot events.
+ *
+ * @param ruvbotInstance - A ruvbot instance (from createRuvBot())
+ * @param guidancePlane - A GuidanceControlPlane or individual components
+ * @param config - Optional bridge configuration
+ * @returns The connected RuvBotGuidanceBridge
+ */
+export declare function createRuvBotBridge(ruvbotInstance: RuvBotInstance, guidancePlane: {
+    gates?: import('./gates.js').EnforcementGates;
+    manifestValidator?: import('./manifest-validator.js').ManifestValidator;
+    trustSystem?: import('./trust.js').TrustSystem;
+    aiDefenceGate?: AIDefenceGate;
+    memoryAdapter?: RuvBotMemoryAdapter;
+}, config?: Partial<RuvBotBridgeConfig>): RuvBotGuidanceBridge;
+/**
+ * Create an AIDefenceGate with optional configuration.
+ *
+ * The gate lazily initializes the underlying ruvbot AIDefence guard
+ * on the first evaluation call.
+ *
+ * @param config - Optional gate configuration
+ * @returns A new AIDefenceGate instance
+ */
+export declare function createAIDefenceGate(config?: Partial<AIDefenceGateConfig>): AIDefenceGate;
+/**
+ * Create a RuvBotMemoryAdapter with governance components.
+ *
+ * The adapter wraps ruvbot memory operations with MemoryWriteGate authority
+ * checks and CoherenceScheduler tracking.
+ *
+ * @param memoryGate - The MemoryWriteGate for authority/rate/contradiction checks
+ * @param coherenceScheduler - The CoherenceScheduler for drift tracking
+ * @returns A new RuvBotMemoryAdapter instance
+ */
+export declare function createRuvBotMemoryAdapter(memoryGate: import('./memory-gate.js').MemoryWriteGate, coherenceScheduler: import('./coherence.js').CoherenceScheduler): RuvBotMemoryAdapter;
+//# sourceMappingURL=ruvbot-integration.d.ts.map