@directive-run/core 0.1.1

package/dist/plugins/index.d.cts

@@ -0,0 +1,697 @@
+import { M as ModuleSchema, P as Plugin, J as System } from '../plugins-CcwEXXMS.cjs';
+
+/**
+ * Logging Plugin - Console logging for Directive events
+ */
+
+interface LoggingPluginOptions {
+    /** Log level */
+    level?: "debug" | "info" | "warn" | "error";
+    /** Filter function to include/exclude events */
+    filter?: (event: string) => boolean;
+    /** Custom logger (defaults to console) */
+    logger?: Pick<Console, "debug" | "info" | "warn" | "error" | "group" | "groupEnd">;
+    /** Prefix for log messages */
+    prefix?: string;
+}
+/**
+ * Create a logging plugin.
+ *
+ * @example
+ * ```ts
+ * const system = createSystem({
+ *   modules: [myModule],
+ *   plugins: [loggingPlugin({ level: "debug" })],
+ * });
+ * ```
+ */
+declare function loggingPlugin<M extends ModuleSchema = ModuleSchema>(options?: LoggingPluginOptions): Plugin<M>;
+
+/**
+ * Devtools Plugin - Browser devtools integration
+ *
+ * Exposes the system to browser devtools via window.__DIRECTIVE__
+ */
+
+interface DevtoolsPluginOptions {
+    /** Name for this system in devtools */
+    name?: string;
+    /** Enable trace logging */
+    trace?: boolean;
+}
+interface DevtoolsState<M extends ModuleSchema> {
+    system: System<M> | null;
+    events: Array<{
+        timestamp: number;
+        type: string;
+        data: unknown;
+    }>;
+    maxEvents: number;
+}
+declare global {
+    interface Window {
+        __DIRECTIVE__?: {
+            systems: Map<string, DevtoolsState<ModuleSchema>>;
+            getSystem(name?: string): System<ModuleSchema> | null;
+            getSystems(): string[];
+            inspect(name?: string): unknown;
+            getEvents(name?: string): Array<{
+                timestamp: number;
+                type: string;
+                data: unknown;
+            }>;
+        };
+    }
+}
+/**
+ * Create a devtools plugin.
+ *
+ * @example
+ * ```ts
+ * const system = createSystem({
+ *   modules: [myModule],
+ *   plugins: [devtoolsPlugin({ name: "my-app" })],
+ * });
+ *
+ * // In browser console:
+ * // __DIRECTIVE__.inspect()
+ * // __DIRECTIVE__.getEvents()
+ * ```
+ */
+declare function devtoolsPlugin<M extends ModuleSchema = ModuleSchema>(options?: DevtoolsPluginOptions): Plugin<M>;
+
+/**
+ * Persistence Plugin - Save/restore facts to storage
+ */
+
+interface PersistencePluginOptions {
+    /** Storage backend (localStorage, sessionStorage, or custom) */
+    storage: Storage;
+    /** Key to use in storage */
+    key: string;
+    /** Only persist these fact keys (default: all) */
+    include?: string[];
+    /** Exclude these fact keys from persistence */
+    exclude?: string[];
+    /** Debounce saves by this many ms (default: 100) */
+    debounce?: number;
+    /** Called when state is restored */
+    onRestore?: (data: Record<string, unknown>) => void;
+    /** Called when state is saved */
+    onSave?: (data: Record<string, unknown>) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a persistence plugin.
+ *
+ * @example
+ * ```ts
+ * const system = createSystem({
+ *   modules: [myModule],
+ *   plugins: [
+ *     persistencePlugin({
+ *       storage: localStorage,
+ *       key: "my-app-state",
+ *       include: ["user", "preferences"],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function persistencePlugin<M extends ModuleSchema = ModuleSchema>(options: PersistencePluginOptions): Plugin<M>;
+
+/**
+ * Performance Plugin - Track constraint, resolver, and reconciliation metrics
+ *
+ * Uses existing plugin hooks to measure performance without modifying core runtime.
+ */
+
+/** Metrics for a single constraint */
+interface ConstraintMetrics {
+    evaluations: number;
+    totalDurationMs: number;
+    avgDurationMs: number;
+    maxDurationMs: number;
+    lastEvaluatedAt: number;
+}
+/** Metrics for a single resolver */
+interface ResolverMetrics {
+    starts: number;
+    completions: number;
+    errors: number;
+    retries: number;
+    cancellations: number;
+    totalDurationMs: number;
+    avgDurationMs: number;
+    maxDurationMs: number;
+    lastCompletedAt: number;
+}
+/** Metrics for the reconciliation loop */
+interface ReconcileMetrics {
+    runs: number;
+    totalDurationMs: number;
+    avgDurationMs: number;
+    maxDurationMs: number;
+}
+/** Metrics for effects */
+interface EffectMetrics {
+    runs: number;
+    errors: number;
+    lastRunAt: number;
+}
+/** Full performance snapshot */
+interface PerformanceSnapshot {
+    constraints: Record<string, ConstraintMetrics>;
+    resolvers: Record<string, ResolverMetrics>;
+    effects: Record<string, EffectMetrics>;
+    reconcile: ReconcileMetrics;
+    uptime: number;
+}
+/** Options for the performance plugin */
+interface PerformancePluginOptions {
+    /** Callback when a slow constraint is detected (default threshold: 16ms) */
+    onSlowConstraint?: (id: string, durationMs: number) => void;
+    /** Callback when a slow resolver is detected (default threshold: 1000ms) */
+    onSlowResolver?: (id: string, durationMs: number) => void;
+    /** Threshold in ms for slow constraint warning (default: 16) */
+    slowConstraintThresholdMs?: number;
+    /** Threshold in ms for slow resolver warning (default: 1000) */
+    slowResolverThresholdMs?: number;
+}
+/**
+ * Create a performance monitoring plugin.
+ *
+ * Tracks constraint evaluation time, resolver latency, reconciliation cost,
+ * and effect runs using existing plugin hooks.
+ *
+ * @example
+ * ```typescript
+ * const perf = performancePlugin({
+ *   onSlowResolver: (id, ms) => console.warn(`Slow resolver ${id}: ${ms}ms`),
+ * });
+ *
+ * const system = createSystem({
+ *   module: myModule,
+ *   plugins: [perf],
+ * });
+ *
+ * // Later: get a performance snapshot
+ * const snapshot = perf.getSnapshot();
+ * console.log(snapshot.resolvers);
+ * ```
+ */
+declare function performancePlugin<M extends ModuleSchema = ModuleSchema>(options?: PerformancePluginOptions): Plugin<M> & {
+    getSnapshot(): PerformanceSnapshot;
+    reset(): void;
+};
+
+/**
+ * Observability Dashboard Plugin
+ *
+ * Provides comprehensive monitoring, metrics collection, and dashboard integration
+ * for AI agent operations.
+ *
+ * @example
+ * ```typescript
+ * import { createObservability, createAgentMetrics } from '@directive-run/ai';
+ *
+ * const observability = createObservability({
+ *   metrics: {
+ *     enabled: true,
+ *     exportInterval: 10000, // Export every 10 seconds
+ *   },
+ *   tracing: {
+ *     enabled: true,
+ *     sampleRate: 1.0, // 100% sampling for dev
+ *   },
+ *   alerts: [
+ *     { metric: 'agent.errors', threshold: 10, action: 'warn' },
+ *     { metric: 'agent.latency', threshold: 5000, action: 'alert' },
+ *   ],
+ * });
+ *
+ * // Use createAgentMetrics for standard metric names (required for getDashboard() summary)
+ * const agentMetrics = createAgentMetrics(observability);
+ *
+ * // Access dashboard data
+ * const dashboard = observability.getDashboard();
+ *
+ * // Clean up when done
+ * await observability.dispose();
+ * ```
+ */
+/** Metric types that can be collected */
+type MetricType = "counter" | "gauge" | "histogram" | "summary";
+/** A single metric data point */
+interface MetricDataPoint {
+    name: string;
+    type: MetricType;
+    value: number;
+    labels: Record<string, string>;
+    timestamp: number;
+}
+/** Histogram bucket for latency/size distributions */
+interface HistogramBucket {
+    le: number;
+    count: number;
+}
+/** Aggregated metric for dashboard display */
+interface AggregatedMetric {
+    name: string;
+    type: MetricType;
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    avg: number;
+    p50?: number;
+    p90?: number;
+    p99?: number;
+    lastValue: number;
+    lastUpdated: number;
+}
+/** Trace span for distributed tracing */
+interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    serviceName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status: "ok" | "error" | "timeout";
+    tags: Record<string, string | number | boolean>;
+    logs: Array<{
+        timestamp: number;
+        message: string;
+        level: "debug" | "info" | "warn" | "error";
+    }>;
+}
+/** Alert configuration */
+interface AlertConfig {
+    metric: string;
+    threshold: number;
+    operator?: ">" | "<" | ">=" | "<=" | "==";
+    action: "log" | "warn" | "alert" | "callback";
+    callback?: (metric: AggregatedMetric, threshold: number) => void;
+    cooldownMs?: number;
+}
+/** Alert event when threshold is crossed */
+interface AlertEvent {
+    alertId: string;
+    metric: string;
+    currentValue: number;
+    threshold: number;
+    operator: string;
+    action: string;
+    timestamp: number;
+    message: string;
+}
+/** Observability configuration */
+interface ObservabilityConfig {
+    /** Service name for tracing */
+    serviceName?: string;
+    /** Metrics configuration */
+    metrics?: {
+        enabled?: boolean;
+        /** Export interval in milliseconds */
+        exportInterval?: number;
+        /** Custom exporter function */
+        exporter?: (metrics: AggregatedMetric[]) => Promise<void>;
+        /** Maximum data points to retain per metric */
+        maxDataPoints?: number;
+    };
+    /** Tracing configuration */
+    tracing?: {
+        enabled?: boolean;
+        /** Sample rate (0.0 to 1.0) */
+        sampleRate?: number;
+        /** Maximum spans to retain */
+        maxSpans?: number;
+        /** Custom trace exporter */
+        exporter?: (spans: TraceSpan[]) => Promise<void>;
+    };
+    /** Alert configurations */
+    alerts?: AlertConfig[];
+    /**
+     * Metric names used by `getDashboard().summary` and `getHealthStatus()`.
+     * Defaults to `agent.requests`, `agent.errors`, `agent.latency`, `agent.tokens`, `agent.cost`.
+     * Must match the metric names you record via `incrementCounter` / `observeHistogram`,
+     * or use `createAgentMetrics()` which records with these default names.
+     */
+    summaryMetrics?: {
+        requests?: string;
+        errors?: string;
+        latency?: string;
+        tokens?: string;
+        cost?: string;
+    };
+    /** Event callbacks */
+    events?: {
+        onMetricRecorded?: (metric: MetricDataPoint) => void;
+        onSpanStart?: (span: TraceSpan) => void;
+        onSpanEnd?: (span: TraceSpan) => void;
+        onAlert?: (alert: AlertEvent) => void;
+    };
+}
+/** Dashboard data for UI display */
+interface DashboardData {
+    /** Service info */
+    service: {
+        name: string;
+        uptime: number;
+        startTime: number;
+    };
+    /** Aggregated metrics */
+    metrics: Record<string, AggregatedMetric>;
+    /** Recent traces */
+    traces: TraceSpan[];
+    /** Active alerts */
+    alerts: AlertEvent[];
+    /** Summary stats */
+    summary: {
+        totalRequests: number;
+        totalErrors: number;
+        errorRate: number;
+        avgLatency: number;
+        p99Latency: number;
+        activeSpans: number;
+        totalTokens: number;
+        totalCost: number;
+    };
+}
+/** Observability instance */
+interface ObservabilityInstance {
+    /** Record a counter metric */
+    incrementCounter(name: string, labels?: Record<string, string>, value?: number): void;
+    /** Record a gauge metric */
+    setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /** Record a histogram observation */
+    observeHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    /** Start a trace span */
+    startSpan(operationName: string, parentSpanId?: string): TraceSpan;
+    /** End a trace span */
+    endSpan(spanId: string, status?: "ok" | "error" | "timeout"): void;
+    /** Add log to a span */
+    addSpanLog(spanId: string, message: string, level?: "debug" | "info" | "warn" | "error"): void;
+    /** Add tag to a span */
+    addSpanTag(spanId: string, key: string, value: string | number | boolean): void;
+    /** Get dashboard data */
+    getDashboard(): DashboardData;
+    /** Get a specific metric */
+    getMetric(name: string): AggregatedMetric | undefined;
+    /** Get recent traces */
+    getTraces(limit?: number): TraceSpan[];
+    /** Get active alerts */
+    getAlerts(): AlertEvent[];
+    /** Export all data */
+    export(): {
+        metrics: AggregatedMetric[];
+        traces: TraceSpan[];
+        alerts: AlertEvent[];
+    };
+    /** Clear all data and reset statistics */
+    clear(): void;
+    /** Dispose of the instance, clearing timers and flushing data */
+    dispose(): Promise<void>;
+    /** Get health status for status pages */
+    getHealthStatus(): {
+        healthy: boolean;
+        uptime: number;
+        errorRate: number;
+        activeAlerts: number;
+    };
+}
+/**
+ * Create an observability instance for monitoring AI agents.
+ *
+ * @example
+ * ```typescript
+ * const obs = createObservability({
+ *   serviceName: 'my-agent-service',
+ *   metrics: { enabled: true },
+ *   tracing: { enabled: true, sampleRate: 0.1 },
+ *   alerts: [
+ *     { metric: 'agent.errors', threshold: 10, action: 'alert' },
+ *   ],
+ * });
+ *
+ * // Track agent operations
+ * const span = obs.startSpan('agent.run');
+ * obs.incrementCounter('agent.requests', { agent: 'support' });
+ *
+ * try {
+ *   await runAgent();
+ *   obs.observeHistogram('agent.latency', Date.now() - start);
+ *   obs.endSpan(span.spanId, 'ok');
+ * } catch (e) {
+ *   obs.incrementCounter('agent.errors');
+ *   obs.endSpan(span.spanId, 'error');
+ * }
+ * ```
+ */
+declare function createObservability(config?: ObservabilityConfig): ObservabilityInstance;
+/**
+ * Create standard agent metrics for an observability instance.
+ *
+ * @example
+ * ```typescript
+ * const obs = createObservability({ serviceName: 'my-service' });
+ * const agentMetrics = createAgentMetrics(obs);
+ *
+ * // Track an agent run
+ * agentMetrics.trackRun('support-agent', {
+ *   success: true,
+ *   latencyMs: 1500,
+ *   inputTokens: 100,
+ *   outputTokens: 500,
+ *   cost: 0.05,
+ * });
+ * ```
+ */
+declare function createAgentMetrics(obs: ObservabilityInstance): {
+    trackRun(agentName: string, result: {
+        success: boolean;
+        latencyMs: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        cost?: number;
+        toolCalls?: number;
+    }): void;
+    trackGuardrail(guardrailName: string, result: {
+        passed: boolean;
+        latencyMs: number;
+        blocked?: boolean;
+    }): void;
+    trackApproval(toolName: string, result: {
+        approved: boolean;
+        waitTimeMs: number;
+        timedOut?: boolean;
+    }): void;
+    trackHandoff(fromAgent: string, toAgent: string, latencyMs: number): void;
+};
+
+/**
+ * OTLP (OpenTelemetry Protocol) Exporter
+ *
+ * Converts Directive observability data to OTLP JSON format for export to
+ * Grafana, Datadog, Jaeger, and other OpenTelemetry-compatible backends.
+ *
+ * @example
+ * ```typescript
+ * import { createObservability } from '@directive-run/ai';
+ * import { createOTLPExporter } from '@directive-run/ai';
+ *
+ * const exporter = createOTLPExporter({
+ *   endpoint: 'http://localhost:4318',
+ *   headers: { 'Authorization': 'Bearer token' },
+ *   serviceName: 'my-agent-service',
+ * });
+ *
+ * const obs = createObservability({
+ *   metrics: { exporter: exporter.exportMetrics, exportInterval: 10000 },
+ *   tracing: { exporter: exporter.exportTraces },
+ * });
+ * ```
+ */
+
+/** OTLP exporter configuration */
+interface OTLPExporterConfig {
+    /** OTLP endpoint base URL (e.g., http://localhost:4318) */
+    endpoint: string;
+    /** Optional headers (e.g., auth tokens) */
+    headers?: Record<string, string>;
+    /** Service name for resource identification */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Custom resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Instrumentation scope version (default: "0.1.0") */
+    scopeVersion?: string;
+    /** Request timeout in ms (default: 10000) */
+    timeoutMs?: number;
+    /** Custom fetch function (for testing or custom HTTP clients) */
+    fetch?: typeof globalThis.fetch;
+    /** Callback on export error */
+    onError?: (error: Error, type: "metrics" | "traces") => void;
+}
+/** OTLP exporter instance */
+interface OTLPExporter {
+    /** Export metrics in OTLP format (compatible with ObservabilityConfig.metrics.exporter) */
+    exportMetrics: (metrics: AggregatedMetric[]) => Promise<void>;
+    /** Export traces in OTLP format (compatible with ObservabilityConfig.tracing.exporter) */
+    exportTraces: (traces: TraceSpan[]) => Promise<void>;
+}
+/**
+ * Create an OTLP exporter for sending metrics and traces to OpenTelemetry-compatible backends.
+ *
+ * Supports:
+ * - Grafana (via OTLP endpoint)
+ * - Datadog (via OTLP ingest)
+ * - Jaeger (via OTLP collector)
+ * - Any OpenTelemetry Collector
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOTLPExporter({
+ *   endpoint: 'http://localhost:4318',
+ *   serviceName: 'my-agent-service',
+ * });
+ *
+ * // Wire into observability
+ * const obs = createObservability({
+ *   metrics: { exporter: exporter.exportMetrics, exportInterval: 10000 },
+ *   tracing: { exporter: exporter.exportTraces },
+ * });
+ * ```
+ */
+declare function createOTLPExporter(config: OTLPExporterConfig): OTLPExporter;
+
+/**
+ * Circuit Breaker for AI Agent Operations
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures when
+ * downstream services (MCP servers, LLM APIs) are degraded. Integrates with
+ * the observability plugin to wire error rates into constraint decisions.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failures exceeded threshold, requests are rejected immediately
+ * - HALF_OPEN: After recovery timeout, a limited number of requests are allowed through
+ *
+ * @example
+ * ```typescript
+ * import { createCircuitBreaker } from '@directive-run/ai';
+ *
+ * const breaker = createCircuitBreaker({
+ *   failureThreshold: 5,
+ *   recoveryTimeMs: 30000,
+ *   halfOpenMaxRequests: 3,
+ * });
+ *
+ * // Use with MCP or any async operation
+ * const result = await breaker.execute(async () => {
+ *   return await callExternalAPI();
+ * });
+ *
+ * // Wire into Directive constraints
+ * constraints: {
+ *   apiDown: {
+ *     when: () => breaker.getState() === 'OPEN',
+ *     require: { type: 'FALLBACK_RESPONSE' },
+ *   },
+ * }
+ * ```
+ */
+
+/** Circuit breaker states */
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/** Circuit breaker configuration */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before transitioning from OPEN to HALF_OPEN (default: 30000) */
+    recoveryTimeMs?: number;
+    /** Number of requests allowed in HALF_OPEN state (default: 3) */
+    halfOpenMaxRequests?: number;
+    /** Time window in ms for counting failures (default: 60000). Failures outside this window are forgotten. */
+    failureWindowMs?: number;
+    /** Optional observability instance for automatic metric tracking */
+    observability?: ObservabilityInstance;
+    /** Metric name prefix for observability (default: "circuit_breaker") */
+    metricPrefix?: string;
+    /** Name for this circuit breaker (used in metrics and errors) */
+    name?: string;
+    /** Custom error classifier. Return true if the error should count as a failure. Default: all errors count. */
+    isFailure?: (error: Error) => boolean;
+    /** Callback when state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/** Circuit breaker statistics */
+interface CircuitBreakerStats {
+    state: CircuitState;
+    totalRequests: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    totalRejected: number;
+    recentFailures: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+    lastStateChange: number;
+}
+/** Circuit breaker instance */
+interface CircuitBreaker {
+    /** Execute an operation through the circuit breaker */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /** Get the current state */
+    getState(): CircuitState;
+    /** Get statistics */
+    getStats(): CircuitBreakerStats;
+    /** Force the circuit to a specific state (useful for testing) */
+    forceState(state: CircuitState): void;
+    /** Reset the circuit breaker to CLOSED with cleared stats */
+    reset(): void;
+    /** Check if a request would be allowed (without executing) */
+    isAllowed(): boolean;
+}
+/** Error thrown when a request is rejected because the circuit is open */
+declare class CircuitBreakerOpenError extends Error {
+    readonly code: "CIRCUIT_OPEN";
+    readonly retryAfterMs: number;
+    readonly state: "OPEN" | "HALF_OPEN";
+    constructor(name: string, retryAfterMs: number, state?: "OPEN" | "HALF_OPEN", detail?: string);
+}
+/**
+ * Create a circuit breaker for protecting against cascading failures.
+ *
+ * @example
+ * ```typescript
+ * const breaker = createCircuitBreaker({
+ *   name: 'openai-api',
+ *   failureThreshold: 5,
+ *   recoveryTimeMs: 30000,
+ *   observability: obs, // Optional: auto-track metrics
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await openai.chat.completions.create({ ... });
+ *   });
+ * } catch (error) {
+ *   if (error.message.includes('Circuit breaker')) {
+ *     // Circuit is open, use fallback
+ *   }
+ * }
+ * ```
+ *
+ * @throws {Error} If failureThreshold is less than 1 or not a finite number
+ * @throws {Error} If recoveryTimeMs is not positive or not a finite number
+ * @throws {Error} If halfOpenMaxRequests is less than 1 or not a finite number
+ * @throws {Error} If failureWindowMs is not positive or not a finite number
+ */
+declare function createCircuitBreaker(config?: CircuitBreakerConfig): CircuitBreaker;
+
+export { type AggregatedMetric, type AlertConfig, type AlertEvent, type CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitBreakerStats, type CircuitState, type ConstraintMetrics, type DashboardData, type DevtoolsPluginOptions, type EffectMetrics, type HistogramBucket, type LoggingPluginOptions, type MetricDataPoint, type MetricType, type OTLPExporter, type OTLPExporterConfig, type ObservabilityConfig, type ObservabilityInstance, type PerformancePluginOptions, type PerformanceSnapshot, type PersistencePluginOptions, type ReconcileMetrics, type ResolverMetrics, type TraceSpan, createAgentMetrics, createCircuitBreaker, createOTLPExporter, createObservability, devtoolsPlugin, loggingPlugin, performancePlugin, persistencePlugin };