@nathapp/nax 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -20,7 +20,6 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.74.0",
     "@types/react": "^19.2.14",
     "chalk": "^5.6.2",
     "commander": "^13.1.0",

package/src/agents/adapters/codex.ts

@@ -0,0 +1,153 @@
+/**
+ * Codex Agent Adapter — implements AgentAdapter interface
+ *
+ * Provides uniform interface for spawning Codex agent processes,
+ * supporting one-shot completions and headless execution.
+ */
+
+import type {
+  AgentAdapter,
+  AgentCapabilities,
+  AgentResult,
+  AgentRunOptions,
+  CompleteOptions,
+  DecomposeOptions,
+  DecomposeResult,
+  PlanOptions,
+  PlanResult,
+} from "../types";
+import { CompleteError } from "../types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Injectable dependencies — matches the _deps pattern used in claude.ts
+// These are replaced in unit tests to intercept Bun.spawn calls.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const _codexRunDeps = {
+  which(name: string): string | null {
+    return Bun.which(name);
+  },
+  spawn(
+    cmd: string[],
+    opts: { cwd?: string; stdout: "pipe"; stderr: "pipe" | "inherit"; env?: Record<string, string | undefined> },
+  ): {
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+    pid: number;
+    kill(signal?: number | NodeJS.Signals): void;
+  } {
+    return Bun.spawn(cmd, opts) as unknown as {
+      stdout: ReadableStream<Uint8Array>;
+      stderr: ReadableStream<Uint8Array>;
+      exited: Promise<number>;
+      pid: number;
+      kill(signal?: number | NodeJS.Signals): void;
+    };
+  },
+};
+
+export const _codexCompleteDeps = {
+  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;
+    };
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CodexAdapter implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Maximum characters to capture from agent stdout.
+ */
+const MAX_AGENT_OUTPUT_CHARS = 5000;
+
+export class CodexAdapter implements AgentAdapter {
+  readonly name = "codex";
+  readonly displayName = "Codex";
+  readonly binary = "codex";
+
+  readonly capabilities: AgentCapabilities = {
+    supportedTiers: ["fast", "balanced"],
+    maxContextTokens: 8_000,
+    features: new Set<"tdd" | "review" | "refactor" | "batch">(["tdd", "refactor"]),
+  };
+
+  async isInstalled(): Promise<boolean> {
+    const path = _codexRunDeps.which("codex");
+    return path !== null;
+  }
+
+  buildCommand(options: AgentRunOptions): string[] {
+    return ["codex", "-q", "--prompt", options.prompt];
+  }
+
+  async run(options: AgentRunOptions): Promise<AgentResult> {
+    const cmd = this.buildCommand(options);
+    const startTime = Date.now();
+
+    const proc = _codexRunDeps.spawn(cmd, {
+      cwd: options.workdir,
+      stdout: "pipe",
+      stderr: "inherit",
+    });
+
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const durationMs = Date.now() - startTime;
+
+    return {
+      success: exitCode === 0,
+      exitCode,
+      output: stdout.slice(-MAX_AGENT_OUTPUT_CHARS),
+      rateLimited: false,
+      durationMs,
+      estimatedCost: 0,
+      pid: proc.pid,
+    };
+  }
+
+  async complete(prompt: string, _options?: CompleteOptions): Promise<string> {
+    const cmd = ["codex", "-q", "--prompt", prompt];
+
+    const proc = _codexCompleteDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const trimmed = stdout.trim();
+
+    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> {
+    throw new Error("CodexAdapter.plan() not implemented");
+  }
+
+  async decompose(_options: DecomposeOptions): Promise<DecomposeResult> {
+    throw new Error("CodexAdapter.decompose() not implemented");
+  }
+}

package/src/agents/claude-plan.ts

@@ -9,6 +9,7 @@ import { join } from "node:path";
 
 import type { PidRegistry } from "../execution/pid-registry";
 import { getLogger } from "../logger";
+import { resolveBalancedModelDef } from "./model-resolution";
 import type { AgentRunOptions } from "./types";
 import type { PlanOptions, PlanResult } from "./types-extended";
 
@@ -18,9 +19,14 @@ import type { PlanOptions, PlanResult } from "./types-extended";
 export function buildPlanCommand(binary: string, options: PlanOptions): string[] {
   const cmd = [binary, "--permission-mode", "plan"];
 
-  // Add model if specified
-  if (options.modelDef) {
-    cmd.push("--model", options.modelDef.model);
+  // Add model if specified (explicit or resolved from config)
+  let modelDef = options.modelDef;
+  if (!modelDef && options.config) {
+    modelDef = resolveBalancedModelDef(options.config);
+  }
+
+  if (modelDef) {
+    cmd.push("--model", modelDef.model);
   }
 
   // Add dangerously-skip-permissions for automation
@@ -64,13 +70,24 @@ export async function runPlan(
   pidRegistry: PidRegistry,
   buildAllowedEnv: (options: AgentRunOptions) => Record<string, string | undefined>,
 ): Promise<PlanResult> {
+  const { resolveBalancedModelDef } = await import("./model-resolution");
+
   const cmd = buildPlanCommand(binary, options);
 
+  // Resolve model: explicit modelDef > config.models.balanced > throw
+  let modelDef = options.modelDef;
+  if (!modelDef) {
+    if (!options.config) {
+      throw new Error("runPlan() requires either modelDef or config with models.balanced configured");
+    }
+    modelDef = resolveBalancedModelDef(options.config);
+  }
+
   const envOptions: AgentRunOptions = {
     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/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";

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,13 +4,14 @@
  * Discovers and manages available coding agents.
  */
 
+import { CodexAdapter } from "./adapters/codex";
 import { ClaudeCodeAdapter } from "./claude";
 import type { AgentAdapter } from "./types";
 
 /** All known agent adapters */
 export const ALL_AGENTS: AgentAdapter[] = [
   new ClaudeCodeAdapter(),
-  // Future: new CodexAdapter(),
+  new CodexAdapter(),
   // Future: new OpenCodeAdapter(),
   // Future: new GeminiAdapter(),
 ];

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/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/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 });
 

package/src/cli/plan.ts

@@ -91,6 +91,7 @@ export async function planCommand(
     inputFile: options.from,
     modelTier,
     modelDef,
+    config,
   };
 
   // Run agent in plan mode