@nyxa/nyx-agent 0.4.1 → 0.6.0

package/dist/runtime/runPipeline.js

@@ -0,0 +1,479 @@
+import path from "node:path";
+import pc from "picocolors";
+import { loadConfig } from "../config/loadConfig.js";
+import { ensureDir, pathExists, readText } from "./files.js";
+import { deleteBranch, removeRunWorktree, setUpRunWorktree } from "./gitLifecycle.js";
+import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "./ledger.js";
+import { getNyxDir, relativeToProject } from "./paths.js";
+import { buildContextBlock, buildPhasePrompt, EXECUTION_PROMPT, GLOBAL_REVIEW_PROMPT, GLOBAL_REVISION_PROMPT, REVIEW_PROMPT, REVISION_PROMPT, SELECTION_PROMPT, truncateForPrompt } from "./prompts.js";
+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 { createRunId } from "./time.js";
+import { filterAvailable, listGitHubIssues, resolveSelectedQueue } from "./workItems.js";
+const MAX_CANDIDATES = 50;
+const EXCERPT_CHARS = 800;
+export function defaultPipelineDependencies() {
+    return {
+        listIssues: listGitHubIssues,
+        runPhase: runAgentPhase,
+        pushBranch,
+        createPullRequest
+    };
+}
+/**
+ * The fixed NyxAgent pipeline:
+ *
+ *   select -> for each item: implement -> [review/revise] -> commit
+ *          -> [global review/revise] -> open pull request
+ *
+ * Control flow lives here in code (not in config). The agent only implements,
+ * reviews, and revises; every git/gh side effect is performed by the engine.
+ */
+export async function runPipeline(input = {}, deps = defaultPipelineDependencies()) {
+    const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+    const nyxDir = getNyxDir(projectRoot);
+    const configPath = input.configPath ?? path.join(nyxDir, "config.json");
+    const config = await loadConfig(configPath);
+    const harness = input.harness ?? config.harness;
+    const runId = createRunId();
+    const runDir = path.join(nyxDir, "runs", runId);
+    await ensureDir(runDir);
+    console.log(pc.bold(`NyxAgent run ${runId}`));
+    console.log(`Harness: ${harness} · model: ${config.model} · review: ${config.review}`);
+    const ledger = await readWorkItemLedger(nyxDir);
+    // 1. Selection runs read-only in the main checkout, before any branch exists.
+    const candidates = filterAvailable({
+        candidates: await deps.listIssues({
+            repo: config.tracker.repo,
+            maxCandidates: MAX_CANDIDATES,
+            excerptChars: EXCERPT_CHARS
+        }),
+        completedKeys: ledger.completed_work_item_keys
+    });
+    if (candidates.length === 0) {
+        console.log("No open work items available. Nothing to do.");
+        return;
+    }
+    const selected = await runSelection({
+        projectRoot,
+        runDir,
+        harness,
+        config,
+        candidates,
+        runPhase: deps.runPhase
+    });
+    if (selected.length === 0) {
+        console.log("Selection chose no work items. 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) {
+        console.log(`  - ${item.title} (#${item.number})`);
+    }
+    // 2. One branch + worktree per run (created only now that there is work).
+    const git = await setUpRunWorktree({
+        projectRoot,
+        runId,
+        base: config.base_branch
+    });
+    console.log(`Branch ${git.branch} (base ${git.base})`);
+    let success = false;
+    let producedCommits = false;
+    let currentLedger = ledger;
+    const completed = [];
+    try {
+        const executionGuidance = await loadExecutionGuidance(nyxDir);
+        for (const [index, item] of planned.entries()) {
+            const iterationNumber = index + 1;
+            const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
+            console.log(pc.cyan(`\n[${iterationNumber}/${planned.length}] ${item.title} (#${item.number})`));
+            await runExecution({
+                iterationDir,
+                item,
+                guidance: executionGuidance,
+                git,
+                harness,
+                config,
+                runPhase: deps.runPhase
+            });
+            if (config.review === "each" || config.review === "both") {
+                await runReviewLoop({
+                    iterationDir,
+                    item,
+                    git,
+                    harness,
+                    config,
+                    maxAttempts: config.review_max_attempts,
+                    runPhase: deps.runPhase
+                });
+            }
+            const { committed } = await commitAll({
+                cwd: git.worktree,
+                message: buildCommitMessage(item)
+            });
+            if (committed) {
+                producedCommits = true;
+            }
+            else {
+                console.log(pc.yellow("  No changes to commit for this item."));
+            }
+            currentLedger = markWorkItemCompleted({
+                ledger: currentLedger,
+                workItem: item
+            });
+            await writeWorkItemLedger(nyxDir, currentLedger);
+            completed.push(item);
+        }
+        if (config.review === "all" || config.review === "both") {
+            const corrections = await runGlobalReviewLoop({
+                runDir,
+                git,
+                harness,
+                config,
+                maxAttempts: config.review_max_attempts,
+                runPhase: deps.runPhase
+            });
+            if (corrections) {
+                producedCommits = true;
+            }
+        }
+        if (!producedCommits || (await commitsAhead(git.worktree, git.base)) === 0) {
+            console.log("\nRun produced no commits; skipping pull request.");
+            success = true;
+            return;
+        }
+        await deps.pushBranch({ cwd: git.worktree, branch: git.branch });
+        const prUrl = await deps.createPullRequest({
+            cwd: git.worktree,
+            repo: config.tracker.repo,
+            base: git.base,
+            head: git.branch,
+            title: buildPrTitle(completed),
+            body: buildPrBody(completed)
+        });
+        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 });
+            if (!producedCommits) {
+                await deleteBranch({ projectRoot, branch: git.branch });
+            }
+        }
+    }
+}
+/**
+ * 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([
+        ["Repository", input.config.tracker.repo],
+        ["Max work items this run", input.config.max_iterations],
+        [
+            "Available candidates",
+            input.candidates.map((candidate) => ({
+                key: candidate.key,
+                number: candidate.number,
+                title: candidate.title,
+                labels: candidate.labels,
+                excerpt: candidate.excerpt
+            }))
+        ]
+    ]);
+    const result = await input.runPhase({
+        phaseId: "selection",
+        phaseDir: path.join(input.runDir, "selection"),
+        workdir: input.projectRoot,
+        harness: input.harness,
+        model: input.config.model,
+        reasoning: input.config.reasoning_effort,
+        capability: "readonly",
+        prompt: buildPhasePrompt({
+            guidance: SELECTION_PROMPT,
+            context,
+            schema: SELECTION_SCHEMA
+        }),
+        schema: SELECTION_SCHEMA
+    });
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+    const value = result.result;
+    if (value.outcome === "no_work") {
+        return [];
+    }
+    const resolved = resolveSelectedQueue({
+        keys: value.work_item_keys,
+        candidates: input.candidates
+    });
+    if (!resolved.ok) {
+        throw new Error(`Selection produced an invalid queue: ${resolved.error}`);
+    }
+    return resolved.queue;
+}
+async function runExecution(input) {
+    const context = buildContextBlock([
+        ["Work item", workItemSummary(input.item)],
+        ["Issue description", input.item.excerpt ?? "(no description provided)"],
+        ["Working directory", input.git.worktree],
+        ["Branch", `${input.git.branch} (base ${input.git.base})`]
+    ]);
+    const result = await input.runPhase({
+        phaseId: "execution",
+        phaseDir: path.join(input.iterationDir, "execution"),
+        workdir: input.git.worktree,
+        harness: input.harness,
+        model: input.config.model,
+        reasoning: input.config.reasoning_effort,
+        capability: "write",
+        prompt: buildPhasePrompt({ guidance: input.guidance, context })
+    });
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+}
+async function runReviewLoop(input) {
+    for (let attempt = 1; attempt <= input.maxAttempts; attempt += 1) {
+        const diff = await stageAllAndDiff(input.git.worktree);
+        const reviewResult = await input.runPhase({
+            phaseId: "review",
+            phaseDir: path.join(input.iterationDir, `review-${attempt}`),
+            workdir: input.git.worktree,
+            harness: input.harness,
+            model: input.config.model,
+            reasoning: input.config.reasoning_effort,
+            capability: "readonly",
+            prompt: buildPhasePrompt({
+                guidance: REVIEW_PROMPT,
+                context: buildContextBlock([
+                    ["Work item", workItemSummary(input.item)],
+                    ["Uncommitted changes (diff)", truncateForPrompt(diff || "(no changes)")]
+                ]),
+                schema: REVIEW_SCHEMA
+            }),
+            schema: REVIEW_SCHEMA
+        });
+        if (!reviewResult.ok) {
+            throw new Error(reviewResult.error);
+        }
+        const review = reviewResult.result;
+        console.log(`  review: ${review.outcome}`);
+        if (review.outcome === "approved") {
+            return;
+        }
+        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",
+            phaseDir: path.join(input.iterationDir, `revision-${attempt}`),
+            workdir: input.git.worktree,
+            harness: input.harness,
+            model: input.config.model,
+            reasoning: input.config.reasoning_effort,
+            capability: "write",
+            prompt: buildPhasePrompt({
+                guidance: REVISION_PROMPT,
+                context: buildContextBlock([
+                    ["Work item", workItemSummary(input.item)],
+                    ["Required changes", review.required_changes ?? []]
+                ])
+            })
+        });
+        if (!revision.ok) {
+            throw new Error(revision.error);
+        }
+    }
+}
+async function runGlobalReviewLoop(input) {
+    let committedCorrections = false;
+    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",
+            phaseDir: path.join(input.runDir, "final", `global-review-${attempt}`),
+            workdir: input.git.worktree,
+            harness: input.harness,
+            model: input.config.model,
+            reasoning: input.config.reasoning_effort,
+            capability: "readonly",
+            prompt: buildPhasePrompt({
+                guidance: GLOBAL_REVIEW_PROMPT,
+                context: buildContextBlock([
+                    ["Run branch", `${input.git.branch} (base ${input.git.base})`],
+                    [
+                        "Combined run diff (base...HEAD)",
+                        truncateForPrompt(diff || "(no changes)")
+                    ]
+                ]),
+                schema: GLOBAL_REVIEW_SCHEMA
+            }),
+            schema: GLOBAL_REVIEW_SCHEMA
+        });
+        if (!reviewResult.ok) {
+            throw new Error(reviewResult.error);
+        }
+        const review = reviewResult.result;
+        console.log(`global review: ${review.outcome}`);
+        if (review.outcome === "approved") {
+            return committedCorrections;
+        }
+        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",
+            phaseDir: path.join(input.runDir, "final", `global-revision-${attempt}`),
+            workdir: input.git.worktree,
+            harness: input.harness,
+            model: input.config.model,
+            reasoning: input.config.reasoning_effort,
+            capability: "write",
+            prompt: buildPhasePrompt({
+                guidance: GLOBAL_REVISION_PROMPT,
+                context: buildContextBlock([
+                    ["Required changes", review.required_changes ?? []]
+                ])
+            })
+        });
+        if (!revision.ok) {
+            throw new Error(revision.error);
+        }
+        const { committed } = await commitAll({
+            cwd: input.git.worktree,
+            message: "Apply global review corrections"
+        });
+        if (committed) {
+            committedCorrections = true;
+        }
+    }
+    return committedCorrections;
+}
+async function loadExecutionGuidance(nyxDir) {
+    const override = path.join(nyxDir, "prompts", "execution.md");
+    if (await pathExists(override)) {
+        const text = (await readText(override)).trim();
+        if (text) {
+            return text;
+        }
+    }
+    return EXECUTION_PROMPT;
+}
+function workItemSummary(item) {
+    return {
+        key: item.key,
+        number: item.number,
+        title: item.title,
+        locator: item.source.locator,
+        url: item.url,
+        labels: item.labels
+    };
+}
+function buildCommitMessage(item) {
+    return `${item.title}\n\nWork item: ${item.source.locator}`;
+}
+function buildPrTitle(items) {
+    if (items.length === 1) {
+        return items[0].title;
+    }
+    return `NyxAgent: ${items.length} work items`;
+}
+function buildPrBody(items) {
+    const list = items.map((item) => `- ${item.title} (#${item.number})`).join("\n");
+    const closes = items.map((item) => `Closes #${item.number}`).join("\n");
+    return [
+        "Automated changes by NyxAgent.",
+        "",
+        "## Work items",
+        "",
+        list,
+        "",
+        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/schemas.js

@@ -0,0 +1,52 @@
+/**
+ * JSON Schemas for the structured results NyxAgent requires from review-style
+ * phases. They are embedded (not files on disk) so they cannot drift from the
+ * engine and are shown verbatim to the agent in the phase prompt.
+ */
+export const SELECTION_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["outcome"],
+    properties: {
+        outcome: { type: "string", enum: ["selected", "no_work"] },
+        work_item_keys: {
+            type: "array",
+            items: { type: "string" },
+            description: "Ordered keys of the chosen candidates (prerequisites first)."
+        }
+    },
+    allOf: [
+        {
+            if: { properties: { outcome: { const: "selected" } } },
+            then: { required: ["work_item_keys"] }
+        }
+    ],
+    additionalProperties: true
+};
+const reviewSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["outcome", "summary"],
+    properties: {
+        outcome: { type: "string", enum: ["approved", "changes_requested"] },
+        summary: {
+            type: "string",
+            minLength: 1,
+            description: "A brief assessment of the work."
+        },
+        required_changes: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Specific, actionable changes (required when outcome is "changes_requested").'
+        }
+    },
+    allOf: [
+        {
+            if: { properties: { outcome: { const: "changes_requested" } } },
+            then: { required: ["required_changes"] }
+        }
+    ],
+    additionalProperties: true
+};
+export const REVIEW_SCHEMA = reviewSchema;
+export const GLOBAL_REVIEW_SCHEMA = reviewSchema;

package/dist/runtime/scm.js

@@ -0,0 +1,80 @@
+import { execa } from "execa";
+/**
+ * Deterministic source-control side effects. NyxAgent — not the agent — performs
+ * every commit, push, and pull request, so closing the loop never depends on an
+ * LLM remembering to. All commands run with the process's own permissions (no
+ * sandbox), from the run worktree.
+ */
+async function git(cwd, args, label) {
+    const result = await execa("git", args, { cwd, reject: false });
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout || "unknown error").trim();
+        throw new Error(`git ${label} failed: ${detail}`);
+    }
+    return { stdout: result.stdout };
+}
+/** Stage everything and return the staged diff (captures new files too). */
+export async function stageAllAndDiff(cwd) {
+    await git(cwd, ["add", "-A"], "add");
+    const diff = await git(cwd, ["diff", "--cached"], "diff --cached");
+    return diff.stdout;
+}
+/** The committed diff for the run: everything on HEAD that is not on `base`. */
+export async function rangeDiff(cwd, base) {
+    const diff = await git(cwd, ["diff", `${base}..HEAD`], "diff range");
+    return diff.stdout;
+}
+/**
+ * Stage all changes and commit them. Returns whether a commit was actually made
+ * (false when there was nothing to commit).
+ */
+export async function commitAll(input) {
+    await git(input.cwd, ["add", "-A"], "add");
+    const staged = await execa("git", ["diff", "--cached", "--quiet"], { cwd: input.cwd, reject: false });
+    // exit 0 = no staged changes, exit 1 = staged changes present.
+    if (staged.exitCode === 0) {
+        return { committed: false };
+    }
+    // Split a "subject\n\nbody" message into conventional subject + body args.
+    const [subject, ...rest] = input.message.split("\n\n");
+    const commitArgs = ["commit", "-m", subject];
+    const body = rest.join("\n\n").trim();
+    if (body) {
+        commitArgs.push("-m", body);
+    }
+    await git(input.cwd, commitArgs, "commit");
+    return { committed: true };
+}
+/** Number of commits on HEAD ahead of `base`. */
+export async function commitsAhead(cwd, base) {
+    const result = await git(cwd, ["rev-list", "--count", `${base}..HEAD`], "rev-list");
+    return Number.parseInt(result.stdout.trim(), 10) || 0;
+}
+export async function pushBranch(input) {
+    await git(input.cwd, ["push", "-u", "origin", input.branch], "push");
+}
+export async function createPullRequest(input) {
+    const args = [
+        "pr",
+        "create",
+        "--repo",
+        input.repo,
+        "--base",
+        input.base,
+        "--head",
+        input.head,
+        "--title",
+        input.title,
+        "--body",
+        input.body
+    ];
+    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}`);
+    }
+    return result.stdout.trim();
+}

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,7 +1,6 @@
-import { readFile } from "node:fs/promises";
+/** Validates a parsed phase result against its JSON Schema using Ajv. */
 import { Ajv2020 } from "ajv/dist/2020.js";
-export async function validateAgainstSchema(schemaPath, value) {
-    const schema = JSON.parse(await readFile(schemaPath, "utf8"));
+export function validateAgainstSchema(schema, value) {
     const ajv = new Ajv2020({ allErrors: true });
     const validate = ajv.compile(schema);
     const valid = validate(value);