@wundam/orchex 1.0.0-rc.1

package/dist/intelligence/stream-generator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Stream definition generator.
+ * Converts deliverables to stream definitions ready for orchex init.
+ */
+import type { StreamDefinitionInput } from '../types.js';
+import type { Deliverable } from './deliverable-extractor.js';
+import type { DependencyGraph } from './dependency-inferrer.js';
+import { type StreamAnalysis } from './anti-pattern-detector.js';
+import type { LearnDiagnostics } from './diagnostics.js';
+/**
+ * Options for stream generation.
+ */
+export interface StreamGeneratorOptions {
+    /** Default verify commands for all streams */
+    defaultVerify?: string[];
+    /** Whether to validate against anti-patterns */
+    validateAntiPatterns?: boolean;
+    /** Minimum plan length to avoid 'vague_plan' anti-pattern */
+    minPlanLength?: number;
+    /** Estimate timeout based on category */
+    estimateTimeout?: boolean;
+    /** Project directory for path validation (optional) */
+    projectDir?: string;
+    /** Diagnostics collector for the learn pipeline */
+    diagnostics?: LearnDiagnostics;
+}
+/**
+ * Result of stream generation.
+ */
+export interface GeneratedStreams {
+    /** Stream definitions ready for orchex init */
+    streams: Record<string, StreamDefinitionInput>;
+    /** Any validation warnings */
+    warnings: string[];
+    /** Anti-pattern analysis results (if enabled) */
+    antiPatterns?: StreamAnalysis[];
+    /** Total stream count */
+    count: number;
+}
+/**
+ * Generate a plan string from deliverable content.
+ * Ensures the plan is descriptive enough to avoid 'vague_plan' anti-pattern.
+ * Includes code examples from the plan document when available.
+ */
+export declare function generatePlan(deliverable: Deliverable, minLength?: number, maxCodeChars?: number): string;
+/**
+ * Generate default verify commands based on category and owned files.
+ */
+export declare function generateVerifyCommands(deliverable: Deliverable): string[];
+/**
+ * Convert a single deliverable to a stream definition.
+ */
+export declare function deliverableToStream(deliverable: Deliverable, deps: string[], options?: StreamGeneratorOptions): StreamDefinitionInput;
+/**
+ * Generate stream definitions from deliverables and dependency graph.
+ */
+export declare function generateStreams(deliverables: Deliverable[], graph: DependencyGraph, options?: StreamGeneratorOptions): GeneratedStreams;
+/**
+ * Format generated streams for review.
+ */
+export declare function formatStreamsForReview(result: GeneratedStreams): string;
+/**
+ * Convert generated streams to the format expected by orchex init.
+ */
+export declare function toInitFormat(result: GeneratedStreams): Record<string, StreamDefinitionInput>;
+/**
+ * Extract prerequisite install commands from stream plan text.
+ *
+ * Scans all stream plans for:
+ * 1. Explicit commands: "npm install X Y Z"
+ * 2. Structured blocks: "Install dependencies:\n  - X\n  - Y"
+ *
+ * Returns deduplicated install commands for the main session to run.
+ */
+export declare function extractPrerequisites(streams: Record<string, StreamDefinitionInput>): string[];
+/**
+ * Result of path validation.
+ */
+export interface PathValidationResult {
+    /** Streams with corrected paths */
+    streams: Record<string, StreamDefinitionInput>;
+    /** Warnings about path issues */
+    warnings: string[];
+}
+/**
+ * Validate and optionally correct file paths in stream definitions.
+ * When projectDir is available, checks that owns/reads paths exist on disk.
+ * Attempts fuzzy correction for reads paths when exactly one match is found.
+ */
+export declare function validateAndCorrectPaths(streams: Record<string, StreamDefinitionInput>, projectDir?: string): PathValidationResult;

package/dist/intelligence/stream-generator.js

@@ -0,0 +1,452 @@
+/**
+ * Stream definition generator.
+ * Converts deliverables to stream definitions ready for orchex init.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createDetector } from './anti-pattern-detector.js';
+/**
+ * Default timeout estimates by category (in milliseconds).
+ */
+const TIMEOUT_BY_CATEGORY = {
+    code: 120000, // 2 minutes - typical implementation
+    test: 90000, // 1.5 minutes - tests are usually simpler
+    docs: 60000, // 1 minute - documentation
+    tutorial: 90000, // 1.5 minutes - tutorials need examples
+    'integration-guide': 90000,
+    'api-reference': 60000,
+    migration: 180000, // 3 minutes - migrations can be complex
+    other: 120000,
+};
+/**
+ * Generate a plan string from deliverable content.
+ * Ensures the plan is descriptive enough to avoid 'vague_plan' anti-pattern.
+ * Includes code examples from the plan document when available.
+ */
+export function generatePlan(deliverable, minLength = 5, maxCodeChars = 4000) {
+    // Start with the description
+    let plan = deliverable.description.trim();
+    // If description is too short, add context from name and category
+    const words = plan.split(/\s+/).filter(w => w.length > 0);
+    if (words.length < minLength) {
+        const verb = getActionVerb(deliverable.category);
+        const files = deliverable.ownedFiles.join(', ') || 'the target files';
+        plan = `${verb} ${deliverable.name}. ${plan}. Target: ${files}`;
+    }
+    // Append code examples if present (these are the LLM's most precise instructions)
+    if (deliverable.codeExamples.length > 0) {
+        const codeBlocks = [];
+        let totalChars = 0;
+        for (const ex of deliverable.codeExamples) {
+            const block = `\`\`\`${ex.language || ''}\n${ex.code}\n\`\`\``;
+            if (totalChars + block.length > maxCodeChars)
+                break;
+            codeBlocks.push(block);
+            totalChars += block.length;
+        }
+        if (codeBlocks.length > 0) {
+            plan += '\n\nReference code:\n' + codeBlocks.join('\n\n');
+        }
+    }
+    return plan;
+}
+/**
+ * Get an action verb appropriate for the category.
+ */
+function getActionVerb(category) {
+    switch (category) {
+        case 'code': return 'Implement';
+        case 'test': return 'Write tests for';
+        case 'docs': return 'Document';
+        case 'tutorial': return 'Create tutorial for';
+        case 'integration-guide': return 'Write integration guide for';
+        case 'api-reference': return 'Generate API reference for';
+        case 'migration': return 'Migrate';
+        default: return 'Complete';
+    }
+}
+/**
+ * Generate default verify commands based on category and owned files.
+ */
+export function generateVerifyCommands(deliverable) {
+    const commands = [];
+    // Always include build check for code files
+    const hasCodeFiles = deliverable.ownedFiles.some(f => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js') || f.endsWith('.jsx'));
+    if (hasCodeFiles) {
+        commands.push('npm run build');
+    }
+    // Add test run for test files
+    if (deliverable.category === 'test') {
+        const testFile = deliverable.ownedFiles.find(f => f.includes('.test.'));
+        if (testFile) {
+            commands.push(`npm test -- ${testFile}`);
+        }
+        else {
+            commands.push('npm test');
+        }
+    }
+    return commands;
+}
+/**
+ * Convert a single deliverable to a stream definition.
+ */
+export function deliverableToStream(deliverable, deps, options = {}) {
+    const { minPlanLength = 5, estimateTimeout = true, defaultVerify } = options;
+    // Check for YAML-sourced verify/setup (attached by yamlToDeliverable)
+    const yamlExtras = deliverable;
+    const verify = yamlExtras._verify || defaultVerify || generateVerifyCommands(deliverable);
+    const setup = yamlExtras._setup;
+    // Use description directly if it came from YAML (already a plan).
+    // YAML-sourced deliverables have codeExamples: [] (set in yamlToDeliverable),
+    // so bypassing generatePlan() here does not drop code examples.
+    const hasYamlPlan = yamlExtras._verify !== undefined || yamlExtras._setup !== undefined;
+    const plan = hasYamlPlan && deliverable.description.length >= minPlanLength
+        ? deliverable.description
+        : generatePlan(deliverable, minPlanLength);
+    const stream = {
+        name: deliverable.name,
+        deps: deps.length > 0 ? deps : undefined,
+        owns: deliverable.ownedFiles.length > 0 ? deliverable.ownedFiles : undefined,
+        reads: deliverable.readFiles.length > 0 ? deliverable.readFiles : undefined,
+        plan,
+        verify: verify.length > 0 ? verify : undefined,
+        setup: setup && setup.length > 0 ? setup : undefined,
+    };
+    // Add timeout estimate if enabled
+    if (estimateTimeout) {
+        const timeout = TIMEOUT_BY_CATEGORY[deliverable.category];
+        // Increase timeout for deliverables with many files
+        const fileMultiplier = Math.max(1, Math.ceil(deliverable.ownedFiles.length / 2));
+        stream.timeoutMs = timeout * fileMultiplier;
+    }
+    return stream;
+}
+/**
+ * Generate stream definitions from deliverables and dependency graph.
+ */
+export function generateStreams(deliverables, graph, options = {}) {
+    const { validateAntiPatterns = true } = options;
+    const streams = {};
+    const warnings = [];
+    const antiPatterns = [];
+    // Check for cycles
+    if (!graph.isAcyclic) {
+        warnings.push(`Dependency graph has cycles: ${graph.cycles.map(c => c.join(' → ')).join('; ')}`);
+    }
+    // Create detector once for all streams
+    const detector = validateAntiPatterns ? createDetector() : null;
+    // Generate streams
+    for (const deliverable of deliverables) {
+        const deps = graph.dependencies.get(deliverable.id) || [];
+        const stream = deliverableToStream(deliverable, deps, options);
+        // Validate against anti-patterns if enabled
+        if (detector) {
+            const analysis = detector.analyzeStream(deliverable.id, {
+                name: stream.name,
+                deps: stream.deps || [],
+                owns: stream.owns || [],
+                reads: stream.reads || [],
+                plan: stream.plan,
+                verify: stream.verify || [],
+            });
+            if (analysis.issues.length > 0) {
+                antiPatterns.push(analysis);
+                for (const issue of analysis.issues) {
+                    warnings.push(`${deliverable.id}: ${issue.type} - ${issue.message}`);
+                }
+            }
+        }
+        // Check for too_complex (independent of anti-pattern detector)
+        const childCount = deliverable.childCount;
+        const planLength = stream.plan?.length ?? 0;
+        const ownsCount = (stream.owns || []).length;
+        if (childCount !== undefined && childCount >= 5 && planLength > 2500) {
+            warnings.push(`${deliverable.id}: too_complex - ${childCount} sub-sections, ${ownsCount} owned files, ~${planLength} char plan. ` +
+                `Consider: use YAML stream definitions for manual decomposition, or set deliverable_level: 3`);
+        }
+        else if (childCount !== undefined && childCount >= 3 && planLength > 3500) {
+            warnings.push(`${deliverable.id}: too_complex - ${childCount} sub-sections, ~${planLength} char plan. ` +
+                `Consider: use YAML stream definitions for finer control`);
+        }
+        // Check for large owned files when projectDir is available
+        if (options.projectDir) {
+            const ownedFiles = stream.owns || [];
+            for (const file of ownedFiles) {
+                try {
+                    const fullPath = path.join(options.projectDir, file);
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    const lineCount = content.split('\n').length;
+                    if (lineCount > 800) {
+                        const warning = `${deliverable.id}: large_file_critical - ${file} is ${lineCount} lines (>800). ` +
+                            `Consider splitting this stream to reduce file scope`;
+                        warnings.push(warning);
+                        if (options.diagnostics) {
+                            options.diagnostics.warnings.push(warning);
+                        }
+                    }
+                    else if (lineCount > 500 && ownedFiles.length >= 3) {
+                        const warning = `${deliverable.id}: large_file_risk - ${file} is ${lineCount} lines, stream owns ${ownedFiles.length} files. ` +
+                            `Consider splitting to reduce complexity`;
+                        warnings.push(warning);
+                        if (options.diagnostics) {
+                            options.diagnostics.warnings.push(warning);
+                        }
+                    }
+                }
+                catch {
+                    // File doesn't exist yet (will be created) — skip
+                }
+            }
+        }
+        // Warn when a deliverable has no owned files
+        if (deliverable.ownedFiles.length === 0) {
+            const warning = `Stream '${deliverable.id}' has no owned files. It can read but not write. ` +
+                `If this is unintentional, check your Create:/Modify: syntax (must use backtick-quoted paths).`;
+            warnings.push(warning);
+            if (options.diagnostics) {
+                options.diagnostics.warnings.push(warning);
+            }
+        }
+        streams[deliverable.id] = stream;
+    }
+    // Validate and correct paths if projectDir available
+    if (options.projectDir) {
+        const validation = validateAndCorrectPaths(streams, options.projectDir);
+        warnings.push(...validation.warnings);
+        for (const [id, correctedStream] of Object.entries(validation.streams)) {
+            streams[id] = correctedStream;
+        }
+    }
+    return {
+        streams,
+        warnings,
+        antiPatterns: validateAntiPatterns ? antiPatterns : undefined,
+        count: deliverables.length,
+    };
+}
+/**
+ * Format generated streams for review.
+ */
+export function formatStreamsForReview(result) {
+    const lines = ['=== Generated Streams ===', ''];
+    lines.push(`Total: ${result.count} streams`);
+    if (result.warnings.length > 0) {
+        lines.push('');
+        lines.push('--- Warnings ---');
+        for (const warning of result.warnings) {
+            lines.push(`⚠️ ${warning}`);
+        }
+    }
+    lines.push('');
+    lines.push('--- Stream Definitions ---');
+    for (const [id, stream] of Object.entries(result.streams)) {
+        lines.push('');
+        lines.push(`${id}:`);
+        lines.push(`  name: ${stream.name}`);
+        if (stream.deps && stream.deps.length > 0) {
+            lines.push(`  deps: [${stream.deps.join(', ')}]`);
+        }
+        if (stream.owns && stream.owns.length > 0) {
+            lines.push(`  owns: [${stream.owns.join(', ')}]`);
+        }
+        if (stream.reads && stream.reads.length > 0) {
+            lines.push(`  reads: [${stream.reads.join(', ')}]`);
+        }
+        if (stream.plan) {
+            lines.push(`  plan: ${stream.plan.slice(0, 80)}${stream.plan.length > 80 ? '...' : ''}`);
+        }
+        if (stream.verify && stream.verify.length > 0) {
+            lines.push(`  verify: [${stream.verify.join(', ')}]`);
+        }
+        if (stream.timeoutMs) {
+            lines.push(`  timeoutMs: ${stream.timeoutMs}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Convert generated streams to the format expected by orchex init.
+ */
+export function toInitFormat(result) {
+    return result.streams;
+}
+// ============================================================================
+// Prerequisite Extraction
+// ============================================================================
+/**
+ * Package manager install patterns.
+ * Matches "npm install X", "pnpm add X", "yarn add X", "pip install X", "bun add X".
+ */
+const INSTALL_CMD_RE = /(?:npm\s+install|pnpm\s+add|yarn\s+add|pip\s+install|bun\s+add)\s+(.+)/gi;
+/**
+ * Matches "Install dependencies:" or "Install packages:" followed by list items.
+ * Captures the block of indented list items that follow.
+ */
+const INSTALL_BLOCK_RE = /install\s+(?:dependencies|packages)\s*:\s*\n((?:\s+[-*]\s+.+\n?)+)/gi;
+/**
+ * Extract a clean package name from a list item.
+ * Strips markdown formatting, parenthetical notes, and version specifiers.
+ * e.g. "- lucia" → "lucia", "- arctic (for OAuth)" → "arctic"
+ */
+function cleanPackageName(raw) {
+    let name = raw.replace(/^\s*[-*]\s*/, '').trim();
+    name = name.replace(/\s*\(.*?\)\s*$/, '').trim();
+    name = name.replace(/[`"']/g, '').trim();
+    if (/^@?[a-z0-9][\w./-]*$/i.test(name)) {
+        return name;
+    }
+    return null;
+}
+/**
+ * Extract prerequisite install commands from stream plan text.
+ *
+ * Scans all stream plans for:
+ * 1. Explicit commands: "npm install X Y Z"
+ * 2. Structured blocks: "Install dependencies:\n  - X\n  - Y"
+ *
+ * Returns deduplicated install commands for the main session to run.
+ */
+export function extractPrerequisites(streams) {
+    const packages = new Set();
+    for (const stream of Object.values(streams)) {
+        const plan = stream.plan ?? '';
+        let match;
+        INSTALL_CMD_RE.lastIndex = 0;
+        while ((match = INSTALL_CMD_RE.exec(plan)) !== null) {
+            const pkgs = match[1].split(/\s+/).filter(p => p && !p.startsWith('-'));
+            for (const pkg of pkgs) {
+                const clean = cleanPackageName(pkg);
+                if (clean)
+                    packages.add(clean);
+            }
+        }
+        INSTALL_BLOCK_RE.lastIndex = 0;
+        while ((match = INSTALL_BLOCK_RE.exec(plan)) !== null) {
+            const lines = match[1].split('\n');
+            for (const line of lines) {
+                const clean = cleanPackageName(line);
+                if (clean)
+                    packages.add(clean);
+            }
+        }
+    }
+    if (packages.size === 0)
+        return [];
+    return [`npm install ${[...packages].join(' ')}`];
+}
+/**
+ * Validate and optionally correct file paths in stream definitions.
+ * When projectDir is available, checks that owns/reads paths exist on disk.
+ * Attempts fuzzy correction for reads paths when exactly one match is found.
+ */
+export function validateAndCorrectPaths(streams, projectDir) {
+    const warnings = [];
+    if (!projectDir) {
+        return { streams, warnings };
+    }
+    const corrected = {};
+    // Build set of all owned paths across all streams — these are virtual files
+    // that will be created by prior-wave streams, so they should NOT be fuzzy-corrected.
+    const allOwnedPaths = new Set();
+    for (const stream of Object.values(streams)) {
+        for (const p of stream.owns || [])
+            allOwnedPaths.add(p);
+    }
+    for (const [id, stream] of Object.entries(streams)) {
+        const newOwns = [...(stream.owns || [])];
+        const newReads = [...(stream.reads || [])];
+        // Validate owns paths (new files are OK if parent dir exists)
+        for (const filePath of newOwns) {
+            const abs = path.join(projectDir, filePath);
+            if (!fs.existsSync(abs)) {
+                const parentDir = path.dirname(abs);
+                if (!fs.existsSync(parentDir)) {
+                    warnings.push(`${id}: path_not_found - owns path "${filePath}" not found and parent directory does not exist`);
+                }
+            }
+        }
+        // Validate and correct reads paths
+        const indicesToRemove = [];
+        for (let i = 0; i < newReads.length; i++) {
+            const filePath = newReads[i];
+            // Skip paths owned by any stream — they'll be created by prior waves
+            if (allOwnedPaths.has(filePath))
+                continue;
+            const abs = path.join(projectDir, filePath);
+            if (!fs.existsSync(abs)) {
+                // Attempt fuzzy correction: find files with same basename
+                const basename = path.basename(filePath);
+                const correction = findUniqueMatch(projectDir, basename);
+                if (correction.matches === 1 && correction.path) {
+                    warnings.push(`${id}: path_corrected - reads path "${filePath}" corrected to "${correction.path}" (only match found)`);
+                    newReads[i] = correction.path;
+                }
+                else if (correction.matches > 1) {
+                    warnings.push(`${id}: path_ambiguous - reads path "${filePath}" not found, ${correction.matches} candidates exist`);
+                }
+                else {
+                    // Remove phantom reads (not on disk, not owned, no fuzzy match)
+                    warnings.push(`${id}: path_removed - reads path "${filePath}" not found on disk, removed from reads`);
+                    indicesToRemove.push(i);
+                }
+            }
+        }
+        // Remove phantom reads (reverse order to preserve indices)
+        for (let i = indicesToRemove.length - 1; i >= 0; i--) {
+            newReads.splice(indicesToRemove[i], 1);
+        }
+        corrected[id] = {
+            ...stream,
+            owns: newOwns,
+            reads: newReads,
+        };
+    }
+    return { streams: corrected, warnings };
+}
+/**
+ * Find files matching a basename in the project directory.
+ * Returns the match count and the relative path if exactly one match.
+ */
+function findUniqueMatch(projectDir, basename) {
+    const matches = [];
+    // Walk common source directories (avoid node_modules, .git, dist)
+    const searchDirs = ['src', 'tests', 'lib', 'scripts'];
+    for (const dir of searchDirs) {
+        const dirPath = path.join(projectDir, dir);
+        if (fs.existsSync(dirPath)) {
+            findFilesRecursive(dirPath, basename, matches);
+        }
+    }
+    // Also check root level
+    const rootFile = path.join(projectDir, basename);
+    if (fs.existsSync(rootFile) && fs.statSync(rootFile).isFile()) {
+        matches.push(basename);
+    }
+    if (matches.length === 1) {
+        return { matches: 1, path: matches[0] };
+    }
+    return { matches: matches.length };
+}
+/**
+ * Recursively find files with a given basename.
+ */
+function findFilesRecursive(dir, basename, results, rootDir) {
+    const root = rootDir || path.dirname(dir);
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist')
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                findFilesRecursive(fullPath, basename, results, root);
+            }
+            else if (entry.name === basename) {
+                results.push(path.relative(root, fullPath));
+            }
+        }
+    }
+    catch {
+        // Permission errors, etc. — skip directory
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Execution Logger
+ *
+ * Append-only file logger for execution visibility.
+ * Writes to .orchex/active/execution.log
+ */
+export type LogLevel = 'INFO' | 'WARN' | 'ERROR';
+export interface LogEntry {
+    level: LogLevel;
+    event: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Create a logger for a specific project directory.
+ */
+export declare function createLogger(projectDir: string): {
+    info: (event: string, data?: Record<string, unknown>) => Promise<void>;
+    warn: (event: string, data?: Record<string, unknown>) => Promise<void>;
+    error: (event: string, data?: Record<string, unknown>) => Promise<void>;
+    /**
+     * Set the runId for log correlation. Once set, all subsequent log lines include it.
+     */
+    setRunId(id: string): void;
+    /**
+     * Start a heartbeat that logs progress every interval.
+     * Returns a stop function.
+     */
+    startHeartbeat(streamId: string, timeoutMs: number, intervalMs?: number): () => void;
+};
+export type Logger = ReturnType<typeof createLogger>;
+/**
+ * Clear the execution log (called at start of new execution).
+ */
+export declare function clearExecutionLog(projectDir: string): Promise<void>;

package/dist/logger.js

@@ -0,0 +1,83 @@
+/**
+ * Execution Logger
+ *
+ * Append-only file logger for execution visibility.
+ * Writes to .orchex/active/execution.log
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const LOG_FILE = '.orchex/active/execution.log';
+/**
+ * Format a log line with ISO timestamp.
+ */
+function formatLogLine(level, event, data, runId) {
+    const timestamp = new Date().toISOString();
+    const runIdStr = runId ? ` runId=${runId}` : '';
+    const dataStr = data
+        ? ' ' + Object.entries(data).map(([k, v]) => `${k}=${v}`).join(' ')
+        : '';
+    return `${timestamp} [${level}] ${event}${runIdStr}${dataStr}\n`;
+}
+/**
+ * Create a logger for a specific project directory.
+ */
+export function createLogger(projectDir) {
+    const logPath = path.join(projectDir, LOG_FILE);
+    let runId;
+    async function ensureLogDir() {
+        await fs.mkdir(path.dirname(logPath), { recursive: true });
+    }
+    async function log(level, event, data) {
+        try {
+            await ensureLogDir();
+            const line = formatLogLine(level, event, data, runId);
+            await fs.appendFile(logPath, line);
+        }
+        catch {
+            // Best effort - don't fail execution for logging issues
+        }
+    }
+    return {
+        info: (event, data) => log('INFO', event, data),
+        warn: (event, data) => log('WARN', event, data),
+        error: (event, data) => log('ERROR', event, data),
+        /**
+         * Set the runId for log correlation. Once set, all subsequent log lines include it.
+         */
+        setRunId(id) {
+            runId = id;
+        },
+        /**
+         * Start a heartbeat that logs progress every interval.
+         * Returns a stop function.
+         */
+        startHeartbeat(streamId, timeoutMs, intervalMs = 10000) {
+            const startTime = Date.now();
+            const interval = setInterval(() => {
+                const elapsed = Date.now() - startTime;
+                const remaining = Math.max(0, timeoutMs - elapsed);
+                const elapsedSec = Math.round(elapsed / 1000);
+                const remainingSec = Math.round(remaining / 1000);
+                const level = remaining < 15000 ? 'WARN' : 'INFO';
+                log(level, 'api_call_waiting', {
+                    id: streamId,
+                    elapsed: `${elapsedSec}s`,
+                    remaining: `${remainingSec}s`,
+                });
+            }, intervalMs);
+            return () => clearInterval(interval);
+        },
+    };
+}
+/**
+ * Clear the execution log (called at start of new execution).
+ */
+export async function clearExecutionLog(projectDir) {
+    const logPath = path.join(projectDir, LOG_FILE);
+    try {
+        await fs.writeFile(logPath, '');
+    }
+    catch {
+        // Ignore if file doesn't exist
+    }
+}

package/dist/logging.d.ts

@@ -0,0 +1,5 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;
+export declare function createLogger(module: string): pino.Logger<never, boolean>;
+export declare function createRequestLogger(requestId: string, userId?: string): pino.Logger<never, boolean>;
+export declare function finalLogger(err: Error | null, evt: string): void;