@nathapp/nax 0.18.1

package/src/agents/types-extended.ts

@@ -0,0 +1,133 @@
+/**
+ * Extended Agent Type Definitions
+ *
+ * Types for plan mode, decompose mode, and interactive PTY sessions.
+ * Separated from core types to keep each file under 400 lines.
+ */
+
+import type { ModelDef, ModelTier } from "../config/schema";
+
+/**
+ * Configuration options for running an agent in plan mode.
+ *
+ * Plan mode spawns the agent interactively (or non-interactively with input file)
+ * to gather requirements, ask clarifying questions, and produce a structured spec.
+ */
+export interface PlanOptions {
+  /** The initial planning prompt or task description */
+  prompt: string;
+  /** Working directory */
+  workdir: string;
+  /** Whether to run in interactive mode (agent takes over terminal) */
+  interactive: boolean;
+  /** Optional codebase context (file tree, dependencies, test patterns) */
+  codebaseContext?: string;
+  /** Optional input file path for non-interactive mode */
+  inputFile?: string;
+  /** Model tier to use for planning (default: "balanced") */
+  modelTier?: ModelTier;
+  /** Resolved model definition */
+  modelDef?: ModelDef;
+}
+
+/**
+ * Result from running an agent in plan mode.
+ *
+ * Contains the generated specification content and optional conversation log.
+ */
+export interface PlanResult {
+  /** The generated specification markdown content */
+  specContent: string;
+  /** Optional conversation log (for debugging/review) */
+  conversationLog?: string;
+}
+
+/**
+ * Configuration options for running an agent in decompose mode.
+ *
+ * Decompose mode reads a spec document and breaks it down into classified user stories
+ * in a single LLM call (decompose + classify combined).
+ */
+export interface DecomposeOptions {
+  /** The spec document content to decompose */
+  specContent: string;
+  /** Working directory */
+  workdir: string;
+  /** Codebase context (file tree, dependencies, test patterns) */
+  codebaseContext: string;
+  /** Model tier to use for decomposition (default: "balanced") */
+  modelTier?: ModelTier;
+  /** Resolved model definition */
+  modelDef?: ModelDef;
+}
+
+/** A single classified user story from decompose result. */
+export interface DecomposedStory {
+  /** Story ID (e.g., "US-001") */
+  id: string;
+  /** Story title */
+  title: string;
+  /** Story description */
+  description: string;
+  /** Acceptance criteria */
+  acceptanceCriteria: string[];
+  /** Tags for routing */
+  tags: string[];
+  /** Dependencies (story IDs) */
+  dependencies: string[];
+  /** Classified complexity */
+  complexity: "simple" | "medium" | "complex" | "expert";
+  /** Context files to inject into agent prompt before execution */
+  contextFiles: string[];
+  /** Classification reasoning */
+  reasoning: string;
+  /** Estimated lines of code */
+  estimatedLOC: number;
+  /** Implementation risks */
+  risks: string[];
+  /** Test strategy recommendation from LLM */
+  testStrategy?: "three-session-tdd" | "test-after";
+}
+
+/**
+ * Result from running an agent in decompose mode.
+ *
+ * Contains the decomposed and classified user stories.
+ */
+export interface DecomposeResult {
+  /** The decomposed and classified user stories */
+  stories: DecomposedStory[];
+}
+
+/**
+ * PTY handle interface for managing spawned PTY process.
+ *
+ * Provides methods to write input, resize terminal, and kill process.
+ * Returned by runInteractive() for TUI integration.
+ */
+export interface PtyHandle {
+  /** Write input to PTY stdin */
+  write(data: string): void;
+  /** Resize PTY terminal */
+  resize(cols: number, rows: number): void;
+  /** Kill PTY process */
+  kill(): void;
+  /** Process ID */
+  pid: number;
+}
+
+/**
+ * Configuration options for running an agent in interactive PTY mode.
+ *
+ * Extends AgentRunOptions with PTY-specific callbacks for output streaming
+ * and exit handling. Used by TUI to embed agent sessions.
+ */
+export interface InteractiveRunOptions extends AgentRunOptions {
+  /** Callback fired when PTY outputs data */
+  onOutput: (data: Buffer) => void;
+  /** Callback fired when PTY process exits */
+  onExit: (code: number) => void;
+}
+
+// Re-import for the extends clause
+import type { AgentRunOptions } from "./types";

package/src/agents/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Agent Adapter Interface
+ *
+ * Every coding agent (Claude Code, Codex, OpenCode, etc.)
+ * implements this interface so nax can spawn, monitor, and
+ * collect results from them uniformly.
+ */
+
+import type { ModelDef, ModelTier } from "../config/schema";
+
+// Re-export extended types for backward compatibility
+export type {
+  PlanOptions,
+  PlanResult,
+  DecomposeOptions,
+  DecomposeResult,
+  DecomposedStory,
+  PtyHandle,
+  InteractiveRunOptions,
+} from "./types-extended";
+
+/**
+ * Agent execution result returned after running a coding agent.
+ */
+export interface AgentResult {
+  /** Whether the agent completed successfully */
+  success: boolean;
+  /** Exit code from the process */
+  exitCode: number;
+  /** stdout output (last N lines) */
+  output: string;
+  /** stderr output tail (last N lines) — useful for diagnosing failures */
+  stderr?: string;
+  /** Whether the agent hit a rate limit */
+  rateLimited: boolean;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Estimated cost for this run (USD) */
+  estimatedCost: number;
+  /** Process ID of the spawned agent (for cleanup on failure) */
+  pid?: number;
+}
+
+/**
+ * Configuration options for running a coding agent session.
+ */
+export interface AgentRunOptions {
+  /** The prompt to send to the agent */
+  prompt: string;
+  /** Working directory */
+  workdir: string;
+  /** Model tier (for cost estimation) */
+  modelTier: ModelTier;
+  /** Resolved model definition */
+  modelDef: ModelDef;
+  /** Maximum runtime in seconds */
+  timeoutSeconds: number;
+  /** Environment variables to pass */
+  env?: Record<string, string>;
+  /** Use --dangerously-skip-permissions flag (default: true) */
+  dangerouslySkipPermissions?: boolean;
+}
+
+/**
+ * Agent capability metadata describing what features and tiers the agent supports.
+ */
+export interface AgentCapabilities {
+  /** Model tiers this agent supports (e.g., fast/balanced/powerful) */
+  readonly supportedTiers: readonly ModelTier[];
+  /** Maximum context window size in tokens */
+  readonly maxContextTokens: number;
+  /** Feature flags — what workflows this agent can handle */
+  readonly features: ReadonlySet<"tdd" | "review" | "refactor" | "batch">;
+}
+
+/**
+ * Agent adapter interface — one implementation per supported coding agent.
+ *
+ * Provides uniform interface for checking installation, running agents,
+ * and building CLI commands across different coding agent tools.
+ */
+export interface AgentAdapter {
+  /** Unique agent name (e.g., "claude", "codex", "opencode") */
+  readonly name: string;
+  /** Human-readable display name */
+  readonly displayName: string;
+  /** Binary command to check if agent is installed */
+  readonly binary: string;
+  /** Capability metadata describing supported tiers and features */
+  readonly capabilities: AgentCapabilities;
+
+  /** Check if the agent binary is available on this machine. */
+  isInstalled(): Promise<boolean>;
+
+  /** Run the agent with a prompt and return the result. */
+  run(options: AgentRunOptions): Promise<AgentResult>;
+
+  /** Build the CLI command for a given run (for dry-run display). */
+  buildCommand(options: AgentRunOptions): string[];
+
+  /** Run the agent in plan mode to generate a feature specification. */
+  plan(options: import("./types-extended").PlanOptions): Promise<import("./types-extended").PlanResult>;
+
+  /** Run the agent in decompose mode to break spec into classified stories. */
+  decompose(options: import("./types-extended").DecomposeOptions): Promise<import("./types-extended").DecomposeResult>;
+
+  /**
+   * Run the agent in interactive PTY mode for TUI embedding.
+   * This method is optional — only implemented by agents that support
+   * interactive terminal sessions (e.g., Claude Code).
+   */
+  runInteractive?(options: import("./types-extended").InteractiveRunOptions): import("./types-extended").PtyHandle;
+}

package/src/agents/validation.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent Validation Helpers
+ *
+ * Runtime validation for agent capabilities and tier compatibility.
+ */
+
+import type { ModelTier } from "../config/schema";
+import type { AgentAdapter } from "./types";
+
+/**
+ * Check if an agent supports a given model tier.
+ *
+ * Used to validate routing decisions at runtime — ensures the orchestrator
+ * doesn't try to use a tier the agent doesn't support.
+ *
+ * @param agent - The agent adapter to validate
+ * @param tier - The model tier to check (fast/balanced/powerful)
+ * @returns true if the agent declares support for this tier
+ *
+ * @example
+ * ```ts
+ * const agent = new ClaudeCodeAdapter();
+ * if (!validateAgentForTier(agent, "powerful")) {
+ *   console.warn(`Agent ${agent.name} does not support powerful tier`);
+ * }
+ * ```
+ */
+export function validateAgentForTier(agent: AgentAdapter, tier: ModelTier): boolean {
+  return agent.capabilities.supportedTiers.includes(tier);
+}
+
+/**
+ * Check if an agent supports a specific feature.
+ *
+ * @param agent - The agent adapter to validate
+ * @param feature - The feature to check (tdd/review/refactor/batch)
+ * @returns true if the agent declares support for this feature
+ *
+ * @example
+ * ```ts
+ * const agent = new ClaudeCodeAdapter();
+ * if (!validateAgentFeature(agent, "tdd")) {
+ *   throw new Error("Agent does not support TDD workflow");
+ * }
+ * ```
+ */
+export function validateAgentFeature(agent: AgentAdapter, feature: "tdd" | "review" | "refactor" | "batch"): boolean {
+  return agent.capabilities.features.has(feature);
+}
+
+/**
+ * Get a human-readable description of agent capabilities.
+ *
+ * @param agent - The agent adapter to describe
+ * @returns Formatted capability summary
+ *
+ * @example
+ * ```ts
+ * const agent = new ClaudeCodeAdapter();
+ * console.log(describeAgentCapabilities(agent));
+ * // "claude: tiers=[fast,balanced,powerful], maxTokens=200000, features=[tdd,review,refactor,batch]"
+ * ```
+ */
+export function describeAgentCapabilities(agent: AgentAdapter): string {
+  const tiers = agent.capabilities.supportedTiers.join(",");
+  const features = Array.from(agent.capabilities.features).join(",");
+  const maxTokens = agent.capabilities.maxContextTokens;
+  return `${agent.name}: tiers=[${tiers}], maxTokens=${maxTokens}, features=[${features}]`;
+}

package/src/analyze/classifier.ts

@@ -0,0 +1,305 @@
+/**
+ * LLM-Enhanced Classifier
+ *
+ * Uses a single cheap LLM call (haiku) to classify all stories in one shot.
+ * Falls back to keyword matching if LLM call fails.
+ */
+
+import { Anthropic } from "@anthropic-ai/sdk";
+import type { NaxConfig } from "../config";
+import { getLogger } from "../logger";
+import type { UserStory } from "../prd";
+import { classifyComplexity } from "../routing";
+import type { ClassificationResult, CodebaseScan, StoryClassification } from "./types";
+
+/**
+ * Raw LLM classification item (before validation)
+ */
+interface LLMClassificationItem {
+  storyId: unknown;
+  complexity: unknown;
+  relevantFiles: unknown;
+  reasoning: unknown;
+  estimatedLOC: unknown;
+  risks: unknown;
+}
+
+/**
+ * Classify stories using LLM-enhanced analysis with fallback to keyword matching.
+ *
+ * Makes a single Anthropic API call (haiku tier) to classify all stories.
+ * If the LLM call fails or returns invalid JSON, falls back to keyword matching.
+ *
+ * @param stories - User stories to classify
+ * @param scan - Codebase scan result
+ * @param config - Ngent configuration
+ * @returns Classification result with method used
+ *
+ * @example
+ * ```ts
+ * const result = await classifyStories(stories, scan, config);
+ * if (result.method === "keyword-fallback") {
+ *   console.warn("LLM classification failed:", result.fallbackReason);
+ * }
+ * console.log(result.classifications);
+ * ```
+ */
+export async function classifyStories(
+  stories: UserStory[],
+  scan: CodebaseScan,
+  config: NaxConfig,
+): Promise<ClassificationResult> {
+  // Check if LLM-enhanced analysis is enabled
+  if (!config.analyze?.llmEnhanced) {
+    return {
+      classifications: stories.map((story) => fallbackClassification(story)),
+      method: "keyword-fallback",
+      fallbackReason: "LLM-enhanced analysis disabled in config",
+    };
+  }
+
+  // Try LLM classification
+  try {
+    const classifications = await classifyWithLLM(stories, scan, config);
+    return {
+      classifications,
+      method: "llm",
+    };
+  } catch (error) {
+    // Fall back to keyword matching
+    const reason = error instanceof Error ? error.message : String(error);
+    const logger = getLogger();
+    logger.warn("analyze", "LLM classification failed, falling back to keyword matching", { error: reason });
+
+    return {
+      classifications: stories.map((story) => fallbackClassification(story)),
+      method: "keyword-fallback",
+      fallbackReason: reason,
+    };
+  }
+}
+
+/**
+ * Classify stories using LLM with structured JSON output.
+ *
+ * @param stories - User stories to classify
+ * @param scan - Codebase scan result
+ * @param config - Ngent configuration
+ * @returns Array of story classifications
+ */
+async function classifyWithLLM(
+  stories: UserStory[],
+  scan: CodebaseScan,
+  config: NaxConfig,
+): Promise<StoryClassification[]> {
+  // Check API key
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error("ANTHROPIC_API_KEY not set");
+  }
+
+  const client = new Anthropic({ apiKey });
+
+  // Build prompt
+  const prompt = buildClassificationPrompt(stories, scan, config);
+
+  // Make API call (use haiku for cheap classification)
+  const response = await client.messages.create({
+    model: "claude-haiku-4-20250514",
+    max_tokens: 4096,
+    messages: [
+      {
+        role: "user",
+        content: prompt,
+      },
+    ],
+  });
+
+  // Extract text from response
+  const textContent = response.content.find((c) => c.type === "text");
+  if (!textContent || textContent.type !== "text") {
+    throw new Error("No text response from LLM");
+  }
+
+  // Parse JSON response
+  const jsonText = extractJSON(textContent.text);
+  const parsed: unknown = JSON.parse(jsonText);
+
+  // Validate structure
+  if (!Array.isArray(parsed)) {
+    throw new Error("LLM response is not an array");
+  }
+
+  // Map to StoryClassification[]
+  const classifications: StoryClassification[] = parsed.map((item: unknown) => {
+    const rawItem = item as LLMClassificationItem;
+    return {
+      storyId: String(rawItem.storyId),
+      complexity: validateComplexity(rawItem.complexity),
+      contextFiles: Array.isArray(rawItem.relevantFiles) ? rawItem.relevantFiles.map(String) : [],
+      reasoning: String(rawItem.reasoning || "No reasoning provided"),
+      estimatedLOC: Number(rawItem.estimatedLOC) || 0,
+      risks: Array.isArray(rawItem.risks) ? rawItem.risks.map(String) : [],
+    };
+  });
+
+  // Ensure all stories are classified
+  const classifiedIds = new Set(classifications.map((c) => c.storyId));
+  for (const story of stories) {
+    if (!classifiedIds.has(story.id)) {
+      throw new Error(`Story ${story.id} not classified by LLM`);
+    }
+  }
+
+  return classifications;
+}
+
+/**
+ * Build classification prompt for LLM.
+ *
+ * @param stories - User stories to classify
+ * @param scan - Codebase scan result
+ * @param config - Ngent configuration
+ * @returns Formatted prompt string
+ */
+function buildClassificationPrompt(stories: UserStory[], scan: CodebaseScan, config: NaxConfig): string {
+  // Format codebase summary
+  const codebaseSummary = `
+FILE TREE:
+${scan.fileTree}
+
+DEPENDENCIES:
+${Object.entries(scan.dependencies)
+  .map(([name, version]) => `- ${name}: ${version}`)
+  .join("\n")}
+
+DEV DEPENDENCIES:
+${Object.entries(scan.devDependencies)
+  .map(([name, version]) => `- ${name}: ${version}`)
+  .join("\n")}
+
+TEST PATTERNS:
+${scan.testPatterns.map((p) => `- ${p}`).join("\n")}
+`.trim();
+
+  // Format stories as JSON for LLM
+  const storiesJson = JSON.stringify(
+    stories.map((s) => ({
+      id: s.id,
+      title: s.title,
+      description: s.description,
+      acceptanceCriteria: s.acceptanceCriteria,
+      tags: s.tags,
+    })),
+    null,
+    2,
+  );
+
+  return `You are a code complexity classifier. Given a codebase summary and user stories,
+classify each story's implementation complexity.
+
+CODEBASE:
+${codebaseSummary}
+
+STORIES:
+${storiesJson}
+
+For each story, respond with a JSON array (and ONLY the JSON array, no markdown code fences):
+[{
+  "storyId": "US-001",
+  "complexity": "simple|medium|complex|expert",
+  "relevantFiles": ["src/path/to/file.ts"],
+  "reasoning": "Why this complexity level",
+  "estimatedLOC": 50,
+  "risks": ["No existing cache layer"]
+}]
+
+Classification rules:
+- simple: 1-3 files, <100 LOC, straightforward implementation, existing patterns
+- medium: 3-6 files, 100-300 LOC, moderate logic, some new patterns
+- complex: 6+ files, 300-800 LOC, architectural changes, cross-cutting concerns
+- expert: Security/crypto/real-time/distributed systems, >800 LOC, new infrastructure
+
+Consider:
+1. Does infrastructure exist? (e.g., "add caching" when no cache layer exists = complex)
+2. How many files will be touched?
+3. Are there cross-cutting concerns (auth, validation, error handling)?
+4. Does it require new dependencies or architectural decisions?
+
+Respond with ONLY the JSON array.`;
+}
+
+/**
+ * Extract JSON from LLM response (handles markdown code fences).
+ *
+ * @param text - LLM response text
+ * @returns JSON string
+ */
+function extractJSON(text: string): string {
+  // Remove markdown code fences if present
+  const jsonMatch = text.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
+  if (jsonMatch) {
+    return jsonMatch[1];
+  }
+
+  // Try to find JSON array directly
+  const arrayMatch = text.match(/\[[\s\S]*\]/);
+  if (arrayMatch) {
+    return arrayMatch[0];
+  }
+
+  // Return as-is if no special formatting detected
+  return text.trim();
+}
+
+/**
+ * Validate complexity value from LLM response.
+ *
+ * @param value - Complexity value from LLM
+ * @returns Valid Complexity type
+ */
+function validateComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
+  if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
+    return value;
+  }
+  // Default to medium if invalid
+  return "medium";
+}
+
+/**
+ * Fallback classification using keyword matching.
+ *
+ * @param story - User story to classify
+ * @returns Story classification using keyword-based complexity
+ */
+function fallbackClassification(story: UserStory): StoryClassification {
+  const complexity = classifyComplexity(story.title, story.description, story.acceptanceCriteria, story.tags);
+
+  return {
+    storyId: story.id,
+    complexity,
+    contextFiles: [],
+    reasoning: `Keyword-based classification: ${complexity}`,
+    estimatedLOC: estimateLOCFromComplexity(complexity),
+    risks: [],
+  };
+}
+
+/**
+ * Estimate LOC from complexity level (rough heuristic).
+ *
+ * @param complexity - Complexity level
+ * @returns Estimated lines of code
+ */
+function estimateLOCFromComplexity(complexity: "simple" | "medium" | "complex" | "expert"): number {
+  switch (complexity) {
+    case "simple":
+      return 50;
+    case "medium":
+      return 150;
+    case "complex":
+      return 400;
+    case "expert":
+      return 800;
+  }
+}

package/src/analyze/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Analyze Module
+ *
+ * LLM-enhanced story classification with codebase scanning.
+ */
+
+export type {
+  CodebaseScan,
+  StoryClassification,
+  ClassifierResponse,
+  ClassificationMethod,
+  ClassificationResult,
+} from "./types";
+
+export { scanCodebase } from "./scanner";
+export { classifyStories } from "./classifier";