@agent-native/core 0.49.2 → 0.49.4

package/dist/cli/recap.js

@@ -125,10 +125,8 @@ export function writePrVisualRecapWorkflow(baseDir, options = {}) {
  */
 export function buildReusableCallerWorkflow(options = {}) {
     const ref = (options.ref ?? "main").replace(/^@/, "");
-    const agentLine = options.agent && options.agent !== "claude"
-        ? `\n          agent: ${options.agent}`
-        : "";
-    const modelLine = options.model ? `\n          model: ${options.model}` : "";
+    const agentValue = options.agent ?? "${{ vars.VISUAL_RECAP_AGENT || 'claude' }}";
+    const modelValue = options.model ?? "${{ vars.VISUAL_RECAP_MODEL || '' }}";
     return (`name: PR Visual Recap\n` +
         `\n` +
         `# Thin caller — the full workflow logic lives in BuilderIO/agent-native.\n` +
@@ -142,16 +140,25 @@ export function buildReusableCallerWorkflow(options = {}) {
         `\n` +
         `jobs:\n` +
         `  visual-recap:\n` +
+        `    permissions:\n` +
+        `      actions: write\n` +
+        `      contents: read\n` +
+        `      checks: write\n` +
+        `      issues: write\n` +
+        `      pull-requests: write\n` +
         `    uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@${ref}\n` +
         `    secrets:\n` +
         `      PLAN_RECAP_TOKEN: \${{ secrets.PLAN_RECAP_TOKEN }}\n` +
         `      ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}\n` +
-        `      # OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}  # only when agent: codex\n` +
-        `      # PLAN_RECAP_APP_URL: \${{ secrets.PLAN_RECAP_APP_URL }}  # only when self-hosting\n` +
-        `    with:${agentLine}${modelLine}\n` +
+        `      OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}\n` +
+        `      PLAN_RECAP_APP_URL: \${{ secrets.PLAN_RECAP_APP_URL }}\n` +
+        `    with:\n` +
+        `      agent: ${agentValue}\n` +
+        `      model: ${modelValue}\n` +
+        `      reasoning: \${{ vars.VISUAL_RECAP_REASONING || '' }}\n` +
+        `      skill-source: \${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}\n` +
         `      # cli-version: "latest"  # pin to a specific @agent-native/core version\n` +
-        `      # reasoning: "high"      # codex only: none|minimal|low|medium|high|xhigh\n` +
-        `      # skill-source: "repo"   # pin to committed visual-recap skill\n`);
+        ``);
 }
 /** File name for the reusable caller workflow. */
 const REUSABLE_CALLER_WORKFLOW_FILE = "pr-visual-recap.yml";
@@ -650,20 +657,23 @@ export function diffContainsSecret(diffText, allowlist = []) {
     return false;
 }
 const AGENT_FAILURE_MAX_CHARS = 1200;
+const STALE_WORKFLOW_FAILURE_SUMMARY = "No agent failure summary was captured. This repo may be using an older PR Visual Recap workflow; refresh `.github/workflows/pr-visual-recap.yml` with `npx -y @agent-native/core@latest recap setup --force`, then rerun the workflow. See the GitHub Actions log for the agent step.";
 function compactWhitespace(text) {
     return text.replace(/\s+/g, " ").trim();
 }
 export function sanitizeAgentFailureSummary(value, maxChars = AGENT_FAILURE_MAX_CHARS) {
+    const redactSecretValues = (line) => line
+        .replace(/Authorization:\s*Bearer\s+[A-Za-z0-9._-]{8,}/gi, "Authorization: Bearer [redacted]")
+        .replace(/Bearer\s+[A-Za-z0-9._-]{8,}/gi, "Bearer [redacted]")
+        .replace(/Authorization:\s*(?!Bearer\s+\[redacted\])[^\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]");
     const sanitizedLines = value
         .replace(/\u001b\[[0-9;]*m/g, "")
         .split("\n")
+        .map(redactSecretValues)
         .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)
@@ -689,6 +699,21 @@ function collectStringFields(value, fields, seen = new Set()) {
     }
     return out;
 }
+function isUsefulAgentSummaryCandidate(candidate) {
+    const value = candidate.trim();
+    if (!value)
+        return false;
+    if (/^(turn|session|item|response|task)\.[a-z0-9_.-]+$/i.test(value)) {
+        return false;
+    }
+    if (/^(success|completed|result|message|error)$/i.test(value)) {
+        return false;
+    }
+    return value.length > 12;
+}
+function isErrorLikeAgentSummary(candidate) {
+    return /error|failed|denied|not found|unavailable|unauthorized|forbidden|tool|exception|timeout|timed out|could not|cannot/i.test(candidate);
+}
 export function summarizeAgentResult(agent, resultText) {
     const normalizedAgent = agent.toLowerCase();
     const text = resultText.trim();
@@ -707,7 +732,10 @@ export function summarizeAgentResult(agent, resultText) {
                     "type",
                 ]),
             ].filter(Boolean);
-            const preferred = candidates.find((candidate) => /error|failed|denied|not found|unavailable|unauthorized|forbidden|tool/i.test(candidate)) ?? candidates[0];
+            const usefulCandidates = candidates.filter(isUsefulAgentSummaryCandidate);
+            const preferred = usefulCandidates.find(isErrorLikeAgentSummary) ??
+                usefulCandidates[0] ??
+                candidates.find(isErrorLikeAgentSummary);
             if (preferred)
                 return sanitizeAgentFailureSummary(preferred);
         }
@@ -726,7 +754,13 @@ export function summarizeAgentResult(agent, resultText) {
                     "text",
                     "delta",
                     "reason",
-                    "type",
+                    "detail",
+                    "details",
+                    "stderr",
+                    "stdout",
+                    "summary",
+                    "result",
+                    "content",
                 ]));
             }
             catch {
@@ -734,13 +768,88 @@ export function summarizeAgentResult(agent, resultText) {
             }
         }
         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];
+        const usefulCandidates = newestFirst.filter(isUsefulAgentSummaryCandidate);
+        const preferred = usefulCandidates.find(isErrorLikeAgentSummary) ?? usefulCandidates[0];
         if (preferred)
             return sanitizeAgentFailureSummary(preferred);
     }
     return sanitizeAgentFailureSummary(text);
 }
+function agentLabel(agent) {
+    const normalized = agent.toLowerCase();
+    if (normalized === "codex")
+        return "Codex";
+    if (normalized === "claude")
+        return "Claude";
+    return agent || "Agent";
+}
+export function summarizeAgentRun(input) {
+    const parts = [];
+    const exitCode = (input.exitCode ?? "").trim();
+    if (exitCode && exitCode !== "0") {
+        parts.push(`${agentLabel(input.agent)} exited with code ${exitCode}.`);
+    }
+    const resultSummary = summarizeAgentResult(input.agent, input.resultText ?? "");
+    if (resultSummary)
+        parts.push(resultSummary);
+    const stderrSummary = sanitizeAgentFailureSummary(input.stderrText ?? "", 500);
+    if (stderrSummary)
+        parts.push(`stderr: ${stderrSummary}`);
+    return sanitizeAgentFailureSummary(parts.join(" "));
+}
+function readTextIfExists(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function localAgentResultCandidates(agent) {
+    const all = [
+        {
+            agent: "claude",
+            resultFile: "claude-result.json",
+            stderrFile: "claude-stderr.log",
+            exitCodeFile: "claude-exit-code.txt",
+        },
+        {
+            agent: "codex",
+            resultFile: "codex-events.jsonl",
+            stderrFile: "codex-stderr.log",
+            exitCodeFile: "codex-exit-code.txt",
+        },
+    ];
+    const normalized = agent.toLowerCase();
+    if (normalized === "codex")
+        return [all[1], all[0]];
+    return all;
+}
+export function summarizeLocalAgentFailure(input = {}) {
+    const cwd = input.cwd ?? process.cwd();
+    for (const candidate of localAgentResultCandidates(input.agent ?? "")) {
+        const resultPath = path.join(cwd, candidate.resultFile);
+        const stderrPath = path.join(cwd, candidate.stderrFile);
+        const exitCodePath = path.join(cwd, candidate.exitCodeFile);
+        const resultText = readTextIfExists(resultPath);
+        const stderrText = readTextIfExists(stderrPath);
+        const exitCode = readTextIfExists(exitCodePath);
+        if (resultText === null && stderrText === null && exitCode === null) {
+            continue;
+        }
+        const summary = summarizeAgentRun({
+            agent: candidate.agent,
+            resultText: resultText ?? "",
+            stderrText: stderrText ?? "",
+            exitCode: exitCode ?? "",
+        });
+        if (summary)
+            return summary;
+    }
+    return "";
+}
 /* -------------------------------------------------------------------------- */
 /* Bounded diff collection — was the workflow's "Collect bounded diff" step    */
 /* -------------------------------------------------------------------------- */
@@ -1385,17 +1494,22 @@ 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);
+        const diagnostic = buildRecapFailureDiagnostic({
+            failureSummary: (env.RECAP_AGENT_SUMMARY || "").trim(),
+            urlReason: (env.RECAP_URL_REASON || "").trim(),
+        });
         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 `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.");
+            lines.push("Recap authentication failed — the `PLAN_RECAP_TOKEN` secret may be expired or revoked. Re-mint it with `npx -y @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) {
+            if (diagnostic) {
                 lines.push("");
-                lines.push(`Agent output: ${agentSummary}`);
+                lines.push("Diagnostic:");
+                lines.push("");
+                lines.push(diagnostic);
             }
         }
         // Keep a link to the last-good recap so reviewers are not left in the dark.
@@ -1587,7 +1701,7 @@ const RECAP_SHOT_VIEWPORT = {
     width: RECAP_SHOT_WIDTH,
     height: RECAP_SHOT_MAX_HEIGHT,
 };
-const RECAP_SHOT_DEVICE_SCALE_FACTOR = 1;
+const RECAP_SHOT_DEVICE_SCALE_FACTOR = 2;
 async function defaultImportPlaywright() {
     try {
         return (await import("playwright"));
@@ -1792,7 +1906,7 @@ async function runComment(args, sub) {
             owner,
             repo,
             issue,
-            body: buildCommentBody(),
+            body: buildCommentBody(recoverRecapFailureEnv()),
             updateOnly: args["update-only"] === true || args["update-only"] === "true",
         });
         process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -1800,6 +1914,30 @@ async function runComment(args, sub) {
     }
     throw new Error("Usage: npx @agent-native/core@latest recap comment <find-plan-id|upsert> --repo owner/name --issue n --token token");
 }
+function shouldRecoverRecapFailureDetails(env) {
+    return (!(env.PLAN_URL || "").trim() &&
+        env.DIFF_TINY !== "true" &&
+        env.SUPPRESSED !== "true");
+}
+function recoverRecapFailureEnv(env = process.env) {
+    if (!shouldRecoverRecapFailureDetails(env))
+        return env;
+    const recovered = { ...env };
+    if (!recovered.RECAP_AGENT_SUMMARY) {
+        recovered.RECAP_AGENT_SUMMARY = summarizeLocalAgentFailure({
+            agent: recovered.RECAP_AGENT || recovered.VISUAL_RECAP_AGENT,
+        });
+    }
+    if (!recovered.RECAP_URL_REASON) {
+        recovered.RECAP_URL_REASON = inferLocalRecapUrlFailureReason({
+            appUrl: recovered.PLAN_RECAP_APP_URL,
+        });
+    }
+    if (!recovered.RECAP_AGENT_SUMMARY && !recovered.RECAP_URL_REASON) {
+        recovered.RECAP_AGENT_SUMMARY = STALE_WORKFLOW_FAILURE_SUMMARY;
+    }
+    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
@@ -2085,8 +2223,10 @@ export function appendGateSkipLine(existingBody, skipLine) {
  */
 export function canonicalRecapUrl(rawUrl, appUrl) {
     try {
-        const parsed = new URL(rawUrl);
         const trusted = new URL(appUrl || "https://plan.agent-native.com");
+        const parsed = /^https?:\/\//i.test(rawUrl)
+            ? new URL(rawUrl)
+            : new URL(rawUrl, trusted);
         if (parsed.origin !== trusted.origin)
             return "";
         // Honor a path-prefixed mount (e.g. https://host/agent-native): strip the
@@ -2102,6 +2242,43 @@ export function canonicalRecapUrl(rawUrl, appUrl) {
         return "";
     }
 }
+export function inferLocalRecapUrlFailureReason(input = {}) {
+    const recapUrlPath = path.join(input.cwd ?? process.cwd(), "recap-url.txt");
+    const raw = readTextIfExists(recapUrlPath);
+    if (raw === null)
+        return "recap-url.txt was not created by the agent.";
+    const value = raw.replace(/[\r\n\s]/g, "");
+    if (!value)
+        return "recap-url.txt was empty.";
+    const appUrl = input.appUrl ||
+        process.env.PLAN_RECAP_APP_URL ||
+        "https://plan.agent-native.com";
+    if (canonicalRecapUrl(value, appUrl))
+        return "";
+    try {
+        const trusted = new URL(appUrl || "https://plan.agent-native.com");
+        const parsed = /^https?:\/\//i.test(value)
+            ? new URL(value)
+            : new URL(value, trusted);
+        if (parsed.origin !== trusted.origin) {
+            return `recap-url.txt points at ${parsed.origin}, expected ${trusted.origin}.`;
+        }
+        return "recap-url.txt did not contain a valid /plans/<id> or /recaps/<id> URL for the configured plan app.";
+    }
+    catch {
+        return "recap-url.txt was not a valid URL or recap path.";
+    }
+}
+export function buildRecapFailureDiagnostic(input) {
+    const parts = [];
+    const urlReason = sanitizeAgentFailureSummary(input.urlReason ?? "", 400);
+    const failureSummary = sanitizeAgentFailureSummary(input.failureSummary ?? "", 900);
+    if (urlReason)
+        parts.push(`No plan URL: ${urlReason}`);
+    if (failureSummary)
+        parts.push(`Agent output: ${failureSummary}`);
+    return parts.join("\n\n");
+}
 /**
  * Map the workflow's terminal recap state to the completed check's
  * conclusion/title/summary/text/details_url. Pure so it can be unit-tested —
@@ -2118,9 +2295,11 @@ 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 = input.failureSummary
-        ? `Agent output: ${sanitizeAgentFailureSummary(input.failureSummary)}`
-        : "";
+    const diagnostic = buildRecapFailureDiagnostic({
+        failureSummary: input.failureSummary,
+        urlReason: input.urlReason,
+    });
+    let text = diagnostic ? `### Diagnostic\n\n${diagnostic}` : "";
     let detailsUrl = input.workflowUrl;
     if (input.planOk) {
         const recapUrl = canonicalRecapUrl(input.planUrl, input.appUrl);
@@ -2163,9 +2342,9 @@ export function recapCheckOutcome(input) {
         summary = `No recap was published because ${reason}.`;
         text = "";
     }
-    else if (input.failureSummary) {
+    else if (diagnostic) {
         summary =
-            "The visual recap agent ran but did not produce a plan URL. See the agent output below.";
+            "The visual recap agent ran but did not produce a plan URL. See diagnostics below.";
     }
     return { conclusion, title, summary, text, detailsUrl };
 }
@@ -2229,15 +2408,39 @@ async function runCheckComplete(args) {
         process.env.GITHUB_TOKEN ||
         "";
     const checkRunId = optionalArg(args, "check-run-id") ?? "";
+    const planOk = boolFlag(args, "plan-ok");
+    const huge = boolFlag(args, "huge");
+    const tiny = boolFlag(args, "tiny");
+    const suppressed = boolFlag(args, "suppressed");
+    const appUrl = optionalArg(args, "app-url") ?? process.env.PLAN_RECAP_APP_URL ?? "";
+    let failureSummary = optionalArg(args, "failure-summary") ?? "";
+    let urlReason = optionalArg(args, "url-reason") ?? "";
+    if (!planOk && !tiny && !suppressed) {
+        if (!failureSummary) {
+            failureSummary = summarizeLocalAgentFailure({
+                agent: optionalArg(args, "agent") ??
+                    process.env.RECAP_AGENT ??
+                    process.env.VISUAL_RECAP_AGENT ??
+                    "",
+            });
+        }
+        if (!urlReason) {
+            urlReason = inferLocalRecapUrlFailureReason({ appUrl });
+        }
+        if (!failureSummary && !urlReason) {
+            failureSummary = STALE_WORKFLOW_FAILURE_SUMMARY;
+        }
+    }
     const outcome = recapCheckOutcome({
-        planOk: boolFlag(args, "plan-ok"),
+        planOk,
         planUrl: optionalArg(args, "plan-url") ?? "",
-        appUrl: optionalArg(args, "app-url") ?? process.env.PLAN_RECAP_APP_URL ?? "",
-        huge: boolFlag(args, "huge"),
-        tiny: boolFlag(args, "tiny"),
-        suppressed: boolFlag(args, "suppressed"),
+        appUrl,
+        huge,
+        tiny,
+        suppressed,
         suppressedJson: optionalArg(args, "suppressed-json") ?? "",
-        failureSummary: optionalArg(args, "failure-summary") ?? "",
+        failureSummary,
+        urlReason,
         workflowUrl: optionalArg(args, "workflow-url") ?? "",
     });
     try {
@@ -2456,6 +2659,8 @@ function writeGitHubOutput(name, value) {
 function runAgentSummary(args) {
     const agent = optionalArg(args, "agent") ?? "claude";
     const resultFile = stringArg(args, "result-file");
+    const stderrFile = optionalArg(args, "stderr-file");
+    const exitCodeFile = optionalArg(args, "exit-code-file");
     let raw = "";
     try {
         raw = fs.readFileSync(path.resolve(resultFile), "utf8");
@@ -2463,7 +2668,18 @@ function runAgentSummary(args) {
     catch (err) {
         raw = `could not read ${resultFile}: ${String(err)}`;
     }
-    const summary = summarizeAgentResult(agent, raw);
+    const stderrText = stderrFile
+        ? (readTextIfExists(path.resolve(stderrFile)) ?? "")
+        : "";
+    const exitCode = exitCodeFile
+        ? (readTextIfExists(path.resolve(exitCodeFile)) ?? "")
+        : "";
+    const summary = summarizeAgentRun({
+        agent,
+        resultText: raw,
+        stderrText,
+        exitCode,
+    });
     writeGitHubOutput("summary", summary);
     process.stdout.write(`${JSON.stringify({ ok: Boolean(summary), summary })}\n`);
 }
@@ -2478,14 +2694,14 @@ Usage:
   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 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>
   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.
-  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>]
+  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>] [--failure-summary <text>] [--url-reason <text>] [--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).