0xray 3.4.2 → 3.4.4

package/dist/core/adaptive-kernel.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Adaptive Kernel Extension for P9 - ADAPTIVE_PATTERN_LEARNING
+ *
+ * Composes with existing Kernel to add self-modifying pattern learning capabilities.
+ * Enables continuous pattern improvement based on performance data.
+ *
+ * @since 2026-03-05
+ */
+import { type KernelInferenceResult, type AdaptiveThresholds, type EmergentPattern, type PatternUpdate } from "../core/kernel-patterns.js";
+import { patternPerformanceTracker } from "../analytics/pattern-performance-tracker.js";
+import { emergingPatternDetector } from "../analytics/emerging-pattern-detector.js";
+import { patternLearningEngine } from "../analytics/pattern-learning-engine.js";
+export interface AdaptiveKernelConfig {
+    enabled: boolean;
+    enableP9Learning: boolean;
+    learningIntervalMs: number;
+    autoApplyThreshold: number;
+    confidenceThreshold: number;
+    maxPatternsPerAnalysis: number;
+}
+export interface P9AnalysisResult extends KernelInferenceResult {
+    patternDriftDetected: boolean;
+    driftAnalyses: Array<{
+        patternId: string;
+        driftMagnitude: number;
+        driftDirection: 'increasing' | 'decreasing' | 'unstable';
+        recommendedAction: string;
+    }>;
+    emergentPatterns: EmergentPattern[];
+    suggestedUpdates: PatternUpdate[];
+    adaptiveThresholds?: AdaptiveThresholds;
+    learningApplied: boolean;
+}
+export declare class AdaptiveKernelAnalyzer {
+    private adaptiveConfig;
+    private baseKernel;
+    private lastLearningRun;
+    private cachedP9Analysis;
+    private cacheValidMs;
+    constructor(config?: Partial<AdaptiveKernelConfig>);
+    /**
+     * Analyze observation using base kernel enhanced with P9 learning
+     */
+    analyze(observation: string): KernelInferenceResult;
+    /**
+     * Enhanced analyze with P9 learning capabilities
+     */
+    analyzeWithP9(observation: string): P9AnalysisResult;
+    /**
+     * Perform P9 adaptive pattern learning analysis
+     */
+    private performP9Analysis;
+    /**
+     * Get current adaptive thresholds
+     */
+    getAdaptiveThresholds(): AdaptiveThresholds;
+    /**
+     * Get pattern drift analyses
+     */
+    getPatternDrift(): Array<{
+        patternId: string;
+        driftMagnitude: number;
+        driftDirection: 'increasing' | 'decreasing' | 'unstable';
+        recommendedAction: string;
+    }>;
+    /**
+     * Manually trigger learning cycle
+     */
+    triggerLearning(outcomes: Array<{
+        taskId: string;
+        taskDescription: string;
+        routedAgent: string;
+        routedSkill: string;
+        confidence: number;
+        success: boolean;
+    }>, existingMappings: Array<{
+        keywords: string[];
+        skill: string;
+        agent: string;
+        confidence: number;
+    }>): {
+        newPatterns: number;
+        modifiedPatterns: number;
+        removedPatterns: number;
+        thresholdUpdates: number;
+        recommendations: string[];
+    };
+    /**
+     * Get learning statistics
+     */
+    getLearningStats(): {
+        lastLearningRun: Date;
+        cacheValid: boolean;
+        patternsTracked: number;
+        driftDetected: number;
+        thresholdsCalibrated: boolean;
+    };
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: Partial<AdaptiveKernelConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): AdaptiveKernelConfig;
+}
+export declare function getAdaptiveKernel(config?: Partial<AdaptiveKernelConfig>): AdaptiveKernelAnalyzer;
+export { patternPerformanceTracker, emergingPatternDetector, patternLearningEngine };

package/dist/core/agent-spawn-gate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agent Spawn Gate — Singleton (provider-agnostic)
+ *
+ * CENTRALIZED CONTROL for all agent process spawning across 0xRay
+ * (OpenCode, Hermes, or any other MCP-compatible host).
+ *
+ * Purpose:
+ *   Prevent runaway recursive agent spawning.
+ *
+ * Design:
+ *   - Singleton instance shared across all modules
+ *   - Explicit enable/disable with state persistence
+ *   - Tracks all active spawned processes for cleanup
+ *   - Gates every spawn path: inference, orchestrator, scripts, tests
+ *
+ * Usage:
+ *   import { spawnGate } from "./agent-spawn-gate.js";
+ *
+ *   // Before spawning
+ *   spawnGate.assertAllowed("inference-cycle");
+ *
+ *   // Global disable (emergency brake)
+ *   spawnGate.disable("emergency: runaway processes detected");
+ */
+declare class AgentSpawnGate {
+    private static instance;
+    private state;
+    private constructor();
+    static getInstance(): AgentSpawnGate;
+    /** Check if spawning is globally allowed */
+    isAllowed(): boolean;
+    /** Enable spawning (opt-in, not default) */
+    enable(reason: string): void;
+    /** Disable spawning globally */
+    disable(reason: string): void;
+    /** Assert spawning is allowed or throw */
+    assertAllowed(module: string): void;
+    /** Register a spawned process PID for tracking */
+    trackProcess(pid: number, module: string, description: string): void;
+    /** Unregister a process when it exits */
+    untrackProcess(pid: number): void;
+    /** Kill all tracked processes (emergency cleanup) */
+    killAllProcesses(signal?: NodeJS.Signals): Promise<number>;
+    /** Get current gate status */
+    getStatus(): {
+        enabled: boolean;
+        reason: string | undefined;
+        disabledAt: number | undefined;
+        activeProcesses: number;
+        totalSpawned: number;
+        totalBlocked: number;
+    };
+}
+/** Singleton export — use this everywhere (provider-agnostic) */
+export declare const spawnGate: AgentSpawnGate;
+export default spawnGate;

package/dist/core/boot-orchestrator.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Boot Orchestrator (min documented consumer runtime compat shim from prior 0xRay releases; primary Xray paths + .xray fallbacks only; 1-line per Scope Rule).
+ */
+import { XrayStateManager } from "../state/state-manager.js";
+import { type MemoryStats } from "../monitoring/memory-monitor.js";
+export interface BootSequenceConfig {
+    enableEnforcement: boolean;
+    codexValidation: boolean;
+    sessionManagement: boolean;
+    processorActivation: boolean;
+    agentLoading: boolean;
+}
+export interface BootResult {
+    success: boolean;
+    orchestratorLoaded: boolean;
+    sessionManagementActive: boolean;
+    processorsActivated: boolean;
+    enforcementEnabled: boolean;
+    codexComplianceActive: boolean;
+    agentsLoaded: string[];
+    errors: string[];
+}
+export declare class BootOrchestrator {
+    private contextLoader;
+    private stateManager;
+    private processorManager;
+    private config;
+    private pluginRegistry?;
+    private pluginServerRegistry?;
+    private shutdownInitialized;
+    constructor(config?: Partial<BootSequenceConfig>, stateManager?: XrayStateManager);
+    /**
+     * Initialize delegation system components
+     */
+    private initializeDelegationSystem;
+    private loadProcessorsConfig;
+    /**
+     * Initialize plugin system and register MCP servers
+     */
+    private initializePluginSystem;
+    /**
+     * Load orchestrator as the first component
+     */
+    private loadOrchestrator;
+    /**
+     * Initialize session management system
+     */
+    private initializeSessionManagement;
+    /**
+     * Activate pre/post processors
+     */
+    private activateProcessors;
+    /**
+     * Load remaining agents after orchestrator
+     */
+    private loadRemainingAgents;
+    /**
+     * Enable automatic enforcement activation
+     */
+    private enableEnforcement;
+    /**
+     * Activate codex compliance checking during boot
+     */
+    private activateCodexCompliance;
+    private initializeSecurityComponents;
+    private finalizeSecurityIntegration;
+    private runInitialSecurityAudit;
+    /**
+     * Validate processor health during boot
+     */
+    private validateProcessorHealth;
+    /**
+     * Get current boot status information
+     */
+    getBootStatus(): BootResult;
+    /**
+     * Set up comprehensive memory monitoring and alerting
+     */
+    private setupMemoryMonitoring;
+    /**
+     * Perform comprehensive memory health check
+     */
+    getMemoryHealth(): {
+        healthy: boolean;
+        issues: string[];
+        metrics: {
+            current: MemoryStats;
+            peak: MemoryStats;
+            average: number;
+            trend: string;
+        };
+    };
+    /**
+     * Execute the boot sequence (internal framework initialization)
+     */
+    executeBootSequence(): Promise<BootResult>;
+    private loadXrayConfiguration;
+}
+export declare const bootOrchestrator: BootOrchestrator;

package/dist/core/codex-formatter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Codex Formatter — Standalone Codex-to-Prompt Converter
+ *
+ * Converts 0xRay's Universal Development Codex terms into
+ * formatted system prompt text. No OpenCode dependency, no plugin
+ * API, no framework imports. Pure input/output.
+ *
+ * This is the decoupled replacement for the codex injection that
+ * previously lived inside the OpenCode plugin (xray-codex-injection.ts).
+ *
+ * Usage from any host (Node.js, Python via bridge, HTTP, etc.):
+ *   import { formatCodexPrompt } from './codex-formatter.js';
+ *   const prompt = formatCodexPrompt({ projectRoot: '/path' });
+ *   // Append to system prompt
+ *
+ * @since 2026-03-28
+ */
+export interface CodexTerm {
+    id: string;
+    title: string;
+    description: string;
+    severity: "blocking" | "high" | "medium";
+    examples?: string[];
+}
+export interface CodexConfig {
+    version: string;
+    terms: CodexTerm[];
+    categories?: Record<string, string[]>;
+}
+export interface FormatOptions {
+    /** Project root for config resolution (default: cwd) */
+    projectRoot?: string;
+    /** Include only terms matching these severity levels (default: all) */
+    severityFilter?: Array<"blocking" | "high" | "medium">;
+    /** Include examples for each term (default: false) */
+    includeExamples?: boolean;
+    /** Maximum number of terms to include (default: all) */
+    maxTerms?: number;
+    /** Custom header text (default: auto-generated) */
+    header?: string;
+    /** Include config path reference in footer (default: true) */
+    includeConfigPath?: boolean;
+    /** Compress output by omitting descriptions for medium-severity terms */
+    compressed?: boolean;
+}
+export interface FormatResult {
+    /** The formatted prompt text */
+    prompt: string;
+    /** Number of terms included */
+    termCount: number;
+    /** Total terms available */
+    totalTerms: number;
+    /** Codex version */
+    version: string;
+    /** Config source path (or null if using built-in fallback) */
+    configPath: string | null;
+    /** Approximate character count */
+    charCount: number;
+}
+export declare const BUILTIN_CODEX: CodexConfig;
+/**
+ * Find codex.json using the standard priority chain.
+ * Mirrors config-paths.ts resolveCodexPath() but returns first match.
+ */
+export declare function findCodexPath(projectRoot?: string): string | null;
+/**
+ * Load and parse codex.json. Falls back to built-in codex if not found.
+ */
+export declare function loadCodex(projectRoot?: string): {
+    config: CodexConfig;
+    source: string | null;
+};
+/**
+ * Format codex terms into a system-prompt-ready string.
+ *
+ * This is the primary export. Any host (OpenCode, Hermes, Claude Desktop,
+ * custom agent) can call this to get enforcement text for their system prompt.
+ */
+export declare function formatCodexPrompt(options?: FormatOptions): FormatResult;
+/**
+ * Get codex as a structured JSON object (for programmatic consumers).
+ */
+export declare function getCodexConfig(options?: {
+    projectRoot?: string;
+}): {
+    version: string;
+    terms: CodexTerm[];
+    termCount: number;
+    source: string | null;
+};
+/**
+ * Get a minimal codex prompt for token-constrained environments.
+ * Only includes blocking terms, no descriptions.
+ */
+export declare function formatMinimalCodexPrompt(options?: FormatOptions): FormatResult;

package/dist/core/codex-injector.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 0xRay Codex Context Injector Hook
+ *
+ * Injects Universal Development Codex v1.2.0 context into agent operations.
+ * Follows production-tested pattern from rules-injector.
+ *
+ * @since 2026-01-06
+ */
+/**
+ * Create xray-codex-injector hook
+ *
+ * This hook injects codex context into tool outputs and displays
+ * a welcome message on agent startup, following the production-tested
+ * pattern from OpenCode's rules-injector.
+ */
+export declare function createXrayCodexInjectorHook(): {
+    name: "xray-codex-injector";
+    hooks: {
+        "agent.start": (sessionId: string) => Promise<void>;
+        "tool.execute.before": (input: {
+            tool: string;
+            args?: Record<string, unknown>;
+        }, sessionId: string) => Promise<void>;
+        "tool.execute.after": (input: {
+            tool: string;
+            args?: Record<string, unknown>;
+        }, output: {
+            output?: string;
+            [key: string]: unknown;
+        }, sessionId: string) => Promise<{
+            [key: string]: unknown;
+            output?: string;
+        } | {
+            output: string;
+        }>;
+    };
+};
+/**
+ * Get codex statistics for debugging
+ */
+export declare function getCodexStats(sessionId: string): {
+    loaded: boolean;
+    fileCount: number;
+    totalTerms: number;
+    version: string;
+};
+/**
+ * Clear codex cache (useful for testing or forced reload)
+ */
+export declare function clearCodexCache(sessionId?: string): void;
+/**
+ * CodexInjector class for plugin compatibility
+ */
+export declare class CodexInjector {
+    injectCodexRules(context: Record<string, unknown>, options: {
+        priority?: string;
+        mergeStrategy?: string;
+    }): Record<string, unknown>;
+    getCodexStats(): {
+        loaded: boolean;
+        fileCount: number;
+        totalTerms: number;
+        version: string;
+    };
+    /**
+     * Permissive comment validation - recognizes that comments are beneficial
+     * Only flags truly problematic patterns, provides guidance not requirements
+     */
+    validateCommentsPermissively(content: string): {
+        guidance: string[];
+        concerns: string[];
+    };
+}

package/dist/core/config-loader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Configuration Loader (backward-compat shim)
+ *
+ * Delegates to FeaturesConfigLoader as the single source of truth.
+ * Retained for backward compatibility -- all consumers of xrayConfigLoader
+ * continue to work without changes.
+ *
+ * @deprecated Use featuresConfigLoader from "./features-config.js" instead.
+ * Will be removed in v4.0.0.
+ */
+export type { MultiAgentOrchestrationConfig, AutonomousReportingConfig } from "./features-config.js";
+export interface XrayConfig {
+    multi_agent_orchestration: import("./features-config.js").MultiAgentOrchestrationConfig;
+    autonomous_reporting: import("./features-config.js").AutonomousReportingConfig;
+    disabled_agents: string[];
+}
+export declare class XrayConfigLoader {
+    private configPath;
+    private cachedConfig;
+    private cacheExpiry;
+    private lastLoadTime;
+    constructor(configPath?: string);
+    /**
+     * Load configuration -- delegates to FeaturesConfigLoader
+     * @deprecated Use featuresConfigLoader.getXrayConfig() instead.
+     */
+    loadConfig(): XrayConfig;
+    /**
+     * Parse configuration data with validation
+     * @deprecated Use featuresConfigLoader.loadConfig() instead.
+     */
+    private parseConfig;
+    /**
+     * Parse multi-agent orchestration configuration
+     * @deprecated Use featuresConfigLoader.loadConfig().multi_agent_orchestration instead.
+     */
+    private parseMultiAgentConfig;
+    /**
+     * Parse autonomous reporting configuration
+     * @deprecated Use featuresConfigLoader.loadConfig().autonomous_reporting instead.
+     */
+    private parseAutonomousReportingConfig;
+    /**
+     * Get default configuration
+     * @deprecated Use featuresConfigLoader.getDefaultConfig() instead.
+     */
+    private getDefaultConfig;
+    /**
+     * Validate enum values
+     * @deprecated Internal implementation detail.
+     */
+    private validateEnum;
+    /**
+     * Clear configuration cache
+     * @deprecated Use featuresConfigLoader.clearCache() instead.
+     */
+    clearCache(): void;
+}
+export declare const xrayConfigLoader: XrayConfigLoader;

package/dist/core/config-paths.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Config Path Resolver
+ *
+ * Centralizes all 0xRay config file path resolution.
+ * Supports XRAY_CONFIG_DIR env var for custom config roots.
+ *
+ * Resolution order (per file type):
+ *   1. XRAY_CONFIG_DIR/<relative_path>     (if env var set)
+ *   2. .xray/<relative_path>                 (preferred lightweight root)
+ *   3. null                                   (callers fall back to built-in defaults)
+ *
+ * For state/data directories, uses:
+ *   1. XRAY_CONFIG_DIR/state                 (if env var set)
+ *   2. .xray/state
+ *   3. .opencode/state                         (legacy)
+ *   4. .xray/state                              (default — always writable)
+ */
+/** Environment variable name for custom config root */
+export declare const XRAY_CONFIG_DIR_ENV = "XRAY_CONFIG_DIR";
+/**
+ * Detect the best available config directory.
+ * Scans in priority order and caches the first one that exists (or the first default).
+ */
+export declare function getConfigDir(projectRoot?: string): string;
+/**
+ * Resolve a specific config file path using the standard priority chain.
+ * Returns null if no suitable path is found (caller should use defaults).
+ *
+ * @param relativePath - Path relative to config dir (e.g., "features.json")
+ * @param projectRoot  - Optional project root override
+ */
+export declare function resolveConfigPath(relativePath: string, projectRoot?: string): string | null;
+/**
+ * Get the state persistence directory (the parent directory for state.json).
+ * Similar logic to resolveConfigPath but for the state/ subdirectory.
+ */
+export declare function resolveStateDir(projectRoot?: string): string;
+/**
+ * Get the state persistence FILE path (e.g. .opencode/state/state.json).
+ * Prefer this over resolveStateDir when you need a file path for fs.writeFileSync.
+ */
+export declare function resolveStateFilePath(projectRoot?: string): string;
+/**
+ * Get the profiles storage directory.
+ */
+export declare function resolveProfilesDir(projectRoot?: string): string;
+/**
+ * Resolve codex.json path.
+ * Has additional fallback locations beyond the standard config dir.
+ */
+/** Environment variable for explicit project root override */
+export declare const XRAY_ROOT_ENV = "XRAY_ROOT";
+/**
+ * Resolve project root using XRAY_ROOT env var if set,
+ * otherwise fall back to projectRoot param or cwd.
+ */
+export declare function resolveProjectRoot(projectRoot?: string): string;
+export declare function resolveCodexPath(projectRoot?: string): string[];
+/**
+ * Get the logs directory for framework logging.
+ */
+export declare function resolveLogDir(projectRoot?: string): string;
+/**
+ * Reset the cached config dir (useful for testing).
+ */
+export declare function resetConfigDirCache(): void;

package/dist/core/context-loader.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 0xRay Context Loader
+ *
+ * Loads Universal Development Codex v1.2.0 context for agent initialization.
+ * Provides structured access to 30+ codex terms, interweaves, lenses, and anti-patterns.
+ *
+ * @since 2026-01-06
+ */
+/**
+ * Codex term structure
+ */
+export interface CodexTerm {
+    number: number;
+    description: string;
+    category: "core" | "extended" | "architecture" | "advanced";
+    zeroTolerance?: boolean;
+    enforcementLevel?: "low" | "medium" | "high" | "blocking";
+}
+/**
+ * Parsed codex context
+ */
+export interface CodexContext {
+    version: string;
+    lastUpdated: string;
+    terms: Map<number, CodexTerm>;
+    interweaves: string[];
+    lenses: string[];
+    principles: string[];
+    antiPatterns: string[];
+    validationCriteria: Record<string, boolean>;
+    frameworkAlignment: Record<string, string>;
+    errorPreventionTarget: number;
+}
+/**
+ * Context loading result
+ */
+export interface ContextLoadResult {
+    success: boolean;
+    context?: CodexContext;
+    error?: string;
+    warnings: string[];
+}
+/**
+ * 0xRay Context Loader
+ *
+ * Loads and parses the Universal Development Codex v1.2.0 from codex.json
+ */
+export declare class XrayContextLoader {
+    private static instance;
+    private cachedContext;
+    private codexFilePaths;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): XrayContextLoader;
+    /**
+     * Load codex context
+     *
+     * Attempts to load the Universal Development Codex from multiple possible locations.
+     * Returns cached context if available and not expired.
+     */
+    loadCodexContext(projectRoot: string): Promise<ContextLoadResult>;
+    /**
+     * Parse codex content from JSON or Markdown
+     *
+     * Extracts all 30+ codex terms, interweaves, lenses, and principles from content.
+     * Supports both JSON and Markdown formats with explicit format detection.
+     */
+    private parseCodexContent;
+    private inferTermCategory;
+    /**
+     * Get specific codex term by number
+     */
+    getTerm(context: CodexContext, termNumber: number): CodexTerm | undefined;
+    /**
+     * Get all core terms (1-10)
+     */
+    getCoreTerms(context: CodexContext): CodexTerm[];
+    /**
+     * Get zero-tolerance terms that require immediate blocking
+     */
+    getZeroToleranceTerms(context: CodexContext): CodexTerm[];
+    /**
+     * Validate action against codex
+     *
+     * Checks if an action complies with relevant codex terms.
+     * Returns validation result with violations and recommendations.
+     */
+    validateAgainstCodex(context: CodexContext, action: string, actionDetails: Record<string, unknown>): {
+        compliant: boolean;
+        violations: Array<{
+            term: CodexTerm;
+            reason: string;
+            severity: "low" | "medium" | "high" | "blocking";
+        }>;
+        recommendations: string[];
+    };
+    /**
+     * Clear cached context (useful for testing or forced reload)
+     */
+    clearCache(): void;
+    /**
+     * Check if context is loaded and valid
+     */
+    isContextLoaded(): boolean;
+    /**
+     * Get context statistics
+     */
+    getContextStats(): {
+        loaded: boolean;
+        termCount: number;
+        categoryBreakdown: Record<string, number>;
+        zeroToleranceCount: number;
+    };
+}
+/**
+ * Export singleton instance
+ */
+export declare const xrayContextLoader: XrayContextLoader;