@shepai/cli 1.14.1 → 1.15.0

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-worker.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * Feature Agent Worker
+ *
+ * Background worker entry point that runs as a child process via fork().
+ * Initializes DI, creates the feature agent graph, and executes it.
+ * Sends periodic heartbeats so the CLI can detect stuck/crashed workers.
+ *
+ * CLI Args: --feature-id <id> --run-id <id> --repo <path> --spec-dir <path>
+ */
+import 'reflect-metadata';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { Command } from '@langchain/langgraph';
+import { initializeContainer, container } from '../../../../infrastructure/di/container.js';
+import { createFeatureAgentGraph } from './feature-agent-graph.js';
+import { createCheckpointer } from '../common/checkpointer.js';
+import { AgentRunStatus } from '../../../../domain/generated/output.js';
+import { getSettings, initializeSettings } from '../../../../infrastructure/services/settings.service.js';
+import { InitializeSettingsUseCase } from '../../../../application/use-cases/settings/initialize-settings.use-case.js';
+import { setHeartbeatContext } from './heartbeat.js';
+/**
+ * Parse CLI arguments into a WorkerArgs object.
+ * Throws if any required argument is missing.
+ */
+export function parseWorkerArgs(args) {
+    const getArg = (name) => {
+        const index = args.indexOf(`--${name}`);
+        if (index === -1 || index + 1 >= args.length) {
+            throw new Error(`Missing required argument: --${name}`);
+        }
+        return args[index + 1];
+    };
+    const worktreeIdx = args.indexOf('--worktree-path');
+    const worktreePath = worktreeIdx !== -1 && worktreeIdx + 1 < args.length ? args[worktreeIdx + 1] : undefined;
+    const approvalIdx = args.indexOf('--approval-mode');
+    const approvalMode = approvalIdx !== -1 && approvalIdx + 1 < args.length ? args[approvalIdx + 1] : undefined;
+    const resume = args.includes('--resume');
+    return {
+        featureId: getArg('feature-id'),
+        runId: getArg('run-id'),
+        repo: getArg('repo'),
+        specDir: getArg('spec-dir'),
+        worktreePath,
+        approvalMode,
+        resume,
+    };
+}
+/** Simple worker logger — writes to stdout which is redirected to log file by the parent. */
+function log(message) {
+    const ts = new Date().toISOString();
+    process.stdout.write(`[${ts}] [WORKER] ${message}\n`);
+}
+/** Heartbeat interval (30 seconds) */
+const HEARTBEAT_INTERVAL_MS = 30_000;
+/**
+ * Start periodic heartbeat that updates last_heartbeat in the DB.
+ * Returns a cleanup function to stop the interval.
+ */
+function startHeartbeat(runId, runRepository) {
+    const interval = setInterval(async () => {
+        try {
+            const now = new Date();
+            await runRepository.updateStatus(runId, AgentRunStatus.running, {
+                lastHeartbeat: now,
+                updatedAt: now,
+            });
+        }
+        catch {
+            // Heartbeat failure is non-fatal — just log it
+            log('Heartbeat update failed (non-fatal)');
+        }
+    }, HEARTBEAT_INTERVAL_MS);
+    return () => clearInterval(interval);
+}
+/**
+ * Run the feature agent worker with the given arguments.
+ * Initializes DI, creates the graph, and executes it.
+ */
+export async function runWorker(args) {
+    log(`Starting with featureId=${args.featureId} runId=${args.runId}`);
+    log(`  repo=${args.repo}`);
+    log(`  specDir=${args.specDir}`);
+    log(`  worktreePath=${args.worktreePath ?? '(none)'}`);
+    log(`  approvalMode=${args.approvalMode ?? '(none)'}`);
+    log(`  resume=${args.resume}`);
+    log('Initializing container...');
+    await initializeContainer();
+    // Initialize settings in the worker process
+    log('Loading settings...');
+    const initSettingsUseCase = container.resolve(InitializeSettingsUseCase);
+    const settings = await initSettingsUseCase.execute();
+    initializeSettings(settings);
+    const runRepository = container.resolve('IAgentRunRepository');
+    const executorFactory = container.resolve('IAgentExecutorFactory');
+    // Create executor from configured agent settings (now settings are initialized)
+    const configuredSettings = getSettings();
+    log(`Creating executor for agent type: ${configuredSettings.agent.type}`);
+    const executor = executorFactory.createExecutor(configuredSettings.agent.type, configuredSettings.agent);
+    // Use a file-based checkpointer for persistence across restarts
+    const checkpointPath = join(homedir(), '.shep', 'checkpoints', `${args.runId}.db`);
+    log(`Creating checkpointer at ${checkpointPath}`);
+    const checkpointer = createCheckpointer(checkpointPath);
+    const graph = createFeatureAgentGraph(executor, checkpointer);
+    // Mark the run as running with our PID
+    const now = new Date();
+    log(`Updating status to running (PID ${process.pid})...`);
+    await runRepository.updateStatus(args.runId, AgentRunStatus.running, {
+        pid: process.pid,
+        startedAt: now,
+        lastHeartbeat: now,
+        updatedAt: now,
+    });
+    // Start heartbeat so the CLI can detect if we're still alive
+    const stopHeartbeat = startHeartbeat(args.runId, runRepository);
+    // Set heartbeat context so node-helpers can update current node
+    setHeartbeatContext(args.runId, runRepository);
+    try {
+        const graphConfig = { configurable: { thread_id: args.runId } };
+        let result;
+        if (args.resume) {
+            log('Resuming graph from checkpoint...');
+            result = await graph.invoke(new Command({ resume: { approved: true } }), graphConfig);
+        }
+        else {
+            log('Starting graph invocation...');
+            result = await graph.invoke({
+                featureId: args.featureId,
+                repositoryPath: args.repo,
+                worktreePath: args.worktreePath ?? args.repo,
+                specDir: args.specDir,
+                ...(args.approvalMode ? { approvalMode: args.approvalMode } : {}),
+            }, graphConfig);
+        }
+        log(`Graph invocation completed. Error: ${result.error ?? 'none'}`);
+        stopHeartbeat();
+        // Check if graph was interrupted (human-in-the-loop approval needed)
+        const interruptPayload = result.__interrupt__;
+        if (interruptPayload && interruptPayload.length > 0) {
+            const now = new Date();
+            await runRepository.updateStatus(args.runId, AgentRunStatus.waitingApproval, {
+                approvalStatus: 'waiting',
+                updatedAt: now,
+            });
+            log('Run paused — waiting for human approval');
+            return;
+        }
+        // Check if the graph itself reported an error in state
+        if (result.error) {
+            const failedAt = new Date();
+            await runRepository.updateStatus(args.runId, AgentRunStatus.failed, {
+                error: result.error,
+                completedAt: failedAt,
+                updatedAt: failedAt,
+            });
+            log(`Run marked as failed: ${result.error}`);
+            return;
+        }
+        const completedAt = new Date();
+        await runRepository.updateStatus(args.runId, AgentRunStatus.completed, {
+            result: result.messages?.join('\n') ?? '',
+            completedAt,
+            updatedAt: completedAt,
+        });
+        log('Run marked as completed');
+    }
+    catch (error) {
+        stopHeartbeat();
+        const failedAt = new Date();
+        const message = error instanceof Error ? error.message : String(error);
+        log(`Graph invocation error: ${message}`);
+        await runRepository.updateStatus(args.runId, AgentRunStatus.failed, {
+            error: message,
+            completedAt: failedAt,
+            updatedAt: failedAt,
+        });
+        log('Run marked as failed');
+    }
+}
+// Catch unhandled errors globally so they always appear in the log file
+process.on('uncaughtException', (err) => {
+    log(`UNCAUGHT EXCEPTION: ${err.message}\n${err.stack}`);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    const msg = reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason);
+    log(`UNHANDLED REJECTION: ${msg}`);
+    process.exit(1);
+});
+// Handle IPC disconnect (parent exited) gracefully — this is expected for detached workers
+process.on('disconnect', () => {
+    log('Parent disconnected (IPC channel closed) — continuing as detached worker');
+});
+// Handle SIGTERM for graceful shutdown
+let runIdForSignal;
+let runRepoForSignal;
+process.on('SIGTERM', async () => {
+    log('Received SIGTERM, shutting down...');
+    if (runIdForSignal && runRepoForSignal) {
+        const now = new Date();
+        await runRepoForSignal.updateStatus(runIdForSignal, AgentRunStatus.interrupted, {
+            error: 'Process received SIGTERM',
+            completedAt: now,
+            updatedAt: now,
+        });
+    }
+    process.exit(0);
+});
+// Main execution when run as a script
+// When using fork(), the forked process runs the entire module, but we want to detect if we're the entrypoint
+const isMainModule = typeof require !== 'undefined'
+    ? require.main === module
+    : process.argv[1]?.includes('feature-agent-worker');
+if (isMainModule) {
+    log('Worker process starting...');
+    try {
+        const args = parseWorkerArgs(process.argv.slice(2));
+        runIdForSignal = args.runId;
+        runWorker(args)
+            .then(() => {
+            runRepoForSignal = container.resolve('IAgentRunRepository');
+            log('Worker completed successfully, exiting.');
+            process.exit(0);
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            log(`Worker fatal error: ${msg}`);
+            process.exit(1);
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`Worker setup error: ${msg}`);
+        process.exit(1);
+    }
+}

package/dist/src/infrastructure/services/agents/feature-agent/heartbeat.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Heartbeat context for current-node tracking.
+ *
+ * The worker sets the context (runId + repository), and node-helpers
+ * call reportNodeStart() to update the DB with the current node name.
+ * This is a module-level singleton since only one worker runs per process.
+ */
+import type { IAgentRunRepository } from '../../../../application/ports/output/agent-run-repository.interface.js';
+/**
+ * Set the heartbeat context. Called once by the worker after DI init.
+ */
+export declare function setHeartbeatContext(runId: string, repository: IAgentRunRepository): void;
+/**
+ * Report that a graph node has started executing.
+ * Updates the run record with the current node name and a fresh heartbeat.
+ * Non-blocking: errors are swallowed so graph execution is not affected.
+ */
+export declare function reportNodeStart(nodeName: string): void;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../../../../../src/infrastructure/services/agents/feature-agent/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8DAA8D,CAAC;AAMxG;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAGxF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAgBtD"}

package/dist/src/infrastructure/services/agents/feature-agent/heartbeat.js

@@ -0,0 +1,38 @@
+/**
+ * Heartbeat context for current-node tracking.
+ *
+ * The worker sets the context (runId + repository), and node-helpers
+ * call reportNodeStart() to update the DB with the current node name.
+ * This is a module-level singleton since only one worker runs per process.
+ */
+import { AgentRunStatus } from '../../../../domain/generated/output.js';
+let contextRunId;
+let contextRepository;
+/**
+ * Set the heartbeat context. Called once by the worker after DI init.
+ */
+export function setHeartbeatContext(runId, repository) {
+    contextRunId = runId;
+    contextRepository = repository;
+}
+/**
+ * Report that a graph node has started executing.
+ * Updates the run record with the current node name and a fresh heartbeat.
+ * Non-blocking: errors are swallowed so graph execution is not affected.
+ */
+export function reportNodeStart(nodeName) {
+    if (!contextRunId || !contextRepository)
+        return;
+    const runId = contextRunId;
+    const repo = contextRepository;
+    // Fire-and-forget — don't await in the graph's hot path
+    repo
+        .updateStatus(runId, AgentRunStatus.running, {
+        result: `node:${nodeName}`,
+        lastHeartbeat: new Date(),
+        updatedAt: new Date(),
+    })
+        .catch(() => {
+        // Swallow — DB write failure is non-fatal
+    });
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/analyze.node.d.ts

@@ -0,0 +1,7 @@
+import type { IAgentExecutor } from '../../../../../application/ports/output/agent-executor.interface.js';
+/**
+ * Creates the analyze node that explores the repository and writes
+ * codebase analysis, complexity estimate, and affected areas to spec.yaml.
+ */
+export declare function createAnalyzeNode(executor: IAgentExecutor): (state: import("../state.js").FeatureAgentState) => Promise<Partial<import("../state.js").FeatureAgentState>>;
+//# sourceMappingURL=analyze.node.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/nodes/analyze.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.node.d.ts","sourceRoot":"","sources":["../../../../../../../src/infrastructure/services/agents/feature-agent/nodes/analyze.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wDAAwD,CAAC;AAI7F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,iHAEzD"}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/analyze.node.js

@@ -0,0 +1,9 @@
+import { executeNode } from './node-helpers.js';
+import { buildAnalyzePrompt } from './prompts/analyze.prompt.js';
+/**
+ * Creates the analyze node that explores the repository and writes
+ * codebase analysis, complexity estimate, and affected areas to spec.yaml.
+ */
+export function createAnalyzeNode(executor) {
+    return executeNode('analyze', executor, buildAnalyzePrompt);
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/implement.node.d.ts

@@ -0,0 +1,11 @@
+import type { IAgentExecutor } from '../../../../../application/ports/output/agent-executor.interface.js';
+import type { FeatureAgentState } from '../state.js';
+/**
+ * Creates the implement node — PLACEHOLDER.
+ *
+ * Implementation execution is not yet wired up.
+ * Returns a programming joke to clearly signal this is a placeholder
+ * while keeping the graph pipeline intact.
+ */
+export declare function createImplementNode(_executor: IAgentExecutor): (_state: FeatureAgentState) => Promise<Partial<FeatureAgentState>>;
+//# sourceMappingURL=implement.node.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/nodes/implement.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement.node.d.ts","sourceRoot":"","sources":["../../../../../../../src/infrastructure/services/agents/feature-agent/nodes/implement.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wDAAwD,CAAC;AAC7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKrD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,cAAc,IAG7C,QAAQ,iBAAiB,KAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAY9E"}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/implement.node.js

@@ -0,0 +1,23 @@
+import { createNodeLogger } from './node-helpers.js';
+import { reportNodeStart } from '../heartbeat.js';
+import { getImplementPlaceholderJoke } from './prompts/implement.prompt.js';
+/**
+ * Creates the implement node — PLACEHOLDER.
+ *
+ * Implementation execution is not yet wired up.
+ * Returns a programming joke to clearly signal this is a placeholder
+ * while keeping the graph pipeline intact.
+ */
+export function createImplementNode(_executor) {
+    const log = createNodeLogger('implement');
+    return async (_state) => {
+        log.info('Starting... (placeholder — implementation not yet wired)');
+        reportNodeStart('implement');
+        const joke = getImplementPlaceholderJoke();
+        log.info(`Placeholder complete. ${joke}`);
+        return {
+            currentNode: 'implement',
+            messages: [`[implement] Placeholder — ${joke}`],
+        };
+    };
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared foundation for feature-agent graph nodes.
+ *
+ * Provides consistent logging, spec file reading, executor invocation,
+ * and error handling so every node follows the same patterns.
+ */
+import type { IAgentExecutor, AgentExecutionOptions } from '../../../../../application/ports/output/agent-executor.interface.js';
+import type { FeatureAgentState } from '../state.js';
+/**
+ * Create a scoped logger that prefixes messages with the node name.
+ * Output goes to stdout which the worker redirects to the log file.
+ */
+export declare function createNodeLogger(nodeName: string): {
+    info(message: string): void;
+    error(message: string): void;
+};
+export type NodeLogger = ReturnType<typeof createNodeLogger>;
+/**
+ * Safely read a file from the spec directory. Returns empty string if file doesn't exist.
+ */
+export declare function readSpecFile(specDir: string, filename: string): string;
+/**
+ * Build executor options with cwd. Each node gets a clean agent context.
+ */
+export declare function buildExecutorOptions(state: FeatureAgentState): AgentExecutionOptions;
+/**
+ * Determine whether the current node should trigger an interrupt
+ * for human approval given the configured approval mode.
+ */
+export declare function shouldInterrupt(nodeName: string, approvalMode: string | undefined): boolean;
+/**
+ * Execute a node with consistent logging and error handling.
+ *
+ * Wraps the node's core logic with:
+ * - Entry/exit logging with timing
+ * - Error catching that returns error state instead of throwing
+ * - Consistent state shape for success and failure
+ */
+export declare function executeNode(nodeName: string, executor: IAgentExecutor, buildPrompt: (state: FeatureAgentState, log: NodeLogger) => string): (state: FeatureAgentState) => Promise<Partial<FeatureAgentState>>;
+//# sourceMappingURL=node-helpers.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-helpers.d.ts","sourceRoot":"","sources":["../../../../../../../src/infrastructure/services/agents/feature-agent/nodes/node-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,wDAAwD,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM;kBAE/B,MAAM,GAAG,IAAI;mBAIZ,MAAM,GAAG,IAAI;EAK/B;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,qBAAqB,CAIpF;AAUD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,UAAU,KAAK,MAAM,GACjE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAiDnE"}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/node-helpers.js

@@ -0,0 +1,114 @@
+/**
+ * Shared foundation for feature-agent graph nodes.
+ *
+ * Provides consistent logging, spec file reading, executor invocation,
+ * and error handling so every node follows the same patterns.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { interrupt, isGraphBubbleUp } from '@langchain/langgraph';
+import { reportNodeStart } from '../heartbeat.js';
+/**
+ * Create a scoped logger that prefixes messages with the node name.
+ * Output goes to stdout which the worker redirects to the log file.
+ */
+export function createNodeLogger(nodeName) {
+    return {
+        info(message) {
+            const ts = new Date().toISOString();
+            process.stdout.write(`[${ts}] [${nodeName}] ${message}\n`);
+        },
+        error(message) {
+            const ts = new Date().toISOString();
+            process.stderr.write(`[${ts}] [${nodeName}] ERROR: ${message}\n`);
+        },
+    };
+}
+/**
+ * Safely read a file from the spec directory. Returns empty string if file doesn't exist.
+ */
+export function readSpecFile(specDir, filename) {
+    try {
+        return readFileSync(join(specDir, filename), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Build executor options with cwd. Each node gets a clean agent context.
+ */
+export function buildExecutorOptions(state) {
+    return {
+        cwd: state.worktreePath || state.repositoryPath,
+    };
+}
+/** Nodes that are auto-approved (no interrupt) for each approval mode. */
+const AUTO_APPROVED_NODES = {
+    interactive: [],
+    'allow-prd': ['analyze', 'requirements'],
+    'allow-plan': ['analyze', 'requirements', 'research', 'plan'],
+    'allow-all': ['analyze', 'requirements', 'research', 'plan', 'implement'],
+};
+/**
+ * Determine whether the current node should trigger an interrupt
+ * for human approval given the configured approval mode.
+ */
+export function shouldInterrupt(nodeName, approvalMode) {
+    if (!approvalMode || approvalMode === 'allow-all')
+        return false;
+    const autoApproved = AUTO_APPROVED_NODES[approvalMode] ?? [];
+    return !autoApproved.includes(nodeName);
+}
+/**
+ * Execute a node with consistent logging and error handling.
+ *
+ * Wraps the node's core logic with:
+ * - Entry/exit logging with timing
+ * - Error catching that returns error state instead of throwing
+ * - Consistent state shape for success and failure
+ */
+export function executeNode(nodeName, executor, buildPrompt) {
+    const log = createNodeLogger(nodeName);
+    return async (state) => {
+        log.info('Starting...');
+        reportNodeStart(nodeName);
+        const startTime = Date.now();
+        try {
+            const prompt = buildPrompt(state, log);
+            const options = buildExecutorOptions(state);
+            log.info(`Executing agent at cwd=${options.cwd}`);
+            log.info(`Prompt length: ${prompt.length} chars`);
+            const result = await executor.execute(prompt, options);
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+            log.info(`Complete (${result.result.length} chars, ${elapsed}s)`);
+            const nodeResult = {
+                currentNode: nodeName,
+                messages: [`[${nodeName}] Complete (${result.result.length} chars, ${elapsed}s)`],
+            };
+            // Human-in-the-loop: interrupt after node execution for review
+            if (shouldInterrupt(nodeName, state.approvalMode)) {
+                log.info('Interrupting for human approval');
+                interrupt({
+                    node: nodeName,
+                    result: result.result.slice(0, 500),
+                    message: `Node "${nodeName}" completed. Approve to continue.`,
+                });
+            }
+            return nodeResult;
+        }
+        catch (err) {
+            // Re-throw LangGraph control-flow exceptions (interrupt, Command, etc.)
+            if (isGraphBubbleUp(err))
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+            log.error(`${message} (after ${elapsed}s)`);
+            return {
+                currentNode: nodeName,
+                error: message,
+                messages: [`[${nodeName}] Error: ${message}`],
+            };
+        }
+    };
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/plan.node.d.ts

@@ -0,0 +1,7 @@
+import type { IAgentExecutor } from '../../../../../application/ports/output/agent-executor.interface.js';
+/**
+ * Creates the plan node that generates an implementation plan (plan.yaml)
+ * and task breakdown with TDD cycles (tasks.yaml) from spec and research.
+ */
+export declare function createPlanNode(executor: IAgentExecutor): (state: import("../state.js").FeatureAgentState) => Promise<Partial<import("../state.js").FeatureAgentState>>;
+//# sourceMappingURL=plan.node.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/nodes/plan.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.node.d.ts","sourceRoot":"","sources":["../../../../../../../src/infrastructure/services/agents/feature-agent/nodes/plan.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wDAAwD,CAAC;AAI7F;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,iHAEtD"}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/plan.node.js

@@ -0,0 +1,9 @@
+import { executeNode } from './node-helpers.js';
+import { buildPlanPrompt } from './prompts/plan.prompt.js';
+/**
+ * Creates the plan node that generates an implementation plan (plan.yaml)
+ * and task breakdown with TDD cycles (tasks.yaml) from spec and research.
+ */
+export function createPlanNode(executor) {
+    return executeNode('plan', executor, buildPlanPrompt);
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/prompts/analyze.prompt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Analyze Phase Prompt
+ *
+ * Instructs the agent to analyze the repository and user query,
+ * then write findings to spec.yaml with complexity estimate and affected areas.
+ */
+import type { FeatureAgentState } from '../../state.js';
+export declare function buildAnalyzePrompt(state: FeatureAgentState): string;
+//# sourceMappingURL=analyze.prompt.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/nodes/prompts/analyze.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.prompt.d.ts","sourceRoot":"","sources":["../../../../../../../../src/infrastructure/services/agents/feature-agent/nodes/prompts/analyze.prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAuFnE"}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/prompts/analyze.prompt.js

@@ -0,0 +1,94 @@
+/**
+ * Analyze Phase Prompt
+ *
+ * Instructs the agent to analyze the repository and user query,
+ * then write findings to spec.yaml with complexity estimate and affected areas.
+ */
+import { readSpecFile } from '../node-helpers.js';
+export function buildAnalyzePrompt(state) {
+    const existingSpec = readSpecFile(state.specDir, 'spec.yaml');
+    return `You are a senior software architect performing the ANALYSIS phase of feature development.
+
+## Your Task
+
+1. Read and understand the feature request from the spec below
+2. Explore this repository thoroughly — understand the project structure, architecture, key technologies, patterns, and conventions
+3. Assess complexity and identify which areas of the codebase are affected
+4. Write your complete analysis to the spec YAML file
+
+## Feature Request (from spec.yaml)
+
+${existingSpec || `Feature ID: ${state.featureId}`}
+
+## What to Analyze
+
+- **Project structure**: directories, modules, layers, organization patterns
+- **Architecture**: design patterns, dependency flow, separation of concerns
+- **Technologies**: languages, frameworks, libraries, build tools
+- **Conventions**: naming, file organization, testing patterns, code style
+- **Affected areas**: which parts of the codebase this feature will touch and why
+- **Dependencies**: existing code/libraries this feature depends on
+- **Complexity**: estimate effort as S (hours), M (days), L (week+), XL (multi-week)
+
+## Output Instructions
+
+Write your analysis to: ${state.specDir}/spec.yaml
+
+You MUST write the COMPLETE file (not a partial update). Preserve the existing name/number/branch fields and update everything else. Use this YAML structure:
+
+  name: (keep existing)
+  number: (keep existing)
+  branch: (keep existing)
+  oneLiner: (concise one-line description of the feature)
+  summary: >
+    (2-3 sentence summary of what this feature involves based on your analysis)
+  phase: Analysis
+  sizeEstimate: (S | M | L | XL)
+
+  relatedFeatures: []
+
+  technologies:
+    - (list each technology relevant to implementing this feature)
+
+  relatedLinks: []
+
+  openQuestions: []
+
+  content: |
+    ## Problem Statement
+
+    (What problem does this feature solve? Reference specific current limitations.)
+
+    ## Codebase Analysis
+
+    ### Project Structure
+    (Key directories, their purposes, and how they relate)
+
+    ### Architecture Patterns
+    (Design patterns, dependency rules, layering)
+
+    ### Relevant Technologies
+    (Frameworks and libraries in use that are relevant to this feature)
+
+    ## Affected Areas
+
+    | Area | Impact | Reasoning |
+    | ---- | ------ | --------- |
+    | (path/module) | (High/Medium/Low) | (why this area is affected) |
+
+    ## Dependencies
+
+    (What existing code, libraries, or infrastructure does this feature depend on?)
+
+    ## Size Estimate
+
+    **(S/M/L/XL)** — (justify your estimate with specific reasoning)
+
+## Constraints
+
+- Write ONLY to ${state.specDir}/spec.yaml
+- Do NOT create any other files
+- Do NOT modify any source code
+- Do NOT start implementing the feature
+- Keep your analysis thorough but concise`;
+}

package/dist/src/infrastructure/services/agents/feature-agent/nodes/prompts/implement.prompt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Implement Phase Prompt — PLACEHOLDER
+ *
+ * The implement phase is not yet wired up. This returns a programming joke
+ * to clearly signal it's a placeholder while keeping the graph pipeline intact.
+ */
+export declare function getImplementPlaceholderJoke(): string;
+//# sourceMappingURL=implement.prompt.d.ts.map