@nyxa/nyx-agent 0.3.4 → 0.4.0

package/dist/runtime/buildPrompt.js

@@ -13,6 +13,10 @@ async function buildRuntimeContract(input) {
     const schemaText = input.phase.output_schema
         ? await readFile(resolveNyxPath(input.projectRoot, input.phase.output_schema, `output_schema for phase "${input.phase.id}"`), "utf8")
         : undefined;
+    const workdir = typeof input.context.workdir === "string"
+        ? input.context.workdir
+        : input.projectRoot;
+    const git = input.context.git;
     const lines = [
         "# NyxAgent Runtime Contract",
         "",
@@ -20,57 +24,15 @@ async function buildRuntimeContract(input) {
         "Follow the phase prompt, but obey this runtime contract first.",
         "",
         `Project root: ${input.projectRoot}`,
-        `Run dir: ${input.runDir}`,
-        `Iteration dir: ${input.iterationDir}`,
-        `Phase dir: ${input.phaseDir}`,
-        `State file: ${input.stateFile}`,
-        `Phase id: ${input.phase.id}`,
-        "",
-        "Current state:",
-        "```json",
-        JSON.stringify(input.context.state ?? {}, null, 2),
-        "```",
-        "",
-        "Work item configuration:",
-        "```json",
-        JSON.stringify(input.config.work_items ?? {}, null, 2),
-        "```",
-        "",
-        "Available work items:",
-        "```json",
-        JSON.stringify(input.context.available_work_items ?? [], null, 2),
-        "```",
-        "",
-        "Recommended work item queue:",
-        "```json",
-        JSON.stringify(input.context.recommended_work_item_queue ?? [], null, 2),
-        "```",
-        "",
-        "Selected work item queue:",
-        "```json",
-        JSON.stringify(input.context.selected_work_item_queue ?? [], null, 2),
-        "```",
-        "",
-        "Work item annotations:",
-        "```json",
-        JSON.stringify(input.context.work_item_annotations ?? [], null, 2),
-        "```",
-        "",
-        "Seen work item keys:",
-        "```json",
-        JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2),
-        "```",
-        "",
-        "Completed work item keys:",
-        "```json",
-        JSON.stringify(input.context.completed_work_item_keys ?? [], null, 2),
-        "```",
-        "",
-        "Last completed work item:",
-        "```json",
-        JSON.stringify(input.context.last_completed_work_item ?? null, null, 2),
-        "```"
+        `Working directory: ${workdir}`
     ];
+    if (workdir !== input.projectRoot) {
+        lines.push("Run all commands and edit files from the working directory above (an", "isolated git worktree). The project root only holds NyxAgent run artifacts.");
+    }
+    if (git?.branch) {
+        lines.push(`Git branch: ${git.branch} (base ${git.base ?? "unknown"})`);
+    }
+    lines.push(`Run dir: ${input.runDir}`, `Iteration dir: ${input.iterationDir}`, `Phase dir: ${input.phaseDir}`, `State file: ${input.stateFile}`, `Phase id: ${input.phase.id}`, "", "Current state:", "```json", JSON.stringify(input.context.state ?? {}, null, 2), "```", "", "Work item configuration:", "```json", JSON.stringify(input.config.work_items ?? {}, null, 2), "```", "", "Available work items:", "```json", JSON.stringify(input.context.available_work_items ?? [], null, 2), "```", "", "Recommended work item queue:", "```json", JSON.stringify(input.context.recommended_work_item_queue ?? [], null, 2), "```", "", "Selected work item queue:", "```json", JSON.stringify(input.context.selected_work_item_queue ?? [], null, 2), "```", "", "Work item annotations:", "```json", JSON.stringify(input.context.work_item_annotations ?? [], null, 2), "```", "", "Seen work item keys:", "```json", JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2), "```", "", "Completed work item keys:", "```json", JSON.stringify(input.context.completed_work_item_keys ?? [], null, 2), "```", "", "Last completed work item:", "```json", JSON.stringify(input.context.last_completed_work_item ?? null, null, 2), "```");
     if (input.phase.transitions) {
         lines.push("", "Configured outcome transitions:", "```json", JSON.stringify(input.phase.transitions, null, 2), "```");
     }

package/dist/runtime/gitLifecycle.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { rm } from "node:fs/promises";
+import { execa } from "execa";
+import { renderTemplate } from "./renderTemplate.js";
+/**
+ * Set up the run-scoped git context (one branch per run = one PRD = one PR).
+ *
+ * The engine only performs generic git plumbing (branch + worktree). All
+ * GitHub semantics (pushing, opening the PR, closing issues) stay in the
+ * phase prompts, keeping the engine agnostic.
+ *
+ * Returns `undefined` when git management is disabled (`mode = "off"`), in
+ * which case phases run in `projectRoot` exactly as before.
+ */
+export async function setUpGitContext(input) {
+    const mode = input.git.mode;
+    if (mode === "off") {
+        return undefined;
+    }
+    await assertGitRepository(input.projectRoot);
+    const branch = sanitizeBranch(renderTemplate(input.git.branch_template, { run_id: input.runId }));
+    if (!branch) {
+        throw new Error(`[git].branch_template "${input.git.branch_template}" produced an empty branch name`);
+    }
+    const base = input.git.base ?? (await currentRef(input.projectRoot));
+    const branchExists = await refExists(input.projectRoot, branch);
+    if (mode === "branch") {
+        const args = branchExists
+            ? ["checkout", branch]
+            : ["checkout", "-b", branch, base];
+        await runGit(input.projectRoot, args, "create branch");
+        return { mode, branch, base, worktree: input.projectRoot };
+    }
+    // mode === "worktree"
+    const worktree = path.resolve(input.projectRoot, input.git.worktree_dir, input.runId);
+    const args = branchExists
+        ? ["worktree", "add", worktree, branch]
+        : ["worktree", "add", worktree, "-b", branch, base];
+    await runGit(input.projectRoot, args, "create worktree");
+    return { mode, branch, base, worktree };
+}
+/**
+ * Tear down a run-scoped git context. The branch is always kept (it holds the
+ * committed work and any pull request); only the worktree working directory is
+ * removed, according to the cleanup policy.
+ */
+export async function tearDownGitContext(input) {
+    if (input.context.mode !== "worktree") {
+        return;
+    }
+    const shouldRemove = input.cleanup === "always" ||
+        (input.cleanup === "on_success" && input.success);
+    if (!shouldRemove) {
+        return;
+    }
+    const removal = await execa("git", ["worktree", "remove", input.context.worktree, "--force"], { cwd: input.projectRoot, reject: false });
+    if (removal.exitCode !== 0) {
+        // Fall back to pruning the directory and the worktree registry so a failed
+        // run never leaves the next run unable to reuse the path.
+        await rm(input.context.worktree, { recursive: true, force: true });
+        await execa("git", ["worktree", "prune"], {
+            cwd: input.projectRoot,
+            reject: false
+        });
+    }
+}
+export function sanitizeBranch(name) {
+    return name
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/[~^:?*[\]\\]/g, "-")
+        .replace(/\.{2,}/g, ".")
+        .replace(/\/{2,}/g, "/")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-/.]+/, "")
+        .replace(/[-/.]+$/, "");
+}
+async function assertGitRepository(cwd) {
+    const result = await execa("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd,
+        reject: false
+    });
+    if (result.exitCode !== 0 || result.stdout.trim() !== "true") {
+        throw new Error(`[git].mode is enabled but ${cwd} is not a git repository. Run "git init" or set [git].mode = "off".`);
+    }
+}
+async function currentRef(cwd) {
+    const named = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd,
+        reject: false
+    });
+    const name = named.stdout.trim();
+    if (named.exitCode === 0 && name && name !== "HEAD") {
+        return name;
+    }
+    const sha = await execa("git", ["rev-parse", "HEAD"], { cwd, reject: false });
+    return sha.stdout.trim();
+}
+async function refExists(cwd, ref) {
+    const result = await execa("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${ref}`], { cwd, reject: false });
+    return result.exitCode === 0;
+}
+async function runGit(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(`Failed to ${label} with git: ${detail}`);
+    }
+}

package/dist/runtime/runPhase.js

@@ -29,7 +29,7 @@ export async function runPhase(input) {
         context,
         config: input.config,
         phase: input.phase,
-        projectRoot: input.projectRoot
+        workdir: input.workdir ?? input.projectRoot
     });
     if (attempt.exitCode !== 0) {
         await writeAttemptMeta(attempt, {
@@ -93,7 +93,9 @@ function buildContext(input) {
         phase_results: input.state.phase_results ?? {},
         state: input.state,
         model,
-        harness
+        harness,
+        workdir: input.workdir ?? input.projectRoot,
+        git: input.git ?? {}
     };
 }
 async function runHarnessAttempt(input) {
@@ -107,13 +109,13 @@ async function runHarnessAttempt(input) {
     const args = harness.args.map((arg) => renderTemplate(arg, input.context));
     const startedAt = new Date().toISOString();
     const started = Date.now();
-    const gitBefore = await getGitSnapshot(input.projectRoot);
+    const gitBefore = await getGitSnapshot(input.workdir);
     let stdout = "";
     let stderr = "";
     let exitCode = 0;
     try {
         const result = await execa(command, args, {
-            cwd: input.projectRoot,
+            cwd: input.workdir,
             input: input.prompt,
             reject: false
         });
@@ -127,7 +129,7 @@ async function runHarnessAttempt(input) {
     }
     const endedAt = new Date().toISOString();
     const durationMs = Date.now() - started;
-    const gitAfter = await getGitSnapshot(input.projectRoot);
+    const gitAfter = await getGitSnapshot(input.workdir);
     await writeText(path.join(input.attemptDir, "stdout.log"), stdout);
     await writeText(path.join(input.attemptDir, "stderr.log"), stderr);
     const attempt = {
@@ -250,7 +252,7 @@ async function repairStructuredResult(input) {
             context: repairContext,
             config: input.input.config,
             phase: input.input.phase,
-            projectRoot: input.input.projectRoot
+            workdir: input.input.workdir ?? input.input.projectRoot
         });
         if (repairAttempt.exitCode !== 0) {
             lastError = `Repair harness exited with code ${repairAttempt.exitCode}`;

package/dist/runtime/runWorkflow.js

@@ -4,6 +4,7 @@ import pc from "picocolors";
 import { loadConfig } from "../config/loadConfig.js";
 import { ensureDir, writeJson } from "./files.js";
 import { getGitSnapshot } from "./git.js";
+import { setUpGitContext, tearDownGitContext } from "./gitLifecycle.js";
 import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "./ledger.js";
 import { getNyxDir, relativeToProject } from "./paths.js";
 import { runPhase } from "./runPhase.js";
@@ -109,6 +110,53 @@ export async function runWorkflow(options) {
         console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
         return;
     }
+    let gitContext;
+    if (config.git && config.git.mode !== "off") {
+        gitContext = await setUpGitContext({ projectRoot, git: config.git, runId });
+    }
+    if (gitContext) {
+        console.log(`Git: ${gitContext.mode} on "${gitContext.branch}" (base "${gitContext.base}")`);
+        if (gitContext.mode === "worktree") {
+            console.log(`Worktree: ${relativeToProject(projectRoot, gitContext.worktree)}`);
+        }
+        console.log("");
+    }
+    const cleanup = config.git?.cleanup ?? "on_success";
+    let runSucceeded = false;
+    try {
+        runSucceeded = await runSelectedQueue({
+            projectRoot,
+            nyxDir,
+            runDir,
+            config,
+            phasesById,
+            selection,
+            selectedWorkItems,
+            runState,
+            ledger,
+            workdir: gitContext?.worktree ?? projectRoot,
+            gitContext
+        });
+    }
+    finally {
+        if (gitContext) {
+            await tearDownGitContext({
+                projectRoot,
+                context: gitContext,
+                cleanup,
+                success: runSucceeded
+            });
+        }
+    }
+}
+/**
+ * Run the confirmed work item queue and, when configured, the run-scoped final
+ * phase (e.g. opening the PRD pull request). Returns true when the whole run
+ * completed normally, false when it stopped early (stop_run).
+ */
+async function runSelectedQueue(input) {
+    const { projectRoot, nyxDir, runDir, config, phasesById, selection, selectedWorkItems, runState, workdir, gitContext } = input;
+    let ledger = input.ledger;
     for (let queueIndex = 0; queueIndex < selectedWorkItems.length; queueIndex += 1) {
         const iterationNumber = queueIndex + 1;
         const workItem = selectedWorkItems[queueIndex];
@@ -148,7 +196,9 @@ export async function runWorkflow(options) {
                 iterationState,
                 runState,
                 iterationNumber,
-                maxIterations: selectedWorkItems.length
+                maxIterations: selectedWorkItems.length,
+                workdir,
+                git: gitContext
             });
             if (!phaseResult.ok) {
                 throw new Error(phaseResult.error);
@@ -164,7 +214,7 @@ export async function runWorkflow(options) {
                 console.log("");
                 console.log(`Done: ${runState.status}`);
                 console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
-                return;
+                return false;
             }
             if (nextTarget === "stop_iteration" || nextTarget === "next_iteration") {
                 iterationState.status = "completed";
@@ -186,6 +236,23 @@ export async function runWorkflow(options) {
             currentPhaseId = nextTarget;
         }
     }
+    if (config.workflow.final_phase) {
+        const finalized = await runFinalPhase({
+            projectRoot,
+            runDir,
+            config,
+            phasesById,
+            runState,
+            selectedWorkItems,
+            ledger,
+            workdir,
+            gitContext,
+            workItemAnnotations: selection.workItemAnnotations
+        });
+        if (!finalized) {
+            return false;
+        }
+    }
     runState.status =
         selectedWorkItems.length >= config.workflow.max_iterations
             ? "completed_max_iterations"
@@ -194,6 +261,91 @@ export async function runWorkflow(options) {
     console.log("");
     console.log(`Done: ${runState.status}`);
     console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
+    return true;
+}
+/**
+ * Execute the run-scoped finalization flow after all iterations complete. This
+ * is a self-contained phase graph (symmetric to the iteration flow started by
+ * `entry_phase`): it begins at `workflow.final_phase` and follows each phase's
+ * `next`/`transitions` until it reaches a leaf phase (success) or `stop_run`
+ * (abort). This is where, for example, a review -> revision -> pull request
+ * chain runs. The engine only provides the branch/worktree context and
+ * run-level state; the GitHub/PR semantics live in the phase prompts, keeping
+ * the engine agnostic. A single leaf `final_phase` simply runs once.
+ *
+ * Returns true when finalization completed normally, false when a phase routed
+ * to `stop_run`.
+ */
+async function runFinalPhase(input) {
+    const finalPhaseId = input.config.workflow.final_phase;
+    if (!finalPhaseId) {
+        return true;
+    }
+    const finalizationDir = path.join(input.runDir, "finalization");
+    await ensureDir(finalizationDir);
+    const finalizationState = {
+        iteration: 0,
+        status: "running",
+        available_work_items: input.selectedWorkItems,
+        recommended_work_item_queue: input.selectedWorkItems,
+        selected_work_item_queue: input.selectedWorkItems,
+        work_item_annotations: input.workItemAnnotations,
+        seen_work_item_keys: [...input.runState.seen_work_item_keys],
+        completed_work_item_keys: [...input.ledger.completed_work_item_keys],
+        last_completed_work_item: input.ledger.last_completed_work_item,
+        phase_results: {},
+        phase_visit_counts: {}
+    };
+    const finalizationStateFile = path.join(finalizationDir, "state.json");
+    await writeJson(finalizationStateFile, finalizationState);
+    let currentPhaseId = finalPhaseId;
+    let lastResult;
+    while (currentPhaseId) {
+        const phase = input.phasesById.get(currentPhaseId);
+        if (!phase) {
+            throw new Error(`Unknown final phase "${currentPhaseId}"`);
+        }
+        const phaseResult = await runWorkflowPhase({
+            projectRoot: input.projectRoot,
+            runDir: input.runDir,
+            iterationDir: finalizationDir,
+            iterationStateFile: finalizationStateFile,
+            config: input.config,
+            phase,
+            iterationState: finalizationState,
+            runState: input.runState,
+            iterationNumber: "final",
+            maxIterations: input.selectedWorkItems.length,
+            workdir: input.workdir,
+            git: input.gitContext
+        });
+        if (!phaseResult.ok) {
+            throw new Error(phaseResult.error);
+        }
+        if (phaseResult.result !== undefined) {
+            lastResult = phaseResult.result;
+        }
+        const nextTarget = resolveNextTarget(phase, phaseResult.outcome);
+        if (nextTarget === "stop_run") {
+            finalizationState.status = "stopped";
+            input.runState.status = "stopped";
+            input.runState.final_result = phaseResult.result ?? { status: "stopped" };
+            await writeJson(finalizationStateFile, finalizationState);
+            await writeJson(path.join(input.runDir, "state.json"), input.runState);
+            console.log("");
+            console.log(`Done: ${input.runState.status}`);
+            console.log(`Run dir: ${relativeToProject(input.projectRoot, input.runDir)}`);
+            return false;
+        }
+        if (nextTarget === "next_iteration" || nextTarget === "stop_iteration") {
+            throw new Error(`Final phase "${phase.id}" routed to iteration-only target "${nextTarget}"; finalization phases must end at a leaf phase (no next/transitions) or "stop_run"`);
+        }
+        currentPhaseId = nextTarget;
+    }
+    finalizationState.status = "completed";
+    input.runState.final_result = lastResult ?? { status: "ok" };
+    await writeJson(finalizationStateFile, finalizationState);
+    return true;
 }
 async function runSelectionPhase(input) {
     const selectionPhase = input.phasesById.get(input.config.workflow.entry_phase);
@@ -303,7 +455,9 @@ async function runWorkflowPhase(input) {
         stateFile: input.iterationStateFile,
         config: input.config,
         phase: input.phase,
-        state: input.iterationState
+        state: input.iterationState,
+        workdir: input.workdir,
+        git: input.git
     });
     if (!phaseResult.ok) {
         console.log(pc.red("failed"));