@nyxa/nyx-agent 0.7.0 → 0.8.1

package/dist/runtime/schemas.js

@@ -12,41 +12,127 @@ export const SELECTION_SCHEMA = {
         work_item_keys: {
             type: "array",
             items: { type: "string" },
-            description: "Ordered keys of the chosen candidates (prerequisites first)."
-        }
+            description: "Ordered keys of the chosen candidates (prerequisites first).",
+        },
     },
     allOf: [
         {
             if: { properties: { outcome: { const: "selected" } } },
-            then: { required: ["work_item_keys"] }
-        }
+            then: { required: ["work_item_keys"] },
+        },
     ],
-    additionalProperties: true
+    additionalProperties: true,
+};
+const evidenceSchema = {
+    type: "object",
+    properties: {
+        file: { type: "string" },
+        line: { type: "integer", minimum: 1 },
+        command: { type: "string" },
+        observation: { type: "string" },
+        detail: { type: "string" },
+    },
+    additionalProperties: true,
+};
+const findingSchema = {
+    type: "object",
+    required: ["title", "required_change", "confidence", "evidence"],
+    properties: {
+        title: { type: "string", minLength: 1 },
+        required_change: { type: "string", minLength: 1 },
+        confidence: {
+            type: "string",
+            enum: ["low", "medium", "high"],
+        },
+        evidence: {
+            type: "array",
+            minItems: 1,
+            items: evidenceSchema,
+            description: "Concrete evidence: file+line, command+observation, or an equivalent current-code observation.",
+        },
+    },
+    additionalProperties: true,
 };
-const reviewSchema = {
+const findingArraySchema = {
+    type: "array",
+    items: findingSchema,
+    default: [],
+};
+const reviewDiscoverySchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
-    required: ["outcome", "summary"],
+    required: [
+        "summary",
+        "blockers",
+        "test_gaps",
+        "advisory_findings",
+        "uncertain_findings",
+        "rejected_findings",
+    ],
     properties: {
-        outcome: { type: "string", enum: ["approved", "changes_requested"] },
         summary: {
             type: "string",
             minLength: 1,
-            description: "A brief assessment of the work."
+            description: "A brief assessment of the work.",
         },
-        required_changes: {
+        blockers: findingArraySchema,
+        test_gaps: findingArraySchema,
+        advisory_findings: findingArraySchema,
+        uncertain_findings: findingArraySchema,
+        rejected_findings: findingArraySchema,
+    },
+    additionalProperties: true,
+};
+const reviewChallengeSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["summary", "blockers", "rejected_findings"],
+    properties: {
+        summary: { type: "string", minLength: 1 },
+        blockers: findingArraySchema,
+        rejected_findings: findingArraySchema,
+    },
+    additionalProperties: true,
+};
+const validationSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["summary", "validations"],
+    properties: {
+        summary: { type: "string", minLength: 1 },
+        validations: {
             type: "array",
-            items: { type: "string" },
-            description: 'Specific, actionable changes (required when outcome is "changes_requested").'
-        }
+            items: {
+                type: "object",
+                required: ["blocker_title", "status", "evidence"],
+                properties: {
+                    blocker_title: { type: "string", minLength: 1 },
+                    status: {
+                        type: "string",
+                        enum: [
+                            "resolved",
+                            "unresolved",
+                            "false_positive",
+                            "regression_from_correction",
+                        ],
+                    },
+                    required_change: {
+                        type: "string",
+                        description: "Required when the status remains unresolved or is a correction-caused regression.",
+                    },
+                    evidence: {
+                        type: "array",
+                        minItems: 1,
+                        items: evidenceSchema,
+                    },
+                },
+                additionalProperties: true,
+            },
+        },
     },
-    allOf: [
-        {
-            if: { properties: { outcome: { const: "changes_requested" } } },
-            then: { required: ["required_changes"] }
-        }
-    ],
-    additionalProperties: true
+    additionalProperties: true,
 };
-export const REVIEW_SCHEMA = reviewSchema;
-export const GLOBAL_REVIEW_SCHEMA = reviewSchema;
+export const REVIEW_DISCOVERY_SCHEMA = reviewDiscoverySchema;
+export const GLOBAL_REVIEW_SCHEMA = reviewDiscoverySchema;
+export const REVIEW_CHALLENGE_SCHEMA = reviewChallengeSchema;
+export const REVIEW_VALIDATION_SCHEMA = validationSchema;

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.7.0",
+  "version": "0.8.1",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {