@agent-native/core 0.94.2 → 0.95.0

package/dist/cli/recap.js

@@ -37,6 +37,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { normalizeOpenAiBaseUrl } from "../agent/engine/openai-compatible-endpoint.js";
 import { DEFAULT_PLAN_APP_URL, fetchPlanBlockCatalog, planActionEndpoint, } from "./plan-blocks.js";
 import { readPlanPublishAuth } from "./plan-publish-store.js";
 import { PR_VISUAL_RECAP_WORKFLOW_YML } from "./pr-visual-recap-workflow.js";
@@ -82,7 +83,9 @@ export const PR_VISUAL_RECAP_SETUP = [
     "  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",
-    "  VISUAL_RECAP_MODEL / VISUAL_RECAP_REASONING (variables) — pin the model (e.g. gpt-5.6-sol) and reasoning depth (none|minimal|low|medium|high|xhigh; Codex only)",
+    "  VISUAL_RECAP_API_KEY (secret) + VISUAL_RECAP_AGENT=openai-compatible + VISUAL_RECAP_BASE_URL (variable) — use DeepSeek, Kimi, or any OpenAI-compatible API",
+    "  VISUAL_RECAP_MODEL (variable, required for openai-compatible) — provider model id; optional override for Claude/Codex",
+    "  VISUAL_RECAP_REASONING (variable) — reasoning depth (none|minimal|low|medium|high|xhigh; Codex only)",
     "  VISUAL_RECAP_SKILL_SOURCE=repo (variable) — pin CI to the repo-local visual-recap skill instead of latest bundled guidance",
     "  VISUAL_RECAP_SECRET_SCAN=off|high-confidence|strict (variable) — default high-confidence; strict restores generic TOKEN/SECRET assignment suppression",
     "  PLAN_RECAP_APP_URL (secret) — only when self-hosting the plan app (defaults to https://plan.agent-native.com)",
@@ -154,10 +157,12 @@ export function buildReusableCallerWorkflow(options = {}) {
         `      PLAN_RECAP_TOKEN: \${{ secrets.PLAN_RECAP_TOKEN }}\n` +
         `      ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}\n` +
         `      OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}\n` +
+        `      VISUAL_RECAP_API_KEY: \${{ secrets.VISUAL_RECAP_API_KEY }}\n` +
         `      PLAN_RECAP_APP_URL: \${{ secrets.PLAN_RECAP_APP_URL }}\n` +
         `    with:\n` +
         `      agent: ${agentValue}\n` +
         `      model: ${modelValue}\n` +
+        `      base-url: \${{ vars.VISUAL_RECAP_BASE_URL || '' }}\n` +
         `      reasoning: \${{ vars.VISUAL_RECAP_REASONING || '' }}\n` +
         `      skill-source: \${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}\n` +
         `      secret-scan: \${{ vars.VISUAL_RECAP_SECRET_SCAN || 'high-confidence' }}\n` +
@@ -202,12 +207,19 @@ export function normalizeRecapAgent(value) {
         return "codex";
     if (agent === "claude")
         return "claude";
-    throw new Error(`Unsupported recap agent "${value}" (expected "claude" or "codex").`);
+    if (["openai-compatible", "deepseek", "kimi", "moonshot", "custom"].includes(agent)) {
+        return "openai-compatible";
+    }
+    throw new Error(`Unsupported recap agent "${value}" (expected "claude", "codex", or "openai-compatible").`);
 }
 export function recapRequiredSecrets(agent) {
     return [
         "PLAN_RECAP_TOKEN",
-        agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY",
+        agent === "codex"
+            ? "OPENAI_API_KEY"
+            : agent === "openai-compatible"
+                ? "VISUAL_RECAP_API_KEY"
+                : "ANTHROPIC_API_KEY",
     ];
 }
 function recapWorkflowFile(baseDir) {
@@ -338,13 +350,60 @@ function setGithubVariable(name, value, repo, dryRun) {
         args.push("--repo", repo);
     return gh(args).ok ? "set" : "failed";
 }
+const OPENAI_COMPATIBLE_VARIABLE_REQUIREMENTS = [
+    {
+        name: "VISUAL_RECAP_BASE_URL",
+        example: "https://provider.example/v1",
+    },
+    { name: "VISUAL_RECAP_MODEL", example: "provider-model-id" },
+];
+const RECAP_MODEL_PATTERN = /^[a-zA-Z0-9._-]{1,80}$/;
+const OPENAI_COMPATIBLE_RECAP_MODEL_PATTERN = /^[^\p{C}\p{Z}]{1,200}$/u;
+export function validateOpenAiCompatibleRecapVariables(input) {
+    const [baseUrlRequirement, modelRequirement] = OPENAI_COMPATIBLE_VARIABLE_REQUIREMENTS;
+    const problems = [];
+    const baseUrl = input.baseUrl?.trim() || "";
+    const rawModel = input.model || "";
+    const model = rawModel.trim();
+    try {
+        const parsed = normalizeOpenAiBaseUrl(baseUrl);
+        if (!parsed)
+            throw new Error("empty");
+    }
+    catch {
+        problems.push({
+            requirement: baseUrlRequirement,
+            reason: "VISUAL_RECAP_BASE_URL must be a valid http(s) URL without credentials",
+        });
+    }
+    if (!model) {
+        problems.push({
+            requirement: modelRequirement,
+            reason: "VISUAL_RECAP_MODEL is required (openai-compatible backend)",
+        });
+    }
+    else if (!OPENAI_COMPATIBLE_RECAP_MODEL_PATTERN.test(rawModel)) {
+        problems.push({
+            requirement: modelRequirement,
+            reason: "invalid VISUAL_RECAP_MODEL value (must be 1-200 characters without whitespace or controls)",
+        });
+    }
+    return problems;
+}
 export function buildRecapSetupPlan(input) {
     const env = input.env ?? process.env;
     const appUrl = stripTrailingSlash(input.appUrl || env.PLAN_RECAP_APP_URL || DEFAULT_RECAP_APP_URL);
     const agent = normalizeRecapAgent(input.agent || env.VISUAL_RECAP_AGENT);
     const requiredSecrets = recapRequiredSecrets(agent);
+    const requiredVariables = agent === "openai-compatible"
+        ? OPENAI_COMPATIBLE_VARIABLE_REQUIREMENTS
+        : [];
     const planToken = envValue(env, "PLAN_RECAP_TOKEN") ?? planTokenFromLocalStore(appUrl);
-    const llmSecretName = agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+    const llmSecretName = agent === "codex"
+        ? "OPENAI_API_KEY"
+        : agent === "openai-compatible"
+            ? "VISUAL_RECAP_API_KEY"
+            : "ANTHROPIC_API_KEY";
     const variableValues = {};
     if (agent !== "claude")
         variableValues.VISUAL_RECAP_AGENT = agent;
@@ -357,6 +416,17 @@ export function buildRecapSetupPlan(input) {
         if (value)
             variableValues[key] = value;
     }
+    if (agent === "openai-compatible") {
+        const baseUrl = envValue(env, "VISUAL_RECAP_BASE_URL");
+        if (baseUrl)
+            variableValues.VISUAL_RECAP_BASE_URL = baseUrl;
+    }
+    const variableProblems = agent === "openai-compatible"
+        ? validateOpenAiCompatibleRecapVariables({
+            baseUrl: variableValues.VISUAL_RECAP_BASE_URL,
+            model: variableValues.VISUAL_RECAP_MODEL,
+        })
+        : [];
     return {
         agent,
         appUrl,
@@ -364,6 +434,8 @@ export function buildRecapSetupPlan(input) {
         workflowPath: path.relative(input.baseDir, recapWorkflowFile(input.baseDir)),
         workflowExists: fs.existsSync(recapWorkflowFile(input.baseDir)),
         requiredSecrets,
+        requiredVariables,
+        variableProblems,
         variableValues,
         secretValues: {
             PLAN_RECAP_TOKEN: planToken,
@@ -469,7 +541,10 @@ function runSetup(args) {
                 lines.push(`    Set manually: ${commandForMissingSecret(name, repo)}`);
             }
         }
+        const invalidVariableNames = new Set(plan.variableProblems.map((problem) => problem.requirement.name));
         for (const [name, value] of Object.entries(plan.variableValues)) {
+            if (invalidVariableNames.has(name))
+                continue;
             const status = setGithubVariable(name, value, repo, dryRun);
             if (status === "set") {
                 lines.push(`  ${name}: set to ${value}.`);
@@ -482,6 +557,13 @@ function runSetup(args) {
                 lines.push(`    Set manually: ${commandForMissingVariable(name, value, repo)}`);
             }
         }
+        for (const problem of plan.variableProblems) {
+            const { requirement } = problem;
+            const hasValue = Boolean(plan.variableValues[requirement.name]);
+            lines.push(`  ${requirement.name}: ${hasValue ? "invalid value" : "missing value"}.`);
+            lines.push(`    ${problem.reason}.`);
+            lines.push(`    Set manually: ${commandForMissingVariable(requirement.name, requirement.example, repo)}`);
+        }
     }
     lines.push("");
     lines.push(`Next: commit ${plan.workflowPath}, then run npx @agent-native/core@latest recap doctor.`);
@@ -558,6 +640,28 @@ function runDoctor(args) {
     else {
         const configuredAgent = variables.get("VISUAL_RECAP_AGENT") || "claude";
         lines.push(`[ok] Recap backend variable: ${configuredAgent}.`);
+        const remoteVariableProblems = plan.agent === "openai-compatible"
+            ? validateOpenAiCompatibleRecapVariables({
+                baseUrl: variables.get("VISUAL_RECAP_BASE_URL"),
+                model: variables.get("VISUAL_RECAP_MODEL"),
+            })
+            : [];
+        const problemsByName = new Map(remoteVariableProblems.map((problem) => [
+            problem.requirement.name,
+            problem,
+        ]));
+        for (const requirement of plan.requiredVariables) {
+            const problem = problemsByName.get(requirement.name);
+            if (!problem) {
+                lines.push(`[ok] GitHub variable configured: ${requirement.name}.`);
+            }
+            else {
+                ok = false;
+                const hasValue = Boolean(variables.get(requirement.name)?.trim());
+                lines.push(`[${hasValue ? "invalid" : "missing"}] ${problem.reason}.`);
+                lines.push(`  Set it with: ${commandForMissingVariable(requirement.name, requirement.example, repo)}`);
+            }
+        }
     }
     process.stdout.write(`${lines.join("\n")}\n`);
     if (!ok)
@@ -810,6 +914,8 @@ function agentLabel(agent) {
         return "Codex";
     if (normalized === "claude")
         return "Claude";
+    if (normalized === "openai-compatible")
+        return "OpenAI-compatible";
     return agent || "Agent";
 }
 export function summarizeAgentRun(input) {
@@ -850,10 +956,18 @@ function localAgentResultCandidates(agent) {
             stderrFile: "codex-stderr.log",
             exitCodeFile: "codex-exit-code.txt",
         },
+        {
+            agent: "openai-compatible",
+            resultFile: "openai-compatible-result.txt",
+            stderrFile: "openai-compatible-stderr.log",
+            exitCodeFile: "openai-compatible-exit-code.txt",
+        },
     ];
     const normalized = agent.toLowerCase();
     if (normalized === "codex")
-        return [all[1], all[0]];
+        return [all[1], all[0], all[2]];
+    if (normalized === "openai-compatible")
+        return [all[2], all[0], all[1]];
     return all;
 }
 export function summarizeLocalAgentFailure(input = {}) {
@@ -2599,22 +2713,35 @@ export function evaluateRecapGate(input) {
     // The chosen backend's API key must be present. Normalize the agent value once
     // here and validate it: an unknown or mis-cased value (e.g. "Claude", "gpt")
     // must NOT silently pass the gate and then match neither agent step.
-    const agent = (input.agentRaw || "claude").toLowerCase();
-    if (agent !== "claude" && agent !== "codex") {
-        reasons.push(`unsupported VISUAL_RECAP_AGENT "${input.agentRaw}" (expected "claude" or "codex")`);
+    const rawAgent = (input.agentRaw || "claude").toLowerCase();
+    const agent = ["deepseek", "kimi", "moonshot", "custom"].includes(rawAgent)
+        ? "openai-compatible"
+        : rawAgent;
+    if (!["claude", "codex", "openai-compatible"].includes(agent)) {
+        reasons.push(`unsupported VISUAL_RECAP_AGENT "${input.agentRaw}" (expected "claude", "codex", or "openai-compatible")`);
     }
     else if (agent === "codex") {
         if (!input.hasOpenai)
             reasons.push("OPENAI_API_KEY not configured (codex backend)");
     }
-    else {
+    else if (agent === "claude") {
         if (!input.hasAnthropic)
             reasons.push("ANTHROPIC_API_KEY not configured (claude backend)");
     }
+    else {
+        if (!input.hasOpenaiCompatible)
+            reasons.push("VISUAL_RECAP_API_KEY not configured (openai-compatible backend)");
+        reasons.push(...validateOpenAiCompatibleRecapVariables({
+            baseUrl: input.baseUrl,
+            model: input.model,
+        }).map((problem) => problem.reason));
+    }
     // Validate VISUAL_RECAP_MODEL if set — an unchecked value could be injected by
     // a repo settings writer and passed straight to the agent CLI.
     const model = input.model || "";
-    if (model && !/^[a-zA-Z0-9._-]{1,80}$/.test(model)) {
+    if (agent !== "openai-compatible" &&
+        model &&
+        !RECAP_MODEL_PATTERN.test(model)) {
         reasons.push("invalid VISUAL_RECAP_MODEL value (must match [a-zA-Z0-9._-]{1,80})");
     }
     const skillSource = normalizeRecapSkillSourceMode(input.skillSource);
@@ -2729,8 +2856,10 @@ async function runGate() {
         hasPlan: process.env.HAS_PLAN === "true",
         hasAnthropic: process.env.HAS_ANTHROPIC === "true",
         hasOpenai: process.env.HAS_OPENAI === "true",
+        hasOpenaiCompatible: process.env.HAS_COMPATIBLE === "true",
         agentRaw: process.env.AGENT,
         model: process.env.VISUAL_RECAP_MODEL,
+        baseUrl: process.env.VISUAL_RECAP_BASE_URL,
         skillSource: process.env.VISUAL_RECAP_SKILL_SOURCE,
         changedFiles,
     });
@@ -3190,6 +3319,41 @@ export function parseCodexUsage(jsonl) {
         model: typeof u.model === "string" ? u.model : undefined,
     };
 }
+/** Parse the usage sidecar emitted by an Agent-Native Code run. */
+export function parseOpenAiCompatibleUsage(json) {
+    const obj = parseLastJsonObject(json);
+    const usage = obj?.usage ?? obj;
+    if (!usage || typeof usage !== "object")
+        return null;
+    const input = usage.inputTokens ?? usage.input_tokens ?? usage.prompt_tokens ?? undefined;
+    const output = usage.outputTokens ??
+        usage.output_tokens ??
+        usage.completion_tokens ??
+        undefined;
+    if (input == null && output == null)
+        return null;
+    const asCount = (value) => {
+        const parsed = Number(value ?? 0);
+        return Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
+    };
+    const inputDetails = usage.inputTokenDetails;
+    return {
+        inputTokens: asCount(input),
+        outputTokens: asCount(output),
+        cacheReadTokens: asCount(usage.cacheReadTokens ??
+            usage.cachedInputTokens ??
+            usage.cache_read_input_tokens ??
+            inputDetails?.cacheReadTokens),
+        cacheWriteTokens: asCount(usage.cacheWriteTokens ??
+            usage.cache_write_tokens ??
+            inputDetails?.cacheWriteTokens),
+        model: typeof obj?.model === "string"
+            ? obj.model
+            : typeof usage.model === "string"
+                ? usage.model
+                : undefined,
+    };
+}
 /**
  * `recap usage` — parse the agent's run output for token usage and POST it to
  * the plan app's record-recap-usage action so the recap row carries cost. The
@@ -3214,7 +3378,12 @@ async function runUsage(args) {
     let parsed = null;
     try {
         const raw = fs.readFileSync(path.resolve(stringArg(args, "result-file")), "utf8");
-        parsed = agent === "codex" ? parseCodexUsage(raw) : parseClaudeUsage(raw);
+        parsed =
+            agent === "codex"
+                ? parseCodexUsage(raw)
+                : agent === "openai-compatible"
+                    ? parseOpenAiCompatibleUsage(raw)
+                    : parseClaudeUsage(raw);
     }
     catch (err) {
         done({ ok: false, reason: `could not read/parse usage: ${String(err)}` });
@@ -3228,10 +3397,17 @@ async function runUsage(args) {
     // the pinned --model (VISUAL_RECAP_MODEL) and finally the documented default.
     const model = parsed.model ??
         optionalArg(args, "model") ??
-        (agent === "codex" ? "gpt-5.6-sol" : "claude");
+        (agent === "codex"
+            ? "gpt-5.6-sol"
+            : agent === "openai-compatible"
+                ? "openai-compatible"
+                : "claude");
+    const usageAgent = agent === "claude" || agent === "codex" || agent === "openai-compatible"
+        ? agent
+        : undefined;
     const body = {
         planId,
-        ...(agent === "codex" || agent === "claude" ? { agent } : {}),
+        ...(usageAgent ? { agent: usageAgent } : {}),
         model,
         inputTokens: parsed.inputTokens,
         outputTokens: parsed.outputTokens,
@@ -3302,16 +3478,16 @@ function runAgentSummary(args) {
 const HELP = `npx @agent-native/core@latest recap — PR visual recap helpers (used by the GitHub Action)
 
 Usage:
-  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 setup [--repo owner/name] [--agent claude|codex|openai-compatible] [--app-url <url>] [--skip-secrets] [--dry-run] [--force]
+  npx @agent-native/core@latest recap doctor [--repo owner/name] [--agent claude|codex|openai-compatible] [--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 block-reference [--app-url <url>] [--out recap-blocks.md]
   npx @agent-native/core@latest recap scan --diff <path> [--mode off|high-confidence|strict]
   npx @agent-native/core@latest recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--block-reference recap-blocks.md] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
   npx @agent-native/core@latest recap publish [--source recap-source.json] [--out recap-url.txt] [--repo owner/name] [--pr <n>] [--prev-plan-id <id>] [--source-pr-state open|closed|merged] [--source-pr-merged-at <iso>] [--source-author-email <email>] [--source-author-name <name>] [--source-author-login <login>] [--app-url <url>] [--token <planToken>] [--github-token <ghToken>]
   npx @agent-native/core@latest recap shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png] [--theme light|dark] [--image-cache-key <key>]
-  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 usage --plan-url <planUrl> --result-file <path> --app-url <url> --token <planToken> [--agent claude|codex|openai-compatible] [--model <id>]
+  npx @agent-native/core@latest recap agent-summary --result-file <path> [--stderr-file <path>] [--exit-code-file <path>] [--agent claude|codex|openai-compatible]
   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
@@ -3328,16 +3504,16 @@ Usage:
     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
-    environment (HAS_PLAN / HAS_ANTHROPIC / HAS_OPENAI === 'true', AGENT,
-    VISUAL_RECAP_MODEL), the repo from $GITHUB_REPOSITORY, and the PR's changed
+    environment (HAS_PLAN / HAS_ANTHROPIC / HAS_OPENAI / HAS_COMPATIBLE === 'true', AGENT,
+    VISUAL_RECAP_MODEL / VISUAL_RECAP_BASE_URL), the repo from $GITHUB_REPOSITORY, and the PR's changed
     files from the GitHub REST API (paged, with GH_TOKEN/GITHUB_TOKEN). Skips
     drafts, forks without secret access, bot authors, the missing-secret case, an
     invalid agent/model, and any untrusted PR that touches recap-control files
     (repo-pinned skill instructions, .claude/**, root CLAUDE.md, root AGENTS.md,
     root .mcp.json) — failing CLOSED on any file-list error. Writes
-    run=<true|false> and agent=<claude|codex> to $GITHUB_OUTPUT.
+    run=<true|false> and agent=<claude|codex|openai-compatible> to $GITHUB_OUTPUT.
   npx @agent-native/core@latest recap agent-summary
-    Read the captured Claude/Codex result file and write a sanitized one-line
+    Read the captured agent 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 scan
@@ -3358,7 +3534,8 @@ Usage:
     commands; secret values are sent to gh through stdin, never argv.
   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.
+    repo access, and required GitHub Actions secrets and variables for the
+    selected backend, including provider-variable validity.
 `;
 export async function runRecap(argv) {
     const [sub, ...rest] = argv;