@nathapp/nax 0.38.0 → 0.38.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.38.0",
-  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "version": "0.38.2",
+  "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
     "nax": "./dist/nax.js"

package/src/agents/claude-complete.ts

@@ -0,0 +1,72 @@
+/**
+ * Claude Code Agent - Completion API
+ *
+ * Standalone completion endpoint for simple prompts.
+ */
+
+import type { CompleteOptions } from "./types";
+import { CompleteError } from "./types";
+
+/**
+ * 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;
+    };
+  },
+};
+
+/**
+ * Execute a simple completion request without starting a full agent session.
+ *
+ * @param binary - Path to claude binary
+ * @param prompt - Prompt text
+ * @param options - Completion options (model, tokens, format)
+ * @returns Completion text output
+ * @throws CompleteError if execution fails
+ */
+export async function executeComplete(binary: string, prompt: string, options?: CompleteOptions): Promise<string> {
+  const cmd = [binary, "-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;
+
+  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;
+}

package/src/agents/claude-execution.ts

@@ -0,0 +1,189 @@
+/**
+ * Claude Code Agent - Execution Layer
+ *
+ * Handles building commands, preparing environment, and process execution.
+ */
+
+import type { PidRegistry } from "../execution/pid-registry";
+import { withProcessTimeout } from "../execution/timeout-handler";
+import { getLogger } from "../logger";
+import { estimateCostByDuration, estimateCostFromOutput } from "./cost";
+import type { AgentResult, AgentRunOptions } from "./types";
+
+/**
+ * Maximum characters to capture from agent stdout.
+ */
+const MAX_AGENT_OUTPUT_CHARS = 5000;
+
+/**
+ * Maximum characters to capture from agent stderr.
+ */
+const MAX_AGENT_STDERR_CHARS = 1000;
+
+/**
+ * Grace period in ms between SIGTERM and SIGKILL on timeout.
+ */
+const SIGKILL_GRACE_PERIOD_MS = 5000;
+
+/**
+ * Injectable dependencies for runOnce() — allows tests to verify
+ * that PID cleanup (unregister) always runs even if kill() throws.
+ *
+ * @internal
+ */
+export const _runOnceDeps = {
+  killProc(proc: { kill(signal?: number | NodeJS.Signals): void }, signal: NodeJS.Signals): void {
+    proc.kill(signal);
+  },
+  buildCmd(binary: string, options: AgentRunOptions): string[] {
+    return buildCommand(binary, options);
+  },
+};
+
+/**
+ * Build Claude Code command with model and permissions.
+ *
+ * @param binary - Path to claude binary
+ * @param options - Agent run options
+ * @returns Command array for Bun.spawn()
+ */
+export function buildCommand(binary: string, options: AgentRunOptions): string[] {
+  const model = options.modelDef.model;
+  const skipPermissions = options.dangerouslySkipPermissions ?? true;
+  const permArgs = skipPermissions ? ["--dangerously-skip-permissions"] : [];
+  return [binary, "--model", model, ...permArgs, "-p", options.prompt];
+}
+
+/**
+ * Build allowed environment variables for spawned agents.
+ * SEC-4: Only pass essential env vars to prevent leaking sensitive data.
+ *
+ * @param options - Agent run options
+ * @returns Filtered environment variables
+ */
+export function 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;
+}
+
+/**
+ * Execute agent process once with timeout and signal handling.
+ *
+ * @param binary - Path to claude binary
+ * @param options - Agent run options
+ * @param pidRegistry - PID registry for cleanup
+ * @returns Agent execution result
+ *
+ * @internal
+ */
+export async function executeOnce(
+  binary: string,
+  options: AgentRunOptions,
+  pidRegistry: PidRegistry,
+): Promise<AgentResult> {
+  const cmd = _runOnceDeps.buildCmd(binary, options);
+  const startTime = Date.now();
+
+  const proc = Bun.spawn(cmd, {
+    cwd: options.workdir,
+    stdout: "pipe",
+    stderr: "inherit",
+    env: buildAllowedEnv(options),
+  });
+
+  const processPid = proc.pid;
+  await pidRegistry.register(processPid);
+
+  let timedOut = false;
+  let exitCode: number;
+  try {
+    const timeoutResult = await withProcessTimeout(proc, options.timeoutSeconds * 1000, {
+      graceMs: SIGKILL_GRACE_PERIOD_MS,
+      onTimeout: () => {
+        timedOut = true;
+      },
+      killFn: (p, signal) => _runOnceDeps.killProc(p, signal),
+    });
+    exitCode = timeoutResult.exitCode;
+    timedOut = timeoutResult.timedOut;
+  } finally {
+    await pidRegistry.unregister(processPid);
+  }
+
+  let stdoutTimeoutId: ReturnType<typeof setTimeout> | undefined;
+  const stdout = await Promise.race([
+    new Response(proc.stdout).text(),
+    new Promise<string>((resolve) => {
+      stdoutTimeoutId = setTimeout(() => resolve(""), 5000);
+    }),
+  ]);
+  clearTimeout(stdoutTimeoutId); // prevent leaked timer when stdout resolves first
+  const stderr = proc.stderr ? await new Response(proc.stderr).text() : "";
+  const durationMs = Date.now() - startTime;
+
+  const fullOutput = stdout + stderr;
+  const rateLimited =
+    fullOutput.toLowerCase().includes("rate limit") ||
+    fullOutput.includes("429") ||
+    fullOutput.toLowerCase().includes("too many requests");
+
+  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,
+  };
+}

package/src/agents/claude-interactive.ts

@@ -0,0 +1,77 @@
+/**
+ * Claude Code Agent - Interactive (TUI) Mode
+ *
+ * Handles terminal UI interactions with the Claude agent.
+ */
+
+import type { PidRegistry } from "../execution/pid-registry";
+import { getLogger } from "../logger";
+import { buildAllowedEnv } from "./claude-execution";
+import type { AgentRunOptions, InteractiveRunOptions, PtyHandle } from "./types";
+
+/**
+ * Run Claude agent in interactive (TTY) mode for TUI output.
+ *
+ * @param binary - Path to claude binary
+ * @param options - Interactive run options
+ * @param pidRegistry - PID registry for cleanup
+ * @returns PTY handle for stdin/stdout/kill control
+ */
+export function runInteractiveMode(
+  binary: string,
+  options: InteractiveRunOptions,
+  pidRegistry: PidRegistry,
+): PtyHandle {
+  const model = options.modelDef.model;
+  const cmd = [binary, "--model", model, options.prompt];
+
+  // BUN-001: Replaced node-pty with Bun.spawn (piped stdio).
+  // runInteractive() is TUI-only and currently dormant in headless nax runs.
+  // TERM + FORCE_COLOR preserve formatting output from Claude Code.
+  const allowedEnv = buildAllowedEnv(options as unknown as AgentRunOptions);
+  const proc = Bun.spawn(cmd, {
+    cwd: options.workdir,
+    env: { ...allowedEnv, TERM: "xterm-256color", FORCE_COLOR: "1" },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "inherit",
+  });
+
+  pidRegistry.register(proc.pid).catch(() => {});
+
+  // Stream stdout to onOutput callback
+  (async () => {
+    try {
+      for await (const chunk of proc.stdout) {
+        options.onOutput(Buffer.from(chunk));
+      }
+    } catch (err) {
+      // BUG-21: Handle stream errors to avoid unhandled rejections
+      getLogger()?.error("agent", "runInteractive stdout error", { err });
+    }
+  })();
+
+  // Fire onExit when process completes
+  proc.exited
+    .then((code) => {
+      pidRegistry.unregister(proc.pid).catch(() => {});
+      options.onExit(code ?? 1);
+    })
+    .catch((err) => {
+      // BUG-22: Guard against onExit or unregister throws
+      getLogger()?.error("agent", "runInteractive exit error", { err });
+    });
+
+  return {
+    write: (data: string) => {
+      proc.stdin.write(data);
+    },
+    resize: (_cols: number, _rows: number) => {
+      /* no-op: Bun.spawn has no PTY resize */
+    },
+    kill: () => {
+      proc.kill();
+    },
+    pid: proc.pid,
+  };
+}

package/src/agents/claude-plan.ts

@@ -8,6 +8,7 @@ import { join } from "node:path";
  */
 
 import type { PidRegistry } from "../execution/pid-registry";
+import { withProcessTimeout } from "../execution/timeout-handler";
 import { getLogger } from "../logger";
 import { resolveBalancedModelDef } from "./model-resolution";
 import type { AgentRunOptions } from "./types";
@@ -91,6 +92,8 @@ export async function runPlan(
     timeoutSeconds: 600,
   };
 
+  const PLAN_TIMEOUT_MS = 600_000; // 10 minutes
+
   if (options.interactive) {
     // Interactive mode: inherit stdio
     const proc = Bun.spawn(cmd, {
@@ -104,10 +107,16 @@ export async function runPlan(
     // Register PID
     await pidRegistry.register(proc.pid);
 
-    const exitCode = await proc.exited;
-
-    // Unregister PID after exit
-    await pidRegistry.unregister(proc.pid);
+    let exitCode: number;
+    try {
+      const timeoutResult = await withProcessTimeout(proc, PLAN_TIMEOUT_MS, {
+        graceMs: 5000,
+      });
+      exitCode = timeoutResult.exitCode;
+    } finally {
+      // Unregister PID after exit
+      await pidRegistry.unregister(proc.pid);
+    }
 
     if (exitCode !== 0) {
       throw new Error(`Plan mode failed with exit code ${exitCode}`);
@@ -133,10 +142,16 @@ export async function runPlan(
     // Register PID
     await pidRegistry.register(proc.pid);
 
-    const exitCode = await proc.exited;
-
-    // Unregister PID after exit
-    await pidRegistry.unregister(proc.pid);
+    let exitCode: number;
+    try {
+      const timeoutResult = await withProcessTimeout(proc, PLAN_TIMEOUT_MS, {
+        graceMs: 5000,
+      });
+      exitCode = timeoutResult.exitCode;
+    } finally {
+      // Unregister PID after exit
+      await pidRegistry.unregister(proc.pid);
+    }
 
     const specContent = await Bun.file(outFile).text();
     const conversationLog = await Bun.file(errFile).text();