@agent-native/core 0.48.4 → 0.49.1

package/dist/cli/recap.js

@@ -76,7 +76,7 @@ function optionalArg(args, key) {
 /** GitHub secrets the installed PR Visual Recap workflow needs. */
 export const PR_VISUAL_RECAP_SETUP = [
     "Required secrets:",
-    "  PLAN_RECAP_TOKEN   — bearer token from `agent-native connect`",
+    "  PLAN_RECAP_TOKEN   — bearer token from `npx @agent-native/core@latest connect`",
     "  ANTHROPIC_API_KEY  — the LLM key for the default Claude Code backend",
     "Optional (only if you change defaults):",
     "  OPENAI_API_KEY (secret) + VISUAL_RECAP_AGENT=codex (variable) — use Codex instead of Claude",
@@ -449,7 +449,7 @@ function runSetup(args) {
             else if (status === "missing") {
                 lines.push(`  ${name}: missing value.`);
                 if (name === "PLAN_RECAP_TOKEN") {
-                    lines.push(`    Run agent-native connect ${plan.appUrl} --client codex, then rerun this setup.`);
+                    lines.push(`    Run npx @agent-native/core@latest connect ${plan.appUrl} --client codex, then rerun this setup.`);
                 }
                 lines.push(`    Or set manually: ${commandForMissingSecret(name, repo)}`);
             }
@@ -473,7 +473,7 @@ function runSetup(args) {
         }
     }
     lines.push("");
-    lines.push(`Next: commit ${plan.workflowPath}, then run agent-native recap doctor.`);
+    lines.push(`Next: commit ${plan.workflowPath}, then run npx @agent-native/core@latest recap doctor.`);
     process.stdout.write(`${lines.join("\n")}\n`);
 }
 function runDoctor(args) {
@@ -495,7 +495,7 @@ function runDoctor(args) {
     if (!fs.existsSync(workflowFile)) {
         ok = false;
         lines.push(`[missing] Workflow missing: ${plan.workflowPath}.`);
-        lines.push("  Run agent-native skills add visual-plan --with-github-action.");
+        lines.push("  Run npx @agent-native/skills add --skill visual-plan --with-github-action.");
     }
     else {
         const current = fs.readFileSync(workflowFile, "utf-8");
@@ -505,7 +505,7 @@ function runDoctor(args) {
         else {
             ok = false;
             lines.push(`[missing] Workflow differs from the bundled template: ${plan.workflowPath}.`);
-            lines.push("  Run agent-native recap setup to refresh it.");
+            lines.push("  Run npx @agent-native/core@latest recap setup to refresh it.");
         }
     }
     if (plan.secretValues.PLAN_RECAP_TOKEN) {
@@ -513,7 +513,7 @@ function runDoctor(args) {
     }
     else {
         lines.push("[warn] Local Plans publish token not found.");
-        lines.push(`  Run agent-native connect ${plan.appUrl} --client codex to mint one.`);
+        lines.push(`  Run npx @agent-native/core@latest connect ${plan.appUrl} --client codex to mint one.`);
     }
     if (repo) {
         lines.push(`[ok] GitHub repo detected: ${repo}.`);
@@ -649,6 +649,98 @@ export function diffContainsSecret(diffText, allowlist = []) {
     }
     return false;
 }
+const AGENT_FAILURE_MAX_CHARS = 1200;
+function compactWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+export function sanitizeAgentFailureSummary(value, maxChars = AGENT_FAILURE_MAX_CHARS) {
+    const sanitizedLines = value
+        .replace(/\u001b\[[0-9;]*m/g, "")
+        .split("\n")
+        .map((line) => (lineLooksSecret(line) ? "[redacted sensitive line]" : line))
+        .map((line) => line
+        .replace(/Bearer\s+[A-Za-z0-9._-]{8,}/gi, "Bearer [redacted]")
+        .replace(/Authorization:\s*[^\s]+/gi, "Authorization: [redacted]")
+        .replace(/PLAN_RECAP_TOKEN=([^\s]+)/g, "PLAN_RECAP_TOKEN=[redacted]")
+        .replace(/ANTHROPIC_API_KEY=([^\s]+)/g, "ANTHROPIC_API_KEY=[redacted]")
+        .replace(/OPENAI_API_KEY=([^\s]+)/g, "OPENAI_API_KEY=[redacted]"))
+        .join("\n");
+    const compacted = compactWhitespace(sanitizedLines);
+    if (compacted.length <= maxChars)
+        return compacted;
+    return `${compacted.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+function collectStringFields(value, fields, seen = new Set()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return [];
+    seen.add(value);
+    const obj = value;
+    const out = [];
+    for (const field of fields) {
+        const candidate = obj[field];
+        if (typeof candidate === "string" && candidate.trim()) {
+            out.push(candidate.trim());
+        }
+    }
+    for (const nested of Object.values(obj)) {
+        if (nested && typeof nested === "object") {
+            out.push(...collectStringFields(nested, fields, seen));
+        }
+    }
+    return out;
+}
+export function summarizeAgentResult(agent, resultText) {
+    const normalizedAgent = agent.toLowerCase();
+    const text = resultText.trim();
+    if (!text)
+        return "";
+    if (normalizedAgent === "claude") {
+        const obj = parseLastJsonObject(text);
+        if (obj) {
+            const candidates = [
+                ...collectStringFields(obj, [
+                    "error",
+                    "message",
+                    "result",
+                    "reason",
+                    "subtype",
+                    "type",
+                ]),
+            ].filter(Boolean);
+            const preferred = candidates.find((candidate) => /error|failed|denied|not found|unavailable|unauthorized|forbidden|tool/i.test(candidate)) ?? candidates[0];
+            if (preferred)
+                return sanitizeAgentFailureSummary(preferred);
+        }
+    }
+    if (normalizedAgent === "codex") {
+        const candidates = [];
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith("{"))
+                continue;
+            try {
+                const obj = JSON.parse(trimmed);
+                candidates.push(...collectStringFields(obj, [
+                    "error",
+                    "message",
+                    "text",
+                    "delta",
+                    "reason",
+                    "type",
+                ]));
+            }
+            catch {
+                // Keep scanning.
+            }
+        }
+        const newestFirst = [...candidates].reverse();
+        const preferred = newestFirst.find((candidate) => candidate.length > 12 &&
+            /error|failed|denied|not found|unavailable|unauthorized|forbidden|tool/i.test(candidate)) ?? newestFirst[0];
+        if (preferred)
+            return sanitizeAgentFailureSummary(preferred);
+    }
+    return sanitizeAgentFailureSummary(text);
+}
 /* -------------------------------------------------------------------------- */
 /* Bounded diff collection — was the workflow's "Collect bounded diff" step    */
 /* -------------------------------------------------------------------------- */
@@ -1007,7 +1099,7 @@ export function readRepoSkillMd(cwd = process.cwd()) {
             return { text: fs.readFileSync(abs, "utf8"), source: rel };
         }
     }
-    throw new Error("Could not find visual-recap/SKILL.md. Run `agent-native skills add visual-plan` first.");
+    throw new Error("Could not find visual-recap/SKILL.md. Run `npx @agent-native/skills add --skill visual-plan` first.");
 }
 function listRecapSkillReferenceFiles(skillDir) {
     const out = {};
@@ -1112,7 +1204,7 @@ export function buildRecapPrompt(input) {
         lines.push("## Local-Files Output (this is the only way to produce output)");
         lines.push("Do NOT call the `plan` MCP server, `create-visual-recap`, `import-visual-plan-source`, `update-visual-plan`, `export-visual-plan`, or any hosted Plan action. This mode exists so the recap data never goes to a Plan app database.");
         lines.push(`1. Create or replace the local MDX folder \`${localDir}\` with \`plan.mdx\` and optional \`canvas.mdx\`, \`prototype.mdx\`, and \`.plan-state.json\` derived ONLY from the real diff. Set \`kind: "recap"\` and \`localOnly: true\` in source metadata/state.`);
-        lines.push(`2. Run \`agent-native plan local preview --dir ${JSON.stringify(localDir)} --kind recap --out ${JSON.stringify(path.join(localDir, "preview.html"))}\` to validate the folder and generate the local preview.`);
+        lines.push(`2. Run \`npx @agent-native/core@latest plan local preview --dir ${JSON.stringify(localDir)} --kind recap --out ${JSON.stringify(path.join(localDir, "preview.html"))}\` to validate the folder and generate the local preview.`);
         lines.push("3. Write the returned `url` from that command to `recap-url.txt` at the repo root, containing exactly one line. This file is the workflow's only hand-off.");
     }
     else {
@@ -1147,6 +1239,7 @@ export function buildRecapPrompt(input) {
 /* -------------------------------------------------------------------------- */
 const MARKER = "<!-- pr-visual-recap -->";
 const RECAP_IMAGE_URL_PATH_PATTERN = /\/_agent-native\/recap-image\/[0-9a-f]{32,128}\.png$/;
+const RECAP_SCREENSHOT_QUERY_PARAM = "recapScreenshot";
 function repoParts(repoFullName) {
     const [owner, repo] = repoFullName.split("/");
     if (!owner || !repo)
@@ -1237,9 +1330,6 @@ function originOf(url) {
 /** Build the sticky comment body from the workflow's environment. */
 export function buildCommentBody(env = process.env) {
     const lines = [MARKER];
-    // Short head SHA for the "as of" freshness line.
-    const headSha = (env.HEAD_SHA || "").trim();
-    const headShort = headSha ? headSha.slice(0, 7) : "";
     // Last-known plan id threaded from the previous run (supplied via PREV_PLAN_ID
     // when the comment is rebuilt from scratch, or parsed from the env on upsert).
     // We always emit the plan-id marker when any plan id is known so that a
@@ -1260,21 +1350,17 @@ export function buildCommentBody(env = process.env) {
         lines.push("The recap was **suppressed** because the diff matched a secret/credential pattern. No plan was published.");
         lines.push("");
         lines.push(`Reason: \`${reason}\`.`);
-        if (headShort)
-            lines.push("", `_As of \`${headShort}\`_`);
         if (prevPlanId)
             lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
         return lines.join("\n");
     }
     // Tiny diffs aren't worth a recap. Refresh an existing sticky comment to this
-    // state (the workflow only updates, never creates, on tiny) so it never lingers
-    // pointing at a stale head SHA.
+    // state (the workflow only updates, never creates, on tiny) so stale recap
+    // links do not linger on no-op changes.
     if (env.DIFF_TINY === "true") {
         lines.push("### Visual recap — skipped (diff too small)");
         lines.push("");
         lines.push("The change in this pull request is too small to be worth a visual recap. This is informational only and does **not** block the PR.");
-        if (headShort)
-            lines.push("", `_As of \`${headShort}\`_`);
         if (prevPlanId)
             lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
         return lines.join("\n");
@@ -1299,16 +1385,19 @@ export function buildCommentBody(env = process.env) {
     const markerPlanId = trustedPlanId ?? prevPlanId;
     if (!safeUrl) {
         const authFailed = env.RECAP_AUTH_FAILED === "true";
+        const agentSummary = sanitizeAgentFailureSummary((env.RECAP_AGENT_SUMMARY || "").trim(), 800);
         lines.push("### Visual recap — generation failed");
         lines.push("");
         if (authFailed) {
-            lines.push("Recap authentication failed — the `PLAN_RECAP_TOKEN` secret may be expired or revoked. Re-mint it with `agent-native connect` and update the repo secret.");
+            lines.push("Recap authentication failed — the `PLAN_RECAP_TOKEN` secret may be expired or revoked. Re-mint it with `npx @agent-native/core@latest reconnect <app-url>` (or `npx @agent-native/core@latest connect <app-url>` for first-time setup) and update the repo secret.");
         }
         else {
             lines.push("The visual recap could not be generated for this pull request. This is informational only and does **not** block the PR.");
+            if (agentSummary) {
+                lines.push("");
+                lines.push(`Agent output: ${agentSummary}`);
+            }
         }
-        if (headShort)
-            lines.push("", `_As of \`${headShort}\`_`);
         // Keep a link to the last-good recap so reviewers are not left in the dark.
         if (prevPlanId && base) {
             const prevSafeUrl = `${base}/recaps/${prevPlanId}`;
@@ -1338,8 +1427,6 @@ export function buildCommentBody(env = process.env) {
         lines.push("");
         lines.push("> Large diff — this recap is a **summarized** view (top files + schema/API deltas).");
     }
-    if (headShort)
-        lines.push("", `_As of \`${headShort}\`_`);
     lines.push("", `<!-- plan-id: ${planId} -->`);
     return lines.join("\n");
 }
@@ -1494,6 +1581,13 @@ export async function uploadRecapImage(input) {
 }
 /** Mirrors RECAP_IMAGE_MAX_BYTES on the server — the route rejects larger PNGs. */
 const RECAP_SHOT_MAX_BYTES = 5 * 1024 * 1024;
+const RECAP_SHOT_WIDTH = 950;
+const RECAP_SHOT_MAX_HEIGHT = 2000;
+const RECAP_SHOT_VIEWPORT = {
+    width: RECAP_SHOT_WIDTH,
+    height: RECAP_SHOT_MAX_HEIGHT,
+};
+const RECAP_SHOT_DEVICE_SCALE_FACTOR = 1;
 async function defaultImportPlaywright() {
     try {
         return (await import("playwright"));
@@ -1502,6 +1596,16 @@ async function defaultImportPlaywright() {
         return (await import("@playwright/test"));
     }
 }
+export function withRecapScreenshotParams(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.searchParams.set(RECAP_SCREENSHOT_QUERY_PARAM, "1");
+        return parsed.toString();
+    }
+    catch {
+        return url;
+    }
+}
 export async function runShot(args, 
 /** @internal test seam — defaults to dynamic playwright import */
 importPlaywright = defaultImportPlaywright) {
@@ -1534,6 +1638,7 @@ importPlaywright = defaultImportPlaywright) {
             return;
         }
     }
+    const captureUrl = withRecapScreenshotParams(url);
     let chromium;
     try {
         ({ chromium } = await importPlaywright());
@@ -1551,8 +1656,8 @@ importPlaywright = defaultImportPlaywright) {
     try {
         browser = await chromium.launch({ args: ["--no-sandbox"] });
         const context = await browser.newContext({
-            viewport: { width: 1450, height: 1450 },
-            deviceScaleFactor: 2,
+            viewport: RECAP_SHOT_VIEWPORT,
+            deviceScaleFactor: RECAP_SHOT_DEVICE_SCALE_FACTOR,
         });
         if (attachToken) {
             // Attach the bearer ONLY to same-origin requests. Context-wide
@@ -1573,7 +1678,7 @@ importPlaywright = defaultImportPlaywright) {
             });
         }
         const page = await context.newPage();
-        await page.goto(url, { waitUntil: "networkidle", timeout: 45_000 });
+        await page.goto(captureUrl, { waitUntil: "networkidle", timeout: 45_000 });
         const selectors = [
             "[data-plan-document]",
             "[data-plan-block]",
@@ -1593,63 +1698,53 @@ importPlaywright = defaultImportPlaywright) {
             }
         }
         await page.waitForTimeout(matched ? 1_200 : 500);
-        // Zoom out slightly so more content fits. Keep the plan title (h1) in frame:
-        // the recap reads better led by its own title than cropped to the body.
         await page.evaluate(() => {
-            document.documentElement.style.zoom = "90%";
+            document.documentElement.style.zoom = "100%";
         });
+        const measuredHeight = await page.evaluate((maxHeight) => {
+            const readHeights = (selectors) => {
+                const result = [];
+                for (const selector of selectors) {
+                    const el = document.querySelector(selector);
+                    if (!el)
+                        continue;
+                    const rect = el.getBoundingClientRect();
+                    result.push(el.scrollHeight, rect.top + el.scrollHeight);
+                }
+                return result;
+            };
+            const documentHeights = readHeights([
+                ".plan-document-shell",
+                ".plan-document-flow",
+            ]);
+            const contentHeights = documentHeights.some((height) => height > 0)
+                ? documentHeights
+                : readHeights(["[data-plan-document]", ".plan-content-surface"]);
+            const fallbackHeights = [
+                document.querySelector("[data-plan-reader]")
+                    ?.scrollHeight ?? 0,
+                document.scrollingElement?.scrollHeight ?? 0,
+                document.documentElement.scrollHeight,
+                document.body?.scrollHeight ?? 0,
+            ];
+            const heights = contentHeights.some((height) => height > 0)
+                ? contentHeights
+                : fallbackHeights;
+            const documentHeight = Math.ceil(Math.max(...heights.filter((height) => Number.isFinite(height))));
+            return Math.max(1, Math.min(maxHeight, documentHeight || maxHeight));
+        }, RECAP_SHOT_MAX_HEIGHT);
+        await page.setViewportSize({
+            width: RECAP_SHOT_WIDTH,
+            height: measuredHeight,
+        });
+        await page.waitForTimeout(250);
         await page.screenshot({ path: out });
-        // If the captured PNG is over the upload cap, retry at half the pixel
-        // density (deviceScaleFactor 1) to produce a smaller file.
+        // If the captured PNG is over the upload cap, remove it so the upload step
+        // sees no file and the comment falls back to a link-only recap.
         const firstSize = fs.existsSync(out) ? fs.statSync(out).size : 0;
         if (firstSize > RECAP_SHOT_MAX_BYTES) {
-            process.stderr.write(`[recap shot] PNG is ${firstSize} bytes (cap ${RECAP_SHOT_MAX_BYTES}) — retrying at deviceScaleFactor 1\n`);
-            const ctx2 = await browser.newContext({
-                viewport: { width: 1450, height: 1450 },
-                deviceScaleFactor: 1,
-            });
-            if (attachToken) {
-                const appOrigin = new URL(appUrl).origin;
-                await ctx2.route("**/*", async (route) => {
-                    const request = route.request();
-                    if (new URL(request.url()).origin === appOrigin) {
-                        await route.continue({
-                            headers: {
-                                ...request.headers(),
-                                authorization: `Bearer ${token}`,
-                            },
-                        });
-                    }
-                    else {
-                        await route.continue();
-                    }
-                });
-            }
-            const page2 = await ctx2.newPage();
-            await page2.goto(url, { waitUntil: "networkidle", timeout: 45_000 });
-            for (const sel of selectors) {
-                try {
-                    await page2.waitForSelector(sel, {
-                        timeout: 6_000,
-                        state: "visible",
-                    });
-                    break;
-                }
-                catch {
-                    /* try the next selector */
-                }
-            }
-            await page2.waitForTimeout(matched ? 1_200 : 500);
-            await page2.evaluate(() => {
-                document.documentElement.style.zoom = "90%";
-            });
-            await page2.screenshot({ path: out });
-            const retrySize = fs.existsSync(out) ? fs.statSync(out).size : 0;
-            if (retrySize > RECAP_SHOT_MAX_BYTES) {
-                process.stderr.write(`[recap shot] retry PNG is still ${retrySize} bytes — skipping upload\n`);
-                // Remove oversized file so the upload step sees no file.
-                fs.unlinkSync(out);
-            }
+            process.stderr.write(`[recap shot] PNG is ${firstSize} bytes (cap ${RECAP_SHOT_MAX_BYTES}) — skipping upload\n`);
+            fs.unlinkSync(out);
         }
         captured = fs.existsSync(out);
         await browser.close();
@@ -1703,7 +1798,7 @@ async function runComment(args, sub) {
         process.stdout.write(`${JSON.stringify(result)}\n`);
         return;
     }
-    throw new Error("Usage: agent-native recap comment <find-plan-id|upsert> --repo owner/name --issue n --token token");
+    throw new Error("Usage: npx @agent-native/core@latest recap comment <find-plan-id|upsert> --repo owner/name --issue n --token token");
 }
 /**
  * Files that, if a PR touches them, would let that PR rewrite what the trusted
@@ -2023,7 +2118,9 @@ export function recapCheckOutcome(input) {
     let conclusion = "neutral";
     let title = "Visual recap not generated";
     let summary = "The visual recap did not produce a plan URL. This is informational only and does not block the PR.";
-    let text = "";
+    let text = input.failureSummary
+        ? `Agent output: ${sanitizeAgentFailureSummary(input.failureSummary)}`
+        : "";
     let detailsUrl = input.workflowUrl;
     if (input.planOk) {
         const recapUrl = canonicalRecapUrl(input.planUrl, input.appUrl);
@@ -2049,6 +2146,7 @@ export function recapCheckOutcome(input) {
         conclusion = "skipped";
         title = "Visual recap skipped";
         summary = "The diff is too small to need a visual recap.";
+        text = "";
     }
     else if (input.suppressed) {
         let reason = "potential secret in diff";
@@ -2063,6 +2161,11 @@ export function recapCheckOutcome(input) {
         conclusion = "skipped";
         title = "Visual recap suppressed";
         summary = `No recap was published because ${reason}.`;
+        text = "";
+    }
+    else if (input.failureSummary) {
+        summary =
+            "The visual recap agent ran but did not produce a plan URL. See the agent output below.";
     }
     return { conclusion, title, summary, text, detailsUrl };
 }
@@ -2134,6 +2237,7 @@ async function runCheckComplete(args) {
         tiny: boolFlag(args, "tiny"),
         suppressed: boolFlag(args, "suppressed"),
         suppressedJson: optionalArg(args, "suppressed-json") ?? "",
+        failureSummary: optionalArg(args, "failure-summary") ?? "",
         workflowUrl: optionalArg(args, "workflow-url") ?? "",
     });
     try {
@@ -2169,7 +2273,7 @@ async function runCheck(args, sub) {
         await runCheckComplete(args);
         return;
     }
-    throw new Error("Usage: agent-native recap check <start|complete> [flags] (see `recap help`)");
+    throw new Error("Usage: npx @agent-native/core@latest recap check <start|complete> [flags] (see `recap help`)");
 }
 /** Parse the last top-level JSON object from a possibly-noisy stdout dump. */
 function parseLastJsonObject(text) {
@@ -2342,30 +2446,52 @@ async function runUsage(args) {
         done({ ok: false, reason: `record-recap-usage error: ${String(err)}` });
     }
 }
-const HELP = `agent-native recap — PR visual recap helpers (used by the GitHub Action)
+function writeGitHubOutput(name, value) {
+    const out = process.env.GITHUB_OUTPUT;
+    if (!out)
+        return;
+    const delimiter = `__RECAP_${name}_${process.pid}_${Date.now()}__`;
+    fs.appendFileSync(out, `${name}<<${delimiter}\n${value}\n${delimiter}\n`);
+}
+function runAgentSummary(args) {
+    const agent = optionalArg(args, "agent") ?? "claude";
+    const resultFile = stringArg(args, "result-file");
+    let raw = "";
+    try {
+        raw = fs.readFileSync(path.resolve(resultFile), "utf8");
+    }
+    catch (err) {
+        raw = `could not read ${resultFile}: ${String(err)}`;
+    }
+    const summary = summarizeAgentResult(agent, raw);
+    writeGitHubOutput("summary", summary);
+    process.stdout.write(`${JSON.stringify({ ok: Boolean(summary), summary })}\n`);
+}
+const HELP = `npx @agent-native/core@latest recap — PR visual recap helpers (used by the GitHub Action)
 
 Usage:
-  agent-native recap setup [--repo owner/name] [--agent claude|codex] [--app-url <url>] [--skip-secrets] [--dry-run] [--force]
-  agent-native recap doctor [--repo owner/name] [--agent claude|codex] [--app-url <url>]
-  agent-native recap collect-diff --base <baseSha> --head <headSha> [--out recap.diff] [--stat recap.stat]
-  agent-native recap mcp-config --agent claude|codex --app-url <url> [--out <path>]
-  agent-native recap scan --diff <path>
-  agent-native recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
-  agent-native recap shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png]
-  agent-native recap usage --plan-url <planUrl> --result-file <path> --app-url <url> --token <planToken> [--agent claude|codex] [--model <id>]
-  agent-native recap comment <find-plan-id|upsert> --repo owner/name --issue <n> --token <github-token>
-  agent-native recap check start [--repo owner/name] [--sha <headSha>] [--token <github-token>] [--workflow-url <url>]
+  npx @agent-native/core@latest recap setup [--repo owner/name] [--agent claude|codex] [--app-url <url>] [--skip-secrets] [--dry-run] [--force]
+  npx @agent-native/core@latest recap doctor [--repo owner/name] [--agent claude|codex] [--app-url <url>]
+  npx @agent-native/core@latest recap collect-diff --base <baseSha> --head <headSha> [--out recap.diff] [--stat recap.stat]
+  npx @agent-native/core@latest recap mcp-config --agent claude|codex --app-url <url> [--out <path>]
+  npx @agent-native/core@latest recap scan --diff <path>
+  npx @agent-native/core@latest recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
+  npx @agent-native/core@latest recap shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png]
+  npx @agent-native/core@latest recap usage --plan-url <planUrl> --result-file <path> --app-url <url> --token <planToken> [--agent claude|codex] [--model <id>]
+  npx @agent-native/core@latest recap agent-summary --result-file <path> [--agent claude|codex]
+  npx @agent-native/core@latest recap comment <find-plan-id|upsert> --repo owner/name --issue <n> --token <github-token>
+  npx @agent-native/core@latest recap check start [--repo owner/name] [--sha <headSha>] [--token <github-token>] [--workflow-url <url>]
     Create the in-progress "Visual Recap" GitHub check run and write its id to
     $GITHUB_OUTPUT (check_run_id). repo/sha/token default to GITHUB_REPOSITORY /
     HEAD_SHA / GH_TOKEN (or GITHUB_TOKEN). Best-effort: warns and exits 0 on any
     API error without emitting an id.
-  agent-native recap check complete --check-run-id <id> [--repo owner/name] [--token <github-token>] [--plan-ok <bool>] [--plan-url <url>] [--app-url <url>] [--suppressed <bool>] [--suppressed-json <json>] [--huge <bool>] [--tiny <bool>] [--workflow-url <url>]
+  npx @agent-native/core@latest recap check complete --check-run-id <id> [--repo owner/name] [--token <github-token>] [--plan-ok <bool>] [--plan-url <url>] [--app-url <url>] [--suppressed <bool>] [--suppressed-json <json>] [--huge <bool>] [--tiny <bool>] [--workflow-url <url>]
     Mark the "Visual Recap" check run completed with a computed
     conclusion/title/summary/text/details_url (success when the agent published a
     plan whose URL validates against --app-url; neutral/skipped otherwise).
     repo/token/app-url default to GITHUB_REPOSITORY / GH_TOKEN / PLAN_RECAP_APP_URL.
     Best-effort: warns and exits 0 on any API error.
-  agent-native recap gate
+  npx @agent-native/core@latest recap gate
     The PR Visual Recap security gate. Decides whether to run the recap at all
     and which (normalized) backend agent to use. Reads the pull_request payload
     from $GITHUB_EVENT_PATH, the secret-presence/agent/model signals from the
@@ -2377,12 +2503,16 @@ Usage:
     packages/core, .claude/**, CLAUDE.md, AGENTS.md, .mcp.json) — failing CLOSED
     on any file-list error. Writes run=<true|false> and agent=<claude|codex> to
     $GITHUB_OUTPUT.
-  agent-native recap setup
+  npx @agent-native/core@latest recap agent-summary
+    Read the captured Claude/Codex result file and write a sanitized one-line
+    summary to stdout and $GITHUB_OUTPUT (summary). Used only when no plan URL
+    was produced, so PR comments/checks explain the actual failure.
+  npx @agent-native/core@latest recap setup
     Write/refresh .github/workflows/pr-visual-recap.yml, then configure GitHub
     Actions secrets and variables with gh when values are available from env or
     the local Plans publish-token store. Missing values are printed as exact next
     commands; secret values are sent to gh through stdin, never argv.
-  agent-native recap doctor
+  npx @agent-native/core@latest recap doctor
     Check workflow presence/drift, local Plans publish-token availability, gh
     repo access, and required GitHub Actions secrets for the selected backend.
 `;
@@ -2414,6 +2544,9 @@ export async function runRecap(argv) {
         case "usage":
             await runUsage(args);
             return;
+        case "agent-summary":
+            runAgentSummary(args);
+            return;
         case "comment":
             await runComment(parseArgs(rest.slice(1)), rest[0] ?? "");
             return;