@nathapp/nax 0.50.2 → 0.51.0

package/src/execution/runner.ts

@@ -1,265 +0,0 @@
-/**
- * Execution Runner — The Core Loop
- *
- * Orchestrates the agent loop:
- * 1. Load PRD → find next story/batch
- * 2. Run pipeline for each story/batch
- * 3. Handle pipeline results (escalate, mark complete, etc.)
- * 4. Loop until complete or blocked
- *
- * Delegates to extracted modules for each phase:
- * - runner-setup.ts: Initial setup (PRD, status, loggers)
- * - runner-execution.ts: Parallel/sequential execution
- * - runner-completion.ts: Acceptance loop, hooks, metrics
- */
-
-import { sweepFeatureSessions } from "../agents/acp/adapter";
-import { createAgentRegistry } from "../agents/registry";
-import type { NaxConfig } from "../config";
-import type { LoadedHooksConfig } from "../hooks";
-import { fireHook } from "../hooks";
-import { getSafeLogger } from "../logger";
-import type { PipelineEventEmitter } from "../pipeline/events";
-import { countStories, isComplete } from "../prd";
-import { stopHeartbeat } from "./crash-recovery";
-import type { ParallelExecutorOptions, ParallelExecutorResult } from "./parallel-executor";
-import { type RunnerCompletionOptions, runCompletionPhase } from "./runner-completion";
-import { type RunnerExecutionOptions, runExecutionPhase } from "./runner-execution";
-import { type RunnerSetupOptions, runSetupPhase } from "./runner-setup";
-
-/**
- * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- * @internal - test use only.
- */
-export const _runnerDeps = {
-  fireHook,
-  // Injectable for tests — avoids dynamic-import module-cache issues in bun test (bun 1.3.9+)
-  runParallelExecution: null as
-    | null
-    | ((options: ParallelExecutorOptions, prd: import("../prd").PRD) => Promise<ParallelExecutorResult>),
-};
-
-// Re-export for backward compatibility
-export { resolveMaxAttemptsOutcome } from "./escalation";
-
-/** Run options */
-
-export interface RunOptions {
-  /** Path to prd.json */
-  prdPath: string;
-  /** Working directory */
-  workdir: string;
-  /** Ngent config */
-  config: NaxConfig;
-  /** Hooks config */
-  hooks: LoadedHooksConfig;
-  /** Feature name */
-  feature: string;
-  /** Feature directory (for progress logging) */
-  featureDir?: string;
-  /** Dry run */
-  dryRun: boolean;
-  /** Enable story batching (default: true) */
-  useBatch?: boolean;
-  /** Max parallel sessions: undefined=sequential, 0=auto-detect, N>0=cap at N */
-  parallel?: number;
-  /** Optional event emitter for TUI integration */
-  eventEmitter?: PipelineEventEmitter;
-  /** Path to write a machine-readable JSON status file */
-  statusFile: string;
-  /** Path to JSONL log file (for crash recovery) */
-  logFilePath?: string;
-  /** Formatter verbosity mode for headless stdout (default: "normal") */
-  formatterMode?: "quiet" | "normal" | "verbose" | "json";
-  /** Whether running in headless mode (vs TUI mode) */
-  headless?: boolean;
-  /** Skip precheck validations (for advanced users) */
-  skipPrecheck?: boolean;
-}
-
-/** Run result */
-export interface RunResult {
-  success: boolean;
-  iterations: number;
-  storiesCompleted: number;
-  totalCost: number;
-  durationMs: number;
-}
-
-/**
- * Main execution loop
- */
-export async function run(options: RunOptions): Promise<RunResult> {
-  const {
-    prdPath,
-    workdir,
-    config,
-    hooks,
-    feature,
-    featureDir,
-    dryRun,
-    useBatch = true,
-    eventEmitter,
-    statusFile,
-    parallel,
-    logFilePath,
-    formatterMode = "normal",
-    headless = false,
-    skipPrecheck = false,
-  } = options;
-  const startTime = Date.now();
-  const runStartedAt = new Date().toISOString();
-  const runId = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-  let iterations = 0;
-  let storiesCompleted = 0;
-  let totalCost = 0;
-  // biome-ignore lint/suspicious/noExplicitAny: Metrics array type varies
-  const allStoryMetrics: any[] = [];
-
-  const logger = getSafeLogger();
-
-  // Create protocol-aware agent registry (ACP wiring — ACP-003/registry-wiring)
-  const registry = createAgentRegistry(config);
-  const agentGetFn = registry.getAgent.bind(registry);
-
-  // Declare prd before crash handler setup to avoid TDZ if SIGTERM arrives during setup
-  // biome-ignore lint/suspicious/noExplicitAny: PRD type initialized during setup
-  let prd: any | undefined;
-
-  // ── Phase 1: Setup ──────────────────────────────────────────────────────────
-  const setupResult = await runSetupPhase({
-    prdPath,
-    workdir,
-    config,
-    hooks,
-    feature,
-    featureDir,
-    dryRun,
-    statusFile,
-    logFilePath,
-    runId,
-    startedAt: runStartedAt,
-    startTime,
-    skipPrecheck,
-    headless,
-    formatterMode,
-    agentGetFn,
-    getTotalCost: () => totalCost,
-    getIterations: () => iterations,
-    // BUG-017: Pass getters for run.complete event on SIGTERM
-    getStoriesCompleted: () => storiesCompleted,
-    getTotalStories: () => (prd ? countStories(prd).total : 0),
-  });
-
-  const { statusWriter, pidRegistry, cleanupCrashHandlers, pluginRegistry, interactionChain } = setupResult;
-  prd = setupResult.prd;
-
-  try {
-    // ── Phase 2: Execution ──────────────────────────────────────────────────────
-    const executionResult = await runExecutionPhase(
-      {
-        prdPath,
-        workdir,
-        config,
-        hooks,
-        feature,
-        featureDir,
-        dryRun,
-        useBatch,
-        eventEmitter,
-        statusWriter,
-        statusFile,
-        logFilePath,
-        runId,
-        startedAt: runStartedAt,
-        startTime,
-        formatterMode,
-        headless,
-        parallel,
-        runParallelExecution: _runnerDeps.runParallelExecution ?? undefined,
-        agentGetFn,
-        pidRegistry,
-      },
-      prd,
-      pluginRegistry,
-    );
-
-    prd = executionResult.prd;
-    iterations = executionResult.iterations;
-    storiesCompleted = executionResult.storiesCompleted;
-    totalCost = executionResult.totalCost;
-    allStoryMetrics.push(...executionResult.allStoryMetrics);
-
-    // Return early if parallel execution completed everything
-    if (executionResult.completedEarly && executionResult.durationMs !== undefined) {
-      return {
-        success: isComplete(prd),
-        iterations,
-        storiesCompleted,
-        totalCost,
-        durationMs: executionResult.durationMs,
-      };
-    }
-
-    // ── Phase 3: Completion ────────────────────────────────────────────────────
-    const completionResult = await runCompletionPhase({
-      config,
-      hooks,
-      feature,
-      workdir,
-      prdPath,
-      statusFile,
-      logFilePath,
-      runId,
-      startedAt: runStartedAt,
-      startTime,
-      formatterMode,
-      headless,
-      featureDir,
-      prd,
-      allStoryMetrics,
-      totalCost,
-      storiesCompleted,
-      iterations,
-      statusWriter,
-      pluginRegistry,
-      eventEmitter,
-      agentGetFn,
-    });
-
-    const { durationMs } = completionResult;
-
-    return {
-      success: isComplete(prd),
-      iterations,
-      storiesCompleted,
-      totalCost,
-      durationMs,
-    };
-  } finally {
-    // Stop heartbeat on any exit (US-007)
-    stopHeartbeat();
-    // Cleanup crash handlers (MEM-1 fix)
-    cleanupCrashHandlers();
-
-    // Sweep any remaining open ACP sessions for this feature
-    await sweepFeatureSessions(workdir, feature).catch(() => {});
-
-    // Execute cleanup operations
-    const { cleanupRun } = await import("./lifecycle/run-cleanup");
-    await cleanupRun({
-      runId,
-      startTime,
-      totalCost,
-      storiesCompleted,
-      prd,
-      pluginRegistry,
-      workdir,
-      interactionChain,
-    });
-  }
-}
-
-// Re-exports for backward compatibility with existing test imports
-export { groupStoriesIntoBatches, type StoryBatch } from "./batching";
-export { escalateTier } from "./escalation";

package/src/execution/sequential-executor.ts

@@ -1,219 +0,0 @@
-/** Sequential Story Executor (ADR-005, Phase 4) — main execution loop. */
-
-import { checkCostExceeded, checkCostWarning, checkPreMerge, isTriggerEnabled } from "../interaction/triggers";
-import { getSafeLogger } from "../logger";
-import type { StoryMetrics } from "../metrics";
-import { pipelineEventBus } from "../pipeline/event-bus";
-import { runPipeline } from "../pipeline/runner";
-import { postRunPipeline, preRunPipeline } from "../pipeline/stages";
-import { wireEventsWriter } from "../pipeline/subscribers/events-writer";
-import { wireHooks } from "../pipeline/subscribers/hooks";
-import { wireInteraction } from "../pipeline/subscribers/interaction";
-import { wireRegistry } from "../pipeline/subscribers/registry";
-import { wireReporters } from "../pipeline/subscribers/reporters";
-import type { PipelineContext } from "../pipeline/types";
-import { generateHumanHaltSummary, isComplete, isStalled, loadPRD } from "../prd";
-import type { PRD } from "../prd/types";
-import { startHeartbeat } from "./crash-recovery";
-import { captureRunStartRef, runDeferredReview } from "./deferred-review";
-import type { DeferredReviewResult } from "./deferred-review";
-import type { SequentialExecutionContext, SequentialExecutionResult } from "./executor-types";
-import { runIteration } from "./iteration-runner";
-import { selectNextStories } from "./story-selector";
-
-export type { SequentialExecutionContext, SequentialExecutionResult } from "./executor-types";
-
-export async function executeSequential(
-  ctx: SequentialExecutionContext,
-  initialPrd: PRD,
-): Promise<SequentialExecutionResult> {
-  const logger = getSafeLogger();
-  let [prd, prdDirty, iterations, storiesCompleted, totalCost, lastStoryId, currentBatchIndex] = [
-    initialPrd,
-    false,
-    0,
-    0,
-    0,
-    null as string | null,
-    0,
-  ];
-  const allStoryMetrics: StoryMetrics[] = [];
-  let warningSent = false;
-  let deferredReview: DeferredReviewResult | undefined;
-
-  const runStartRef = await captureRunStartRef(ctx.workdir);
-
-  pipelineEventBus.clear();
-  wireHooks(pipelineEventBus, ctx.hooks, ctx.workdir, ctx.feature);
-  wireReporters(pipelineEventBus, ctx.pluginRegistry, ctx.runId, ctx.startTime);
-  wireInteraction(pipelineEventBus, ctx.interactionChain, ctx.config);
-  wireEventsWriter(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
-  wireRegistry(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
-
-  const buildResult = (exitReason: SequentialExecutionResult["exitReason"]): SequentialExecutionResult => ({
-    prd,
-    iterations,
-    storiesCompleted,
-    totalCost,
-    allStoryMetrics,
-    exitReason,
-    deferredReview,
-  });
-
-  startHeartbeat(
-    ctx.statusWriter,
-    () => totalCost,
-    () => iterations,
-    ctx.logFilePath,
-  );
-
-  try {
-    // Pre-run pipeline (acceptance test setup with RED gate)
-    logger?.info("execution", "Running pre-run pipeline (acceptance test setup)");
-    const preRunCtx: PipelineContext = {
-      config: ctx.config,
-      effectiveConfig: ctx.config,
-      prd,
-      workdir: ctx.workdir,
-      featureDir: ctx.featureDir,
-      story: prd.userStories[0],
-      stories: prd.userStories,
-      routing: { complexity: "simple", modelTier: "fast", testStrategy: "test-after", reasoning: "" },
-      hooks: ctx.hooks,
-    };
-    await runPipeline(preRunPipeline, preRunCtx, ctx.eventEmitter);
-
-    while (iterations < ctx.config.execution.maxIterations) {
-      iterations++;
-      if (Math.round(process.memoryUsage().heapUsed / 1024 / 1024) > 1024)
-        logger?.warn("execution", "High memory usage detected");
-      if (prdDirty) {
-        prd = await loadPRD(ctx.prdPath);
-        prdDirty = false;
-      }
-      if (isComplete(prd)) {
-        // pre-merge trigger: prompt before completing the run
-        if (ctx.interactionChain && isTriggerEnabled("pre-merge", ctx.config)) {
-          const shouldProceed = await checkPreMerge(
-            { featureName: ctx.feature, totalStories: prd.userStories.length, cost: totalCost },
-            ctx.config,
-            ctx.interactionChain,
-          );
-          if (!shouldProceed) {
-            return buildResult("pre-merge-aborted");
-          }
-        }
-        deferredReview = await runDeferredReview(ctx.workdir, ctx.config.review, ctx.pluginRegistry, runStartRef);
-        return buildResult("completed");
-      }
-
-      const selected = selectNextStories(prd, ctx.config, ctx.batchPlan, currentBatchIndex, lastStoryId, ctx.useBatch);
-      if (!selected) return buildResult("no-stories");
-      if (!selected.selection) {
-        currentBatchIndex = selected.nextBatchIndex;
-        continue;
-      }
-      currentBatchIndex = selected.nextBatchIndex;
-      const { selection } = selected;
-      if (!ctx.useBatch) lastStoryId = selection.story.id;
-
-      if (totalCost >= ctx.config.execution.costLimit) {
-        const shouldProceed =
-          ctx.interactionChain && isTriggerEnabled("cost-exceeded", ctx.config)
-            ? await checkCostExceeded(
-                { featureName: ctx.feature, cost: totalCost, limit: ctx.config.execution.costLimit },
-                ctx.config,
-                ctx.interactionChain,
-              )
-            : false;
-        if (!shouldProceed) {
-          pipelineEventBus.emit({
-            type: "run:paused",
-            reason: `Cost limit reached: $${totalCost.toFixed(2)}`,
-            storyId: selection.story.id,
-            cost: totalCost,
-          });
-          return buildResult("cost-limit");
-        }
-        pipelineEventBus.emit({ type: "run:resumed", feature: ctx.feature });
-      }
-
-      pipelineEventBus.emit({
-        type: "story:started",
-        storyId: selection.story.id,
-        story: selection.story,
-        workdir: ctx.workdir,
-        modelTier: selection.routing.modelTier,
-        agent: ctx.config.autoMode.defaultAgent,
-        iteration: iterations,
-      });
-
-      const iter = await runIteration(ctx, prd, selection, iterations, totalCost, allStoryMetrics);
-      [prd, storiesCompleted, totalCost, prdDirty] = [
-        iter.prd,
-        storiesCompleted + iter.storiesCompletedDelta,
-        totalCost + iter.costDelta,
-        iter.prdDirty,
-      ];
-
-      // ENH-009: Decomposition is not real work — don't charge an iteration.
-      // Emit story:decomposed event and immediately continue so sub-stories
-      // are picked up on the very next loop turn.
-      if (iter.finalAction === "decomposed") {
-        iterations--;
-        pipelineEventBus.emit({
-          type: "story:decomposed",
-          storyId: selection.story.id,
-          story: selection.story,
-          subStoryCount: iter.subStoryCount ?? 0,
-        });
-        if (iter.prdDirty) {
-          prd = await loadPRD(ctx.prdPath);
-          prdDirty = false;
-        }
-        ctx.statusWriter.setPrd(prd);
-        continue;
-      }
-
-      if (ctx.interactionChain && isTriggerEnabled("cost-warning", ctx.config) && !warningSent) {
-        const costLimit = ctx.config.execution.costLimit;
-        const triggerCfg = ctx.config.interaction?.triggers?.["cost-warning"];
-        const threshold = typeof triggerCfg === "object" ? (triggerCfg.threshold ?? 0.8) : 0.8;
-        if (totalCost >= costLimit * threshold) {
-          await checkCostWarning(
-            { featureName: ctx.feature, cost: totalCost, limit: costLimit },
-            ctx.config,
-            ctx.interactionChain,
-          );
-          warningSent = true;
-        }
-      }
-
-      if (iter.prdDirty) {
-        prd = await loadPRD(ctx.prdPath);
-        prdDirty = false;
-      }
-      ctx.statusWriter.setPrd(prd);
-      ctx.statusWriter.setCurrentStory(null);
-      await ctx.statusWriter.update(totalCost, iterations);
-
-      if (isStalled(prd)) {
-        pipelineEventBus.emit({ type: "run:paused", reason: "All remaining stories blocked", cost: totalCost });
-        return buildResult("stalled");
-      }
-      if (ctx.config.execution.iterationDelayMs > 0) await Bun.sleep(ctx.config.execution.iterationDelayMs);
-    }
-
-    // Post-run pipeline (acceptance tests)
-    logger?.info("execution", "Running post-run pipeline (acceptance tests)");
-    await runPipeline(
-      postRunPipeline,
-      { config: ctx.config, prd, workdir: ctx.workdir, story: prd.userStories[0] } as unknown as PipelineContext,
-      ctx.eventEmitter,
-    );
-
-    return buildResult("max-iterations");
-  } finally {
-    // Cleanup moved to runner.ts (RL-007): exit summary and heartbeat stop are owned by runner
-  }
-}