0xray 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 0xRay Framework - Main Entry Point
+ *
+ * This is the main entry point for the 0xRay framework.
+ * It exports the core initialization function and key components.
+ */
+export { StringRayOrchestrator } from "./orchestrator/orchestrator.js";
+export { StringRayStateManager } from "./state/index.js";
+export { AgentDelegator } from "./delegation/index.js";
+export { frameworkLogger } from "./core/framework-logger.js";
+export { BUILTIN_CODEX } from "./core/codex-formatter.js";
+import { defaultStringRayConfig } from "./core/index.js";
+export { defaultStringRayConfig };
+export { OpenClawIntegration, initializeOpenClawIntegration, getOpenClawIntegration, shutdownOpenClawIntegration } from "./integrations/openclaw/index.js";
+export type { OpenClawIntegrationConfig } from "./integrations/openclaw/types.js";
+export declare function initializeStringRay(config?: {}): {
+    success: boolean;
+    config: {
+        enableOrchestrator: boolean;
+        enableBootOrchestrator: boolean;
+        enableStateManagement: boolean;
+        enableHooks: boolean;
+        enableCodexInjection: boolean;
+        enableProcessors: boolean;
+        enablePostProcessor: boolean;
+    };
+    message: string;
+};

package/dist/inference/deploy-verifier.d.ts

@@ -0,0 +1,26 @@
+export interface DeployVerificationResult {
+    success: boolean;
+    packageVersion: string;
+    tarballPath: string;
+    installDir: string;
+    checks: DeployCheck[];
+    duration: number;
+    timestamp: string;
+}
+export interface DeployCheck {
+    name: string;
+    passed: boolean;
+    output: string;
+    duration: number;
+}
+export declare class DeployVerifier {
+    private projectRoot;
+    constructor(projectRoot?: string);
+    verify(): DeployVerificationResult;
+    quickVerify(): DeployVerificationResult;
+    private runCheck;
+    private exec;
+    private readPackageJson;
+    private cleanup;
+    private result;
+}

package/dist/inference/index.d.ts

@@ -0,0 +1,10 @@
+export { analyzeStructuralPatterns } from "./semantic-patterns.js";
+export type { StructuralPattern } from "./semantic-patterns.js";
+export { captureSessionInference, saveSessionInference, } from "./session-capture.js";
+export type { SessionInference, ReasoningLink, SessionMetrics, } from "./session-capture.js";
+export { shouldTriggerCycle, accumulateCorpus } from "./inference-accumulator.js";
+export type { InferenceCorpus, RecurringPattern, RecurringProblem } from "./inference-accumulator.js";
+export { InferenceCycle } from "./inference-cycle.js";
+export type { InferenceProposal, InferenceCycleResult, CyclePhase } from "./inference-cycle.js";
+export { DeployVerifier } from "./deploy-verifier.js";
+export type { DeployVerificationResult, DeployCheck } from "./deploy-verifier.js";

package/dist/inference/inference-accumulator.d.ts

@@ -0,0 +1,29 @@
+import { SessionInference } from "./session-capture.js";
+export interface InferenceCorpus {
+    sessions: SessionInference[];
+    totalCommits: number;
+    recurringPatterns: RecurringPattern[];
+    recurringProblems: RecurringProblem[];
+    uniqueApproaches: string[];
+    allWrongTurns: string[];
+    collectedAt: string;
+}
+export interface RecurringPattern {
+    name: string;
+    occurrences: number;
+    avgConfidence: number;
+    sessions: string[];
+    evidence: string[];
+    description: string;
+}
+export interface RecurringProblem {
+    pattern: string;
+    occurrences: number;
+    sessions: string[];
+}
+export declare function shouldTriggerCycle(inferenceDir: string, lastCycleFile: string): {
+    trigger: boolean;
+    reason: string;
+};
+export declare function accumulateCorpus(inferenceDir: string): InferenceCorpus;
+export declare function loadSessionInferences(dir: string): SessionInference[];

package/dist/inference/inference-cycle.d.ts

@@ -0,0 +1,110 @@
+import { DeployVerificationResult } from "./deploy-verifier.js";
+export interface InferenceProposal {
+    id: string;
+    type: "fix" | "refactor" | "automate" | "guard" | "codify";
+    title: string;
+    description: string;
+    evidence: string[];
+    confidence: number;
+    source: "recurring_problem" | "recurring_pattern" | "wrong_turn";
+    status: "pending" | "approved" | "rejected" | "applied" | "failed";
+}
+export interface InferenceCycleResult {
+    cycleId: string;
+    triggered: boolean;
+    triggerReason: string;
+    corpusSummary: {
+        sessions: number;
+        totalCommits: number;
+        recurringPatterns: number;
+        recurringProblems: number;
+    };
+    proposals: InferenceProposal[];
+    votes: {
+        proposalId: string;
+        decision: string;
+        confidence: number;
+        details: string[];
+    }[];
+    deployVerification?: DeployVerificationResult | undefined;
+    phase: CyclePhase;
+    completedAt: string;
+    duration: number;
+}
+export type CyclePhase = "idle" | "collecting" | "proposing" | "governing" | "applying" | "deploying" | "verifying" | "complete" | "failed";
+export type AgentInvoker = (agentName: string, prompt: string) => Promise<string>;
+export interface InferenceCycleOptions {
+    skipDeployVerify?: boolean;
+    skipApply?: boolean;
+    skipResearcherReview?: boolean;
+    force?: boolean;
+}
+export declare class InferenceCycle {
+    private static instances;
+    private static reEntryLock;
+    private static governedProposalIds;
+    private static votingCoordinator;
+    static getInstance(projectRoot?: string, options?: InferenceCycleOptions): InferenceCycle;
+    static resetInstance(): void;
+    private inferenceDir;
+    private stateDir;
+    private projectRoot;
+    private phase;
+    private opencodeAvailable;
+    private agentInvoker;
+    private options;
+    constructor(projectRoot?: string, agentInvoker?: AgentInvoker, options?: InferenceCycleOptions);
+    governExternalProposals(proposals: InferenceProposal[]): Promise<InferenceCycleResult>;
+    maybeRunCycle(): Promise<InferenceCycleResult>;
+    private generateProposals;
+    private adjustFromHistory;
+    private getCoordinator;
+    private applyProposals;
+    private applyProposalWork;
+    private applyCodeChange;
+    private applyGuard;
+    private applyAutomation;
+    private extractTargetFiles;
+    private researcherReview;
+    private governProposals;
+    private isGovernanceMcpPreferred;
+    private parseGovernanceMcpResponse;
+    /**
+     * Oscillator 1: Internal VotingCoordinator-based governance
+     */
+    private governProposalsInternal;
+    /**
+     * Pure individual knowledge-skill MCP path for governance.
+     * Used when STRRAY_FORCE_MCP_GOVERNANCE=true.
+     * Each proposal is evaluated directly by the relevant skill servers using analyze_proposal.
+     */
+    private governProposalsWithIndividualSkills;
+    /**
+     * Merge internal and external governance votes.
+     * A proposal passes both oscillators — must be approved by internal AND external.
+     */
+    private mergeGovernanceVotes;
+    /**
+     * Govern proposals using external chrono-warp-drive Dynamo endpoint
+     */
+    private governProposalsExternal;
+    private invokeAgentInternal;
+    private invokeViaOpencode;
+    private parseSubagentVotes;
+    private getGovernanceStateManager;
+    private saveGovernanceState;
+    private extractTextFromNdjson;
+    private resolveOpencodeRoot;
+    private rejectNoQuorum;
+    private classifyProposalType;
+    private patternToProposalType;
+    private generateTitle;
+    private setPhase;
+    getPhase(): CyclePhase;
+    private saveCycleState;
+    private appendHistory;
+    private loadHistory;
+    private adjustConfidenceFromHistory;
+    private buildBlockedResult;
+    private buildResult;
+}

package/dist/inference/semantic-patterns.d.ts

@@ -0,0 +1,7 @@
+export interface StructuralPattern {
+    name: string;
+    confidence: number;
+    evidence: string[];
+    description: string;
+}
+export declare function analyzeStructuralPatterns(fromRef: string, toRef: string): StructuralPattern[];

package/dist/inference/session-capture.d.ts

@@ -0,0 +1,32 @@
+import { StructuralPattern } from "./semantic-patterns.js";
+export interface SessionInference {
+    sessionId: string;
+    timestamp: string;
+    span: {
+        from: string;
+        to: string;
+    };
+    problems: string[];
+    approaches: string[];
+    wrongTurns: string[];
+    solutions: string[];
+    reasoningChain: ReasoningLink[];
+    patterns: StructuralPattern[];
+    metrics: SessionMetrics;
+}
+export interface ReasoningLink {
+    from: string;
+    to: string;
+    reasoning: string;
+}
+export interface SessionMetrics {
+    commits: number;
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+    filesAdded: number;
+    filesDeleted: number;
+    uniqueDirs: number;
+}
+export declare function captureSessionInference(fromRef: string, toRef: string): SessionInference | null;
+export declare function saveSessionInference(inference: SessionInference, outputDir?: string): string;

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

@@ -0,0 +1,47 @@
+/**
+ * Example Integration - Demonstrates using the BaseIntegration class
+ *
+ * This is a simple example showing how to create a custom integration
+ * that extends the BaseIntegration class.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import { BaseIntegration, type HealthResult, type IntegrationConfig } from "./index.js";
+/**
+ * Example custom integration
+ *
+ * Demonstrates how to extend BaseIntegration with custom logic.
+ */
+declare class ExampleIntegration extends BaseIntegration {
+    /** Custom property for this integration */
+    private connectionString;
+    private connected;
+    /**
+     * Create a new ExampleIntegration
+     *
+     * @param config - Optional configuration
+     */
+    constructor(config?: Partial<IntegrationConfig>);
+    /**
+     * Set connection string
+     */
+    setConnectionString(connStr: string): void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Perform integration-specific initialization
+     */
+    protected performInitialization(): Promise<void>;
+    /**
+     * Perform integration-specific shutdown
+     */
+    protected performShutdown(): Promise<void>;
+    /**
+     * Perform integration-specific health check
+     */
+    protected performHealthCheck(): Promise<HealthResult>;
+}
+export { ExampleIntegration };

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

@@ -0,0 +1,267 @@
+/**
+ * Base Integration Class
+ *
+ * Abstract base class providing common lifecycle management, event emission,
+ * configuration handling, and logging for all 0xRay integrations.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import { EventEmitter } from "events";
+import type { LogStatus } from "../../core/framework-logger.js";
+import { type IntegrationConfig, type IntegrationStatus, type IntegrationStats, type HealthResult, type IntegrationEvent, type IntegrationEventType, type IIntegration, type IEventedIntegration, type LogLevel } from "./types.js";
+/**
+ * Abstract base class for all 0xRay integrations
+ *
+ * Provides:
+ * - Lifecycle management (initialize/shutdown)
+ * - Configuration handling with defaults
+ * - Event emission for integration events
+ * - Common statistics tracking (uptime, errors)
+ * - Logging integration with framework logger
+ *
+ * @example
+ * ```typescript
+ * class MyIntegration extends BaseIntegration {
+ *   constructor() {
+ *     super('my-integration', '1.0.0');
+ *   }
+ *
+ *   protected async performInitialization(): Promise<void> {
+ *     // Custom initialization logic
+ *   }
+ *
+ *   protected async performShutdown(): Promise<void> {
+ *     // Custom cleanup logic
+ *   }
+ *
+ *   protected async performHealthCheck(): Promise<HealthResult> {
+ *     return { healthy: true, message: 'OK' };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseIntegration extends EventEmitter implements IIntegration, IEventedIntegration {
+    /** Unique name of the integration */
+    readonly name: string;
+    /** Version of the integration */
+    readonly version: string;
+    /** Current lifecycle status */
+    protected _status: IntegrationStatus;
+    /** Current configuration */
+    protected config: IntegrationConfig;
+    /** Statistics tracking */
+    protected stats: IntegrationStats;
+    /** Start time for uptime calculation */
+    protected startTime: number;
+    /** Job ID for current operation */
+    protected jobId: string;
+    /**
+     * Create a new base integration
+     *
+     * @param name - Unique name for this integration
+     * @param version - Version string
+     * @param initialConfig - Optional initial configuration
+     */
+    constructor(name: string, version: string, initialConfig?: Partial<IntegrationConfig>);
+    /**
+     * Get current integration status (readonly accessor)
+     */
+    get status(): IntegrationStatus;
+    /**
+     * Initialize the integration
+     *
+     * Calls performInitialization() after setting up the base state.
+     * Handles errors and emits appropriate events.
+     *
+     * @param config - Optional partial configuration to merge
+     */
+    initialize(config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Gracefully shutdown the integration
+     *
+     * Calls performShutdown() to clean up resources.
+     *
+     * @example
+     * ```typescript
+     * // Using await
+     * await integration.shutdown();
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Perform a health check
+     *
+     * Default implementation checks status and calls performHealthCheck().
+     * Subclasses should override performHealthCheck() for custom checks.
+     *
+     * @returns Health result indicating integration health
+     *
+     * @example
+     * ```typescript
+     * const health = await integration.healthCheck();
+     * if (!health.healthy) {
+     *   console.error('Integration unhealthy:', health.message);
+     * }
+     * ```
+     */
+    healthCheck(): Promise<HealthResult>;
+    /**
+     * Get current integration statistics
+     *
+     * Calculates uptime since initialization and includes error count.
+     *
+     * @returns Current stats object
+     *
+     * @example
+     * ```typescript
+     * const stats = integration.getStats();
+     * console.log(`Uptime: ${stats.uptime}ms, Errors: ${stats.errors}`);
+     * ```
+     */
+    getStats(): IntegrationStats;
+    /**
+     * Get the event emitter for this integration
+     *
+     * Returns `this` since BaseIntegration extends EventEmitter.
+     *
+     * @returns The event emitter instance
+     */
+    getEventEmitter(): EventEmitter;
+    /**
+     * Ensure the integration is initialized
+     *
+     * @throws IntegrationNotInitializedError if not initialized
+     */
+    protected ensureInitialized(): void;
+    /**
+     * Record an error in statistics
+     *
+     * @param error - Optional error to record
+     */
+    protected recordError(error?: Error): void;
+    /**
+     * Update custom statistics
+     *
+     * @param customStats - Partial stats to merge
+     */
+    protected updateCustomStats(customStats: Record<string, unknown>): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Current configuration object (copy)
+     */
+    protected getConfig(): IntegrationConfig;
+    /**
+     * Update configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    protected updateConfig(config: Partial<IntegrationConfig>): void;
+    /**
+     * Log a message using the framework logger
+     *
+     * @param status - Log status level
+     * @param message - Message to log
+     * @param details - Optional details object
+     */
+    protected log(status: LogStatus, message: string, details?: Record<string, unknown>): Promise<void>;
+    /**
+     * Emit a typed integration event
+     *
+     * @param type - Event type
+     * @param data - Event data
+     * @param error - Optional error
+     */
+    protected emitEvent(type: IntegrationEventType, data?: Record<string, unknown>, error?: Error): void;
+    /**
+     * Perform integration-specific initialization
+     *
+     * Called during initialize() after base setup.
+     * Subclasses should implement custom initialization logic here.
+     *
+     * @example
+     * ```typescript
+     * protected async performInitialization(): Promise<void> {
+     *   // Connect to external service
+     *   await this.connect();
+     *
+     *   // Setup event handlers
+     *   this.on('data', this.handleData);
+     * }
+     * ```
+     */
+    protected abstract performInitialization(): Promise<void>;
+    /**
+     * Perform integration-specific shutdown
+     *
+     * Called during shutdown() for cleanup.
+     * Subclasses should implement cleanup logic here.
+     *
+     * @example
+     * ```typescript
+     * protected async performShutdown(): Promise<void> {
+     *   // Remove event handlers
+     *   this.off('data', this.handleData);
+     *
+     *   // Close connections
+     *   await this.disconnect();
+     * }
+     * ```
+     */
+    protected abstract performShutdown(): Promise<void>;
+    /**
+     * Perform integration-specific health check
+     *
+     * Called by healthCheck() to determine integration health.
+     * Subclasses should implement custom health checks here.
+     *
+     * @returns Health result
+     *
+     * @example
+     * ```typescript
+     * protected async performHealthCheck(): Promise<HealthResult> {
+     *   const connected = await this.isConnected();
+     *
+     *   if (connected) {
+     *     return { healthy: true, message: 'Connection active' };
+     *   }
+     *
+     *   return { healthy: false, message: 'Not connected' };
+     * }
+     * ```
+     */
+    protected abstract performHealthCheck(): Promise<HealthResult>;
+    /**
+     * Check if an object is a BaseIntegration instance
+     *
+     * @param value - Value to check
+     * @returns True if value is a BaseIntegration
+     */
+    static isBaseIntegration(value: unknown): value is BaseIntegration;
+}
+/**
+ * Create a simple integration with minimal implementation
+ *
+ * Useful for testing or simple integrations that don't need much logic.
+ *
+ * @param name - Integration name
+ * @param version - Integration version
+ * @param healthCheck - Custom health check function
+ * @param shutdown - Custom shutdown function
+ * @returns New integration instance
+ *
+ * @example
+ * ```typescript
+ * const simple = createSimpleIntegration(
+ *   'simple',
+ *   '1.0.0',
+ *   async () => ({ healthy: true, message: 'OK' }),
+ *   async () => {}
+ * );
+ *
+ * await simple.initialize();
+ * ```
+ */
+export declare function createSimpleIntegration(name: string, version: string, healthCheck: () => Promise<HealthResult>, shutdown?: () => Promise<void>): BaseIntegration;
+export type { IntegrationConfig, IntegrationStatus, IntegrationStats, HealthResult, IntegrationEvent, IntegrationEventType, IIntegration, IEventedIntegration, LogLevel, };

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

@@ -0,0 +1,12 @@
+/**
+ * Integration Base Module
+ *
+ * Common interfaces and base class for 0xRay integrations.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+export * from "./types.js";
+export * from "./Integration.js";
+export * from "./registry.js";
+export * from "./ExampleIntegration.js";