@nathapp/nax 0.18.1

package/src/agents/claude.ts

@@ -0,0 +1,324 @@
+/**
+ * Claude Code Agent Adapter
+ */
+
+import { PidRegistry } from "../execution/pid-registry";
+import { getLogger } from "../logger";
+import { buildDecomposePrompt, parseDecomposeOutput } from "./claude-decompose";
+import { runPlan } from "./claude-plan";
+import { estimateCostByDuration, estimateCostFromOutput } from "./cost";
+import type {
+  AgentAdapter,
+  AgentCapabilities,
+  AgentResult,
+  AgentRunOptions,
+  DecomposeOptions,
+  DecomposeResult,
+  InteractiveRunOptions,
+  PlanOptions,
+  PlanResult,
+  PtyHandle,
+} from "./types";
+
+/**
+ * Maximum characters to capture from agent stdout.
+ *
+ * Last 5000 chars typically contain the most relevant info (final status, summary, errors).
+ * This limit prevents memory bloat while preserving actionable output.
+ */
+const MAX_AGENT_OUTPUT_CHARS = 5000;
+
+/**
+ * Maximum characters to capture from agent stderr.
+ *
+ * Last 1000 chars typically contain the actual error message (e.g., 401, 500, crash).
+ * Smaller than stdout since stderr is more focused on errors.
+ */
+const MAX_AGENT_STDERR_CHARS = 1000;
+
+/**
+ * Claude Code agent adapter implementation.
+ *
+ * Implements the AgentAdapter interface for Claude Code CLI,
+ * supporting model routing, rate limit retry, and cost tracking.
+ */
+export class ClaudeCodeAdapter implements AgentAdapter {
+  readonly name = "claude";
+  readonly displayName = "Claude Code";
+  readonly binary = "claude";
+
+  readonly capabilities: AgentCapabilities = {
+    supportedTiers: ["fast", "balanced", "powerful"],
+    maxContextTokens: 200_000,
+    features: new Set(["tdd", "review", "refactor", "batch"]),
+  };
+
+  private pidRegistries: Map<string, PidRegistry> = new Map();
+
+  private getPidRegistry(workdir: string): PidRegistry {
+    if (!this.pidRegistries.has(workdir)) {
+      this.pidRegistries.set(workdir, new PidRegistry(workdir));
+    }
+    const registry = this.pidRegistries.get(workdir);
+    if (!registry) {
+      throw new Error(`PidRegistry not found for workdir: ${workdir}`);
+    }
+    return registry;
+  }
+
+  async isInstalled(): Promise<boolean> {
+    try {
+      const proc = Bun.spawn(["which", this.binary], { stdout: "pipe", stderr: "pipe" });
+      const code = await proc.exited;
+      return code === 0;
+    } catch (error) {
+      const logger = getLogger();
+      logger?.debug("agent", "Failed to check if agent is installed", { error });
+      return false;
+    }
+  }
+
+  buildCommand(options: AgentRunOptions): string[] {
+    const model = options.modelDef.model;
+    const skipPermissions = options.dangerouslySkipPermissions ?? true;
+    const permArgs = skipPermissions ? ["--dangerously-skip-permissions"] : [];
+    return [this.binary, "--model", model, ...permArgs, "-p", options.prompt];
+  }
+
+  async run(options: AgentRunOptions): Promise<AgentResult> {
+    const maxRetries = 3;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const result = await this.runOnce(options, attempt);
+
+        if (result.rateLimited && attempt < maxRetries) {
+          const backoffMs = 2 ** attempt * 1000;
+          const logger = getLogger();
+          logger.warn("agent", "Rate limited, retrying", { backoffSeconds: backoffMs / 1000, attempt, maxRetries });
+          await Bun.sleep(backoffMs);
+          continue;
+        }
+
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+        const isSpawnError = lastError.message.includes("spawn") || lastError.message.includes("ENOENT");
+
+        if (isSpawnError && attempt < maxRetries) {
+          const backoffMs = 2 ** attempt * 1000;
+          const logger = getLogger();
+          logger.warn("agent", "Agent spawn error, retrying", {
+            error: lastError.message,
+            backoffSeconds: backoffMs / 1000,
+            attempt,
+            maxRetries,
+          });
+          await Bun.sleep(backoffMs);
+          continue;
+        }
+
+        throw lastError;
+      }
+    }
+
+    throw lastError || new Error("Agent execution failed after all retries");
+  }
+
+  /**
+   * Build allowed environment variables for spawned agents.
+   * SEC-4: Only pass essential env vars to prevent leaking sensitive data.
+   */
+  buildAllowedEnv(options: AgentRunOptions): Record<string, string | undefined> {
+    const allowed: Record<string, string | undefined> = {};
+
+    const essentialVars = ["PATH", "HOME", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
+    for (const varName of essentialVars) {
+      if (process.env[varName]) {
+        allowed[varName] = process.env[varName];
+      }
+    }
+
+    const apiKeyVars = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+    for (const varName of apiKeyVars) {
+      if (process.env[varName]) {
+        allowed[varName] = process.env[varName];
+      }
+    }
+
+    const allowedPrefixes = ["CLAUDE_", "NAX_", "CLAW_", "TURBO_"];
+    for (const [key, value] of Object.entries(process.env)) {
+      if (allowedPrefixes.some((prefix) => key.startsWith(prefix))) {
+        allowed[key] = value;
+      }
+    }
+
+    if (options.modelDef.env) {
+      Object.assign(allowed, options.modelDef.env);
+    }
+
+    if (options.env) {
+      Object.assign(allowed, options.env);
+    }
+
+    return allowed;
+  }
+
+  private async runOnce(options: AgentRunOptions, _attempt: number): Promise<AgentResult> {
+    const cmd = this.buildCommand(options);
+    const startTime = Date.now();
+
+    const proc = Bun.spawn(cmd, {
+      cwd: options.workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: this.buildAllowedEnv(options),
+    });
+
+    const processPid = proc.pid;
+    const pidRegistry = this.getPidRegistry(options.workdir);
+    await pidRegistry.register(processPid);
+
+    let timedOut = false;
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      proc.kill("SIGTERM");
+    }, options.timeoutSeconds * 1000);
+
+    const exitCode = await proc.exited;
+    clearTimeout(timeoutId);
+
+    await pidRegistry.unregister(processPid);
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const durationMs = Date.now() - startTime;
+
+    const rateLimited =
+      stderr.includes("rate limit") ||
+      stderr.includes("429") ||
+      stdout.includes("rate limit") ||
+      stdout.includes("Too many requests");
+
+    const fullOutput = stdout + stderr;
+    let costEstimate = estimateCostFromOutput(options.modelTier, fullOutput);
+    const logger = getLogger();
+    if (!costEstimate) {
+      const fallbackEstimate = estimateCostByDuration(options.modelTier, durationMs);
+      costEstimate = {
+        cost: fallbackEstimate.cost * 1.5,
+        confidence: "fallback",
+      };
+      logger.warn("agent", "Cost estimation fallback (duration-based)", {
+        modelTier: options.modelTier,
+        cost: costEstimate.cost,
+      });
+    } else if (costEstimate.confidence === "estimated") {
+      logger.warn("agent", "Cost estimation using regex parsing (estimated confidence)", { cost: costEstimate.cost });
+    }
+    const cost = costEstimate.cost;
+
+    const actualExitCode = timedOut ? 124 : exitCode;
+
+    return {
+      success: exitCode === 0 && !timedOut,
+      exitCode: actualExitCode,
+      output: stdout.slice(-MAX_AGENT_OUTPUT_CHARS),
+      stderr: stderr.slice(-MAX_AGENT_STDERR_CHARS),
+      rateLimited,
+      durationMs,
+      estimatedCost: cost,
+      pid: processPid,
+    };
+  }
+
+  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 prompt = buildDecomposePrompt(options);
+
+    const cmd = [
+      this.binary,
+      "--model",
+      options.modelDef?.model || "claude-sonnet-4-5",
+      "--dangerously-skip-permissions",
+      "-p",
+      prompt,
+    ];
+
+    const pidRegistry = this.getPidRegistry(options.workdir);
+
+    const proc = Bun.spawn(cmd, {
+      cwd: options.workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: this.buildAllowedEnv({
+        workdir: options.workdir,
+        modelDef: options.modelDef || { provider: "anthropic", model: "claude-sonnet-4-5", env: {} },
+        prompt: "",
+        modelTier: "balanced",
+        timeoutSeconds: 600,
+      }),
+    });
+
+    await pidRegistry.register(proc.pid);
+
+    const exitCode = await proc.exited;
+
+    await pidRegistry.unregister(proc.pid);
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      throw new Error(`Decompose failed with exit code ${exitCode}: ${stderr}`);
+    }
+
+    const stories = parseDecomposeOutput(stdout);
+
+    return { stories };
+  }
+
+  runInteractive(options: InteractiveRunOptions): PtyHandle {
+    let nodePty: typeof import("node-pty");
+    try {
+      nodePty = require("node-pty");
+    } catch (error) {
+      throw new Error(`node-pty not available: ${(error as Error).message}`);
+    }
+
+    const model = options.modelDef.model;
+    const cmd = [this.binary, "--model", model, options.prompt];
+
+    const ptyProc = nodePty.spawn(cmd[0], cmd.slice(1), {
+      name: "xterm-256color",
+      cols: 80,
+      rows: 24,
+      cwd: options.workdir,
+      env: this.buildAllowedEnv(options),
+    });
+
+    const pidRegistry = this.getPidRegistry(options.workdir);
+    pidRegistry.register(ptyProc.pid).catch(() => {});
+
+    ptyProc.onData((data) => {
+      options.onOutput(Buffer.from(data));
+    });
+
+    ptyProc.onExit((event) => {
+      pidRegistry.unregister(ptyProc.pid).catch(() => {});
+      options.onExit(event.exitCode);
+    });
+
+    return {
+      write: (data: string) => ptyProc.write(data),
+      resize: (cols: number, rows: number) => ptyProc.resize(cols, rows),
+      kill: () => ptyProc.kill(),
+      pid: ptyProc.pid,
+    };
+  }
+}

package/src/agents/cost.ts

@@ -0,0 +1,268 @@
+/**
+ * Cost Tracking
+ *
+ * Token-based cost estimation for AI coding agents.
+ * Parses agent output for token usage and calculates costs.
+ */
+
+import type { ModelTier } from "../config/schema";
+
+/** Cost rates per 1M tokens (USD) */
+export interface ModelCostRates {
+  inputPer1M: number;
+  outputPer1M: number;
+}
+
+/** Token usage data */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** Cost estimate with confidence indicator */
+export interface CostEstimate {
+  cost: number;
+  confidence: "exact" | "estimated" | "fallback";
+}
+
+/** Model tier cost rates (as of 2025-01) */
+export const COST_RATES: Record<ModelTier, ModelCostRates> = {
+  fast: {
+    // Haiku 4.5
+    inputPer1M: 0.8,
+    outputPer1M: 4.0,
+  },
+  balanced: {
+    // Sonnet 4.5
+    inputPer1M: 3.0,
+    outputPer1M: 15.0,
+  },
+  powerful: {
+    // Opus 4
+    inputPer1M: 15.0,
+    outputPer1M: 75.0,
+  },
+};
+
+/**
+ * Token usage with confidence indicator.
+ */
+export interface TokenUsageWithConfidence {
+  inputTokens: number;
+  outputTokens: number;
+  confidence: "exact" | "estimated";
+}
+
+/**
+ * Parse Claude Code output for token usage.
+ *
+ * Supports multiple formats with varying confidence levels:
+ * - JSON structured output → "exact" confidence
+ * - Markdown/plain text patterns → "estimated" confidence
+ *
+ * Uses specific regex patterns to reduce false positives.
+ *
+ * @param output - Agent stdout + stderr combined
+ * @returns Token usage with confidence indicator, or null if tokens cannot be parsed
+ *
+ * @example
+ * ```ts
+ * // JSON format (exact)
+ * const usage1 = parseTokenUsage('{"usage": {"input_tokens": 1234, "output_tokens": 5678}}');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'exact' }
+ *
+ * // Markdown format (estimated)
+ * const usage2 = parseTokenUsage('Input tokens: 1234\nOutput tokens: 5678');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'estimated' }
+ *
+ * // Unparseable
+ * const usage3 = parseTokenUsage('No token data here');
+ * // null
+ * ```
+ */
+export function parseTokenUsage(output: string): TokenUsageWithConfidence | null {
+  // Try JSON format first (most reliable) - confidence: exact
+  try {
+    const jsonMatch = output.match(
+      /\{[^}]*"usage"\s*:\s*\{[^}]*"input_tokens"\s*:\s*(\d+)[^}]*"output_tokens"\s*:\s*(\d+)[^}]*\}[^}]*\}/,
+    );
+    if (jsonMatch) {
+      return {
+        inputTokens: Number.parseInt(jsonMatch[1], 10),
+        outputTokens: Number.parseInt(jsonMatch[2], 10),
+        confidence: "exact",
+      };
+    }
+
+    // Try parsing as full JSON object
+    const lines = output.split("\n");
+    for (const line of lines) {
+      if (line.trim().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.usage?.input_tokens && parsed.usage?.output_tokens) {
+            return {
+              inputTokens: parsed.usage.input_tokens,
+              outputTokens: parsed.usage.output_tokens,
+              confidence: "exact",
+            };
+          }
+        } catch {
+          // Not valid JSON, continue
+        }
+      }
+    }
+  } catch {
+    // JSON parsing failed, try regex patterns
+  }
+
+  // Try specific markdown-style patterns (more specific to reduce false positives)
+  // Match "Input tokens: 1234" or "input_tokens: 1234" or "INPUT TOKENS: 1234"
+  // Use word boundary at start, require colon or space after keyword, then digits
+  // confidence: estimated (regex-based)
+  const inputMatch = output.match(/\b(?:input|input_tokens)\s*:\s*(\d{2,})|(?:input)\s+(?:tokens?)\s*:\s*(\d{2,})/i);
+  const outputMatch = output.match(
+    /\b(?:output|output_tokens)\s*:\s*(\d{2,})|(?:output)\s+(?:tokens?)\s*:\s*(\d{2,})/i,
+  );
+
+  if (inputMatch && outputMatch) {
+    // Extract token counts (may be in capture group 1 or 2)
+    const inputTokens = Number.parseInt(inputMatch[1] || inputMatch[2], 10);
+    const outputTokens = Number.parseInt(outputMatch[1] || outputMatch[2], 10);
+
+    // Sanity check: reject if tokens seem unreasonably large (> 1M each)
+    if (inputTokens > 1_000_000 || outputTokens > 1_000_000) {
+      return null;
+    }
+
+    return {
+      inputTokens,
+      outputTokens,
+      confidence: "estimated",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Estimate cost in USD based on token usage.
+ *
+ * Calculates total cost using tier-specific rates per 1M tokens.
+ *
+ * @param modelTier - Model tier (fast/balanced/powerful)
+ * @param inputTokens - Number of input tokens consumed
+ * @param outputTokens - Number of output tokens generated
+ * @returns Total cost in USD
+ *
+ * @example
+ * ```ts
+ * const cost = estimateCost("balanced", 10000, 5000);
+ * // Sonnet 4.5: (10000/1M * $3.00) + (5000/1M * $15.00) = $0.105
+ * ```
+ */
+export function estimateCost(
+  modelTier: ModelTier,
+  inputTokens: number,
+  outputTokens: number,
+  customRates?: ModelCostRates,
+): number {
+  const rates = customRates ?? COST_RATES[modelTier];
+  const inputCost = (inputTokens / 1_000_000) * rates.inputPer1M;
+  const outputCost = (outputTokens / 1_000_000) * rates.outputPer1M;
+  return inputCost + outputCost;
+}
+
+/**
+ * Estimate cost from agent output by parsing token usage.
+ *
+ * Attempts to extract token counts from stdout/stderr, then calculates cost.
+ * Returns null if tokens cannot be parsed (caller should use fallback estimation).
+ *
+ * @param modelTier - Model tier for cost calculation
+ * @param output - Agent stdout + stderr combined
+ * @returns Cost estimate with confidence indicator, or null if unparseable
+ *
+ * @example
+ * ```ts
+ * const estimate = estimateCostFromOutput("balanced", agentOutput);
+ * if (estimate) {
+ *   console.log(`Cost: $${estimate.cost.toFixed(4)} (${estimate.confidence})`);
+ * } else {
+ *   // Fall back to duration-based estimation
+ * }
+ * ```
+ */
+export function estimateCostFromOutput(modelTier: ModelTier, output: string): CostEstimate | null {
+  const usage = parseTokenUsage(output);
+  if (!usage) {
+    return null;
+  }
+  const cost = estimateCost(modelTier, usage.inputTokens, usage.outputTokens);
+  return {
+    cost,
+    confidence: usage.confidence,
+  };
+}
+
+/**
+ * Fallback cost estimation based on runtime duration.
+ *
+ * Used when token usage cannot be parsed from agent output.
+ * Provides conservative estimates using per-minute rates.
+ *
+ * @param modelTier - Model tier for cost calculation
+ * @param durationMs - Agent runtime in milliseconds
+ * @returns Cost estimate with 'fallback' confidence
+ *
+ * @example
+ * ```ts
+ * const estimate = estimateCostByDuration("balanced", 120000); // 2 minutes
+ * // { cost: 0.10, confidence: 'fallback' }
+ * // Sonnet: 2 min * $0.05/min = $0.10
+ * ```
+ */
+export function estimateCostByDuration(modelTier: ModelTier, durationMs: number): CostEstimate {
+  const costPerMinute: Record<ModelTier, number> = {
+    fast: 0.01,
+    balanced: 0.05,
+    powerful: 0.15,
+  };
+  const minutes = durationMs / 60000;
+  const cost = minutes * costPerMinute[modelTier];
+  return {
+    cost,
+    confidence: "fallback",
+  };
+}
+
+/**
+ * Format cost estimate with confidence indicator for display.
+ *
+ * @param estimate - Cost estimate with confidence level
+ * @returns Formatted cost string with confidence indicator
+ *
+ * @example
+ * ```ts
+ * formatCostWithConfidence({ cost: 0.12, confidence: 'exact' });
+ * // "$0.12"
+ *
+ * formatCostWithConfidence({ cost: 0.15, confidence: 'estimated' });
+ * // "~$0.15"
+ *
+ * formatCostWithConfidence({ cost: 0.05, confidence: 'fallback' });
+ * // "~$0.05 (duration-based)"
+ * ```
+ */
+export function formatCostWithConfidence(estimate: CostEstimate): string {
+  const formattedCost = `$${estimate.cost.toFixed(2)}`;
+
+  switch (estimate.confidence) {
+    case "exact":
+      return formattedCost;
+    case "estimated":
+      return `~${formattedCost}`;
+    case "fallback":
+      return `~${formattedCost} (duration-based)`;
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,13 @@
+export type { AgentAdapter, AgentCapabilities, AgentResult, AgentRunOptions } from "./types";
+export { ClaudeCodeAdapter } from "./claude";
+export { getAllAgentNames, getAgent, getInstalledAgents, checkAgentHealth } from "./registry";
+export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence } from "./cost";
+export {
+  COST_RATES,
+  parseTokenUsage,
+  estimateCost,
+  estimateCostFromOutput,
+  estimateCostByDuration,
+  formatCostWithConfidence,
+} from "./cost";
+export { validateAgentForTier, validateAgentFeature, describeAgentCapabilities } from "./validation";

package/src/agents/registry.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent Registry
+ *
+ * Discovers and manages available coding agents.
+ */
+
+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(),
+];
+
+/** Get all registered agent names */
+export function getAllAgentNames(): string[] {
+  return ALL_AGENTS.map((a) => a.name);
+}
+
+/** Get a specific agent by name */
+export function getAgent(name: string): AgentAdapter | undefined {
+  return ALL_AGENTS.find((a) => a.name === name);
+}
+
+/** Get all installed agents on this machine */
+export async function getInstalledAgents(): Promise<AgentAdapter[]> {
+  const results = await Promise.all(
+    ALL_AGENTS.map(async (agent) => ({
+      agent,
+      installed: await agent.isInstalled(),
+    })),
+  );
+  return results.filter((r) => r.installed).map((r) => r.agent);
+}
+
+/** Check health of all agents */
+export async function checkAgentHealth(): Promise<Array<{ name: string; displayName: string; installed: boolean }>> {
+  return Promise.all(
+    ALL_AGENTS.map(async (agent) => ({
+      name: agent.name,
+      displayName: agent.displayName,
+      installed: await agent.isInstalled(),
+    })),
+  );
+}