@nyxa/nyx-agent 0.1.0

package/dist/runtime/runPhase.js

@@ -0,0 +1,244 @@
+import path from "node:path";
+import { execa } from "execa";
+import { buildPhasePrompt, phaseRequiresStructuredResult } from "./buildPrompt.js";
+import { getEffectiveHarness, getEffectiveModel } from "./effectiveConfig.js";
+import { ensureDir, readText, writeJson, writeText } from "./files.js";
+import { getGitSnapshot } from "./git.js";
+import { parseNyxAgentResult, getOutcome } from "./parseResult.js";
+import { resolveNyxPath } from "./paths.js";
+import { renderTemplate } from "./renderTemplate.js";
+import { validateAgainstSchema } from "./validateResult.js";
+export async function runPhase(input) {
+    const phaseDir = path.join(input.iterationDir, "phases", input.phase.id);
+    await ensureDir(phaseDir);
+    const context = buildContext({ ...input, phaseDir });
+    const prompt = await buildPhasePrompt({
+        projectRoot: input.projectRoot,
+        runDir: input.runDir,
+        iterationDir: input.iterationDir,
+        phaseDir,
+        stateFile: input.stateFile,
+        config: input.config,
+        phase: input.phase,
+        context
+    });
+    const attempt = await runHarnessAttempt({
+        attemptDir: path.join(phaseDir, "attempt-001"),
+        prompt,
+        context,
+        config: input.config,
+        phase: input.phase,
+        projectRoot: input.projectRoot
+    });
+    if (attempt.exitCode !== 0) {
+        await writeAttemptMeta(attempt, {
+            failure: `Harness exited with code ${attempt.exitCode}`
+        });
+        return {
+            ok: false,
+            error: `Phase "${input.phase.id}" failed with exit code ${attempt.exitCode}`
+        };
+    }
+    if (!phaseRequiresStructuredResult(input.phase)) {
+        await writeAttemptMeta(attempt);
+        return { ok: true };
+    }
+    const parsed = await parseAndValidatePhaseResult({
+        input,
+        phaseDir,
+        attempt
+    });
+    if (parsed.ok) {
+        return parsed;
+    }
+    await writeAttemptMeta(attempt, {
+        result_error: parsed.error
+    });
+    const repaired = await repairStructuredResult({
+        input,
+        phaseDir,
+        originalPrompt: prompt,
+        originalAttempt: attempt,
+        validationError: parsed.error
+    });
+    if (repaired.ok) {
+        return repaired;
+    }
+    return {
+        ok: false,
+        error: repaired.error
+    };
+}
+function buildContext(input) {
+    const model = getEffectiveModel(input.config, input.phase);
+    const harness = getEffectiveHarness(input.config, input.phase);
+    return {
+        project_root: input.projectRoot,
+        run_dir: input.runDir,
+        iteration_dir: input.iterationDir,
+        phase_dir: input.phaseDir,
+        state_file: input.stateFile,
+        phase: input.phase,
+        workflow: input.config.workflow,
+        work_items: input.config.work_items ?? {},
+        work_item: input.state.work_item ?? {},
+        seen_work_item_keys: input.state.seen_work_item_keys ?? [],
+        phase_results: input.state.phase_results ?? {},
+        state: input.state,
+        model,
+        harness
+    };
+}
+async function runHarnessAttempt(input) {
+    await ensureDir(input.attemptDir);
+    await writeText(path.join(input.attemptDir, "prompt.md"), input.prompt);
+    const harness = getEffectiveHarness(input.config, input.phase);
+    if (harness.prompt_input !== "stdin") {
+        throw new Error(`Unsupported prompt_input "${harness.prompt_input}"`);
+    }
+    const command = renderTemplate(harness.command, input.context);
+    const args = harness.args.map((arg) => renderTemplate(arg, input.context));
+    const startedAt = new Date().toISOString();
+    const started = Date.now();
+    const gitBefore = await getGitSnapshot(input.projectRoot);
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    try {
+        const result = await execa(command, args, {
+            cwd: input.projectRoot,
+            input: input.prompt,
+            reject: false
+        });
+        stdout = result.stdout;
+        stderr = result.stderr;
+        exitCode = result.exitCode ?? 0;
+    }
+    catch (error) {
+        exitCode = 127;
+        stderr = error instanceof Error ? error.message : String(error);
+    }
+    const endedAt = new Date().toISOString();
+    const durationMs = Date.now() - started;
+    const gitAfter = await getGitSnapshot(input.projectRoot);
+    await writeText(path.join(input.attemptDir, "stdout.log"), stdout);
+    await writeText(path.join(input.attemptDir, "stderr.log"), stderr);
+    const attempt = {
+        attemptDir: input.attemptDir,
+        metaPath: path.join(input.attemptDir, "meta.json"),
+        stdout,
+        stderr,
+        exitCode,
+        command,
+        args,
+        startedAt,
+        endedAt,
+        durationMs,
+        gitBefore,
+        gitAfter
+    };
+    await writeAttemptMeta(attempt);
+    return attempt;
+}
+async function writeAttemptMeta(attempt, extra = {}) {
+    await writeJson(attempt.metaPath, {
+        command: attempt.command,
+        args: attempt.args,
+        started_at: attempt.startedAt,
+        ended_at: attempt.endedAt,
+        duration_ms: attempt.durationMs,
+        exit_code: attempt.exitCode,
+        git_before: attempt.gitBefore,
+        git_after: attempt.gitAfter,
+        ...extra
+    });
+}
+async function parseAndValidatePhaseResult(input) {
+    const parsed = parseNyxAgentResult(input.attempt.stdout);
+    if (!parsed.ok) {
+        return parsed;
+    }
+    if (input.input.phase.output_schema) {
+        const schemaPath = resolveNyxPath(input.input.projectRoot, input.input.phase.output_schema, `output_schema for phase "${input.input.phase.id}"`);
+        const validation = await validateAgainstSchema(schemaPath, parsed.value);
+        if (!validation.ok) {
+            return validation;
+        }
+    }
+    if (input.input.phase.transitions && !getOutcome(parsed.value)) {
+        return {
+            ok: false,
+            error: `Phase "${input.input.phase.id}" has transitions but result has no string outcome`
+        };
+    }
+    await writeJson(path.join(input.phaseDir, "result.json"), parsed.value);
+    return {
+        ok: true,
+        result: parsed.value,
+        outcome: getOutcome(parsed.value)
+    };
+}
+async function repairStructuredResult(input) {
+    const maxAttempts = input.input.config.repair.max_attempts;
+    if (maxAttempts <= 0) {
+        return {
+            ok: false,
+            error: input.validationError
+        };
+    }
+    const repairPromptTemplate = await readText(resolveNyxPath(input.input.projectRoot, input.input.config.repair.prompt, "repair prompt"));
+    let lastError = input.validationError;
+    for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
+        const repairContext = buildContext({
+            ...input.input,
+            phaseDir: input.phaseDir
+        });
+        const renderedRepairPrompt = renderTemplate(repairPromptTemplate, {
+            ...repairContext,
+            original_prompt: input.originalPrompt,
+            original_stdout: input.originalAttempt.stdout,
+            original_stderr: input.originalAttempt.stderr,
+            validation_error: lastError
+        });
+        const repairPrompt = [
+            "# NyxAgent Result Repair",
+            "",
+            "Repair only the structured result for the previous phase attempt.",
+            "Do not modify project files. Do not redo the phase work.",
+            "Return a valid result inside the final <nyxagent_result> block.",
+            "",
+            renderedRepairPrompt
+        ].join("\n");
+        const repairAttempt = await runHarnessAttempt({
+            attemptDir: path.join(input.phaseDir, `repair-${String(attemptNumber).padStart(3, "0")}`),
+            prompt: repairPrompt,
+            context: repairContext,
+            config: input.input.config,
+            phase: input.input.phase,
+            projectRoot: input.input.projectRoot
+        });
+        if (repairAttempt.exitCode !== 0) {
+            lastError = `Repair harness exited with code ${repairAttempt.exitCode}`;
+            await writeAttemptMeta(repairAttempt, {
+                failure: lastError
+            });
+            continue;
+        }
+        const repaired = await parseAndValidatePhaseResult({
+            input: input.input,
+            phaseDir: input.phaseDir,
+            attempt: repairAttempt
+        });
+        if (repaired.ok) {
+            return repaired;
+        }
+        lastError = repaired.error;
+        await writeAttemptMeta(repairAttempt, {
+            result_error: repaired.error
+        });
+    }
+    return {
+        ok: false,
+        error: lastError
+    };
+}

package/dist/runtime/runWorkflow.js

@@ -0,0 +1,158 @@
+import path from "node:path";
+import pc from "picocolors";
+import { loadConfig } from "../config/loadConfig.js";
+import { ensureDir, writeJson } from "./files.js";
+import { getGitSnapshot } from "./git.js";
+import { getNyxDir, relativeToProject } from "./paths.js";
+import { runPhase } from "./runPhase.js";
+import { createRunId } from "./time.js";
+export async function runWorkflow(options) {
+    const projectRoot = path.resolve(options.projectRoot);
+    const nyxDir = getNyxDir(projectRoot);
+    const configPath = options.configPath ?? path.join(nyxDir, "config.toml");
+    const config = await loadConfig(configPath);
+    const runId = createRunId();
+    const runDir = path.join(nyxDir, "runs", runId);
+    await ensureDir(runDir);
+    const git = await getGitSnapshot(projectRoot);
+    const runState = {
+        run_id: runId,
+        status: "running",
+        current_iteration: 0,
+        completed_iterations: 0,
+        seen_work_item_keys: []
+    };
+    await writeJson(path.join(runDir, "run.json"), {
+        run_id: runId,
+        project_root: projectRoot,
+        started_at: new Date().toISOString(),
+        config_path: relativeToProject(projectRoot, configPath),
+        harness: {
+            preset: config.harness.preset,
+            command: config.harness.command
+        },
+        git
+    });
+    await writeJson(path.join(runDir, "state.json"), runState);
+    console.log(pc.bold(`NyxAgent run ${runId}`));
+    console.log(`Project: ${projectRoot}`);
+    console.log(`Harness: ${config.harness.preset ?? "custom"} (${config.harness.command})`);
+    console.log(`Model: ${config.model.name}`);
+    console.log("");
+    const phasesById = new Map(config.phases.map((phase) => [phase.id, phase]));
+    for (let iterationNumber = 1; iterationNumber <= config.workflow.max_iterations; iterationNumber += 1) {
+        runState.current_iteration = iterationNumber;
+        await writeJson(path.join(runDir, "state.json"), runState);
+        const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
+        await ensureDir(iterationDir);
+        const iterationState = {
+            iteration: iterationNumber,
+            status: "running",
+            seen_work_item_keys: [...runState.seen_work_item_keys],
+            phase_results: {},
+            phase_visit_counts: {}
+        };
+        const iterationStateFile = path.join(iterationDir, "state.json");
+        await writeJson(iterationStateFile, iterationState);
+        let currentPhaseId = config.workflow.entry_phase;
+        while (currentPhaseId) {
+            const phase = phasesById.get(currentPhaseId);
+            if (!phase) {
+                throw new Error(`Unknown phase "${currentPhaseId}"`);
+            }
+            const visits = (iterationState.phase_visit_counts[phase.id] ?? 0) + 1;
+            iterationState.phase_visit_counts[phase.id] = visits;
+            if (visits > phase.max_visits_per_iteration) {
+                iterationState.status = "failed";
+                runState.status = "failed";
+                await writeJson(iterationStateFile, iterationState);
+                await writeJson(path.join(runDir, "state.json"), runState);
+                throw new Error(`Phase "${phase.id}" exceeded max_visits_per_iteration=${phase.max_visits_per_iteration}`);
+            }
+            process.stdout.write(`[${iterationNumber}/${config.workflow.max_iterations}] ${phase.id} ... `);
+            await writeJson(iterationStateFile, iterationState);
+            const phaseResult = await runPhase({
+                projectRoot,
+                runDir,
+                iterationDir,
+                stateFile: iterationStateFile,
+                config,
+                phase,
+                state: iterationState
+            });
+            if (!phaseResult.ok) {
+                console.log(pc.red("failed"));
+                iterationState.status = "failed";
+                iterationState.phase_results[phase.id] = {
+                    status: "failed",
+                    error: phaseResult.error
+                };
+                runState.status = "failed";
+                await writeJson(iterationStateFile, iterationState);
+                await writeJson(path.join(runDir, "state.json"), runState);
+                throw new Error(phaseResult.error);
+            }
+            iterationState.phase_results[phase.id] =
+                phaseResult.result ?? { status: "ok" };
+            const workItem = readObjectProperty(phaseResult.result, "work_item");
+            if (workItem !== undefined) {
+                iterationState.work_item = workItem;
+                const key = readObjectProperty(workItem, "key");
+                if (typeof key === "string" && !runState.seen_work_item_keys.includes(key)) {
+                    runState.seen_work_item_keys.push(key);
+                    iterationState.seen_work_item_keys = [...runState.seen_work_item_keys];
+                }
+            }
+            const nextTarget = resolveNextTarget(phase, phaseResult.outcome);
+            const label = phaseResult.outcome ?? "ok";
+            console.log(pc.green(label));
+            await writeJson(iterationStateFile, iterationState);
+            await writeJson(path.join(runDir, "state.json"), runState);
+            if (nextTarget === "stop_run") {
+                iterationState.status = phaseResult.outcome === "no_work" ? "no_work" : "stopped";
+                runState.status =
+                    phaseResult.outcome === "no_work" ? "completed_no_work" : "stopped";
+                await writeJson(iterationStateFile, iterationState);
+                await writeJson(path.join(runDir, "state.json"), runState);
+                console.log("");
+                console.log(`Done: ${runState.status}`);
+                console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
+                return;
+            }
+            if (nextTarget === "stop_iteration" || nextTarget === "next_iteration") {
+                iterationState.status = "completed";
+                runState.completed_iterations += 1;
+                await writeJson(iterationStateFile, iterationState);
+                await writeJson(path.join(runDir, "state.json"), runState);
+                break;
+            }
+            currentPhaseId = nextTarget;
+        }
+    }
+    runState.status = "completed_max_iterations";
+    await writeJson(path.join(runDir, "state.json"), runState);
+    console.log("");
+    console.log(`Done: ${runState.status}`);
+    console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
+}
+function resolveNextTarget(phase, outcome) {
+    if (phase.transitions) {
+        if (!outcome) {
+            throw new Error(`Phase "${phase.id}" requires an outcome`);
+        }
+        const target = phase.transitions[outcome];
+        if (!target) {
+            throw new Error(`Phase "${phase.id}" returned unknown outcome "${outcome}"`);
+        }
+        return target;
+    }
+    return phase.next;
+}
+function readObjectProperty(value, key) {
+    if (value &&
+        typeof value === "object" &&
+        Object.prototype.hasOwnProperty.call(value, key)) {
+        return value[key];
+    }
+    return undefined;
+}

package/dist/runtime/time.js

@@ -0,0 +1,3 @@
+export function createRunId(date = new Date()) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z").replace(/[:]/g, "-");
+}

package/dist/runtime/validateResult.js

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+import { Ajv2020 } from "ajv/dist/2020.js";
+export async function validateAgainstSchema(schemaPath, value) {
+    const schema = JSON.parse(await readFile(schemaPath, "utf8"));
+    const ajv = new Ajv2020({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const valid = validate(value);
+    if (valid) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        error: ajv.errorsText(validate.errors, { separator: "\n" })
+    };
+}