@nyxa/nyx-agent 0.3.2 → 0.3.4

package/dist/commands/init.js

@@ -6,6 +6,8 @@ import pc from "picocolors";
 import { ensureDir, pathExists, readText, writeText } from "../runtime/files.js";
 import { getNyxDir, relativeToProject } from "../runtime/paths.js";
 const DEFAULT_OPENAI_MODEL = "gpt-5.5";
+const GITIGNORE_MARKER = "# NyxAgent runtime artifacts";
+const GITIGNORE_ENTRIES = [".nyxagent/runs/", ".nyxagent/state.json"];
 export async function initCommand(options, projectRoot = process.cwd()) {
     const root = path.resolve(projectRoot);
     const nyxDir = getNyxDir(root);
@@ -21,6 +23,7 @@ export async function initCommand(options, projectRoot = process.cwd()) {
     await ensureDir(nyxDir);
     const templatesDir = getTemplatesDir();
     await copyTemplateTree(templatesDir, nyxDir, Boolean(options.missing));
+    await ensureGitignoreEntries(root);
     if (resolved) {
         await writeText(configPath, buildConfigToml(resolved));
     }
@@ -146,6 +149,45 @@ async function ensureWorkItemsDirectory(root, taskPath) {
         throw new Error(`Work item path is not a directory: ${taskPath}`);
     }
 }
+async function ensureGitignoreEntries(root) {
+    const gitignorePath = path.join(root, ".gitignore");
+    const current = (await pathExists(gitignorePath))
+        ? await readText(gitignorePath)
+        : "";
+    const lines = current.split(/\r?\n/);
+    const existingEntries = new Set(lines.map((line) => line.trim()));
+    const missingEntries = GITIGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
+    if (missingEntries.length === 0) {
+        return;
+    }
+    const markerIndex = lines.findIndex((line) => line.trim() === GITIGNORE_MARKER);
+    let updated;
+    if (markerIndex >= 0) {
+        const nextLines = [...lines];
+        nextLines.splice(markerIndex + 1, 0, ...missingEntries);
+        updated = normalizeGitignoreContent(nextLines.join("\n"));
+    }
+    else {
+        const prefix = getGitignoreAppendPrefix(current);
+        updated = `${current}${prefix}${GITIGNORE_MARKER}\n${missingEntries.join("\n")}\n`;
+    }
+    await writeText(gitignorePath, updated);
+}
+function getGitignoreAppendPrefix(current) {
+    if (current.length === 0) {
+        return "";
+    }
+    if (current.endsWith("\n\n")) {
+        return "";
+    }
+    if (current.endsWith("\n")) {
+        return "\n";
+    }
+    return "\n\n";
+}
+function normalizeGitignoreContent(value) {
+    return `${value.replace(/\n*$/, "")}\n`;
+}
 function buildConfigToml(options) {
     const harness = buildHarnessToml(options.harness);
     const workItems = buildWorkItemsToml(options);

package/dist/runtime/buildPrompt.js

@@ -51,6 +51,11 @@ async function buildRuntimeContract(input) {
         JSON.stringify(input.context.selected_work_item_queue ?? [], null, 2),
         "```",
         "",
+        "Work item annotations:",
+        "```json",
+        JSON.stringify(input.context.work_item_annotations ?? [], null, 2),
+        "```",
+        "",
         "Seen work item keys:",
         "```json",
         JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2),

package/dist/runtime/runPhase.js

@@ -85,6 +85,7 @@ function buildContext(input) {
         available_work_items: input.state.available_work_items ?? [],
         recommended_work_item_queue: input.state.recommended_work_item_queue ?? [],
         selected_work_item_queue: input.state.selected_work_item_queue ?? [],
+        work_item_annotations: input.state.work_item_annotations ?? [],
         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 ?? [],

package/dist/runtime/runWorkflow.js

@@ -9,6 +9,7 @@ import { getNyxDir, relativeToProject } from "./paths.js";
 import { runPhase } from "./runPhase.js";
 import { createRunId } from "./time.js";
 import { validateWorkItemQueue } from "./validateWorkItem.js";
+import { buildWorkItemKindMap, formatWorkItemChoiceName, normalizeWorkItemAnnotations } from "./workItemAnnotations.js";
 import { filterAvailableWorkItems, listWorkItemCandidates } from "./workItems.js";
 export async function runWorkflow(options) {
     const projectRoot = path.resolve(options.projectRoot);
@@ -29,6 +30,7 @@ export async function runWorkflow(options) {
         available_work_items: [],
         recommended_work_item_queue: [],
         selected_work_item_queue: [],
+        work_item_annotations: [],
         skipped_work_item_keys: [],
         selection_groups: [],
         seen_work_item_keys: [],
@@ -66,6 +68,7 @@ export async function runWorkflow(options) {
     }
     runState.available_work_items = selection.availableWorkItems;
     runState.recommended_work_item_queue = selection.workItems;
+    runState.work_item_annotations = selection.workItemAnnotations;
     runState.selection_groups = selection.selectionGroups;
     await writeJson(path.join(runDir, "state.json"), runState);
     let confirmedWorkItems;
@@ -76,6 +79,7 @@ export async function runWorkflow(options) {
                 availableWorkItems: selection.availableWorkItems,
                 recommendedWorkItems: selection.workItems,
                 workItems: selection.availableWorkItems,
+                workItemAnnotations: selection.workItemAnnotations,
                 selectionGroups: selection.selectionGroups,
                 maxIterations: config.workflow.max_iterations
             })
@@ -119,6 +123,7 @@ export async function runWorkflow(options) {
             available_work_items: selectedWorkItems,
             recommended_work_item_queue: selection.workItems,
             selected_work_item_queue: selectedWorkItems,
+            work_item_annotations: selection.workItemAnnotations,
             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,
@@ -209,6 +214,7 @@ async function runSelectionPhase(input) {
         available_work_items: availableWorkItems,
         recommended_work_item_queue: [],
         selected_work_item_queue: [],
+        work_item_annotations: [],
         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,
@@ -256,14 +262,20 @@ async function runSelectionPhase(input) {
         completedWorkItemKeys: selectionState.completed_work_item_keys
     });
     const selectionGroups = readSelectionGroups(phaseResult.result);
+    const workItemAnnotations = readWorkItemAnnotations({
+        result: phaseResult.result,
+        availableWorkItems
+    });
     selectionState.status = "completed";
     selectionState.recommended_work_item_queue = workItems;
     selectionState.selected_work_item_queue = workItems;
+    selectionState.work_item_annotations = workItemAnnotations;
     await writeJson(selectionStateFile, selectionState);
     await writeJson(path.join(input.runDir, "state.json"), input.runState);
     return {
         status: "selected",
         workItems,
+        workItemAnnotations,
         selectionGroups,
         availableWorkItems,
         nextPhaseId: nextTarget
@@ -349,6 +361,7 @@ function buildConfirmationView(input) {
     const workItems = [];
     const byKey = new Map(input.availableWorkItems.map((item) => [item.key, item]));
     const recommendedKeys = new Set(input.recommendedWorkItems.map((item) => item.key));
+    const annotationsByKey = buildWorkItemKindMap(input.workItemAnnotations ?? []);
     const displayed = new Set();
     for (const group of input.selectionGroups) {
         const groupItems = group.work_item_keys
@@ -364,7 +377,7 @@ function buildConfirmationView(input) {
         }
         choices.push(new Separator(`-- ${group.title} --`));
         for (const item of groupItems) {
-            choices.push(buildConfirmationChoice(item, recommendedKeys));
+            choices.push(buildConfirmationChoice({ item, recommendedKeys, annotationsByKey }));
             workItems.push(item);
             displayed.add(item.key);
         }
@@ -374,17 +387,20 @@ function buildConfirmationView(input) {
         choices.push(new Separator("-- Ungrouped --"));
     }
     for (const item of ungroupedItems) {
-        choices.push(buildConfirmationChoice(item, recommendedKeys));
+        choices.push(buildConfirmationChoice({ item, recommendedKeys, annotationsByKey }));
         workItems.push(item);
     }
     return { choices, workItems };
 }
-function buildConfirmationChoice(item, recommendedKeys) {
+function buildConfirmationChoice(input) {
     return {
-        value: item.key,
-        name: `${item.title} (${item.key})`,
-        description: item.excerpt,
-        checked: recommendedKeys.has(item.key)
+        value: input.item.key,
+        name: formatWorkItemChoiceName({
+            item: input.item,
+            annotationsByKey: input.annotationsByKey
+        }),
+        description: input.item.excerpt,
+        checked: input.recommendedKeys.has(input.item.key)
     };
 }
 function resolveNextTarget(phase, outcome) {
@@ -459,6 +475,12 @@ function normalizeConfirmedWorkItems(input) {
     }
     return normalized;
 }
+function readWorkItemAnnotations(input) {
+    return normalizeWorkItemAnnotations({
+        annotations: readObjectProperty(input.result, "work_item_annotations"),
+        availableWorkItems: input.availableWorkItems
+    });
+}
 function readSelectionGroups(result) {
     const groups = readObjectProperty(result, "selection_groups");
     if (!Array.isArray(groups)) {

package/dist/runtime/workItemAnnotations.js

@@ -0,0 +1,39 @@
+export const workItemKinds = ["task", "plan", "prd", "work"];
+export function normalizeWorkItemAnnotations(input) {
+    if (!Array.isArray(input.annotations)) {
+        return [];
+    }
+    const availableKeys = new Set(input.availableWorkItems.map((item) => item.key));
+    const seen = new Set();
+    const normalized = [];
+    for (const annotation of input.annotations) {
+        if (!isRecord(annotation) || typeof annotation.key !== "string") {
+            continue;
+        }
+        if (!availableKeys.has(annotation.key) || seen.has(annotation.key)) {
+            continue;
+        }
+        seen.add(annotation.key);
+        normalized.push({
+            key: annotation.key,
+            kind: normalizeWorkItemKind(annotation.kind)
+        });
+    }
+    return normalized;
+}
+export function buildWorkItemKindMap(annotations) {
+    return new Map(annotations.map((annotation) => [annotation.key, annotation.kind]));
+}
+export function formatWorkItemChoiceName(input) {
+    const kind = input.annotationsByKey.get(input.item.key) ?? "work";
+    return `[${kind}] ${input.item.title} (${input.item.key})`;
+}
+function normalizeWorkItemKind(value) {
+    return typeof value === "string" && isWorkItemKind(value) ? value : "work";
+}
+function isWorkItemKind(value) {
+    return workItemKinds.includes(value);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/docs/nyxagent-v0-spec.md

@@ -192,6 +192,10 @@ max_visits_per_iteration = 1
 - Before executing, NyxAgent shows the full `available_work_items` inventory in
   an interactive checkbox prompt. The recommended queue is pre-checked, and the
   user can add or remove available items. Only confirmed items are executed.
+- The selection phase may return optional `work_item_annotations` for display.
+  Supported kinds are `task`, `plan`, `prd`, and `work`. Unknown or missing
+  kinds are shown as `work`; annotations never affect work item identity or
+  ledger completion.
 - Local markdown work items do not have a required frontmatter schema. The
   provider infers titles from the first heading or filename and includes a
   bounded content excerpt.
@@ -303,6 +307,7 @@ The runtime contract includes:
 - `available_work_items`
 - `recommended_work_item_queue`
 - `selected_work_item_queue`
+- `work_item_annotations`
 - `seen_work_item_keys`
 - `completed_work_item_keys`
 - `last_completed_work_item`
@@ -319,6 +324,7 @@ Prompts may use simple interpolation:
 {{state_file}}
 {{recommended_work_item_queue}}
 {{selected_work_item_queue}}
+{{work_item_annotations}}
 {{work_item.key}}
 {{work_item.title}}
 {{model.name}}
@@ -387,6 +393,7 @@ Each run creates a timestamped directory:
 - available work items seen by the initial selection phase
 - recommended work item queue returned by the selection agent
 - selected work item queue confirmed for the run
+- work item annotations returned by the selection agent
 - skipped recommended work item keys
 - selection groups returned for user review
 - seen work item keys
@@ -456,6 +463,8 @@ Selection:
   `completed_work_item_keys`
 - optionally include `selection_groups` to present related work by the most
   useful grouping the agent can infer
+- optionally include `work_item_annotations` with display kinds `task`, `plan`,
+  `prd`, or `work`
 - return `selected` or `no_work`
 
 Execution:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {

package/templates/default/prompts/selection.md

@@ -12,6 +12,11 @@ declared relationships when available, but do not assume every project uses
 plan/PRD subdirectories. Groups may include any key from `available_work_items`,
 including items that are not part of your recommended `work_items` queue.
 
+When useful, include `work_item_annotations` to label available items for user
+review. Each annotation should include `key` and `kind`. Use `kind` values:
+`task`, `plan`, `prd`, or `work`. Use `work` when you are not sure. You may
+annotate items that are not in the recommended `work_items` queue.
+
 Prefer concrete tasks over their parent plan when both are present and the task
 is ready to execute. Choose the plan itself only when it is the best next work.
 If no candidate is exploitable, return `no_work`.
@@ -31,7 +36,8 @@ The selected work item identities must match the inventory entries:
 Return one of these outcomes:
 
 - `selected`: include recommended ordered `work_items`; optionally include
-  `selection_groups` with `title`, optional `kind`, and `work_item_keys`
+  `selection_groups` with `title`, optional `kind`, and `work_item_keys`; and
+  optionally include `work_item_annotations` with `key` and `kind`
 - `no_work`: include a short `reason`
 
 For compatibility, `work_item` is still accepted for a single selected item, but

package/templates/default/schemas/selection.schema.json

@@ -77,6 +77,23 @@
         "additionalProperties": true
       }
     },
+    "work_item_annotations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key"],
+        "properties": {
+          "key": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
     "reason": {
       "type": "string"
     }