@nathapp/nax 0.50.2 → 0.51.0

package/src/agents/shared/model-resolution.ts

@@ -1,43 +0,0 @@
-/**
- * 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/shared/types-extended.ts

@@ -1,164 +0,0 @@
-/**
- * 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, NaxConfig } 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;
-  /** Global config — used to resolve models.balanced when modelDef is absent */
-  config?: Partial<NaxConfig>;
-  /**
-   * Interaction bridge for mid-session human Q&A (ACP only).
-   * If provided, the agent can pause and ask clarifying questions during planning.
-   */
-  interactionBridge?: {
-    detectQuestion: (text: string) => Promise<boolean>;
-    onQuestionDetected: (text: string) => Promise<string>;
-  };
-  /** Feature name for ACP session naming (plan→run continuity) */
-  featureName?: string;
-  /** Story ID for ACP session naming (plan→run continuity) */
-  storyId?: string;
-  /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
-  sessionRole?: string;
-  /** Timeout in seconds — inherited from config.execution.sessionTimeoutSeconds */
-  timeoutSeconds?: number;
-  /** Whether to skip permission prompts (maps to permissionMode in ACP) */
-  dangerouslySkipPermissions?: boolean;
-  /** Max interaction turns when interactionBridge is active (default: 10) */
-  maxInteractionTurns?: number;
-  /**
-   * Callback invoked with the ACP session name after the session is created.
-   * Used to persist the name to status.json for plan→run session continuity.
-   */
-  onAcpSessionCreated?: (sessionName: string) => Promise<void> | void;
-  /** PID registry for tracking spawned agent processes — cleanup on crash/SIGTERM */
-  pidRegistry?: import("../../execution/pid-registry").PidRegistry;
-}
-
-/**
- * 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;
-  /** Global config — used to resolve models.balanced when modelDef is absent */
-  config?: Partial<NaxConfig>;
-}
-
-/** 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?: import("../../config/test-strategy").TestStrategy;
-}
-
-/**
- * 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/shared/validation.ts

@@ -1,69 +0,0 @@
-/**
- * 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/agents/shared/version-detection.ts

@@ -1,109 +0,0 @@
-/**
- * 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/agents/types.ts

@@ -1,205 +0,0 @@
-/**
- * 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 { NaxConfig } from "../config";
-import type { ModelDef, ModelTier } from "../config/schema";
-import type { TokenUsage } from "./cost";
-
-// Re-export extended types for backward compatibility
-export type {
-  PlanOptions,
-  PlanResult,
-  DecomposeOptions,
-  DecomposeResult,
-  DecomposedStory,
-  PtyHandle,
-  InteractiveRunOptions,
-} from "./shared/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;
-  /** Token usage for this run (when available) */
-  tokenUsage?: TokenUsage;
-  /** 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;
-  /** Interaction bridge for mid-session human interaction (ACP) */
-  interactionBridge?: {
-    detectQuestion: (text: string) => Promise<boolean>;
-    onQuestionDetected: (text: string) => Promise<string>;
-  };
-  /** PID registry for cleanup on crash/SIGTERM */
-  pidRegistry?: import("../execution/pid-registry").PidRegistry;
-  /** ACP session name to resume for plan→run session continuity */
-  acpSessionName?: string;
-  /** Feature name for ACP session naming and logging */
-  featureName?: string;
-  /** Story ID for ACP session naming and logging */
-  storyId?: string;
-  /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
-  sessionRole?: string;
-  /** Max turns in multi-turn interaction loop when interactionBridge is active (default: 10) */
-  maxInteractionTurns?: number;
-  /** Pipeline stage this run belongs to — used by resolvePermissions() (default: "run") */
-  pipelineStage?: import("../config/permissions").PipelineStage;
-  /** Full nax config — passed through so adapters can call resolvePermissions() */
-  config?: NaxConfig;
-  /**
-   * When true, the adapter will NOT close the session after a successful run.
-   * Use this for rectification loops where the same session must persist across
-   * multiple attempts so the agent retains full conversation context.
-   * The caller is responsible for closing the session when the loop is done.
-   */
-  keepSessionOpen?: 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">;
-}
-
-/**
- * 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;
-  /** Whether to skip permission prompts (maps to permissionMode in ACP) */
-  dangerouslySkipPermissions?: boolean;
-  /**
-   * Working directory for the completion call.
-   * Used by ACP adapter to set --cwd on the spawned acpx session.
-   * CLI adapter uses this as the process cwd when spawning the agent binary.
-   */
-  workdir?: string;
-  /**
-   * Timeout for the completion call in milliseconds.
-   * Adapters that support it (e.g. ACP) will enforce this as a hard deadline.
-   * Callers may also wrap complete() in their own Promise.race for shorter timeouts.
-   */
-  timeoutMs?: number;
-  /**
-   * Full nax config — used by resolvePermissions() to determine permission mode.
-   * Pass when available so complete() honours permissionProfile / dangerouslySkipPermissions.
-   */
-  config?: NaxConfig;
-  /**
-   * Named session to use for this completion call.
-   * If omitted, a timestamp-based ephemeral session name is generated.
-   * Pass a meaningful name (e.g. "nax-decompose-us-001") to aid debugging.
-   */
-  sessionName?: 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.
- *
- * 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("./shared/types-extended").PlanOptions): Promise<import("./shared/types-extended").PlanResult>;
-
-  /** Run the agent in decompose mode to break spec into classified stories. */
-  decompose(
-    options: import("./shared/types-extended").DecomposeOptions,
-  ): Promise<import("./shared/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
-   * interactive terminal sessions (e.g., Claude Code).
-   */
-  runInteractive?(
-    options: import("./shared/types-extended").InteractiveRunOptions,
-  ): import("./shared/types-extended").PtyHandle;
-}