@nathapp/nax 0.34.0 → 0.36.0

package/src/agents/claude.ts

@@ -12,6 +12,7 @@ import type {
   AgentCapabilities,
   AgentResult,
   AgentRunOptions,
+  CompleteOptions,
   DecomposeOptions,
   DecomposeResult,
   InteractiveRunOptions,
@@ -19,6 +20,7 @@ import type {
   PlanResult,
   PtyHandle,
 } from "./types";
+import { CompleteError } from "./types";
 
 /**
  * Maximum characters to capture from agent stdout.
@@ -42,6 +44,53 @@ const MAX_AGENT_STDERR_CHARS = 1000;
  */
 const SIGKILL_GRACE_PERIOD_MS = 5000;
 
+/**
+ * Injectable dependencies for complete() — allows tests to intercept
+ * Bun.spawn calls and verify correct CLI args without the claude binary.
+ *
+ * @internal
+ */
+export const _completeDeps = {
+  spawn(
+    cmd: string[],
+    opts: { stdout: "pipe"; stderr: "pipe" | "inherit" },
+  ): { stdout: ReadableStream<Uint8Array>; stderr: ReadableStream<Uint8Array>; exited: Promise<number>; pid: number } {
+    return Bun.spawn(cmd, opts) as unknown as {
+      stdout: ReadableStream<Uint8Array>;
+      stderr: ReadableStream<Uint8Array>;
+      exited: Promise<number>;
+      pid: number;
+    };
+  },
+};
+
+/**
+ * Injectable dependencies for decompose() — allows tests to intercept
+ * Bun.spawn calls and verify correct CLI args without the claude binary.
+ *
+ * @internal
+ */
+export const _decomposeDeps = {
+  spawn(
+    cmd: string[],
+    opts: { cwd?: string; stdout: "pipe"; stderr: "inherit" | "pipe"; env?: Record<string, string | undefined> },
+  ): {
+    stdout: ReadableStream<Uint8Array>;
+    stderr?: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+    pid: number;
+    kill(signal?: NodeJS.Signals | number): void;
+  } {
+    return Bun.spawn(cmd, opts) as unknown as {
+      stdout: ReadableStream<Uint8Array>;
+      stderr?: ReadableStream<Uint8Array>;
+      exited: Promise<number>;
+      pid: number;
+      kill(signal?: NodeJS.Signals | number): void;
+    };
+  },
+};
+
 /**
  * Injectable dependencies for runOnce() — allows tests to verify
  * that PID cleanup (unregister) always runs even if kill() throws.
@@ -295,34 +344,76 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     };
   }
 
+  async complete(prompt: string, options?: CompleteOptions): Promise<string> {
+    // Build command: claude -p <prompt> [--model <model>] [--max-tokens <tokens>] [--output-format json]
+    const cmd = ["claude", "-p", prompt];
+
+    if (options?.model) {
+      cmd.push("--model", options.model);
+    }
+
+    if (options?.maxTokens !== undefined) {
+      cmd.push("--max-tokens", String(options.maxTokens));
+    }
+
+    if (options?.jsonMode) {
+      cmd.push("--output-format", "json");
+    }
+
+    const proc = _completeDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+
+    // Read stdout and stderr for error messages
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const trimmed = stdout.trim();
+
+    // Validate exit code and output
+    if (exitCode !== 0) {
+      const errorDetails = stderr.trim() || trimmed;
+      const errorMessage = errorDetails || `complete() failed with exit code ${exitCode}`;
+      throw new CompleteError(errorMessage, exitCode);
+    }
+
+    if (!trimmed) {
+      throw new CompleteError("complete() returned empty output");
+    }
+
+    return trimmed;
+  }
+
   async plan(options: PlanOptions): Promise<PlanResult> {
     const pidRegistry = this.getPidRegistry(options.workdir);
     return runPlan(this.binary, options, pidRegistry, this.buildAllowedEnv.bind(this));
   }
 
   async decompose(options: DecomposeOptions): Promise<DecomposeResult> {
+    const { resolveBalancedModelDef } = await import("./model-resolution");
+
     const prompt = buildDecomposePrompt(options);
 
-    const cmd = [
-      this.binary,
-      "--model",
-      options.modelDef?.model || "claude-sonnet-4-5",
-      "--dangerously-skip-permissions",
-      "-p",
-      prompt,
-    ];
+    // Resolve model: explicit modelDef > config.models.balanced > throw
+    let modelDef = options.modelDef;
+    if (!modelDef) {
+      if (!options.config) {
+        throw new Error("decompose() requires either modelDef or config with models.balanced configured");
+      }
+      modelDef = resolveBalancedModelDef(options.config);
+    }
+
+    const cmd = [this.binary, "--model", modelDef.model, "--dangerously-skip-permissions", "-p", prompt];
 
     const pidRegistry = this.getPidRegistry(options.workdir);
 
-    const proc = Bun.spawn(cmd, {
+    const proc = _decomposeDeps.spawn(cmd, {
       cwd: options.workdir,
       stdout: "pipe",
       stderr: "inherit", // MEM-3: Inherit stderr to avoid blocking on unread pipe
       env: this.buildAllowedEnv({
         workdir: options.workdir,
-        modelDef: options.modelDef || { provider: "anthropic", model: "claude-sonnet-4-5", env: {} },
+        modelDef,
         prompt: "",
-        modelTier: "balanced",
+        modelTier: options.modelTier || "balanced",
         timeoutSeconds: 600,
       }),
     });

package/src/agents/index.ts

@@ -1,4 +1,5 @@
-export type { AgentAdapter, AgentCapabilities, AgentResult, AgentRunOptions } from "./types";
+export type { AgentAdapter, AgentCapabilities, AgentResult, AgentRunOptions, CompleteOptions } from "./types";
+export { CompleteError } from "./types";
 export { ClaudeCodeAdapter } from "./claude";
 export { getAllAgentNames, getAgent, getInstalledAgents, checkAgentHealth } from "./registry";
 export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence } from "./cost";
@@ -11,3 +12,5 @@ export {
   formatCostWithConfidence,
 } from "./cost";
 export { validateAgentForTier, validateAgentFeature, describeAgentCapabilities } from "./validation";
+export type { AgentVersionInfo } from "./version-detection";
+export { getAgentVersion, getAgentVersions } from "./version-detection";

package/src/agents/model-resolution.ts

@@ -0,0 +1,43 @@
+/**
+ * Model resolution utility — AA-006
+ *
+ * Resolves a ModelDef from config.models.balanced with fallback chain:
+ *   config value -> adapter default -> throw if none configured
+ *
+ * Implementation placeholder — logic to be filled in by the implementer.
+ */
+
+import { resolveModel } from "../config/schema";
+import type { ModelDef, NaxConfig } from "../config/schema";
+
+/**
+ * Resolve the balanced model definition from config, with optional adapter default fallback.
+ *
+ * Fallback chain:
+ * 1. config.models.balanced (object or string shorthand)
+ * 2. adapterDefault (if provided)
+ * 3. Throws if neither is configured
+ *
+ * @param config - Partial NaxConfig (models.balanced is read if present)
+ * @param adapterDefault - Optional adapter-level fallback ModelDef
+ * @returns Resolved ModelDef
+ * @throws Error if no balanced model is configured and no adapter default provided
+ */
+export function resolveBalancedModelDef(
+  config: Pick<NaxConfig, "models"> | Partial<NaxConfig>,
+  adapterDefault?: ModelDef,
+): ModelDef {
+  const configWithModels = config as Pick<NaxConfig, "models">;
+  const models = configWithModels.models as Record<string, unknown> | undefined;
+  const balancedEntry = models?.balanced;
+
+  if (balancedEntry) {
+    return resolveModel(balancedEntry as string | ModelDef);
+  }
+
+  if (adapterDefault) {
+    return adapterDefault;
+  }
+
+  throw new Error("No balanced model configured in config.models.balanced and no adapter default provided");
+}

package/src/agents/registry.ts

@@ -4,15 +4,20 @@
  * Discovers and manages available coding agents.
  */
 
+import { AiderAdapter } from "./adapters/aider";
+import { CodexAdapter } from "./adapters/codex";
+import { GeminiAdapter } from "./adapters/gemini";
+import { OpenCodeAdapter } from "./adapters/opencode";
 import { ClaudeCodeAdapter } from "./claude";
 import type { AgentAdapter } from "./types";
 
 /** All known agent adapters */
 export const ALL_AGENTS: AgentAdapter[] = [
   new ClaudeCodeAdapter(),
-  // Future: new CodexAdapter(),
-  // Future: new OpenCodeAdapter(),
-  // Future: new GeminiAdapter(),
+  new CodexAdapter(),
+  new OpenCodeAdapter(),
+  new GeminiAdapter(),
+  new AiderAdapter(),
 ];
 
 /** Get all registered agent names */

package/src/agents/types-extended.ts

@@ -5,7 +5,7 @@
  * Separated from core types to keep each file under 400 lines.
  */
 
-import type { ModelDef, ModelTier } from "../config/schema";
+import type { ModelDef, ModelTier, NaxConfig } from "../config/schema";
 
 /**
  * Configuration options for running an agent in plan mode.
@@ -28,6 +28,8 @@ export interface PlanOptions {
   modelTier?: ModelTier;
   /** Resolved model definition */
   modelDef?: ModelDef;
+  /** Global config — used to resolve models.balanced when modelDef is absent */
+  config?: Partial<NaxConfig>;
 }
 
 /**
@@ -59,6 +61,8 @@ export interface DecomposeOptions {
   modelTier?: ModelTier;
   /** Resolved model definition */
   modelDef?: ModelDef;
+  /** Global config — used to resolve models.balanced when modelDef is absent */
+  config?: Partial<NaxConfig>;
 }
 
 /** A single classified user story from decompose result. */

package/src/agents/types.ts

@@ -73,6 +73,31 @@ export interface AgentCapabilities {
   readonly features: ReadonlySet<"tdd" | "review" | "refactor" | "batch">;
 }
 
+/**
+ * Options for one-shot LLM completion calls.
+ */
+export interface CompleteOptions {
+  /** Maximum tokens for the response */
+  maxTokens?: number;
+  /** Request JSON-formatted output (adds --output-format json) */
+  jsonMode?: boolean;
+  /** Override the model (adds --model flag) */
+  model?: string;
+}
+
+/**
+ * Typed error thrown when complete() fails due to non-zero exit or empty output.
+ */
+export class CompleteError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode?: number,
+  ) {
+    super(message);
+    this.name = "CompleteError";
+  }
+}
+
 /**
  * Agent adapter interface — one implementation per supported coding agent.
  *
@@ -104,6 +129,12 @@ export interface AgentAdapter {
   /** Run the agent in decompose mode to break spec into classified stories. */
   decompose(options: import("./types-extended").DecomposeOptions): Promise<import("./types-extended").DecomposeResult>;
 
+  /**
+   * Run a one-shot LLM call and return the plain text response.
+   * Uses claude -p CLI for non-interactive completions.
+   */
+  complete(prompt: string, options?: CompleteOptions): Promise<string>;
+
   /**
    * Run the agent in interactive PTY mode for TUI embedding.
    * This method is optional — only implemented by agents that support

package/src/agents/version-detection.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent version detection utilities
+ *
+ * Extracts version information from installed agent binaries
+ * by running `<agent> --version` and parsing the output.
+ */
+
+import { getInstalledAgents } from "./registry";
+import type { AgentAdapter } from "./types";
+
+/**
+ * Information about an installed agent including its version
+ */
+export interface AgentVersionInfo {
+  /** Agent name (e.g., "codex", "aider") */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Agent version or null if not installed/unable to detect */
+  version: string | null;
+  /** Whether the agent binary is installed */
+  installed: boolean;
+}
+
+/**
+ * Dependency injection for testability
+ */
+export const _versionDetectionDeps = {
+  spawn(
+    cmd: string[],
+    opts: { stdout: "pipe"; stderr: "pipe" },
+  ): {
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+  } {
+    return Bun.spawn(cmd, opts) as unknown as {
+      stdout: ReadableStream<Uint8Array>;
+      stderr: ReadableStream<Uint8Array>;
+      exited: Promise<number>;
+    };
+  },
+};
+
+/**
+ * Get version for a single agent binary
+ *
+ * Runs `<agent> --version` and extracts version string.
+ * Returns null if agent not found or version detection fails.
+ */
+export async function getAgentVersion(binaryName: string): Promise<string | null> {
+  try {
+    const proc = _versionDetectionDeps.spawn([binaryName, "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      return null;
+    }
+
+    const stdout = await new Response(proc.stdout).text();
+    const versionLine = stdout.trim().split("\n")[0];
+
+    // Extract version from common formats:
+    // "tool version 1.2.3"
+    // "v1.2.3"
+    // "1.2.3"
+    const versionMatch = versionLine.match(/v?(\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?)/);
+    if (versionMatch) {
+      return versionMatch[0];
+    }
+
+    // If no version pattern matched, return the first line as-is
+    return versionLine || null;
+  } catch {
+    // Bun.spawn throws ENOENT if binary not found
+    return null;
+  }
+}
+
+/**
+ * Get version information for all configured agents
+ *
+ * Returns list of agents with their installation status and version info.
+ */
+export async function getAgentVersions(): Promise<AgentVersionInfo[]> {
+  const agents = await getInstalledAgents();
+  const agentsByName = new Map(agents.map((a) => [a.name, a]));
+
+  // Import ALL_AGENTS to include non-installed ones
+  const { ALL_AGENTS } = await import("./registry");
+
+  const versions = await Promise.all(
+    ALL_AGENTS.map(async (agent: AgentAdapter): Promise<AgentVersionInfo> => {
+      const version = agentsByName.has(agent.name) ? await getAgentVersion(agent.binary) : null;
+
+      return {
+        name: agent.name,
+        displayName: agent.displayName,
+        version,
+        installed: agentsByName.has(agent.name),
+      };
+    }),
+  );
+
+  return versions;
+}

package/src/analyze/classifier.ts

@@ -5,13 +5,25 @@
  * Falls back to keyword matching if LLM call fails.
  */
 
-import { Anthropic } from "@anthropic-ai/sdk";
+import type { AgentAdapter } from "../agents";
+import { ClaudeCodeAdapter } from "../agents/claude";
 import type { NaxConfig } from "../config";
+import { resolveModel } from "../config/schema";
 import { getLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { classifyComplexity } from "../routing";
 import type { ClassificationResult, CodebaseScan, StoryClassification } from "./types";
 
+/**
+ * Injectable dependencies for classifier — allows tests to mock adapter.complete()
+ * without needing the claude binary.
+ *
+ * @internal
+ */
+export const _classifyDeps = {
+  adapter: new ClaudeCodeAdapter() as AgentAdapter,
+};
+
 /**
  * Raw LLM classification item (before validation)
  */
@@ -92,37 +104,29 @@ async function classifyWithLLM(
   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");
+  // Check for required environment variables
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new Error("ANTHROPIC_API_KEY environment variable not configured — cannot use LLM classification");
   }
 
-  const client = new Anthropic({ apiKey });
-
   // Build prompt
-  const prompt = buildClassificationPrompt(stories, scan, config);
+  const prompt = buildClassificationPrompt(stories, scan);
 
-  // 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");
+  // Resolve model from config.models.fast
+  const fastModelEntry = config.models.fast;
+  if (!fastModelEntry) {
+    throw new Error("config.models.fast not configured");
   }
+  const modelDef = resolveModel(fastModelEntry);
+
+  // Make API call via adapter (use haiku for cheap classification)
+  const jsonText = await _classifyDeps.adapter.complete(prompt, {
+    jsonMode: true,
+    maxTokens: 4096,
+    model: modelDef.model,
+  });
 
   // Parse JSON response
-  const jsonText = extractJSON(textContent.text);
   const parsed: unknown = JSON.parse(jsonText);
 
   // Validate structure
@@ -159,10 +163,9 @@ async function classifyWithLLM(
  *
  * @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 {
+function buildClassificationPrompt(stories: UserStory[], scan: CodebaseScan): string {
   // Format codebase summary
   const codebaseSummary = `
 FILE TREE:
@@ -229,29 +232,6 @@ Consider:
 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.
  *

package/src/cli/agents.ts

@@ -0,0 +1,87 @@
+/**
+ * Agents Command
+ *
+ * Lists available agents with their binary paths, versions, and health status.
+ */
+
+import { ALL_AGENTS } from "../agents/registry";
+import { getAgentVersion } from "../agents/version-detection";
+import type { NaxConfig } from "../config/schema";
+
+/**
+ * List all agents with status, version, and capabilities.
+ *
+ * @param config - nax configuration
+ * @param _workdir - Working directory (for consistency with other commands)
+ */
+export async function agentsListCommand(config: NaxConfig, _workdir: string): Promise<void> {
+  // Get version info for all agents
+  const agentVersions = await Promise.all(
+    ALL_AGENTS.map(async (agent) => ({
+      name: agent.name,
+      displayName: agent.displayName,
+      binary: agent.binary,
+      version: await getAgentVersion(agent.binary),
+      installed: await agent.isInstalled(),
+      capabilities: agent.capabilities,
+      isDefault: config.autoMode.defaultAgent === agent.name,
+    })),
+  );
+
+  // Build table rows
+  const rows = agentVersions.map((info) => {
+    const status = info.installed ? "installed" : "unavailable";
+    const versionStr = info.version || "-";
+    const defaultMarker = info.isDefault ? " (default)" : "";
+
+    return {
+      name: info.displayName + defaultMarker,
+      status,
+      version: versionStr,
+      binary: info.binary,
+      tiers: info.capabilities.supportedTiers.join(", "),
+    };
+  });
+
+  if (rows.length === 0) {
+    console.log("No agents available.");
+    return;
+  }
+
+  // Calculate column widths
+  const widths = {
+    name: Math.max(5, ...rows.map((r) => r.name.length)),
+    status: Math.max(6, ...rows.map((r) => r.status.length)),
+    version: Math.max(7, ...rows.map((r) => r.version.length)),
+    binary: Math.max(6, ...rows.map((r) => r.binary.length)),
+    tiers: Math.max(5, ...rows.map((r) => r.tiers.length)),
+  };
+
+  // Display table
+  console.log("\nAvailable Agents:\n");
+  console.log(
+    `${pad("Agent", widths.name)}  ${pad("Status", widths.status)}  ${pad("Version", widths.version)}  ${pad("Binary", widths.binary)}  ${pad("Tiers", widths.tiers)}`,
+  );
+  console.log(
+    `${"-".repeat(widths.name)}  ${"-".repeat(widths.status)}  ${"-".repeat(widths.version)}  ${"-".repeat(widths.binary)}  ${"-".repeat(widths.tiers)}`,
+  );
+
+  for (const row of rows) {
+    console.log(
+      `${pad(row.name, widths.name)}  ${pad(row.status, widths.status)}  ${pad(row.version, widths.version)}  ${pad(row.binary, widths.binary)}  ${pad(row.tiers, widths.tiers)}`,
+    );
+  }
+
+  console.log();
+}
+
+/**
+ * Pad string to width.
+ *
+ * @param str - String to pad
+ * @param width - Target width
+ * @returns Padded string
+ */
+function pad(str: string, width: number): string {
+  return str.padEnd(width);
+}

package/src/cli/analyze-parser.ts

@@ -233,7 +233,14 @@ async function reclassifyWithLLM(
   const modelTier = config.analyze.model;
   const modelDef = resolveModel(config.models[modelTier]);
 
-  const result = await adapter.decompose({ specContent: storySpec, workdir, codebaseContext, modelTier, modelDef });
+  const result = await adapter.decompose({
+    specContent: storySpec,
+    workdir,
+    codebaseContext,
+    modelTier,
+    modelDef,
+    config,
+  });
 
   if (result.stories.length === 0) return story;
   const ds = result.stories[0];

package/src/cli/analyze.ts

@@ -115,7 +115,7 @@ async function decomposeLLM(
 
     const modelTier = config.analyze.model;
     const modelDef = resolveModel(config.models[modelTier]);
-    const result = await adapter.decompose({ specContent, workdir, codebaseContext, modelTier, modelDef });
+    const result = await adapter.decompose({ specContent, workdir, codebaseContext, modelTier, modelDef, config });
 
     logger.info("cli", "[OK] Agent decompose complete", { storiesCount: result.stories.length });