@nyxa/nyx-agent 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# NyxAgent
+
+NyxAgent is a small TypeScript CLI that runs coding-agent phases with fresh
+context for each phase.
+
+Current commands:
+
+```bash
+nyxagent init
+nyxagent init --missing
+nyxagent run
+```
+
+See [docs/nyxagent-v0-spec.md](docs/nyxagent-v0-spec.md) for the v0 design.
+# nyxagent

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { initCommand } from "./commands/init.js";
+import { runCommand } from "./commands/run.js";
+const program = new Command();
+program
+    .name("nyxagent")
+    .description("Run coding-agent workflows with fresh context per phase.")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Create a .nyxagent project configuration")
+    .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("--max-iterations <count>", "maximum work items per run")
+    .option("--work-items-source <source>", "work item source template: local-markdown, github, or custom")
+    .option("--work-items-path <path>", "local markdown work item directory")
+    .action(async (options) => {
+    await initCommand(options);
+});
+program
+    .command("run")
+    .description("Run the configured NyxAgent workflow")
+    .option("--config <path>", "config path, defaults to .nyxagent/config.toml")
+    .action(async (options) => {
+    await runCommand(options);
+});
+await program.parseAsync().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(pc.red(`Error: ${message}`));
+    process.exitCode = 1;
+});

package/dist/commands/init.js

@@ -0,0 +1,265 @@
+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 pc from "picocolors";
+import { ensureDir, pathExists, readText, writeText } from "../runtime/files.js";
+import { getNyxDir, relativeToProject } from "../runtime/paths.js";
+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.toml");
+    const shouldCreateConfig = !options.missing || !(await pathExists(configPath));
+    const resolved = shouldCreateConfig
+        ? await resolveInitOptions(options, root)
+        : undefined;
+    await ensureDir(nyxDir);
+    const templatesDir = getTemplatesDir();
+    await copyTemplateTree(templatesDir, nyxDir, Boolean(options.missing));
+    if (resolved) {
+        await writeText(configPath, buildConfigToml(resolved));
+    }
+    if (resolved?.workItemsSource === "local-markdown" && resolved.workItemsPath) {
+        await maybeCreateSampleTask(root, resolved.workItemsPath, Boolean(options.missing));
+    }
+    console.log(pc.green("NyxAgent initialized."));
+    console.log(`Config: ${relativeToProject(root, configPath)}`);
+}
+async function resolveInitOptions(options, root) {
+    const harness = options.harness ??
+        (await select({
+            message: "Harness preset",
+            choices: [
+                { name: "codex", value: "codex" },
+                { name: "claude", value: "claude" },
+                { name: "custom", value: "custom" }
+            ]
+        }));
+    const model = options.model ??
+        (await input({
+            message: "Model",
+            default: harness === "codex" ? "gpt-5-codex" : ""
+        }));
+    const reasoningLevel = options.reasoningLevel ??
+        (await input({
+            message: "Reasoning level",
+            default: "medium"
+        }));
+    const parsedMaxIterations = options.maxIterations
+        ? Number.parseInt(options.maxIterations, 10)
+        : undefined;
+    const maxIterations = parsedMaxIterations ??
+        (await numberPrompt({
+            message: "Max iterations",
+            default: 5,
+            required: true
+        }));
+    const workItemsSource = options.workItemsSource ??
+        (await select({
+            message: "Work item source template",
+            choices: [
+                { name: "local-markdown", value: "local-markdown" },
+                { name: "github", value: "github" },
+                { name: "custom", value: "custom" }
+            ]
+        }));
+    let workItemsPath = options.workItemsPath;
+    if (workItemsSource === "local-markdown" && !workItemsPath) {
+        const issuesPath = path.join(root, "issues");
+        workItemsPath = await input({
+            message: "Local task path",
+            default: (await pathExists(issuesPath)) ? "issues" : ".nyxagent/tasks"
+        });
+    }
+    if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
+        throw new Error("max iterations must be a positive integer");
+    }
+    return {
+        harness,
+        model,
+        reasoningLevel,
+        maxIterations,
+        workItemsSource,
+        workItemsPath
+    };
+}
+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));
+    }
+}
+async function maybeCreateSampleTask(root, taskPath, missingOnly) {
+    const absoluteTaskPath = path.resolve(root, taskPath);
+    await ensureDir(absoluteTaskPath);
+    const sampleTaskPath = path.join(absoluteTaskPath, "TASK-0001.md");
+    if (missingOnly && (await pathExists(sampleTaskPath))) {
+        return;
+    }
+    const taskPathStat = await stat(absoluteTaskPath);
+    if (!taskPathStat.isDirectory()) {
+        throw new Error(`Work item path is not a directory: ${taskPath}`);
+    }
+    if (!(await pathExists(sampleTaskPath))) {
+        await writeText(sampleTaskPath, [
+            "---",
+            "nyx_id: TASK-0001",
+            "status: open",
+            "title: Replace this sample task",
+            "---",
+            "",
+            "# Replace this sample task",
+            "",
+            "Describe the task here.",
+            ""
+        ].join("\n"));
+    }
+}
+function buildConfigToml(options) {
+    const harness = buildHarnessToml(options.harness);
+    const workItems = buildWorkItemsToml(options);
+    return `[workflow]
+entry_phase = "selection"
+max_iterations = ${options.maxIterations}
+
+[model]
+name = "${escapeTomlString(options.model)}"
+reasoning_level = "${escapeTomlString(options.reasoningLevel)}"
+
+${harness}
+
+[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(buildReadOnlyArgs(options.harness))}
+
+[phases.transitions]
+selected = "execution"
+no_work = "stop_run"
+
+[[phases]]
+id = "execution"
+prompt = "prompts/execution.md"
+next = "review"
+max_visits_per_iteration = 3
+
+[phases.model]
+reasoning_level = "high"
+
+[[phases]]
+id = "review"
+prompt = "prompts/review.md"
+output_schema = "schemas/review.schema.json"
+required_output = true
+max_visits_per_iteration = 3
+
+[phases.model]
+reasoning_level = "high"
+
+[phases.harness]
+args = ${formatTomlArray(buildReadOnlyArgs(options.harness))}
+
+[phases.transitions]
+approved = "closure"
+changes_requested = "execution"
+
+[[phases]]
+id = "closure"
+prompt = "prompts/closure.md"
+next = "next_iteration"
+max_visits_per_iteration = 1
+`;
+}
+function buildHarnessToml(harness) {
+    if (harness === "codex") {
+        return `[harness]
+preset = "codex"
+command = "codex"
+args = ${formatTomlArray(buildCodexArgs(false))}
+prompt_input = "stdin"`;
+    }
+    if (harness === "claude") {
+        return `[harness]
+preset = "claude"
+command = "claude"
+args = ["--model", "{{model.name}}"]
+prompt_input = "stdin"`;
+    }
+    return `[harness]
+preset = "custom"
+command = "your-agent-command"
+args = []
+prompt_input = "stdin"`;
+}
+function buildReadOnlyArgs(harness) {
+    if (harness === "codex") {
+        return buildCodexArgs(true);
+    }
+    if (harness === "claude") {
+        return ["--model", "{{model.name}}"];
+    }
+    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 buildWorkItemsToml(options) {
+    if (options.workItemsSource === "local-markdown") {
+        return `[work_items]
+source = "local-markdown"
+path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"`;
+    }
+    if (options.workItemsSource === "github") {
+        return `[work_items]
+source = "github"
+repository = ""`;
+    }
+    return `[work_items]
+source = "custom"`;
+}
+function formatTomlArray(values) {
+    return `[${values.map((value) => `"${escapeTomlString(value)}"`).join(", ")}]`;
+}
+function escapeTomlString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/commands/run.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+import { runWorkflow } from "../runtime/runWorkflow.js";
+export async function runCommand(options, projectRoot = process.cwd()) {
+    await runWorkflow({
+        projectRoot,
+        configPath: options.config ? path.resolve(projectRoot, options.config) : undefined
+    });
+}

package/dist/config/loadConfig.js

@@ -0,0 +1,8 @@
+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);
+}

package/dist/config/schema.js

@@ -0,0 +1,97 @@
+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();
+export const nyxConfigSchema = z
+    .object({
+    workflow: z.object({
+        entry_phase: z.string().min(1),
+        max_iterations: z.number().int().positive()
+    }),
+    model: modelSchema,
+    harness: harnessSchema,
+    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"
+    }),
+    work_items: z.record(z.string(), z.unknown()).optional(),
+    phases: z.array(phaseSchema).min(1)
+})
+    .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}"`
+        });
+    }
+    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}"`
+                });
+            }
+        }
+    }
+});

package/dist/runtime/buildPrompt.js

@@ -0,0 +1,57 @@
+import { readFile } from "node:fs/promises";
+import { resolveNyxPath } from "./paths.js";
+import { renderTemplate } from "./renderTemplate.js";
+export async function buildPhasePrompt(input) {
+    const promptPath = resolveNyxPath(input.projectRoot, input.phase.prompt, `prompt for phase "${input.phase.id}"`);
+    const promptTemplate = await readFile(promptPath, "utf8");
+    const userPrompt = renderTemplate(promptTemplate, input.context);
+    const runtimeContract = await buildRuntimeContract(input);
+    return `${runtimeContract}\n\n# Phase Prompt\n\n${userPrompt}`;
+}
+async function buildRuntimeContract(input) {
+    const requiresResult = phaseRequiresStructuredResult(input.phase);
+    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 lines = [
+        "# NyxAgent Runtime Contract",
+        "",
+        "You are running as one isolated phase in a NyxAgent workflow.",
+        "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),
+        "```"
+    ];
+    if (input.phase.transitions) {
+        lines.push("", "Configured outcome transitions:", "```json", JSON.stringify(input.phase.transitions, null, 2), "```");
+    }
+    if (requiresResult) {
+        lines.push("", "Structured result is required.", "Return the structured result in stdout inside the final <nyxagent_result> XML block.", "NyxAgent will parse the last <nyxagent_result> block, validate it, and write result.json.", "Do not write result.json yourself.", "", "Result format:", "```xml", "<nyxagent_result>", "{", '  "outcome": "one_of_the_configured_outcomes"', "}", "</nyxagent_result>", "```");
+        if (input.phase.transitions) {
+            lines.push("", `The JSON object must include an "outcome" matching one of: ${Object.keys(input.phase.transitions).join(", ")}.`);
+        }
+    }
+    if (schemaText) {
+        lines.push("", "Expected JSON Schema:", "```json", schemaText.trim(), "```");
+    }
+    return lines.join("\n");
+}
+export function phaseRequiresStructuredResult(phase) {
+    return Boolean(phase.required_output ||
+        phase.output_schema ||
+        (phase.transitions && Object.keys(phase.transitions).length > 0));
+}

package/dist/runtime/effectiveConfig.js

@@ -0,0 +1,14 @@
+export function getEffectiveModel(config, phase) {
+    return {
+        ...config.model,
+        ...(phase.model ?? {})
+    };
+}
+export function getEffectiveHarness(config, phase) {
+    return {
+        ...config.harness,
+        ...(phase.harness ?? {}),
+        args: phase.harness?.args ?? config.harness.args,
+        prompt_input: phase.harness?.prompt_input ?? config.harness.prompt_input
+    };
+}

package/dist/runtime/files.js

@@ -0,0 +1,25 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+export async function writeJson(filePath, value) {
+    await ensureDir(path.dirname(filePath));
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export async function readText(filePath) {
+    return readFile(filePath, "utf8");
+}
+export async function writeText(filePath, value) {
+    await ensureDir(path.dirname(filePath));
+    await writeFile(filePath, value, "utf8");
+}
+export async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime/git.js

@@ -0,0 +1,24 @@
+import { execa } from "execa";
+export async function getGitSnapshot(cwd) {
+    const isRepo = await execa("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd,
+        reject: false
+    });
+    if (isRepo.exitCode !== 0 || isRepo.stdout.trim() !== "true") {
+        return {
+            isRepository: false,
+            error: isRepo.stderr.trim() || undefined
+        };
+    }
+    const [branch, head, status] = await Promise.all([
+        execa("git", ["branch", "--show-current"], { cwd, reject: false }),
+        execa("git", ["rev-parse", "HEAD"], { cwd, reject: false }),
+        execa("git", ["status", "--short"], { cwd, reject: false })
+    ]);
+    return {
+        isRepository: true,
+        branch: branch.stdout.trim(),
+        head: head.stdout.trim(),
+        statusShort: status.stdout
+    };
+}

package/dist/runtime/parseResult.js

@@ -0,0 +1,38 @@
+const resultPattern = /<nyxagent_result\b[^>]*>([\s\S]*?)<\/nyxagent_result>/gi;
+export function parseNyxAgentResult(stdout) {
+    const matches = [...stdout.matchAll(resultPattern)];
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: "Missing <nyxagent_result> block"
+        };
+    }
+    const last = matches[matches.length - 1]?.[1]?.trim();
+    if (!last) {
+        return {
+            ok: false,
+            error: "Empty <nyxagent_result> block"
+        };
+    }
+    try {
+        return {
+            ok: true,
+            value: JSON.parse(last)
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: `Invalid JSON in <nyxagent_result>: ${message}`
+        };
+    }
+}
+export function getOutcome(result) {
+    if (result &&
+        typeof result === "object" &&
+        typeof result.outcome === "string") {
+        return result.outcome;
+    }
+    return undefined;
+}

package/dist/runtime/paths.js

@@ -0,0 +1,19 @@
+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/renderTemplate.js

@@ -0,0 +1,28 @@
+const templatePattern = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+export function renderTemplate(input, context) {
+    return input.replace(templatePattern, (_match, key) => {
+        const value = readPath(context, key);
+        if (value === undefined || value === null) {
+            return "";
+        }
+        if (typeof value === "string") {
+            return value;
+        }
+        if (typeof value === "number" ||
+            typeof value === "boolean" ||
+            typeof value === "bigint") {
+            return String(value);
+        }
+        return JSON.stringify(value, null, 2);
+    });
+}
+export function readPath(context, key) {
+    return key.split(".").reduce((current, segment) => {
+        if (current &&
+            typeof current === "object" &&
+            Object.prototype.hasOwnProperty.call(current, segment)) {
+            return current[segment];
+        }
+        return undefined;
+    }, context);
+}