0xray 3.4.1 → 3.4.3

package/dist/nucleus/kernel.d.ts

@@ -0,0 +1,51 @@
+/**
+ * xray Nucleus — the callable governance kernel (Phase 1.1 facade)
+ *
+ * This is the primary, stable import surface for the v3 nucleus.
+ *
+ * Consumers (bridges, custom tools, the MCP governance server, future self-proposal
+ * engines, CLI, etc.) should import from here rather than reaching into
+ * governance-service.ts, govern-http.ts, or postprocessor internals directly.
+ *
+ * Goals:
+ * - Single place to import the core "govern" capability + supporting types.
+ * - Zero risk to the 41-server federation or existing bridges.
+ * - Easy to tree-shake / split later (e.g. "nucleus/core", "nucleus/http").
+ * - Documents the public kernel contract.
+ *
+ * Current surface (Phase 1.1):
+ * - handleGovernRequest: the pure semantic convenience handler (direct JSON in/out)
+ * - getGovernanceService: the underlying singleton (for advanced / in-process use)
+ * - Governance types
+ * - MetamorphosisEngine interface (for PostProcessor lifecycle integration)
+ *
+ * MCP remains the canonical standard surface (see governance.server.ts).
+ * The direct HTTP adapter (govern-http.ts) is a convenience on top of this kernel.
+ *
+ * Anti-goals (for this file):
+ * - No new business logic
+ * - No side effects on import
+ * - Does not pull in the full 25 knowledge-skill servers (dynamic via pluginRegistry only)
+ */
+import type { GovernOptions, GovernanceContext, GovernanceRequest, GovernanceResponse } from '../governance/governance-types.js';
+import { handleGovernRequest } from './govern-http.js';
+export { handleGovernRequest };
+export type { GovernHTTPConfig } from './govern-http.js';
+export { getGovernanceService } from '../governance/governance-service.js';
+export type { GovernanceRequest, GovernanceResponse, GovernanceProposal, GovernanceVote, GovernanceResult, GovernanceContext, GovernOptions, ProposalType, } from '../governance/governance-types.js';
+export type { MetamorphosisEngine, MetamorphosisProposal, } from '../types/metamorphosis.js';
+export { GovernHTTPAdapter } from './govern-http.js';
+export { pluginRegistry } from './plugin-registry.js';
+export type { SkillPlugin, SkillToolPlugin, SkillProposalArgs, SkillPluginResult } from './plugin-registry.js';
+/**
+ * High-level kernel description for introspection / docs.
+ */
+export declare const NUCLEUS_VERSION = "0.1.0";
+export declare const NUCLEUS_DESCRIPTION: string;
+/**
+ * Quick helper for the common case: govern a single proposal and get the overall decision.
+ * (Thin wrapper — real power users should use handleGovernRequest directly for batch + full response.)
+ */
+export declare function governSingle(proposal: Omit<GovernanceRequest['proposals'][0], 'id'> & {
+    id?: string;
+}, context?: GovernanceContext, options?: GovernOptions): Promise<GovernanceResponse>;

package/dist/nucleus/plugin-registry.d.ts

@@ -0,0 +1,132 @@
+/**
+ * PluginRegistry — Phase 1.2 dynamic skill loading + Phase 3 generic tool dispatch
+ *
+ * Allows skills to be registered after boot, loaded from config, or discovered
+ * at runtime. Wraps the existing in-process-skill-registry for backward compat.
+ *
+ * Phase 3 extension: SkillToolPlugin interface for multi-tool skills (knowledge-skill
+ * servers). Each server registers as a SkillToolPlugin, exposing arbitrary tools
+ * that can be dispatched via callSkillTool().
+ *
+ * Goals:
+ * - New skills can be registered post-boot via register()
+ * - Skills are discoverable by name without importing server constructors
+ * - Default set loads automatically from the existing 3 governance skills
+ * - Multi-tool skills can be registered and dispatched via callSkillTool()
+ * - Backward compatible: callInProcessSkill still works as before
+ */
+export interface SkillPlugin {
+    /** Unique skill name (e.g. "code-review", "security-audit") */
+    name: string;
+    /** Handler that processes proposals */
+    analyzeProposal(args: SkillProposalArgs): Promise<SkillPluginResult>;
+}
+/**
+ * Metadata describing a tool exposed by a SkillToolPlugin.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * Extended plugin interface for knowledge-skill servers that expose multiple tools.
+ * Each tool is a named function that accepts arbitrary args.
+ */
+export interface SkillToolPlugin {
+    /** Unique skill name (e.g. "code-review", "api-design") */
+    name: string;
+    /** Dispatch a named tool with arbitrary args */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Optional: list tool definitions for dynamic discovery */
+    listTools?(): ToolDefinition[];
+}
+export interface SkillProposalArgs {
+    proposalTitle?: string;
+    proposalDescription?: string;
+    evidence?: string[];
+    proposalType?: string;
+}
+export interface SkillPluginResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+type SkillHandler = (args: SkillProposalArgs) => Promise<SkillPluginResult>;
+declare class PluginRegistryImpl {
+    private skills;
+    /** Phase 3: multi-tool skill plugins (knowledge-skill servers) */
+    private toolPlugins;
+    private initialized;
+    /**
+     * Register a skill plugin. Can be called after boot.
+     */
+    register(skill: SkillPlugin): void;
+    /**
+     * Register a multi-tool skill plugin (knowledge-skill server).
+     * Tools can be dispatched via callSkillTool().
+     */
+    registerToolPlugin(skill: SkillToolPlugin): void;
+    /**
+     * Call a named tool on a registered multi-tool skill plugin.
+     */
+    callSkillTool(skillName: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Check if a tool plugin is registered.
+     */
+    hasToolPlugin(name: string): boolean;
+    /**
+     * List all registered tool plugin names.
+     */
+    listToolPlugins(): string[];
+    /**
+     * Get a registered tool plugin by name for introspection.
+     */
+    getToolPlugin(name: string): SkillToolPlugin | undefined;
+    /**
+     * List tool definitions for a registered tool plugin.
+     * Returns empty array if plugin not found or does not expose listTools().
+     */
+    listSkillTools(skillName: string): ToolDefinition[];
+    /**
+     * Convenience: register a server as a SkillToolPlugin.
+     * Wraps a server with named tools into the SkillToolPlugin interface.
+     */
+    registerServer(server: {
+        name: string;
+        tools: ToolDefinition[];
+        callTool: (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+    }): void;
+    /**
+     * Get a skill handler by name. Falls back to the in-process registry
+     * for the built-in governance skills (code-review, security-audit, researcher).
+     */
+    get(name: string): SkillHandler | undefined;
+    /**
+     * Check if a skill is registered (either in the plugin registry or the built-in registry).
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered skill names (plugins + built-in).
+     */
+    list(): string[];
+    /**
+     * Call a skill by name. Delegates to the plugin registry first,
+     * then falls back to the built-in in-process registry.
+     */
+    callSkill(name: string, args: SkillProposalArgs): Promise<SkillPluginResult>;
+    /**
+     * Initialize with default governance skills. Called once at boot.
+     * The 3 governance skills are always available via the built-in registry.
+     */
+    initializeDefaults(): void;
+    /**
+     * Reset the registry for testing. Removes all registered plugins
+     * (built-in governance skills remain available via fallback).
+     */
+    resetForTest(): void;
+}
+/** Singleton plugin registry */
+export declare const pluginRegistry: PluginRegistryImpl;
+export {};

package/dist/nucleus/thin-dispatch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * xray Nucleus — thinDispatch (Phase 1E)
+ *
+ * Stable nucleus surface for complexity scoring and agent routing.
+ * Wraps ComplexityAnalyzer; delegates routing to complexity-core utilities.
+ *
+ * Import from here or from delegation/index.ts (which re-exports these).
+ */
+import { ComplexityMetrics, ComplexityScore, ComplexityLevel, ComplexityThresholds } from "../delegation/complexity-core.js";
+export type { ComplexityMetrics, ComplexityScore, ComplexityLevel, ComplexityThresholds };
+export declare const NUCLEUS_THIN_DISPATCH_VERSION = "0.1.0";
+/**
+ * Score the complexity of an operation given its description and context.
+ * Primary entry point for thinDispatch complexity scoring in the nucleus.
+ */
+export declare function scoreComplexity(operation: string, context: unknown, thresholds?: ComplexityThresholds): ComplexityScore;
+/**
+ * Route a complexity score / level to the appropriate agent type.
+ * Uses core complexity-core mappings (tier → agent).
+ */
+export declare function routeToAgent(scoreOrLevel: number | ComplexityScore, level?: ComplexityLevel): string;
+/**
+ * Convenience: score first, then route — one call.
+ */
+export declare function scoreAndRoute(operation: string, context: unknown, thresholds?: ComplexityThresholds): {
+    score: ComplexityScore;
+    agent: string;
+    memoryRouting?: {
+        providerId: string;
+        adjustedScore: number;
+        signals: string[];
+    };
+};

package/dist/orchestrator/agent-spawn-governor.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Agent Spawn Governor
+ *
+ * Critical governance component that prevents infinite agent spawning
+ * and enforces spawn limits across the multi-agent orchestration system.
+ *
+ * @since 2026-01-23
+ */
+export interface SpawnContext {
+    agentType: string;
+    parentAgent?: string;
+    operation?: string;
+    triggeredBy?: string;
+    sessionId?: string;
+    priority?: "high" | "medium" | "low";
+}
+export interface SpawnRecord {
+    id: string;
+    agentType: string;
+    parentAgent?: string | undefined;
+    timestamp: number;
+    status: "active" | "completed" | "failed" | "terminated";
+    context: SpawnContext;
+}
+export interface SpawnLimits {
+    perAgentType: Record<string, number>;
+    totalConcurrent: number;
+    spawnRateLimit: {
+        maxPerMinute: number;
+        windowMs: number;
+    };
+    memoryLimit: {
+        maxMemoryMB: number;
+        emergencyThresholdMB: number;
+        cleanupIntervalMs: number;
+    };
+}
+export interface SpawnAuthorization {
+    authorized: boolean;
+    trackingId?: string;
+    reason?: string;
+    warnings?: string[];
+}
+export declare class AgentSpawnGovernor {
+    private limits;
+    private activeAgents;
+    private spawnHistory;
+    private readonly maxHistorySize;
+    private readonly cleanupInterval;
+    private readonly persistenceTimeout;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private cleanupTimer?;
+    private memoryMonitorInterval?;
+    private authorizationQueue;
+    private isProcessingAuthorization;
+    private getDefaultLimits;
+    private readonly defaultLimits;
+    constructor(limits?: Partial<SpawnLimits>, autoStart?: boolean);
+    private startPeriodicCleanup;
+    private startMemoryMonitoring;
+    private checkMemoryBudget;
+    private emergencyMemoryCleanup;
+    private aggressiveCleanup;
+    private deepCleanupContexts;
+    private sanitizeContext;
+    /**
+     * Authorize a new agent spawn
+     */
+    authorizeSpawn(context: SpawnContext): Promise<SpawnAuthorization>;
+    private processNextAuthorization;
+    private performAuthorization;
+    private checkAgentLimitsWithRetry;
+    private getTotalActiveWithRetry;
+    private registerSpawnWithRetry;
+    private handleAuthorizationError;
+    private categorizeError;
+    private emergencyCleanup;
+    /**
+     * Complete an agent spawn (mark as completed)
+     */
+    completeSpawn(trackingId: string, result?: boolean): Promise<void>;
+    /**
+     * Fail an agent spawn
+     */
+    failSpawn(trackingId: string, error?: Error): Promise<void>;
+    /**
+     * Terminate an agent spawn (force stop)
+     */
+    terminateSpawn(trackingId: string, reason?: string): Promise<void>;
+    /**
+     * Get current active count for agent type
+     */
+    getActiveCount(agentType: string): number;
+    /**
+     * Get total active agents system-wide
+     */
+    getTotalActive(): number;
+    /**
+     * Get spawn statistics
+     */
+    getSpawnStats(): {
+        perAgentType: Record<string, {
+            active: number;
+            total: number;
+        }>;
+        totalActive: number;
+        totalHistory: number;
+    };
+    /**
+     * Emergency: Terminate all active agents
+     */
+    emergencyShutdown(reason?: string): Promise<void>;
+    private registerSpawn;
+    private checkSpawnRateLimit;
+    private detectInfiniteSpawn;
+    private getRecentSpawns;
+    private findRecord;
+    private generateTrackingId;
+    private cleanupOldRecords;
+    private withTimeout;
+    private withRetry;
+    start(): void;
+    destroy(): void;
+}
+export declare const agentSpawnGovernor: AgentSpawnGovernor;

package/dist/orchestrator/enhanced-multi-agent-orchestrator.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Enhanced Multi-Agent Orchestration with Clickable Monitoring
+ * Integrates subagent spawning visibility and lifecycle management
+ */
+import { XrayStateManager } from "../state/state-manager.js";
+export interface AgentSpawnRequest {
+    agentType: string;
+    task: string;
+    context?: Record<string, unknown>;
+    priority?: "low" | "medium" | "high" | "critical";
+    timeout?: number;
+    dependencies?: string[];
+}
+export interface AgentExecutionResult {
+    success: boolean;
+    agentType: string;
+    task: string;
+    executionTime?: number;
+    complexity?: number;
+    result?: unknown;
+    delegationResult?: unknown;
+}
+export interface SpawnedAgent {
+    id: string;
+    agentType: string;
+    task: string;
+    status: "spawning" | "active" | "completed" | "failed" | "cancelled";
+    startTime: number;
+    endTime?: number;
+    result?: AgentExecutionResult;
+    error?: string;
+    progress: number;
+    clickable: boolean;
+    monitorable: boolean;
+    cleanupRequired: boolean;
+    spawnTrackingId: string | undefined;
+}
+export interface AgentOrchestrationState {
+    activeAgents: Map<string, SpawnedAgent>;
+    pendingSpawns: AgentSpawnRequest[];
+    completedAgents: Map<string, SpawnedAgent>;
+    failedAgents: Map<string, SpawnedAgent>;
+    agentDependencies: Map<string, string[]>;
+    monitoringEnabled: boolean;
+    cleanupInterval: number;
+    isMainOrchestrator: boolean;
+}
+export interface ExecutionContext {
+    isExecutingAsSubagent: boolean;
+    currentAgentId: string | null;
+    spawnStack: string[];
+}
+export interface OrchestrationDelegationRequest {
+    operation: string;
+    description: string;
+    context?: Record<string, unknown>;
+}
+export interface OrchestrationDelegationResult {
+    success: boolean;
+    results?: Array<{
+        agent: string;
+        output: unknown;
+        executionTime: number;
+    }>;
+    totalTime: number;
+    errors?: string[];
+    agents?: string[];
+}
+export declare class EnhancedMultiAgentOrchestrator {
+    private state;
+    private stateManager;
+    private complexityAnalyzer;
+    private agentDelegator;
+    private executionContext;
+    private cleanupTimer;
+    constructor(stateManager?: XrayStateManager, isMainOrchestrator?: boolean);
+    /**
+     * 🚨 SECURITY: Check if currently executing as a subagent
+     * Prevents subagents from spawning other subagents (infinite loops, resource exhaustion)
+     */
+    private isCurrentlyExecutingAsSubagent;
+    /**
+     * Enhanced agent spawning with clickable monitoring integration
+     */
+    spawnAgent(request: AgentSpawnRequest): Promise<SpawnedAgent>;
+    /**
+     * Execute agent with monitoring and cleanup
+     */
+    private executeAgent;
+    /**
+     * Execute agent using the agent delegator system
+     */
+    private executeAgentWithDelegator;
+    /**
+     * Simulate agent execution (FALLBACK - used when plugin not loaded)
+     *
+     * NOTE: The primary execution path is through the OpenCode plugin:
+     * - .opencode/plugin/xray-codex-injection.js intercepts prompts
+     * - Routes to agents via .opencode/agents/*.yml configs
+     * - OpenCode spawns actual agent processes
+     * - Hermes Agent handles MCP server execution
+     *
+     * This simulation is a fallback for:
+     * - Testing without real agent execution
+     * - When plugin fails to load
+     * - Documentation of what the framework orchestrates
+     *
+     * For production use, ensure the plugin is loaded in OpenCode.
+     */
+    private simulateAgentExecution;
+    /**
+     * Get estimated execution time for agent type
+     */
+    private getAgentExecutionTime;
+    /**
+     * Update agent monitoring (integrates with clickable interface)
+     */
+    private updateAgentMonitoring;
+    /**
+     * Check for pending spawns that can now execute
+     */
+    private checkPendingSpawns;
+    /**
+     * Get clickable agent monitoring interface
+     */
+    getMonitoringInterface(): Record<string, SpawnedAgent>;
+    /**
+     * Cancel agent execution
+     */
+    cancelAgent(agentId: string): Promise<boolean>;
+    /**
+     * Initialize cleanup system for completed agents
+     */
+    private initializeCleanupSystem;
+    /**
+     * Perform cleanup of completed/failed agents
+     */
+    private performCleanup;
+    /**
+     * Get orchestration statistics
+     */
+    getStatistics(): {
+        activeAgents: number;
+        completedAgents: number;
+        failedAgents: number;
+        pendingSpawns: number;
+        totalSpawned: number;
+    };
+    /**
+     * Shutdown orchestration system
+     */
+    shutdown(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export declare const enhancedMultiAgentOrchestrator: EnhancedMultiAgentOrchestrator;

package/dist/orchestrator/intelligent-commit-batcher.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Intelligent Commit Batcher - Batches related changes for optimal commit history
+ * Implements configurable thresholds for file count, time windows, and risk levels
+ *
+ * Configuration is read from .xray/features.json -> commit_cycle
+ */
+export interface PendingChange {
+    filePath: string;
+    operation: string;
+    changeType: string;
+    riskLevel: "low" | "medium" | "high" | "critical";
+    linesChanged: number;
+    timestamp: number;
+    relatedFiles?: string[];
+    commitMessage?: string;
+    author?: string;
+}
+export interface CommitBatchingConfig {
+    maxFilesPerCommit: number;
+    minFilesPerCommit: number;
+    maxTimeBetweenCommits: number;
+    minTimeBetweenCommits: number;
+    forceCommitAfter: number;
+    batchRelatedOperations: boolean;
+    maxOperationsPerBatch: number;
+    batchLowRiskChanges: boolean;
+    separateHighRiskChanges: boolean;
+    batchByComponent: boolean;
+    maxComponentsPerCommit: number;
+    autoCommit: boolean;
+    generateCommitMessages: boolean;
+    amendLastCommit: boolean;
+}
+export interface BatchMetrics {
+    fileCount: number;
+    operationCount: number;
+    componentCount: number;
+    totalLinesChanged: number;
+    timeSinceLastCommit: number;
+    averageRiskLevel: number;
+    oldestChangeTime: number;
+    newestChangeTime: number;
+}
+export declare class IntelligentCommitBatcher {
+    private pendingChanges;
+    private lastCommitTime;
+    private config;
+    constructor(config?: Partial<CommitBatchingConfig>);
+    private loadFeaturesConfig;
+    /**
+     * Add a change to the pending batch
+     */
+    addChange(change: PendingChange): boolean;
+    /**
+     * Add multiple changes to the batch
+     */
+    addChanges(changes: PendingChange[]): boolean;
+    /**
+     * Check if the current batch should be committed
+     */
+    shouldCommitBatch(): boolean;
+    /**
+     * Commit the current batch of changes
+     */
+    commitBatch(commitMessage?: string): Promise<boolean>;
+    /**
+     * Force commit current batch regardless of thresholds
+     */
+    forceCommitBatch(commitMessage?: string): Promise<boolean>;
+    /**
+     * Get current batch status and metrics
+     */
+    getBatchStatus(): {
+        pendingChanges: number;
+        metrics: BatchMetrics;
+        shouldCommit: boolean;
+        estimatedCommitMessage: string;
+    };
+    /**
+     * Calculate metrics for the current batch
+     */
+    private calculateBatchMetrics;
+    /**
+     * Check if batch has mixed risk levels that should be separated
+     */
+    private hasMixedRiskLevels;
+    /**
+     * Generate intelligent commit message
+     */
+    private generateCommitMessage;
+    /**
+     * Get files that should be staged for this commit
+     */
+    private getFilesToStage;
+    /**
+     * Stage files for commit
+     */
+    private stageFiles;
+    /**
+     * Perform the actual git commit
+     */
+    private performGitCommit;
+    /**
+     * Get summary of operations in this batch
+     */
+    private getOperationSummary;
+    private riskLevelToNumber;
+    private detectComponent;
+    private extractComponentName;
+    private getPrimaryOperation;
+    private getActionVerb;
+}
+export declare const createIntelligentCommitBatcher: (config?: Partial<CommitBatchingConfig>) => IntelligentCommitBatcher;
+export declare const intelligentCommitBatcher: IntelligentCommitBatcher;