@nyxa/nyx-agent 0.2.1 → 0.3.1

package/dist/cli.js

@@ -19,8 +19,9 @@ program
     .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-source <source>", "work item source template: local or github")
     .option("--work-items-path <path>", "local markdown work item directory")
+    .option("--work-items-repository <owner/repo>", "GitHub work item repository")
     .action(async (options) => {
     await initCommand(options);
 });

package/dist/commands/init.js

@@ -24,8 +24,8 @@ export async function initCommand(options, projectRoot = process.cwd()) {
     if (resolved) {
         await writeText(configPath, buildConfigToml(resolved));
     }
-    if (resolved?.workItemsSource === "local-markdown" && resolved.workItemsPath) {
-        await maybeCreateSampleTask(root, resolved.workItemsPath, Boolean(options.missing));
+    if (resolved?.workItemsSource === "local" && resolved.workItemsPath) {
+        await ensureWorkItemsDirectory(root, resolved.workItemsPath);
     }
     console.log(pc.green("NyxAgent initialized."));
     console.log(`Config: ${relativeToProject(root, configPath)}`);
@@ -59,23 +59,36 @@ async function resolveInitOptions(options, root) {
             default: 5,
             required: true
         }));
-    const workItemsSource = options.workItemsSource ??
-        (await select({
+    const workItemsSource = options.workItemsSource
+        ? normalizeWorkItemsSource(options.workItemsSource)
+        : await select({
             message: "Work item source template",
             choices: [
-                { name: "local-markdown", value: "local-markdown" },
-                { name: "github", value: "github" },
-                { name: "custom", value: "custom" }
+                { name: "local", value: "local" },
+                { name: "github", value: "github" }
             ]
-        }));
+        });
     let workItemsPath = options.workItemsPath;
-    if (workItemsSource === "local-markdown" && !workItemsPath) {
+    if (workItemsSource === "local" && !workItemsPath) {
         const issuesPath = path.join(root, "issues");
         workItemsPath = await input({
-            message: "Local task path",
+            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);
+    }
     if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
         throw new Error("max iterations must be a positive integer");
     }
@@ -85,9 +98,24 @@ async function resolveInitOptions(options, root) {
         reasoningLevel,
         maxIterations,
         workItemsSource,
-        workItemsPath
+        workItemsPath,
+        workItemsRepository
     };
 }
+function normalizeWorkItemsSource(source) {
+    if (source === "local" || source === "local-markdown") {
+        return "local";
+    }
+    if (source === "github") {
+        return source;
+    }
+    throw new Error('work item source must be "local" or "github"');
+}
+function validateGitHubRepository(repository) {
+    if (!repository || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+        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");
@@ -108,31 +136,15 @@ async function copyTemplateTree(sourceDir, destinationDir, missingOnly) {
         await writeText(destination, await readText(source));
     }
 }
-async function maybeCreateSampleTask(root, taskPath, missingOnly) {
+async function ensureWorkItemsDirectory(root, taskPath) {
     const absoluteTaskPath = path.resolve(root, taskPath);
-    await ensureDir(absoluteTaskPath);
-    const sampleTaskPath = path.join(absoluteTaskPath, "TASK-0001.md");
-    if (missingOnly && (await pathExists(sampleTaskPath))) {
-        return;
+    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}`);
     }
-    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);
@@ -245,18 +257,18 @@ function buildCodexArgs(readOnly) {
     return args;
 }
 function buildWorkItemsToml(options) {
-    if (options.workItemsSource === "local-markdown") {
+    if (options.workItemsSource === "local") {
         return `[work_items]
-source = "local-markdown"
-path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"`;
-    }
-    if (options.workItemsSource === "github") {
-        return `[work_items]
-source = "github"
-repository = ""`;
+source = "local"
+path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"
+max_candidates = 50
+excerpt_chars = 800`;
     }
     return `[work_items]
-source = "custom"`;
+source = "github"
+repository = "${escapeTomlString(options.workItemsRepository ?? "")}"
+max_candidates = 50
+excerpt_chars = 800`;
 }
 function formatTomlArray(values) {
     return `[${values.map((value) => `"${escapeTomlString(value)}"`).join(", ")}]`;

package/dist/config/schema.js

@@ -28,6 +28,42 @@ const phaseSchema = z
     harness: harnessOverrideSchema.optional()
 })
     .passthrough();
+const workItemsSourceSchema = z.preprocess((value) => (value === "local-markdown" ? "local" : value), z.enum(["local", "github"]));
+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({
@@ -45,7 +81,7 @@ export const nyxConfigSchema = z
         max_attempts: 1,
         prompt: "prompts/repair-result.md"
     }),
-    work_items: z.record(z.string(), z.unknown()).optional(),
+    work_items: workItemsSchema.optional(),
     phases: z.array(phaseSchema).min(1)
 })
     .superRefine((config, ctx) => {

package/dist/runtime/buildPrompt.js

@@ -34,6 +34,31 @@ async function buildRuntimeContract(input) {
         "Work item configuration:",
         "```json",
         JSON.stringify(input.config.work_items ?? {}, null, 2),
+        "```",
+        "",
+        "Available work items:",
+        "```json",
+        JSON.stringify(input.context.available_work_items ?? [], null, 2),
+        "```",
+        "",
+        "Selected work item queue:",
+        "```json",
+        JSON.stringify(input.context.selected_work_item_queue ?? [], null, 2),
+        "```",
+        "",
+        "Seen work item keys:",
+        "```json",
+        JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2),
+        "```",
+        "",
+        "Completed work item keys:",
+        "```json",
+        JSON.stringify(input.context.completed_work_item_keys ?? [], null, 2),
+        "```",
+        "",
+        "Last completed work item:",
+        "```json",
+        JSON.stringify(input.context.last_completed_work_item ?? null, null, 2),
         "```"
     ];
     if (input.phase.transitions) {

package/dist/runtime/ledger.js

@@ -0,0 +1,118 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeJson } from "./files.js";
+export async function readWorkItemLedger(nyxDir) {
+    const statePath = getLedgerPath(nyxDir);
+    let raw;
+    try {
+        raw = await readFile(statePath, "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return createEmptyLedger();
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse .nyxagent/state.json: ${message}`);
+    }
+    return normalizeLedger(parsed);
+}
+export async function writeWorkItemLedger(nyxDir, ledger) {
+    await writeJson(getLedgerPath(nyxDir), ledger);
+}
+export function markWorkItemCompleted(input) {
+    const record = normalizeCompletedRecord(input.workItem, input.completedAt ?? new Date().toISOString());
+    if (!record) {
+        return input.ledger;
+    }
+    const completedWorkItemKeys = uniqueStrings([
+        ...input.ledger.completed_work_item_keys,
+        record.key
+    ]);
+    const previousHistory = input.ledger.completed_work_items.filter((item) => item.key !== record.key);
+    return {
+        completed_work_item_keys: completedWorkItemKeys,
+        last_completed_work_item: record,
+        completed_work_items: [...previousHistory, record]
+    };
+}
+function getLedgerPath(nyxDir) {
+    return path.join(nyxDir, "state.json");
+}
+function createEmptyLedger() {
+    return {
+        completed_work_item_keys: [],
+        last_completed_work_item: null,
+        completed_work_items: []
+    };
+}
+function normalizeLedger(value) {
+    if (!isRecord(value)) {
+        return createEmptyLedger();
+    }
+    const completedWorkItems = Array.isArray(value.completed_work_items)
+        ? value.completed_work_items
+            .map((item) => normalizeCompletedRecord(item))
+            .filter((item) => Boolean(item))
+        : [];
+    const completedKeys = uniqueStrings([
+        ...readStringArray(value.completed_work_item_keys),
+        ...completedWorkItems.map((item) => item.key)
+    ]);
+    const lastCompleted = normalizeCompletedRecord(value.last_completed_work_item) ??
+        completedWorkItems.at(-1);
+    return {
+        completed_work_item_keys: completedKeys,
+        last_completed_work_item: lastCompleted ?? null,
+        completed_work_items: completedWorkItems
+    };
+}
+function normalizeCompletedRecord(value, completedAt) {
+    if (!isRecord(value) || typeof value.key !== "string" || value.key.length === 0) {
+        return undefined;
+    }
+    const record = {
+        key: value.key,
+        completed_at: completedAt ??
+            (typeof value.completed_at === "string"
+                ? value.completed_at
+                : new Date().toISOString())
+    };
+    if (typeof value.title === "string" && value.title.length > 0) {
+        record.title = value.title;
+    }
+    if (typeof value.url === "string" && value.url.length > 0) {
+        record.url = value.url;
+    }
+    if (isRecord(value.source)) {
+        record.source = {};
+        if (typeof value.source.type === "string") {
+            record.source.type = value.source.type;
+        }
+        if (typeof value.source.locator === "string") {
+            record.source.locator = value.source.locator;
+        }
+    }
+    return record;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/runtime/runPhase.js

@@ -8,6 +8,7 @@ import { parseNyxAgentResult, getOutcome } from "./parseResult.js";
 import { resolveNyxPath } from "./paths.js";
 import { renderTemplate } from "./renderTemplate.js";
 import { validateAgainstSchema } from "./validateResult.js";
+import { validateWorkItemIdentity, validateWorkItemQueue } from "./validateWorkItem.js";
 export async function runPhase(input) {
     const phaseDir = path.join(input.iterationDir, "phases", input.phase.id);
     await ensureDir(phaseDir);
@@ -81,8 +82,12 @@ function buildContext(input) {
         phase: input.phase,
         workflow: input.config.workflow,
         work_items: input.config.work_items ?? {},
+        available_work_items: input.state.available_work_items ?? [],
+        selected_work_item_queue: input.state.selected_work_item_queue ?? [],
         work_item: input.state.work_item ?? {},
         seen_work_item_keys: input.state.seen_work_item_keys ?? [],
+        completed_work_item_keys: input.state.completed_work_item_keys ?? [],
+        last_completed_work_item: input.state.last_completed_work_item ?? null,
         phase_results: input.state.phase_results ?? {},
         state: input.state,
         model,
@@ -171,6 +176,34 @@ async function parseAndValidatePhaseResult(input) {
             error: `Phase "${input.input.phase.id}" has transitions but result has no string outcome`
         };
     }
+    const workItem = readObjectProperty(parsed.value, "work_item");
+    if (workItem !== undefined) {
+        const currentWorkItemKey = readObjectProperty(readObjectProperty(input.input.state, "work_item"), "key");
+        const workItemValidation = validateWorkItemIdentity({
+            config: input.input.config,
+            workItem,
+            availableWorkItems: readWorkItemCandidates(input.input.state.available_work_items),
+            seenWorkItemKeys: readStringArray(input.input.state.seen_work_item_keys),
+            completedWorkItemKeys: readStringArray(input.input.state.completed_work_item_keys),
+            allowKnownKey: typeof currentWorkItemKey === "string" ? currentWorkItemKey : undefined
+        });
+        if (!workItemValidation.ok) {
+            return workItemValidation;
+        }
+    }
+    const workItems = readObjectProperty(parsed.value, "work_items");
+    if (workItems !== undefined) {
+        const workItemQueueValidation = validateWorkItemQueue({
+            config: input.input.config,
+            workItems,
+            availableWorkItems: readWorkItemCandidates(input.input.state.available_work_items),
+            seenWorkItemKeys: readStringArray(input.input.state.seen_work_item_keys),
+            completedWorkItemKeys: readStringArray(input.input.state.completed_work_item_keys)
+        });
+        if (!workItemQueueValidation.ok) {
+            return workItemQueueValidation;
+        }
+    }
     await writeJson(path.join(input.phaseDir, "result.json"), parsed.value);
     return {
         ok: true,
@@ -242,3 +275,34 @@ async function repairStructuredResult(input) {
         error: lastError
     };
 }
+function readObjectProperty(value, key) {
+    if (value &&
+        typeof value === "object" &&
+        Object.prototype.hasOwnProperty.call(value, key)) {
+        return value[key];
+    }
+    return undefined;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function readWorkItemCandidates(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter(isWorkItemCandidate);
+}
+function isWorkItemCandidate(value) {
+    const key = readObjectProperty(value, "key");
+    const title = readObjectProperty(value, "title");
+    const source = readObjectProperty(value, "source");
+    const type = readObjectProperty(source, "type");
+    const locator = readObjectProperty(source, "locator");
+    return (typeof key === "string" &&
+        typeof title === "string" &&
+        (type === "local" || type === "github") &&
+        typeof locator === "string");
+}