@nyxa/nyx-agent 0.8.0 → 0.8.1

package/README.md

@@ -7,8 +7,9 @@ GitHub issue at a time, each phase with fresh context.
 
 For every run NyxAgent:
 
-1. **Selects** open GitHub issues to work on (read-only), then asks the user to
-   confirm the proposed checklist.
+1. **Selects** executable open GitHub issues to work on (read-only), grouping
+   GitHub sub-issues under non-executable parent PRD/plan issues, then asks the
+   user to confirm the proposed checklist.
 2. For each selected issue, in an isolated git **worktree**:
    - **implements** it (the agent — the only customizable prompt),
    - optionally **reviews** it in bounded discovery rounds, then revises only
@@ -20,7 +21,9 @@ For every run NyxAgent:
 The agent only implements, reviews, and revises. Every git/gh side effect —
 commit, push, pull request — is performed by the engine, so closing the loop
 never depends on the model. Issues are closed by GitHub when the PR merges
-(`Closes #n` in the PR body); the human merges the PR.
+(`Closes #n` in the PR body); parent PRD/plan issues are closed only when
+NyxAgent can prove the PR completes their remaining open executable children.
+The human merges the PR.
 
 The workflow shape is fixed (not configurable). Only `.nyxagent/prompts/execution.md`
 is editable.

package/dist/runtime/runPipeline.js

@@ -13,13 +13,13 @@ import { REVIEW_CHALLENGE_SCHEMA, REVIEW_DISCOVERY_SCHEMA, GLOBAL_REVIEW_SCHEMA,
 import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff, } from "./scm.js";
 import { confirmWorkItemSelection, } from "./selectionConfirmation.js";
 import { createRunId } from "./time.js";
-import { filterAvailable, listGitHubIssues, resolveSelectedQueue, } from "./workItems.js";
+import { filterAvailable, listGitHubWorkItemInventory, resolveSelectedQueue, } from "./workItems.js";
 const MAX_CANDIDATES = 50;
 const EXCERPT_CHARS = 800;
 const CORRECTION_VALIDATION_MAX_ATTEMPTS = 3;
 export function defaultPipelineDependencies() {
     return {
-        listIssues: listGitHubIssues,
+        listIssues: listGitHubWorkItemInventory,
         runPhase: runAgentPhase,
         pushBranch,
         createPullRequest,
@@ -59,12 +59,13 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
     const ledger = await readWorkItemLedger(nyxDir);
     reporter.detail(`Completed work items already in ledger: ${ledger.completed_work_item_keys.length}`);
     // 1. Selection runs read-only in the main checkout, before any branch exists.
+    const inventory = normalizeWorkItemInventory(await deps.listIssues({
+        repo: config.tracker.repo,
+        maxCandidates: MAX_CANDIDATES,
+        excerptChars: EXCERPT_CHARS,
+    }));
     const candidates = filterAvailable({
-        candidates: await deps.listIssues({
-            repo: config.tracker.repo,
-            maxCandidates: MAX_CANDIDATES,
-            excerptChars: EXCERPT_CHARS,
-        }),
+        candidates: inventory.candidates,
         completedKeys: ledger.completed_work_item_keys,
     });
     reporter.detail(`Available work item candidates: ${candidates.length}`);
@@ -187,7 +188,10 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             base: git.base,
             head: git.branch,
             title: buildPrTitle(completed),
-            body: buildPrBody(completed),
+            body: buildPrBody({
+                items: completed,
+                parents: inventory.parents,
+            }),
         });
         reporter.success(`\nPull request opened: ${prUrl}`);
         success = true;
@@ -203,6 +207,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             producedCommits,
             completed,
             config,
+            parents: inventory.parents,
             deps,
             reporter,
         });
@@ -252,7 +257,11 @@ async function salvageFailedRun(input) {
             base: input.git.base,
             head: input.git.branch,
             title: buildDraftPrTitle(input.completed),
-            body: buildDraftPrBody(input.completed, reason),
+            body: buildDraftPrBody({
+                items: input.completed,
+                parents: input.parents,
+                reason,
+            }),
             draft: true,
         });
         input.reporter.warn(`\nRun failed, but the work was salvaged into a DRAFT pull request: ${url}`);
@@ -281,6 +290,7 @@ async function runSelection(input) {
                 number: candidate.number,
                 title: candidate.title,
                 labels: candidate.labels,
+                parent: candidate.parent,
                 excerpt: candidate.excerpt,
             })),
         ],
@@ -867,6 +877,7 @@ function workItemSummary(item) {
         locator: item.source.locator,
         url: item.url,
         labels: item.labels,
+        parent: item.parent,
     };
 }
 function buildCommitMessage(item) {
@@ -878,35 +889,84 @@ function buildPrTitle(items) {
     }
     return `NyxAgent: ${items.length} work items`;
 }
-function buildPrBody(items) {
-    const list = items
+function normalizeWorkItemInventory(result) {
+    if (Array.isArray(result)) {
+        return { candidates: result, parents: [] };
+    }
+    return {
+        candidates: result.candidates,
+        parents: result.parents ?? [],
+    };
+}
+function buildPrBody(input) {
+    const list = input.items
         .map((item) => `- ${item.title} (#${item.number})`)
         .join("\n");
-    const closes = items.map((item) => `Closes #${item.number}`).join("\n");
-    return [
+    const completedParents = completedParentClosures(input);
+    const closeNumbers = [
+        ...uniqueNumbers(input.items.map((item) => item.number)),
+        ...uniqueNumbers(completedParents.map((parent) => parent.number)),
+    ];
+    const closes = closeNumbers.map((number) => `Closes #${number}`).join("\n");
+    const sections = [
         "Automated changes by NyxAgent.",
         "",
         "## Work items",
         "",
         list,
-        "",
-        closes,
-    ].join("\n");
+    ];
+    if (completedParents.length > 0) {
+        sections.push("", "## Completed plans", "", completedParents
+            .map((parent) => `- ${parent.title ?? `Parent issue ${parent.number}`} (#${parent.number})`)
+            .join("\n"));
+    }
+    sections.push("", closes);
+    return sections.join("\n");
 }
 function buildDraftPrTitle(items) {
     return `[Draft] ${buildPrTitle(items)}`;
 }
-function buildDraftPrBody(items, reason) {
+function buildDraftPrBody(input) {
     return [
         "> [!WARNING]",
         "> This pull request was opened automatically by NyxAgent after the run",
         "> **failed review**. The work is preserved here for a human to finish.",
         "",
-        `**Why the run failed:** ${reason}`,
+        `**Why the run failed:** ${input.reason}`,
         "",
-        buildPrBody(items),
+        buildPrBody({
+            items: input.items,
+            parents: input.parents,
+        }),
     ].join("\n");
 }
+function completedParentClosures(input) {
+    const completedKeys = new Set(input.items.map((item) => item.key));
+    const completedParentKeys = new Set(input.items
+        .map((item) => item.parent?.key)
+        .filter((key) => Boolean(key)));
+    const completedParents = [];
+    for (const parent of input.parents ?? []) {
+        if (!parent.closable || !completedParentKeys.has(parent.key)) {
+            continue;
+        }
+        const openChildren = parent.children.filter((child) => child.state !== "closed");
+        const openContainerChild = openChildren.some((child) => !child.executable);
+        if (openContainerChild) {
+            continue;
+        }
+        const completedChildInThisPr = parent.children.some((child) => completedKeys.has(child.key));
+        if (!completedChildInThisPr ||
+            openChildren.some((child) => !completedKeys.has(child.key))) {
+            continue;
+        }
+        completedParents.push(parent);
+    }
+    return completedParents;
+}
+function uniqueNumbers(numbers) {
+    return [...new Set(numbers)];
+}
 /** Render unresolved blockers as a bullet list to append to a failure message. */
 function formatBlockers(blockers) {
     if (blockers.length === 0) {

package/dist/runtime/selectionConfirmation.js

@@ -16,8 +16,8 @@ export async function confirmWorkItemSelection(input) {
             `Select at most ${input.maxItems} work item(s).`,
         shortcuts: {
             all: null,
-            invert: null
-        }
+            invert: null,
+        },
     });
     const selected = new Set(selectedKeys);
     return input.candidates.filter((candidate) => selected.has(candidate.key));
@@ -37,7 +37,7 @@ export function buildSelectionChoiceItems(input) {
             type: "choice",
             value: candidate.key,
             name: `#${candidate.number} ${candidate.title}${proposed ? " (agent)" : ""}`,
-            checked: proposed
+            checked: proposed,
         });
     }
     return items;
@@ -49,10 +49,13 @@ function toInquirerChoice(item) {
     return {
         value: item.value,
         name: item.name,
-        checked: item.checked
+        checked: item.checked,
     };
 }
 function detectPlanGroup(candidate) {
+    if (candidate.parent) {
+        return formatParentGroup(candidate.parent);
+    }
     for (const label of candidate.labels ?? []) {
         const group = parseGroupLabel(label);
         if (group) {
@@ -61,6 +64,14 @@ function detectPlanGroup(candidate) {
     }
     return parseBracketedTitleGroup(candidate.title);
 }
+function formatParentGroup(parent) {
+    if (!parent) {
+        return "Parent";
+    }
+    return parent.title
+        ? `Parent #${parent.number}: ${parent.title}`
+        : `Parent #${parent.number}`;
+}
 function parseGroupLabel(label) {
     const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(label.trim());
     if (!match) {

package/dist/runtime/workItems.js

@@ -1,6 +1,96 @@
 /** Work items: lists GitHub issues via `gh`, normalizes them to candidates, and resolves the selected queue. */
 import { execa } from "execa";
 export async function listGitHubIssues(input) {
+    const records = await listOpenGitHubIssueRecords(input);
+    return records.map((record) => record.candidate);
+}
+export async function listGitHubWorkItemInventory(input) {
+    const records = await listOpenGitHubIssueRecords(input);
+    const issueByNumber = new Map(records.map((record) => [record.number, record]));
+    const nativeParentNumberByChild = new Map();
+    const explicitParentNumberByChild = new Map();
+    const parentDetails = new Map();
+    const subIssueResults = new Map();
+    const repoParts = parseGitHubRepo(input.repo);
+    for (const record of records) {
+        const parent = await getGitHubParentIssue({
+            ...repoParts,
+            issueNumber: record.number,
+        });
+        if (parent) {
+            nativeParentNumberByChild.set(record.number, parent.number);
+            parentDetails.set(parent.number, parent);
+        }
+    }
+    const numbersToInspectForSubIssues = new Set([
+        ...records.map((record) => record.number),
+        ...nativeParentNumberByChild.values(),
+    ]);
+    for (const issueNumber of numbersToInspectForSubIssues) {
+        const result = await listGitHubSubIssues({
+            ...repoParts,
+            issueNumber,
+        });
+        subIssueResults.set(issueNumber, result);
+        if (result.ok && result.issues.length > 0) {
+            const existing = issueByNumber.get(issueNumber);
+            if (existing) {
+                parentDetails.set(issueNumber, existing.details);
+            }
+        }
+    }
+    for (const record of records) {
+        if (nativeParentNumberByChild.has(record.number)) {
+            continue;
+        }
+        const explicitParent = parseExplicitParentReference(record);
+        if (explicitParent && explicitParent !== record.number) {
+            explicitParentNumberByChild.set(record.number, explicitParent);
+            const parentRecord = issueByNumber.get(explicitParent);
+            if (parentRecord) {
+                parentDetails.set(explicitParent, parentRecord.details);
+            }
+        }
+    }
+    const parentNumbers = new Set([
+        ...nativeParentNumberByChild.values(),
+        ...explicitParentNumberByChild.values(),
+    ]);
+    for (const [issueNumber, result] of subIssueResults) {
+        if (result.ok && result.issues.length > 0) {
+            parentNumbers.add(issueNumber);
+        }
+    }
+    const parentInventory = buildParentInventory({
+        repo: input.repo,
+        records,
+        parentNumbers,
+        nativeParentNumberByChild,
+        explicitParentNumberByChild,
+        parentDetails,
+        subIssueResults,
+    });
+    const parentByNumber = new Map(parentInventory.map((parent) => [parent.number, toCandidateParent(parent)]));
+    const candidates = records
+        .filter((record) => !parentNumbers.has(record.number))
+        .map((record) => {
+        const candidate = { ...record.candidate };
+        const parentNumber = nativeParentNumberByChild.get(record.number) ??
+            explicitParentNumberByChild.get(record.number);
+        const parent = parentNumber
+            ? parentByNumber.get(parentNumber)
+            : undefined;
+        if (parent) {
+            candidate.parent = parent;
+        }
+        return candidate;
+    });
+    return {
+        candidates,
+        parents: parentInventory,
+    };
+}
+async function listOpenGitHubIssueRecords(input) {
     const result = await execa("gh", [
         "issue",
         "list",
@@ -11,7 +101,7 @@ export async function listGitHubIssues(input) {
         "--limit",
         String(input.maxCandidates),
         "--json",
-        "number,title,url,labels,updatedAt,body"
+        "number,title,url,labels,updatedAt,body,state",
     ], { reject: false });
     if (result.exitCode !== 0) {
         const detail = (result.stderr || result.stdout || "unknown error").trim();
@@ -28,12 +118,10 @@ export async function listGitHubIssues(input) {
     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) => normalizeIssue({
+    return issues.slice(0, input.maxCandidates).map((issue) => normalizeIssueRecord({
         issue,
         repo: input.repo,
-        excerptChars: input.excerptChars
+        excerptChars: input.excerptChars,
     }));
 }
 export function filterAvailable(input) {
@@ -59,7 +147,7 @@ export function resolveSelectedQueue(input) {
         if (!candidate) {
             return {
                 ok: false,
-                error: `selection key "${key}" is not an available candidate`
+                error: `selection key "${key}" is not an available candidate`,
             };
         }
         seen.add(key);
@@ -67,7 +155,7 @@ export function resolveSelectedQueue(input) {
     }
     return { ok: true, queue };
 }
-function normalizeIssue(input) {
+function normalizeIssueRecord(input) {
     if (!isRecord(input.issue)) {
         throw new Error("gh issue list returned a non-object issue");
     }
@@ -80,24 +168,53 @@ function normalizeIssue(input) {
         throw new Error(`GitHub issue #${number} is missing a title`);
     }
     const locator = `${input.repo}#${number}`;
+    const labels = normalizeLabels(input.issue.labels);
     const candidate = {
         key: `github:${locator}`,
         title,
         number,
         source: { type: "github", locator },
-        labels: normalizeLabels(input.issue.labels)
+        labels,
     };
-    if (typeof input.issue.url === "string" && input.issue.url.length > 0) {
-        candidate.url = input.issue.url;
+    const url = typeof input.issue.url === "string"
+        ? input.issue.url
+        : typeof input.issue.html_url === "string"
+            ? input.issue.html_url
+            : undefined;
+    if (url && url.length > 0) {
+        candidate.url = url;
     }
-    if (typeof input.issue.updatedAt === "string" &&
-        input.issue.updatedAt.length > 0) {
-        candidate.updated_at = input.issue.updatedAt;
+    const updatedAt = typeof input.issue.updatedAt === "string"
+        ? input.issue.updatedAt
+        : typeof input.issue.updated_at === "string"
+            ? input.issue.updated_at
+            : undefined;
+    if (updatedAt && updatedAt.length > 0) {
+        candidate.updated_at = updatedAt;
     }
+    let body;
     if (typeof input.issue.body === "string") {
-        candidate.excerpt = buildExcerpt(input.issue.body, input.excerptChars);
+        body = input.issue.body;
+        candidate.excerpt = buildExcerpt(body, input.excerptChars);
     }
-    return candidate;
+    const state = typeof input.issue.state === "string" ? input.issue.state : undefined;
+    const details = {
+        number,
+        title,
+        state,
+    };
+    if (typeof input.issue.id === "number" && Number.isInteger(input.issue.id)) {
+        details.id = input.issue.id;
+    }
+    return {
+        number,
+        title,
+        body,
+        state,
+        labels,
+        candidate,
+        details,
+    };
 }
 function buildExcerpt(content, maxChars) {
     if (maxChars <= 0) {
@@ -132,6 +249,223 @@ function normalizeLabels(labels) {
         .filter((label) => Boolean(label));
     return normalized.length > 0 ? normalized : undefined;
 }
+function buildParentInventory(input) {
+    const parentNumbers = new Set([
+        ...input.parentNumbers,
+        ...input.nativeParentNumberByChild.values(),
+        ...input.explicitParentNumberByChild.values(),
+    ]);
+    const recordsByNumber = new Map(input.records.map((record) => [record.number, record]));
+    const parents = [];
+    for (const parentNumber of [...parentNumbers].sort((a, b) => a - b)) {
+        const nativeChildren = input.records
+            .filter((record) => input.nativeParentNumberByChild.get(record.number) === parentNumber)
+            .map((record) => issueDetailsToParentChild({
+            repo: input.repo,
+            issue: record.details,
+            parentNumbers,
+        }));
+        const explicitChildren = input.records
+            .filter((record) => input.explicitParentNumberByChild.get(record.number) === parentNumber)
+            .map((record) => issueDetailsToParentChild({
+            repo: input.repo,
+            issue: record.details,
+            parentNumbers,
+        }));
+        const subIssueResult = input.subIssueResults.get(parentNumber);
+        const children = subIssueResult?.ok && subIssueResult.issues.length > 0
+            ? subIssueResult.issues.map((issue) => issueDetailsToParentChild({
+                repo: input.repo,
+                issue,
+                parentNumbers,
+            }))
+            : [...nativeChildren, ...explicitChildren];
+        const relationship = nativeChildren.length > 0 ||
+            (subIssueResult?.ok && subIssueResult.issues.length > 0)
+            ? "github-sub-issue"
+            : "explicit-ref";
+        const parentDetail = input.parentDetails.get(parentNumber) ??
+            recordsByNumber.get(parentNumber)?.details;
+        const parentState = parentDetail?.state;
+        const closable = relationship === "github-sub-issue" &&
+            subIssueResult?.ok === true &&
+            subIssueResult.issues.length > 0 &&
+            parentState === "open";
+        parents.push({
+            ...buildParentMetadata({
+                repo: input.repo,
+                number: parentNumber,
+                title: parentDetail?.title,
+                relationship,
+                closable,
+            }),
+            state: parentState,
+            children: dedupeParentChildren(children),
+        });
+    }
+    return parents;
+}
+function buildParentMetadata(input) {
+    const locator = `${input.repo}#${input.number}`;
+    const parent = {
+        key: `github:${locator}`,
+        number: input.number,
+        source: { type: "github", locator },
+        relationship: input.relationship,
+        closable: input.closable,
+    };
+    if (input.title) {
+        parent.title = input.title;
+    }
+    return parent;
+}
+function toCandidateParent(parent) {
+    const candidateParent = {
+        key: parent.key,
+        number: parent.number,
+        source: parent.source,
+        relationship: parent.relationship,
+        closable: parent.closable,
+    };
+    if (parent.title) {
+        candidateParent.title = parent.title;
+    }
+    return candidateParent;
+}
+function issueDetailsToParentChild(input) {
+    const locator = `${input.repo}#${input.issue.number}`;
+    const child = {
+        key: `github:${locator}`,
+        number: input.issue.number,
+        executable: !input.parentNumbers.has(input.issue.number),
+    };
+    if (input.issue.title) {
+        child.title = input.issue.title;
+    }
+    if (input.issue.state) {
+        child.state = input.issue.state;
+    }
+    return child;
+}
+function dedupeParentChildren(children) {
+    const byNumber = new Map();
+    for (const child of children) {
+        byNumber.set(child.number, child);
+    }
+    return [...byNumber.values()].sort((a, b) => a.number - b.number);
+}
+function parseExplicitParentReference(record) {
+    const refs = new Set();
+    for (const label of record.labels ?? []) {
+        const ref = parseExplicitParentReferenceLine(label);
+        if (ref) {
+            refs.add(ref);
+        }
+    }
+    for (const line of record.body?.split(/\r?\n/) ?? []) {
+        const ref = parseExplicitParentReferenceLine(line);
+        if (ref) {
+            refs.add(ref);
+        }
+    }
+    return refs.size === 1 ? [...refs][0] : undefined;
+}
+function parseExplicitParentReferenceLine(line) {
+    const trimmed = line
+        .trim()
+        .replace(/^[-*]\s+/, "")
+        .replace(/^>\s+/, "");
+    const issueRef = "(?:#|[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#|https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/issues/)(\\d+)";
+    const match = new RegExp(`^(?:parent(?:\\s+issue)?|prd|plan)\\s*(?::|=|-)?\\s*${issueRef}\\s*$`, "i").exec(trimmed);
+    if (!match) {
+        return undefined;
+    }
+    const number = Number.parseInt(match[1], 10);
+    return Number.isInteger(number) && number > 0 ? number : undefined;
+}
+function parseGitHubRepo(repo) {
+    const [owner, repoName, ...rest] = repo.split("/");
+    if (!owner || !repoName || rest.length > 0) {
+        throw new Error(`GitHub repo must be in owner/repo form: ${repo}`);
+    }
+    return { owner, repoName };
+}
+async function getGitHubParentIssue(input) {
+    const result = await ghApi([
+        `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}/parent`,
+    ]);
+    if (!result.ok || result.value === undefined) {
+        return undefined;
+    }
+    return normalizeGitHubIssueDetails(result.value);
+}
+async function listGitHubSubIssues(input) {
+    const result = await ghApi([
+        `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}/sub_issues?per_page=100`,
+    ]);
+    if (!result.ok) {
+        return { ok: false, issues: [] };
+    }
+    if (result.value === undefined) {
+        return { ok: true, issues: [] };
+    }
+    if (!Array.isArray(result.value)) {
+        return { ok: false, issues: [] };
+    }
+    return {
+        ok: true,
+        issues: result.value
+            .map((issue) => normalizeGitHubIssueDetails(issue))
+            .filter((issue) => Boolean(issue)),
+    };
+}
+async function ghApi(args) {
+    const result = await execa("gh", [
+        "api",
+        "-H",
+        "Accept: application/vnd.github+json",
+        "-H",
+        "X-GitHub-Api-Version: 2026-03-10",
+        ...args,
+    ], { reject: false });
+    if (result.exitCode !== 0) {
+        return isMissingGitHubRelation(result.stderr || result.stdout)
+            ? { ok: true, value: undefined }
+            : { ok: false };
+    }
+    if (result.stdout.trim().length === 0) {
+        return { ok: true, value: undefined };
+    }
+    try {
+        return { ok: true, value: JSON.parse(result.stdout) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function normalizeGitHubIssueDetails(issue) {
+    if (!isRecord(issue)) {
+        return undefined;
+    }
+    const number = issue.number;
+    if (typeof number !== "number" || !Number.isInteger(number) || number <= 0) {
+        return undefined;
+    }
+    const details = { number };
+    if (typeof issue.title === "string" && issue.title.length > 0) {
+        details.title = issue.title;
+    }
+    if (typeof issue.state === "string" && issue.state.length > 0) {
+        details.state = issue.state;
+    }
+    if (typeof issue.id === "number" && Number.isInteger(issue.id)) {
+        details.id = issue.id;
+    }
+    return details;
+}
+function isMissingGitHubRelation(output) {
+    return /HTTP\s+(404|410)\b|not found|gone/i.test(output);
+}
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }

package/package.json

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