@lumenflow/core 2.18.3 → 2.19.0

package/dist/delegation-monitor.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Delegation Monitor Library (WU-1948, WU-1968)
+ *
+ * Core monitoring logic for detecting stuck delegations and zombie locks.
+ * Used by orchestrate:monitor CLI command.
+ *
+ * Features:
+ * - Analyzes delegation registry for status counts
+ * - Detects pending delegations older than threshold (stuck)
+ * - Checks lane locks for zombie PIDs
+ * - Generates recovery suggestions
+ * - WU-1968: Processes delegation_failure signals from memory bus
+ *
+ * Library-First Note: This is project-specific monitoring code for
+ * PatientPath's delegation-registry.jsonl and lane-lock files. No external
+ * library exists for this custom format.
+ *
+ * @see {@link packages/@lumenflow/cli/src/__tests__/orchestrate-monitor.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/delegation-monitor.test.ts} - Signal handler tests
+ * @see {@link packages/@lumenflow/cli/src/orchestrate-monitor.ts} - CLI entry point
+ * @see {@link packages/@lumenflow/cli/src/lib/delegation-registry-store.ts} - Registry storage
+ */
+/**
+ * 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]";
+/**
+ * @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: any): {
+    pending: number;
+    completed: number;
+    timeout: number;
+    crashed: number;
+    total: any;
+};
+/**
+ * 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: any, thresholdMinutes?: number): any[];
+/**
+ * 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<any[]>;
+/**
+ * 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: any, zombieLocks: any): any[];
+/**
+ * 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: any): 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: any, options?: RunRecoveryOptions): Promise<any[]>;
+/**
+ * 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: any): 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<{
+    processed: any[];
+    signalCount: number;
+    retryCount: number;
+    blockCount: number;
+    bugWuCount: number;
+}>;
+/**
+ * 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: any): 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":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH;;GAEG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,UAAU,yBAAyB,CAAC;AAEjD;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,KAAA;;;;;;EA2B7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,KAAA,EAAE,gBAAgB,SAA4B,SA4B/F;AAED;;;;;;;;;;;GAWG;AACH,UAAU,0BAA0B;IAClC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,0BAA+B,kBAuC9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,KAAA,EAAE,WAAW,KAAA,SAuBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,KAAA,UAkEzC;AAED;;;;;;;;;;;;;GAaG;AACH,UAAU,kBAAmB,SAAQ,0BAA0B;IAC7D,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,gBAAgB,KAAA,EAAE,OAAO,GAAE,kBAAuB,kBA2CnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,KAAA,UAkD5C;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAuIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,GAAE,kBAAuB;;;;;;GAwHrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,KAAA,UAmC/C"}