@nathapp/nax 0.18.1

package/src/optimizer/noop.optimizer.ts

@@ -0,0 +1,24 @@
+import type { IPromptOptimizer, PromptOptimizerInput, PromptOptimizerResult } from "./types.js";
+import { estimateTokens } from "./types.js";
+
+/**
+ * Passthrough optimizer that returns the prompt unchanged.
+ *
+ * Used as the default when optimization is disabled or
+ * when the configured strategy is unrecognized.
+ */
+export class NoopOptimizer implements IPromptOptimizer {
+  public readonly name = "noop";
+
+  async optimize(input: PromptOptimizerInput): Promise<PromptOptimizerResult> {
+    const tokens = estimateTokens(input.prompt);
+
+    return {
+      prompt: input.prompt,
+      originalTokens: tokens,
+      optimizedTokens: tokens,
+      savings: 0,
+      appliedRules: [],
+    };
+  }
+}

package/src/optimizer/rule-based.optimizer.ts

@@ -0,0 +1,248 @@
+import type { IPromptOptimizer, PromptOptimizerInput, PromptOptimizerResult } from "./types.js";
+import { estimateTokens } from "./types.js";
+
+interface RuleBasedConfig {
+  stripWhitespace?: boolean;
+  compactCriteria?: boolean;
+  deduplicateContext?: boolean;
+  maxPromptTokens?: number;
+}
+
+const DEFAULT_CONFIG: RuleBasedConfig = {
+  stripWhitespace: true,
+  compactCriteria: true,
+  deduplicateContext: true,
+  maxPromptTokens: 8000,
+};
+
+/**
+ * Rule-based optimizer that applies deterministic transformations
+ * to reduce token usage without external dependencies.
+ */
+export class RuleBasedOptimizer implements IPromptOptimizer {
+  public readonly name = "rule-based";
+
+  async optimize(input: PromptOptimizerInput): Promise<PromptOptimizerResult> {
+    const originalTokens = estimateTokens(input.prompt);
+    const appliedRules: string[] = [];
+
+    let optimized = input.prompt;
+
+    // Get config with defaults
+    const config = {
+      ...DEFAULT_CONFIG,
+      ...input.config.optimizer?.strategies?.["rule-based"],
+    };
+
+    // Rule 1: Strip whitespace
+    if (config.stripWhitespace) {
+      const before = optimized;
+      optimized = this.stripWhitespace(optimized);
+      if (optimized !== before) {
+        appliedRules.push("stripWhitespace");
+      }
+    }
+
+    // Rule 2: Compact acceptance criteria
+    if (config.compactCriteria) {
+      const before = optimized;
+      optimized = this.compactCriteria(optimized);
+      if (optimized !== before) {
+        appliedRules.push("compactCriteria");
+      }
+    }
+
+    // Rule 3: Deduplicate context
+    if (config.deduplicateContext && input.contextMarkdown) {
+      const before = optimized;
+      optimized = this.deduplicateContext(optimized, input.contextMarkdown);
+      if (optimized !== before) {
+        appliedRules.push("deduplicateContext");
+      }
+    }
+
+    // Rule 4: Enforce max prompt tokens
+    if (config.maxPromptTokens) {
+      const currentTokens = estimateTokens(optimized);
+      if (currentTokens > config.maxPromptTokens) {
+        optimized = this.trimToMaxTokens(optimized, config.maxPromptTokens);
+        appliedRules.push("maxPromptTokens");
+      }
+    }
+
+    const optimizedTokens = estimateTokens(optimized);
+    const savings = originalTokens > 0 ? (originalTokens - optimizedTokens) / originalTokens : 0;
+
+    return {
+      prompt: optimized,
+      originalTokens,
+      optimizedTokens,
+      savings,
+      appliedRules,
+    };
+  }
+
+  /**
+   * Collapse multiple blank lines to single blank line and trim trailing whitespace.
+   */
+  private stripWhitespace(prompt: string): string {
+    return (
+      prompt
+        // Trim trailing whitespace from each line
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        // Collapse 3+ consecutive newlines to 2
+        .replace(/\n{3,}/g, "\n\n")
+    );
+  }
+
+  /**
+   * Convert verbose acceptance criteria to terse bullet format.
+   */
+  private compactCriteria(prompt: string): string {
+    return (
+      prompt
+        // Remove verbose prefixes
+        .replace(/The user should be able to /gi, "")
+        .replace(/The system must /gi, "")
+        .replace(/The system should /gi, "")
+        .replace(/When the /gi, "")
+        .replace(/When a /gi, "")
+        // Compact common verbose patterns
+        .replace(/it should validate all fields/gi, "validate all fields")
+        .replace(/display an error message/gi, "show error")
+        .replace(/error message/gi, "error")
+    );
+  }
+
+  /**
+   * Remove context sections that duplicate constitution content.
+   */
+  private deduplicateContext(prompt: string, contextMarkdown: string): string {
+    // Find context section
+    const contextSectionMatch = prompt.match(/# Context\n([\s\S]*?)(?=\n#|$)/i);
+    if (!contextSectionMatch) {
+      return prompt;
+    }
+
+    const contextSection = contextSectionMatch[1];
+    const contextLines = contextSection.split("\n");
+
+    // Remove lines that appear in constitution
+    const dedupedLines = contextLines.filter((line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return true; // Keep blank lines for now
+      // Check if this line appears in the context markdown (which may duplicate constitution)
+      return !contextMarkdown.includes(trimmed);
+    });
+
+    // If we removed content, replace the context section
+    if (dedupedLines.length < contextLines.length) {
+      const newContextSection = dedupedLines.join("\n");
+      return prompt.replace(contextSectionMatch[0], `# Context\n${newContextSection}`);
+    }
+
+    return prompt;
+  }
+
+  /**
+   * Trim context aggressively if prompt exceeds max tokens.
+   * Preserve Task and Acceptance Criteria sections.
+   */
+  private trimToMaxTokens(prompt: string, maxTokens: number): string {
+    const currentTokens = estimateTokens(prompt);
+    if (currentTokens <= maxTokens) {
+      return prompt;
+    }
+
+    // Extract sections
+    const sections = this.extractSections(prompt);
+    const targetChars = maxTokens * 4; // Reverse of token estimation
+    const trimmedMessage = "\n... (context trimmed)";
+
+    // Preserve task and AC, trim context
+    let result = "";
+    let remainingChars = targetChars;
+
+    // Add task section (always preserve)
+    if (sections.task) {
+      result += sections.task;
+      remainingChars -= sections.task.length;
+    }
+
+    // Add AC section (always preserve)
+    if (sections.acceptanceCriteria) {
+      result += sections.acceptanceCriteria;
+      remainingChars -= sections.acceptanceCriteria.length;
+    }
+
+    // Add as much context as fits
+    if (sections.context && remainingChars > 0) {
+      // Reserve space for the trimmed message if we're going to add it
+      const reserveForMessage = sections.context.length > remainingChars ? trimmedMessage.length : 0;
+      const maxContextChars = Math.max(0, remainingChars - reserveForMessage);
+      const trimmedContext = sections.context.substring(0, maxContextChars);
+      result += trimmedContext;
+      if (trimmedContext.length < sections.context.length) {
+        result += trimmedMessage;
+      }
+    }
+
+    // Add other sections if there's room
+    if (sections.other && remainingChars > sections.other.length) {
+      result += sections.other;
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract common prompt sections for targeted trimming.
+   */
+  private extractSections(prompt: string): {
+    task?: string;
+    context?: string;
+    acceptanceCriteria?: string;
+    other?: string;
+  } {
+    const sections: {
+      task?: string;
+      context?: string;
+      acceptanceCriteria?: string;
+      other?: string;
+    } = {};
+
+    const taskMatch = prompt.match(/# Task\n([\s\S]*?)(?=\n#|$)/i);
+    if (taskMatch) {
+      sections.task = taskMatch[0];
+    }
+
+    const contextMatch = prompt.match(/# Context\n([\s\S]*?)(?=\n#|$)/i);
+    if (contextMatch) {
+      sections.context = contextMatch[0];
+    }
+
+    const acMatch = prompt.match(/# Acceptance Criteria\n([\s\S]*?)(?=\n#|$)/i);
+    if (acMatch) {
+      sections.acceptanceCriteria = acMatch[0];
+    }
+
+    // Collect everything else
+    let other = prompt;
+    if (sections.task) {
+      other = other.replace(sections.task, "");
+    }
+    if (sections.context) {
+      other = other.replace(sections.context, "");
+    }
+    if (sections.acceptanceCriteria) {
+      other = other.replace(sections.acceptanceCriteria, "");
+    }
+    if (other.trim()) {
+      sections.other = other;
+    }
+
+    return sections;
+  }
+}

package/src/optimizer/types.ts

@@ -0,0 +1,53 @@
+import type { NaxConfig } from "../config/schema.js";
+import type { UserStory } from "../prd/types.js";
+
+/**
+ * Interface for prompt optimizers.
+ *
+ * Optimizers transform assembled prompts to reduce token usage while
+ * preserving semantic meaning and all technical requirements.
+ */
+export interface IPromptOptimizer {
+  /** Unique optimizer name */
+  name: string;
+
+  /**
+   * Optimize a prompt before it is sent to the coding agent.
+   *
+   * Implementations MUST preserve all technical requirements,
+   * acceptance criteria semantics, and code references.
+   */
+  optimize(input: PromptOptimizerInput): Promise<PromptOptimizerResult>;
+}
+
+export interface PromptOptimizerInput {
+  /** Assembled prompt from promptStage */
+  prompt: string;
+  /** Stories being executed (for context) */
+  stories: UserStory[];
+  /** Raw context markdown (pre-assembly, for dedup detection) */
+  contextMarkdown?: string;
+  /** Nax configuration */
+  config: NaxConfig;
+}
+
+export interface PromptOptimizerResult {
+  /** Optimized prompt */
+  prompt: string;
+  /** Estimated token count before optimization */
+  originalTokens: number;
+  /** Estimated token count after optimization */
+  optimizedTokens: number;
+  /** Savings percentage (0-1) */
+  savings: number;
+  /** List of applied optimization rules/passes */
+  appliedRules: string[];
+}
+
+/**
+ * Estimate token count using simple heuristic.
+ * ~4 chars per token for English text (rough estimate).
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}

package/src/pipeline/events.ts

@@ -0,0 +1,130 @@
+/**
+ * Pipeline Event Emitter
+ *
+ * Typed event emitter for TUI integration. Emits lifecycle events during
+ * pipeline execution so the TUI can display real-time progress.
+ */
+
+import { EventEmitter } from "node:events";
+import type { UserStory } from "../prd/types";
+import type { RoutingResult, StageResult } from "./types";
+
+/**
+ * Summary of a completed run.
+ */
+export interface RunSummary {
+  /** Total number of stories processed */
+  storiesProcessed: number;
+  /** Number of stories completed successfully */
+  storiesCompleted: number;
+  /** Number of stories failed */
+  storiesFailed: number;
+  /** Number of stories skipped */
+  storiesSkipped: number;
+  /** Total cost in USD */
+  totalCost: number;
+  /** Total duration in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Pipeline event types matching v0.6 spec.
+ *
+ * Events:
+ * - story:start — Story execution begins
+ * - story:complete — Story execution ends (success/fail/skip)
+ * - story:escalate — Story escalated to higher tier
+ * - stage:enter — Pipeline stage starts
+ * - stage:exit — Pipeline stage finishes
+ * - run:complete — Full run completes
+ */
+export interface PipelineEvents {
+  "story:start": (story: UserStory, routing: RoutingResult) => void;
+  "story:complete": (story: UserStory, result: StageResult) => void;
+  "story:escalate": (story: UserStory, fromTier: string, toTier: string) => void;
+  "stage:enter": (stage: string, story: UserStory) => void;
+  "stage:exit": (stage: string, result: StageResult) => void;
+  "run:complete": (summary: RunSummary) => void;
+}
+
+/**
+ * Typed event emitter for pipeline events.
+ *
+ * Wraps Node.js EventEmitter with TypeScript types for pipeline lifecycle
+ * events. The TUI subscribes to these events to update UI state in real-time.
+ *
+ * @example
+ * ```ts
+ * const emitter = new PipelineEventEmitter();
+ *
+ * emitter.on('story:start', (story, routing) => {
+ *   // Handle story start: ${story.id} with ${routing.modelTier}
+ * });
+ *
+ * emitter.on('story:complete', (story, result) => {
+ *   // Handle story completion: ${story.id} - ${result.action}
+ * });
+ *
+ * // In pipeline runner:
+ * emitter.emit('story:start', story, routing);
+ * ```
+ */
+export class PipelineEventEmitter {
+  private emitter = new EventEmitter();
+
+  /**
+   * Subscribe to a pipeline event.
+   *
+   * @param event - Event name
+   * @param listener - Event handler
+   */
+  on<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
+    this.emitter.on(event, listener as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Subscribe to an event once (auto-unsubscribe after first emission).
+   *
+   * @param event - Event name
+   * @param listener - Event handler
+   */
+  once<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
+    this.emitter.once(event, listener as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Unsubscribe from an event.
+   *
+   * @param event - Event name
+   * @param listener - Event handler to remove
+   */
+  off<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
+    this.emitter.off(event, listener as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Emit a pipeline event.
+   *
+   * Called internally by the pipeline runner. External code should only
+   * subscribe to events, not emit them.
+   *
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  emit<E extends keyof PipelineEvents>(event: E, ...args: Parameters<PipelineEvents[E]>): void {
+    this.emitter.emit(event, ...args);
+  }
+
+  /**
+   * Remove all listeners for a specific event or all events.
+   *
+   * @param event - Optional event name (if not provided, removes all listeners)
+   */
+  removeAllListeners(event?: keyof PipelineEvents): void {
+    if (event) {
+      this.emitter.removeAllListeners(event);
+    } else {
+      this.emitter.removeAllListeners();
+    }
+  }
+}

package/src/pipeline/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Pipeline Module
+ *
+ * Composable stage-based execution pipeline.
+ */
+
+export type {
+  PipelineContext,
+  PipelineStage,
+  StageResult,
+  StageAction,
+  RoutingResult,
+} from "./types";
+
+export { runPipeline } from "./runner";
+export type { PipelineRunResult } from "./runner";
+
+export { PipelineEventEmitter } from "./events";
+export type { PipelineEvents, RunSummary } from "./events";

package/src/pipeline/runner.ts

@@ -0,0 +1,161 @@
+/**
+ * Pipeline Runner
+ *
+ * Executes a sequence of pipeline stages, handling stage results and
+ * controlling the flow (continue/skip/fail/escalate/pause).
+ */
+
+import { getLogger } from "../logger";
+import type { PipelineEventEmitter } from "./events";
+import type { PipelineContext, PipelineStage, StageResult } from "./types";
+
+/**
+ * Pipeline execution result.
+ */
+export interface PipelineRunResult {
+  /** Whether the pipeline completed successfully (reached the end) */
+  success: boolean;
+  /** Final action taken (e.g., "skip", "fail", "escalate", "pause", "complete") */
+  finalAction: "complete" | "skip" | "fail" | "escalate" | "pause";
+  /** Reason for non-complete outcomes */
+  reason?: string;
+  /** Stage where the pipeline stopped (if not completed) */
+  stoppedAtStage?: string;
+  /** Updated context after pipeline execution */
+  context: PipelineContext;
+}
+
+/**
+ * Run a pipeline of stages against a context.
+ *
+ * Iterates through each enabled stage, executing them in sequence.
+ * Stops early if a stage returns skip/fail/escalate/pause.
+ *
+ * **IMPORTANT - Context Mutation Contract:**
+ * This function mutates the input context in-place. Stages modify the context
+ * object directly (e.g., `ctx.constitution = result`, `ctx.routing = routing`).
+ * The returned `context` in PipelineRunResult is the same object reference,
+ * not a clone. If you need immutability, clone the context before calling
+ * runPipeline.
+ *
+ * @param stages - Array of pipeline stages to execute
+ * @param context - Initial pipeline context (WILL BE MUTATED IN-PLACE)
+ * @param eventEmitter - Optional event emitter for TUI integration
+ * @returns Pipeline execution result with mutated context
+ *
+ * @example
+ * ```ts
+ * const stages = [routingStage, contextStage, executionStage];
+ * const ctx = createInitialContext(); // { config, prd, story, ... }
+ *
+ * const result = await runPipeline(stages, ctx);
+ *
+ * if (result.success) {
+ *   // Pipeline completed successfully
+ *   // ctx and result.context are the same object
+ *   // ctx.agentResult === result.context.agentResult is true
+ * } else {
+ *   // Pipeline stopped: ${result.finalAction} - ${result.reason}
+ * }
+ * ```
+ */
+export async function runPipeline(
+  stages: PipelineStage[],
+  context: PipelineContext,
+  eventEmitter?: PipelineEventEmitter,
+): Promise<PipelineRunResult> {
+  const logger = getLogger();
+
+  for (const stage of stages) {
+    // Skip disabled stages
+    if (!stage.enabled(context)) {
+      logger.debug("pipeline", `Stage "${stage.name}" skipped (disabled)`);
+      continue;
+    }
+
+    // Emit stage:enter event
+    eventEmitter?.emit("stage:enter", stage.name, context.story);
+
+    // Execute the stage
+    let result: StageResult;
+    try {
+      result = await stage.execute(context);
+    } catch (error) {
+      // Stage execution failed with an exception
+      const failResult: StageResult = {
+        action: "fail",
+        reason: `Stage "${stage.name}" threw error: ${error instanceof Error ? error.message : String(error)}`,
+      };
+
+      // Emit stage:exit event
+      eventEmitter?.emit("stage:exit", stage.name, failResult);
+
+      return {
+        success: false,
+        finalAction: "fail",
+        reason: failResult.reason,
+        stoppedAtStage: stage.name,
+        context,
+      };
+    }
+
+    // Emit stage:exit event
+    eventEmitter?.emit("stage:exit", stage.name, result);
+
+    // Handle stage result
+    switch (result.action) {
+      case "continue":
+        // Proceed to next stage
+        continue;
+
+      case "skip":
+        return {
+          success: false,
+          finalAction: "skip",
+          reason: result.reason,
+          stoppedAtStage: stage.name,
+          context,
+        };
+
+      case "fail":
+        return {
+          success: false,
+          finalAction: "fail",
+          reason: result.reason,
+          stoppedAtStage: stage.name,
+          context,
+        };
+
+      case "escalate":
+        return {
+          success: false,
+          finalAction: "escalate",
+          reason: "Stage requested escalation to higher tier",
+          stoppedAtStage: stage.name,
+          context,
+        };
+
+      case "pause":
+        return {
+          success: false,
+          finalAction: "pause",
+          reason: result.reason,
+          stoppedAtStage: stage.name,
+          context,
+        };
+
+      default: {
+        // Exhaustiveness check
+        const _exhaustive: never = result;
+        throw new Error(`Unknown stage action: ${JSON.stringify(_exhaustive)}`);
+      }
+    }
+  }
+
+  // All stages completed successfully
+  return {
+    success: true,
+    finalAction: "complete",
+    context,
+  };
+}