@nyxa/nyx-agent 0.9.0 → 0.9.2

package/README.md

@@ -21,9 +21,10 @@ 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); parent PRD/plan issues are closed only when
-NyxAgent can prove the PR completes their remaining open executable children.
-The human merges the PR.
+(`Closes #n` in the PR body); parent PRD/plan issues referenced explicitly from
+child descriptions are grouped for selection, while parent close lines are added
+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,7 +13,7 @@ import { REVIEW_CHALLENGE_SCHEMA, REVIEW_DISCOVERY_SCHEMA, GLOBAL_REVIEW_SCHEMA,
 import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff, } from "./scm.js";
 import { buildSelectionSections, confirmWorkItemSelection, } from "./selectionConfirmation.js";
 import { createRunId } from "./time.js";
-import { filterAvailable, listGitHubWorkItemInventory, resolveSelectedQueue, } from "./workItems.js";
+import { filterAvailable, listGitHubWorkItemInventory, orderWorkItemsByDependencies, resolveSelectedQueue, } from "./workItems.js";
 const MAX_CANDIDATES = 50;
 const EXCERPT_CHARS = 800;
 const CORRECTION_VALIDATION_MAX_ATTEMPTS = 3;
@@ -96,7 +96,14 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         reporter.info("No work items selected. Nothing to do.");
         return;
     }
-    const planned = selected.slice(0, config.max_iterations);
+    const orderedSelection = orderWorkItemsByDependencies(selected);
+    if (orderedSelection.cycleKeys.length > 0) {
+        reporter.detail(`Dependency cycle detected among selected work items; preserving confirmed order inside cycle(s): ${formatDependencyCycles({
+            cycles: orderedSelection.cycleKeys,
+            items: selected,
+        })}`);
+    }
+    const planned = orderedSelection.queue.slice(0, config.max_iterations);
     reporter.info(`Selected ${planned.length} work item(s):`);
     for (const item of planned) {
         reporter.info(`  - ${item.title} (#${item.number})`);
@@ -874,6 +881,7 @@ function workItemSummary(item) {
         url: item.url,
         labels: item.labels,
         parent: item.parent,
+        blocked_by: item.blocked_by,
     };
 }
 function selectionCandidateSummary(candidate) {
@@ -883,6 +891,7 @@ function selectionCandidateSummary(candidate) {
         title: candidate.title,
         labels: candidate.labels,
         parent: candidate.parent,
+        blocked_by: candidate.blocked_by,
         excerpt: candidate.excerpt,
     };
 }
@@ -973,6 +982,17 @@ function completedParentClosures(input) {
 function uniqueNumbers(numbers) {
     return [...new Set(numbers)];
 }
+function formatDependencyCycles(input) {
+    const itemByKey = new Map(input.items.map((item) => [item.key, item]));
+    return input.cycles
+        .map((cycle) => cycle
+        .map((key) => {
+        const item = itemByKey.get(key);
+        return item ? `#${item.number}` : key;
+    })
+        .join(" -> "))
+        .join("; ");
+}
 /** 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

@@ -31,15 +31,49 @@ export async function confirmWorkItemSelection(input) {
     });
 }
 export function buildSelectionChoiceItems(input) {
-    const proposedKeys = new Set(input.proposed.map((item) => item.key));
+    const candidateByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
+    const proposedCandidates = [];
+    const proposedKeys = new Set();
+    for (const proposed of input.proposed) {
+        const candidate = candidateByKey.get(proposed.key);
+        if (!candidate || proposedKeys.has(candidate.key)) {
+            continue;
+        }
+        proposedCandidates.push(candidate);
+        proposedKeys.add(candidate.key);
+    }
+    const remainingCandidates = input.candidates.filter((candidate) => !proposedKeys.has(candidate.key));
     const items = [];
-    for (const section of buildSelectionSections(input.candidates)) {
+    let activeSectionLabel;
+    activeSectionLabel = appendSelectionChoices({
+        items,
+        sections: buildSelectionSections(proposedCandidates),
+        proposedKeys,
+        activeSectionLabel,
+    });
+    appendSelectionChoices({
+        items,
+        sections: buildSelectionSections(remainingCandidates),
+        proposedKeys,
+        activeSectionLabel,
+    });
+    return items;
+}
+function appendSelectionChoices(input) {
+    let activeSectionLabel = input.activeSectionLabel;
+    for (const section of input.sections) {
         if (section.label) {
-            items.push({ type: "separator", label: section.label });
+            if (activeSectionLabel !== section.label) {
+                input.items.push({ type: "separator", label: section.label });
+            }
+            activeSectionLabel = section.label;
+        }
+        else {
+            activeSectionLabel = undefined;
         }
         for (const candidate of section.candidates) {
-            const proposed = proposedKeys.has(candidate.key);
-            items.push({
+            const proposed = input.proposedKeys.has(candidate.key);
+            input.items.push({
                 type: "choice",
                 value: candidate.key,
                 name: `#${candidate.number} ${candidate.title}${proposed ? " (agent)" : ""}`,
@@ -47,7 +81,7 @@ export function buildSelectionChoiceItems(input) {
             });
         }
     }
-    return items;
+    return activeSectionLabel;
 }
 export function buildSelectionSections(candidates) {
     const sections = [];
@@ -105,9 +139,14 @@ function formatParentGroup(parent) {
     if (!parent) {
         return "Parent";
     }
-    return parent.title
-        ? `Parent #${parent.number}: ${parent.title}`
-        : `Parent #${parent.number}`;
+    if (!parent.title) {
+        return `Parent #${parent.number}`;
+    }
+    const titledGroup = parseLeadingTitleGroup(parent.title);
+    if (titledGroup) {
+        return `${titledGroup.kind} #${parent.number}: ${titledGroup.name}`;
+    }
+    return `Parent #${parent.number}: ${parent.title}`;
 }
 function parseGroupLabel(label) {
     const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(label.trim());
@@ -123,6 +162,20 @@ function parseBracketedTitleGroup(title) {
     }
     return formatGroupLabel(match[1], match[2]);
 }
+function parseLeadingTitleGroup(title) {
+    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(title.trim());
+    if (!match) {
+        return undefined;
+    }
+    const name = match[2].trim();
+    if (!name) {
+        return undefined;
+    }
+    return {
+        kind: match[1].toLowerCase() === "prd" ? "PRD" : "Plan",
+        name,
+    };
+}
 function formatGroupLabel(kind, rawName) {
     const name = rawName.trim();
     if (!name) {

package/dist/runtime/workItems.js

@@ -118,11 +118,13 @@ async function listOpenGitHubIssueRecords(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) => normalizeIssueRecord({
+    const records = issues.slice(0, input.maxCandidates).map((issue) => normalizeIssueRecord({
         issue,
         repo: input.repo,
         excerptChars: input.excerptChars,
     }));
+    attachBlockedByDependencies({ records, repo: input.repo });
+    return records;
 }
 export function filterAvailable(input) {
     const completed = new Set(input.completedKeys);
@@ -155,6 +157,79 @@ export function resolveSelectedQueue(input) {
     }
     return { ok: true, queue };
 }
+export function orderWorkItemsByDependencies(queue) {
+    const selectedKeys = new Set(queue.map((item) => item.key));
+    const itemByKey = new Map(queue.map((item) => [item.key, item]));
+    const originalIndex = new Map(queue.map((item, index) => [item.key, index]));
+    const dependenciesByKey = new Map();
+    for (const item of queue) {
+        const seen = new Set();
+        const dependencies = (item.blocked_by ?? [])
+            .map((dependency) => dependency.key)
+            .filter((key) => {
+            if (!selectedKeys.has(key) || seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+        dependenciesByKey.set(item.key, dependencies);
+    }
+    const components = findDependencyComponents({
+        keys: queue.map((item) => item.key),
+        dependenciesByKey,
+    });
+    const componentByKey = new Map();
+    for (const [index, component] of components.entries()) {
+        for (const key of component) {
+            componentByKey.set(key, index);
+        }
+    }
+    const componentDependsOn = new Map();
+    const dependentsByComponent = new Map();
+    for (const [key, dependencies] of dependenciesByKey) {
+        const component = componentByKey.get(key);
+        if (component === undefined) {
+            continue;
+        }
+        for (const dependencyKey of dependencies) {
+            const dependencyComponent = componentByKey.get(dependencyKey);
+            if (dependencyComponent === undefined ||
+                dependencyComponent === component) {
+                continue;
+            }
+            let dependsOn = componentDependsOn.get(component);
+            if (!dependsOn) {
+                dependsOn = new Set();
+                componentDependsOn.set(component, dependsOn);
+            }
+            dependsOn.add(dependencyComponent);
+            let dependents = dependentsByComponent.get(dependencyComponent);
+            if (!dependents) {
+                dependents = new Set();
+                dependentsByComponent.set(dependencyComponent, dependents);
+            }
+            dependents.add(component);
+        }
+    }
+    const orderedComponentIndexes = orderDependencyComponents({
+        components,
+        componentDependsOn,
+        dependentsByComponent,
+        itemByKey,
+        originalIndex,
+    });
+    const ordered = orderedComponentIndexes.flatMap((componentIndex) => sortKeysByOriginalOrder(components[componentIndex], originalIndex).flatMap((key) => {
+        const item = itemByKey.get(key);
+        return item ? [item] : [];
+    }));
+    return {
+        queue: ordered,
+        cycleKeys: components
+            .filter((component) => isCyclicDependencyComponent(component, dependenciesByKey))
+            .map((component) => sortKeysByOriginalOrder(component, originalIndex)),
+    };
+}
 function normalizeIssueRecord(input) {
     if (!isRecord(input.issue)) {
         throw new Error("gh issue list returned a non-object issue");
@@ -216,6 +291,31 @@ function normalizeIssueRecord(input) {
         details,
     };
 }
+function attachBlockedByDependencies(input) {
+    const detailsByKey = new Map(input.records.map((record) => [record.candidate.key, record.details]));
+    for (const record of input.records) {
+        const dependencies = parseBlockedByDependencies({
+            body: record.body,
+            repo: input.repo,
+        }).map((dependency) => {
+            const details = detailsByKey.get(dependency.key);
+            if (!details) {
+                return dependency;
+            }
+            const enriched = { ...dependency };
+            if (details.title) {
+                enriched.title = details.title;
+            }
+            if (details.state) {
+                enriched.state = details.state;
+            }
+            return enriched;
+        });
+        if (dependencies.length > 0) {
+            record.candidate.blocked_by = dependencies;
+        }
+    }
+}
 function buildExcerpt(content, maxChars) {
     if (maxChars <= 0) {
         return undefined;
@@ -376,13 +476,216 @@ function parseExplicitParentReferenceLine(line) {
         .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);
+    const match = new RegExp(`^(?:parent(?:\\s+(?:issue|prd|plan))?|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 parseBlockedByDependencies(input) {
+    if (!input.body) {
+        return [];
+    }
+    const dependencies = [];
+    let blockedBySectionLevel;
+    for (const line of input.body.split(/\r?\n/)) {
+        const heading = parseMarkdownHeading(line);
+        if (heading) {
+            if (blockedBySectionLevel !== undefined &&
+                heading.level <= blockedBySectionLevel) {
+                blockedBySectionLevel = undefined;
+            }
+            if (isBlockedByHeading(heading.title)) {
+                blockedBySectionLevel = heading.level;
+            }
+            continue;
+        }
+        dependencies.push(...parseDirectBlockedByLine({
+            line,
+            repo: input.repo,
+        }));
+        if (blockedBySectionLevel !== undefined) {
+            dependencies.push(...parseBlockedBySectionBullet({
+                line,
+                repo: input.repo,
+            }));
+        }
+    }
+    return dedupeDependencies(dependencies);
+}
+function parseDirectBlockedByLine(input) {
+    const line = normalizeMarkdownLinePrefix(input.line);
+    const match = /^blocked\s+by\s*:\s*(.+)$/i.exec(line);
+    return match
+        ? parseIssueReferences({ text: match[1], repo: input.repo })
+        : [];
+}
+function parseBlockedBySectionBullet(input) {
+    const line = normalizeMarkdownLinePrefix(input.line);
+    const match = /^[-*+]\s+(?:\[[ xX]\]\s+)?(.+)$/.exec(line);
+    return match
+        ? parseIssueReferences({ text: match[1], repo: input.repo })
+        : [];
+}
+function parseIssueReferences(input) {
+    const dependencies = [];
+    const issueRefPattern = /#(\d+)|([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)|https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/(\d+)/gi;
+    for (const match of input.text.matchAll(issueRefPattern)) {
+        const repo = match[2] ??
+            (match[4] && match[5] ? `${match[4]}/${match[5]}` : input.repo);
+        const rawNumber = match[1] ?? match[3] ?? match[6];
+        const number = Number.parseInt(rawNumber, 10);
+        if (!repo || !Number.isInteger(number) || number <= 0) {
+            continue;
+        }
+        const locator = `${repo}#${number}`;
+        dependencies.push({
+            key: `github:${locator}`,
+            number,
+            source: { type: "github", locator },
+        });
+    }
+    return dedupeDependencies(dependencies);
+}
+function parseMarkdownHeading(line) {
+    const match = /^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        level: match[1].length,
+        title: match[2].trim().replace(/[:：]\s*$/, ""),
+    };
+}
+function isBlockedByHeading(title) {
+    return /^blocked\s+by$/i.test(title.trim());
+}
+function normalizeMarkdownLinePrefix(line) {
+    return line.trim().replace(/^>\s+/, "").trim();
+}
+function dedupeDependencies(dependencies) {
+    const byKey = new Map();
+    for (const dependency of dependencies) {
+        byKey.set(dependency.key, dependency);
+    }
+    return [...byKey.values()];
+}
+function findDependencyComponents(input) {
+    const components = [];
+    const indexByKey = new Map();
+    const lowLinkByKey = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let nextIndex = 0;
+    const visit = (key) => {
+        indexByKey.set(key, nextIndex);
+        lowLinkByKey.set(key, nextIndex);
+        nextIndex += 1;
+        stack.push(key);
+        onStack.add(key);
+        for (const dependencyKey of input.dependenciesByKey.get(key) ?? []) {
+            if (!indexByKey.has(dependencyKey)) {
+                visit(dependencyKey);
+                lowLinkByKey.set(key, Math.min(lowLinkByKey.get(key) ?? 0, lowLinkByKey.get(dependencyKey) ?? 0));
+                continue;
+            }
+            if (onStack.has(dependencyKey)) {
+                lowLinkByKey.set(key, Math.min(lowLinkByKey.get(key) ?? 0, indexByKey.get(dependencyKey) ?? 0));
+            }
+        }
+        if (lowLinkByKey.get(key) !== indexByKey.get(key)) {
+            return;
+        }
+        const component = [];
+        let member;
+        do {
+            member = stack.pop();
+            if (!member) {
+                break;
+            }
+            onStack.delete(member);
+            component.push(member);
+        } while (member !== key);
+        components.push(component);
+    };
+    for (const key of input.keys) {
+        if (!indexByKey.has(key)) {
+            visit(key);
+        }
+    }
+    return components;
+}
+function orderDependencyComponents(input) {
+    const indegree = input.components.map((_, index) => input.componentDependsOn.get(index)?.size ?? 0);
+    const available = input.components
+        .map((_, index) => index)
+        .filter((index) => indegree[index] === 0);
+    const ordered = [];
+    while (available.length > 0) {
+        available.sort((a, b) => compareDependencyComponents({
+            a,
+            b,
+            components: input.components,
+            itemByKey: input.itemByKey,
+            originalIndex: input.originalIndex,
+        }));
+        const component = available.shift();
+        if (component === undefined) {
+            break;
+        }
+        ordered.push(component);
+        for (const dependent of input.dependentsByComponent.get(component) ?? []) {
+            indegree[dependent] -= 1;
+            if (indegree[dependent] === 0) {
+                available.push(dependent);
+            }
+        }
+    }
+    if (ordered.length === input.components.length) {
+        return ordered;
+    }
+    const orderedSet = new Set(ordered);
+    return [
+        ...ordered,
+        ...input.components
+            .map((_, index) => index)
+            .filter((index) => !orderedSet.has(index))
+            .sort((a, b) => compareDependencyComponents({
+            a,
+            b,
+            components: input.components,
+            itemByKey: input.itemByKey,
+            originalIndex: input.originalIndex,
+        })),
+    ];
+}
+function compareDependencyComponents(input) {
+    const aIndex = minOriginalIndex(input.components[input.a], input.originalIndex);
+    const bIndex = minOriginalIndex(input.components[input.b], input.originalIndex);
+    if (aIndex !== bIndex) {
+        return aIndex - bIndex;
+    }
+    return (minIssueNumber(input.components[input.a], input.itemByKey) -
+        minIssueNumber(input.components[input.b], input.itemByKey));
+}
+function minOriginalIndex(keys, originalIndex) {
+    return Math.min(...keys.map((key) => originalIndex.get(key) ?? Number.MAX_SAFE_INTEGER));
+}
+function minIssueNumber(keys, itemByKey) {
+    return Math.min(...keys.map((key) => itemByKey.get(key)?.number ?? Number.MAX_SAFE_INTEGER));
+}
+function sortKeysByOriginalOrder(keys, originalIndex) {
+    return [...keys].sort((a, b) => (originalIndex.get(a) ?? Number.MAX_SAFE_INTEGER) -
+        (originalIndex.get(b) ?? Number.MAX_SAFE_INTEGER));
+}
+function isCyclicDependencyComponent(component, dependenciesByKey) {
+    if (component.length > 1) {
+        return true;
+    }
+    const key = component[0];
+    return (dependenciesByKey.get(key) ?? []).includes(key);
+}
 function parseGitHubRepo(repo) {
     const [owner, repoName, ...rest] = repo.split("/");
     if (!owner || !repoName || rest.length > 0) {

package/package.json

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