@nyxa/nyx-agent 0.5.0 → 0.6.1

package/README.md

@@ -7,7 +7,8 @@ GitHub issue at a time, each phase with fresh context.
 
 For every run NyxAgent:
 
-1. **Selects** open GitHub issues to work on (read-only).
+1. **Selects** open GitHub issues to work on (read-only), then asks the user to
+   confirm the proposed checklist.
 2. For each selected issue, in an isolated git **worktree**:
    - **implements** it (the agent — the only customizable prompt),
    - optionally **reviews** and **revises** it (bounded loop),
@@ -27,7 +28,8 @@ is editable.
 
 ```bash
 nyxagent init                 # create .nyxagent/config.json (interactive)
-nyxagent run                  # run the pipeline
+nyxagent run                  # run the pipeline, confirming selected work items
+nyxagent run --yes            # accept the agent selection without prompting
 nyxagent run --harness claude # override the configured harness for one run
 nyxagent update               # self-update to the latest published version
 ```
@@ -42,6 +44,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,10 +53,16 @@ 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.
 - The `gh` CLI authenticated for the configured repository.
 - The selected harness CLI (`codex` or `claude`) on `PATH`.
+- An interactive terminal for `nyxagent run`, unless `--yes` is used.

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")
@@ -31,6 +33,7 @@ program
     .description("Run the NyxAgent pipeline")
     .option("--config <path>", "config path (default: .nyxagent/config.json)")
     .option("--harness <name>", "override the configured harness: codex or claude")
+    .option("-y, --yes", "accept the agent-selected work items without prompting")
     .action(async (options) => {
     await runCommand(options);
 });

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";
@@ -7,7 +8,8 @@ export async function runCommand(options, projectRoot = process.cwd()) {
         configPath: options.config
             ? path.resolve(projectRoot, options.config)
             : undefined,
-        harness: normalizeHarness(options.harness)
+        harness: normalizeHarness(options.harness),
+        autoAcceptSelection: options.yes ?? false
     });
 }
 function normalizeHarness(value) {

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

@@ -9,17 +9,18 @@ import { buildContextBlock, buildPhasePrompt, EXECUTION_PROMPT, GLOBAL_REVIEW_PR
 import { runAgentPhase } from "./runPhase.js";
 import { GLOBAL_REVIEW_SCHEMA, REVIEW_SCHEMA, SELECTION_SCHEMA } from "./schemas.js";
 import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff } from "./scm.js";
+import { confirmWorkItemSelection } from "./selectionConfirmation.js";
 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,
         runPhase: runAgentPhase,
         pushBranch,
-        createPullRequest
+        createPullRequest,
+        confirmSelection: confirmWorkItemSelection
     };
 }
 /**
@@ -56,7 +57,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         console.log("No open work items available. Nothing to do.");
         return;
     }
-    const selected = await runSelection({
+    const proposed = await runSelection({
         projectRoot,
         runDir,
         harness,
@@ -64,10 +65,20 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         candidates,
         runPhase: deps.runPhase
     });
-    if (selected.length === 0) {
+    if (proposed.length === 0) {
         console.log("Selection chose no work items. Nothing to do.");
         return;
     }
+    const selected = await deps.confirmSelection({
+        candidates,
+        proposed,
+        maxItems: config.max_iterations,
+        autoAccept: input.autoAcceptSelection ?? false
+    });
+    if (selected.length === 0) {
+        console.log("No work items selected. Nothing to do.");
+        return;
+    }
     const planned = selected.slice(0, config.max_iterations);
     console.log(`Selected ${planned.length} work item(s):`);
     for (const item of planned) {
@@ -106,6 +117,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                     git,
                     harness,
                     config,
+                    maxAttempts: config.review_max_attempts,
                     runPhase: deps.runPhase
                 });
             }
@@ -132,6 +144,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                 git,
                 harness,
                 config,
+                maxAttempts: config.review_max_attempts,
                 runPhase: deps.runPhase
             });
             if (corrections) {
@@ -155,6 +168,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,9 +190,54 @@ 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) {
@@ -235,7 +308,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 +336,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 +362,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 +393,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 +466,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/selectionConfirmation.js

@@ -0,0 +1,85 @@
+import { checkbox, Separator } from "@inquirer/prompts";
+export async function confirmWorkItemSelection(input) {
+    if (input.autoAccept) {
+        return input.proposed;
+    }
+    const isInteractive = input.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!isInteractive) {
+        throw new Error('Interactive work item selection requires a TTY. Re-run with "nyxagent run --yes" to accept the agent selection.');
+    }
+    const selectedKeys = await checkbox({
+        message: `Select work items to run (max ${input.maxItems})`,
+        choices: buildSelectionChoiceItems(input).map(toInquirerChoice),
+        pageSize: Math.min(Math.max(input.candidates.length, 7), 20),
+        required: false,
+        validate: (selected) => selected.length <= input.maxItems ||
+            `Select at most ${input.maxItems} work item(s).`,
+        shortcuts: {
+            all: null,
+            invert: null
+        }
+    });
+    const selected = new Set(selectedKeys);
+    return input.candidates.filter((candidate) => selected.has(candidate.key));
+}
+export function buildSelectionChoiceItems(input) {
+    const proposedKeys = new Set(input.proposed.map((item) => item.key));
+    const items = [];
+    let currentGroup;
+    for (const candidate of input.candidates) {
+        const group = detectPlanGroup(candidate);
+        if (group && group !== currentGroup) {
+            items.push({ type: "separator", label: group });
+        }
+        currentGroup = group;
+        const proposed = proposedKeys.has(candidate.key);
+        items.push({
+            type: "choice",
+            value: candidate.key,
+            name: `#${candidate.number} ${candidate.title}${proposed ? " (agent)" : ""}`,
+            checked: proposed
+        });
+    }
+    return items;
+}
+function toInquirerChoice(item) {
+    if (item.type === "separator") {
+        return new Separator(item.label);
+    }
+    return {
+        value: item.value,
+        name: item.name,
+        checked: item.checked
+    };
+}
+function detectPlanGroup(candidate) {
+    for (const label of candidate.labels ?? []) {
+        const group = parseGroupLabel(label);
+        if (group) {
+            return group;
+        }
+    }
+    return parseBracketedTitleGroup(candidate.title);
+}
+function parseGroupLabel(label) {
+    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(label.trim());
+    if (!match) {
+        return undefined;
+    }
+    return formatGroupLabel(match[1], match[2]);
+}
+function parseBracketedTitleGroup(title) {
+    const match = /^\[(plan|prd)\s*[:/=-]\s*([^\]]+)\]/i.exec(title.trim());
+    if (!match) {
+        return undefined;
+    }
+    return formatGroupLabel(match[1], match[2]);
+}
+function formatGroupLabel(kind, rawName) {
+    const name = rawName.trim();
+    if (!name) {
+        return undefined;
+    }
+    const prefix = kind.toLowerCase() === "prd" ? "PRD" : "Plan";
+    return `${prefix}: ${name}`;
+}

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.1",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {