@lumenflow/core 3.2.0 → 3.2.1

package/dist/delegation-monitor.d.ts

@@ -0,0 +1,262 @@
+import { type DelegationEvent } from './delegation-registry-schema.js';
+/**
+ * Default threshold for stuck delegation detection (in minutes)
+ */
+export declare const DEFAULT_THRESHOLD_MINUTES = 30;
+/**
+ * Log prefix for delegation-monitor messages
+ */
+export declare const LOG_PREFIX = "[delegation-monitor]";
+interface SpawnAnalysis {
+    pending: number;
+    completed: number;
+    timeout: number;
+    crashed: number;
+    total: number;
+}
+interface StuckSpawnInfo {
+    delegation: DelegationEvent;
+    ageMinutes: number;
+    lastCheckpoint: string | null;
+}
+interface ZombieLockInfo {
+    wuId: string;
+    lane: string;
+    pid: number;
+    timestamp: string;
+}
+interface Suggestion {
+    command: string;
+    reason: string;
+}
+interface MonitorResult {
+    analysis: SpawnAnalysis;
+    stuckDelegations: StuckSpawnInfo[];
+    zombieLocks: ZombieLockInfo[];
+    suggestions: Suggestion[];
+}
+interface RecoveryResultInfo {
+    delegationId: string;
+    targetWuId: string;
+    action: string;
+    recovered: boolean;
+    reason: string;
+    escalation?: {
+        bugWuId: string;
+        title: string;
+    };
+}
+interface BugWuSpec {
+    title: string;
+    lane: string;
+    description: string;
+    type: 'bug';
+    priority: 'P1';
+}
+interface SignalResponse {
+    signalId: string;
+    delegationId: string;
+    targetWuId: string;
+    action: string;
+    reason: string;
+    severity: string;
+    wuBlocked: boolean;
+    bugWuCreated: string | null;
+    blockReason?: string;
+    bugWuSpec?: BugWuSpec;
+}
+interface SignalProcessingResult {
+    processed: SignalResponse[];
+    signalCount: number;
+    retryCount: number;
+    blockCount: number;
+    bugWuCount: number;
+}
+/**
+ * @typedef {Object} SpawnAnalysis
+ * @property {number} pending - Count of pending delegations
+ * @property {number} completed - Count of completed delegations
+ * @property {number} timeout - Count of timed out delegations
+ * @property {number} crashed - Count of crashed delegations
+ * @property {number} total - Total delegation count
+ */
+/**
+ * @typedef {Object} StuckSpawnInfo
+ * @property {import('./delegation-registry-schema.js').DelegationEvent} delegation - The stuck delegation event
+ * @property {number} ageMinutes - Age of delegation in minutes
+ * @property {string|null} lastCheckpoint - Last checkpoint timestamp (if available from memory layer)
+ */
+/**
+ * @typedef {Object} ZombieLockInfo
+ * @property {string} wuId - WU ID that holds the zombie lock
+ * @property {string} lane - Lane name
+ * @property {number} pid - Process ID (no longer running)
+ * @property {string} timestamp - When lock was acquired
+ */
+/**
+ * @typedef {Object} Suggestion
+ * @property {string} command - Suggested command to run
+ * @property {string} reason - Explanation of why this is suggested
+ */
+/**
+ * @typedef {Object} MonitorResult
+ * @property {SpawnAnalysis} analysis - Delegation status counts
+ * @property {StuckSpawnInfo[]} stuckDelegations - List of stuck delegations
+ * @property {ZombieLockInfo[]} zombieLocks - List of zombie locks
+ * @property {Suggestion[]} suggestions - Recovery suggestions
+ */
+/**
+ * @typedef {Object} RecoveryResultInfo
+ * @property {string} delegationId - ID of the delegation that was processed
+ * @property {string} targetWuId - Target WU ID for the delegation
+ * @property {string} action - Recovery action taken (from RecoveryAction)
+ * @property {boolean} recovered - Whether auto-recovery was successful
+ * @property {string} reason - Human-readable explanation
+ * @property {Object} [escalation] - Escalation info if action is ESCALATED_STUCK
+ * @property {string} [escalation.bugWuId] - Bug WU ID created for escalation
+ * @property {string} [escalation.title] - Bug WU title
+ */
+/**
+ * Analyzes delegation events and returns status counts.
+ *
+ * @param {import('./delegation-registry-schema.js').DelegationEvent[]} delegations - Array of delegation events
+ * @returns {SpawnAnalysis} Status counts
+ *
+ * @example
+ * const analysis = analyzeDelegations(delegations);
+ * console.log(`Pending: ${analysis.pending}, Completed: ${analysis.completed}`);
+ */
+export declare function analyzeDelegations(delegations: DelegationEvent[]): SpawnAnalysis;
+/**
+ * Detects pending delegations that have been running longer than the threshold.
+ *
+ * @param {import('./delegation-registry-schema.js').DelegationEvent[]} delegations - Array of delegation events
+ * @param {number} [thresholdMinutes=DEFAULT_THRESHOLD_MINUTES] - Threshold in minutes
+ * @returns {StuckSpawnInfo[]} Array of stuck delegation info
+ *
+ * @example
+ * const stuck = detectStuckDelegations(delegations, 30);
+ * for (const info of stuck) {
+ *   console.log(`${info.delegation.targetWuId} stuck for ${info.ageMinutes} minutes`);
+ * }
+ */
+export declare function detectStuckDelegations(delegations: DelegationEvent[], thresholdMinutes?: number): StuckSpawnInfo[];
+/**
+ * Checks lane lock files for zombie locks (dead PIDs).
+ *
+ * @param {SpawnMonitorBaseDirOptions} [options] - Options
+ * @returns {Promise<ZombieLockInfo[]>} Array of zombie lock info
+ *
+ * @example
+ * const zombies = await checkZombieLocks();
+ * for (const lock of zombies) {
+ *   console.log(`Zombie lock: ${lock.lane} (PID ${lock.pid})`);
+ * }
+ */
+interface SpawnMonitorBaseDirOptions {
+    /** Base directory (defaults to process.cwd()) */
+    baseDir?: string;
+}
+export declare function checkZombieLocks(options?: SpawnMonitorBaseDirOptions): Promise<ZombieLockInfo[]>;
+/**
+ * Generates recovery suggestions for stuck delegations and zombie locks.
+ *
+ * @param {StuckSpawnInfo[]} stuckDelegations - Array of stuck delegation info
+ * @param {ZombieLockInfo[]} zombieLocks - Array of zombie lock info
+ * @returns {Suggestion[]} Array of suggestions
+ *
+ * @example
+ * const suggestions = generateSuggestions(stuckDelegations, zombieLocks);
+ * for (const s of suggestions) {
+ *   console.log(`${s.reason}\n  ${s.command}`);
+ * }
+ */
+export declare function generateSuggestions(stuckDelegations: StuckSpawnInfo[], zombieLocks: ZombieLockInfo[]): Suggestion[];
+/**
+ * Formats monitor output for display.
+ *
+ * @param {MonitorResult} result - Monitor result to format
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatMonitorOutput(result);
+ * console.log(output);
+ */
+export declare function formatMonitorOutput(result: MonitorResult): string;
+/**
+ * Runs recovery for stuck delegations by calling recoverStuckDelegation for each.
+ * When a delegation is escalated (action=ESCALATED_STUCK), chains to escalateStuckDelegation.
+ *
+ * @param {StuckSpawnInfo[]} stuckDelegations - Array of stuck delegation info
+ * @param {RunRecoveryOptions} [options] - Options
+ * @returns {Promise<RecoveryResultInfo[]>} Array of recovery results
+ *
+ * @example
+ * const results = await runRecovery(stuckDelegations, { baseDir: '/path/to/project' });
+ * for (const result of results) {
+ *   console.log(`${result.delegationId}: ${result.action}`);
+ * }
+ */
+interface RunRecoveryOptions extends SpawnMonitorBaseDirOptions {
+    /** If true, escalations return spec only */
+    dryRun?: boolean;
+}
+export declare function runRecovery(stuckDelegations: StuckSpawnInfo[], options?: RunRecoveryOptions): Promise<RecoveryResultInfo[]>;
+/**
+ * Formats recovery results for display.
+ *
+ * @param {RecoveryResultInfo[]} results - Array of recovery results
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatRecoveryResults(results);
+ * console.log(output);
+ */
+export declare function formatRecoveryResults(results: RecoveryResultInfo[]): string;
+/**
+ * Log prefix for signal handler messages
+ */
+export declare const SIGNAL_HANDLER_LOG_PREFIX = "[delegation-signal-handler]";
+/**
+ * Response actions for delegation failure signals
+ */
+export declare const SignalResponseAction: Readonly<{
+    RETRY: "retry";
+    BLOCK: "block";
+    BUG_WU: "bug_wu";
+    NONE: "none";
+}>;
+/**
+ * Processes delegation_failure signals from the memory bus.
+ *
+ * WU-1968: Orchestrator signal handler for delegation_failure signals.
+ *
+ * Response logic:
+ * - First failure (suggested_action=retry): logs warning, suggests retry
+ * - Second failure (suggested_action=block): marks WU blocked with reason
+ * - Third+ failure (suggested_action=human_escalate): creates Bug WU
+ *
+ * @param {RunRecoveryOptions} options - Options
+ * @returns {Promise<SignalProcessingResult>} Processing result
+ *
+ * @example
+ * const result = await processDelegationFailureSignals({ baseDir: '/path/to/project' });
+ * console.log(`Processed ${result.signalCount} signals`);
+ * for (const response of result.processed) {
+ *   console.log(`${response.targetWuId}: ${response.action}`);
+ * }
+ */
+export declare function processDelegationFailureSignals(options?: RunRecoveryOptions): Promise<SignalProcessingResult>;
+/**
+ * Formats signal handler output for display.
+ *
+ * @param {SignalProcessingResult} result - Processing result
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatSignalHandlerOutput(result);
+ * console.log(output);
+ */
+export declare function formatSignalHandlerOutput(result: SignalProcessingResult): string;
+export {};
+//# sourceMappingURL=delegation-monitor.d.ts.map

package/dist/delegation-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-monitor.d.ts","sourceRoot":"","sources":["../src/delegation-monitor.ts"],"names":[],"mappings":"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"}