@nyxa/nyx-agent 0.3.1 → 0.3.3

package/dist/runtime/buildPrompt.js

@@ -41,11 +41,21 @@ async function buildRuntimeContract(input) {
         JSON.stringify(input.context.available_work_items ?? [], null, 2),
         "```",
         "",
+        "Recommended work item queue:",
+        "```json",
+        JSON.stringify(input.context.recommended_work_item_queue ?? [], null, 2),
+        "```",
+        "",
         "Selected work item queue:",
         "```json",
         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

@@ -83,7 +83,9 @@ function buildContext(input) {
         workflow: input.config.workflow,
         work_items: input.config.work_items ?? {},
         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);
@@ -27,7 +28,9 @@ export async function runWorkflow(options) {
         current_iteration: 0,
         completed_iterations: 0,
         available_work_items: [],
+        recommended_work_item_queue: [],
         selected_work_item_queue: [],
+        work_item_annotations: [],
         skipped_work_item_keys: [],
         selection_groups: [],
         seen_work_item_keys: [],
@@ -64,14 +67,19 @@ export async function runWorkflow(options) {
         return;
     }
     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;
     try {
         confirmedWorkItems = normalizeConfirmedWorkItems({
-            queue: selection.workItems,
+            availableWorkItems: selection.availableWorkItems,
             confirmed: await (options.confirmWorkItems ?? confirmWorkItemsWithCheckbox)({
-                workItems: selection.workItems,
+                availableWorkItems: selection.availableWorkItems,
+                recommendedWorkItems: selection.workItems,
+                workItems: selection.availableWorkItems,
+                workItemAnnotations: selection.workItemAnnotations,
                 selectionGroups: selection.selectionGroups,
                 maxIterations: config.workflow.max_iterations
             })
@@ -113,7 +121,9 @@ export async function runWorkflow(options) {
             status: "running",
             work_item: workItem,
             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,
@@ -202,7 +212,9 @@ async function runSelectionPhase(input) {
         iteration: 0,
         status: "running",
         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,
@@ -250,13 +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
@@ -319,24 +338,30 @@ async function runWorkflowPhase(input) {
     return phaseResult;
 }
 export async function confirmWorkItemsWithCheckbox(input) {
-    if (input.workItems.length === 0) {
+    if (input.availableWorkItems.length === 0) {
         return [];
     }
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new Error("Work item selection confirmation requires an interactive TTY");
     }
+    const confirmationView = buildConfirmationView(input);
     const selectedKeys = await checkbox({
         message: `Confirm work items to run (max ${input.maxIterations})`,
-        choices: buildConfirmationChoices(input),
+        choices: confirmationView.choices,
         required: false,
-        pageSize: Math.min(Math.max(input.workItems.length + 2, 5), 20)
+        pageSize: Math.min(Math.max(input.availableWorkItems.length + 2, 5), 20),
+        validate: (selected) => selected.length <= input.maxIterations ||
+            `Select at most ${input.maxIterations} work items.`
     });
     const selected = new Set(selectedKeys);
-    return input.workItems.filter((item) => selected.has(item.key));
+    return confirmationView.workItems.filter((item) => selected.has(item.key));
 }
-function buildConfirmationChoices(input) {
+function buildConfirmationView(input) {
     const choices = [];
-    const byKey = new Map(input.workItems.map((item) => [item.key, item]));
+    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
@@ -352,25 +377,30 @@ function buildConfirmationChoices(input) {
         }
         choices.push(new Separator(`-- ${group.title} --`));
         for (const item of groupItems) {
-            choices.push(buildConfirmationChoice(item));
+            choices.push(buildConfirmationChoice({ item, recommendedKeys, annotationsByKey }));
+            workItems.push(item);
             displayed.add(item.key);
         }
     }
-    const ungroupedItems = input.workItems.filter((item) => !displayed.has(item.key));
+    const ungroupedItems = input.availableWorkItems.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));
+        choices.push(buildConfirmationChoice({ item, recommendedKeys, annotationsByKey }));
+        workItems.push(item);
     }
-    return choices;
+    return { choices, workItems };
 }
-function buildConfirmationChoice(item) {
+function buildConfirmationChoice(input) {
     return {
-        value: item.key,
-        name: `${item.title} (${item.key})`,
-        description: item.excerpt,
-        checked: true
+        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) {
@@ -429,22 +459,28 @@ function readSelectedWorkItems(input) {
     return validation.workItems;
 }
 function normalizeConfirmedWorkItems(input) {
-    const queuedByKey = new Map(input.queue.map((item) => [item.key, item]));
+    const availableByKey = new Map(input.availableWorkItems.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`);
+        const available = availableByKey.get(item.key);
+        if (!available) {
+            throw new Error(`Confirmed work item key "${item.key}" is not in available_work_items`);
         }
         if (selected.has(item.key)) {
             throw new Error(`Confirmed work item key "${item.key}" was selected twice`);
         }
         selected.add(item.key);
-        normalized.push(queued);
+        normalized.push(available);
     }
     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

@@ -185,12 +185,17 @@ max_visits_per_iteration = 1
 - `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
 - At run start, the engine scans the configured provider, normalizes candidates
   into `available_work_items`, and sends that inventory to the selection phase.
-- The selection phase returns an ordered `work_items` queue. NyxAgent validates
-  each selected identity against `[work_items]`, rejects duplicates, and
-  requires every selected key to exist in `available_work_items`.
-- Before executing, NyxAgent shows the selected queue in an interactive
-  checkbox prompt. The user can uncheck work items; only confirmed items are
-  executed.
+- The selection phase returns an ordered recommended `work_items` queue.
+  NyxAgent validates each recommended identity against `[work_items]`, rejects
+  duplicates, and requires every selected key to exist in
+  `available_work_items`.
+- 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.
@@ -199,7 +204,8 @@ max_visits_per_iteration = 1
   configured repository.
 - NyxAgent does not decide whether an item is a plan, PRD, or task. The
   selection agent makes that semantic choice from the deterministic inventory
-  and may include optional `selection_groups` for user review.
+  and may include optional `selection_groups` for user review. Groups may cover
+  the full available inventory, not only the recommended queue.
 
 ## Workflow Model
 
@@ -222,7 +228,7 @@ only knows phases, outcomes, transitions, and visit limits.
 The default template expresses the standard run:
 
 ```text
-selection -> user confirms queue
+selection -> user confirms inventory with recommended queue pre-checked
 for each confirmed work item:
   execution -> review
 review.approved -> closure -> next_iteration
@@ -299,7 +305,9 @@ The runtime contract includes:
 - work item context, when selected
 - work item config from `[work_items]`
 - `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`
@@ -314,7 +322,9 @@ Prompts may use simple interpolation:
 {{iteration_dir}}
 {{phase_dir}}
 {{state_file}}
+{{recommended_work_item_queue}}
 {{selected_work_item_queue}}
+{{work_item_annotations}}
 {{work_item.key}}
 {{work_item.title}}
 {{model.name}}
@@ -381,8 +391,10 @@ Each run creates a timestamped directory:
 - current iteration
 - completed iterations
 - 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
-- skipped selected work item keys
+- work item annotations returned by the selection agent
+- skipped recommended work item keys
 - selection groups returned for user review
 - seen work item keys
 - completed work item keys
@@ -442,14 +454,17 @@ Default prompts should be concise but operational.
 
 Selection:
 
-- choose an ordered queue from `available_work_items`
+- recommend an ordered queue from `available_work_items`
 - treat candidates agnostically: they may be plans, PRDs, or tasks
 - prefer the most actionable items based on candidate titles and excerpts
 - if a plan references concrete candidate tasks, choose the concrete task when
   that is the best next work
 - avoid keys already present in `seen_work_item_keys` or
   `completed_work_item_keys`
-- optionally include `selection_groups` to present related work by plan or PRD
+- 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.1",
+  "version": "0.3.3",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {

package/templates/default/prompts/selection.md

@@ -1,13 +1,21 @@
-Select the ordered work item queue for this run.
+Recommend the ordered work item queue for this run.
 
 Use `available_work_items` from the runtime contract as the complete inventory
-for selection. Some candidates may be plans, PRDs, or concrete tasks. Build the
-most actionable queue for this run, up to `workflow.max_iterations` items.
-
-If candidates appear to belong to the same plan or PRD, keep related concrete
-tasks together and use `selection_groups` to describe the grouping. The grouping
-is only for user review; every executable item must still be included in
-`work_items`.
+for selection. Some candidates may be plans, PRDs, or concrete tasks.
+Recommend the most actionable queue for this run, up to
+`workflow.max_iterations` items. NyxAgent will show the complete inventory to
+the user afterward with your recommendation pre-selected.
+
+If candidates appear to belong together, use `selection_groups` to describe the
+most useful review grouping. Infer grouping from titles, paths, excerpts, and
+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.
@@ -27,8 +35,9 @@ The selected work item identities must match the inventory entries:
 
 Return one of these outcomes:
 
-- `selected`: include ordered `work_items`; optionally include
-  `selection_groups` with `title`, optional `kind`, and `work_item_keys`
+- `selected`: include recommended ordered `work_items`; optionally include
+  `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"
     }