@nyxa/nyx-agent 0.9.2 → 0.9.3

package/dist/runtime/prompts.js

@@ -6,15 +6,17 @@
  * prompt is pure guidance — NyxAgent prepends an engine-owned context block and,
  * for review-style phases, appends the required-result contract + JSON Schema.
  */
-export const SELECTION_PROMPT = `Select and order the GitHub issues to work on in this run.
+export const SELECTION_PROMPT = `Select the GitHub issue series to work on in this run.
 
-The available open issues (candidates) are listed in the context above. Choose the
-ones that form a coherent unit of work for this run and order them so prerequisites
-come first. You may select a subset; skip issues that are unclear, blocked, or out
-of scope. Do not invent keys — only use keys present in the candidates.
+The context lists recommended executable series, blockers, and available open
+issues by PRD/Plan section. Choose the coherent series or issue set that should be
+started now. Prefer the recommended executable order when it matches the intent.
+Skip issues with open blockers. Closed blockers are satisfied. Do not invent keys
+— only use keys present in the candidates.
 
-Return outcome "selected" with the ordered keys in a work_item_keys array. If
-nothing is worth working on, return outcome "no_work" instead.`;
+Return outcome "selected" with the chosen intent keys in a work_item_keys array;
+the engine will expand PRD/Plan series and prerequisites safely. If nothing is
+worth working on, return outcome "no_work" instead.`;
 export const EXECUTION_PROMPT = `Implement the selected work item described in the context above.
 
 Work only on this item. Keep changes focused and coherent. Use a

package/dist/runtime/runPipeline.js

@@ -11,9 +11,10 @@ import { createRunReporter } from "./reporter.js";
 import { runAgentPhase, } from "./runPhase.js";
 import { REVIEW_CHALLENGE_SCHEMA, REVIEW_DISCOVERY_SCHEMA, GLOBAL_REVIEW_SCHEMA, REVIEW_VALIDATION_SCHEMA, SELECTION_SCHEMA, } from "./schemas.js";
 import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff, } from "./scm.js";
-import { buildSelectionSections, confirmWorkItemSelection, } from "./selectionConfirmation.js";
+import { confirmWorkItemSelection, } from "./selectionConfirmation.js";
+import { buildWorkItemSelectionPlan, formatSelectionBlockers, isDependencySatisfied, normalizeWorkItemSelection, } from "./selectionPlanner.js";
 import { createRunId } from "./time.js";
-import { filterAvailable, listGitHubWorkItemInventory, orderWorkItemsByDependencies, 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;
@@ -73,12 +74,18 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         reporter.info("No open work items available. Nothing to do.");
         return;
     }
+    const selectionPlan = buildWorkItemSelectionPlan({
+        candidates,
+        maxItems: config.max_iterations,
+        completedKeys: ledger.completed_work_item_keys,
+    });
     const proposed = await runSelection({
         projectRoot,
         runDir,
         cliHarness: input.harness,
         config,
         candidates,
+        completedKeys: ledger.completed_work_item_keys,
         runPhase: deps.runPhase,
         reporter,
     });
@@ -87,7 +94,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         return;
     }
     const selected = await deps.confirmSelection({
-        candidates,
+        candidates: selectionPlan.candidateOrder,
         proposed,
         maxItems: config.max_iterations,
         autoAccept: input.autoAcceptSelection ?? false,
@@ -96,14 +103,31 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         reporter.info("No work items selected. Nothing to do.");
         return;
     }
-    const orderedSelection = orderWorkItemsByDependencies(selected);
-    if (orderedSelection.cycleKeys.length > 0) {
+    const finalSelection = normalizeWorkItemSelection({
+        candidates,
+        selected,
+        maxItems: config.max_iterations,
+        expandGroups: false,
+        strictMax: true,
+        completedKeys: ledger.completed_work_item_keys,
+    });
+    if (!finalSelection.ok) {
+        throw new Error(finalSelection.error);
+    }
+    if (finalSelection.blockedCandidates.length > 0) {
+        reporter.warn(`Skipping blocked work item(s): ${formatSelectionBlockers(finalSelection.blockedCandidates)}`);
+    }
+    if (finalSelection.queue.length === 0) {
+        reporter.info("No executable work items selected. Nothing to do.");
+        return;
+    }
+    if (finalSelection.cycleKeys.length > 0) {
         reporter.detail(`Dependency cycle detected among selected work items; preserving confirmed order inside cycle(s): ${formatDependencyCycles({
-            cycles: orderedSelection.cycleKeys,
+            cycles: finalSelection.cycleKeys,
             items: selected,
         })}`);
     }
-    const planned = orderedSelection.queue.slice(0, config.max_iterations);
+    const planned = finalSelection.queue;
     reporter.info(`Selected ${planned.length} work item(s):`);
     for (const item of planned) {
         reporter.info(`  - ${item.title} (#${item.number})`);
@@ -287,14 +311,30 @@ async function runSelection(input) {
         config: input.config,
         cliHarness: input.cliHarness,
     });
+    const selectionPlan = buildWorkItemSelectionPlan({
+        candidates: input.candidates,
+        maxItems: input.config.max_iterations,
+        completedKeys: input.completedKeys,
+    });
+    const candidateKeys = new Set(input.candidates.map((candidate) => candidate.key));
+    const completedKeys = new Set(input.completedKeys);
     const context = buildContextBlock([
         ["Repository", input.config.tracker.repo],
         ["Max work items this run", input.config.max_iterations],
+        [
+            "Recommended executable series",
+            selectionPlan.recommendedSeries.map(selectionSeriesSummary),
+        ],
+        [
+            "Blocked candidates",
+            selectionPlan.blockedCandidates.map(selectionBlockerSummary),
+        ],
         [
             "Available candidates",
-            buildSelectionSections(input.candidates).map((section) => ({
+            selectionPlan.sections.map((section) => ({
                 section: section.label ?? "Ungrouped issues",
-                candidates: section.candidates.map(selectionCandidateSummary),
+                recommended_order: section.recommended.map(workItemReference),
+                candidates: section.candidates.map((candidate) => selectionCandidateSummary(candidate, candidateKeys, completedKeys)),
             })),
         ],
     ]);
@@ -328,7 +368,23 @@ async function runSelection(input) {
     if (!resolved.ok) {
         throw new Error(`Selection produced an invalid queue: ${resolved.error}`);
     }
-    return resolved.queue;
+    const normalized = normalizeWorkItemSelection({
+        candidates: input.candidates,
+        selected: resolved.queue,
+        maxItems: input.config.max_iterations,
+        expandGroups: true,
+        completedKeys: input.completedKeys,
+    });
+    if (!normalized.ok) {
+        throw new Error(normalized.error);
+    }
+    if (normalized.blockedCandidates.length > 0) {
+        input.reporter.detail(`Selection omitted blocked work item(s): ${formatSelectionBlockers(normalized.blockedCandidates)}`);
+    }
+    if (normalized.truncated) {
+        input.reporter.detail(`Selection truncated to ${input.config.max_iterations} work item(s) after dependency planning.`);
+    }
+    return normalized.queue;
 }
 async function runExecution(input) {
     const agent = resolveAgentProfile({
@@ -884,7 +940,22 @@ function workItemSummary(item) {
         blocked_by: item.blocked_by,
     };
 }
-function selectionCandidateSummary(candidate) {
+function selectionSeriesSummary(series) {
+    return {
+        section: series.section ?? "Ungrouped issues",
+        work_item_keys: series.candidates.map((candidate) => candidate.key),
+        order: series.candidates.map(workItemReference),
+        blocked: series.blocked.map(selectionBlockerSummary),
+        truncated: series.truncated,
+    };
+}
+function selectionBlockerSummary(blocked) {
+    return {
+        candidate: workItemReference(blocked.candidate),
+        blockers: blocked.blockers.map(dependencyReference),
+    };
+}
+function selectionCandidateSummary(candidate, candidateKeys, completedKeys) {
     return {
         key: candidate.key,
         number: candidate.number,
@@ -892,9 +963,50 @@ function selectionCandidateSummary(candidate) {
         labels: candidate.labels,
         parent: candidate.parent,
         blocked_by: candidate.blocked_by,
+        dependency_status: dependencyStatusSummary({
+            dependencies: candidate.blocked_by ?? [],
+            candidateKeys,
+            completedKeys,
+        }),
         excerpt: candidate.excerpt,
     };
 }
+function dependencyStatusSummary(input) {
+    const selectablePrerequisites = [];
+    const satisfiedBlockers = [];
+    const openBlockers = [];
+    for (const dependency of input.dependencies) {
+        if (input.candidateKeys.has(dependency.key)) {
+            selectablePrerequisites.push(dependency);
+            continue;
+        }
+        if (isDependencySatisfied(dependency, input.completedKeys)) {
+            satisfiedBlockers.push(dependency);
+            continue;
+        }
+        openBlockers.push(dependency);
+    }
+    return {
+        selectable_prerequisites: selectablePrerequisites.map(dependencyReference),
+        satisfied_blockers: satisfiedBlockers.map(dependencyReference),
+        open_blockers: openBlockers.map(dependencyReference),
+    };
+}
+function workItemReference(item) {
+    return {
+        key: item.key,
+        number: item.number,
+        title: item.title,
+    };
+}
+function dependencyReference(dependency) {
+    return {
+        key: dependency.key,
+        number: dependency.number,
+        title: dependency.title,
+        state: dependency.state,
+    };
+}
 function buildCommitMessage(item) {
     return `${item.title}\n\nWork item: ${item.source.locator}`;
 }

package/dist/runtime/selectionConfirmation.js

@@ -1,4 +1,6 @@
 import { checkbox, Separator } from "@inquirer/prompts";
+import { buildWorkItemSelectionPlan, formatSelectionBlockers, normalizeWorkItemSelection, } from "./selectionPlanner.js";
+export { buildSelectionSections } from "./selectionPlanner.js";
 export async function confirmWorkItemSelection(input) {
     if (input.autoAccept) {
         return input.proposed;
@@ -8,104 +10,84 @@ export async function confirmWorkItemSelection(input) {
         throw new Error('Interactive work item selection requires a TTY. Re-run with "nyxagent run --yes" to accept the agent selection.');
     }
     const choiceItems = buildSelectionChoiceItems(input);
+    const choiceOrder = choiceItems
+        .filter((item) => item.type === "choice")
+        .map((item) => item.value);
     const selectedKeys = await checkbox({
         message: `Select work items to run (max ${input.maxItems})`,
         choices: choiceItems.map(toInquirerChoice),
         pageSize: Math.min(Math.max(choiceItems.length, 7), 20),
         required: false,
-        validate: (selected) => selected.length <= input.maxItems ||
-            `Select at most ${input.maxItems} work item(s).`,
+        validate: (selected) => {
+            const normalized = normalizeSelectedKeys({
+                selectedKeys: selected.map((choice) => choice.value),
+                choiceOrder,
+                candidates: input.candidates,
+                maxItems: input.maxItems,
+            });
+            if (!normalized.ok) {
+                return normalized.error;
+            }
+            if (normalized.blockedCandidates.length > 0) {
+                return `Selection contains blocked work item(s): ${formatSelectionBlockers(normalized.blockedCandidates)}`;
+            }
+            return true;
+        },
         shortcuts: {
             all: null,
             invert: null,
         },
     });
-    const selected = new Set(selectedKeys);
-    const candidatesByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
-    return choiceItems.flatMap((item) => {
-        if (item.type !== "choice" || !selected.has(item.value)) {
-            return [];
-        }
-        const candidate = candidatesByKey.get(item.value);
-        return candidate ? [candidate] : [];
+    const normalized = normalizeSelectedKeys({
+        selectedKeys,
+        choiceOrder,
+        candidates: input.candidates,
+        maxItems: input.maxItems,
     });
+    if (!normalized.ok) {
+        throw new Error(normalized.error);
+    }
+    return normalized.queue;
 }
 export function buildSelectionChoiceItems(input) {
-    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 = [];
-    let activeSectionLabel;
-    activeSectionLabel = appendSelectionChoices({
-        items,
-        sections: buildSelectionSections(proposedCandidates),
-        proposedKeys,
-        activeSectionLabel,
+    const plan = buildWorkItemSelectionPlan({
+        candidates: input.candidates,
+        proposed: input.proposed,
+        maxItems: input.maxItems ?? input.candidates.length,
     });
+    const proposedKeys = new Set(plan.recommendedQueue.map((item) => item.key));
+    const blockedByKey = new Map(plan.blockedCandidates.map((blocked) => [blocked.candidate.key, blocked]));
+    const items = [];
     appendSelectionChoices({
         items,
-        sections: buildSelectionSections(remainingCandidates),
+        sections: plan.sections,
         proposedKeys,
-        activeSectionLabel,
+        blockedByKey,
     });
     return items;
 }
 function appendSelectionChoices(input) {
-    let activeSectionLabel = input.activeSectionLabel;
     for (const section of input.sections) {
         if (section.label) {
-            if (activeSectionLabel !== section.label) {
-                input.items.push({ type: "separator", label: section.label });
-            }
-            activeSectionLabel = section.label;
-        }
-        else {
-            activeSectionLabel = undefined;
+            input.items.push({ type: "separator", label: section.label });
         }
         for (const candidate of section.candidates) {
             const proposed = input.proposedKeys.has(candidate.key);
-            input.items.push({
+            const blocked = input.blockedByKey.get(candidate.key);
+            const item = {
                 type: "choice",
                 value: candidate.key,
                 name: `#${candidate.number} ${candidate.title}${proposed ? " (agent)" : ""}`,
                 checked: proposed,
-            });
-        }
-    }
-    return activeSectionLabel;
-}
-export function buildSelectionSections(candidates) {
-    const sections = [];
-    const groupedSections = new Map();
-    let ungroupedSection;
-    for (const candidate of candidates) {
-        const group = detectSelectionGroup(candidate);
-        if (!group) {
-            if (!ungroupedSection) {
-                ungroupedSection = { candidates: [] };
-                sections.push(ungroupedSection);
+            };
+            if (blocked) {
+                item.disabled = `blocked by ${blocked.blockers
+                    .map((blocker) => `#${blocker.number}`)
+                    .join(", ")}`;
             }
-            ungroupedSection.candidates.push(candidate);
-            continue;
+            input.items.push(item);
         }
-        let section = groupedSections.get(group.key);
-        if (!section) {
-            section = { label: group.label, candidates: [] };
-            groupedSections.set(group.key, section);
-            sections.push(section);
-        }
-        section.candidates.push(candidate);
     }
-    return sections;
 }
 function toInquirerChoice(item) {
     if (item.type === "separator") {
@@ -115,72 +97,21 @@ function toInquirerChoice(item) {
         value: item.value,
         name: item.name,
         checked: item.checked,
+        disabled: item.disabled,
     };
 }
-function detectSelectionGroup(candidate) {
-    if (candidate.parent) {
-        return {
-            key: `parent:${candidate.parent.key}`,
-            label: formatParentGroup(candidate.parent),
-        };
-    }
-    for (const label of candidate.labels ?? []) {
-        const group = parseGroupLabel(label);
-        if (group) {
-            return { key: `display:${group.toLowerCase()}`, label: group };
-        }
-    }
-    const titleGroup = parseBracketedTitleGroup(candidate.title);
-    return titleGroup
-        ? { key: `display:${titleGroup.toLowerCase()}`, label: titleGroup }
-        : undefined;
-}
-function formatParentGroup(parent) {
-    if (!parent) {
-        return "Parent";
-    }
-    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());
-    if (!match) {
-        return undefined;
-    }
-    return formatGroupLabel(match[1], match[2]);
-}
-function parseBracketedTitleGroup(title) {
-    const match = /^\[(plan|prd)\s*[:/=-]\s*([^\]]+)\]/i.exec(title.trim());
-    if (!match) {
-        return undefined;
-    }
-    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) {
-        return undefined;
-    }
-    const prefix = kind.toLowerCase() === "prd" ? "PRD" : "Plan";
-    return `${prefix}: ${name}`;
+function normalizeSelectedKeys(input) {
+    const selected = new Set(input.selectedKeys);
+    const candidatesByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
+    const orderedSelected = input.choiceOrder.flatMap((key) => {
+        const candidate = candidatesByKey.get(key);
+        return candidate && selected.has(key) ? [candidate] : [];
+    });
+    return normalizeWorkItemSelection({
+        candidates: input.candidates,
+        selected: orderedSelected,
+        maxItems: input.maxItems,
+        expandGroups: false,
+        strictMax: true,
+    });
 }

package/dist/runtime/selectionPlanner.js

@@ -0,0 +1,406 @@
+import { orderWorkItemsByDependencies, } from "./workItems.js";
+export function buildWorkItemSelectionPlan(input) {
+    const context = createPlanningContext(input);
+    const recommended = input.proposed
+        ? normalizeWithContext(context, {
+            selected: input.proposed,
+            maxItems: input.maxItems,
+            expandGroups: true,
+        })
+        : emptyNormalizedSelection();
+    const plannedSections = context.sections.map((section) => {
+        const sectionSeries = buildSectionSeries({
+            context,
+            section,
+            maxItems: input.maxItems,
+        });
+        return {
+            label: section.label,
+            candidates: section.candidates,
+            recommended: sectionSeries.queue,
+            blocked: section.candidates.flatMap((candidate) => blockerForCandidate(context, candidate)),
+        };
+    });
+    return {
+        sections: plannedSections,
+        recommendedSeries: plannedSections
+            .map((section) => ({
+            section: section.label,
+            candidates: section.recommended,
+            blocked: section.blocked,
+            truncated: section.recommended.length > 0 &&
+                section.recommended.length === input.maxItems &&
+                section.candidates.some((candidate) => !section.recommended.some((item) => item.key === candidate.key)),
+        }))
+            .filter((series) => series.candidates.length > 0 || series.blocked.length > 0),
+        recommendedQueue: recommended.ok ? recommended.queue : recommended.queue,
+        candidateOrder: context.sections.flatMap((section) => section.candidates),
+        blockedCandidates: [...context.blockedByKey.values()],
+        cycleKeys: recommended.cycleKeys,
+        truncated: recommended.truncated,
+    };
+}
+export function normalizeWorkItemSelection(input) {
+    return normalizeWithContext(createPlanningContext(input), input);
+}
+export function buildSelectionSections(candidates) {
+    const sections = [];
+    const groupedSections = new Map();
+    let ungroupedSection;
+    for (const candidate of candidates) {
+        const group = detectSelectionGroup(candidate);
+        if (!group) {
+            if (!ungroupedSection) {
+                ungroupedSection = { candidates: [] };
+                sections.push(ungroupedSection);
+            }
+            ungroupedSection.candidates.push(candidate);
+            continue;
+        }
+        let section = groupedSections.get(group.key);
+        if (!section) {
+            section = { label: group.label, candidates: [] };
+            groupedSections.set(group.key, section);
+            sections.push(section);
+        }
+        section.candidates.push(candidate);
+    }
+    return sections.map((section) => ({
+        label: section.label,
+        candidates: orderCandidatesForPlanning(section.candidates),
+    }));
+}
+export function isDependencySatisfied(dependency, completedKeys = new Set()) {
+    return (completedKeys.has(dependency.key) ||
+        dependency.state?.toLowerCase() === "closed");
+}
+export function formatSelectionBlockers(blocked) {
+    return blocked
+        .map((item) => `#${item.candidate.number} blocked by ${item.blockers
+        .map(formatDependencyReference)
+        .join(", ")}`)
+        .join("; ");
+}
+function buildSectionSeries(input) {
+    const first = input.section.candidates[0];
+    if (!first) {
+        return emptyNormalizedSelection();
+    }
+    return normalizeWithContext(input.context, {
+        selected: [first],
+        maxItems: input.maxItems,
+        expandGroups: Boolean(input.section.label),
+    });
+}
+function normalizeWithContext(context, input) {
+    if (input.selected.length === 0) {
+        return emptyNormalizedSelection();
+    }
+    const selected = dedupeCandidates(input.selected.flatMap((candidate) => {
+        const resolved = context.candidateByKey.get(candidate.key);
+        return resolved ? [resolved] : [];
+    }));
+    const selectedOrder = new Map(selected.map((candidate, index) => [candidate.key, index]));
+    const targetKeys = selectionTargetKeys({
+        context,
+        selected,
+        expandGroups: input.expandGroups,
+    });
+    const targetIndex = new Map(targetKeys.map((key, index) => [key, index]));
+    const closureKeys = new Set();
+    const blockedByKey = new Map();
+    const visiting = new Set();
+    const resolved = new Map();
+    const includeCandidate = (key) => {
+        const cached = resolved.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const candidate = context.candidateByKey.get(key);
+        if (!candidate) {
+            return false;
+        }
+        if (visiting.has(key)) {
+            return true;
+        }
+        visiting.add(key);
+        const blockers = [];
+        for (const dependency of candidate.blocked_by ?? []) {
+            const dependencyCandidate = context.candidateByKey.get(dependency.key);
+            if (dependencyCandidate) {
+                if (!includeCandidate(dependencyCandidate.key)) {
+                    blockers.push(enrichDependencyFromCandidate(dependency, dependencyCandidate));
+                }
+                continue;
+            }
+            if (!isDependencySatisfied(dependency, context.completedKeys)) {
+                blockers.push(dependency);
+            }
+        }
+        visiting.delete(key);
+        const ok = blockers.length === 0;
+        if (ok) {
+            closureKeys.add(key);
+        }
+        else {
+            blockedByKey.set(candidate.key, {
+                candidate,
+                blockers: dedupeDependencies(blockers),
+            });
+        }
+        resolved.set(key, ok);
+        return ok;
+    };
+    for (const key of targetKeys) {
+        includeCandidate(key);
+    }
+    const preOrdered = [...closureKeys]
+        .flatMap((key) => {
+        const candidate = context.candidateByKey.get(key);
+        return candidate ? [candidate] : [];
+    })
+        .sort((a, b) => compareSelectionCandidates({
+        a,
+        b,
+        targetIndex,
+        selectedOrder,
+        canonicalIndex: context.canonicalIndex,
+    }));
+    const ordered = orderWorkItemsByDependencies(preOrdered);
+    const requiredCount = ordered.queue.length;
+    if (input.strictMax && requiredCount > input.maxItems) {
+        return {
+            ok: false,
+            error: `Selection expands to ${requiredCount} work item(s) after prerequisites; max is ${input.maxItems}.`,
+            queue: ordered.queue.slice(0, input.maxItems),
+            cycleKeys: ordered.cycleKeys,
+            blockedCandidates: [...blockedByKey.values()],
+            requiredCount,
+            truncated: true,
+        };
+    }
+    return {
+        ok: true,
+        queue: ordered.queue.slice(0, input.maxItems),
+        cycleKeys: ordered.cycleKeys,
+        blockedCandidates: [...blockedByKey.values()],
+        requiredCount,
+        truncated: requiredCount > input.maxItems,
+    };
+}
+function createPlanningContext(input) {
+    const sections = buildSelectionSections(input.candidates);
+    const candidateOrder = sections.flatMap((section) => section.candidates);
+    const candidateByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
+    const sectionByCandidateKey = new Map();
+    const canonicalIndex = new Map();
+    const completedKeys = new Set(input.completedKeys ?? []);
+    for (const [index, candidate] of candidateOrder.entries()) {
+        canonicalIndex.set(candidate.key, index);
+    }
+    for (const section of sections) {
+        for (const candidate of section.candidates) {
+            sectionByCandidateKey.set(candidate.key, section);
+        }
+    }
+    const context = {
+        candidates: input.candidates,
+        candidateByKey,
+        completedKeys,
+        sections,
+        sectionByCandidateKey,
+        canonicalIndex,
+        blockedByKey: new Map(),
+    };
+    context.blockedByKey = collectBlockedCandidates(context);
+    return context;
+}
+function collectBlockedCandidates(context) {
+    const blockedByKey = new Map();
+    const visiting = new Set();
+    const blockersFor = (candidate) => {
+        const cached = blockedByKey.get(candidate.key);
+        if (cached) {
+            return cached.blockers;
+        }
+        if (visiting.has(candidate.key)) {
+            return [];
+        }
+        visiting.add(candidate.key);
+        const blockers = [];
+        for (const dependency of candidate.blocked_by ?? []) {
+            const dependencyCandidate = context.candidateByKey.get(dependency.key);
+            if (dependencyCandidate) {
+                if (blockersFor(dependencyCandidate).length > 0) {
+                    blockers.push(enrichDependencyFromCandidate(dependency, dependencyCandidate));
+                }
+                continue;
+            }
+            if (!isDependencySatisfied(dependency, context.completedKeys)) {
+                blockers.push(dependency);
+            }
+        }
+        visiting.delete(candidate.key);
+        if (blockers.length > 0) {
+            blockedByKey.set(candidate.key, {
+                candidate,
+                blockers: dedupeDependencies(blockers),
+            });
+        }
+        return blockers;
+    };
+    for (const candidate of context.candidates) {
+        blockersFor(candidate);
+    }
+    return blockedByKey;
+}
+function selectionTargetKeys(input) {
+    const keys = [];
+    const seen = new Set();
+    for (const candidate of input.selected) {
+        const section = input.context.sectionByCandidateKey.get(candidate.key);
+        const sectionCandidates = input.expandGroups && section?.label ? section.candidates : [candidate];
+        for (const item of sectionCandidates) {
+            if (!seen.has(item.key)) {
+                seen.add(item.key);
+                keys.push(item.key);
+            }
+        }
+    }
+    return keys;
+}
+function orderCandidatesForPlanning(candidates) {
+    const byNumber = [...candidates].sort(compareByIssueNumber);
+    return orderWorkItemsByDependencies(byNumber).queue;
+}
+function compareSelectionCandidates(input) {
+    const aRank = selectionCandidateRank(input.a, input);
+    const bRank = selectionCandidateRank(input.b, input);
+    if (aRank !== bRank) {
+        return aRank - bRank;
+    }
+    return compareByIssueNumber(input.a, input.b);
+}
+function selectionCandidateRank(candidate, input) {
+    return (input.targetIndex.get(candidate.key) ??
+        input.selectedOrder.get(candidate.key) ??
+        input.canonicalIndex.get(candidate.key) ??
+        Number.MAX_SAFE_INTEGER);
+}
+function compareByIssueNumber(a, b) {
+    if (a.number !== b.number) {
+        return a.number - b.number;
+    }
+    return a.title.localeCompare(b.title);
+}
+function blockerForCandidate(context, candidate) {
+    const blocker = context.blockedByKey.get(candidate.key);
+    return blocker ? [blocker] : [];
+}
+function enrichDependencyFromCandidate(dependency, candidate) {
+    return {
+        ...dependency,
+        title: dependency.title ?? candidate.title,
+        state: dependency.state ?? "open",
+    };
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const deduped = [];
+    for (const candidate of candidates) {
+        if (seen.has(candidate.key)) {
+            continue;
+        }
+        seen.add(candidate.key);
+        deduped.push(candidate);
+    }
+    return deduped;
+}
+function dedupeDependencies(dependencies) {
+    const byKey = new Map();
+    for (const dependency of dependencies) {
+        byKey.set(dependency.key, dependency);
+    }
+    return [...byKey.values()];
+}
+function formatDependencyReference(dependency) {
+    const state = dependency.state ? ` (${dependency.state})` : "";
+    return `#${dependency.number}${state}`;
+}
+function emptyNormalizedSelection() {
+    return {
+        ok: true,
+        queue: [],
+        cycleKeys: [],
+        blockedCandidates: [],
+        requiredCount: 0,
+        truncated: false,
+    };
+}
+function detectSelectionGroup(candidate) {
+    if (candidate.parent) {
+        return {
+            key: `parent:${candidate.parent.key}`,
+            label: formatParentGroup(candidate.parent),
+        };
+    }
+    for (const label of candidate.labels ?? []) {
+        const group = parseGroupLabel(label);
+        if (group) {
+            return { key: `display:${group.toLowerCase()}`, label: group };
+        }
+    }
+    const titleGroup = parseBracketedTitleGroup(candidate.title);
+    return titleGroup
+        ? { key: `display:${titleGroup.toLowerCase()}`, label: titleGroup }
+        : undefined;
+}
+function formatParentGroup(parent) {
+    if (!parent) {
+        return "Parent";
+    }
+    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());
+    if (!match) {
+        return undefined;
+    }
+    return formatGroupLabel(match[1], match[2]);
+}
+function parseBracketedTitleGroup(title) {
+    const match = /^\[(plan|prd)\s*[:/=-]\s*([^\]]+)\]/i.exec(title.trim());
+    if (!match) {
+        return undefined;
+    }
+    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) {
+        return undefined;
+    }
+    const prefix = kind.toLowerCase() === "prd" ? "PRD" : "Plan";
+    return `${prefix}: ${name}`;
+}

package/dist/runtime/workItems.js

@@ -123,7 +123,7 @@ async function listOpenGitHubIssueRecords(input) {
         repo: input.repo,
         excerptChars: input.excerptChars,
     }));
-    attachBlockedByDependencies({ records, repo: input.repo });
+    await attachBlockedByDependencies({ records, repo: input.repo });
     return records;
 }
 export function filterAvailable(input) {
@@ -291,14 +291,29 @@ function normalizeIssueRecord(input) {
         details,
     };
 }
-function attachBlockedByDependencies(input) {
+async function attachBlockedByDependencies(input) {
     const detailsByKey = new Map(input.records.map((record) => [record.candidate.key, record.details]));
+    const dependenciesByRecord = new Map();
+    const externalDependencies = new Map();
     for (const record of input.records) {
         const dependencies = parseBlockedByDependencies({
             body: record.body,
             repo: input.repo,
-        }).map((dependency) => {
-            const details = detailsByKey.get(dependency.key);
+        });
+        dependenciesByRecord.set(record, dependencies);
+        for (const dependency of dependencies) {
+            if (!detailsByKey.has(dependency.key)) {
+                externalDependencies.set(dependency.key, dependency);
+            }
+        }
+    }
+    const externalDetailsByKey = await fetchExternalDependencyDetails([
+        ...externalDependencies.values(),
+    ]);
+    for (const record of input.records) {
+        const dependencies = (dependenciesByRecord.get(record) ?? []).map((dependency) => {
+            const details = detailsByKey.get(dependency.key) ??
+                externalDetailsByKey.get(dependency.key);
             if (!details) {
                 return dependency;
             }
@@ -316,6 +331,20 @@ function attachBlockedByDependencies(input) {
         }
     }
 }
+async function fetchExternalDependencyDetails(dependencies) {
+    const detailsByKey = new Map();
+    for (const dependency of dependencies) {
+        const locator = parseGitHubIssueLocator(dependency.source.locator);
+        if (!locator) {
+            continue;
+        }
+        const details = await getGitHubIssue(locator);
+        if (details) {
+            detailsByKey.set(dependency.key, details);
+        }
+    }
+    return detailsByKey;
+}
 function buildExcerpt(content, maxChars) {
     if (maxChars <= 0) {
         return undefined;
@@ -693,6 +722,26 @@ function parseGitHubRepo(repo) {
     }
     return { owner, repoName };
 }
+function parseGitHubIssueLocator(locator) {
+    const separator = locator.lastIndexOf("#");
+    if (separator <= 0 || separator === locator.length - 1) {
+        return undefined;
+    }
+    const repo = locator.slice(0, separator);
+    const issueNumber = Number.parseInt(locator.slice(separator + 1), 10);
+    if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+        return undefined;
+    }
+    try {
+        return {
+            ...parseGitHubRepo(repo),
+            issueNumber,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function getGitHubParentIssue(input) {
     const result = await ghApi([
         `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}/parent`,
@@ -722,6 +771,15 @@ async function listGitHubSubIssues(input) {
             .filter((issue) => Boolean(issue)),
     };
 }
+async function getGitHubIssue(input) {
+    const result = await ghApi([
+        `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}`,
+    ]);
+    if (!result.ok || result.value === undefined) {
+        return undefined;
+    }
+    return normalizeGitHubIssueDetails(result.value);
+}
 async function ghApi(args) {
     const result = await execa("gh", [
         "api",

package/package.json

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