@nyxa/nyx-agent 0.4.1 → 0.6.0

package/dist/config/loadConfig.js

@@ -1,8 +1,22 @@
+/** Reads, JSON-parses, and schema-validates a .nyxagent/config.json file. */
 import { readFile } from "node:fs/promises";
-import { parse } from "smol-toml";
 import { nyxConfigSchema } from "./schema.js";
 export async function loadConfig(configPath) {
     const raw = await readFile(configPath, "utf8");
-    const parsed = parse(raw);
-    return nyxConfigSchema.parse(parsed);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in ${configPath}: ${message}`);
+    }
+    const result = nyxConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ");
+        throw new Error(`Invalid NyxAgent config (${configPath}): ${detail}`);
+    }
+    return result.data;
 }

package/dist/config/schema.js

@@ -1,152 +1,35 @@
 import { z } from "zod";
-const modelSchema = z
-    .object({
-    name: z.string().min(1),
-    reasoning_level: z.string().min(1).default("medium")
-})
-    .passthrough();
-const modelOverrideSchema = modelSchema.partial().passthrough();
-const harnessSchema = z
-    .object({
-    preset: z.string().min(1).optional(),
-    command: z.string().min(1),
-    args: z.array(z.string()).default([]),
-    prompt_input: z.literal("stdin").default("stdin")
-})
-    .passthrough();
-const harnessOverrideSchema = harnessSchema.partial().passthrough();
-const phaseSchema = z
-    .object({
-    id: z.string().min(1),
-    prompt: z.string().min(1),
-    output_schema: z.string().min(1).optional(),
-    required_output: z.boolean().default(false),
-    max_visits_per_iteration: z.number().int().positive().default(1),
-    next: z.string().min(1).optional(),
-    transitions: z.record(z.string(), z.string()).optional(),
-    model: modelOverrideSchema.optional(),
-    harness: harnessOverrideSchema.optional()
-})
-    .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();
+/**
+ * The closed-pipeline configuration. NyxAgent runs one fixed workflow
+ * (select -> implement -> [review] -> commit -> [global review] -> pull request);
+ * this config only tunes the knobs the pipeline exposes. The workflow shape
+ * itself is not configurable.
+ */
+export const harnessNames = ["codex", "claude"];
+export const reviewModes = ["each", "all", "both", "none"];
 const githubRepositoryPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const workItemsSchema = z
-    .object({
-    source: workItemsSourceSchema,
-    path: z.string().min(1).optional(),
-    repository: z.string().min(1).optional(),
-    max_candidates: z.number().int().positive().default(50),
-    excerpt_chars: z.number().int().nonnegative().default(800)
-})
-    .passthrough()
-    .superRefine((workItems, ctx) => {
-    if (workItems.source === "local" && !workItems.path) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["path"],
-            message: 'Local work items require "path"'
-        });
-    }
-    if (workItems.source === "github") {
-        if (!workItems.repository) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["repository"],
-                message: 'GitHub work items require "repository"'
-            });
-        }
-        else if (!githubRepositoryPattern.test(workItems.repository)) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["repository"],
-                message: 'GitHub repository must use "owner/repo"'
-            });
-        }
-    }
-});
 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),
-        prompt: z.string().min(1).default("prompts/repair-result.md")
-    })
-        .default({
-        max_attempts: 1,
-        prompt: "prompts/repair-result.md"
+    /** Which agent CLI runs each phase. Overridable per run via `run --harness`. */
+    harness: z.enum(harnessNames),
+    /** Model name passed to the harness. */
+    model: z.string().min(1),
+    /** Reasoning effort passed to the harness (codex `model_reasoning_effort`). */
+    reasoning_effort: z.string().min(1).default("medium"),
+    /** When the agent reviews its own work. */
+    review: z.enum(reviewModes).default("each"),
+    /** How many review+revise rounds a review stage gets before the run fails. */
+    review_max_attempts: z.number().int().positive().default(4),
+    /** Work item tracker. GitHub issues only in this version. */
+    tracker: z.object({
+        type: z.literal("github"),
+        repo: z
+            .string()
+            .regex(githubRepositoryPattern, 'tracker.repo must be "owner/repo"')
     }),
-    work_items: workItemsSchema.optional(),
-    phases: z.array(phaseSchema).min(1)
+    /** Base branch the run branch is cut from. Defaults to the current branch. */
+    base_branch: z.string().min(1).optional(),
+    /** Maximum work items processed in a single run. */
+    max_iterations: z.number().int().positive().default(5)
 })
-    .superRefine((config, ctx) => {
-    const phaseIds = new Set();
-    for (const [index, phase] of config.phases.entries()) {
-        if (phaseIds.has(phase.id)) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["phases", index, "id"],
-                message: `Duplicate phase id "${phase.id}"`
-            });
-        }
-        phaseIds.add(phase.id);
-        if (phase.next && phase.transitions) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["phases", index],
-                message: `Phase "${phase.id}" cannot define both next and transitions`
-            });
-        }
-    }
-    if (!phaseIds.has(config.workflow.entry_phase)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["workflow", "entry_phase"],
-            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",
-        "next_iteration"
-    ]);
-    for (const [index, phase] of config.phases.entries()) {
-        const targets = [
-            phase.next,
-            ...Object.values(phase.transitions ?? {})
-        ].filter((target) => Boolean(target));
-        for (const target of targets) {
-            if (!reservedTargets.has(target) && !phaseIds.has(target)) {
-                ctx.addIssue({
-                    code: "custom",
-                    path: ["phases", index],
-                    message: `Phase "${phase.id}" points to unknown target "${target}"`
-                });
-            }
-        }
-    }
-});
+    .strict();

package/dist/runtime/files.js

@@ -1,3 +1,4 @@
+/** Small filesystem helpers: ensure a directory, read/write text and JSON, check existence. */
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 export async function ensureDir(dir) {

package/dist/runtime/git.js

@@ -1,3 +1,4 @@
+/** Read-only git snapshot (branch, HEAD, short status) recorded around each phase for the audit trail. */
 import { execa } from "execa";
 export async function getGitSnapshot(cwd) {
     const isRepo = await execa("git", ["rev-parse", "--is-inside-work-tree"], {

package/dist/runtime/gitLifecycle.js

@@ -1,69 +1,35 @@
 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;
-    }
+const WORKTREE_DIR = ".nyxagent/worktrees";
+export async function setUpRunWorktree(input) {
     await assertGitRepository(input.projectRoot);
-    const branch = sanitizeBranch(renderTemplate(input.git.branch_template, { run_id: input.runId }));
+    const base = input.base ?? (await currentRef(input.projectRoot));
+    const branch = sanitizeBranch(`nyxagent/${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 };
+        throw new Error(`Could not derive a branch name from run id "${input.runId}"`);
     }
-    // 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 };
+    const worktree = path.resolve(input.projectRoot, WORKTREE_DIR, input.runId);
+    await runGit(input.projectRoot, ["worktree", "add", worktree, "-b", branch, base], "create worktree");
+    return { 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 });
+export async function removeRunWorktree(input) {
+    const removal = await execa("git", ["worktree", "remove", input.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 rm(input.worktree, { recursive: true, force: true });
         await execa("git", ["worktree", "prune"], {
             cwd: input.projectRoot,
             reject: false
         });
     }
 }
+/** Delete a local branch (used when a run produced no commits). */
+export async function deleteBranch(input) {
+    await execa("git", ["branch", "-D", input.branch], {
+        cwd: input.projectRoot,
+        reject: false
+    });
+}
 export function sanitizeBranch(name) {
     return name
         .trim()
@@ -81,7 +47,7 @@ async function assertGitRepository(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".`);
+        throw new Error(`${cwd} is not a git repository. Run "git init" first.`);
     }
 }
 async function currentRef(cwd) {
@@ -96,10 +62,6 @@ async function currentRef(cwd) {
     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) {

package/dist/runtime/harness.js

@@ -0,0 +1,26 @@
+export function buildHarnessInvocation(input) {
+    if (input.harness === "codex") {
+        const args = [
+            "exec",
+            "--model",
+            input.model,
+            "-c",
+            `model_reasoning_effort="${input.reasoning}"`
+        ];
+        if (input.capability === "readonly") {
+            args.push("--sandbox", "read-only");
+        }
+        // write: codex default workspace-write sandbox; no network needed.
+        args.push("-");
+        return { command: "codex", args };
+    }
+    // claude
+    const args = ["-p", "--model", input.model, "--output-format", "text"];
+    if (input.capability === "readonly") {
+        args.push("--permission-mode", "plan");
+    }
+    else {
+        args.push("--dangerously-skip-permissions");
+    }
+    return { command: "claude", args };
+}

package/dist/runtime/ledger.js

@@ -1,3 +1,4 @@
+/** Tracks which work items each run completed (.nyxagent/state.json) so they are skipped on later runs. */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeJson } from "./files.js";

package/dist/runtime/paths.js

@@ -1,19 +1,8 @@
+/** Project path helpers: locate the .nyxagent directory and render project-relative paths. */
 import path from "node:path";
 export function getNyxDir(projectRoot) {
     return path.join(projectRoot, ".nyxagent");
 }
-export function resolveNyxPath(projectRoot, relativePath, label) {
-    if (path.isAbsolute(relativePath)) {
-        throw new Error(`${label} must be relative to .nyxagent`);
-    }
-    const nyxDir = getNyxDir(projectRoot);
-    const resolved = path.resolve(nyxDir, relativePath);
-    const relative = path.relative(nyxDir, resolved);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error(`${label} must stay inside .nyxagent`);
-    }
-    return resolved;
-}
 export function relativeToProject(projectRoot, absolutePath) {
     return path.relative(projectRoot, absolutePath) || ".";
 }

package/dist/runtime/prompts.js

@@ -0,0 +1,103 @@
+/**
+ * Embedded phase prompts and the prompt assembler.
+ *
+ * Only the execution prompt is user-overridable (via .nyxagent/prompts/execution.md);
+ * every other prompt is fixed here so the pipeline's contracts cannot drift. Each
+ * prompt is pure guidance — NyxAgent prepends an engine-owned context block and,
+ * for review-style phases, appends the required-result contract + JSON Schema.
+ */
+export const SELECTION_PROMPT = `Select and order the GitHub issues to work on in this run.
+
+The available open issues (candidates) are listed in the context above. Choose the
+ones that form a coherent unit of work for this run and order them so prerequisites
+come first. You may select a subset; skip issues that are unclear, blocked, or out
+of scope. Do not invent keys — only use keys present in the candidates.
+
+Return outcome "selected" with the ordered keys in a work_item_keys array. If
+nothing is worth working on, return outcome "no_work" instead.`;
+export const EXECUTION_PROMPT = `Implement the selected work item described in the context above.
+
+Work only on this item. Keep changes focused and coherent. Use a
+red-green-refactor loop when practical: cover the expected behavior with a focused
+test, implement the smallest change that satisfies it, then tidy the result.
+
+Do not commit and do not touch git — NyxAgent commits your changes for you. Leave
+clear validation evidence (commands run and their results) in your final response.`;
+export const REVIEW_PROMPT = `Review the implementation of the selected work item.
+
+The uncommitted changes for this item are shown as a diff in the context above; you
+may also read files in the working directory. Stay read-only and do not modify
+anything.
+
+Assess: alignment with the work item, correctness and regression risk, test or
+validation evidence, design fit, and security or data-safety concerns.
+
+Set outcome to "approved" when the work is ready, or "changes_requested" with a
+concrete, actionable list in required_changes. Always include a short summary.`;
+export const REVISION_PROMPT = `Apply the changes requested by the review for the selected work item.
+
+The required changes are listed in the context above. Address exactly those, keeping
+the work focused. Do not commit — NyxAgent commits your changes for you.`;
+export const GLOBAL_REVIEW_PROMPT = `Review the entire run as a whole, now that every selected work item is implemented
+and committed.
+
+The combined diff for the run is shown in the context above; you may also read files
+in the working directory. Stay read-only and do not modify anything.
+
+Focus on cross-cutting concerns a per-item review cannot see: integration between
+items, regressions one item introduced in another, overall design coherence,
+duplication, and gaps versus the issues' intent.
+
+Set outcome to "approved" when the run is coherent and ready, or
+"changes_requested" with a concrete, actionable list in required_changes. Always
+include a short summary.`;
+export const GLOBAL_REVISION_PROMPT = `Apply the changes requested by the global review of the whole run.
+
+The required changes are listed in the context above. Address exactly those, across
+whichever work items are affected. Do not commit — NyxAgent commits your corrections
+for you.`;
+/** Rendered into .nyxagent/prompts/execution.md at init; the only editable prompt. */
+export const EXECUTION_PROMPT_FILE = `${EXECUTION_PROMPT}
+`;
+/** Engine-owned context block prepended to every phase prompt. */
+export function buildContextBlock(entries) {
+    const lines = ["## Context", ""];
+    for (const [label, value] of entries) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        lines.push(`### ${label}`, "");
+        if (typeof value === "string") {
+            lines.push(value === "" ? "(empty)" : value, "");
+        }
+        else {
+            lines.push("```json", JSON.stringify(value, null, 2), "```", "");
+        }
+    }
+    return lines.join("\n").trimEnd();
+}
+/** Assemble the full prompt sent to the harness for one phase. */
+export function buildPhasePrompt(input) {
+    const parts = [
+        "# NyxAgent phase",
+        "",
+        "You run as one isolated phase of an automated workflow. Follow the context and",
+        "instructions below exactly.",
+        "",
+        input.context,
+        "",
+        "## Instructions",
+        "",
+        input.guidance.trim()
+    ];
+    if (input.schema) {
+        parts.push("", "## Required result", "", "End your response with a single <nyxagent_result> block containing JSON that", "matches this schema. NyxAgent parses the last such block, validates it, and", "ignores everything else for control flow.", "", "```json", JSON.stringify(input.schema, null, 2), "```", "", "<nyxagent_result>", "{ ... }", "</nyxagent_result>");
+    }
+    return parts.join("\n");
+}
+export function truncateForPrompt(text, maxChars = 40000) {
+    if (text.length <= maxChars) {
+        return text;
+    }
+    return `${text.slice(0, maxChars)}\n... [truncated ${text.length - maxChars} characters]`;
+}