@nyxa/nyx-agent 0.2.1 → 0.3.1

package/dist/runtime/runWorkflow.js

@@ -1,11 +1,15 @@
 import path from "node:path";
+import { checkbox, Separator } from "@inquirer/prompts";
 import pc from "picocolors";
 import { loadConfig } from "../config/loadConfig.js";
 import { ensureDir, writeJson } from "./files.js";
 import { getGitSnapshot } from "./git.js";
+import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "./ledger.js";
 import { getNyxDir, relativeToProject } from "./paths.js";
 import { runPhase } from "./runPhase.js";
 import { createRunId } from "./time.js";
+import { validateWorkItemQueue } from "./validateWorkItem.js";
+import { filterAvailableWorkItems, listWorkItemCandidates } from "./workItems.js";
 export async function runWorkflow(options) {
     const projectRoot = path.resolve(options.projectRoot);
     const nyxDir = getNyxDir(projectRoot);
@@ -14,13 +18,21 @@ export async function runWorkflow(options) {
     const runId = createRunId();
     const runDir = path.join(nyxDir, "runs", runId);
     await ensureDir(runDir);
+    let ledger = await readWorkItemLedger(nyxDir);
+    await writeWorkItemLedger(nyxDir, ledger);
     const git = await getGitSnapshot(projectRoot);
     const runState = {
         run_id: runId,
         status: "running",
         current_iteration: 0,
         completed_iterations: 0,
-        seen_work_item_keys: []
+        available_work_items: [],
+        selected_work_item_queue: [],
+        skipped_work_item_keys: [],
+        selection_groups: [],
+        seen_work_item_keys: [],
+        completed_work_item_keys: [...ledger.completed_work_item_keys],
+        last_completed_work_item: ledger.last_completed_work_item
     };
     await writeJson(path.join(runDir, "run.json"), {
         run_id: runId,
@@ -40,7 +52,58 @@ export async function runWorkflow(options) {
     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) {
+    const selection = await runSelectionPhase({
+        projectRoot,
+        runDir,
+        config,
+        phasesById,
+        runState,
+        ledger
+    });
+    if (selection.status === "stopped") {
+        return;
+    }
+    runState.available_work_items = selection.availableWorkItems;
+    runState.selection_groups = selection.selectionGroups;
+    await writeJson(path.join(runDir, "state.json"), runState);
+    let confirmedWorkItems;
+    try {
+        confirmedWorkItems = normalizeConfirmedWorkItems({
+            queue: selection.workItems,
+            confirmed: await (options.confirmWorkItems ?? confirmWorkItemsWithCheckbox)({
+                workItems: selection.workItems,
+                selectionGroups: selection.selectionGroups,
+                maxIterations: config.workflow.max_iterations
+            })
+        });
+    }
+    catch (error) {
+        runState.status = "failed";
+        await writeJson(path.join(runDir, "state.json"), runState);
+        throw error;
+    }
+    const selectedWorkItems = confirmedWorkItems.slice(0, config.workflow.max_iterations);
+    const selectedKeys = new Set(selectedWorkItems.map((item) => item.key));
+    runState.selected_work_item_queue = selectedWorkItems;
+    runState.skipped_work_item_keys = selection.workItems
+        .filter((item) => !selectedKeys.has(item.key))
+        .map((item) => item.key);
+    runState.seen_work_item_keys = selectedWorkItems.map((item) => item.key);
+    await writeJson(path.join(runDir, "state.json"), runState);
+    if (confirmedWorkItems.length > config.workflow.max_iterations) {
+        console.log(pc.yellow(`Only the first ${config.workflow.max_iterations} selected work items will run.`));
+    }
+    if (selectedWorkItems.length === 0) {
+        runState.status = "completed_no_selected_work";
+        await writeJson(path.join(runDir, "state.json"), runState);
+        console.log("");
+        console.log(`Done: ${runState.status}`);
+        console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
+        return;
+    }
+    for (let queueIndex = 0; queueIndex < selectedWorkItems.length; queueIndex += 1) {
+        const iterationNumber = queueIndex + 1;
+        const workItem = selectedWorkItems[queueIndex];
         runState.current_iteration = iterationNumber;
         await writeJson(path.join(runDir, "state.json"), runState);
         const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
@@ -48,68 +111,42 @@ export async function runWorkflow(options) {
         const iterationState = {
             iteration: iterationNumber,
             status: "running",
+            work_item: workItem,
+            available_work_items: selectedWorkItems,
+            selected_work_item_queue: selectedWorkItems,
             seen_work_item_keys: [...runState.seen_work_item_keys],
+            completed_work_item_keys: [...ledger.completed_work_item_keys],
+            last_completed_work_item: ledger.last_completed_work_item,
             phase_results: {},
             phase_visit_counts: {}
         };
         const iterationStateFile = path.join(iterationDir, "state.json");
         await writeJson(iterationStateFile, iterationState);
-        let currentPhaseId = config.workflow.entry_phase;
+        let currentPhaseId = selection.nextPhaseId;
         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({
+            const phaseResult = await runWorkflowPhase({
                 projectRoot,
                 runDir,
                 iterationDir,
-                stateFile: iterationStateFile,
+                iterationStateFile,
                 config,
                 phase,
-                state: iterationState
+                iterationState,
+                runState,
+                iterationNumber,
+                maxIterations: selectedWorkItems.length
             });
             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";
+                iterationState.status =
+                    phaseResult.outcome === "no_work" ? "no_work" : "stopped";
                 runState.status =
                     phaseResult.outcome === "no_work" ? "completed_no_work" : "stopped";
                 await writeJson(iterationStateFile, iterationState);
@@ -122,6 +159,16 @@ export async function runWorkflow(options) {
             if (nextTarget === "stop_iteration" || nextTarget === "next_iteration") {
                 iterationState.status = "completed";
                 runState.completed_iterations += 1;
+                ledger = await completeIterationWorkItem({
+                    nyxDir,
+                    ledger,
+                    runState,
+                    iterationState
+                });
+                iterationState.completed_work_item_keys = [
+                    ...ledger.completed_work_item_keys
+                ];
+                iterationState.last_completed_work_item = ledger.last_completed_work_item;
                 await writeJson(iterationStateFile, iterationState);
                 await writeJson(path.join(runDir, "state.json"), runState);
                 break;
@@ -129,12 +176,203 @@ export async function runWorkflow(options) {
             currentPhaseId = nextTarget;
         }
     }
-    runState.status = "completed_max_iterations";
+    runState.status =
+        selectedWorkItems.length >= config.workflow.max_iterations
+            ? "completed_max_iterations"
+            : "completed_queue";
     await writeJson(path.join(runDir, "state.json"), runState);
     console.log("");
     console.log(`Done: ${runState.status}`);
     console.log(`Run dir: ${relativeToProject(projectRoot, runDir)}`);
 }
+async function runSelectionPhase(input) {
+    const selectionPhase = input.phasesById.get(input.config.workflow.entry_phase);
+    if (!selectionPhase) {
+        throw new Error(`Unknown phase "${input.config.workflow.entry_phase}"`);
+    }
+    const availableWorkItems = await loadAvailableWorkItems({
+        projectRoot: input.projectRoot,
+        config: input.config,
+        runState: input.runState,
+        ledger: input.ledger
+    });
+    const selectionDir = path.join(input.runDir, "selection");
+    await ensureDir(selectionDir);
+    const selectionState = {
+        iteration: 0,
+        status: "running",
+        available_work_items: availableWorkItems,
+        selected_work_item_queue: [],
+        seen_work_item_keys: [...input.runState.seen_work_item_keys],
+        completed_work_item_keys: [...input.ledger.completed_work_item_keys],
+        last_completed_work_item: input.ledger.last_completed_work_item,
+        phase_results: {},
+        phase_visit_counts: {}
+    };
+    const selectionStateFile = path.join(selectionDir, "state.json");
+    await writeJson(selectionStateFile, selectionState);
+    const phaseResult = await runWorkflowPhase({
+        projectRoot: input.projectRoot,
+        runDir: input.runDir,
+        iterationDir: selectionDir,
+        iterationStateFile: selectionStateFile,
+        config: input.config,
+        phase: selectionPhase,
+        iterationState: selectionState,
+        runState: input.runState,
+        iterationNumber: "selection",
+        maxIterations: input.config.workflow.max_iterations
+    });
+    if (!phaseResult.ok) {
+        throw new Error(phaseResult.error);
+    }
+    const nextTarget = resolveNextTarget(selectionPhase, phaseResult.outcome);
+    if (nextTarget === "stop_run") {
+        selectionState.status =
+            phaseResult.outcome === "no_work" ? "no_work" : "stopped";
+        input.runState.status =
+            phaseResult.outcome === "no_work" ? "completed_no_work" : "stopped";
+        await writeJson(selectionStateFile, selectionState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        console.log("");
+        console.log(`Done: ${input.runState.status}`);
+        console.log(`Run dir: ${relativeToProject(input.projectRoot, input.runDir)}`);
+        return { status: "stopped" };
+    }
+    if (!nextTarget || isReservedTarget(nextTarget)) {
+        throw new Error(`Selection phase must transition to a runnable phase, got "${nextTarget ?? "none"}"`);
+    }
+    const workItems = readSelectedWorkItems({
+        config: input.config,
+        result: phaseResult.result,
+        availableWorkItems,
+        seenWorkItemKeys: selectionState.seen_work_item_keys,
+        completedWorkItemKeys: selectionState.completed_work_item_keys
+    });
+    const selectionGroups = readSelectionGroups(phaseResult.result);
+    selectionState.status = "completed";
+    selectionState.selected_work_item_queue = workItems;
+    await writeJson(selectionStateFile, selectionState);
+    await writeJson(path.join(input.runDir, "state.json"), input.runState);
+    return {
+        status: "selected",
+        workItems,
+        selectionGroups,
+        availableWorkItems,
+        nextPhaseId: nextTarget
+    };
+}
+async function runWorkflowPhase(input) {
+    const visits = (input.iterationState.phase_visit_counts[input.phase.id] ?? 0) + 1;
+    input.iterationState.phase_visit_counts[input.phase.id] = visits;
+    if (visits > input.phase.max_visits_per_iteration) {
+        input.iterationState.status = "failed";
+        input.runState.status = "failed";
+        await writeJson(input.iterationStateFile, input.iterationState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        return {
+            ok: false,
+            error: `Phase "${input.phase.id}" exceeded max_visits_per_iteration=${input.phase.max_visits_per_iteration}`
+        };
+    }
+    process.stdout.write(`[${input.iterationNumber}/${input.maxIterations}] ${input.phase.id} ... `);
+    await writeJson(input.iterationStateFile, input.iterationState);
+    const phaseResult = await runPhase({
+        projectRoot: input.projectRoot,
+        runDir: input.runDir,
+        iterationDir: input.iterationDir,
+        stateFile: input.iterationStateFile,
+        config: input.config,
+        phase: input.phase,
+        state: input.iterationState
+    });
+    if (!phaseResult.ok) {
+        console.log(pc.red("failed"));
+        input.iterationState.status = "failed";
+        input.iterationState.phase_results[input.phase.id] = {
+            status: "failed",
+            error: phaseResult.error
+        };
+        input.runState.status = "failed";
+        await writeJson(input.iterationStateFile, input.iterationState);
+        await writeJson(path.join(input.runDir, "state.json"), input.runState);
+        return phaseResult;
+    }
+    input.iterationState.phase_results[input.phase.id] =
+        phaseResult.result ?? { status: "ok" };
+    const workItem = readObjectProperty(phaseResult.result, "work_item");
+    if (workItem !== undefined && input.iterationNumber !== "selection") {
+        input.iterationState.work_item = workItem;
+        const key = readObjectProperty(workItem, "key");
+        if (typeof key === "string" &&
+            !input.runState.seen_work_item_keys.includes(key)) {
+            input.runState.seen_work_item_keys.push(key);
+            input.iterationState.seen_work_item_keys = [
+                ...input.runState.seen_work_item_keys
+            ];
+        }
+    }
+    const label = phaseResult.outcome ?? "ok";
+    console.log(pc.green(label));
+    await writeJson(input.iterationStateFile, input.iterationState);
+    await writeJson(path.join(input.runDir, "state.json"), input.runState);
+    return phaseResult;
+}
+export async function confirmWorkItemsWithCheckbox(input) {
+    if (input.workItems.length === 0) {
+        return [];
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Work item selection confirmation requires an interactive TTY");
+    }
+    const selectedKeys = await checkbox({
+        message: `Confirm work items to run (max ${input.maxIterations})`,
+        choices: buildConfirmationChoices(input),
+        required: false,
+        pageSize: Math.min(Math.max(input.workItems.length + 2, 5), 20)
+    });
+    const selected = new Set(selectedKeys);
+    return input.workItems.filter((item) => selected.has(item.key));
+}
+function buildConfirmationChoices(input) {
+    const choices = [];
+    const byKey = new Map(input.workItems.map((item) => [item.key, item]));
+    const displayed = new Set();
+    for (const group of input.selectionGroups) {
+        const groupItems = group.work_item_keys
+            .map((key) => byKey.get(key))
+            .filter((item) => {
+            if (!item) {
+                return false;
+            }
+            return !displayed.has(item.key);
+        });
+        if (groupItems.length === 0) {
+            continue;
+        }
+        choices.push(new Separator(`-- ${group.title} --`));
+        for (const item of groupItems) {
+            choices.push(buildConfirmationChoice(item));
+            displayed.add(item.key);
+        }
+    }
+    const ungroupedItems = input.workItems.filter((item) => !displayed.has(item.key));
+    if (input.selectionGroups.length > 0 && ungroupedItems.length > 0) {
+        choices.push(new Separator("-- Ungrouped --"));
+    }
+    for (const item of ungroupedItems) {
+        choices.push(buildConfirmationChoice(item));
+    }
+    return choices;
+}
+function buildConfirmationChoice(item) {
+    return {
+        value: item.key,
+        name: `${item.title} (${item.key})`,
+        description: item.excerpt,
+        checked: true
+    };
+}
 function resolveNextTarget(phase, outcome) {
     if (phase.transitions) {
         if (!outcome) {
@@ -148,6 +386,97 @@ function resolveNextTarget(phase, outcome) {
     }
     return phase.next;
 }
+async function loadAvailableWorkItems(input) {
+    const candidates = await listWorkItemCandidates({
+        projectRoot: input.projectRoot,
+        config: input.config
+    });
+    return filterAvailableWorkItems({
+        candidates,
+        seenWorkItemKeys: input.runState.seen_work_item_keys,
+        completedWorkItemKeys: input.ledger.completed_work_item_keys
+    });
+}
+async function completeIterationWorkItem(input) {
+    const ledger = markWorkItemCompleted({
+        ledger: input.ledger,
+        workItem: input.iterationState.work_item
+    });
+    input.runState.completed_work_item_keys = [
+        ...ledger.completed_work_item_keys
+    ];
+    input.runState.last_completed_work_item = ledger.last_completed_work_item;
+    await writeWorkItemLedger(input.nyxDir, ledger);
+    return ledger;
+}
+function readSelectedWorkItems(input) {
+    const workItems = readObjectProperty(input.result, "work_items");
+    const legacyWorkItem = readObjectProperty(input.result, "work_item");
+    const selection = workItems ?? (legacyWorkItem === undefined ? undefined : [legacyWorkItem]);
+    if (selection === undefined) {
+        throw new Error('Selection phase returned "selected" without work_items');
+    }
+    const validation = validateWorkItemQueue({
+        config: input.config,
+        workItems: selection,
+        availableWorkItems: input.availableWorkItems,
+        seenWorkItemKeys: input.seenWorkItemKeys,
+        completedWorkItemKeys: input.completedWorkItemKeys
+    });
+    if (!validation.ok) {
+        throw new Error(validation.error);
+    }
+    return validation.workItems;
+}
+function normalizeConfirmedWorkItems(input) {
+    const queuedByKey = new Map(input.queue.map((item) => [item.key, item]));
+    const selected = new Set();
+    const normalized = [];
+    for (const item of input.confirmed) {
+        const queued = queuedByKey.get(item.key);
+        if (!queued) {
+            throw new Error(`Confirmed work item key "${item.key}" is not in selected queue`);
+        }
+        if (selected.has(item.key)) {
+            throw new Error(`Confirmed work item key "${item.key}" was selected twice`);
+        }
+        selected.add(item.key);
+        normalized.push(queued);
+    }
+    return normalized;
+}
+function readSelectionGroups(result) {
+    const groups = readObjectProperty(result, "selection_groups");
+    if (!Array.isArray(groups)) {
+        return [];
+    }
+    return groups
+        .map((group) => {
+        if (!isRecord(group) || typeof group.title !== "string") {
+            return undefined;
+        }
+        const keys = Array.isArray(group.work_item_keys)
+            ? group.work_item_keys.filter((key) => typeof key === "string")
+            : [];
+        if (keys.length === 0) {
+            return undefined;
+        }
+        const normalized = {
+            title: group.title,
+            work_item_keys: keys
+        };
+        if (typeof group.kind === "string") {
+            normalized.kind = group.kind;
+        }
+        return normalized;
+    })
+        .filter((group) => Boolean(group));
+}
+function isReservedTarget(target) {
+    return (target === "stop_run" ||
+        target === "stop_iteration" ||
+        target === "next_iteration");
+}
 function readObjectProperty(value, key) {
     if (value &&
         typeof value === "object" &&
@@ -156,3 +485,6 @@ function readObjectProperty(value, key) {
     }
     return undefined;
 }
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}