dino-spec 17.4.2 → 17.5.0

package/dist/hooks/hook-agent-bridge.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Hook-Agent Bridge - v17.5.0
+ *
+ * Enables hybrid communication between hooks (fast, deterministic) and
+ * agents (reasoning, complex). Implements decision matrix for when to
+ * escalate from hook to agent.
+ *
+ * Features:
+ * - Escalation from hooks to agents when complexity detected
+ * - Temporary hook registration by agents
+ * - Shared validation cache
+ * - Decision matrix: <2s deterministic = hook, >2s reasoning = agent
+ * - Performance targets: hooks <100ms, agents 2-30s
+ * - Message bus integration
+ *
+ * @module hook-agent-bridge
+ */
+import { type CacheConfig, ValidationCache } from '../core/agents/validation-cache.js';
+/**
+ * Decision on how to handle an operation
+ */
+export type HandlerDecision = 'hook' | 'agent' | 'both';
+/**
+ * Complexity assessment result
+ */
+export interface ComplexityAssessment {
+    /** Overall complexity score (0-100) */
+    score: number;
+    /** Recommended handler */
+    handler: HandlerDecision;
+    /** Factors contributing to complexity */
+    factors: ComplexityFactor[];
+    /** Estimated processing time (ms) */
+    estimatedTimeMs: number;
+    /** Reason for decision */
+    reason: string;
+}
+/**
+ * Factor contributing to complexity
+ */
+export interface ComplexityFactor {
+    /** Factor name */
+    name: string;
+    /** Weight (0-1) */
+    weight: number;
+    /** Score (0-100) */
+    score: number;
+    /** Description */
+    description: string;
+}
+/**
+ * Escalation request from hook to agent
+ */
+export interface EscalationRequest {
+    /** Unique request ID */
+    id: string;
+    /** Hook that is escalating */
+    hookId: string;
+    /** Operation being performed */
+    operation: string;
+    /** Context data */
+    context: Record<string, unknown>;
+    /** Complexity assessment */
+    assessment: ComplexityAssessment;
+    /** Priority */
+    priority: 'low' | 'medium' | 'high' | 'critical';
+    /** Timestamp */
+    timestamp: Date;
+    /** Callback for result */
+    callback?: (result: EscalationResult) => void;
+}
+/**
+ * Result from agent escalation
+ */
+export interface EscalationResult {
+    /** Request ID */
+    requestId: string;
+    /** Success status */
+    success: boolean;
+    /** Result data */
+    data?: unknown;
+    /** Error if failed */
+    error?: string;
+    /** Processing time (ms) */
+    processingTimeMs: number;
+    /** Agent that handled */
+    agentId?: string;
+}
+/**
+ * Temporary hook registration by agent
+ */
+export interface TemporaryHook {
+    /** Unique ID */
+    id: string;
+    /** Agent that registered */
+    agentId: string;
+    /** Event to match */
+    event: string;
+    /** Matcher pattern (regex) */
+    matcher?: string;
+    /** Handler function */
+    handler: (context: Record<string, unknown>) => Promise<HookResult>;
+    /** Whether blocking */
+    blocking: boolean;
+    /** Expiration time */
+    expiresAt: Date;
+    /** Priority (higher = runs first) */
+    priority: number;
+}
+/**
+ * Result from hook execution
+ */
+export interface HookResult {
+    /** Continue with operation */
+    proceed: boolean;
+    /** Message to return */
+    message?: string;
+    /** Modified context */
+    modifiedContext?: Record<string, unknown>;
+}
+/**
+ * Bridge configuration
+ */
+export interface BridgeConfig {
+    /** Threshold for escalating to agent (0-100) */
+    escalationThreshold: number;
+    /** Max hook execution time (ms) */
+    maxHookTimeMs: number;
+    /** Max agent execution time (ms) */
+    maxAgentTimeMs: number;
+    /** Enable shared validation cache */
+    enableSharedCache: boolean;
+    /** Cache configuration */
+    cacheConfig?: Partial<CacheConfig>;
+    /** Default temporary hook TTL (ms) */
+    defaultHookTtlMs: number;
+}
+export declare const DEFAULT_BRIDGE_CONFIG: BridgeConfig;
+/**
+ * Bridge between hooks and agents
+ */
+export declare class HookAgentBridge {
+    private config;
+    private temporaryHooks;
+    private pendingEscalations;
+    private sharedCache;
+    private escalationCounter;
+    constructor(config?: Partial<BridgeConfig>);
+    /**
+     * Assess complexity of an operation
+     */
+    assessComplexity(operation: string, context: Record<string, unknown>): ComplexityAssessment;
+    /**
+     * Detect if operation requires reasoning
+     */
+    private detectReasoningRequired;
+    /**
+     * Detect external API calls
+     */
+    private detectExternalCalls;
+    /**
+     * Detect security-sensitive operations
+     */
+    private detectSecuritySensitive;
+    /**
+     * Detect async operations
+     */
+    private detectAsyncOperation;
+    /**
+     * Determine handler based on score and factors
+     */
+    private determineHandler;
+    /**
+     * Estimate processing time
+     */
+    private estimateProcessingTime;
+    /**
+     * Generate decision reason
+     */
+    private generateDecisionReason;
+    /**
+     * Escalate operation to agent
+     */
+    escalateToAgent(hookId: string, operation: string, context: Record<string, unknown>): Promise<EscalationResult>;
+    /**
+     * Determine priority for escalation
+     */
+    private determinePriority;
+    /**
+     * Wait for escalation result
+     */
+    private waitForEscalationResult;
+    /**
+     * Register a temporary hook from an agent
+     */
+    registerTemporaryHook(hook: Omit<TemporaryHook, 'id' | 'expiresAt'>): string;
+    /**
+     * Unregister a temporary hook
+     */
+    unregisterTemporaryHook(hookId: string): boolean;
+    /**
+     * Get all active temporary hooks for an event
+     */
+    getTemporaryHooksForEvent(event: string): TemporaryHook[];
+    /**
+     * Execute temporary hooks
+     */
+    executeTemporaryHooks(event: string, context: Record<string, unknown>): Promise<HookResult>;
+    /**
+     * Get the shared validation cache
+     */
+    getSharedCache(): ValidationCache<unknown>;
+    /**
+     * Check cache for a value
+     */
+    getCached<T>(key: string): T | undefined;
+    /**
+     * Set cache value
+     */
+    setCached(key: string, value: unknown, ttlMs?: number): void;
+    /**
+     * Setup message handlers for agent communication
+     */
+    private setupMessageHandlers;
+    /**
+     * Get bridge statistics
+     */
+    getStats(): {
+        pendingEscalations: number;
+        activeTemporaryHooks: number;
+        cacheStats: ReturnType<ValidationCache<unknown>['getStats']>;
+    };
+    /**
+     * Clear all state
+     */
+    clear(): void;
+}
+/** Global hook-agent bridge instance */
+export declare const hookAgentBridge: HookAgentBridge;
+/**
+ * Quick decision on handler for an operation
+ */
+export declare function decideHandler(operation: string, context: Record<string, unknown>): HandlerDecision;
+/**
+ * Check if operation should escalate to agent
+ */
+export declare function shouldEscalate(operation: string, context: Record<string, unknown>): boolean;
+/**
+ * Format assessment for display
+ */
+export declare function formatAssessment(assessment: ComplexityAssessment): string;
+//# sourceMappingURL=hook-agent-bridge.d.ts.map

package/dist/hooks/hook-agent-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-agent-bridge.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-agent-bridge.ts"],"names":[],"mappings":"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"}