@agent-native/core 0.49.8 → 0.49.10

package/dist/cli/recap.js

@@ -192,6 +192,7 @@ export function writePrVisualRecapReusableCallerWorkflow(baseDir, options = {})
     return { status: "written", path: rel, existed: false };
 }
 const DEFAULT_RECAP_APP_URL = "https://plan.agent-native.com";
+const RECAP_MCP_CLIENT_HEADER = "agent-native-pr-visual-recap";
 export function normalizeRecapAgent(value) {
     const agent = (value || "claude").toLowerCase();
     if (agent === "codex")
@@ -1088,7 +1089,11 @@ export function buildRecapClaudeMcpConfig(appUrl, token) {
             plan: {
                 type: "http",
                 url,
-                headers: { Authorization: "Bearer " + token },
+                headers: {
+                    Authorization: "Bearer " + token,
+                    "X-Agent-Native-MCP-Client": RECAP_MCP_CLIENT_HEADER,
+                    "X-Agent-Native-MCP-Full-Catalog": "1",
+                },
             },
         },
     });
@@ -1105,7 +1110,8 @@ export function buildRecapCodexMcpConfig(appUrl) {
         "url = " +
         JSON.stringify(url) +
         "\n" +
-        'bearer_token_env_var = "PLAN_RECAP_TOKEN"\n');
+        'bearer_token_env_var = "PLAN_RECAP_TOKEN"\n' +
+        'http_headers = { "X-Agent-Native-MCP-Client" = "agent-native-pr-visual-recap", "X-Agent-Native-MCP-Full-Catalog" = "1" }\n');
 }
 /**
  * `recap mcp-config` — write the plan MCP client config for the chosen backend,
@@ -1319,6 +1325,7 @@ export function buildRecapPrompt(input) {
     else {
         lines.push("## Publish (this is the only way to produce output)");
         lines.push(`The \`plan\` MCP server is configured for you. Call its tools by name (your host may expose them as \`get-plan-blocks\` / \`create-visual-recap\` or \`mcp__plan__get-plan-blocks\` / \`mcp__plan__create-visual-recap\` — same tools).`);
+        lines.push("This is a one-shot GitHub Actions run. Do not wait, sleep, back off, schedule wakeups, reminders, follow-ups, or retries in another turn. Either publish the recap and write `recap-url.txt` in this process, or report the MCP/tool failure plainly.");
         lines.push("First call `get-plan-blocks`, then call `create-visual-recap`. If `create-visual-recap` is available but `get-plan-blocks` is not, the Plan MCP is connected but the block-registry tool is not visible to this runner. Report that the runner must expose `get-plan-blocks` through the workflow/tool allowlist or compact MCP catalog; do not describe that case as a disconnected Plan MCP.");
         lines.push(`1. Call the **create-visual-recap** tool on the \`plan\` MCP server with grounded MDX derived ONLY from the real diff, passing \`visibility: "org"\` so the recap is published org-scoped (never public) server-side${input.prevPlanId
             ? `, and also passing \`planId: "${input.prevPlanId}"\` so this REPLACES the existing recap plan`
@@ -1349,6 +1356,9 @@ 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";
+const RECAP_SCREENSHOT_THEME_QUERY_PARAM = "recapScreenshotTheme";
+const GITHUB_LIGHT_CANVAS_BACKGROUND = "#ffffff";
+const GITHUB_DARK_CANVAS_BACKGROUND = "#0d1117";
 function repoParts(repoFullName) {
     const [owner, repo] = repoFullName.split("/");
     if (!owner || !repo)
@@ -1436,6 +1446,14 @@ function originOf(url) {
         return "";
     }
 }
+function trustedRecapImageUrl(raw, base) {
+    const value = (raw || "").trim();
+    return value &&
+        sameOrigin(value, base) &&
+        RECAP_IMAGE_URL_PATH_PATTERN.test(value)
+        ? value
+        : "";
+}
 /** Build the sticky comment body from the workflow's environment. */
 export function buildCommentBody(env = process.env) {
     const lines = [MARKER];
@@ -1512,28 +1530,29 @@ export function buildCommentBody(env = process.env) {
                 lines.push(diagnostic);
             }
         }
-        // Keep a link to the last-good recap so reviewers are not left in the dark.
-        if (prevPlanId && base) {
-            const prevSafeUrl = `${base}/recaps/${prevPlanId}`;
-            lines.push("", `Previous recap (from an earlier push): [Open recap](${prevSafeUrl})`);
-        }
         if (markerPlanId)
             lines.push("", `<!-- plan-id: ${markerPlanId} -->`);
         return lines.join("\n");
     }
-    // The image URL is produced by our own recap-image route, but validate it is
+    // Image URLs are produced by our own recap-image route, but validate each is
     // same-origin and matches the canonical hex-token path before embedding it, so
-    // it likewise cannot inject markdown.
-    const imageUrlRaw = (env.RECAP_IMAGE_URL || "").trim();
-    const imageUrl = imageUrlRaw &&
-        sameOrigin(imageUrlRaw, base) &&
-        RECAP_IMAGE_URL_PATH_PATTERN.test(imageUrlRaw)
-        ? imageUrlRaw
-        : "";
+    // they likewise cannot inject markdown or HTML.
+    const lightImageUrl = trustedRecapImageUrl(env.RECAP_LIGHT_IMAGE_URL || env.RECAP_IMAGE_URL, base);
+    const darkImageUrl = trustedRecapImageUrl(env.RECAP_DARK_IMAGE_URL, base);
+    const fallbackImageUrl = lightImageUrl || darkImageUrl;
     lines.push(`### Here's a [visual recap](${safeUrl}) of what changed:`);
     lines.push("");
-    if (imageUrl) {
-        lines.push(`[![Visual recap](${imageUrl})](${safeUrl})`);
+    if (lightImageUrl && darkImageUrl) {
+        lines.push(`<a href="${safeUrl}">`);
+        lines.push(`<picture>`);
+        lines.push(`  <source media="(prefers-color-scheme: dark)" srcset="${darkImageUrl}">`);
+        lines.push(`  <img alt="Visual recap" src="${lightImageUrl}">`);
+        lines.push(`</picture>`);
+        lines.push(`</a>`);
+        lines.push("");
+    }
+    else if (fallbackImageUrl) {
+        lines.push(`[![Visual recap](${fallbackImageUrl})](${safeUrl})`);
         lines.push("");
     }
     lines.push(`**[Open the full interactive recap](${safeUrl})**`);
@@ -1710,10 +1729,25 @@ async function defaultImportPlaywright() {
         return (await import("@playwright/test"));
     }
 }
-export function withRecapScreenshotParams(url) {
+function parseRecapScreenshotTheme(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "light" || value === "dark")
+        return value;
+    throw new Error("--theme must be light or dark.");
+}
+function recapScreenshotBackground(theme) {
+    return theme === "dark"
+        ? GITHUB_DARK_CANVAS_BACKGROUND
+        : GITHUB_LIGHT_CANVAS_BACKGROUND;
+}
+export function withRecapScreenshotParams(url, options = {}) {
     try {
         const parsed = new URL(url);
         parsed.searchParams.set(RECAP_SCREENSHOT_QUERY_PARAM, "1");
+        if (options.theme) {
+            parsed.searchParams.set(RECAP_SCREENSHOT_THEME_QUERY_PARAM, options.theme);
+        }
         return parsed.toString();
     }
     catch {
@@ -1727,6 +1761,7 @@ importPlaywright = defaultImportPlaywright) {
     const out = optionalArg(args, "out") ?? "recap.png";
     const token = optionalArg(args, "token");
     const appUrl = optionalArg(args, "app-url");
+    const theme = parseRecapScreenshotTheme(optionalArg(args, "theme"));
     const done = (obj) => {
         process.stdout.write(`${JSON.stringify(obj)}\n`);
     };
@@ -1752,7 +1787,7 @@ importPlaywright = defaultImportPlaywright) {
             return;
         }
     }
-    const captureUrl = withRecapScreenshotParams(url);
+    const captureUrl = withRecapScreenshotParams(url, { theme });
     let chromium;
     try {
         ({ chromium } = await importPlaywright());
@@ -1772,7 +1807,33 @@ importPlaywright = defaultImportPlaywright) {
         const context = await browser.newContext({
             viewport: RECAP_SHOT_VIEWPORT,
             deviceScaleFactor: RECAP_SHOT_DEVICE_SCALE_FACTOR,
+            ...(theme ? { colorScheme: theme } : {}),
         });
+        if (theme) {
+            await context.addInitScript(({ background, nextTheme }) => {
+                const applyTheme = () => {
+                    try {
+                        window.localStorage.setItem("theme", nextTheme);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    const root = document.documentElement;
+                    root.classList.remove("light", "dark");
+                    root.classList.add(nextTheme);
+                    root.setAttribute("data-theme", nextTheme);
+                    root.style.colorScheme = nextTheme;
+                    root.style.backgroundColor = background;
+                    if (document.body) {
+                        document.body.style.backgroundColor = background;
+                    }
+                };
+                applyTheme();
+                document.addEventListener("DOMContentLoaded", applyTheme, {
+                    once: true,
+                });
+            }, { background: recapScreenshotBackground(theme), nextTheme: theme });
+        }
         if (attachToken) {
             // Attach the bearer ONLY to same-origin requests. Context-wide
             // extraHTTPHeaders would also send it to every cross-origin subresource
@@ -1812,9 +1873,23 @@ importPlaywright = defaultImportPlaywright) {
             }
         }
         await page.waitForTimeout(matched ? 1_200 : 500);
-        await page.evaluate(() => {
+        await page.evaluate((background) => {
             document.documentElement.style.zoom = "100%";
-        });
+            if (!background)
+                return;
+            const root = document.documentElement;
+            root.style.backgroundColor = background;
+            document.body.style.backgroundColor = background;
+            for (const selector of [
+                ".plans-workspace",
+                "[data-plan-reader]",
+                "[data-plan-document]",
+            ]) {
+                const el = document.querySelector(selector);
+                if (el)
+                    el.style.backgroundColor = background;
+            }
+        }, theme ? recapScreenshotBackground(theme) : "");
         const measuredHeight = await page.evaluate((maxHeight) => {
             const readHeights = (selectors) => {
                 const result = [];
@@ -1939,18 +2014,13 @@ function recoverRecapFailureEnv(env = process.env) {
     return recovered;
 }
 /**
- * Files that, if a PR touches them, would let that PR rewrite what the trusted
- * recap job runs (the workflow itself, the skill, the local CLI, or any agent
- * config the runner loads) — so the whole job is skipped, not just the agent
- * step, to keep untrusted PR code away from the publish/API secrets.
- *
- * The `packages/core/**` rule is scoped to the BuilderIO/agent-native monorepo
- * (where packages/core IS the recap CLI source) so that consumer repos with an
- * unrelated `packages/core/` directory are not silently gated. Pass the
- * `repository` ("owner/name") to apply that scoping; omit it to match the old
- * unconditional behaviour (safe for the gate's self-test).
+ * Files that, if a PR touches them, would let that PR rewrite the workflow,
+ * skill, or agent config the trusted recap job loads. The workflow runs the
+ * recap CLI from trusted base-branch source (or an installed package), so normal
+ * package code such as `packages/core/**` can be recapped without executing
+ * PR-modified CLI code.
  */
-export function isRecapSensitivePath(p, repository) {
+export function isRecapSensitivePath(p) {
     if (p === ".github/workflows/pr-visual-recap.yml" ||
         /(^|\/)skills\/visual-(recap|plan|plans)\//.test(p) ||
         /(^|\/)\.claude\//.test(p) ||
@@ -1959,12 +2029,6 @@ export function isRecapSensitivePath(p, repository) {
         /(^|\/)\.mcp\.json$/.test(p)) {
         return true;
     }
-    // packages/core is the recap-CLI source only in the agent-native monorepo.
-    // In consumer repos an unrelated packages/core/ must not gate recaps.
-    const isAgentNativeMonorepo = !repository || repository === "BuilderIO/agent-native";
-    if (isAgentNativeMonorepo && /(^|\/)packages\/core\//.test(p)) {
-        return true;
-    }
     return false;
 }
 /**
@@ -2025,11 +2089,11 @@ export function evaluateRecapGate(input) {
         reasons.push("invalid VISUAL_RECAP_MODEL value (must match [a-zA-Z0-9._-]{1,80})");
     }
     // Self-modifying guard: if this PR changes the workflow, the
-    // visual-recap/visual-plan skill, the local CLI (packages/core), or any agent
-    // config the runner would load (.claude/**, CLAUDE.md, .mcp.json), skip the
-    // ENTIRE job — not just the agent — so a PR can never rewrite what runs
-    // (skill, hooks, settings, CLI) and exfiltrate the publish/API secrets.
-    const hits = input.changedFiles.filter((p) => isRecapSensitivePath(p, input.repository));
+    // visual-recap/visual-plan skill, or any agent config the runner would load
+    // (.claude/**, CLAUDE.md, .mcp.json), skip the ENTIRE job — not just the
+    // agent — so a PR can never rewrite what runs (skill, hooks, settings) and
+    // exfiltrate the publish/API secrets.
+    const hits = input.changedFiles.filter((p) => isRecapSensitivePath(p));
     if (hits.length) {
         reasons.push(`PR modifies recap-control files (${hits.slice(0, 3).join(", ")}${hits.length > 3 ? ", …" : ""}) — skipping so untrusted PR code never runs with secrets`);
     }
@@ -2692,7 +2756,7 @@ Usage:
   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 shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png] [--theme light|dark]
   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> [--stderr-file <path>] [--exit-code-file <path>] [--agent claude|codex]
   npx @agent-native/core@latest recap comment <find-plan-id|upsert> --repo owner/name --issue <n> --token <github-token>
@@ -2716,8 +2780,8 @@ Usage:
     files from the GitHub REST API (paged, with GH_TOKEN/GITHUB_TOKEN). Skips
     drafts, forks, bot authors, the missing-secret case, an invalid agent/model,
     and any PR that touches recap-control files (the workflow, the skill,
-    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
+    .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.
   npx @agent-native/core@latest recap agent-summary
     Read the captured Claude/Codex result file and write a sanitized one-line