opencode-swarm 7.0.0-beta.1 → 7.0.0

package/dist/background/circuit-breaker.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Circuit Breaker + Loop Protection Primitives
+ *
+ * Provides fault tolerance and infinite loop prevention for background automation.
+ */
+/** Circuit breaker states */
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time in ms to wait before attempting reset */
+    resetTimeoutMs: number;
+    /** Number of success calls needed to close from half-open */
+    successThreshold: number;
+    /** Timeout for individual calls (0 = no timeout) */
+    callTimeoutMs: number;
+}
+/** Circuit breaker events */
+export interface CircuitBreakerEvents {
+    opened: {
+        timestamp: number;
+        failureCount: number;
+    };
+    closed: {
+        timestamp: number;
+        successCount: number;
+    };
+    'half-open': {
+        timestamp: number;
+    };
+    callSuccess: {
+        duration: number;
+    };
+    callFailure: {
+        error: unknown;
+        duration: number;
+    };
+}
+export type CircuitBreakerEventType = keyof CircuitBreakerEvents;
+/**
+ * Circuit Breaker Implementation
+ *
+ * Prevents cascading failures by stopping requests when the circuit is open.
+ * States:
+ * - closed: Normal operation, requests pass through
+ * - open: Circuit is open, requests fail fast
+ * - half-open: Testing if service recovered
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime?;
+    private readonly config;
+    private readonly name;
+    private readonly onStateChange?;
+    constructor(name: string, config?: Partial<CircuitBreakerConfig>, onStateChange?: (eventType: string, event: unknown) => void);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Record a successful call
+     */
+    private recordSuccess;
+    /**
+     * Record a failed call
+     */
+    private recordFailure;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        state: CircuitBreakerState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime?: number;
+    };
+}
+/**
+ * Loop Protection for preventing infinite automation loops
+ *
+ * Tracks operation history and detects potential infinite loops.
+ */
+export interface LoopProtectionConfig {
+    /** Maximum times an operation can be attempted */
+    maxIterations: number;
+    /** Time window in ms to track iterations */
+    timeWindowMs: number;
+    /** Unique key for the operation being protected */
+    operationKey: string;
+}
+/**
+ * Loop Protection Implementation
+ *
+ * Prevents infinite loops by tracking operation frequency.
+ */
+export declare class LoopProtection {
+    private records;
+    private readonly config;
+    private readonly onLoopDetected?;
+    constructor(config: LoopProtectionConfig, onLoopDetected?: (key: string, count: number) => void);
+    /**
+     * Record an iteration attempt
+     * Returns false if max iterations exceeded
+     */
+    recordAttempt(key?: string): boolean;
+    /**
+     * Check if operation is allowed without recording
+     */
+    canProceed(key?: string): boolean;
+    /**
+     * Get remaining iterations allowed
+     */
+    getRemainingIterations(key?: string): number;
+    /**
+     * Reset tracking for an operation
+     */
+    reset(key?: string): void;
+    /**
+     * Reset all tracking
+     */
+    resetAll(): void;
+    /**
+     * Get current iteration count
+     */
+    getIterationCount(key?: string): number;
+    /**
+     * Get all operation keys being tracked
+     */
+    getTrackedOperations(): string[];
+}

package/dist/background/event-bus.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed Event Bus for Internal Automation Events
+ *
+ * Provides a type-safe event system for background automation.
+ * Events flow through the system without external dependencies.
+ */
+/** Automation event types */
+export type AutomationEventType = 'queue.item.enqueued' | 'queue.item.dequeued' | 'queue.item.completed' | 'queue.item.failed' | 'queue.item.retry scheduled' | 'worker.started' | 'worker.stopped' | 'worker.error' | 'circuit.breaker.opened' | 'circuit.breaker.half-open' | 'circuit.breaker.closed' | 'loop.protection.triggered' | 'automation.started' | 'automation.stopped' | 'preflight.requested' | 'preflight.triggered' | 'preflight.skipped' | 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed' | 'evidence.summary.generated' | 'evidence.summary.error' | 'curator.init.completed' | 'curator.init.llm_completed' | 'curator.init.llm_fallback' | 'curator.phase.completed' | 'curator.phase.llm_completed' | 'curator.phase.llm_fallback' | 'curator.drift.completed' | 'curator.error';
+/** Base automation event */
+export interface AutomationEvent<T = unknown> {
+    type: AutomationEventType;
+    timestamp: number;
+    payload: T;
+    source?: string;
+}
+/** Event listener type */
+export type EventListener<T = unknown> = (event: AutomationEvent<T>) => void | Promise<void>;
+/**
+ * Type-safe event bus for automation events
+ */
+export declare class AutomationEventBus {
+    private listeners;
+    private eventHistory;
+    private readonly maxHistorySize;
+    constructor(options?: {
+        maxHistorySize?: number;
+    });
+    /**
+     * Subscribe to an event type
+     */
+    subscribe<T>(type: AutomationEventType, listener: EventListener<T>): () => void;
+    /**
+     * Publish an event to all subscribers
+     */
+    publish<T>(type: AutomationEventType, payload: T, source?: string): Promise<void>;
+    /**
+     * Get recent event history
+     */
+    getHistory(types?: AutomationEventType[]): AutomationEvent[];
+    /**
+     * Clear event history
+     */
+    clearHistory(): void;
+    /**
+     * Get listener count for an event type
+     */
+    getListenerCount(type: AutomationEventType): number;
+    /**
+     * Check if any listeners exist for a type
+     */
+    hasListeners(type: AutomationEventType): boolean;
+}
+/**
+ * Get or create the global event bus instance
+ */
+export declare function getGlobalEventBus(): AutomationEventBus;
+/**
+ * Reset the global event bus (for testing)
+ */
+export declare function resetGlobalEventBus(): void;

package/dist/background/evidence-summary-integration.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Evidence Summary Background Integration
+ *
+ * Wires the evidence summary service to background automation:
+ * - Subscribes to preflight and phase boundary events
+ * - Generates evidence summaries automatically
+ * - Persists artifacts under .swarm/ for GUI consumption
+ * - Respects feature flags (evidence_auto_summaries) with default-off safety
+ */
+import type { AutomationConfig } from '../config/schema';
+import { type EvidenceSummaryArtifact } from '../services/evidence-summary-service';
+/** Evidence summary integration configuration */
+export interface EvidenceSummaryIntegrationConfig {
+    /** Automation configuration for feature flag gating */
+    automationConfig: AutomationConfig;
+    /** Directory to run evidence analysis in */
+    directory: string;
+    /** Project root directory for persisting summary artifacts under .swarm/ */
+    projectDir: string;
+    /** Filename for the summary artifact (default: evidence-summary.json) */
+    summaryFilename?: string;
+}
+/** Event types that can trigger evidence summary generation */
+export type EvidenceSummaryTriggerEvent = 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed';
+/** Payload for evidence summary trigger events */
+export interface EvidenceSummaryTriggerPayload {
+    trigger: EvidenceSummaryTriggerEvent;
+    phase: number;
+    reason: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Evidence Summary Integration
+ *
+ * Automatically generates and persists evidence summaries on relevant events.
+ */
+export declare class EvidenceSummaryIntegration {
+    private readonly config;
+    private readonly eventBus;
+    private unsubscribes;
+    constructor(config: EvidenceSummaryIntegrationConfig);
+    /**
+     * Check if auto-summaries are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Initialize the integration by subscribing to trigger events
+     * Only subscribes if enabled via feature flags
+     */
+    initialize(): void;
+    /**
+     * Subscribe to an event type
+     */
+    private subscribeToEvent;
+    /**
+     * Generate and persist evidence summary
+     */
+    generateSummary(phase: number, trigger: EvidenceSummaryTriggerEvent): Promise<EvidenceSummaryArtifact | null>;
+    /**
+     * Manually trigger summary generation (for CLI or testing)
+     */
+    triggerManual(phase?: number): Promise<EvidenceSummaryArtifact | null>;
+    /**
+     * Cleanup subscriptions
+     */
+    cleanup(): void;
+}
+/**
+ * Create evidence summary integration
+ *
+ * Factory function that creates and optionally initializes the integration.
+ */
+export declare function createEvidenceSummaryIntegration(config: EvidenceSummaryIntegrationConfig, autoInitialize?: boolean): EvidenceSummaryIntegration;

package/dist/background/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Background Automation Framework
+ *
+ * Provides infrastructure for v6.7 background-first automation:
+ * - Typed event bus for internal automation events
+ * - Lightweight in-process queue with priorities and retry metadata
+ * - Worker lifecycle manager (start/stop/register handlers)
+ * - Circuit breaker + loop protection primitives
+ * - Phase-boundary trigger detection and preflight request plumbing
+ * - Passive status artifact writer for GUI visibility
+ *
+ * Gated behind Task 5.2 automation feature flags and default-off behavior.
+ */
+export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerState, LoopProtection, } from './circuit-breaker';
+export { type AutomationEvent, AutomationEventBus, type AutomationEventType, } from './event-bus';
+export { createEvidenceSummaryIntegration, type EvidenceSummaryIntegrationConfig, type EvidenceSummaryTriggerEvent, type EvidenceSummaryTriggerPayload, } from './evidence-summary-integration';
+export { type AutomationFrameworkConfig, BackgroundAutomationManager, createAutomationManager, } from './manager';
+export { PlanSyncWorker, type PlanSyncWorkerOptions, type PlanSyncWorkerStatus, } from './plan-sync-worker';
+export { AutomationQueue, type QueueItem, type QueuePriority, type RetryMetadata, } from './queue';
+export { AutomationStatusArtifact, type AutomationStatusSnapshot, } from './status-artifact';
+export { type PhaseBoundaryResult, PhaseBoundaryTrigger, type PreflightHandler, type PreflightRequest, type PreflightRequestPayload, type PreflightTriggerConfig, type PreflightTriggerEventType, PreflightTriggerManager, } from './trigger';
+export { type WorkerHandler, WorkerManager, type WorkerRegistration, } from './worker';

package/dist/background/manager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Background Automation Manager
+ *
+ * Main entry point for the background automation framework.
+ * Handles feature flag gating and orchestrates all components.
+ */
+import type { AutomationConfig } from '../config/schema';
+import { CircuitBreaker, type CircuitBreakerConfig, LoopProtection, type LoopProtectionConfig } from './circuit-breaker';
+import { type AutomationEvent, type AutomationEventType } from './event-bus';
+import { AutomationQueue } from './queue';
+import { WorkerManager, type WorkerRegistration } from './worker';
+/** Framework configuration */
+export interface AutomationFrameworkConfig {
+    /** Enable/disable the entire framework */
+    enabled: boolean;
+    /** Max queue size */
+    maxQueueSize?: number;
+    /** Max retries for failed items */
+    maxRetries?: number;
+    /** Circuit breaker config */
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    /** Loop protection config */
+    loopProtection?: Partial<LoopProtectionConfig>;
+}
+/**
+ * Background Automation Manager
+ *
+ * Provides a unified interface for background automation with feature flag gating.
+ * All components are optional and only activated when enabled.
+ */
+export declare class BackgroundAutomationManager {
+    private readonly config;
+    private readonly eventBus;
+    private readonly workerManager;
+    private readonly queues;
+    private readonly circuitBreakers;
+    private readonly loopProtections;
+    private isInitialized;
+    private isRunning;
+    constructor(config: AutomationFrameworkConfig);
+    /**
+     * Initialize the automation framework
+     * Only performs work if enabled
+     */
+    initialize(): void;
+    /**
+     * Start the automation framework
+     */
+    start(): void;
+    /**
+     * Stop the automation framework
+     */
+    stop(): void;
+    /**
+     * Check if framework is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if framework is running
+     */
+    isActive(): boolean;
+    /**
+     * Create or get a named queue
+     */
+    getOrCreateQueue<T>(name: string): AutomationQueue<T>;
+    /**
+     * Register a worker with the framework
+     */
+    registerWorker(registration: WorkerRegistration): void;
+    /**
+     * Start a specific worker
+     */
+    startWorker(name: string): boolean;
+    /**
+     * Stop a specific worker
+     */
+    stopWorker(name: string): boolean;
+    /**
+     * Get or create a circuit breaker
+     */
+    getOrCreateCircuitBreaker(name: string): CircuitBreaker;
+    /**
+     * Get or create loop protection
+     */
+    getOrCreateLoopProtection(operationKey: string): LoopProtection;
+    /**
+     * Subscribe to automation events
+     */
+    subscribe<T>(type: AutomationEventType, listener: (event: AutomationEvent<T>) => void | Promise<void>): () => void;
+    /**
+     * Publish an event to the automation event bus
+     */
+    publish<T>(type: AutomationEventType, payload: T, source?: string): Promise<void>;
+    /**
+     * Get framework statistics
+     */
+    getStats(): {
+        enabled: boolean;
+        initialized: boolean;
+        running: boolean;
+        queues: Record<string, ReturnType<AutomationQueue['getStats']>>;
+        workers: Record<string, ReturnType<WorkerManager['getStats']>>;
+        circuitBreakers: Record<string, ReturnType<CircuitBreaker['getStats']>>;
+        loopProtections: string[];
+    };
+    /**
+     * Reset the framework (for testing)
+     */
+    reset(): void;
+}
+/**
+ * Get or create the global automation manager
+ */
+export declare function getAutomationManager(config?: AutomationFrameworkConfig): BackgroundAutomationManager;
+/**
+ * Initialize automation manager from plugin config
+ */
+export declare function createAutomationManager(automationConfig: AutomationConfig | undefined): BackgroundAutomationManager;
+/**
+ * Reset the global manager (for testing)
+ */
+export declare function resetAutomationManager(): void;

package/dist/background/plan-sync-worker.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Plan Sync Worker
+ *
+ * Watches .swarm/plan.json for changes and syncs plan.md accordingly.
+ * Uses fs.watch with polling fallback for cross-platform reliability.
+ */
+/** Configuration options for PlanSyncWorker */
+export interface PlanSyncWorkerOptions {
+    /** Directory containing .swarm folder (defaults to cwd) */
+    directory?: string;
+    /** Debounce delay in ms (default: 500ms) */
+    debounceMs?: number;
+    /** Polling interval in ms when fs.watch fails (default: 2000ms) */
+    pollIntervalMs?: number;
+    /** Sync operation timeout in ms (default: 30000ms) - prevents runaway hangs */
+    syncTimeoutMs?: number;
+    /** Called on sync completion (success or failure) */
+    onSyncComplete?: (success: boolean, error?: Error) => void;
+}
+/** Worker status */
+export type PlanSyncWorkerStatus = 'stopped' | 'starting' | 'running' | 'stopping';
+/**
+ * Plan Sync Worker
+ *
+ * Standalone class that watches plan.json and triggers plan.md regeneration.
+ * Handles cross-platform fs.watch reliability issues with polling fallback.
+ */
+export declare class PlanSyncWorker {
+    private readonly directory;
+    private readonly debounceMs;
+    private readonly pollIntervalMs;
+    private readonly syncTimeoutMs;
+    private readonly onSyncComplete?;
+    private status;
+    private watcher;
+    private pollTimer;
+    private debounceTimer;
+    /** In-flight sync lock */
+    private syncing;
+    /** Pending sync requested while in-flight */
+    private pendingSync;
+    /** Last known plan.json stat to detect changes */
+    private lastStat;
+    /** Track if we've been disposed */
+    private disposed;
+    constructor(options?: PlanSyncWorkerOptions);
+    /**
+     * Get the swarm directory path
+     */
+    private getSwarmDir;
+    /**
+     * Get the plan.json file path
+     */
+    private getPlanJsonPath;
+    /**
+     * Start watching for plan.json changes
+     */
+    start(): void;
+    /**
+     * Stop watching and clean up resources
+     */
+    stop(): void;
+    /**
+     * Dispose of the worker - stop and prevent further use
+     */
+    dispose(): void;
+    /**
+     * Get current status
+     */
+    getStatus(): PlanSyncWorkerStatus;
+    /**
+     * Check if worker is running
+     */
+    isRunning(): boolean;
+    /**
+     * Initialize the stat tracking for change detection
+     */
+    private initializeStat;
+    /**
+     * Set up native fs.watch on the swarm directory
+     * Returns true if successful, false if unavailable
+     */
+    private setupNativeWatcher;
+    /**
+     * Set up polling fallback
+     */
+    private setupPolling;
+    /**
+     * Check for changes via polling
+     */
+    private pollCheck;
+    /**
+     * Debounced sync - prevents rapid successive syncs
+     */
+    private debouncedSync;
+    /**
+     * Clear debounce timer
+     */
+    private clearDebounce;
+    /**
+     * Trigger a sync operation with overlap protection
+     */
+    private triggerSync;
+    /**
+     * Execute the sync operation with timeout protection
+     */
+    private executeSync;
+    /**
+     * Safely invoke onSyncComplete callback, catching any exceptions
+     * to prevent callback errors from affecting worker stability
+     */
+    private safeCallback;
+    /**
+     * Advisory: check for unauthorized writes to plan.json outside of save_plan/savePlan
+     * Logs a warning if plan.json appears to have been modified after the write marker
+     */
+    private checkForUnauthorizedWrite;
+    /**
+     * Wrap a promise with a timeout
+     */
+    private withTimeout;
+}

package/dist/background/queue.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Lightweight In-Process Queue with Priorities and Retry Metadata
+ *
+ * Provides a simple but powerful queue abstraction for background automation.
+ * Supports priorities, retry logic, and in-memory persistence only.
+ * NOTE: This queue does NOT persist across restarts — all items are lost when the process exits.
+ */
+/** Queue priority levels */
+export type QueuePriority = 'critical' | 'high' | 'normal' | 'low';
+/** Retry metadata for failed items */
+export interface RetryMetadata {
+    attempts: number;
+    maxAttempts: number;
+    lastAttempt?: number;
+    nextAttemptAt?: number;
+    backoffMs: number;
+    maxBackoffMs: number;
+}
+/** Queue item structure */
+export interface QueueItem<T = unknown> {
+    id: string;
+    priority: QueuePriority;
+    payload: T;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+    retry?: RetryMetadata;
+}
+/** Queue configuration */
+export interface QueueConfig {
+    priorityLevels?: QueuePriority[];
+    maxSize?: number;
+    defaultMaxRetries?: number;
+    defaultBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+/**
+ * In-process queue with priority support and retry metadata
+ */
+export declare class AutomationQueue<T = unknown> {
+    private items;
+    private readonly maxSize;
+    private readonly defaultMaxRetries;
+    private readonly defaultBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly eventBus;
+    private itemCounter;
+    constructor(config?: QueueConfig);
+    /**
+     * Generate unique item ID
+     */
+    private generateId;
+    /**
+     * Enqueue an item with priority
+     */
+    enqueue(payload: T, priority?: QueuePriority, metadata?: Record<string, unknown>): string;
+    /**
+     * Dequeue the highest priority item
+     */
+    dequeue(): QueueItem<T> | undefined;
+    /**
+     * Peek at the highest priority item without removing
+     */
+    peek(): QueueItem<T> | undefined;
+    /**
+     * Get item by ID
+     */
+    get(id: string): QueueItem<T> | undefined;
+    /**
+     * Remove specific item by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Mark item as completed and remove from queue
+     */
+    complete(id: string): boolean;
+    /**
+     * Mark item as failed and schedule retry if possible
+     */
+    retry(id: string, _error?: unknown): boolean;
+    /**
+     * Get items due for retry
+     */
+    getRetryableItems(): QueueItem<T>[];
+    /**
+     * Get current queue size
+     */
+    size(): number;
+    /**
+     * Check if queue is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if queue is full
+     */
+    isFull(): boolean;
+    /**
+     * Clear all items from queue
+     */
+    clear(): void;
+    /**
+     * Get all items (for debugging/inspection)
+     */
+    getAll(): QueueItem<T>[];
+    /**
+     * Get items by priority
+     */
+    getByPriority(priority: QueuePriority): QueueItem<T>[];
+    /**
+     * Get queue statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        byPriority: Record<QueuePriority, number>;
+        retryable: number;
+    };
+}