@lumenflow/core 1.0.0

package/dist/telemetry.d.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Telemetry Module - DORA/SPACE Metrics Emission
+ *
+ * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
+ * Used by gates-local.mjs and flow-report.mjs.
+ */
+/**
+ * Emit a telemetry event as NDJSON
+ * @param {string} filePath - Path to NDJSON file
+ * @param {object} event - Event data to emit
+ */
+export declare function emit(filePath: any, event: any): void;
+/**
+ * Emit a gates execution event
+ * @param {object} data - Gates event data
+ * @param {string} data.wu_id - Work Unit ID (e.g., 'WU-402')
+ * @param {string} data.lane - Lane name (e.g., 'Operations')
+ * @param {string} data.gate_name - Gate name (e.g., 'format:check')
+ * @param {boolean} data.passed - Whether gate passed
+ * @param {number} data.duration_ms - Execution duration in milliseconds
+ */
+export declare function emitGateEvent(data: any): void;
+/**
+ * Get current WU ID from git branch or environment
+ * @returns {string|null} WU ID or null
+ */
+export declare function getCurrentWU(): string;
+/**
+ * Get lane from git branch or environment
+ * @returns {string|null} Lane name or null
+ */
+export declare function getCurrentLane(): string;
+/**
+ * Emit LLM classification start event
+ * @param {object} data - Classification start data
+ * @param {string} data.classification_type - Type of classification (e.g., 'mode_detection', 'red_flag', 'phi_detection')
+ * @param {boolean} [data.has_context] - Whether conversation context was provided
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationStart(data: any, logPath?: string): void;
+/**
+ * Emit LLM classification complete event
+ * @param {object} data - Classification completion data
+ * @param {string} data.classification_type - Type of classification
+ * @param {number} data.duration_ms - Processing duration in milliseconds
+ * @param {number} data.tokens_used - Total tokens consumed
+ * @param {number} data.estimated_cost_usd - Estimated cost in USD
+ * @param {number} data.confidence - Classification confidence score (0-1)
+ * @param {boolean} data.fallback_used - Whether fallback (regex) was used
+ * @param {string} [data.fallback_reason] - Reason fallback was triggered
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationComplete(data: any, logPath?: string): void;
+/**
+ * Emit LLM classification error event
+ * @param {object} data - Classification error data
+ * @param {string} data.classification_type - Type of classification
+ * @param {string} data.error_type - Error type (e.g., 'timeout', 'rate_limit', 'validation')
+ * @param {string} data.error_message - Error message (must be PII-free)
+ * @param {number} [data.duration_ms] - Duration before error occurred
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationError(data: any, logPath?: string): void;
+/**
+ * Emit WU flow telemetry event to .beacon/flow.log
+ *
+ * Used by wu-claim, wu-done, wu-unblock for workflow tracking.
+ * Centralized from duplicated emitTelemetry() functions (WU-1256).
+ *
+ * @param {object} event - Event data (script, wu_id, lane, step, etc.)
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitWUFlowEvent(event: any, logPath?: string): void;

package/dist/telemetry.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Telemetry Module - DORA/SPACE Metrics Emission
+ *
+ * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
+ * Used by gates-local.mjs and flow-report.mjs.
+ */
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import { BEACON_PATHS, FILE_EXTENSIONS, STDIO, STRING_LITERALS, } from './wu-constants.js';
+const TELEMETRY_DIR = BEACON_PATHS.TELEMETRY;
+const GATES_LOG = `${TELEMETRY_DIR}/gates${FILE_EXTENSIONS.NDJSON}`;
+const LLM_CLASSIFICATION_LOG = `${TELEMETRY_DIR}/llm-classification${FILE_EXTENSIONS.NDJSON}`;
+const FLOW_LOG = BEACON_PATHS.FLOW_LOG;
+/**
+ * Ensure telemetry directory exists
+ */
+function ensureTelemetryDir() {
+    try {
+        mkdirSync(TELEMETRY_DIR, { recursive: true });
+    }
+    catch {
+        // Directory may already exist, ignore
+    }
+}
+/**
+ * Emit a telemetry event as NDJSON
+ * @param {string} filePath - Path to NDJSON file
+ * @param {object} event - Event data to emit
+ */
+export function emit(filePath, event) {
+    ensureTelemetryDir();
+    const line = `${JSON.stringify(event)}${STRING_LITERALS.NEWLINE}`;
+    try {
+        appendFileSync(filePath, line, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[telemetry] Failed to emit to ${filePath}:`, message);
+    }
+}
+/**
+ * Emit a gates execution event
+ * @param {object} data - Gates event data
+ * @param {string} data.wu_id - Work Unit ID (e.g., 'WU-402')
+ * @param {string} data.lane - Lane name (e.g., 'Operations')
+ * @param {string} data.gate_name - Gate name (e.g., 'format:check')
+ * @param {boolean} data.passed - Whether gate passed
+ * @param {number} data.duration_ms - Execution duration in milliseconds
+ */
+export function emitGateEvent(data) {
+    const event = {
+        timestamp: new Date().toISOString(),
+        wu_id: data.wu_id || null,
+        lane: data.lane || null,
+        gate_name: data.gate_name,
+        passed: data.passed,
+        duration_ms: data.duration_ms,
+    };
+    emit(GATES_LOG, event);
+}
+/**
+ * Get current WU ID from git branch or environment
+ * @returns {string|null} WU ID or null
+ */
+export function getCurrentWU() {
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf-8',
+            stdio: [STDIO.PIPE, STDIO.PIPE, STDIO.IGNORE],
+        }).trim();
+        // Extract WU ID from branch name (e.g., lane/operations/wu-402 -> WU-402)
+        const match = branch.match(/wu-(\d+)/i);
+        if (match) {
+            return `WU-${match[1]}`.toUpperCase();
+        }
+    }
+    catch {
+        // Not in a git repo or command failed
+    }
+    return null;
+}
+/**
+ * Get lane from git branch or environment
+ * @returns {string|null} Lane name or null
+ */
+export function getCurrentLane() {
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf-8',
+            stdio: [STDIO.PIPE, STDIO.PIPE, STDIO.IGNORE],
+        }).trim();
+        // Extract lane from branch name (e.g., lane/operations/wu-402 -> Operations)
+        const match = branch.match(/^lane\/([^/]+)\//i);
+        if (match) {
+            return match[1].charAt(0).toUpperCase() + match[1].slice(1).toLowerCase();
+        }
+    }
+    catch {
+        // Not in a git repo or command failed
+    }
+    return null;
+}
+/**
+ * Emit LLM classification start event
+ * @param {object} data - Classification start data
+ * @param {string} data.classification_type - Type of classification (e.g., 'mode_detection', 'red_flag', 'phi_detection')
+ * @param {boolean} [data.has_context] - Whether conversation context was provided
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationStart(data, logPath = LLM_CLASSIFICATION_LOG) {
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.start',
+        classification_type: data.classification_type,
+        has_context: data.has_context ?? false,
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    emit(logPath, event);
+}
+/**
+ * Emit LLM classification complete event
+ * @param {object} data - Classification completion data
+ * @param {string} data.classification_type - Type of classification
+ * @param {number} data.duration_ms - Processing duration in milliseconds
+ * @param {number} data.tokens_used - Total tokens consumed
+ * @param {number} data.estimated_cost_usd - Estimated cost in USD
+ * @param {number} data.confidence - Classification confidence score (0-1)
+ * @param {boolean} data.fallback_used - Whether fallback (regex) was used
+ * @param {string} [data.fallback_reason] - Reason fallback was triggered
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationComplete(data, logPath = LLM_CLASSIFICATION_LOG) {
+    // PII Protection: Explicitly exclude any user input fields
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.complete',
+        classification_type: data.classification_type,
+        duration_ms: data.duration_ms,
+        tokens_used: data.tokens_used,
+        estimated_cost_usd: data.estimated_cost_usd,
+        confidence: data.confidence,
+        fallback_used: data.fallback_used,
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    // Add fallback_reason only if fallback was used
+    if (data.fallback_used && data.fallback_reason) {
+        event.fallback_reason = data.fallback_reason;
+    }
+    emit(logPath, event);
+}
+/**
+ * Emit LLM classification error event
+ * @param {object} data - Classification error data
+ * @param {string} data.classification_type - Type of classification
+ * @param {string} data.error_type - Error type (e.g., 'timeout', 'rate_limit', 'validation')
+ * @param {string} data.error_message - Error message (must be PII-free)
+ * @param {number} [data.duration_ms] - Duration before error occurred
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationError(data, logPath = LLM_CLASSIFICATION_LOG) {
+    // PII Protection: Never log user input or sensitive data
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.error',
+        classification_type: data.classification_type,
+        error_type: data.error_type,
+        error_message: data.error_message, // Caller must ensure this is PII-free
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    if (data.duration_ms !== undefined) {
+        event.duration_ms = data.duration_ms;
+    }
+    // Explicitly redact any input_text_preview to prevent PII leakage
+    if (data.input_text_preview) {
+        event.input_text_preview = '[REDACTED]';
+    }
+    emit(logPath, event);
+}
+/**
+ * Emit WU flow telemetry event to .beacon/flow.log
+ *
+ * Used by wu-claim, wu-done, wu-unblock for workflow tracking.
+ * Centralized from duplicated emitTelemetry() functions (WU-1256).
+ *
+ * @param {object} event - Event data (script, wu_id, lane, step, etc.)
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitWUFlowEvent(event, logPath = FLOW_LOG) {
+    const logDir = path.dirname(logPath);
+    if (!existsSync(logDir)) {
+        mkdirSync(logDir, { recursive: true });
+    }
+    const line = JSON.stringify({ timestamp: new Date().toISOString(), ...event });
+    try {
+        appendFileSync(logPath, `${line}${STRING_LITERALS.NEWLINE}`, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        // Silently fail - telemetry should not block workflow
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[telemetry] Failed to emit flow event: ${message}`);
+    }
+}

package/dist/token-counter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Token Counter Utility
+ *
+ * Wraps tiktoken for counting tokens in prompts using the o200k_base encoding
+ * (used by gpt-5-nano). Provides caching and hash computation for stability checks.
+ *
+ * Part of WU-676: Single-Call LLM Orchestrator token budget enforcement.
+ */
+/**
+ * Count tokens in text using gpt-5-nano tokenizer
+ * @param {string} text - Text to tokenize
+ * @returns {number} Token count
+ */
+export declare function countTokens(text: any): any;
+/**
+ * Compute SHA256 hash of text (for stability checks)
+ * @param {string} text - Text to hash
+ * @returns {string} Hex hash
+ */
+export declare function computeHash(text: any): string;
+/**
+ * Load and render a prompt file (resolves includes, strips comments)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{text: string, raw: string}} Rendered text and raw YAML
+ */
+export declare function loadPrompt(promptPath: any): {
+    text: any;
+    raw: string;
+};
+/**
+ * Analyze a prompt file (count tokens, compute hash, extract metadata)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{tokenCount: number, hash: string, text: string, raw: string}}
+ */
+export declare function analyzePrompt(promptPath: any): {
+    tokenCount: any;
+    hash: string;
+    text: any;
+    raw: string;
+};
+/**
+ * Get top N longest lines from text (for cleanup targeting)
+ * @param {string} text - Text to analyze
+ * @param {number} n - Number of lines to return
+ * @returns {Array<{line: string, length: number, number: number}>} Longest lines
+ */
+export declare function getLongestLines(text: any, n?: number): any;
+/**
+ * Cleanup function (call on process exit to free tokenizer)
+ */
+export declare function cleanup(): void;

package/dist/token-counter.js

@@ -0,0 +1,145 @@
+/**
+ * Token Counter Utility
+ *
+ * Wraps tiktoken for counting tokens in prompts using the o200k_base encoding
+ * (used by gpt-5-nano). Provides caching and hash computation for stability checks.
+ *
+ * Part of WU-676: Single-Call LLM Orchestrator token budget enforcement.
+ */
+import { get_encoding } from 'tiktoken';
+import { readFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { load as loadYAML } from 'js-yaml';
+import { createError, ErrorCodes } from './error-handler.js';
+import { EXIT_CODES, STRING_LITERALS } from './wu-constants.js';
+// Cache tokenizer instance (expensive to create)
+let tokenizerCache = null;
+/**
+ * Get or create tiktoken instance with o200k_base encoding (gpt-5-nano)
+ * @returns {Tiktoken} Tokenizer instance
+ */
+function getTokenizer() {
+    if (!tokenizerCache) {
+        tokenizerCache = get_encoding('o200k_base');
+    }
+    return tokenizerCache;
+}
+/**
+ * Count tokens in text using gpt-5-nano tokenizer
+ * @param {string} text - Text to tokenize
+ * @returns {number} Token count
+ */
+export function countTokens(text) {
+    if (!text || typeof text !== 'string') {
+        return 0;
+    }
+    const tokenizer = getTokenizer();
+    const tokens = tokenizer.encode(text);
+    return tokens.length;
+}
+/**
+ * Compute SHA256 hash of text (for stability checks)
+ * @param {string} text - Text to hash
+ * @returns {string} Hex hash
+ */
+export function computeHash(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * Strip YAML comments from prompt text
+ * @param {string} text - YAML text
+ * @returns {string} Text with comments removed
+ */
+function stripYAMLComments(text) {
+    return text
+        .split(STRING_LITERALS.NEWLINE)
+        .filter((line) => !line.trim().startsWith('#'))
+        .join(STRING_LITERALS.NEWLINE);
+}
+/**
+ * Load and render a prompt file (resolves includes, strips comments)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{text: string, raw: string}} Rendered text and raw YAML
+ */
+export function loadPrompt(promptPath) {
+    try {
+        const raw = readFileSync(promptPath, { encoding: 'utf-8' });
+        // Parse YAML to access prompt structure
+        const parsed = loadYAML(raw);
+        // Extract prompt text (handle different YAML structures)
+        let promptText = '';
+        if (typeof parsed === 'string') {
+            promptText = parsed;
+        }
+        else if (parsed && parsed.prompt) {
+            promptText = parsed.prompt;
+        }
+        else if (parsed && parsed.system) {
+            promptText = parsed.system;
+        }
+        else if (parsed && parsed.content) {
+            promptText = parsed.content;
+        }
+        else {
+            // Fallback: use entire YAML stringified (for complex structures)
+            promptText = JSON.stringify(parsed, null, 2);
+        }
+        // Strip comments from rendered text
+        const renderedText = stripYAMLComments(promptText);
+        return { text: renderedText, raw };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Failed to load prompt from ${promptPath}: ${message}`, { path: promptPath, originalError: message });
+    }
+}
+/**
+ * Analyze a prompt file (count tokens, compute hash, extract metadata)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{tokenCount: number, hash: string, text: string, raw: string}}
+ */
+export function analyzePrompt(promptPath) {
+    const { text, raw } = loadPrompt(promptPath);
+    const tokenCount = countTokens(text);
+    const hash = computeHash(text);
+    return {
+        tokenCount,
+        hash,
+        text,
+        raw,
+    };
+}
+/**
+ * Get top N longest lines from text (for cleanup targeting)
+ * @param {string} text - Text to analyze
+ * @param {number} n - Number of lines to return
+ * @returns {Array<{line: string, length: number, number: number}>} Longest lines
+ */
+export function getLongestLines(text, n = 3) {
+    const lines = text.split(STRING_LITERALS.NEWLINE);
+    const linesWithMetadata = lines.map((line, index) => ({
+        line: line.trim(),
+        length: line.length,
+        number: index + 1,
+    }));
+    // Sort by length descending, take top N
+    return linesWithMetadata
+        .filter((l) => l.line.length > 0)
+        .sort((a, b) => b.length - a.length)
+        .slice(0, n);
+}
+/**
+ * Cleanup function (call on process exit to free tokenizer)
+ */
+export function cleanup() {
+    if (tokenizerCache) {
+        tokenizerCache.free();
+        tokenizerCache = null;
+    }
+}
+// Auto-cleanup on process exit
+process.on('exit', cleanup);
+process.on('SIGINT', () => {
+    cleanup();
+    process.exit(EXIT_CODES.SUCCESS);
+});

package/dist/usecases/get-dashboard-data.usecase.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GetDashboardData Use Case
+ *
+ * Orchestrates the collection of all dashboard metrics from the metrics collector.
+ * Follows hexagonal architecture - depends on port interface, not concrete implementation.
+ *
+ * @module get-dashboard-data.usecase
+ * @see {@link ../ports/metrics-collector.port.ts} - Port interface
+ * @see {@link ../domain/orchestration.types.ts} - Domain types
+ */
+import type { IMetricsCollector } from '../ports/metrics-collector.port.js';
+import type { DashboardData } from '../domain/orchestration.types.js';
+/**
+ * Options for the GetDashboardData use case.
+ */
+export interface GetDashboardDataOptions {
+    /**
+     * Number of hours to include in the timeline.
+     * @default TIMELINE_WINDOW_HOURS (24)
+     */
+    timelineHours?: number;
+}
+/**
+ * Use case for collecting all dashboard data.
+ *
+ * Orchestrates parallel calls to the metrics collector to gather:
+ * - Global status (active WUs, completed, blocked, etc.)
+ * - Agent metrics (invocation counts, pass rates, timing)
+ * - WU progress (DoD progress, agent statuses)
+ * - Timeline events (recent activity)
+ * - Alerts (items requiring attention)
+ *
+ * @example
+ * const collector = new FileSystemMetricsCollector(basePath);
+ * const useCase = new GetDashboardDataUseCase(collector);
+ * const data = await useCase.execute();
+ * console.log(data.globalStatus.activeWUs);
+ */
+export declare class GetDashboardDataUseCase {
+    private readonly metricsCollector;
+    constructor(metricsCollector: IMetricsCollector);
+    /**
+     * Execute the use case to collect all dashboard data.
+     *
+     * Calls all collector methods in parallel for optimal performance.
+     *
+     * @param options - Optional configuration
+     * @returns Promise resolving to complete dashboard data
+     * @throws Error if any collector method fails
+     */
+    execute(options?: GetDashboardDataOptions): Promise<DashboardData>;
+}

package/dist/usecases/get-dashboard-data.usecase.js

@@ -0,0 +1,61 @@
+/**
+ * GetDashboardData Use Case
+ *
+ * Orchestrates the collection of all dashboard metrics from the metrics collector.
+ * Follows hexagonal architecture - depends on port interface, not concrete implementation.
+ *
+ * @module get-dashboard-data.usecase
+ * @see {@link ../ports/metrics-collector.port.ts} - Port interface
+ * @see {@link ../domain/orchestration.types.ts} - Domain types
+ */
+import { TIMELINE_WINDOW_HOURS } from '../domain/orchestration.constants.js';
+/**
+ * Use case for collecting all dashboard data.
+ *
+ * Orchestrates parallel calls to the metrics collector to gather:
+ * - Global status (active WUs, completed, blocked, etc.)
+ * - Agent metrics (invocation counts, pass rates, timing)
+ * - WU progress (DoD progress, agent statuses)
+ * - Timeline events (recent activity)
+ * - Alerts (items requiring attention)
+ *
+ * @example
+ * const collector = new FileSystemMetricsCollector(basePath);
+ * const useCase = new GetDashboardDataUseCase(collector);
+ * const data = await useCase.execute();
+ * console.log(data.globalStatus.activeWUs);
+ */
+export class GetDashboardDataUseCase {
+    metricsCollector;
+    constructor(metricsCollector) {
+        this.metricsCollector = metricsCollector;
+    }
+    /**
+     * Execute the use case to collect all dashboard data.
+     *
+     * Calls all collector methods in parallel for optimal performance.
+     *
+     * @param options - Optional configuration
+     * @returns Promise resolving to complete dashboard data
+     * @throws Error if any collector method fails
+     */
+    async execute(options = {}) {
+        const { timelineHours = TIMELINE_WINDOW_HOURS } = options;
+        const timelineSince = new Date();
+        timelineSince.setHours(timelineSince.getHours() - timelineHours);
+        const [globalStatus, agentMetrics, wuProgress, timeline, alerts] = await Promise.all([
+            this.metricsCollector.getGlobalStatus(),
+            this.metricsCollector.getAgentMetrics(),
+            this.metricsCollector.getWUProgress(),
+            this.metricsCollector.getTimeline(timelineSince),
+            this.metricsCollector.getAlerts(),
+        ]);
+        return {
+            globalStatus,
+            agentMetrics,
+            wuProgress,
+            timeline,
+            alerts,
+        };
+    }
+}