0xray 2.0.0 → 2.0.1

package/dist/integrations/base/registry.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Integration Registry
+ *
+ * Central registry for managing 0xRay integrations.
+ * Provides registration, loading, unloading, health checking, and stats retrieval.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import { EventEmitter } from "events";
+import { type IIntegration, type IntegrationConfig, type HealthResult, type IntegrationStats, type IntegrationStatus } from "./types.js";
+/**
+ * Integration configuration from config file
+ */
+export interface IntegrationsConfig {
+    integrations: Record<string, {
+        enabled: boolean;
+        config?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Registry event types
+ */
+export type RegistryEventType = "integration-registered" | "integration-unregistered" | "integration-loaded" | "integration-unloaded" | "load-complete" | "unload-complete" | "health-check-complete" | "error";
+/**
+ * Registry event
+ */
+export interface RegistryEvent {
+    type: RegistryEventType;
+    timestamp: number;
+    integrationName?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    error?: Error | undefined;
+}
+/**
+ * Loaded integration metadata
+ */
+interface LoadedIntegration {
+    instance: IIntegration;
+    config: IntegrationConfig;
+    loadedAt: number;
+}
+/**
+ * Error thrown when integration is not found in registry
+ */
+export declare class IntegrationNotFoundError extends Error {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown when integration is already registered
+ */
+export declare class IntegrationAlreadyRegisteredError extends Error {
+    constructor(integrationName: string);
+}
+/**
+ * Integration Registry
+ *
+ * Manages registration, loading, and lifecycle of integrations.
+ *
+ * @example
+ * ```typescript
+ * const registry = new IntegrationRegistry();
+ *
+ * // Register an integration
+ * registry.register('my-integration', new MyIntegration());
+ *
+ * // Get an integration
+ * const integration = registry.get('my-integration');
+ *
+ * // List all integrations
+ * const names = registry.list();
+ *
+ * // Load from config
+ * await registry.loadAll({
+ *   integrations: {
+ *     'my-integration': { enabled: true }
+ *   }
+ * });
+ * ```
+ */
+export declare class IntegrationRegistry extends EventEmitter {
+    /** Map of registered integrations (name -> instance) */
+    private registeredIntegrations;
+    /** Map of loaded integrations (name -> metadata) */
+    private loadedIntegrations;
+    /** Job ID for registry operations */
+    private jobId;
+    /**
+     * Create a new IntegrationRegistry
+     */
+    constructor();
+    /**
+     * Register an integration with the registry
+     *
+     * @param name - Unique name for the integration
+     * @param integration - Integration instance to register
+     * @throws IntegrationAlreadyRegisteredError if name already registered
+     */
+    register(name: string, integration: IIntegration): void;
+    /**
+     * Unregister an integration from the registry
+     *
+     * @param name - Name of the integration to unregister
+     * @throws IntegrationNotFoundError if integration not found
+     */
+    unregister(name: string): void;
+    /**
+     * Get an integration by name
+     *
+     * @param name - Name of the integration
+     * @returns Integration instance or undefined if not found
+     */
+    get(name: string): IIntegration | undefined;
+    /**
+     * Get a loaded integration by name
+     *
+     * @param name - Name of the loaded integration
+     * @returns Loaded integration metadata or undefined if not loaded
+     */
+    getLoaded(name: string): LoadedIntegration | undefined;
+    /**
+     * List all registered integration names
+     *
+     * @returns Array of integration names
+     */
+    list(): string[];
+    /**
+     * List all loaded integration names
+     *
+     * @returns Array of loaded integration names
+     */
+    listLoaded(): string[];
+    /**
+     * Check if an integration is registered
+     *
+     * @param name - Name to check
+     * @returns true if registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Check if an integration is loaded
+     *
+     * @param name - Name to check
+     * @returns true if loaded
+     */
+    isLoaded(name: string): boolean;
+    /**
+     * Load an integration by name
+     *
+     * @param name - Integration name
+     * @param config - Optional integration configuration
+     * @throws IntegrationNotFoundError if integration not registered
+     */
+    load(name: string, config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Unload an integration by name
+     *
+     * @param name - Integration name
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    unload(name: string): Promise<void>;
+    /**
+     * Load all enabled integrations from configuration
+     *
+     * @param config - Integrations configuration
+     */
+    loadAll(config: IntegrationsConfig): Promise<void>;
+    /**
+     * Unload all loaded integrations
+     */
+    unloadAll(): Promise<void>;
+    /**
+     * Get health status of all loaded integrations
+     *
+     * @returns Record of integration names to health results
+     */
+    healthCheckAll(): Promise<Record<string, HealthResult>>;
+    /**
+     * Get health status of a specific integration
+     *
+     * @param name - Integration name
+     * @returns Health result
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    healthCheck(name: string): Promise<HealthResult>;
+    /**
+     * Get statistics from all loaded integrations
+     *
+     * @returns Record of integration names to stats
+     */
+    getAllStats(): Record<string, IntegrationStats>;
+    /**
+     * Get statistics from a specific integration
+     *
+     * @param name - Integration name
+     * @returns Integration stats
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    getStats(name: string): IntegrationStats;
+    /**
+     * Get status of a specific integration
+     *
+     * @param name - Integration name
+     * @returns Integration status
+     */
+    getStatus(name: string): IntegrationStatus | undefined;
+    /**
+     * Get all integration statuses
+     *
+     * @returns Record of integration names to statuses
+     */
+    getAllStatuses(): Record<string, IntegrationStatus>;
+    /**
+     * Clear all registered integrations (not loaded ones)
+     */
+    clear(): void;
+    /**
+     * Get registry statistics
+     *
+     * @returns Registry statistics
+     */
+    getRegistryStats(): {
+        registered: number;
+        loaded: number;
+        byStatus: Record<IntegrationStatus, number>;
+    };
+    /**
+     * Emit a registry event
+     */
+    private emitEvent;
+}
+/**
+ * Integration discovery result
+ */
+export interface DiscoveredIntegration {
+    name: string;
+    path: string;
+    module: unknown;
+}
+/**
+ * Auto-discover integrations from directory index files
+ *
+ * This function scans the integrations directory for integration modules
+ * and returns their discovered information.
+ *
+ * @param integrationsPath - Path to integrations directory
+ * @returns Array of discovered integrations
+ *
+ * @example
+ * ```typescript
+ * const discovered = await discoverIntegrations('./src/integrations');
+ * for (const d of discovered) {
+ *   console.log(`Found: ${d.name} at ${d.path}`);
+ * }
+ * ```
+ */
+export declare function discoverIntegrations(integrationsPath: string): Promise<DiscoveredIntegration[]>;
+/**
+ * Auto-register integrations from discovered modules
+ *
+ * @param registry - Registry instance to register with
+ * @param integrationsPath - Path to integrations directory
+ * @returns Number of integrations registered
+ *
+ * @example
+ * ```typescript
+ * const registry = new IntegrationRegistry();
+ * const count = await autoRegisterIntegrations(registry, './src/integrations');
+ * console.log(`Registered ${count} integrations`);
+ * ```
+ */
+export declare function autoRegisterIntegrations(registry: IntegrationRegistry, integrationsPath: string): Promise<number>;
+export {};

package/dist/integrations/base/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Integration Base Types
+ *
+ * Common TypeScript interfaces for 0xRay integrations.
+ * Provides a standardized foundation for all integration types.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import type { EventEmitter } from "events";
+/**
+ * Log levels for integration logging
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/**
+ * Integration configuration options
+ */
+export interface IntegrationConfig {
+    /** Whether the integration is enabled */
+    enabled: boolean;
+    /** Enable debug mode for additional logging */
+    debug: boolean;
+    /** Log level for the integration */
+    logLevel: LogLevel;
+    /** Optional custom configuration options */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Default integration configuration
+ */
+export declare const DEFAULT_INTEGRATION_CONFIG: IntegrationConfig;
+/**
+ * Integration lifecycle status
+ */
+export type IntegrationStatus = "uninitialized" | "initializing" | "initialized" | "error" | "shutting-down" | "shutdown";
+/**
+ * Health check result
+ */
+export interface HealthResult {
+    /** Whether the integration is healthy */
+    healthy: boolean;
+    /** Human-readable message describing the health status */
+    message: string;
+    /** Optional additional details about the health status */
+    details?: Record<string, unknown> | undefined;
+}
+/**
+ * Default healthy result
+ */
+export declare const HEALTHY_RESULT: HealthResult;
+/**
+ * Default unhealthy result
+ */
+export declare function createUnhealthyResult(message: string, details?: Record<string, unknown>): HealthResult;
+/**
+ * Base integration statistics
+ */
+export interface IntegrationStats {
+    /** Time since initialization in milliseconds */
+    uptime: number;
+    /** Number of errors encountered */
+    errors: number;
+    /** Optional custom statistics */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Creates a default integration stats object
+ */
+export declare function createIntegrationStats(): IntegrationStats;
+/**
+ * Base integration events
+ */
+export type IntegrationEventType = "initialized" | "initializing" | "shutdown" | "shutting-down" | "error" | "health-check" | "stats-updated" | "config-updated";
+/**
+ * Integration event payload
+ */
+export interface IntegrationEvent<T = unknown> {
+    /** Event type */
+    type: IntegrationEventType;
+    /** Timestamp when the event occurred */
+    timestamp: number;
+    /** Event data */
+    data?: T | undefined;
+    /** Optional error if event represents an error */
+    error?: Error | undefined;
+}
+/**
+ * Integration interface
+ * All 0xRay integrations must implement this interface
+ */
+export interface IIntegration {
+    /** Unique name of the integration */
+    readonly name: string;
+    /** Version of the integration */
+    readonly version: string;
+    /** Current lifecycle status */
+    readonly status: IntegrationStatus;
+    /**
+     * Initialize the integration with optional configuration
+     * @param config - Optional partial configuration to merge with defaults
+     */
+    initialize(config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Gracefully shutdown the integration
+     * Should clean up resources and close connections
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Perform a health check
+     * @returns Promise resolving to health result
+     */
+    healthCheck(): Promise<HealthResult>;
+    /**
+     * Get current integration statistics
+     * @returns Current stats object
+     */
+    getStats(): IntegrationStats;
+}
+/**
+ * Extended integration interface with event support
+ */
+export interface IEventedIntegration extends IIntegration {
+    /** Get the event emitter for this integration */
+    getEventEmitter(): EventEmitter;
+}
+/**
+ * Integration factory function type
+ */
+export type IntegrationFactory<T extends IIntegration = IIntegration> = (config?: Partial<IntegrationConfig>) => T;
+/**
+ * Integration constructor type
+ */
+export type IntegrationConstructor<T extends IIntegration = IIntegration> = new (config?: Partial<IntegrationConfig>) => T;
+/**
+ * Base error class for integration errors
+ */
+export declare class IntegrationError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, recoverable: boolean, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when integration is not initialized
+ */
+export declare class IntegrationNotInitializedError extends IntegrationError {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown when integration is already initialized
+ */
+export declare class IntegrationAlreadyInitializedError extends IntegrationError {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown during integration initialization
+ */
+export declare class IntegrationInitializationError extends IntegrationError {
+    constructor(integrationName: string, originalError: Error);
+}
+/**
+ * Type guard to check if an object is an integration
+ */
+export declare function isIntegration(value: unknown): value is IIntegration;
+/**
+ * Type guard to check if an object is a health result
+ */
+export declare function isHealthy(result: HealthResult): boolean;

package/dist/integrations/governance/governance-client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Governance HTTP Client
+ *
+ * Client for calling the chrono-warp-drive Dynamo governance endpoint.
+ * Handles HTTP requests, retries, and response validation.
+ *
+ * @version 1.0.0
+ * @since 2026-05-11
+ */
+import type { GovernanceCheckResponse, SolarGovernanceCheckRequest, SolarGovernanceCheckResponse, GovernanceClientConfig, GovernanceClientStats } from './types.js';
+/**
+ * HTTP client for governance endpoint
+ */
+export declare class GovernanceClient {
+    private config;
+    private stats;
+    constructor(config?: Partial<GovernanceClientConfig>);
+    /**
+     * Call any Dynamo MCP tool via call_connected_tool proxy
+     */
+    private callTool;
+    /**
+     * Check a proposal with solar-enhanced governance (govern_with_solar tool)
+     *
+     * Brings real-time solar context from NOAA GOES into governance decisions,
+     * automatically adjusting vote weight and adding warnings based on current
+     * solar activity (quiet / moderate / active / storm).
+     */
+    governWithSolar(request: SolarGovernanceCheckRequest): Promise<SolarGovernanceCheckResponse>;
+    /**
+     * Evaluate a proposal with standard governance (evaluate_governance tool)
+     *
+     * For purely technical or low-level protocol decisions where external
+     * solar modifiers are undesired.
+     */
+    evaluateGovernance(params: {
+        proposalId: string;
+        proposalText: string;
+        agentReviews: string[];
+        codeDiff?: string;
+        historicalSignalIds?: string[];
+    }): Promise<GovernanceCheckResponse>;
+    /**
+     * Make HTTP request with retries and exponential backoff
+     */
+    private makeJsonRequest;
+    /**
+     * Validate solar governance response structure with range checks
+     */
+    private isValidSolarResponse;
+    private doJsonRequest;
+    /**
+     * Validate governance response structure
+     */
+    private isValidResponse;
+    /**
+     * Update average response time
+     */
+    private updateResponseTime;
+    /**
+     * Delay utility
+     */
+    private delay;
+    /**
+     * Get client statistics
+     */
+    getStats(): GovernanceClientStats;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<GovernanceClientConfig>): void;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+}

package/dist/integrations/governance/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Inference Governance Integration
+ *
+ * Integrates chrono-warp-drive Dynamo governance endpoint for external
+ * inference checking in governance decision-making.
+ *
+ * @version 1.0.0
+ * @since 2026-05-11
+ */
+import { BaseIntegration } from '../base/index.js';
+import type { GovernanceIntegrationConfig, GovernanceVoteResult, BatchGovernanceCheck } from './types.js';
+import type { InferenceProposal } from '../../inference/inference-cycle.js';
+/**
+ * Main Governance Integration class
+ *
+ * Provides external governance checking for inference proposals via the
+ * chrono-warp-drive Dynamo /governance endpoint.
+ */
+export declare class InferenceGovernanceIntegration extends BaseIntegration {
+    private client;
+    private configData;
+    constructor();
+    /**
+     * Perform integration-specific initialization
+     */
+    protected performInitialization(): Promise<void>;
+    /**
+     * Perform integration-specific shutdown
+     */
+    protected performShutdown(): Promise<void>;
+    /**
+     * Perform health check
+     */
+    protected performHealthCheck(): Promise<{
+        healthy: boolean;
+        message: string;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * Check if governance is enabled and available
+     */
+    isAvailable(): boolean;
+    /**
+     * Check a single inference proposal via the appropriate governance tool
+     *
+     * Routes to govern_with_solar (strategic proposals) or evaluate_governance
+     * (technical proposals) based on proposal type.
+     */
+    checkProposal(proposal: InferenceProposal, agentReviews?: string[], historicalIds?: string[]): Promise<GovernanceVoteResult>;
+    /**
+     * Route: evaluate_governance — for purely technical proposals (fix, guard)
+     */
+    private evaluateProposal;
+    /**
+     * Route: govern_with_solar — for strategic proposals (refactor, codify, automate)
+     *
+     * Brings real-time NOAA GOES solar context into the decision, adjusting
+     * vote weight and adding warnings based on current solar activity.
+     */
+    private governWithSolarProposal;
+    /**
+     * Check multiple proposals with external governance
+     */
+    checkProposals(proposals: InferenceProposal[], agentReviews?: string[], historicalIds?: string[]): Promise<BatchGovernanceCheck>;
+    /**
+     * Apply decision logic based on governance response
+     */
+    private applyDecisionLogic;
+    /**
+     * Create fallback vote when governance is unavailable
+     */
+    private createFallbackVote;
+    /**
+     * Load configuration from features.json
+     */
+    private loadConfig;
+    /**
+     * Get governance-specific configuration
+     */
+    getGovernanceConfig(): GovernanceIntegrationConfig;
+    /**
+     * Get client statistics
+     */
+    getClientStats(): import("./types.js").GovernanceClientStats;
+}
+/**
+ * Initialize the global governance integration
+ */
+export declare function initializeGovernanceIntegration(): Promise<InferenceGovernanceIntegration>;
+/**
+ * Get the global governance integration
+ */
+export declare function getGovernanceIntegration(): InferenceGovernanceIntegration | null;
+/**
+ * Shutdown the global governance integration
+ */
+export declare function shutdownGovernanceIntegration(): Promise<void>;
+export * from './types.js';
+export * from './governance-client.js';