@nyxa/nyx-agent 0.4.1 → 0.6.0

package/dist/commands/init.js

@@ -1,521 +1,171 @@
-import { readdir, stat } from "node:fs/promises";
+/** `nyxagent init`: scaffolds .nyxagent/config.json, the editable execution prompt, and .gitignore entries. */
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { confirm, input, number as numberPrompt, select } from "@inquirer/prompts";
+import { input, number as numberPrompt, select } from "@inquirer/prompts";
 import pc from "picocolors";
+import { harnessNames, reviewModes } from "../config/schema.js";
 import { ensureDir, pathExists, readText, writeText } from "../runtime/files.js";
 import { getNyxDir, relativeToProject } from "../runtime/paths.js";
-const DEFAULT_OPENAI_MODEL = "gpt-5.5";
+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/worktrees/"
+    ".nyxagent/config.json",
+    ".nyxagent/config.toml",
+    ".nyxagent/prompts/"
 ];
 export async function initCommand(options, projectRoot = process.cwd()) {
     const root = path.resolve(projectRoot);
     const nyxDir = getNyxDir(root);
-    const exists = await pathExists(nyxDir);
-    if (exists && !options.missing) {
-        throw new Error(`.nyxagent already exists. Use "nyxagent init --missing" to add missing template files.`);
+    const configPath = path.join(nyxDir, "config.json");
+    if ((await pathExists(configPath)) && !options.force) {
+        throw new Error('.nyxagent/config.json already exists. Use "nyxagent init --force" to overwrite it.');
     }
-    const configPath = path.join(nyxDir, "config.toml");
-    const shouldCreateConfig = !options.missing || !(await pathExists(configPath));
-    const resolved = shouldCreateConfig
-        ? await resolveInitOptions(options, root)
-        : undefined;
+    const resolved = await resolveInitOptions(options);
     await ensureDir(nyxDir);
-    const templatesDir = getTemplatesDir();
-    await copyTemplateTree(templatesDir, nyxDir, Boolean(options.missing));
-    await ensureGitignoreEntries(root);
-    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);
+    await writeText(configPath, `${JSON.stringify(buildConfig(resolved), null, 2)}\n`);
+    const executionPromptPath = path.join(nyxDir, "prompts", "execution.md");
+    if (!(await pathExists(executionPromptPath))) {
+        await ensureDir(path.dirname(executionPromptPath));
+        await writeText(executionPromptPath, EXECUTION_PROMPT_FILE);
     }
+    await ensureGitignoreEntries(root);
     console.log(pc.green("NyxAgent initialized."));
     console.log(`Config: ${relativeToProject(root, configPath)}`);
+    console.log(`Editable prompt: ${relativeToProject(root, executionPromptPath)}`);
 }
-async function resolveInitOptions(options, root) {
-    const harness = options.harness ??
-        (await select({
-            message: "Harness preset",
+async function resolveInitOptions(options) {
+    const harness = options.harness
+        ? normalizeHarness(options.harness)
+        : await select({
+            message: "Default harness",
             choices: [
                 { name: "codex", value: "codex" },
-                { name: "claude", value: "claude" },
-                { name: "custom", value: "custom" }
+                { name: "claude", value: "claude" }
             ]
-        }));
+        });
     const model = options.model ??
         (await input({
             message: "Model",
-            default: harness === "codex" ? DEFAULT_OPENAI_MODEL : ""
+            default: harness === "codex" ? DEFAULT_CODEX_MODEL : "",
+            validate: (value) => value.trim().length > 0 || "Model is required"
         }));
-    const reasoningLevel = options.reasoningLevel ??
+    const reasoning_effort = options.reasoningEffort ??
+        (await input({ message: "Reasoning effort", default: "medium" }));
+    const review = options.review
+        ? normalizeReview(options.review)
+        : await select({
+            message: "Review strategy",
+            choices: [
+                { name: "After each task", value: "each" },
+                { name: "After all tasks (global review)", value: "all" },
+                { name: "Both per-task and global", value: "both" },
+                { name: "No review", value: "none" }
+            ],
+            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 ??
         (await input({
-            message: "Default reasoning level",
-            default: "medium"
+            message: "Base branch (blank = current branch at run time)",
+            default: ""
         }));
-    const implementationSkill = await resolveImplementationSkill(options);
-    const reviewMode = await resolveReviewMode(options);
-    const parsedMaxIterations = options.maxIterations
-        ? Number.parseInt(options.maxIterations, 10)
-        : undefined;
-    const maxIterations = parsedMaxIterations ??
+    const base_branch = baseBranchInput.trim() ? baseBranchInput.trim() : undefined;
+    const max_iterations = parseMaxIterations(options.maxIterations) ??
         (await numberPrompt({
-            message: "Max iterations",
+            message: "Max work items per run",
             default: 5,
             required: true
         }));
-    const workItemsSource = options.workItemsSource
-        ? normalizeWorkItemsSource(options.workItemsSource)
-        : await select({
-            message: "Work item source template",
-            choices: [
-                { name: "local", value: "local" },
-                { name: "github", value: "github" }
-            ]
-        });
-    let workItemsPath = options.workItemsPath;
-    if (workItemsSource === "local" && !workItemsPath) {
-        const issuesPath = path.join(root, "issues");
-        workItemsPath = await input({
-            message: "Local work item path",
-            default: (await pathExists(issuesPath)) ? "issues" : ".nyxagent/tasks"
-        });
-    }
-    if (workItemsSource !== "local" && workItemsPath) {
-        throw new Error("--work-items-path can only be used with local work items");
-    }
-    let workItemsRepository = options.workItemsRepository;
-    if (workItemsSource === "github" && !workItemsRepository) {
-        workItemsRepository = await input({
-            message: "GitHub repository",
-            default: ""
-        });
-    }
-    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) {
+    if (!Number.isInteger(max_iterations) || max_iterations <= 0) {
         throw new Error("max iterations must be a positive integer");
     }
     return {
         harness,
-        model,
-        reasoningLevel,
-        maxIterations,
-        workItemsSource,
-        workItemsPath,
-        workItemsRepository,
-        implementationSkill,
-        reviewMode,
-        pullRequest
+        model: model.trim(),
+        reasoning_effort: reasoning_effort.trim() || "medium",
+        review,
+        review_max_attempts,
+        repo,
+        base_branch,
+        max_iterations
     };
 }
-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";
+function buildConfig(options) {
+    const config = {
+        harness: options.harness,
+        model: options.model,
+        reasoning_effort: options.reasoning_effort,
+        review: options.review,
+        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;
     }
-    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;
+    if (options.base_branch) {
+        config.base_branch = options.base_branch;
     }
-    throw new Error('review mode must be "each", "all", "both", or "none"');
+    return config;
 }
-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;
+function normalizeHarness(value) {
+    if (harnessNames.includes(value)) {
+        return value;
     }
-    const skill = (await input({
-        message: "Skill name (as you invoke it, e.g. /tdd)"
-    })).trim();
-    return skill.length > 0 ? skill : undefined;
+    throw new Error(`harness must be one of: ${harnessNames.join(", ")}`);
 }
-function normalizeWorkItemsSource(source) {
-    if (source === "local" || source === "local-markdown") {
-        return "local";
+function normalizeReview(value) {
+    if (reviewModes.includes(value)) {
+        return value;
     }
-    if (source === "github") {
-        return source;
-    }
-    throw new Error('work item source must be "local" or "github"');
+    throw new Error(`review must be one of: ${reviewModes.join(", ")}`);
 }
-function validateGitHubRepository(repository) {
-    if (!repository || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+function validateRepository(repo) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
         throw new Error('GitHub repository must use "owner/repo"');
     }
 }
-function getTemplatesDir() {
-    const currentFile = fileURLToPath(import.meta.url);
-    return path.resolve(path.dirname(currentFile), "../../templates/default");
-}
-async function copyTemplateTree(sourceDir, destinationDir, missingOnly) {
-    await ensureDir(destinationDir);
-    const entries = await readdir(sourceDir, { withFileTypes: true });
-    for (const entry of entries) {
-        const source = path.join(sourceDir, entry.name);
-        const destination = path.join(destinationDir, entry.name);
-        if (entry.isDirectory()) {
-            await copyTemplateTree(source, destination, missingOnly);
-            continue;
-        }
-        if (missingOnly && (await pathExists(destination))) {
-            continue;
-        }
-        await writeText(destination, await readText(source));
+function parseMaxIterations(value) {
+    if (value === undefined) {
+        return undefined;
     }
+    return Number.parseInt(value, 10);
 }
-async function ensureWorkItemsDirectory(root, taskPath) {
-    const absoluteTaskPath = path.resolve(root, taskPath);
-    if (!(await pathExists(absoluteTaskPath))) {
-        await ensureDir(absoluteTaskPath);
-    }
-    const taskPathStat = await stat(absoluteTaskPath);
-    if (!taskPathStat.isDirectory()) {
-        throw new Error(`Work item path is not a directory: ${taskPath}`);
+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))
         ? await readText(gitignorePath)
         : "";
-    const lines = current.split(/\r?\n/);
-    const existingEntries = new Set(lines.map((line) => line.trim()));
-    const missingEntries = GITIGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
-    if (missingEntries.length === 0) {
+    const existing = new Set(current.split(/\r?\n/).map((line) => line.trim()));
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !existing.has(entry));
+    if (missing.length === 0) {
         return;
     }
-    const markerIndex = lines.findIndex((line) => line.trim() === GITIGNORE_MARKER);
-    let updated;
-    if (markerIndex >= 0) {
-        const nextLines = [...lines];
-        nextLines.splice(markerIndex + 1, 0, ...missingEntries);
-        updated = normalizeGitignoreContent(nextLines.join("\n"));
-    }
-    else {
-        const prefix = getGitignoreAppendPrefix(current);
-        updated = `${current}${prefix}${GITIGNORE_MARKER}\n${missingEntries.join("\n")}\n`;
-    }
-    await writeText(gitignorePath, updated);
-}
-function getGitignoreAppendPrefix(current) {
-    if (current.length === 0) {
-        return "";
-    }
-    if (current.endsWith("\n\n")) {
-        return "";
-    }
-    if (current.endsWith("\n")) {
-        return "\n";
-    }
-    return "\n\n";
-}
-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"${finalPhaseLine}
-max_iterations = ${options.maxIterations}
-
-[model]
-name = "${escapeTomlString(options.model)}"
-reasoning_level = "${escapeTomlString(options.reasoningLevel)}"
-
-${harness}
-
-${gitSection}[repair]
-max_attempts = 1
-prompt = "prompts/repair-result.md"
-
-${workItems}
-
-[[phases]]
-id = "selection"
-prompt = "prompts/selection.md"
-output_schema = "schemas/selection.schema.json"
-required_output = true
-max_visits_per_iteration = 1
-
-[phases.harness]
-args = ${formatTomlArray(buildHarnessArgs(options.harness, "readonly"))}
-
-[phases.transitions]
-selected = "execution"
-no_work = "stop_run"
-
-[[phases]]
-id = "execution"
-prompt = "prompts/execution.md"
-next = "${executionNext}"
-max_visits_per_iteration = 1
-${reviewPhases}
-[[phases]]
-id = "closure"
-prompt = "prompts/closure.md"
-output_schema = "schemas/closure.schema.json"
-required_output = true
-max_visits_per_iteration = 1
-
-[phases.harness]
-args = ${formatTomlArray(buildHarnessArgs(options.harness, "write_network"))}
-
-[phases.transitions]
-closed = "next_iteration"
-failed = "stop_run"
-${pullRequestPhase}${globalReviewPhases}${finalizePhase}`;
-}
-function buildHarnessToml(harness) {
-    if (harness === "codex") {
-        return `[harness]
-preset = "codex"
-command = "codex"
-args = ${formatTomlArray(buildHarnessArgs("codex", "write"))}
-prompt_input = "stdin"`;
-    }
-    if (harness === "claude") {
-        return `[harness]
-preset = "claude"
-command = "claude"
-args = ${formatTomlArray(buildHarnessArgs("claude", "write"))}
-prompt_input = "stdin"`;
-    }
-    return `[harness]
-preset = "custom"
-command = "your-agent-command"
-args = []
-prompt_input = "stdin"`;
-}
-/**
- * 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") {
-        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") {
-        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 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") {
-        return `[work_items]
-source = "local"
-path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"
-max_candidates = 50
-excerpt_chars = 800`;
-    }
-    return `[work_items]
-source = "github"
-repository = "${escapeTomlString(options.workItemsRepository ?? "")}"
-max_candidates = 50
-excerpt_chars = 800`;
-}
-function formatTomlArray(values) {
-    return `[${values.map((value) => `"${escapeTomlString(value)}"`).join(", ")}]`;
-}
-function escapeTomlString(value) {
-    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    const prefix = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    const block = `${prefix}${current.length === 0 ? "" : "\n"}${GITIGNORE_MARKER}\n${missing.join("\n")}\n`;
+    await writeText(gitignorePath, `${current}${block}`);
 }

package/dist/commands/run.js

@@ -1,8 +1,22 @@
+/** `nyxagent run`: normalizes CLI options and hands off to the pipeline runner. */
 import path from "node:path";
-import { runWorkflow } from "../runtime/runWorkflow.js";
+import { harnessNames } from "../config/schema.js";
+import { runPipeline } from "../runtime/runPipeline.js";
 export async function runCommand(options, projectRoot = process.cwd()) {
-    await runWorkflow({
+    await runPipeline({
         projectRoot,
-        configPath: options.config ? path.resolve(projectRoot, options.config) : undefined
+        configPath: options.config
+            ? path.resolve(projectRoot, options.config)
+            : undefined,
+        harness: normalizeHarness(options.harness)
     });
 }
+function normalizeHarness(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (harnessNames.includes(value)) {
+        return value;
+    }
+    throw new Error(`--harness must be one of: ${harnessNames.join(", ")}`);
+}

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";