@nyxa/nyx-agent 0.5.0 → 0.6.0

package/README.md

@@ -42,6 +42,7 @@ nyxagent update               # self-update to the latest published version
   "model": "gpt-5.5",
   "reasoning_effort": "medium",
   "review": "each",
+  "review_max_attempts": 4,
   "tracker": { "type": "github", "repo": "owner/repo" },
   "base_branch": "main",
   "max_iterations": 5
@@ -50,8 +51,13 @@ nyxagent update               # self-update to the latest published version
 
 - `harness`: `codex` or `claude` (override per run with `--harness`).
 - `review`: `each` (per task), `all` (global only), `both`, or `none`.
+- `review_max_attempts`: review+revise rounds per stage before the run fails (default 4).
 - `base_branch`: optional; defaults to the current branch at run time.
 
+If a run fails review after exhausting its attempts but has already produced
+commits, NyxAgent pushes the branch and opens a **draft** pull request with the
+unresolved feedback, so the work is never stranded on an orphaned branch.
+
 ## Requirements
 
 - A git repository with a GitHub remote.

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/** CLI entry point: declares the `init`, `run`, and `update` commands and dispatches them. */
 import { Command } from "commander";
 import { createRequire } from "node:module";
 import pc from "picocolors";
@@ -19,6 +20,7 @@ program
     .option("--model <name>", "model name")
     .option("--reasoning-effort <level>", "reasoning effort (default: medium)")
     .option("--review <mode>", "review strategy: each, all, both, or none")
+    .option("--review-attempts <count>", "max review attempts per stage (default: 4)")
     .option("--repo <owner/repo>", "GitHub repository")
     .option("--base-branch <branch>", "base branch (default: current branch)")
     .option("--max-iterations <count>", "maximum work items per run")

package/dist/commands/init.js

@@ -1,3 +1,4 @@
+/** `nyxagent init`: scaffolds .nyxagent/config.json, the editable execution prompt, and .gitignore entries. */
 import path from "node:path";
 import { input, number as numberPrompt, select } from "@inquirer/prompts";
 import pc from "picocolors";
@@ -7,10 +8,16 @@ import { getNyxDir, relativeToProject } from "../runtime/paths.js";
 import { EXECUTION_PROMPT_FILE } from "../runtime/prompts.js";
 const DEFAULT_CODEX_MODEL = "gpt-5.5";
 const GITIGNORE_MARKER = "# NyxAgent runtime artifacts";
+// Everything under .nyxagent/ is NyxAgent's own plumbing. Ignoring it keeps it
+// out of the agent's worktree checkout and out of the commits/diffs it reviews,
+// so the agent can never accidentally edit (or review) NyxAgent's own files.
 const GITIGNORE_ENTRIES = [
     ".nyxagent/runs/",
     ".nyxagent/worktrees/",
-    ".nyxagent/state.json"
+    ".nyxagent/state.json",
+    ".nyxagent/config.json",
+    ".nyxagent/config.toml",
+    ".nyxagent/prompts/"
 ];
 export async function initCommand(options, projectRoot = process.cwd()) {
     const root = path.resolve(projectRoot);
@@ -62,6 +69,17 @@ async function resolveInitOptions(options) {
             ],
             default: "each"
         });
+    const review_max_attempts = review === "none"
+        ? 4
+        : parseReviewAttempts(options.reviewAttempts) ??
+            (await numberPrompt({
+                message: "Max review attempts per stage",
+                default: 4,
+                required: true
+            }));
+    if (!Number.isInteger(review_max_attempts) || review_max_attempts <= 0) {
+        throw new Error("review attempts must be a positive integer");
+    }
     const repo = options.repo ?? (await input({ message: "GitHub repository (owner/repo)" }));
     validateRepository(repo);
     const baseBranchInput = options.baseBranch ??
@@ -84,6 +102,7 @@ async function resolveInitOptions(options) {
         model: model.trim(),
         reasoning_effort: reasoning_effort.trim() || "medium",
         review,
+        review_max_attempts,
         repo,
         base_branch,
         max_iterations
@@ -98,6 +117,10 @@ function buildConfig(options) {
         tracker: { type: "github", repo: options.repo },
         max_iterations: options.max_iterations
     };
+    // No point persisting an attempts cap when reviews are disabled.
+    if (options.review !== "none") {
+        config.review_max_attempts = options.review_max_attempts;
+    }
     if (options.base_branch) {
         config.base_branch = options.base_branch;
     }
@@ -126,6 +149,12 @@ function parseMaxIterations(value) {
     }
     return Number.parseInt(value, 10);
 }
+function parseReviewAttempts(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return Number.parseInt(value, 10);
+}
 async function ensureGitignoreEntries(root) {
     const gitignorePath = path.join(root, ".gitignore");
     const current = (await pathExists(gitignorePath))

package/dist/commands/run.js

@@ -1,3 +1,4 @@
+/** `nyxagent run`: normalizes CLI options and hands off to the pipeline runner. */
 import path from "node:path";
 import { harnessNames } from "../config/schema.js";
 import { runPipeline } from "../runtime/runPipeline.js";

package/dist/commands/update.js

@@ -1,3 +1,4 @@
+/** `nyxagent update`: self-update command that resolves the target version from npm and installs it globally. */
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { confirm } from "@inquirer/prompts";

package/dist/config/loadConfig.js

@@ -1,3 +1,4 @@
+/** Reads, JSON-parses, and schema-validates a .nyxagent/config.json file. */
 import { readFile } from "node:fs/promises";
 import { nyxConfigSchema } from "./schema.js";
 export async function loadConfig(configPath) {

package/dist/config/schema.js

@@ -18,6 +18,8 @@ export const nyxConfigSchema = z
     reasoning_effort: z.string().min(1).default("medium"),
     /** When the agent reviews its own work. */
     review: z.enum(reviewModes).default("each"),
+    /** How many review+revise rounds a review stage gets before the run fails. */
+    review_max_attempts: z.number().int().positive().default(4),
     /** Work item tracker. GitHub issues only in this version. */
     tracker: z.object({
         type: z.literal("github"),

package/dist/runtime/files.js

@@ -1,3 +1,4 @@
+/** Small filesystem helpers: ensure a directory, read/write text and JSON, check existence. */
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 export async function ensureDir(dir) {

package/dist/runtime/git.js

@@ -1,3 +1,4 @@
+/** Read-only git snapshot (branch, HEAD, short status) recorded around each phase for the audit trail. */
 import { execa } from "execa";
 export async function getGitSnapshot(cwd) {
     const isRepo = await execa("git", ["rev-parse", "--is-inside-work-tree"], {

package/dist/runtime/ledger.js

@@ -1,3 +1,4 @@
+/** Tracks which work items each run completed (.nyxagent/state.json) so they are skipped on later runs. */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeJson } from "./files.js";

package/dist/runtime/paths.js

@@ -1,3 +1,4 @@
+/** Project path helpers: locate the .nyxagent directory and render project-relative paths. */
 import path from "node:path";
 export function getNyxDir(projectRoot) {
     return path.join(projectRoot, ".nyxagent");

package/dist/runtime/runPipeline.js

@@ -13,7 +13,6 @@ import { createRunId } from "./time.js";
 import { filterAvailable, listGitHubIssues, resolveSelectedQueue } from "./workItems.js";
 const MAX_CANDIDATES = 50;
 const EXCERPT_CHARS = 800;
-const REVIEW_MAX_ATTEMPTS = 3;
 export function defaultPipelineDependencies() {
     return {
         listIssues: listGitHubIssues,
@@ -106,6 +105,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                     git,
                     harness,
                     config,
+                    maxAttempts: config.review_max_attempts,
                     runPhase: deps.runPhase
                 });
             }
@@ -132,6 +132,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                 git,
                 harness,
                 config,
+                maxAttempts: config.review_max_attempts,
                 runPhase: deps.runPhase
             });
             if (corrections) {
@@ -155,6 +156,21 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         console.log(pc.green(`\nPull request opened: ${prUrl}`));
         success = true;
     }
+    catch (error) {
+        // A failed run that already produced commits is salvaged into a draft PR so
+        // the work is never stranded on an orphaned branch; the error still
+        // propagates so the exit code reflects the failure.
+        await salvageFailedRun({
+            error,
+            projectRoot,
+            git,
+            producedCommits,
+            completed,
+            config,
+            deps
+        });
+        throw error;
+    }
     finally {
         if (success) {
             await removeRunWorktree({ projectRoot, worktree: git.worktree });
@@ -162,10 +178,55 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                 await deleteBranch({ projectRoot, branch: git.branch });
             }
         }
-        else {
-            console.log(pc.red(`\nRun failed. Branch ${git.branch} and worktree kept for debugging: ${relativeToProject(projectRoot, git.worktree)}`));
+    }
+}
+/**
+ * Failure handling that preserves work. If the run produced commits, push the
+ * branch and open a DRAFT pull request describing why it failed, so a human can
+ * finish it. Otherwise just keep the branch/worktree for debugging. The branch
+ * and worktree are always kept on failure.
+ */
+async function salvageFailedRun(input) {
+    const location = relativeToProject(input.projectRoot, input.git.worktree);
+    // Best-effort: never let salvage throw and mask the original failure.
+    let ahead = 0;
+    if (input.producedCommits) {
+        try {
+            ahead = await commitsAhead(input.git.worktree, input.git.base);
+        }
+        catch {
+            ahead = 0;
         }
     }
+    if (ahead === 0) {
+        console.log(pc.red(`\nRun failed. Branch ${input.git.branch} and worktree kept for debugging: ${location}`));
+        return;
+    }
+    const reason = input.error instanceof Error ? input.error.message : String(input.error);
+    try {
+        await input.deps.pushBranch({
+            cwd: input.git.worktree,
+            branch: input.git.branch
+        });
+        const url = await input.deps.createPullRequest({
+            cwd: input.git.worktree,
+            repo: input.config.tracker.repo,
+            base: input.git.base,
+            head: input.git.branch,
+            title: buildDraftPrTitle(input.completed),
+            body: buildDraftPrBody(input.completed, reason),
+            draft: true
+        });
+        console.log(pc.yellow(`\nRun failed, but the work was salvaged into a DRAFT pull request: ${url}`));
+        console.log(pc.yellow(`Branch ${input.git.branch} and worktree kept: ${location}`));
+    }
+    catch (salvageError) {
+        const detail = salvageError instanceof Error
+            ? salvageError.message
+            : String(salvageError);
+        console.log(pc.red(`\nRun failed, and salvaging the work into a draft pull request also failed: ${detail}`));
+        console.log(pc.red(`Branch ${input.git.branch} and worktree kept for debugging: ${location}`));
+    }
 }
 async function runSelection(input) {
     const context = buildContextBlock([
@@ -235,7 +296,7 @@ async function runExecution(input) {
     }
 }
 async function runReviewLoop(input) {
-    for (let attempt = 1; attempt <= REVIEW_MAX_ATTEMPTS; attempt += 1) {
+    for (let attempt = 1; attempt <= input.maxAttempts; attempt += 1) {
         const diff = await stageAllAndDiff(input.git.worktree);
         const reviewResult = await input.runPhase({
             phaseId: "review",
@@ -263,8 +324,8 @@ async function runReviewLoop(input) {
         if (review.outcome === "approved") {
             return;
         }
-        if (attempt === REVIEW_MAX_ATTEMPTS) {
-            throw new Error(`Review for #${input.item.number} not approved after ${REVIEW_MAX_ATTEMPTS} attempts: ${review.summary}`);
+        if (attempt === input.maxAttempts) {
+            throw new Error(`Review for #${input.item.number} not approved after ${input.maxAttempts} attempts: ${review.summary}${formatRequiredChanges(review.required_changes)}`);
         }
         const revision = await input.runPhase({
             phaseId: "revision",
@@ -289,7 +350,7 @@ async function runReviewLoop(input) {
 }
 async function runGlobalReviewLoop(input) {
     let committedCorrections = false;
-    for (let attempt = 1; attempt <= REVIEW_MAX_ATTEMPTS; attempt += 1) {
+    for (let attempt = 1; attempt <= input.maxAttempts; attempt += 1) {
         const diff = await rangeDiff(input.git.worktree, input.git.base);
         const reviewResult = await input.runPhase({
             phaseId: "global_review",
@@ -320,8 +381,8 @@ async function runGlobalReviewLoop(input) {
         if (review.outcome === "approved") {
             return committedCorrections;
         }
-        if (attempt === REVIEW_MAX_ATTEMPTS) {
-            throw new Error(`Global review not approved after ${REVIEW_MAX_ATTEMPTS} attempts: ${review.summary}`);
+        if (attempt === input.maxAttempts) {
+            throw new Error(`Global review not approved after ${input.maxAttempts} attempts: ${review.summary}${formatRequiredChanges(review.required_changes)}`);
         }
         const revision = await input.runPhase({
             phaseId: "global_revision",
@@ -393,3 +454,26 @@ function buildPrBody(items) {
         closes
     ].join("\n");
 }
+function buildDraftPrTitle(items) {
+    return `[Draft] ${buildPrTitle(items)}`;
+}
+function buildDraftPrBody(items, reason) {
+    return [
+        "> [!WARNING]",
+        "> This pull request was opened automatically by NyxAgent after the run",
+        "> **failed review**. The work is preserved here for a human to finish.",
+        "",
+        `**Why the run failed:** ${reason}`,
+        "",
+        buildPrBody(items)
+    ].join("\n");
+}
+/** Render review `required_changes` as a bullet list to append to a failure message. */
+function formatRequiredChanges(changes) {
+    if (!changes || changes.length === 0) {
+        return "";
+    }
+    return `\n\nUnresolved review feedback:\n${changes
+        .map((change) => `- ${change}`)
+        .join("\n")}`;
+}

package/dist/runtime/scm.js

@@ -54,7 +54,7 @@ export async function pushBranch(input) {
     await git(input.cwd, ["push", "-u", "origin", input.branch], "push");
 }
 export async function createPullRequest(input) {
-    const result = await execa("gh", [
+    const args = [
         "pr",
         "create",
         "--repo",
@@ -67,7 +67,11 @@ export async function createPullRequest(input) {
         input.title,
         "--body",
         input.body
-    ], { cwd: input.cwd, reject: false });
+    ];
+    if (input.draft) {
+        args.push("--draft");
+    }
+    const result = await execa("gh", args, { cwd: input.cwd, reject: false });
     if (result.exitCode !== 0) {
         const detail = (result.stderr || result.stdout || "unknown error").trim();
         throw new Error(`gh pr create failed: ${detail}`);

package/dist/runtime/time.js

@@ -1,3 +1,4 @@
+/** Builds a filesystem-safe, lexicographically sortable run id from a timestamp. */
 export function createRunId(date = new Date()) {
     return date.toISOString().replace(/\.\d{3}Z$/, "Z").replace(/[:]/g, "-");
 }

package/dist/runtime/validateResult.js

@@ -1,3 +1,4 @@
+/** Validates a parsed phase result against its JSON Schema using Ajv. */
 import { Ajv2020 } from "ajv/dist/2020.js";
 export function validateAgainstSchema(schema, value) {
     const ajv = new Ajv2020({ allErrors: true });

package/dist/runtime/workItems.js

@@ -1,3 +1,4 @@
+/** Work items: lists GitHub issues via `gh`, normalizes them to candidates, and resolves the selected queue. */
 import { execa } from "execa";
 export async function listGitHubIssues(input) {
     const result = await execa("gh", [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {