@nyxa/nyx-agent 0.3.4 → 0.4.0

package/README.md

@@ -9,6 +9,7 @@ Current commands:
 nyxagent init
 nyxagent init --missing
 nyxagent run
+nyxagent update
 ```
 
 See [docs/nyxagent-v0-spec.md](docs/nyxagent-v0-spec.md) for the v0 design.

package/dist/cli.js

@@ -4,6 +4,7 @@ import { createRequire } from "node:module";
 import pc from "picocolors";
 import { initCommand } from "./commands/init.js";
 import { runCommand } from "./commands/run.js";
+import { updateCommand } from "./commands/update.js";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 const program = new Command();
@@ -17,11 +18,17 @@ program
     .option("--missing", "only add missing template files")
     .option("--harness <preset>", "harness preset: codex, claude, or custom")
     .option("--model <name>", "model name")
-    .option("--reasoning-level <level>", "harness-neutral reasoning level")
+    .option("--reasoning-level <level>", "default harness-neutral reasoning level")
     .option("--max-iterations <count>", "maximum work items per run")
     .option("--work-items-source <source>", "work item source template: local or github")
     .option("--work-items-path <path>", "local markdown work item directory")
     .option("--work-items-repository <owner/repo>", "GitHub work item repository")
+    .option("--implementation-skill <name>", "implementation skill to reference in the execution prompt")
+    .option("--review", "include a review phase (alias for --review-mode each)")
+    .option("--no-review", "skip the review phase (alias for --review-mode none)")
+    .option("--review-mode <mode>", "review strategy: each, all, both, or none")
+    .option("--pull-request", "close the PRD with a pull request (GitHub work items)")
+    .option("--no-pull-request", "skip the pull request finalization phase")
     .action(async (options) => {
     await initCommand(options);
 });
@@ -32,6 +39,16 @@ program
     .action(async (options) => {
     await runCommand(options);
 });
+program
+    .command("update")
+    .description("Update nyxagent to the latest published version")
+    .argument("[version]", "version or dist-tag to install (default: latest)")
+    .option("--check", "only check for a newer version, do not install")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--package-manager <pm>", "force a package manager: npm, pnpm, yarn, or bun")
+    .action(async (version, options) => {
+    await updateCommand(version, options);
+});
 await program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(pc.red(`Error: ${message}`));

package/dist/commands/init.js

@@ -1,13 +1,17 @@
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { input, number as numberPrompt, select } from "@inquirer/prompts";
+import { confirm, input, number as numberPrompt, select } from "@inquirer/prompts";
 import pc from "picocolors";
 import { ensureDir, pathExists, readText, writeText } from "../runtime/files.js";
 import { getNyxDir, relativeToProject } from "../runtime/paths.js";
 const DEFAULT_OPENAI_MODEL = "gpt-5.5";
 const GITIGNORE_MARKER = "# NyxAgent runtime artifacts";
-const GITIGNORE_ENTRIES = [".nyxagent/runs/", ".nyxagent/state.json"];
+const GITIGNORE_ENTRIES = [
+    ".nyxagent/runs/",
+    ".nyxagent/state.json",
+    ".nyxagent/worktrees/"
+];
 export async function initCommand(options, projectRoot = process.cwd()) {
     const root = path.resolve(projectRoot);
     const nyxDir = getNyxDir(root);
@@ -27,6 +31,10 @@ export async function initCommand(options, projectRoot = process.cwd()) {
     if (resolved) {
         await writeText(configPath, buildConfigToml(resolved));
     }
+    if (resolved?.implementationSkill) {
+        const executionPromptPath = path.join(nyxDir, "prompts", "execution.md");
+        await writeText(executionPromptPath, buildSkillExecutionPrompt(resolved.implementationSkill));
+    }
     if (resolved?.workItemsSource === "local" && resolved.workItemsPath) {
         await ensureWorkItemsDirectory(root, resolved.workItemsPath);
     }
@@ -50,9 +58,11 @@ async function resolveInitOptions(options, root) {
         }));
     const reasoningLevel = options.reasoningLevel ??
         (await input({
-            message: "Reasoning level",
+            message: "Default reasoning level",
             default: "medium"
         }));
+    const implementationSkill = await resolveImplementationSkill(options);
+    const reviewMode = await resolveReviewMode(options);
     const parsedMaxIterations = options.maxIterations
         ? Number.parseInt(options.maxIterations, 10)
         : undefined;
@@ -92,6 +102,11 @@ async function resolveInitOptions(options, root) {
     if (workItemsSource === "github") {
         validateGitHubRepository(workItemsRepository);
     }
+    // GitHub PRDs are closed with a pull request by default (a dedicated branch +
+    // worktree). Opt out with --no-pull-request or by removing [git]/final_phase
+    // from the generated config. Pull requests are GitHub-specific, so local work
+    // item sources never get the finalization phase.
+    const pullRequest = workItemsSource === "github" ? options.pullRequest ?? true : false;
     if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
         throw new Error("max iterations must be a positive integer");
     }
@@ -102,9 +117,63 @@ async function resolveInitOptions(options, root) {
         maxIterations,
         workItemsSource,
         workItemsPath,
-        workItemsRepository
+        workItemsRepository,
+        implementationSkill,
+        reviewMode,
+        pullRequest
     };
 }
+async function resolveReviewMode(options) {
+    if (options.reviewMode !== undefined) {
+        return normalizeReviewMode(options.reviewMode);
+    }
+    // Backward compatibility with the boolean --review / --no-review flags.
+    if (options.review !== undefined) {
+        return options.review ? "each" : "none";
+    }
+    return select({
+        message: "Review strategy",
+        choices: [
+            {
+                name: "After each task (review + correction inside the loop)",
+                value: "each"
+            },
+            {
+                name: "After all tasks (global review + correction)",
+                value: "all"
+            },
+            {
+                name: "Both (per-task and a final global review)",
+                value: "both"
+            },
+            { name: "No review", value: "none" }
+        ],
+        default: "each"
+    });
+}
+function normalizeReviewMode(mode) {
+    if (mode === "each" || mode === "all" || mode === "both" || mode === "none") {
+        return mode;
+    }
+    throw new Error('review mode must be "each", "all", "both", or "none"');
+}
+async function resolveImplementationSkill(options) {
+    if (options.implementationSkill !== undefined) {
+        const provided = options.implementationSkill.trim();
+        return provided.length > 0 ? provided : undefined;
+    }
+    const useSkill = await confirm({
+        message: "Use an implementation skill?",
+        default: false
+    });
+    if (!useSkill) {
+        return undefined;
+    }
+    const skill = (await input({
+        message: "Skill name (as you invoke it, e.g. /tdd)"
+    })).trim();
+    return skill.length > 0 ? skill : undefined;
+}
 function normalizeWorkItemsSource(source) {
     if (source === "local" || source === "local-markdown") {
         return "local";
@@ -188,11 +257,71 @@ function getGitignoreAppendPrefix(current) {
 function normalizeGitignoreContent(value) {
     return `${value.replace(/\n*$/, "")}\n`;
 }
+function buildSkillExecutionPrompt(skill) {
+    return `Implement the selected work item using the ${skill} skill.
+
+Do not commit. Do not close or mark the work item done. Leave clear validation
+evidence in your final response.
+`;
+}
 function buildConfigToml(options) {
     const harness = buildHarnessToml(options.harness);
     const workItems = buildWorkItemsToml(options);
+    const perTaskReview = options.reviewMode === "each" || options.reviewMode === "both";
+    const globalReview = options.reviewMode === "all" || options.reviewMode === "both";
+    const executionNext = perTaskReview ? "review" : "closure";
+    const reviewPhases = perTaskReview
+        ? `
+[[phases]]
+id = "revision"
+prompt = "prompts/revision.md"
+next = "review"
+max_visits_per_iteration = 3
+
+[[phases]]
+id = "review"
+prompt = "prompts/review.md"
+output_schema = "schemas/review.schema.json"
+required_output = true
+max_visits_per_iteration = 3
+
+[phases.harness]
+args = ${formatTomlArray(buildHarnessArgs(options.harness, "readonly"))}
+
+[phases.transitions]
+approved = "closure"
+changes_requested = "revision"
+`
+        : "";
+    // The finalization terminal leaf the global review approves into: a pushed
+    // pull request for GitHub, otherwise a read-only finalize phase.
+    const finalizationTerminal = options.pullRequest
+        ? "pull_request"
+        : globalReview
+            ? "finalize"
+            : undefined;
+    // The entry of the finalization flow: the global review when enabled, else
+    // the pull request (when configured), else nothing.
+    const finalPhaseEntry = globalReview
+        ? "global_review"
+        : options.pullRequest
+            ? "pull_request"
+            : undefined;
+    const finalPhaseLine = finalPhaseEntry
+        ? `\nfinal_phase = "${finalPhaseEntry}"`
+        : "";
+    const gitSection = options.pullRequest ? `${buildGitToml()}\n\n` : "";
+    const pullRequestPhase = options.pullRequest
+        ? `\n${buildPullRequestPhaseToml(options.harness)}\n`
+        : "";
+    const globalReviewPhases = globalReview
+        ? `\n${buildGlobalReviewPhasesToml(options.harness, finalizationTerminal ?? "finalize")}\n`
+        : "";
+    const finalizePhase = globalReview && !options.pullRequest
+        ? `\n${buildFinalizePhaseToml(options.harness)}\n`
+        : "";
     return `[workflow]
-entry_phase = "selection"
+entry_phase = "selection"${finalPhaseLine}
 max_iterations = ${options.maxIterations}
 
 [model]
@@ -201,7 +330,7 @@ reasoning_level = "${escapeTomlString(options.reasoningLevel)}"
 
 ${harness}
 
-[repair]
+${gitSection}[repair]
 max_attempts = 1
 prompt = "prompts/repair-result.md"
 
@@ -215,7 +344,7 @@ required_output = true
 max_visits_per_iteration = 1
 
 [phases.harness]
-args = ${formatTomlArray(buildReadOnlyArgs(options.harness))}
+args = ${formatTomlArray(buildHarnessArgs(options.harness, "readonly"))}
 
 [phases.transitions]
 selected = "execution"
@@ -224,49 +353,37 @@ no_work = "stop_run"
 [[phases]]
 id = "execution"
 prompt = "prompts/execution.md"
-next = "review"
-max_visits_per_iteration = 3
-
-[phases.model]
-reasoning_level = "high"
-
+next = "${executionNext}"
+max_visits_per_iteration = 1
+${reviewPhases}
 [[phases]]
-id = "review"
-prompt = "prompts/review.md"
-output_schema = "schemas/review.schema.json"
+id = "closure"
+prompt = "prompts/closure.md"
+output_schema = "schemas/closure.schema.json"
 required_output = true
-max_visits_per_iteration = 3
-
-[phases.model]
-reasoning_level = "high"
+max_visits_per_iteration = 1
 
 [phases.harness]
-args = ${formatTomlArray(buildReadOnlyArgs(options.harness))}
+args = ${formatTomlArray(buildHarnessArgs(options.harness, "write_network"))}
 
 [phases.transitions]
-approved = "closure"
-changes_requested = "execution"
-
-[[phases]]
-id = "closure"
-prompt = "prompts/closure.md"
-next = "next_iteration"
-max_visits_per_iteration = 1
-`;
+closed = "next_iteration"
+failed = "stop_run"
+${pullRequestPhase}${globalReviewPhases}${finalizePhase}`;
 }
 function buildHarnessToml(harness) {
     if (harness === "codex") {
         return `[harness]
 preset = "codex"
 command = "codex"
-args = ${formatTomlArray(buildCodexArgs(false))}
+args = ${formatTomlArray(buildHarnessArgs("codex", "write"))}
 prompt_input = "stdin"`;
     }
     if (harness === "claude") {
         return `[harness]
 preset = "claude"
 command = "claude"
-args = ["--model", "{{model.name}}"]
+args = ${formatTomlArray(buildHarnessArgs("claude", "write"))}
 prompt_input = "stdin"`;
     }
     return `[harness]
@@ -275,28 +392,112 @@ command = "your-agent-command"
 args = []
 prompt_input = "stdin"`;
 }
-function buildReadOnlyArgs(harness) {
+/**
+ * Build the harness CLI args for a phase capability. This is where the
+ * harness-specific network/permission posture lives, keeping the runtime
+ * engine itself agnostic (it only runs `command + args`).
+ *
+ * - readonly: no writes, no network (selection, review).
+ * - write: edit files locally (execution, revision).
+ * - write_network: edit files AND reach the network for `gh`/`git push`
+ *   (closure, pull_request). This is the fix for issues never being closed:
+ *   codex's default workspace-write sandbox blocks the network, so closing a
+ *   GitHub issue silently failed.
+ */
+function buildHarnessArgs(harness, capability) {
     if (harness === "codex") {
-        return buildCodexArgs(true);
+        const args = [
+            "exec",
+            "--model",
+            "{{model.name}}",
+            "-c",
+            'model_reasoning_effort="{{model.reasoning_level}}"'
+        ];
+        if (capability === "readonly") {
+            args.push("--sandbox", "read-only");
+        }
+        else if (capability === "write_network") {
+            args.push("-c", "sandbox_workspace_write.network_access=true");
+        }
+        args.push("-");
+        return args;
     }
     if (harness === "claude") {
-        return ["--model", "{{model.name}}"];
+        const args = ["-p", "--model", "{{model.name}}", "--output-format", "text"];
+        if (capability === "readonly") {
+            args.push("--permission-mode", "plan");
+        }
+        else {
+            args.push("--dangerously-skip-permissions");
+        }
+        return args;
     }
     return [];
 }
-function buildCodexArgs(readOnly) {
-    const args = [
-        "exec",
-        "--model",
-        "{{model.name}}",
-        "-c",
-        'model_reasoning_effort="{{model.reasoning_level}}"'
-    ];
-    if (readOnly) {
-        args.push("--sandbox", "read-only");
-    }
-    args.push("-");
-    return args;
+function buildGitToml() {
+    return `[git]
+mode = "worktree"
+# base = "main"            # defaults to the current branch
+branch_template = "nyxagent/{{run_id}}"
+worktree_dir = ".nyxagent/worktrees"
+cleanup = "on_success"`;
+}
+function buildPullRequestPhaseToml(harness) {
+    return `[[phases]]
+id = "pull_request"
+prompt = "prompts/pull-request.md"
+output_schema = "schemas/pull-request.schema.json"
+required_output = true
+max_visits_per_iteration = 1
+
+[phases.harness]
+args = ${formatTomlArray(buildHarnessArgs(harness, "write_network"))}`;
+}
+/**
+ * Build the run-level "global review + correction" finalization sub-graph:
+ *
+ *   global_review --approved-----------> <terminal leaf>
+ *                 --changes_requested--> global_revision --> global_review
+ *
+ * `global_revision` relies on the default write harness (like the per-task
+ * `revision`/`execution` phases) and commits its own corrections, since no
+ * `closure` phase follows it before the terminal. `global_review` is read-only.
+ * The loop is bounded by max_visits_per_iteration = 3.
+ */
+function buildGlobalReviewPhasesToml(harness, terminal) {
+    return `[[phases]]
+id = "global_revision"
+prompt = "prompts/global-revision.md"
+next = "global_review"
+max_visits_per_iteration = 3
+
+[[phases]]
+id = "global_review"
+prompt = "prompts/global-review.md"
+output_schema = "schemas/global-review.schema.json"
+required_output = true
+max_visits_per_iteration = 3
+
+[phases.harness]
+args = ${formatTomlArray(buildHarnessArgs(harness, "readonly"))}
+
+[phases.transitions]
+approved = "${terminal}"
+changes_requested = "global_revision"`;
+}
+/**
+ * The terminal leaf of a global-review finalization flow when there is no pull
+ * request to land on (local sources, or GitHub with --no-pull-request). It is
+ * read-only and makes no changes; it just confirms/summarizes the run.
+ */
+function buildFinalizePhaseToml(harness) {
+    return `[[phases]]
+id = "finalize"
+prompt = "prompts/finalize.md"
+max_visits_per_iteration = 1
+
+[phases.harness]
+args = ${formatTomlArray(buildHarnessArgs(harness, "readonly"))}`;
 }
 function buildWorkItemsToml(options) {
     if (options.workItemsSource === "local") {

package/dist/commands/update.js

@@ -0,0 +1,148 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { confirm } from "@inquirer/prompts";
+import { execa } from "execa";
+import pc from "picocolors";
+const PACKAGE_NAME = "@nyxa/nyx-agent";
+export async function updateCommand(versionSpec, options, deps = defaultUpdateDependencies()) {
+    const spec = (versionSpec ?? "").trim() || "latest";
+    const current = deps.getCurrentVersion();
+    const target = await deps.resolveVersion(spec);
+    if (current === target) {
+        console.log(pc.green(`nyxagent is already up to date (${current}).`));
+        return;
+    }
+    // Only guard against downgrades for moving dist-tags like "latest"; an
+    // explicit version (e.g. "0.3.9") is treated as a deliberate pin.
+    const isDistTag = !/^\d/.test(spec);
+    if (isDistTag && compareVersions(current, target) > 0) {
+        console.log(pc.yellow(`Installed nyxagent ${current} is newer than ${spec} (${target}); nothing to do.`));
+        return;
+    }
+    const verb = compareVersions(target, current) >= 0 ? "Update" : "Downgrade";
+    console.log(`${verb} available: ${pc.dim(current)} -> ${pc.cyan(target)}`);
+    if (options.check) {
+        console.log(`Run ${pc.bold("nyxagent update")} to install it.`);
+        return;
+    }
+    const packageManager = options.packageManager
+        ? normalizePackageManager(options.packageManager)
+        : deps.detectPackageManager();
+    if (!options.yes) {
+        const confirmed = await deps.confirm(`${verb} nyxagent to ${target} with ${packageManager}?`);
+        if (!confirmed) {
+            console.log("Update cancelled.");
+            return;
+        }
+    }
+    console.log(`Installing ${PACKAGE_NAME}@${target} with ${packageManager}...`);
+    await deps.install({ packageManager, version: target });
+    console.log(pc.green(`nyxagent updated to ${target}. Run "nyxagent --version" to confirm.`));
+}
+function normalizePackageManager(value) {
+    if (value === "npm" ||
+        value === "pnpm" ||
+        value === "yarn" ||
+        value === "bun") {
+        return value;
+    }
+    throw new Error('package manager must be "npm", "pnpm", "yarn", or "bun"');
+}
+export function defaultUpdateDependencies() {
+    return {
+        getCurrentVersion: readPackageVersion,
+        resolveVersion: resolveVersionFromRegistry,
+        install: runGlobalInstall,
+        detectPackageManager: detectPackageManagerFromPath,
+        confirm: confirmInteractive
+    };
+}
+function readPackageVersion() {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../../package.json");
+    return pkg.version;
+}
+async function resolveVersionFromRegistry(spec) {
+    const result = await execa("npm", ["view", `${PACKAGE_NAME}@${spec}`, "version"], { reject: false });
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout || "unknown error").trim();
+        throw new Error(`Failed to query the npm registry: ${detail}`);
+    }
+    const lines = result.stdout
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        throw new Error(`No published version matches ${PACKAGE_NAME}@${spec}`);
+    }
+    // For an exact version or dist-tag npm prints a bare version; for a range it
+    // prints `<name>@<version> '<version>'` lines, so take the last match.
+    const last = lines[lines.length - 1];
+    const match = /([0-9][^\s'"]*)\s*$/.exec(last);
+    return match ? match[1] : last;
+}
+async function runGlobalInstall(input) {
+    const spec = `${PACKAGE_NAME}@${input.version}`;
+    await execa(input.packageManager, installArgs(input.packageManager, spec), {
+        stdio: "inherit"
+    });
+}
+function installArgs(packageManager, spec) {
+    switch (packageManager) {
+        case "npm":
+            return ["install", "-g", spec];
+        case "pnpm":
+            return ["add", "-g", spec];
+        case "yarn":
+            return ["global", "add", spec];
+        case "bun":
+            return ["add", "-g", spec];
+    }
+}
+function detectPackageManagerFromPath() {
+    const here = fileURLToPath(import.meta.url).replace(/\\/g, "/").toLowerCase();
+    if (here.includes("/pnpm/") || here.includes("/.pnpm/")) {
+        return "pnpm";
+    }
+    if (here.includes("/.bun/") || here.includes("/bun/")) {
+        return "bun";
+    }
+    if (here.includes("/yarn/") || here.includes("/.config/yarn/")) {
+        return "yarn";
+    }
+    return "npm";
+}
+async function confirmInteractive(message) {
+    // In a non-interactive context the user already opted in by running the
+    // command, so proceed without a prompt that would otherwise fail.
+    if (!process.stdin.isTTY) {
+        return true;
+    }
+    return confirm({ message, default: true });
+}
+function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    for (let i = 0; i < 3; i += 1) {
+        if (pa.core[i] !== pb.core[i]) {
+            return pa.core[i] - pb.core[i];
+        }
+    }
+    // A final release outranks a prerelease sharing the same core (1.0.0 > 1.0.0-rc).
+    if (pa.pre === pb.pre) {
+        return 0;
+    }
+    if (pa.pre === "") {
+        return 1;
+    }
+    if (pb.pre === "") {
+        return -1;
+    }
+    return pa.pre < pb.pre ? -1 : 1;
+}
+function parseVersion(value) {
+    const [main, pre = ""] = value.replace(/^v/, "").split("-", 2);
+    const parts = main.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    return { core: [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0], pre };
+}

package/dist/config/schema.js

@@ -29,6 +29,15 @@ const phaseSchema = z
 })
     .passthrough();
 const workItemsSourceSchema = z.preprocess((value) => (value === "local-markdown" ? "local" : value), z.enum(["local", "github"]));
+const gitSchema = z
+    .object({
+    mode: z.enum(["off", "branch", "worktree"]).default("off"),
+    base: z.string().min(1).optional(),
+    branch_template: z.string().min(1).default("nyxagent/{{run_id}}"),
+    worktree_dir: z.string().min(1).default(".nyxagent/worktrees"),
+    cleanup: z.enum(["always", "on_success", "never"]).default("on_success")
+})
+    .passthrough();
 const githubRepositoryPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const workItemsSchema = z
     .object({
@@ -68,10 +77,12 @@ export const nyxConfigSchema = z
     .object({
     workflow: z.object({
         entry_phase: z.string().min(1),
+        final_phase: z.string().min(1).optional(),
         max_iterations: z.number().int().positive()
     }),
     model: modelSchema,
     harness: harnessSchema,
+    git: gitSchema.optional(),
     repair: z
         .object({
         max_attempts: z.number().int().nonnegative().default(1),
@@ -110,6 +121,14 @@ export const nyxConfigSchema = z
             message: `Unknown entry phase "${config.workflow.entry_phase}"`
         });
     }
+    if (config.workflow.final_phase &&
+        !phaseIds.has(config.workflow.final_phase)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["workflow", "final_phase"],
+            message: `Unknown final phase "${config.workflow.final_phase}"`
+        });
+    }
     const reservedTargets = new Set([
         "stop_run",
         "stop_iteration",