@nyxa/nyx-agent 0.2.1 → 0.3.1

package/dist/runtime/validateWorkItem.js

@@ -0,0 +1,212 @@
+import path from "node:path";
+export function validateWorkItemIdentity(input) {
+    const workItems = input.config.work_items;
+    if (!workItems) {
+        return {
+            ok: false,
+            error: "Selected work item requires configured [work_items]"
+        };
+    }
+    if (!isRecord(input.workItem)) {
+        return { ok: false, error: "Selected work item must be an object" };
+    }
+    const source = input.workItem.source;
+    if (!isRecord(source)) {
+        return { ok: false, error: "Selected work item source must be an object" };
+    }
+    const key = input.workItem.key;
+    const sourceType = source.type;
+    const locator = source.locator;
+    if (typeof key !== "string" || key.length === 0) {
+        return { ok: false, error: "Selected work item key must be a non-empty string" };
+    }
+    if (input.seenWorkItemKeys?.includes(key) && key !== input.allowKnownKey) {
+        return {
+            ok: false,
+            error: `Selected work item key "${key}" was already seen in this run`
+        };
+    }
+    if (input.completedWorkItemKeys?.includes(key) &&
+        key !== input.allowKnownKey) {
+        return {
+            ok: false,
+            error: `Selected work item key "${key}" is already completed`
+        };
+    }
+    if (sourceType !== workItems.source) {
+        return {
+            ok: false,
+            error: `Selected work item source.type must be "${workItems.source}"`
+        };
+    }
+    if (typeof locator !== "string" || locator.length === 0) {
+        return {
+            ok: false,
+            error: "Selected work item source.locator must be a non-empty string"
+        };
+    }
+    if (key !== `${workItems.source}:${locator}`) {
+        return {
+            ok: false,
+            error: `Selected work item key must be "${workItems.source}:${locator}"`
+        };
+    }
+    if (workItems.source === "local") {
+        const localValidation = validateLocalLocator(locator, workItems.path);
+        if (!localValidation.ok) {
+            return localValidation;
+        }
+    }
+    else {
+        const githubValidation = validateGitHubLocator(locator, workItems.repository);
+        if (!githubValidation.ok) {
+            return githubValidation;
+        }
+    }
+    if (input.availableWorkItems) {
+        return validateCandidateMembership({
+            key,
+            sourceType,
+            locator,
+            availableWorkItems: input.availableWorkItems
+        });
+    }
+    return { ok: true };
+}
+export function validateWorkItemQueue(input) {
+    if (!Array.isArray(input.workItems)) {
+        return {
+            ok: false,
+            error: "Selected work_items must be an array"
+        };
+    }
+    if (input.workItems.length === 0) {
+        return {
+            ok: false,
+            error: "Selected work_items must contain at least one item"
+        };
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const [index, workItem] of input.workItems.entries()) {
+        const validation = validateWorkItemIdentity({
+            config: input.config,
+            workItem,
+            availableWorkItems: input.availableWorkItems,
+            seenWorkItemKeys: input.seenWorkItemKeys,
+            completedWorkItemKeys: input.completedWorkItemKeys
+        });
+        if (!validation.ok) {
+            return {
+                ok: false,
+                error: `Selected work_items[${index}] ${validation.error}`
+            };
+        }
+        const key = readObjectProperty(workItem, "key");
+        if (typeof key !== "string") {
+            return {
+                ok: false,
+                error: `Selected work_items[${index}] key must be a string`
+            };
+        }
+        if (seen.has(key)) {
+            return {
+                ok: false,
+                error: `Selected work_items contains duplicate key "${key}"`
+            };
+        }
+        seen.add(key);
+        const candidate = input.availableWorkItems?.find((item) => item.key === key);
+        normalized.push(candidate ?? workItem);
+    }
+    return { ok: true, workItems: normalized };
+}
+function validateCandidateMembership(input) {
+    const candidate = input.availableWorkItems.find((item) => item.key === input.key);
+    if (!candidate) {
+        return {
+            ok: false,
+            error: `Selected work item key "${input.key}" is not in available_work_items`
+        };
+    }
+    if (candidate.source.type !== input.sourceType ||
+        candidate.source.locator !== input.locator) {
+        return {
+            ok: false,
+            error: `Selected work item source does not match available_work_items entry "${input.key}"`
+        };
+    }
+    return { ok: true };
+}
+function validateLocalLocator(locator, configuredPath) {
+    const normalizedLocator = normalizeRelativePath(locator);
+    const normalizedPath = configuredPath
+        ? normalizeRelativePath(configuredPath)
+        : undefined;
+    if (!normalizedLocator || normalizedLocator !== locator) {
+        return {
+            ok: false,
+            error: "Local work item locator must be a canonical relative path"
+        };
+    }
+    if (!normalizedPath) {
+        return {
+            ok: false,
+            error: "Local work item validation requires [work_items].path"
+        };
+    }
+    if (normalizedLocator !== normalizedPath &&
+        !normalizedLocator.startsWith(`${normalizedPath}/`)) {
+        return {
+            ok: false,
+            error: `Local work item locator must stay under "${normalizedPath}"`
+        };
+    }
+    return { ok: true };
+}
+function validateGitHubLocator(locator, repository) {
+    if (!repository) {
+        return {
+            ok: false,
+            error: "GitHub work item validation requires [work_items].repository"
+        };
+    }
+    const match = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)$/.exec(locator);
+    if (!match) {
+        return {
+            ok: false,
+            error: 'GitHub work item locator must use "owner/repo#number"'
+        };
+    }
+    if (match[1] !== repository) {
+        return {
+            ok: false,
+            error: `GitHub work item locator must use repository "${repository}"`
+        };
+    }
+    return { ok: true };
+}
+function normalizeRelativePath(value) {
+    if (value.length === 0 ||
+        value.includes("\\") ||
+        path.posix.isAbsolute(value) ||
+        /^[A-Za-z]:[\\/]/.test(value)) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return undefined;
+    }
+    return normalized;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readObjectProperty(value, key) {
+    if (value &&
+        typeof value === "object" &&
+        Object.prototype.hasOwnProperty.call(value, key)) {
+        return value[key];
+    }
+    return undefined;
+}

package/dist/runtime/workItems.js

@@ -0,0 +1,212 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { execa } from "execa";
+export async function listWorkItemCandidates(input) {
+    const workItems = input.config.work_items;
+    if (!workItems) {
+        return [];
+    }
+    if (workItems.source === "local") {
+        if (!workItems.path) {
+            throw new Error('Local work items require [work_items].path');
+        }
+        return listLocalWorkItemCandidates({
+            projectRoot: input.projectRoot,
+            workItemsPath: workItems.path,
+            maxCandidates: workItems.max_candidates,
+            excerptChars: workItems.excerpt_chars
+        });
+    }
+    if (!workItems.repository) {
+        throw new Error('GitHub work items require [work_items].repository');
+    }
+    return listGitHubWorkItemCandidates({
+        repository: workItems.repository,
+        maxCandidates: workItems.max_candidates,
+        excerptChars: workItems.excerpt_chars
+    });
+}
+export function filterAvailableWorkItems(input) {
+    const seen = new Set(input.seenWorkItemKeys);
+    const completed = new Set(input.completedWorkItemKeys);
+    return input.candidates.filter((candidate) => !seen.has(candidate.key) && !completed.has(candidate.key));
+}
+export async function listLocalWorkItemCandidates(input) {
+    const normalizedPath = normalizeProjectRelativePath(input.workItemsPath);
+    if (!normalizedPath) {
+        throw new Error("[work_items].path must be a canonical relative path");
+    }
+    const root = path.resolve(input.projectRoot);
+    const workItemsDir = path.resolve(root, normalizedPath);
+    const relative = path.relative(root, workItemsDir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("[work_items].path must stay inside the project root");
+    }
+    const dirStat = await stat(workItemsDir).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Local work item path does not exist: ${normalizedPath} (${message})`);
+    });
+    if (!dirStat.isDirectory()) {
+        throw new Error(`Local work item path is not a directory: ${normalizedPath}`);
+    }
+    const files = (await collectMarkdownFiles(workItemsDir))
+        .map((filePath) => toPosixPath(path.relative(root, filePath)))
+        .sort((left, right) => left.localeCompare(right));
+    const candidates = [];
+    for (const locator of files.slice(0, input.maxCandidates)) {
+        const absolutePath = path.join(root, locator);
+        const content = await readFile(absolutePath, "utf8");
+        candidates.push({
+            key: `local:${locator}`,
+            title: inferMarkdownTitle(content, locator),
+            source: {
+                type: "local",
+                locator
+            },
+            excerpt: buildExcerpt(content, input.excerptChars)
+        });
+    }
+    return candidates;
+}
+export async function listGitHubWorkItemCandidates(input) {
+    const result = await execa("gh", [
+        "issue",
+        "list",
+        "--repo",
+        input.repository,
+        "--state",
+        "open",
+        "--limit",
+        String(input.maxCandidates),
+        "--json",
+        "number,title,url,labels,updatedAt,body"
+    ], { reject: false });
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout || "unknown error").trim();
+        throw new Error(`Failed to list GitHub work items with gh: ${detail}`);
+    }
+    let issues;
+    try {
+        issues = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse gh issue list JSON: ${message}`);
+    }
+    if (!Array.isArray(issues)) {
+        throw new Error("gh issue list returned JSON that is not an array");
+    }
+    return issues.slice(0, input.maxCandidates).map((issue) => normalizeGitHubIssue({
+        issue,
+        repository: input.repository,
+        excerptChars: input.excerptChars
+    }));
+}
+function normalizeGitHubIssue(input) {
+    if (!isRecord(input.issue)) {
+        throw new Error("gh issue list returned a non-object issue");
+    }
+    const number = input.issue.number;
+    const title = input.issue.title;
+    if (typeof number !== "number" || !Number.isInteger(number) || number <= 0) {
+        throw new Error("GitHub issue is missing a positive integer number");
+    }
+    if (typeof title !== "string" || title.length === 0) {
+        throw new Error(`GitHub issue #${number} is missing a title`);
+    }
+    const locator = `${input.repository}#${number}`;
+    const candidate = {
+        key: `github:${locator}`,
+        title,
+        source: {
+            type: "github",
+            locator
+        },
+        labels: normalizeLabels(input.issue.labels)
+    };
+    if (typeof input.issue.url === "string" && input.issue.url.length > 0) {
+        candidate.url = input.issue.url;
+    }
+    if (typeof input.issue.updatedAt === "string" &&
+        input.issue.updatedAt.length > 0) {
+        candidate.updated_at = input.issue.updatedAt;
+    }
+    if (typeof input.issue.body === "string") {
+        candidate.excerpt = buildExcerpt(input.issue.body, input.excerptChars);
+    }
+    return candidate;
+}
+async function collectMarkdownFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const filePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(filePath)));
+            continue;
+        }
+        if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            files.push(filePath);
+        }
+    }
+    return files;
+}
+function inferMarkdownTitle(content, locator) {
+    const heading = /^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/m.exec(content);
+    if (heading?.[1]) {
+        return heading[1].trim();
+    }
+    return path.posix.basename(locator, ".md");
+}
+function buildExcerpt(content, maxChars) {
+    if (maxChars <= 0) {
+        return undefined;
+    }
+    const compact = content.replace(/\s+/g, " ").trim();
+    if (!compact) {
+        return undefined;
+    }
+    if (compact.length <= maxChars) {
+        return compact;
+    }
+    if (maxChars <= 3) {
+        return compact.slice(0, maxChars);
+    }
+    return `${compact.slice(0, maxChars - 3).trimEnd()}...`;
+}
+function normalizeLabels(labels) {
+    if (!Array.isArray(labels)) {
+        return undefined;
+    }
+    const normalized = labels
+        .map((label) => {
+        if (typeof label === "string") {
+            return label;
+        }
+        if (isRecord(label) && typeof label.name === "string") {
+            return label.name;
+        }
+        return undefined;
+    })
+        .filter((label) => Boolean(label));
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeProjectRelativePath(value) {
+    if (value.length === 0 ||
+        value.includes("\\") ||
+        path.posix.isAbsolute(value) ||
+        /^[A-Za-z]:[\\/]/.test(value)) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return undefined;
+    }
+    return normalized;
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join(path.posix.sep);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/docs/nyxagent-v0-spec.md

@@ -16,7 +16,8 @@ configuration.
 ## Goals
 
 - Install a `.nyxagent/` folder into a project with sensible templates.
-- Run a configurable phase workflow for up to `max_iterations` work items.
+- Select an ordered work-item queue once, then run a configurable phase workflow
+  for up to `max_iterations` confirmed work items.
 - Launch a fresh harness process for each phase.
 - Keep workflow structure generic through phase transitions and outcomes.
 - Keep prompts focused on agent behavior, not runtime mechanics.
@@ -26,7 +27,7 @@ configuration.
 
 ## Non-Goals For v0
 
-- No built-in GitHub, Jira, Linear, or local task tracker adapter.
+- No native classification of work items as plans, PRDs, or tasks.
 - No native Git commit or issue close logic in the engine.
 - No resume command.
 - No fully general DAG/workflow engine.
@@ -62,6 +63,7 @@ If `.nyxagent/` already exists:
 ```text
 .nyxagent/
   config.toml
+  state.json
   prompts/
     selection.md
     execution.md
@@ -113,8 +115,10 @@ max_attempts = 1
 prompt = "prompts/repair-result.md"
 
 [work_items]
-source = "local-markdown"
+source = "local"
 path = "issues"
+max_candidates = 50
+excerpt_chars = 800
 
 [[phases]]
 id = "selection"
@@ -168,15 +172,34 @@ max_visits_per_iteration = 1
 
 ### Config Semantics
 
-- `workflow.max_iterations` is the maximum number of distinct work items in a
-  run.
+- `workflow.max_iterations` is the maximum number of distinct confirmed work
+  items in a run.
 - `phases[*].max_visits_per_iteration` prevents infinite loops inside one work
   item.
 - `model.reasoning_level` is a harness-neutral string.
 - Harness args are declarative and may interpolate config/runtime variables.
 - Per-phase `model` and `harness` blocks override global values.
-- `work_items` is informative in v0. It is injected into runtime context and
-  used by prompts, not scanned by the engine.
+- `work_items` supports only `local` and `github` in v0.
+- `work_items.max_candidates` defaults to `50` and caps the inventory sent to
+  the initial selection prompt.
+- `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.
+- 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.
+- Local keys use `local:<relative-path-under-work-items-path>`.
+- GitHub keys use `github:<owner>/<repo>#<issue-number>` and must match the
+  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.
 
 ## Workflow Model
 
@@ -196,10 +219,12 @@ Reserved next targets:
 The engine does not know about development, review, approval, or closure. It
 only knows phases, outcomes, transitions, and visit limits.
 
-The default template expresses the standard loop:
+The default template expresses the standard run:
 
 ```text
-selection -> execution -> review
+selection -> user confirms queue
+for each confirmed work item:
+  execution -> review
 review.approved -> closure -> next_iteration
 review.changes_requested -> execution
 selection.no_work -> stop_run
@@ -273,6 +298,11 @@ The runtime contract includes:
 - required structured output contract
 - work item context, when selected
 - work item config from `[work_items]`
+- `available_work_items`
+- `selected_work_item_queue`
+- `seen_work_item_keys`
+- `completed_work_item_keys`
+- `last_completed_work_item`
 
 The user prompt remains focused on domain behavior.
 
@@ -284,6 +314,7 @@ Prompts may use simple interpolation:
 {{iteration_dir}}
 {{phase_dir}}
 {{state_file}}
+{{selected_work_item_queue}}
 {{work_item.key}}
 {{work_item.title}}
 {{model.name}}
@@ -300,17 +331,20 @@ Each run creates a timestamped directory:
 .nyxagent/runs/2026-05-23T12-30-00/
   run.json
   state.json
+  selection/
+    state.json
+    phases/
+      selection/
+        attempt-001/
+          prompt.md
+          stdout.log
+          stderr.log
+          meta.json
+        result.json
   iterations/
     001/
       state.json
       phases/
-        selection/
-          attempt-001/
-            prompt.md
-            stdout.log
-            stderr.log
-            meta.json
-          result.json
         execution/
           attempt-001/
             prompt.md
@@ -346,12 +380,28 @@ Each run creates a timestamped directory:
 - run status
 - current iteration
 - completed iterations
+- available work items seen by the initial selection phase
+- selected work item queue confirmed for the run
+- skipped selected work item keys
+- selection groups returned for user review
 - seen work item keys
+- completed work item keys
+- last completed work item
+
+`.nyxagent/state.json` records persistent work item completion state:
+
+- completed work item keys
+- last completed work item
+- minimal completion history
 
 `iterations/NNN/state.json` records per-work-item state:
 
 - iteration number
 - work item
+- selected work item queue for the run
+- seen work item keys
+- completed work item keys
+- last completed work item
 - phase results
 - phase visit counts
 - current phase status
@@ -392,9 +442,14 @@ Default prompts should be concise but operational.
 
 Selection:
 
-- inspect configured work item source
-- choose one work item
-- avoid keys already present in `seen_work_item_keys`
+- choose 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
 - return `selected` or `no_work`
 
 Execution:
@@ -429,17 +484,18 @@ Closure:
 - model name
 - reasoning level
 - max iterations
-- work item source template: `local-markdown`, `github`, or `custom`
+- work item source template: `local` or `github`
 
-For `local-markdown`, init asks for a task path.
+For `local`, init asks for a work item path.
+For `github`, init asks for a repository in `owner/repo` format.
 
 Default path selection:
 
 - use `issues/` if it exists
 - otherwise suggest `.nyxagent/tasks/`
 
-If the chosen local task path does not exist, init may create it and add a
-sample task.
+If the chosen local work item path does not exist, init creates the directory but
+does not create sample work items.
 
 ## Implementation Stack
 
@@ -479,7 +535,7 @@ src/
 
 - `nyxagent resume`
 - `nyxagent import-tasks`
-- tracker adapters for GitHub, Jira, Linear, or local frontmatter tasks
+- additional tracker adapters
 - explicit Git commit adapter
 - stricter artifact redaction
 - richer phase retry policy

package/package.json

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

package/templates/default/prompts/selection.md

@@ -1,19 +1,37 @@
-Select exactly one work item for this iteration.
+Select the ordered work item queue for this run.
 
-Use the work item configuration from the runtime contract. Prefer open,
-well-scoped work that has not already been selected in this run. Avoid any item
-whose key appears in `seen_work_item_keys`.
+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 no suitable work item exists, return `no_work`.
+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`.
+
+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`.
+
+Do not choose any key listed in `seen_work_item_keys` or
+`completed_work_item_keys`. Every selected work item must be copied from
+`available_work_items`; do not invent keys.
+
+The selected work item identities must match the inventory entries:
+
+- local: `source.type` is `local`, `source.locator` is the project-relative
+  markdown path, and `key` is `local:<source.locator>`.
+- github: `source.type` is `github`, `source.locator` is
+  `owner/repo#number` for the configured repository, and `key` is
+  `github:<source.locator>`.
 
 Return one of these outcomes:
 
-- `selected`: include a stable `work_item`
+- `selected`: include ordered `work_items`; optionally include
+  `selection_groups` with `title`, optional `kind`, and `work_item_keys`
 - `no_work`: include a short `reason`
 
-The selected work item must have a stable key. Examples:
-
-- `github:owner/repo#42`
-- `local:issues/TASK-0007.md`
+For compatibility, `work_item` is still accepted for a single selected item, but
+new results should use `work_items`.
 
 Do not modify project files or task files during selection.