ShockVPN/shockbot
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: adapt pullfrog for gitea + ollama

Browse Source
This commit is contained in:
wolfy
2026-05-31 01:01:00 -05:00
parent 36ac64a5b6
commit 2aca1a3aa3
183 changed files with 1419 additions and 28292 deletions
Download Patch File Download Diff File Expand all files Collapse all files
utils/agent.test.ts
-198
View File
@@ -1,198 +0,0 @@
import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { resolveAgent, resolveModel } from "./agent.ts";
import { cleanupVertexCredentials, materializeVertexCredentials } from "./vertex.ts";
const savedEnv = { ...process.env };
const STRIPPED = [
/_API_KEY$/,
/^CLAUDE_CODE_OAUTH_TOKEN$/,
/^AWS_BEARER_TOKEN_BEDROCK$/,
/^AWS_ACCESS_KEY_ID$/,
/^AWS_SECRET_ACCESS_KEY$/,
/^AWS_SESSION_TOKEN$/,
/^AWS_REGION$/,
/^BEDROCK_MODEL_ID$/,
/^GOOGLE_APPLICATION_CREDENTIALS$/,
/^GOOGLE_CLOUD_PROJECT$/,
/^VERTEX_SERVICE_ACCOUNT_JSON$/,
/^VERTEX_LOCATION$/,
/^VERTEX_MODEL_ID$/,
/^PULLFROG_SECRET_HOME$/,
/^PULLFROG_MODEL$/,
/^PULLFROG_AGENT$/,
];
beforeEach(() => {
for (const key of Object.keys(process.env)) {
if (STRIPPED.some((re) => re.test(key))) delete process.env[key];
}
});
afterEach(() => {
process.env = { ...savedEnv };
});
describe("resolveAgent", () => {
it("returns opencode by default", () => {
expect(resolveAgent({}).name).toBe("opencode");
});
it("routes anthropic/* to claude when ANTHROPIC_API_KEY is set", () => {
process.env.ANTHROPIC_API_KEY = "sk-test";
expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("claude");
});
it("falls back to opencode for anthropic/* without claude-code creds", () => {
expect(resolveAgent({ model: "anthropic/claude-opus-4-7" }).name).toBe("opencode");
});
describe("bedrock routing", () => {
it("routes Anthropic Bedrock IDs to claude", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveAgent({ model: "us.anthropic.claude-opus-4-7" }).name).toBe("claude");
});
it("routes Anthropic Bedrock IDs (no region prefix) to claude", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.BEDROCK_MODEL_ID = "anthropic.claude-haiku-4-5-20251001-v1:0";
expect(resolveAgent({ model: "anthropic.claude-haiku-4-5-20251001-v1:0" }).name).toBe(
"claude"
);
});
it("routes non-Anthropic Bedrock IDs to opencode", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.BEDROCK_MODEL_ID = "amazon.nova-pro-v1:0";
expect(resolveAgent({ model: "amazon.nova-pro-v1:0" }).name).toBe("opencode");
});
it("routes Llama IDs to opencode", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.BEDROCK_MODEL_ID = "us.meta.llama4-scout-17b-instruct-v1:0";
expect(resolveAgent({ model: "us.meta.llama4-scout-17b-instruct-v1:0" }).name).toBe(
"opencode"
);
});
it("accepts AWS access keys as auth", () => {
process.env.AWS_ACCESS_KEY_ID = "AKIA-test";
process.env.AWS_SECRET_ACCESS_KEY = "secret-test";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveAgent({ model: "us.anthropic.claude-opus-4-7" }).name).toBe("claude");
});
it("PULLFROG_AGENT override wins over Anthropic auto-routing", () => {
process.env.PULLFROG_AGENT = "opencode";
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveAgent({ model: "us.anthropic.claude-opus-4-7" }).name).toBe("opencode");
});
});
describe("vertex routing", () => {
it("routes Anthropic Vertex IDs to claude", () => {
process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
expect(resolveAgent({ model: "claude-opus-4-1@20250805" }).name).toBe("claude");
});
it("routes Gemini Vertex IDs to opencode", () => {
process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
expect(resolveAgent({ model: "gemini-2.5-pro" }).name).toBe("opencode");
});
});
});
describe("resolveModel", () => {
it("PULLFROG_MODEL override wins", () => {
process.env.PULLFROG_MODEL = "anthropic/claude-opus";
expect(resolveModel({ slug: "openai/gpt" })).toBe("anthropic/claude-opus-4-7");
});
it("PULLFROG_MODEL bypasses bedrock routing entirely", () => {
process.env.PULLFROG_MODEL = "openai/gpt";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveModel({ slug: "bedrock/byok" })).toBe("openai/gpt-5.5");
});
it("resolves bedrock/byok to BEDROCK_MODEL_ID", () => {
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveModel({ slug: "bedrock/byok" })).toBe("us.anthropic.claude-opus-4-7");
});
it("throws when bedrock/byok is selected without BEDROCK_MODEL_ID", () => {
expect(() => resolveModel({ slug: "bedrock/byok" })).toThrow("BEDROCK_MODEL_ID");
});
it("returns the alias resolve for normal slugs", () => {
expect(resolveModel({ slug: "openai/gpt" })).toBe("openai/gpt-5.5");
});
it("returns undefined for no slug + no PULLFROG_MODEL", () => {
expect(resolveModel({})).toBeUndefined();
});
// regression: PR #720 review caught that `resolveCliModel("bedrock/byok")`
// returns the literal sentinel `"bedrock"` from the alias's `resolve`
// field. Without routing-aware handling, PULLFROG_MODEL=bedrock/byok would
// leak that sentinel downstream and break agent dispatch.
it("PULLFROG_MODEL=bedrock/byok defers to BEDROCK_MODEL_ID, not the sentinel", () => {
process.env.PULLFROG_MODEL = "bedrock/byok";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(resolveModel({ slug: "openai/gpt" })).toBe("us.anthropic.claude-opus-4-7");
});
it("PULLFROG_MODEL=bedrock/byok throws if BEDROCK_MODEL_ID is missing", () => {
process.env.PULLFROG_MODEL = "bedrock/byok";
expect(() => resolveModel({ slug: "openai/gpt" })).toThrow("BEDROCK_MODEL_ID");
});
it("resolves vertex/byok to VERTEX_MODEL_ID", () => {
process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
expect(resolveModel({ slug: "vertex/byok" })).toBe("claude-opus-4-1@20250805");
});
it("throws when vertex/byok is selected without VERTEX_MODEL_ID", () => {
expect(() => resolveModel({ slug: "vertex/byok" })).toThrow("VERTEX_MODEL_ID");
});
it("PULLFROG_MODEL=vertex/byok defers to VERTEX_MODEL_ID, not the sentinel", () => {
process.env.PULLFROG_MODEL = "vertex/byok";
process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
expect(resolveModel({ slug: "openai/gpt" })).toBe("gemini-2.5-pro");
});
});
describe("materializeVertexCredentials", () => {
it("writes service-account JSON outside tmpdir and defaults project from project_id", () => {
const dir = mkdtempSync(join(tmpdir(), "vertex-creds-test-"));
process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
process.env.PULLFROG_SECRET_HOME = dir;
process.env.VERTEX_SERVICE_ACCOUNT_JSON = JSON.stringify({
project_id: "test-project",
client_email: "pullfrog@test-project.iam.gserviceaccount.com",
});
try {
const credentials = materializeVertexCredentials({ model: "claude-opus-4-1@20250805" });
if (!credentials) throw new Error("expected vertex credentials");
expect(credentials.credentialsPath).toContain(join(dir, ".pullfrog", "secrets"));
expect(process.env.GOOGLE_APPLICATION_CREDENTIALS).toBe(credentials.credentialsPath);
expect(process.env.GOOGLE_CLOUD_PROJECT).toBe("test-project");
expect(readFileSync(credentials.credentialsPath, "utf8")).toBe(
process.env.VERTEX_SERVICE_ACCOUNT_JSON
);
expect(statSync(credentials.credentialsPath).mode & 0o777).toBe(0o600);
cleanupVertexCredentials(credentials);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
utils/agent.ts
-139
View File
@@ -1,139 +0,0 @@
import type { Agent } from "../agents/index.ts";
import { agents } from "../agents/index.ts";
import {
BEDROCK_MODEL_ID_ENV,
getModelProvider,
isBedrockAnthropicId,
isVertexAnthropicId,
resolveCliModel,
resolveDisplayAlias,
VERTEX_MODEL_ID_ENV,
} from "../models.ts";
import { log } from "./cli.ts";
import { VERTEX_SERVICE_ACCOUNT_JSON_ENV } from "./vertex.ts";
function hasEnvVar(name: string): boolean {
const val = process.env[name];
return typeof val === "string" && val.length > 0;
}
function hasClaudeCodeAuth(): boolean {
return hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN") || hasEnvVar("ANTHROPIC_API_KEY");
}
function hasBedrockAuth(): boolean {
return (
hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") ||
(hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY"))
);
}
function hasVertexAuth(): boolean {
return hasEnvVar(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
}
/**
* resolve a single slug to its CLI-ready model string. routing aliases
* (e.g. `bedrock/byok`) defer to their backing env var instead of the
* sentinel stored in `resolve`. shared between PULLFROG_MODEL override
* and repo-config slug resolution so both paths get the same routing
* semantics — without this helper, `PULLFROG_MODEL=bedrock/byok` would
* leak the literal sentinel string `"bedrock"` downstream.
*/
function resolveSlug(slug: string): string | undefined {
const alias = resolveDisplayAlias(slug);
if (alias?.routing === "bedrock") {
const bedrockId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
if (!bedrockId) {
throw new Error(
`${BEDROCK_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
`set it to an AWS Bedrock model ID from the Bedrock console. ` +
`see https://docs.pullfrog.com/bedrock for setup.`
);
}
return bedrockId;
}
if (alias?.routing === "vertex") {
const vertexId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
if (!vertexId) {
throw new Error(
`${VERTEX_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
`set it to a Google Vertex AI model ID from Model Garden. ` +
`see https://docs.pullfrog.com/vertex for setup.`
);
}
return vertexId;
}
return resolveCliModel(slug);
}
/**
* resolve the effective model for this run.
*
* priority:
* 1. PULLFROG_MODEL env var — resolved through the alias registry first,
* so values like "anthropic/claude-opus" become "anthropic/claude-opus-4-7".
* raw specifiers (e.g. "anthropic/claude-opus-4-6") pass through unchanged.
* always wins — bypasses Bedrock routing entirely. to test a different
* Bedrock model, change `BEDROCK_MODEL_ID`, not `PULLFROG_MODEL`.
* 2. slug from repo config / payload → alias registry. routing slugs
* (e.g. `bedrock/byok`) defer to a separate env var (`BEDROCK_MODEL_ID`).
* 3. undefined — agent will auto-select.
*/
export function resolveModel(ctx: { slug?: string | undefined }): string | undefined {
const envModel = process.env.PULLFROG_MODEL?.trim();
if (envModel) {
return resolveSlug(envModel) ?? envModel;
}
if (ctx.slug) {
const resolved = resolveSlug(ctx.slug);
if (resolved) {
return resolved;
}
log.warning(`» unknown model slug "${ctx.slug}" — agent will auto-select`);
}
return undefined;
}
export function resolveAgent(ctx: { model?: string | undefined }): Agent {
// 1. explicit env var override (escape hatch)
const envAgent = process.env.PULLFROG_AGENT?.trim();
if (envAgent) {
if (envAgent in agents) {
return agents[envAgent as keyof typeof agents];
}
log.warning(`» unknown PULLFROG_AGENT="${envAgent}" — falling through to auto-select`);
}
// 2. Bedrock routing: when BEDROCK_MODEL_ID is the resolved model, route
// Anthropic IDs through claude-code (which supports Bedrock natively
// once CLAUDE_CODE_USE_BEDROCK=1) and everything else through opencode's
// `amazon-bedrock` provider.
if (ctx.model && hasBedrockAuth() && process.env[BEDROCK_MODEL_ID_ENV]?.trim() === ctx.model) {
return isBedrockAnthropicId(ctx.model) ? agents.claude : agents.opencode;
}
// 3. Vertex routing: same shape as Bedrock, but Anthropic Vertex IDs are
// anchored `claude-*` IDs and non-Anthropic models use opencode's
// `google-vertex` provider.
if (ctx.model && hasVertexAuth() && process.env[VERTEX_MODEL_ID_ENV]?.trim() === ctx.model) {
return isVertexAnthropicId(ctx.model) ? agents.claude : agents.opencode;
}
// 4. if model is Anthropic and Claude Code credentials are available, use Claude Code
if (ctx.model) {
try {
const provider = getModelProvider(ctx.model);
if (provider === "anthropic" && hasClaudeCodeAuth()) {
return agents.claude;
}
} catch {
// invalid model format — fall through
}
}
// 5. default: OpenCode (universal, supports all providers)
return agents.opencode;
}
utils/agentHangReport.ts
-170
View File
@@ -1,170 +0,0 @@
const MAX_STDERR_BYTES = 3000;
/**
* mutable per-run handle the agent harness writes to as a run progresses.
* the action's outer try/catch in `main.ts` reads this off `toolState` when
* the activity-timeout watchdog wins the race against the harness's own
* catch — the bare timer reject reason ("activity timeout: no output for
* 302s") tells the user nothing actionable, but `recentStderr` +
* `lastProviderError` together usually point straight at the upstream cause.
*
* `recentStderr` is shared by reference with the harness's bounded ring
* buffer, so the diagnostic always reflects the latest captured tail.
*/
export type AgentDiagnostic = {
/** display label for the agent, e.g. "Pullfrog". used in the headline. */
label: string;
/** shared reference to the harness's bounded stderr ring buffer. */
recentStderr: string[];
/** most-recent provider-error label from `detectProviderError`, if any. */
lastProviderError: string | undefined;
/** count of stdout events successfully parsed before the failure. */
eventCount: number;
};
/**
* Build a user-facing markdown body for an agent hang or failure.
*
* Rendered into both the PR progress comment and the GitHub Actions job
* summary. Returns `null` when no diagnostic is available, which signals to
* the caller to fall back to its bare-error rendering.
*
* `errorMessage` is the underlying timer / spawn reject string (e.g.
* `activity timeout: no output for 301s`). The idle seconds are parsed out
* of it for the hang explanation — total runtime would overstate the stall
* for runs that streamed for a long time before going quiet.
*/
export function formatAgentHangBody(input: {
diagnostic: AgentDiagnostic | undefined;
isHang: boolean;
errorMessage: string;
}): string | null {
if (!input.diagnostic) return null;
// billing exhaustion (CreditsError / FreeUsageLimitError / spending cap /
// Insufficient balance) is mis-classified as transient by upstream harnesses
// and the run only ends when the activity-timeout watchdog fires (see #778).
// when we recognise the billing label, replace the generic "stalled — auth
// error" headline with a billing-specific CTA that names the actual remedy.
if (input.diagnostic.lastProviderError === "provider billing exhausted") {
return formatBillingExhaustedBody(input.diagnostic);
}
const verb = input.isHang ? "stalled" : "failed";
const cause = input.diagnostic.lastProviderError
? ` — likely cause: \`${input.diagnostic.lastProviderError}\``
: "";
const headline = `**${input.diagnostic.label} ${verb}**${cause}`;
const explanation = formatExplanation({
isHang: input.isHang,
errorMessage: input.errorMessage,
});
const parts = [headline, "", `${explanation} ${formatEventsPart(input.diagnostic)}`];
const tail = renderStderrTail(input.diagnostic.recentStderr);
if (tail) {
// pick a fence longer than any backtick run in the body so a stderr line
// containing ``` (provider error JSON occasionally embeds it) can't
// terminate the fence early and corrupt the rest of the markdown.
const fence = pickFence(tail);
parts.push(
"",
"<details><summary>Recent agent stderr</summary>",
"",
fence,
tail,
fence,
"",
"</details>"
);
}
return parts.join("\n");
}
function formatExplanation(input: { isHang: boolean; errorMessage: string }): string {
if (!input.isHang) return `The agent exited unexpectedly: ${input.errorMessage}`;
const idleSec = parseIdleSec(input.errorMessage);
if (idleSec === undefined) {
return "The agent stopped emitting events and was killed by the activity-timeout watchdog.";
}
return `The agent stopped emitting events for ${idleSec}s and was killed by the activity-timeout watchdog.`;
}
function parseIdleSec(message: string): number | undefined {
const match = /no output for (\d+)s/.exec(message);
return match ? Number(match[1]) : undefined;
}
function formatEventsPart(diagnostic: AgentDiagnostic): string {
if (diagnostic.eventCount > 0) {
return `${diagnostic.eventCount} events were processed before the failure.`;
}
// when the provider-error label already names the cause in the headline,
// the reachability nudge below contradicts it (e.g. an immediate 401 also
// produces zero events but isn't a reachability problem). suppress it.
if (diagnostic.lastProviderError) return "No events were emitted before the failure.";
return "No events were emitted — check whether the model provider is reachable.";
}
function renderStderrTail(lines: readonly string[]): string {
if (lines.length === 0) return "";
const joined = lines.join("\n");
if (joined.length <= MAX_STDERR_BYTES) return joined;
return `... (older lines truncated)\n${joined.slice(-MAX_STDERR_BYTES)}`;
}
function pickFence(content: string): string {
let max = 0;
for (const match of content.matchAll(/`+/g)) {
if (match[0].length > max) max = match[0].length;
}
return "`".repeat(Math.max(3, max + 1));
}
/**
* Pull a billing URL out of the captured stderr if the provider helpfully
* embedded one (OpenCode Zen does — Anthropic and Gemini do not). Restricted
* to known billing/console hosts so a stray URL elsewhere in the buffer
* can't masquerade as the remedy link.
*/
function extractBillingUrl(lines: readonly string[]): string | undefined {
const urlPattern =
/https:\/\/(?:opencode\.ai\/[^\s"]*billing[^\s"]*|console\.anthropic\.com[^\s"]*|console\.cloud\.google\.com[^\s"]*billing[^\s"]*)/i;
for (let i = lines.length - 1; i >= 0; i--) {
const m = urlPattern.exec(lines[i] ?? "");
if (m) return m[0];
}
return undefined;
}
function formatBillingExhaustedBody(diagnostic: AgentDiagnostic): string {
const headline = `**${diagnostic.label} stopped** — your model provider returned a billing-exhausted response.`;
const billingUrl = extractBillingUrl(diagnostic.recentStderr);
const cta = billingUrl
? `Top up your provider balance, then re-run: [${billingUrl}](${billingUrl})`
: "Top up your model-provider balance (or rotate to a key with remaining credits) and re-run.";
const explanation =
"The agent kept retrying the request because the provider marked the failure as transient. Pullfrog's activity-timeout watchdog ended the run after no further events were emitted.";
const parts = [headline, "", explanation, "", cta];
const tail = renderStderrTail(diagnostic.recentStderr);
if (tail) {
const fence = pickFence(tail);
parts.push(
"",
"<details><summary>Recent agent stderr</summary>",
"",
fence,
tail,
fence,
"",
"</details>"
);
}
return parts.join("\n");
}
utils/apiFetch.ts
-62
View File
@@ -1,62 +0,0 @@
import { getApiUrl } from "./apiUrl.ts";
import { log } from "./cli.ts";
type ApiFetchOptions = {
path: string;
method?: string | undefined;
headers?: Record<string, string> | undefined;
body?: string | undefined;
signal?: AbortSignal | undefined;
};
/**
* fetch wrapper for hitting the Pullfrog API with Vercel deployment protection bypass.
*
* adds the bypass secret as BOTH a query parameter and a header for maximum reliability.
* the server-side forwarding code uses query params, and the Vercel docs say both work,
* so we do both as belt-and-suspenders.
*
* the query param approach is the primary bypass mechanism (matches server-side forwarding).
* the header is added as a fallback.
*/
export async function apiFetch(options: ApiFetchOptions): Promise<Response> {
const apiUrl = getApiUrl();
const url = new URL(options.path, apiUrl);
const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
if (bypassSecret) {
url.searchParams.set("x-vercel-protection-bypass", bypassSecret);
}
const headers: Record<string, string> = {
...options.headers,
};
// also add as header for belt-and-suspenders
if (bypassSecret) {
headers["x-vercel-protection-bypass"] = bypassSecret;
}
// never send Content-Type on body-less requests. empirically, Vercel's
// Next.js lambda adapter (Next 16.1.x) throws `SyntaxError: Unexpected
// end of data` before delegating to the route handler — returning a 500 —
// when Content-Type is set but no body is present. exact mechanism is
// unverified (minified runtime frame), but Content-Type on a body-less
// request has no defined semantics per RFC 9110 §8.3 anyway. see #692.
if (!options.body) {
for (const key of Object.keys(headers)) {
if (key.toLowerCase() === "content-type") delete headers[key];
}
}
log.debug(`api fetch: ${options.method ?? "GET"} ${url.pathname}`);
const init: RequestInit = {
method: options.method ?? "GET",
headers,
};
if (options.body) init.body = options.body;
if (options.signal) init.signal = options.signal;
return fetch(url.toString(), init);
}
utils/apiKeys.test.ts
-271
View File
@@ -1,271 +0,0 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { formatApiKeyErrorSummary, isApiKeyAuthError, validateAgentApiKey } from "./apiKeys.ts";
const savedEnv = { ...process.env };
const ENV_KEYS_TO_STRIP = [
/_API_KEY$/,
/^CLAUDE_CODE_OAUTH_TOKEN$/,
/^CODEX_AUTH_JSON$/,
/^AWS_BEARER_TOKEN_BEDROCK$/,
/^AWS_ACCESS_KEY_ID$/,
/^AWS_SECRET_ACCESS_KEY$/,
/^AWS_SESSION_TOKEN$/,
/^AWS_REGION$/,
/^BEDROCK_MODEL_ID$/,
/^GOOGLE_APPLICATION_CREDENTIALS$/,
/^GOOGLE_CLOUD_PROJECT$/,
/^VERTEX_SERVICE_ACCOUNT_JSON$/,
/^VERTEX_LOCATION$/,
/^VERTEX_MODEL_ID$/,
];
beforeEach(() => {
for (const key of Object.keys(process.env)) {
if (ENV_KEYS_TO_STRIP.some((re) => re.test(key))) delete process.env[key];
}
});
afterEach(() => {
process.env = { ...savedEnv };
});
const opencode = { name: "opencode" };
const claude = { name: "claude" };
const owner = "test-owner";
const name = "test-repo";
describe("validateAgentApiKey — opencode", () => {
it("passes when the resolved model is in the authorized set", () => {
expect(() =>
validateAgentApiKey({
agent: opencode,
model: "anthropic/claude-opus-4-7",
authorized: new Set(["anthropic/claude-opus-4-7"]),
owner,
name,
})
).not.toThrow();
});
it("throws when the resolved model is absent from the authorized set", () => {
expect(() =>
validateAgentApiKey({
agent: opencode,
model: "anthropic/claude-opus-4-7",
authorized: new Set(),
owner,
name,
})
).toThrow("no API key found");
});
it("passes the auto-select path when the authorized set is non-empty", () => {
expect(() =>
validateAgentApiKey({
agent: opencode,
model: undefined,
authorized: new Set(["opencode/big-pickle"]),
owner,
name,
})
).not.toThrow();
});
it("throws the auto-select path when the authorized set is empty", () => {
expect(() =>
validateAgentApiKey({
agent: opencode,
model: undefined,
authorized: new Set(),
owner,
name,
})
).toThrow("no API key found");
});
});
describe("validateAgentApiKey — claude (static Anthropic check)", () => {
it("passes when ANTHROPIC_API_KEY is set", () => {
process.env.ANTHROPIC_API_KEY = "sk-test";
expect(() =>
validateAgentApiKey({
agent: claude,
model: "anthropic/claude-opus-4-7",
authorized: new Set(),
owner,
name,
})
).not.toThrow();
});
it("passes when CLAUDE_CODE_OAUTH_TOKEN is set", () => {
process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-test";
expect(() =>
validateAgentApiKey({
agent: claude,
model: "anthropic/claude-opus-4-7",
authorized: new Set(),
owner,
name,
})
).not.toThrow();
});
it("throws when neither Anthropic credential is set", () => {
expect(() =>
validateAgentApiKey({
agent: claude,
model: "anthropic/claude-opus-4-7",
authorized: new Set(),
owner,
name,
})
).toThrow("no API key found");
});
});
describe("validateAgentApiKey — Bedrock routing", () => {
const params = { agent: opencode, authorized: new Set<string>(), owner, name };
it("passes with AWS_BEARER_TOKEN_BEDROCK + AWS_REGION + BEDROCK_MODEL_ID", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.AWS_REGION = "us-east-1";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-7";
expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).not.toThrow();
});
it("passes with AWS access keys + region + model id", () => {
process.env.AWS_ACCESS_KEY_ID = "AKIA-test";
process.env.AWS_SECRET_ACCESS_KEY = "secret-test";
process.env.AWS_REGION = "us-east-1";
process.env.BEDROCK_MODEL_ID = "amazon.nova-pro-v1:0";
expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).not.toThrow();
});
it("throws when BEDROCK_MODEL_ID is missing", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.AWS_REGION = "us-east-1";
expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).toThrow(
"BEDROCK_MODEL_ID"
);
});
// regression: main.ts passes the post-resolveModel value into
// validateAgentApiKey, which for Bedrock is the raw AWS model ID (no `/`).
it("accepts a raw Bedrock model ID without throwing", () => {
process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
process.env.AWS_REGION = "us-east-1";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-6-v1";
expect(() =>
validateAgentApiKey({ ...params, model: "us.anthropic.claude-opus-4-6-v1" })
).not.toThrow();
});
it("throws on raw Bedrock model ID when AWS auth is missing", () => {
process.env.AWS_REGION = "us-east-1";
process.env.BEDROCK_MODEL_ID = "us.anthropic.claude-opus-4-6-v1";
expect(() =>
validateAgentApiKey({ ...params, model: "us.anthropic.claude-opus-4-6-v1" })
).toThrow("AWS_BEARER_TOKEN_BEDROCK");
});
});
describe("validateAgentApiKey — Vertex routing", () => {
const params = { agent: opencode, authorized: new Set<string>(), owner, name };
it("passes with service-account JSON + project + location + model id", () => {
process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
process.env.GOOGLE_CLOUD_PROJECT = "test-project";
process.env.VERTEX_LOCATION = "us-east5";
process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).not.toThrow();
});
it("throws when VERTEX_MODEL_ID is missing", () => {
process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
process.env.GOOGLE_CLOUD_PROJECT = "test-project";
process.env.VERTEX_LOCATION = "us-east5";
expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).toThrow(
"VERTEX_MODEL_ID"
);
});
it("accepts a raw Vertex model ID without throwing", () => {
process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
process.env.GOOGLE_CLOUD_PROJECT = "test-project";
process.env.VERTEX_LOCATION = "us-east5";
process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
expect(() => validateAgentApiKey({ ...params, model: "gemini-2.5-pro" })).not.toThrow();
});
it("throws on raw Vertex model ID when auth is missing", () => {
process.env.GOOGLE_CLOUD_PROJECT = "test-project";
process.env.VERTEX_LOCATION = "us-east5";
process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
expect(() => validateAgentApiKey({ ...params, model: "gemini-2.5-pro" })).toThrow(
"VERTEX_SERVICE_ACCOUNT_JSON"
);
});
});
describe("isApiKeyAuthError", () => {
it("matches the missing-key marker thrown by validateAgentApiKey", () => {
expect(isApiKeyAuthError("no API key found. Pullfrog needs ...")).toBe(true);
});
it("matches Claude CLI 401 strings", () => {
expect(isApiKeyAuthError("Invalid API key · Fix external API key")).toBe(true);
});
it("matches OpenAI / OpenRouter 401 phrasings", () => {
expect(isApiKeyAuthError("ProviderAuthError: User not found")).toBe(true);
expect(isApiKeyAuthError("401 Invalid authentication")).toBe(true);
});
// see #782 — direct-Anthropic 401 shape (revoked / mistyped / rotated
// ANTHROPIC_API_KEY) reaches us via Claude CLI as a JSON dump, not as
// any of the canonical "Invalid API key" strings.
it("matches direct-Anthropic 401 shapes", () => {
expect(
isApiKeyAuthError(
'Failed to authenticate. API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid bearer token"}}'
)
).toBe(true);
expect(
isApiKeyAuthError(
"» Pullfrog result error: subtype=success, api_error_status=401, message=Failed to authenticate."
)
).toBe(true);
});
it("ignores unrelated errors", () => {
expect(isApiKeyAuthError("git fetch failed")).toBe(false);
expect(isApiKeyAuthError("")).toBe(false);
});
});
describe("formatApiKeyErrorSummary", () => {
it("renders the missing-key body when the raw error contains the marker", () => {
const msg = formatApiKeyErrorSummary({
owner: "acme",
name: "repo",
raw: "no API key found in this run",
});
expect(msg).toContain("no API key found");
expect(msg).toContain("https://github.com/acme/repo/settings/secrets/actions");
expect(msg).toContain("/console/acme/repo");
expect(msg).toContain("https://discord.gg/8y96raFg8e");
});
it("renders the invalid-key body for any other auth error", () => {
const msg = formatApiKeyErrorSummary({
owner: "acme",
name: "repo",
raw: "Invalid API key · Fix external API key",
});
expect(msg).toContain("rejected (401)");
expect(msg).toContain("https://github.com/acme/repo/settings/secrets/actions");
expect(msg).toContain("https://discord.gg/8y96raFg8e");
});
});
utils/apiKeys.ts
-206
View File
@@ -1,206 +0,0 @@
import { BEDROCK_MODEL_ID_ENV, resolveDisplayAlias, VERTEX_MODEL_ID_ENV } from "../models.ts";
import { getApiUrl } from "./apiUrl.ts";
import {
GOOGLE_CLOUD_PROJECT_ENV,
readProjectIdFromVertexServiceAccountJson,
VERTEX_LOCATION_ENV,
VERTEX_SERVICE_ACCOUNT_JSON_ENV,
} from "./vertex.ts";
/** marker prefix on the throw message for the catch-side reclassification path */
const MISSING_KEY_MARKER = "no API key found";
/** Markdown body used for both the thrown error and the formatted PR comment summary. */
function buildMissingApiKeyError(params: { owner: string; name: string }): string {
const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
return [
`**${MISSING_KEY_MARKER}** — Pullfrog needs at least one LLM provider API key (e.g. \`ANTHROPIC_API_KEY\`, \`OPENAI_API_KEY\`, \`GEMINI_API_KEY\`) configured as a GitHub Actions secret.`,
"",
`[Open repo secrets →](${githubSecretsUrl}) · [Configure model →](${settingsUrl}) · [Setup docs →](https://docs.pullfrog.com/keys) · [Ask in Discord →](https://discord.gg/8y96raFg8e)`,
].join("\n");
}
function buildBedrockSetupError(params: {
owner: string;
name: string;
missing: string[];
}): string {
const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
return `Bedrock model selected but required configuration is missing: ${params.missing.join(", ")}.
add the missing secret(s) to your GitHub repository at ${githubSecretsUrl}, then reference them in your workflow's \`env:\` block:
AWS_BEARER_TOKEN_BEDROCK: \${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
AWS_REGION: \${{ secrets.AWS_REGION }}
${BEDROCK_MODEL_ID_ENV}: \${{ secrets.${BEDROCK_MODEL_ID_ENV} }}
\`AWS_BEARER_TOKEN_BEDROCK\` may be substituted with \`AWS_ACCESS_KEY_ID\` + \`AWS_SECRET_ACCESS_KEY\` (and optional \`AWS_SESSION_TOKEN\`) if you prefer access keys.
for full setup instructions, see https://docs.pullfrog.com/bedrock`;
}
function buildVertexSetupError(params: { owner: string; name: string; missing: string[] }): string {
const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
return `Google Vertex AI model selected but required configuration is missing: ${params.missing.join(", ")}.
add the missing secret(s) to your GitHub repository at ${githubSecretsUrl}, then reference them in your workflow's \`env:\` block:
${VERTEX_SERVICE_ACCOUNT_JSON_ENV}: \${{ secrets.${VERTEX_SERVICE_ACCOUNT_JSON_ENV} }}
${GOOGLE_CLOUD_PROJECT_ENV}: my-project
${VERTEX_LOCATION_ENV}: global
${VERTEX_MODEL_ID_ENV}: <vertex-model-id>
for full setup instructions, see https://docs.pullfrog.com/vertex`;
}
function hasEnvVar(name: string): boolean {
const value = process.env[name];
return typeof value === "string" && value.length > 0;
}
function validateBedrockSetup(params: { owner: string; name: string }): void {
const hasAuth =
hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") ||
(hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY"));
const missing: string[] = [];
if (!hasAuth)
missing.push("AWS_BEARER_TOKEN_BEDROCK (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)");
if (!hasEnvVar("AWS_REGION")) missing.push("AWS_REGION");
if (!hasEnvVar(BEDROCK_MODEL_ID_ENV)) missing.push(BEDROCK_MODEL_ID_ENV);
if (missing.length > 0) {
throw new Error(buildBedrockSetupError({ owner: params.owner, name: params.name, missing }));
}
}
function validateVertexSetup(params: { owner: string; name: string }): void {
const hasAuth = hasEnvVar(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
const hasProject =
hasEnvVar(GOOGLE_CLOUD_PROJECT_ENV) ||
readProjectIdFromVertexServiceAccountJson() !== undefined;
const missing: string[] = [];
if (!hasAuth) missing.push(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
if (!hasProject) missing.push(GOOGLE_CLOUD_PROJECT_ENV);
if (!hasEnvVar(VERTEX_LOCATION_ENV)) missing.push(VERTEX_LOCATION_ENV);
if (!hasEnvVar(VERTEX_MODEL_ID_ENV)) missing.push(VERTEX_MODEL_ID_ENV);
if (missing.length > 0) {
throw new Error(buildVertexSetupError({ owner: params.owner, name: params.name, missing }));
}
}
/**
* Validate that the resolved model can actually be served by the chosen
* agent. For routing slugs (Bedrock / Vertex) the auth shape is multi-var
* (auth + region/location + model-id) and `opencode models` doesn't catch
* gaps in the latter two — keep dedicated setup validators. For the
* opencode path, the authoritative answer comes from OpenCode's own model
* introspection (`authorized` set captured in `openCodeModels.ts`). For
* the claude path, fall back to the static check (`ANTHROPIC_API_KEY` /
* `CLAUDE_CODE_OAUTH_TOKEN`).
*/
export function validateAgentApiKey(params: {
agent: { name: string };
model: string | undefined;
authorized: Set<string>;
owner: string;
name: string;
}): void {
if (params.model) {
const alias = resolveDisplayAlias(params.model);
if (alias?.routing === "bedrock") {
validateBedrockSetup({ owner: params.owner, name: params.name });
return;
}
if (alias?.routing === "vertex") {
validateVertexSetup({ owner: params.owner, name: params.name });
return;
}
// raw backend model IDs (post-resolveModel for routing slugs) have no
// `/`. discriminate by the env-var sentinel, then run the matching
// setup validator — `opencode models` doesn't help here because the
// Bedrock/Vertex provider plugins need region/location/model-id wired
// through env regardless of CLI-side auth.
if (!params.model.includes("/")) {
if (process.env[VERTEX_MODEL_ID_ENV]?.trim() === params.model) {
validateVertexSetup({ owner: params.owner, name: params.name });
return;
}
validateBedrockSetup({ owner: params.owner, name: params.name });
return;
}
if (params.agent.name === "opencode") {
if (params.authorized.has(params.model)) return;
throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
}
// claude: single-provider check on the Anthropic auth shapes.
if (hasEnvVar("ANTHROPIC_API_KEY") || hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN")) return;
throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
}
// no model configured (auto-select path).
if (params.agent.name === "opencode") {
if (params.authorized.size > 0) return;
throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
}
if (hasEnvVar("ANTHROPIC_API_KEY") || hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN")) return;
throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
}
/**
* Detect agent-runtime auth failures that should be reformatted as an actionable
* key-fix CTA before being shown to the user. Covers the shapes we see:
* - missing key (validateAgentApiKey throw): contains MISSING_KEY_MARKER
* - revoked / invalid key (Claude CLI 401 surfaced via api_error_status):
* "Invalid API key · Fix external API key" + similar provider variants
* - direct-Anthropic 401 (`Failed to authenticate. API Error: 401 ...
* {"type":"error","error":{"type":"authentication_error", ...
* "Invalid bearer token"}}`) emitted by the Claude CLI for revoked /
* mistyped / rotated `ANTHROPIC_API_KEY`. see #782.
*/
export function isApiKeyAuthError(text: string): boolean {
if (!text) return false;
return (
text.includes(MISSING_KEY_MARKER) ||
/Invalid API key/i.test(text) ||
/\bUser not found\b/i.test(text) ||
/\bInvalid authentication\b/i.test(text) ||
/authentication_error/i.test(text) ||
/Invalid bearer token/i.test(text) ||
/api_error_status\s*=\s*401/i.test(text) ||
/API Error:\s*401/i.test(text)
);
}
/**
* Friendly Markdown summary for both the missing-key and invalid-key cases.
* Used in the catch / result-failure paths in `main.ts` to overwrite the raw
* agent error before it's posted to the PR progress comment.
*/
export function formatApiKeyErrorSummary(params: {
owner: string;
name: string;
raw: string;
}): string {
if (params.raw.includes(MISSING_KEY_MARKER)) {
return buildMissingApiKeyError({ owner: params.owner, name: params.name });
}
const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
return [
`**Your LLM provider API key was rejected (401).** Rotate the key in your provider dashboard, then update the matching GitHub Actions secret.`,
"",
`[Update repo secret →](${githubSecretsUrl}) · [Model settings →](${settingsUrl}) · [Setup docs →](https://docs.pullfrog.com/keys) · [Ask in Discord →](https://discord.gg/8y96raFg8e)`,
].join("\n");
}
utils/apiUrl.ts
-42
View File
@@ -1,42 +0,0 @@
import { log } from "./cli.ts";
function isLocalUrl(url: URL): boolean {
return url.hostname === "localhost" || url.hostname === "127.0.0.1";
}
/**
* resolve the Pullfrog API base URL.
*
* in the action: API_URL is not explicitly set, so this falls back to https://pullfrog.com.
* in local dev: API_URL=http://localhost:3000 (from .env).
*
* enforces https:// for non-local URLs to prevent cleartext credential transmission.
*/
export function getApiUrl(): string {
const raw = process.env.API_URL || "https://pullfrog.com";
const parsed = new URL(raw);
if (parsed.protocol !== "https:" && !isLocalUrl(parsed)) {
throw new Error(
`API_URL must use https:// (got ${parsed.protocol}). only localhost is exempt.`
);
}
log.debug(`resolved API_URL: ${raw}`);
return raw;
}
/**
* true when the action is configured to talk to a localhost API server (i.e.
* `pnpm dev` running on the developer's box). signals we can use dev-only
* affordances like the `x-dev-repo` proxy-token bypass — the corresponding
* server-side dev gates (`NODE_ENV === "development"`) ensure these paths
* never activate against prod regardless of what the action does.
*/
export function isLocalApiUrl(): boolean {
try {
return isLocalUrl(new URL(getApiUrl()));
} catch {
return false;
}
}
utils/billingErrors.ts
-189
View File
@@ -1,189 +0,0 @@
/**
* Billing-error classification + user-facing copy for `/api/proxy-token`
* failures and OpenRouter mid-run exhaustion. Two error classes (Billing vs.
* Transient) keep the framing honest: a card decline is *not* the same UX as
* a 503 from the proxy service. Both originate in `utils/proxy.ts` (mint
* failures) and `utils/runErrorRenderer.ts` (mid-run keylimit reclassify).
*
* Renderers return markdown bodies that are written into both the GitHub
* Actions job summary and the PR progress comment.
*
* Lives outside `main.ts` so adding a new error `code` branch is a one-file
* edit that does not retrigger the full LLM CI matrix (`action/main.ts` is
* in `action/test/coverage.ts::ALWAYS_RUN_ALL`).
*/
/**
* Billing-layer error surfaced from `/api/proxy-token` as a 402. User-actionable
* — distinct from TransientError (503 / transient sync issue) so the job
* summary + PR comment can use affirmative "you need to do X" copy rather than
* the ambiguous "billing error" label that makes transient outages look like
* the user's fault.
*
* `code` is a server-side discriminator: `router_requires_card` (no card + no
* wallet balance on Router), or null for unclassified. `declineCode` is
* Stripe's more specific sub-reason on `card_declined` (e.g.
* `insufficient_funds`, `lost_card`). `needsReauthentication` is the 3DS case
* broken out for convenience.
*/
export class BillingError extends Error {
code: string | null;
declineCode: string | null;
needsReauthentication: boolean;
constructor(
message: string,
opts: {
code?: string | null;
declineCode?: string | null;
needsReauthentication?: boolean;
} = {}
) {
super(message);
this.name = "BillingError";
this.code = opts.code ?? null;
this.declineCode = opts.declineCode ?? null;
this.needsReauthentication = opts.needsReauthentication ?? false;
}
}
/**
* Transient service failures from `/api/proxy-token` (503: partial OpenRouter
* usage sync, DB flake, in-flight payment intent). Not the user's fault — the
* summary uses "temporarily unavailable" framing, and the non-zero exit lets
* GH Actions apply whatever retry policy the workflow has configured.
*/
export class TransientError extends Error {
constructor(message: string) {
super(message);
this.name = "TransientError";
}
}
/**
* Deep link into the right console section for the failing account. Anchors
* are defined in `app/console/[owner]/page.tsx` (`#billing`, `#model-access`).
* `owner` is the GitHub login of the repo's account — i.e. the org or user
* that pays for this repo's runs, which is the right scope for billing.
*/
function billingConsoleUrl(owner: string, anchor: "billing" | "model-access"): string {
return `https://pullfrog.com/console/${encodeURIComponent(owner)}#${anchor}`;
}
/**
* Render a BillingError as user-facing markdown (shared between GH job summary
* and the PR progress comment). Goals:
*
* - quiet, not alarmist — bold first line instead of an `### ❌` H3, since
* the comment already has Pullfrog branding in the footer
* - actionable — every branch ends in a single CTA deep-linked to the
* correct section of the owner's console
* - honest — say what actually went wrong (card declined vs. balance
* empty vs. 3DS required), don't lump them under "billing error"
*
* Branches:
* - `router_requires_card`: user is on Router mode with no card AND no
* wallet balance (signup credit exhausted or not granted). Frame as
* "add a card to continue", link to `#model-access` where the Add
* Card flow lives.
* - `router_balance_exhausted`: user has a card on file but auto-reload is
* disabled and they've spent past their $5 overdraft buffer. Frame as
* "balance ran out" and surface both remediation paths (top up, or flip
* on auto-reload).
* - `router_keylimit_exhausted`: OpenRouter rejected mid-run because the
* per-run key budget was exhausted while the agent was working. The
* wallet is now negative; same remediation as `router_balance_exhausted`
* but framed for the after-the-fact case ("this run was cut short").
* - `needsReauthentication`: issuer requires 3DS on every off-session
* charge. Re-adding the card won't help — the only escape is a manual
* top-up where 3DS runs interactively in Stripe Checkout.
* - `declineCode` set: Stripe declined a real charge. Show the sub-code
* so support can act on it; tell the user we'll retry on next dispatch.
* - default: balance hit zero with no in-flight charge (auto-reload off
* or amount below threshold). Direct them to top up or enable auto-reload.
*/
export function formatBillingErrorSummary(error: BillingError, owner: string): string {
if (error.code === "router_requires_card") {
return [
"**Add a card to start using Pullfrog Router.**",
"",
"Router proxies OpenRouter at raw cost — no platform markup. Add a card and we'll auto-reload your wallet so runs keep flowing.",
"",
`[Add a card →](${billingConsoleUrl(owner, "model-access")})`,
].join("\n");
}
if (error.code === "router_balance_exhausted") {
return [
"**Your Pullfrog Router balance is exhausted.**",
"",
"You have a card on file but auto-reload is disabled, so runs paused once your balance went past the overdraft buffer.",
"",
`[Top up balance →](${billingConsoleUrl(owner, "billing")}) · [Enable auto-reload →](${billingConsoleUrl(owner, "model-access")})`,
].join("\n");
}
if (error.code === "router_keylimit_exhausted") {
return [
"**This run was cut short — your Pullfrog Router balance ran out mid-run.**",
"",
"OpenRouter stopped the agent because the per-run budget was exhausted. Your wallet is now negative; top up or enable auto-reload to keep runs flowing.",
"",
`[Top up balance →](${billingConsoleUrl(owner, "billing")}) · [Enable auto-reload →](${billingConsoleUrl(owner, "model-access")})`,
].join("\n");
}
if (error.code === "router_monthly_limit") {
return [
"**Pullfrog Router hit its monthly spend limit.**",
"",
"Auto-reloads are paused for the rest of this UTC month. Ask your admin to raise the cap, or wait for it to reset at 00:00 UTC on the 1st.",
"",
`[Adjust limit →](${billingConsoleUrl(owner, "model-access")})`,
].join("\n");
}
if (error.needsReauthentication) {
const code = error.declineCode ?? "authentication_required";
return [
`**Your card issuer requires 3D Secure on every charge** (\`${code}\`).`,
"",
"Pullfrog can't complete a 3DS challenge from inside a workflow. Top up your Router balance once in Stripe Checkout — subsequent runs draw from the prepaid balance without re-triggering 3DS.",
"",
`[Top up balance →](${billingConsoleUrl(owner, "billing")})`,
].join("\n");
}
if (error.declineCode) {
return [
`**Your card was declined** (\`${error.declineCode}\`).`,
"",
"Update your payment method and Pullfrog will retry on the next run.",
"",
`[Update payment method →](${billingConsoleUrl(owner, "billing")})`,
].join("\n");
}
return [
"**Your Pullfrog balance is empty.**",
"",
"Top up your balance or enable auto-reload to keep runs flowing.",
"",
`[Manage billing →](${billingConsoleUrl(owner, "billing")})`,
].join("\n");
}
/**
* Render a TransientError as user-facing markdown. Distinct framing from
* BillingError so the user doesn't read an alarm and assume their card
* failed — this branch is "our fault, retry shortly", not theirs.
*/
export function formatTransientErrorSummary(error: TransientError, owner: string): string {
return [
"**Pullfrog billing is temporarily unavailable.**",
"",
error.message,
"",
`Usually transient — the next dispatch should succeed. If it persists, check [status.pullfrog.com](https://status.pullfrog.com) or [your console](${billingConsoleUrl(owner, "billing")}).`,
].join("\n");
}
utils/body.ts
-146
View File
@@ -1,146 +0,0 @@
import TurndownService from "turndown";
import type { PayloadEvent } from "../external.ts";
import { log } from "./cli.ts";
import type { OctokitWithPlugins } from "./github.ts";
import type { RunContextData } from "./runContextData.ts";
const turndown = new TurndownService();
function hasImages(body: string | null | undefined): boolean {
if (!body) return false;
return body.includes("<img") || body.includes("![");
}
interface ResolveBodyContext {
event: PayloadEvent;
octokit: OctokitWithPlugins;
repo: RunContextData["repo"];
}
/**
* resolves the body of an event by fetching body_html and converting to markdown.
* only fetches body_html if the body contains images (to avoid unnecessary API calls).
* this ensures agents receive markdown with working signed image URLs instead of
* broken user-attachments URLs.
*/
export async function resolveBody(ctx: ResolveBodyContext): Promise<string | null> {
const body = ctx.event.body;
// pass through if no images - no API call needed
if (!hasImages(body)) return body ?? null;
log.debug(`[resolveBody] fetching body_html for ${ctx.event.trigger}`);
const bodyHtml = await fetchBodyHtml(ctx);
log.debug(`[resolveBody] bodyHtml: ${bodyHtml?.substring(0, 300)}`);
if (!bodyHtml) return body ?? null;
const resolved = turndown.turndown(bodyHtml);
log.debug(`[resolveBody] resolved: ${resolved.substring(0, 300)}`);
return resolved;
}
async function fetchBodyHtml(ctx: ResolveBodyContext): Promise<string | undefined> {
const event = ctx.event;
const headers = { accept: "application/vnd.github.full+json" };
const owner = ctx.repo.owner;
const repo = ctx.repo.name;
switch (event.trigger) {
case "issue_comment_created":
if (!event.comment_id) return;
return (
await ctx.octokit.rest.issues.getComment({
owner,
repo,
comment_id: event.comment_id,
headers,
})
).data.body_html;
case "issues_opened":
case "issues_assigned":
case "issues_labeled":
if (!event.issue_number) return;
return (
await ctx.octokit.rest.issues.get({
owner,
repo,
issue_number: event.issue_number,
headers,
})
).data.body_html;
case "pull_request_opened":
case "pull_request_ready_for_review":
case "pull_request_synchronize":
case "pull_request_review_requested":
// PRs are also issues - use issues.get which returns body_html
if (!event.issue_number) return;
return (
await ctx.octokit.rest.issues.get({
owner,
repo,
issue_number: event.issue_number,
headers,
})
).data.body_html;
case "pull_request_review_submitted":
if (!event.issue_number || !event.review_id) return;
return (
await ctx.octokit.rest.pulls.getReview({
owner,
repo,
pull_number: event.issue_number,
review_id: event.review_id,
headers,
})
).data.body_html;
case "pull_request_review_comment_created":
if (!event.comment_id) return;
return (
await ctx.octokit.rest.pulls.getReviewComment({
owner,
repo,
comment_id: event.comment_id,
headers,
})
).data.body_html;
case "check_suite_completed":
// body is the PR body
if (!event.issue_number) return;
return (
await ctx.octokit.rest.issues.get({
owner,
repo,
issue_number: event.issue_number,
headers,
})
).data.body_html;
case "implement_plan":
// body is the plan content from an issue comment
if (!event.plan_comment_id) return;
return (
await ctx.octokit.rest.issues.getComment({
owner,
repo,
comment_id: event.plan_comment_id,
headers,
})
).data.body_html;
// triggers without a body field that needs resolution
case "workflow_dispatch":
case "fix_review":
case "unknown":
return undefined;
default:
// exhaustiveness check - TypeScript will error if a trigger is missing
event satisfies never;
return undefined;
}
}
utils/browser.ts
+5 -128
View File
@@ -1,133 +1,10 @@
import { execFileSync, spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import { dirname } from "node:path";
import type { ToolState } from "../toolState.ts";
import { log } from "./cli.ts";
import { filterEnv } from "./secrets.ts";
import { getDevDependencyVersion } from "./version.ts";
// agent-browser already discovers chrome via `which` and the playwright cache as fallbacks,
// so this list only needs to cover the GHA ubuntu-latest runner where we know the exact path.
const CHROME_PATHS = ["/usr/bin/google-chrome-stable"];
let systemChromePath: string | undefined;
function findSystemChromePath(): string | undefined {
if (typeof systemChromePath === "string") {
// return cached result but normalize to undefined if empty
return systemChromePath || undefined;
}
for (const p of CHROME_PATHS) {
if (existsSync(p)) {
systemChromePath = p;
log.info(`found system chrome: ${p}`);
return p;
}
}
// set to an empty string to indicate no system chrome found
// and to avoid repeated lookups
systemChromePath = "";
log.info(`no system chrome found (checked: ${CHROME_PATHS.join(", ")})`);
// Browser daemon is not supported in shockbot
export function ensureBrowserDaemon(_toolState: ToolState): string | undefined {
return "Browser daemon is not supported in shockbot";
}
function buildEnv(): Record<string, string> {
const env: Record<string, string> = { ...filterEnv() };
const chromePath = findSystemChromePath();
if (chromePath) {
env.AGENT_BROWSER_EXECUTABLE_PATH = chromePath;
}
return env;
}
/**
* ensure the agent-browser daemon is running by issuing a real command.
*
* agent-browser is stateful — it manages a persistent browser process via a
* daemon that communicates over a Unix socket. we start the daemon here,
* outside of ShellTool, because ShellTool's child process lifecycle would
* kill it between invocations and the daemon must survive across calls.
*
* despite ShellTool commands running inside unshare-sandboxed namespaces,
* they can still reach this daemon because the Unix socket is discoverable
* regardless of unshare's PID/mount isolation. starting the daemon in the
* host namespace keeps it alive while sandboxed shells come and go.
*
* agent-browser auto-starts its daemon on the first CLI invocation and
* keeps it alive via the socket for subsequent commands.
* we run `open about:blank` as the seed command to trigger this.
* idempotent — only runs once.
*/
export function ensureBrowserDaemon(toolState: ToolState): string | undefined {
if (toolState.browserDaemon) {
return toolState.browserDaemon.error;
}
const agentBrowserVersion = getDevDependencyVersion("agent-browser");
log.info(`installing agent-browser@${agentBrowserVersion}...`);
const install = spawnSync("npm", ["install", "-g", `agent-browser@${agentBrowserVersion}`], {
stdio: "pipe",
encoding: "utf-8",
});
if (install.status !== 0) {
const error = `agent-browser install failed: ${(install.stderr || install.stdout || "unknown error").trim()}`;
log.error(error);
toolState.browserDaemon = { error };
return error;
}
log.info("agent-browser installed");
let binDir: string;
try {
const binPath = execFileSync("which", ["agent-browser"], { encoding: "utf-8" }).trim();
binDir = dirname(binPath);
log.info(`agent-browser binary: ${binPath}`);
} catch {
const error = "agent-browser binary not found in PATH after install";
log.error(error);
toolState.browserDaemon = { error };
return error;
}
const env = buildEnv();
// `open about:blank` triggers daemon auto-start and returns once the daemon + browser are ready
log.info("starting browser daemon...");
const seed = spawnSync("agent-browser", ["open", "about:blank"], {
env,
stdio: "pipe",
encoding: "utf-8",
timeout: 30_000,
});
if (seed.status !== 0) {
const output = (seed.stderr || seed.stdout || "unknown error").trim();
const error = `agent-browser open about:blank failed (exit=${seed.status}): ${output}`;
log.error(error);
toolState.browserDaemon = { error };
return error;
}
log.debug(`seed command done (exit=0): ${(seed.stdout || "").trim()}`);
toolState.browserDaemon = { binDir };
log.info("browser daemon ready");
}
export function closeBrowserDaemon(toolState: ToolState): void {
if (!toolState.browserDaemon?.binDir) {
delete toolState.browserDaemon;
return;
}
delete toolState.browserDaemon;
try {
log.info("closing browser daemon...");
spawnSync("agent-browser", ["close"], {
env: filterEnv(),
stdio: "pipe",
timeout: 10_000,
});
log.info("browser daemon closed");
} catch {
// best-effort
}
export function closeBrowserDaemon(_toolState: ToolState): void {
// no-op
}
utils/buildPullfrogFooter.test.ts
-38
View File
@@ -1,38 +0,0 @@
import { describe, expect, it } from "vitest";
import { buildPullfrogFooter } from "./buildPullfrogFooter.ts";
describe("buildPullfrogFooter — fallbackFrom annotation", () => {
it("renders the provider display name when fallbackFrom is set", () => {
const footer = buildPullfrogFooter({
model: "opencode/big-pickle",
fallbackFrom: "anthropic/claude-opus",
});
expect(footer).toContain(
"Using `Big Pickle` (free) (credentials for Anthropic not configured)"
);
});
it("works for OpenAI's display name too", () => {
const footer = buildPullfrogFooter({
model: "opencode/big-pickle",
fallbackFrom: "openai/gpt",
});
expect(footer).toContain("(credentials for OpenAI not configured)");
});
it("falls back to the raw provider key when the slug provider is unknown to the catalog", () => {
const footer = buildPullfrogFooter({
model: "opencode/big-pickle",
fallbackFrom: "some-unknown/model",
});
expect(footer).toContain("(credentials for some-unknown not configured)");
});
it("omits the annotation when fallbackFrom is not set", () => {
const footer = buildPullfrogFooter({
model: "anthropic/claude-opus",
});
expect(footer).toContain("Using `Claude Opus`");
expect(footer).not.toContain("not configured");
});
});
utils/buildPullfrogFooter.ts
-107
View File
@@ -1,107 +0,0 @@
import { getModelProvider, modelAliases, providers, resolveDisplayAlias } from "../models.ts";
export const PULLFROG_DIVIDER = "<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->";
const FROG_LOGO = `<a href="https://pullfrog.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pullfrog.com/logos/frog-white-full-18px.png"><img src="https://pullfrog.com/logos/frog-green-full-18px.png" width="9px" height="9px" style="vertical-align: middle; " alt="Pullfrog"></picture></a>`;
export interface WorkflowRunFooterInfo {
owner: string;
repo: string;
runId: number;
/** optional job ID - if provided, will append /job/{jobId} to the workflow run URL */
jobId?: string | undefined;
}
export interface BuildPullfrogFooterParams {
/** add "via Pullfrog" link */
triggeredBy?: boolean;
/** add "View workflow run" link */
workflowRun?: WorkflowRunFooterInfo | undefined;
/** alternative: just pass a pre-built URL directly (for shortlinks etc.) */
workflowRunUrl?: string | undefined;
/** arbitrary custom parts (e.g., action links) */
customParts?: string[] | undefined;
/** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
model?: string | undefined;
/**
* When the action engaged the BYOK fallback, this is the slug the user
* had configured (e.g. "anthropic/claude-opus") — the footer renders
* `Using <free model> (credentials for <configured> not configured)`
* so the substitution is visible in PR comments + reviews.
*/
fallbackFrom?: string | undefined;
}
/** Provider display name (e.g. "Anthropic") for the slug, or the raw provider segment as a fallback. */
function providerDisplayName(slug: string): string {
try {
const key = getModelProvider(slug);
const meta = providers[key as keyof typeof providers];
return meta?.displayName ?? key;
} catch {
// raw IDs without a `/` (Bedrock model IDs) — never reach this function
// in practice because the BYOK fallback skips Bedrock, but defensively
// return the slug itself rather than throw if it ever does.
return slug;
}
}
function formatModelLabel(params: { model: string; fallbackFrom?: string | undefined }): string {
const alias =
resolveDisplayAlias(params.model) ??
// reverse-lookup: when the caller passes an effective model (proxy or
// resolved target like "openrouter/anthropic/claude-opus-4.7") instead of
// a stored alias slug, find the alias whose resolve target matches so we
// still render a friendly display name.
modelAliases.find((a) => a.resolve === params.model || a.openRouterResolve === params.model);
const displayName = alias?.displayName ?? params.model;
const base = alias?.isFree ? `\`${displayName}\` (free)` : `\`${displayName}\``;
if (!params.fallbackFrom) return base;
return `${base} (credentials for ${providerDisplayName(params.fallbackFrom)} not configured)`;
}
/**
* build a pullfrog footer with configurable parts
* always includes: frog logo at start and X link at end
* order: action links (customParts) > workflow run > model > attribution > reference links
*/
export function buildPullfrogFooter(params: BuildPullfrogFooterParams): string {
const parts: string[] = [];
if (params.customParts) {
parts.push(...params.customParts);
}
if (params.workflowRunUrl) {
parts.push(`[View workflow run](${params.workflowRunUrl})`);
} else if (params.workflowRun) {
const baseUrl = `https://github.com/${params.workflowRun.owner}/${params.workflowRun.repo}/actions/runs/${params.workflowRun.runId}`;
const url = params.workflowRun.jobId ? `${baseUrl}/job/${params.workflowRun.jobId}` : baseUrl;
parts.push(`[View workflow run](${url})`);
}
if (params.triggeredBy) {
parts.push("via [Pullfrog](https://pullfrog.com)");
}
if (params.model) {
parts.push(
`Using ${formatModelLabel({ model: params.model, fallbackFrom: params.fallbackFrom })}`
);
}
const allParts = [...parts, "[𝕏](https://x.com/pullfrogai)"];
return `\n\n${PULLFROG_DIVIDER}\n<sup>${FROG_LOGO}&nbsp;&nbsp;｜ ${allParts.join(" ｜ ")}</sup>`;
}
/**
* strip any existing pullfrog footer from a comment body
*/
export function stripExistingFooter(body: string): string {
const dividerIndex = body.indexOf(PULLFROG_DIVIDER);
if (dividerIndex === -1) {
return body;
}
return body.substring(0, dividerIndex).trimEnd();
}
utils/buildShockbotFooter.ts
+17
View File
@@ -0,0 +1,17 @@
const FOOTER_MARKER = "<!-- shockbot-footer -->";
export function buildShockbotFooter(params?: {
model?: string | undefined;
}): string {
const modelPart = params?.model ? ` · \`${params.model}\`` : "";
return `\n\n<br>\n\n---\n${FOOTER_MARKER}\n*Reviewed by [shockbot](https://git.shockvpn.com)${modelPart}*`;
}
export function stripExistingFooter(body: string): string {
const markerIdx = body.lastIndexOf(FOOTER_MARKER);
if (markerIdx === -1) return body;
// walk back past "\n\n---\n" before the marker
const beforeMarker = body.slice(0, markerIdx);
const stripped = beforeMarker.replace(/\s*\n+---\n$/, "").trimEnd();
return stripped;
}
utils/byokFallback.test.ts
-88
View File
@@ -1,88 +0,0 @@
import { describe, expect, it } from "vitest";
import { resolveCliModel } from "../models.ts";
import { FREE_FALLBACK_SLUG, selectFallbackModelIfNeeded } from "./byokFallback.ts";
describe("FREE_FALLBACK_SLUG", () => {
it("resolves in the curated catalog", () => {
expect(resolveCliModel(FREE_FALLBACK_SLUG)).toBe("opencode/big-pickle");
});
it("is opencode/big-pickle", () => {
expect(FREE_FALLBACK_SLUG).toBe("opencode/big-pickle");
});
});
describe("selectFallbackModelIfNeeded", () => {
const empty = new Set<string>();
it("falls back when the resolved model is not in OpenCode's authorized set", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: "anthropic/claude-opus-4-7",
proxyModel: undefined,
authorized: empty,
});
expect(result).toEqual({
fallback: true,
from: "anthropic/claude-opus-4-7",
to: FREE_FALLBACK_SLUG,
});
});
it("does not fall back when the resolved model IS authorized", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: "anthropic/claude-opus-4-7",
proxyModel: undefined,
authorized: new Set(["anthropic/claude-opus-4-7"]),
});
expect(result.fallback).toBe(false);
});
it("does not fall back on Router runs (proxyModel set)", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: undefined,
proxyModel: "openrouter/anthropic/claude-opus-4.7",
authorized: empty,
});
expect(result.fallback).toBe(false);
});
it("does not fall back when no model is resolved (auto-select path)", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: undefined,
proxyModel: undefined,
authorized: empty,
});
expect(result.fallback).toBe(false);
});
it("does not fall back when the resolved model is itself the free fallback", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: FREE_FALLBACK_SLUG,
proxyModel: undefined,
authorized: empty,
});
expect(result.fallback).toBe(false);
});
it("does not fall back for Bedrock routing (raw model ID has no slash)", () => {
// resolveModel({slug:"bedrock/byok"}) returns the raw BEDROCK_MODEL_ID
// value (e.g. "us.anthropic.claude-opus-4-7"), which has no `/`. the
// routing validator (validateBedrockSetup) owns auth + region + model-id
// checking for this path, not the BYOK fallback gate.
const result = selectFallbackModelIfNeeded({
resolvedModel: "us.anthropic.claude-opus-4-7",
proxyModel: undefined,
authorized: empty,
});
expect(result.fallback).toBe(false);
});
it("does not fall back when stored minimax-m2.5-free resolves to big-pickle", () => {
const result = selectFallbackModelIfNeeded({
resolvedModel: resolveCliModel("opencode/minimax-m2.5-free"),
proxyModel: undefined,
authorized: empty,
});
expect(result.fallback).toBe(false);
});
});
utils/byokFallback.ts
-45
View File
@@ -1,45 +0,0 @@
/**
* Slug we fall back to when a BYOK-required model is configured but the
* runner has no provider key in env. Picked because it's free, stable, and
* currently served by OpenCode Zen without a key.
*
* The slug is intentionally hard-coded and not a config knob — the
* fallback is a safety net, not a user-facing preference, and adding a
* config surface here would just push the same "what to fall back to"
* decision into another setting that goes stale the same way.
*/
export const FREE_FALLBACK_SLUG = "opencode/big-pickle";
export type FallbackDecision = { fallback: false } | { fallback: true; from: string; to: string };
/**
* If the resolved model is NOT in OpenCode's `authorized` set (the
* authoritative "what can OpenCode route right now" snapshot captured
* after dbSecrets + Codex auth.json are in place), swap to a free
* OpenCode slug so the run can still produce value. Caller is responsible
* for surfacing the swap (log line + run summary).
*
* Skip cases (return `fallback: false` without consulting `authorized`):
* - Router / proxy runs (`proxyModel` set): Pullfrog mints the key.
* - No resolved model: auto-select handles it downstream.
* - Resolved model is the free fallback already.
* - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
* validators (`validateBedrockSetup` / `validateVertexSetup`) cover
* auth + region/location/model-id; `opencode models` does not.
*/
export function selectFallbackModelIfNeeded(input: {
resolvedModel: string | undefined;
proxyModel: string | undefined;
authorized: Set<string>;
}): FallbackDecision {
if (input.proxyModel) return { fallback: false };
if (!input.resolvedModel) return { fallback: false };
if (input.resolvedModel === FREE_FALLBACK_SLUG) return { fallback: false };
if (!input.resolvedModel.includes("/")) return { fallback: false };
if (input.authorized.has(input.resolvedModel)) return { fallback: false };
return {
fallback: true,
from: input.resolvedModel,
to: FREE_FALLBACK_SLUG,
};
}
utils/codexAuth.ts
-283
View File
@@ -1,283 +0,0 @@
import { spawn } from "node:child_process";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
/**
* minted Codex subscription credential. raw `auth.json` body that Codex CLI /
* OpenCode plugins consume. validated to be `auth_mode: "chatgpt"` with a
* refresh token before being returned. caller is responsible for storing it
* (typically as the `CODEX_AUTH_JSON` Pullfrog secret).
*/
export interface CodexAuth {
/** raw JSON body of the minted `auth.json`; safe to persist verbatim. */
json: string;
/** parsed for caller convenience; mirrors the shape Codex CLI writes. */
parsed: CodexAuthJson;
}
export interface CodexAuthJson {
auth_mode: "chatgpt";
tokens: {
access_token: string;
id_token?: string;
refresh_token: string;
account_id?: string;
};
last_refresh?: string;
}
/** OAuth client id Codex CLI and OpenCode both use against `auth.openai.com`.
* Same chain — a refresh token minted via `codex login --device-auth` can be
* refreshed against this client_id. */
const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
interface OAuthTokenResponse {
access_token: string;
refresh_token: string;
id_token?: string;
expires_in?: number;
}
/** force one refresh round-trip against the OAuth provider so the saved
* credential carries the freshest refresh token. used right after `codex
* login --device-auth` and again any time we want to bump the chain before
* persisting (avoids the user's laptop refreshing first and burning ours). */
export async function refreshCodexAuth(auth: CodexAuth): Promise<CodexAuth> {
const response = await fetch(CODEX_OAUTH_TOKEN_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
refresh_token: auth.parsed.tokens.refresh_token,
client_id: CODEX_OAUTH_CLIENT_ID,
}).toString(),
});
if (!response.ok) {
const body = await response.text().catch(() => "");
throw new Error(`Codex token refresh failed: ${response.status} ${body}`);
}
const tokens = (await response.json()) as OAuthTokenResponse;
const idToken = tokens.id_token ?? auth.parsed.tokens.id_token;
const accountId = auth.parsed.tokens.account_id;
const refreshed: CodexAuthJson = {
auth_mode: "chatgpt",
tokens: {
access_token: tokens.access_token,
refresh_token: tokens.refresh_token,
...(idToken ? { id_token: idToken } : {}),
...(accountId ? { account_id: accountId } : {}),
},
last_refresh: new Date().toISOString(),
};
return { json: `${JSON.stringify(refreshed, null, 2)}\n`, parsed: refreshed };
}
export type ProgressEvent =
| { kind: "start"; attempt: number }
| { kind: "exit"; exitCode: number; signal: NodeJS.Signals | null; timedOut: boolean }
| { kind: "retry"; reason: "user-request" | "no-auth-written" }
| { kind: "cancel" };
interface RunOptions {
/** abort the whole flow when true is returned. polled before each retry. */
shouldRetry: () => Promise<boolean>;
/** observe progress for UI rendering. */
onProgress?: (event: ProgressEvent) => void;
/**
* pass-through control over the child's stdio. `inherit` streams Codex's
* own UI directly to the user's terminal. `pipe` is what `pullfrog auth
* codex` uses so it can re-render each line with a Pullfrog-styled rail
* + dim formatting via `onChildLine`.
*/
childStdio?: "inherit" | "pipe";
/**
* called once per line of Codex's stdout/stderr when `childStdio` is
* "pipe". raw line text is passed through unmodified (including any ANSI
* escapes Codex emitted); the caller is responsible for stripping/styling.
*/
onChildLine?: (line: string, stream: "stdout" | "stderr") => void;
/** how long a single device-auth attempt is allowed to run. */
perAttemptTimeoutMs?: number;
}
/**
* mint a fresh Codex subscription credential by running `codex login
* --device-auth` against an isolated `CODEX_HOME`. the user's global
* `~/.codex/auth.json` is never touched; on success or failure, the
* temporary home is cleaned up.
*
* the caller controls retry behavior via `shouldRetry`: when device auth
* exits without writing `auth.json` (most commonly because the user needed
* to enable device-code auth on their ChatGPT account first), the function
* invokes `shouldRetry()` to decide whether to spin up another attempt.
*/
export async function mintCodexAuth(options: RunOptions): Promise<CodexAuth> {
// mkdtempSync already creates the dir with the default 0o700 perms on
// posix; an extra mkdirSync would just be ceremony.
const codexHome = mkdtempSync(join(tmpdir(), "pullfrog-codex-"));
try {
// device auth requires file-backed credentials; otherwise Codex routes the
// refresh token into the OS keyring and we can't observe / persist it.
writeFileSync(join(codexHome, "config.toml"), 'cli_auth_credentials_store = "file"\n', {
mode: 0o600,
});
const authPath = join(codexHome, "auth.json");
let attempt = 1;
while (true) {
options.onProgress?.({ kind: "start", attempt });
const result = await runDeviceAuth({
codexHome,
timeoutMs: options.perAttemptTimeoutMs ?? 15 * 60 * 1000,
childStdio: options.childStdio ?? "inherit",
onChildLine: options.onChildLine,
});
options.onProgress?.({
kind: "exit",
exitCode: result.exitCode,
signal: result.signal,
timedOut: result.timedOut,
});
const auth = readAuthIfPresent(authPath);
if (auth) return auth;
if (!(await options.shouldRetry())) {
options.onProgress?.({ kind: "cancel" });
throw new Error("Codex login did not produce auth.json (no retry requested)");
}
options.onProgress?.({ kind: "retry", reason: "no-auth-written" });
attempt += 1;
}
} finally {
rmSync(codexHome, { recursive: true, force: true });
}
}
interface DeviceAuthResult {
exitCode: number;
signal: NodeJS.Signals | null;
/** true if the attempt was killed by our per-attempt timeout (vs. exited
* naturally or was interrupted by the user). lets callers distinguish
* "user walked away" from "user closed the device flow early". */
timedOut: boolean;
}
interface DeviceAuthInput {
codexHome: string;
timeoutMs: number;
childStdio: "inherit" | "pipe";
onChildLine?: ((line: string, stream: "stdout" | "stderr") => void) | undefined;
}
/** how long to wait between SIGTERM and SIGKILL when killing a stuck `codex`
* subprocess. Codex usually exits cleanly on SIGTERM, but if it ignores it we
* don't want the CLI pinned forever. */
const SIGTERM_GRACE_MS = 5_000;
/** spawn `codex login --device-auth` with stdin closed so Codex doesn't hang
* waiting for input. by default inherits stdout/stderr so the user sees the
* device URL + one-time code Codex prints; when `pipe`d, lines are forwarded
* to `onChildLine` so the caller can re-style them. on per-attempt timeout,
* sends SIGTERM and escalates to SIGKILL after a short grace.
*/
function runDeviceAuth(input: DeviceAuthInput): Promise<DeviceAuthResult> {
return new Promise((resolve, reject) => {
const child = spawn("codex", ["login", "--device-auth"], {
env: { ...process.env, CODEX_HOME: input.codexHome },
stdio: ["ignore", input.childStdio, input.childStdio],
});
if (input.childStdio === "pipe") {
const onLine = input.onChildLine ?? (() => {});
if (child.stdout) pipeLines(child.stdout, (line) => onLine(line, "stdout"));
if (child.stderr) pipeLines(child.stderr, (line) => onLine(line, "stderr"));
}
let killTimer: NodeJS.Timeout | null = null;
let timedOut = false;
const timeoutTimer = setTimeout(() => {
timedOut = true;
child.kill("SIGTERM");
// give Codex a grace window to exit cleanly on SIGTERM. if it ignores
// it, force SIGKILL so we don't pin the CLI on a stuck child.
killTimer = setTimeout(() => child.kill("SIGKILL"), SIGTERM_GRACE_MS);
}, input.timeoutMs);
// `spawn` emits 'error' (not 'close') when the binary can't be found
// (ENOENT) or otherwise fails to start. without a listener, Node crashes
// the process with an unhandled 'error' event.
child.on("error", (err) => {
clearTimeout(timeoutTimer);
if (killTimer) clearTimeout(killTimer);
const errno = err as NodeJS.ErrnoException;
const message =
errno.code === "ENOENT"
? "codex CLI not found on PATH. install it with `npm i -g @openai/codex` or see https://developers.openai.com/codex/cli for other install options."
: `failed to spawn codex: ${errno.message}`;
reject(new Error(message));
});
child.on("close", (code, signal) => {
clearTimeout(timeoutTimer);
if (killTimer) clearTimeout(killTimer);
resolve({ exitCode: code ?? 1, signal, timedOut });
});
});
}
/** byte-stream → newline-delimited line callback. emits any final partial
* line on stream end so trailing content (e.g. a prompt with no newline)
* still surfaces to the renderer.
*/
function pipeLines(stream: NodeJS.ReadableStream, onLine: (line: string) => void): void {
let buffer = "";
stream.on("data", (chunk: Buffer | string) => {
buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
let idx = buffer.indexOf("\n");
while (idx !== -1) {
const line = buffer.slice(0, idx).replace(/\r$/, "");
buffer = buffer.slice(idx + 1);
onLine(line);
idx = buffer.indexOf("\n");
}
});
stream.on("end", () => {
if (buffer.length > 0) {
onLine(buffer);
buffer = "";
}
});
}
function readAuthIfPresent(authPath: string): CodexAuth | null {
let raw: string;
try {
raw = readFileSync(authPath, "utf8");
} catch {
return null;
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return null;
}
if (!isCodexAuthJson(parsed)) return null;
return { json: raw, parsed };
}
function isCodexAuthJson(value: unknown): value is CodexAuthJson {
if (!value || typeof value !== "object") return false;
const v = value as Record<string, unknown>;
if (v.auth_mode !== "chatgpt") return false;
const tokens = v.tokens;
if (!tokens || typeof tokens !== "object") return false;
const t = tokens as Record<string, unknown>;
if (typeof t.access_token !== "string" || t.access_token.length === 0) return false;
if (typeof t.refresh_token !== "string" || t.refresh_token.length === 0) return false;
return true;
}
utils/codexHome.ts
-140
View File
@@ -1,140 +0,0 @@
// Codex-to-OpenCode auth bridging for the action runtime.
//
// `pullfrog auth codex` stores a Codex CLI `auth.json` blob in the Pullfrog
// per-org secret store (production Postgres) — NOT a GitHub Actions secret.
// This is non-negotiable: the OAuth refresh chain rotates on every use, and
// `entryPost.ts` writes the rotated chain back via `PUT /api/runtime/secret`
// after each run. GH Actions secrets are immutable at runtime, so a token
// stashed there silently expires on the first refresh (~1h). See
// wiki/codex-auth.md for the full constraint.
//
// At runtime, `CODEX_AUTH_JSON` lands in process.env via `runContext.dbSecrets`
// merged in main.ts — sourced from Pullfrog Postgres through the OIDC-validated
// run-context endpoint, never from `${{ secrets.CODEX_AUTH_JSON }}` in
// workflow yaml. This utility:
//
// 1. parses + validates that env value
// 2. converts Codex's shape `{ auth_mode, tokens: { access_token, refresh_token, ... } }`
// into OpenCode's shape `{ openai: { type: "oauth", refresh, access, expires, accountId } }`
// 3. materializes it to disk at the runner's REAL `$HOME/.local/share/opencode/auth.json`
// (NOT the per-run tmpdir's HOME)
// 4. returns the path + the original refresh token so the post-run hook
// can detect a refresh and write back to Pullfrog
//
// Why real $HOME and not ctx.tmpdir-redirected HOME: the broad
// `external_directory: { "/tmp/*": "allow" }` rule on OpenCode would expose
// auth.json to the agent's filesystem tools if the file lived under
// `ctx.tmpdir` = `/tmp/pullfrog-*`. Real `$HOME/.local/share/opencode/...`
// falls outside that allow zone, so OpenCode's deny-default protects it
// without any new permission rules.
//
// `expires: 0` forces OpenCode to refresh on first request (we don't trust
// the in-blob freshness — the saved token was eager-refreshed once at
// `auth codex` time but may have aged since).
//
// See [wiki/codex-auth.md] for the full data-flow picture.
import { mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { log } from "./cli.ts";
const CODEX_AUTH_ENV = "CODEX_AUTH_JSON";
interface CodexAuthBlob {
auth_mode: "chatgpt";
tokens: {
access_token: string;
refresh_token: string;
id_token?: string;
account_id?: string;
};
last_refresh?: string;
}
interface OpenCodeAuthFile {
openai: {
type: "oauth";
refresh: string;
access: string;
expires: number;
accountId?: string;
};
}
export interface InstalledCodexAuth {
/** absolute path of the auth.json we wrote — caller passes this to the
* post-hook via core.saveState for refresh-detection later. */
authPath: string;
/** value to set as XDG_DATA_HOME for the OpenCode subprocess. */
xdgDataHome: string;
/** refresh_token from the env at materialization time. post-hook compares
* against the on-disk file after the run to detect whether OpenCode
* refreshed during the session. */
originalRefresh: string;
}
/** materialize CODEX_AUTH_JSON from env into a disk path OpenCode reads from.
* returns null when the env var is absent, malformed, or wrong auth mode —
* caller treats null as "no codex auth, fall through to API key flow". */
export function installCodexAuth(): InstalledCodexAuth | null {
const raw = process.env[CODEX_AUTH_ENV];
if (!raw) return null;
const blob = parseCodexBlob(raw);
if (!blob) {
log.warning(`» ${CODEX_AUTH_ENV} present but malformed; ignoring`);
return null;
}
const xdgDataHome = join(homedir(), ".local", "share");
const opencodeDir = join(xdgDataHome, "opencode");
const authPath = join(opencodeDir, "auth.json");
const opencodeAuth: OpenCodeAuthFile = {
openai: {
type: "oauth",
refresh: blob.tokens.refresh_token,
access: blob.tokens.access_token,
// expires: 0 forces OpenCode's CodexAuthPlugin to refresh on first
// request (it checks `expires < Date.now()`). safest default — we
// don't carry an `expires_in` from the Codex blob.
expires: 0,
...(blob.tokens.account_id ? { accountId: blob.tokens.account_id } : {}),
},
};
mkdirSync(opencodeDir, { recursive: true });
writeFileSync(authPath, `${JSON.stringify(opencodeAuth, null, 2)}\n`, { mode: 0o600 });
log.info(`» installed Codex auth at ${authPath}`);
return { authPath, xdgDataHome, originalRefresh: blob.tokens.refresh_token };
}
function parseCodexBlob(raw: string): CodexAuthBlob | null {
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return null;
}
if (!parsed || typeof parsed !== "object") return null;
const v = parsed as Record<string, unknown>;
if (v.auth_mode !== "chatgpt") return null;
const tokens = v.tokens;
if (!tokens || typeof tokens !== "object") return null;
const t = tokens as Record<string, unknown>;
if (typeof t.access_token !== "string" || t.access_token.length === 0) return null;
if (typeof t.refresh_token !== "string" || t.refresh_token.length === 0) return null;
return {
auth_mode: "chatgpt",
tokens: {
access_token: t.access_token,
refresh_token: t.refresh_token,
...(typeof t.id_token === "string" ? { id_token: t.id_token } : {}),
...(typeof t.account_id === "string" ? { account_id: t.account_id } : {}),
},
...(typeof v.last_refresh === "string" ? { last_refresh: v.last_refresh } : {}),
};
}
utils/codexRefreshDetect.test.ts
-85
View File
@@ -1,85 +0,0 @@
import { describe, expect, it } from "vitest";
import { detectCodexRefresh } from "./codexRefreshDetect.ts";
// installCodexAuth touches the filesystem (mkdir + writeFile) — leaving it
// untested here per AGENTS.md guidance ("be highly dubious of any test that
// relies on mocks"). The conversion math is what we actually want to
// protect; the disk write is one writeFileSync call.
describe("detectCodexRefresh", () => {
const original = "rt_original_chain";
it("returns Codex-shape JSON when openai.refresh advanced", () => {
const authFileContent = JSON.stringify({
openai: {
type: "oauth",
refresh: "rt_new_chain",
access: "at_new",
expires: 9_999_999_999_999,
accountId: "acc_123",
},
});
const result = detectCodexRefresh({ authFileContent, originalRefresh: original });
expect(result).not.toBeNull();
const parsed = JSON.parse(result ?? "{}");
expect(parsed.auth_mode).toBe("chatgpt");
expect(parsed.tokens.refresh_token).toBe("rt_new_chain");
expect(parsed.tokens.access_token).toBe("at_new");
expect(parsed.tokens.account_id).toBe("acc_123");
expect(typeof parsed.last_refresh).toBe("string");
});
it("omits account_id when accountId is absent from OpenCode shape", () => {
const authFileContent = JSON.stringify({
openai: {
type: "oauth",
refresh: "rt_new",
access: "at_new",
expires: 0,
},
});
const result = detectCodexRefresh({ authFileContent, originalRefresh: original });
const parsed = JSON.parse(result ?? "{}");
expect("account_id" in parsed.tokens).toBe(false);
});
it("returns null when refresh token unchanged (no rotation happened)", () => {
const authFileContent = JSON.stringify({
openai: { type: "oauth", refresh: original, access: "at_same", expires: 0 },
});
expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
});
it("returns null when openai entry is missing", () => {
const authFileContent = JSON.stringify({
anthropic: { type: "oauth", refresh: "rt_other", access: "at_other", expires: 0 },
});
expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
});
it("returns null when openai is api-key type (no refresh chain)", () => {
const authFileContent = JSON.stringify({
openai: { type: "api", key: "sk-something" },
});
expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
});
it("returns null for malformed JSON", () => {
expect(
detectCodexRefresh({ authFileContent: "{not json", originalRefresh: original })
).toBeNull();
});
it("returns null for non-object content", () => {
expect(
detectCodexRefresh({ authFileContent: '"a string"', originalRefresh: original })
).toBeNull();
});
it("returns null when refresh field is missing", () => {
const authFileContent = JSON.stringify({
openai: { type: "oauth", access: "at_new", expires: 0 },
});
expect(detectCodexRefresh({ authFileContent, originalRefresh: original })).toBeNull();
});
});
utils/codexRefreshDetect.ts
-35
View File
@@ -1,35 +0,0 @@
/** Convert an on-disk OpenCode auth.json back to the Codex CLI shape so the
* post-hook can write it to the Pullfrog secret store. Returns null when the
* file's `openai` entry is missing, has the wrong type, or hasn't actually
* refreshed (refresh token unchanged from `originalRefresh`). Lives in its
* own module so `entryPost.ts` can import it without pulling in `codexHome.ts`
* (which imports `./cli.ts` and node fs helpers). */
export function detectCodexRefresh(params: {
authFileContent: string;
originalRefresh: string;
}): string | null {
let parsed: unknown;
try {
parsed = JSON.parse(params.authFileContent);
} catch {
return null;
}
if (!parsed || typeof parsed !== "object") return null;
const oauth = (parsed as Record<string, unknown>).openai;
if (!oauth || typeof oauth !== "object") return null;
const o = oauth as Record<string, unknown>;
if (o.type !== "oauth") return null;
if (typeof o.refresh !== "string" || typeof o.access !== "string") return null;
if (o.refresh === params.originalRefresh) return null;
const codexShape = {
auth_mode: "chatgpt",
tokens: {
access_token: o.access,
refresh_token: o.refresh,
...(typeof o.accountId === "string" ? { account_id: o.accountId } : {}),
},
last_refresh: new Date().toISOString(),
};
return `${JSON.stringify(codexShape, null, 2)}\n`;
}
utils/errorReport.ts
-84
View File
@@ -1,84 +0,0 @@
import type { ToolState } from "../toolState.ts";
import { getApiUrl } from "./apiUrl.ts";
import { buildPullfrogFooter } from "./buildPullfrogFooter.ts";
import { log } from "./cli.ts";
import { createOctokit, parseRepoContext } from "./github.ts";
import { updateProgressComment } from "./progressComment.ts";
import { getGitHubInstallationToken } from "./token.ts";
interface ReportErrorParams {
toolState: ToolState;
error: string;
title?: string;
/**
* When the run has no pre-existing progress comment to update (silent
* IncrementalReview / pull_request_synchronize, mode-less polls), create
* a fresh issue comment on `toolState.issueNumber` instead of returning
* silently. Used for terminal errors (BillingError, TransientError) where
* the GH job summary is the only other surface and most users never open
* it. see #775.
*/
createIfMissing?: boolean;
}
export async function reportErrorToComment(ctx: ReportErrorParams): Promise<void> {
const formattedError = ctx.title ? `${ctx.title}\n\n${ctx.error}` : ctx.error;
const repoContext = parseRepoContext();
const octokit = createOctokit(getGitHubInstallationToken());
const runId = process.env.GITHUB_RUN_ID
? Number.parseInt(process.env.GITHUB_RUN_ID, 10)
: undefined;
const customParts: string[] = [];
if (runId) {
const apiUrl = getApiUrl();
customParts.push(
`[Rerun failed job ➔](${apiUrl}/trigger/${repoContext.owner}/${repoContext.name}/${runId}?action=rerun)`
);
}
const footer = buildPullfrogFooter({
triggeredBy: true,
workflowRun: runId ? { owner: repoContext.owner, repo: repoContext.name, runId } : undefined,
customParts,
model: ctx.toolState.model,
fallbackFrom: ctx.toolState.modelFallback?.from,
});
const body = `${formattedError}${footer}`;
const comment = ctx.toolState.progressComment;
if (comment) {
await updateProgressComment(
{ octokit, owner: repoContext.owner, repo: repoContext.name },
comment,
body
);
ctx.toolState.wasUpdated = true;
return;
}
// silent triggers (pull_request_synchronize IncrementalReview, etc.)
// intentionally have no progress comment. for terminal errors that need
// user action — billing exhaustion, transient billing-service outage —
// surface a fresh issue comment instead of leaving the GH job summary as
// the only signal. see #775.
if (!ctx.createIfMissing) return;
if (!ctx.toolState.issueNumber) return;
try {
const created = await octokit.rest.issues.createComment({
owner: repoContext.owner,
repo: repoContext.name,
issue_number: ctx.toolState.issueNumber,
body,
});
ctx.toolState.progressComment = { id: created.data.id, type: "issue" };
ctx.toolState.wasUpdated = true;
} catch (error) {
log.warning(
`[errorReport] fallback comment create failed: ${error instanceof Error ? error.message : String(error)}`
);
}
}
utils/ghaCore.ts
-13
View File
@@ -1,13 +0,0 @@
/** stdlib-only GitHub Actions helpers for entryPost.ts (no node_modules). */
export function getState(name: string): string {
return process.env[`STATE_${name}`] ?? "";
}
export function info(message: string): void {
console.log(message);
}
export function warning(message: string): void {
console.log(`::warning::${message}`);
}
utils/gitAuthServer.ts
+4 -13
View File
@@ -44,18 +44,9 @@ export type GitAuthServer = {
[Symbol.asyncDispose]: () => Promise<void>;
};
function revokeGitHubToken(token: string): void {
fetch("https://api.github.com/installation/token", {
method: "DELETE",
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/vnd.github+json",
"User-Agent": "pullfrog",
},
}).then(
(r) => log.info(`token revocation response: ${r.status}`),
() => log.warning("token revocation request failed")
);
function revokeToken(_token: string): void {
// For Gitea personal access tokens / bot tokens, revocation is not needed.
log.debug("token revocation skipped (Gitea tokens don't require explicit revocation)");
}
export async function startGitAuthServer(tmpdir: string): Promise<GitAuthServer> {
@@ -91,7 +82,7 @@ export async function startGitAuthServer(tmpdir: string): Promise<GitAuthServer>
// request for a revoked code — the $git() window has closed, so this
// is an agent replaying the code. revoke the token as a precaution.
log.info("askpass code used after revoke — revoking token");
revokeGitHubToken(entry.token);
revokeToken(entry.token);
if (entry.timeout) clearTimeout(entry.timeout);
codes.delete(code);
res.writeHead(409, { "Content-Type": "text/plain" });
utils/gitea.ts
+23
View File
@@ -0,0 +1,23 @@
import { Gitea } from "@go-gitea/sdk.js";
import type { GiteaEndpoints } from "@go-gitea/sdk.js";
export { Gitea };
export type { GiteaEndpoints };
// The SDK's ChangedFile type omits `patch`. Gitea does return it; cast to this when needed.
export interface ChangedFileWithPatch {
filename?: string;
status?: string;
additions?: number;
deletions?: number;
changes?: number;
patch?: string;
[key: string]: unknown;
}
export function createGiteaClient(): Gitea {
const baseUrl = (process.env.GITEA_URL ?? "https://git.shockvpn.com").replace(/\/$/, "");
const token = process.env.BOT_TOKEN;
if (!token) throw new Error("BOT_TOKEN environment variable is required");
return new Gitea({ baseUrl, auth: token });
}
utils/github.ts
-533
View File
@@ -1,533 +0,0 @@
import { createSign } from "node:crypto";
import { rename, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import * as core from "@actions/core";
import { throttling } from "@octokit/plugin-throttling";
import { Octokit } from "@octokit/rest";
import { apiFetch } from "./apiFetch.ts";
import { retry } from "./retry.ts";
function isObject(value: unknown) {
return typeof value === "object" && value !== null;
}
// we don't get access to the actual class from @octokit/rest
// it's reachable from @octokit/request-error but we'd have to add a dependency on it
// and it would pose a risk of accidentally pulling a different version of that class (node_modules dep graphs ❤️)
// so it's safer to ducktype this
interface OctokitResponseShim {
headers: Record<string, string | number | undefined>;
}
export interface InstallationToken {
token: string;
expires_at: string;
installation_id: number;
repository: string;
ref: string;
runner_environment: string;
owner?: string;
}
interface GitHubAppConfig {
appId: string;
privateKey: string;
repoOwner: string;
repoName: string;
}
interface Installation {
id: number;
account: {
login: string;
type: string;
};
}
interface Repository {
owner: {
login: string;
};
name: string;
}
interface InstallationTokenResponse {
token: string;
expires_at: string;
}
interface RepositoriesResponse {
repositories: Repository[];
}
function isOIDCAvailable(): boolean {
// OIDC requires both env vars to be set (only in real GitHub Actions with id-token permission)
return Boolean(
process.env.ACTIONS_ID_TOKEN_REQUEST_URL && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
);
}
type ReadWrite = "read" | "write";
type WriteOnly = "write";
/**
* GitHub App installation access token permissions.
* passed to `POST /app/installations/{id}/access_tokens` to scope the token.
* fields and allowed values come from the `app-permissions` OpenAPI schema.
* @see https://docs.github.com/en/rest/apps/installations#create-an-installation-access-token-for-an-app
* @see https://github.com/github/rest-api-description — components.schemas.app-permissions
*/
type GitHubAppPermissions = {
actions?: ReadWrite;
artifact_metadata?: ReadWrite;
attestations?: ReadWrite;
checks?: ReadWrite;
contents?: ReadWrite;
deployments?: ReadWrite;
discussions?: ReadWrite;
issues?: ReadWrite;
packages?: ReadWrite;
pages?: ReadWrite;
pull_requests?: ReadWrite;
security_events?: ReadWrite;
statuses?: ReadWrite;
workflows?: WriteOnly;
};
type AcquireTokenOptions = {
repos?: string[];
permissions?: GitHubAppPermissions;
};
/**
* Thrown when our token-exchange endpoint returns a non-2xx response.
* The retry policy in `acquireNewToken` looks for this concrete type to
* skip retries — 4xx is terminal user state (not-installed, not-authorized)
* and 5xx is rare enough that re-running the workflow is the right escape
* hatch. Genuine network failures throw plain `Error` and stay retryable.
*/
class TokenExchangeError extends Error {
readonly status: number;
constructor(status: number, message: string) {
super(message);
this.name = "TokenExchangeError";
this.status = status;
}
}
async function acquireTokenViaOIDC(opts?: AcquireTokenOptions): Promise<string> {
const oidcToken = await core.getIDToken("pullfrog-api");
const repos = [...(opts?.repos ?? [])];
const targetRepo = process.env.GITHUB_REPOSITORY?.split("/")[1];
if (targetRepo) {
repos.push(targetRepo);
}
const reposParam = repos.length ? `?repos=${repos.join(",")}` : "";
const timeoutMs = 30000;
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
try {
const tokenResponse = await apiFetch({
path: `/api/github/installation-token${reposParam}`,
method: "POST",
headers: {
Authorization: `Bearer ${oidcToken}`,
"Content-Type": "application/json",
},
body: opts?.permissions ? JSON.stringify({ permissions: opts.permissions }) : undefined,
signal: controller.signal,
});
clearTimeout(timeoutId);
if (!tokenResponse.ok) {
// prefer the server-side `error` field — it's the single source of
// truth for the install URL (uses GITHUB_APP_INSTALL_URL, which
// varies per env / GITHUB_APP_SLUG). fall back to a generic message
// if the body isn't JSON or doesn't carry an `error` field.
let serverMessage: string | undefined;
try {
const body = (await tokenResponse.json()) as { error?: unknown };
if (typeof body.error === "string") serverMessage = body.error;
} catch {
// body wasn't JSON — fall through to the generic message
}
throw new TokenExchangeError(
tokenResponse.status,
serverMessage ??
`Token exchange failed: ${tokenResponse.status} ${tokenResponse.statusText}`
);
}
const tokenData = (await tokenResponse.json()) as InstallationToken;
return tokenData.token;
} catch (error) {
clearTimeout(timeoutId);
if (error instanceof Error && error.name === "AbortError") {
throw new Error(`Token exchange timed out after ${timeoutMs}ms`);
}
throw error;
}
}
const base64UrlEncode = (str: string): string => {
return Buffer.from(str)
.toString("base64")
.replace(/\+/g, "-")
.replace(/\//g, "_")
.replace(/=/g, "");
};
const generateJWT = (appId: string, privateKey: string): string => {
const now = Math.floor(Date.now() / 1000);
const payload = {
iat: now - 60,
exp: now + 5 * 60,
iss: appId,
};
const header = {
alg: "RS256",
typ: "JWT",
};
const encodedHeader = base64UrlEncode(JSON.stringify(header));
const encodedPayload = base64UrlEncode(JSON.stringify(payload));
const signaturePart = `${encodedHeader}.${encodedPayload}`;
const signature = createSign("RSA-SHA256")
.update(signaturePart)
.sign(privateKey, "base64")
.replace(/\+/g, "-")
.replace(/\//g, "_")
.replace(/=/g, "");
return `${signaturePart}.${signature}`;
};
const githubRequest = async <T>(
path: string,
options: {
method?: string;
headers?: Record<string, string>;
body?: string;
} = {}
): Promise<T> => {
const { method = "GET", headers = {}, body } = options;
const url = `https://api.github.com${path}`;
const requestHeaders = {
Accept: "application/vnd.github.v3+json",
"User-Agent": "Pullfrog-Installation-Token-Generator/1.0",
...headers,
};
const response = await fetch(url, {
method,
headers: requestHeaders,
...(body && { body }),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(
`GitHub API request failed: ${response.status} ${response.statusText}\n${errorText}`
);
}
return response.json() as T;
};
const checkRepositoryAccess = async (
token: string,
repoOwner: string,
repoName: string
): Promise<boolean> => {
try {
const response = await githubRequest<RepositoriesResponse>("/installation/repositories", {
headers: { Authorization: `token ${token}` },
});
const ownerLower = repoOwner.toLowerCase();
const nameLower = repoName.toLowerCase();
return response.repositories.some(
(repo) =>
repo.owner.login.toLowerCase() === ownerLower && repo.name.toLowerCase() === nameLower
);
} catch {
return false;
}
};
const createInstallationToken = async (
jwt: string,
installationId: number,
permissions?: GitHubAppPermissions
): Promise<string> => {
const requestOpts: { method: string; headers: Record<string, string>; body?: string } = {
method: "POST",
headers: { Authorization: `Bearer ${jwt}` },
};
if (permissions) {
requestOpts.body = JSON.stringify({ permissions });
}
const response = await githubRequest<InstallationTokenResponse>(
`/app/installations/${installationId}/access_tokens`,
requestOpts
);
return response.token;
};
const findInstallationId = async (
jwt: string,
repoOwner: string,
repoName: string
): Promise<number> => {
const installations = await githubRequest<Installation[]>("/app/installations", {
headers: { Authorization: `Bearer ${jwt}` },
});
for (const installation of installations) {
try {
const tempToken = await createInstallationToken(jwt, installation.id);
const hasAccess = await checkRepositoryAccess(tempToken, repoOwner, repoName);
if (hasAccess) {
return installation.id;
}
} catch {}
}
throw new Error(
`No installation found with access to ${repoOwner}/${repoName}. ` +
"Ensure the GitHub App is installed on the target repository."
);
};
// for local development only
async function acquireTokenViaGitHubApp(opts?: AcquireTokenOptions): Promise<string> {
if (!process.env.GITHUB_APP_ID || !process.env.GITHUB_PRIVATE_KEY) {
throw new Error(
"cannot acquire token via GitHub App: GITHUB_APP_ID and GITHUB_PRIVATE_KEY must be set"
);
}
const repoContext = parseRepoContext();
const config: GitHubAppConfig = {
appId: process.env.GITHUB_APP_ID,
privateKey: process.env.GITHUB_PRIVATE_KEY.replace(/\\n/g, "\n"),
repoOwner: repoContext.owner,
repoName: repoContext.name,
};
const jwt = generateJWT(config.appId, config.privateKey);
const installationId = await findInstallationId(jwt, config.repoOwner, config.repoName);
return await createInstallationToken(jwt, installationId, opts?.permissions);
}
/**
* ensure a GitHub token is available in the environment.
*
* when OIDC is available (CI), always mints a fresh token scoped to
* GITHUB_REPOSITORY — overriding any inherited GITHUB_TOKEN that may
* be scoped to the wrong repo.
*
* otherwise falls back to GitHub App credentials for local development.
*
* only called from play.ts (test/dev path) — the live action calls
* main() directly and never calls this.
*/
export async function ensureGitHubToken(): Promise<void> {
// when OIDC is available, always mint a fresh token scoped to
// GITHUB_REPOSITORY. the inherited GITHUB_TOKEN may be scoped to a
// different repo (e.g., runner token for pullfrog/app when tests
// target pullfrog/test-repo).
if (isOIDCAvailable()) {
const token = await acquireNewToken();
process.env.GITHUB_TOKEN = token;
return;
}
if (!process.env.GITHUB_TOKEN && !process.env.GH_TOKEN) {
const token = await acquireNewToken();
process.env.GITHUB_TOKEN = token;
}
}
export async function acquireNewToken(opts?: AcquireTokenOptions): Promise<string> {
if (isOIDCAvailable()) {
return await retry(() => acquireTokenViaOIDC(opts), {
label: "token exchange",
shouldRetry: (error) => {
// 4xx is terminal user state (app not installed, permissions wrong) —
// retrying just triples our log noise and the user's CI bill (see
// #693). 5xx/429 are transient (vercel cold start, github outage,
// rate limit) and should ride the existing backoff.
if (error instanceof TokenExchangeError) return error.status >= 500 || error.status === 429;
return (
error instanceof Error &&
(error.message.includes("timed out") ||
error.message.includes("fetch failed") ||
error.message.includes("ECONNRESET") ||
error.message.includes("ETIMEDOUT"))
);
},
});
}
// running inside GitHub Actions but the OIDC env vars are absent — the
// workflow is missing `permissions: id-token: write`. surface an
// actionable, customer-facing message; the GitHub-App branch below is
// local-dev only. see #739.
if (process.env.GITHUB_ACTIONS === "true") {
throw new Error(
"missing `permissions: id-token: write` on the Pullfrog workflow job.\n" +
"\n" +
"Pullfrog mints short-lived GitHub App installation tokens via OIDC and\n" +
"requires `id-token: write` to be granted at the job level. add the\n" +
"following to your workflow yaml:\n" +
"\n" +
" jobs:\n" +
" pullfrog:\n" +
" permissions:\n" +
" id-token: write # mint Pullfrog installation tokens via OIDC\n" +
" contents: read # for actions/checkout\n" +
"\n" +
"see https://docs.pullfrog.com/headless-action#required-permissions for the full template."
);
}
// local development via GitHub App
return await acquireTokenViaGitHubApp(opts);
}
export interface RepoContext {
owner: string;
name: string;
}
/**
* Parse repository context from GITHUB_REPOSITORY environment variable.
*/
export function parseRepoContext(): RepoContext {
const githubRepo = process.env.GITHUB_REPOSITORY;
if (!githubRepo) {
throw new Error("GITHUB_REPOSITORY environment variable is required");
}
const [owner, name] = githubRepo.split("/");
if (!owner || !name) {
throw new Error(`Invalid GITHUB_REPOSITORY format: ${githubRepo}. Expected 'owner/repo'`);
}
return { owner, name };
}
export type OctokitWithPlugins = InstanceType<
ReturnType<typeof Octokit.plugin<typeof Octokit, [typeof throttling]>>
>;
export interface ResourceUsage {
requestCount: number;
rateLimitRemaining: number | null;
rateLimitResetMs: number | null;
}
function emptyResourceUsage(): ResourceUsage {
return {
requestCount: 0,
rateLimitRemaining: null,
rateLimitResetMs: null,
};
}
const usageByResource: Record<string, ResourceUsage> = {
core: emptyResourceUsage(),
graphql: emptyResourceUsage(),
};
export interface UsageSummary {
version: 1;
github: {
core: ResourceUsage;
graphql: ResourceUsage;
};
}
function getGitHubUsageSummary(): UsageSummary {
return {
version: 1,
github: {
core: usageByResource.core,
graphql: usageByResource.graphql,
},
};
}
export async function writeGitHubUsageSummaryToFile(path: string): Promise<void> {
const summary = getGitHubUsageSummary();
const tmpPath = join(dirname(path), `.usage-summary-${process.pid}.tmp`);
await writeFile(tmpPath, JSON.stringify(summary));
await rename(tmpPath, path);
}
export function createOctokit(token: string): OctokitWithPlugins {
// `OctokitWithPlugins` initialization based on https://github.com/actions/toolkit/blob/2506e78e82fbd2f9e94d63e75f5309118c8de1b1/packages/github/src/github.ts#L15-L22
// we can't use it directly because it's stuck on `@octokit/core@v5` and we use the hottest `@octokit/core@v7`
const OctokitWithPlugins = Octokit.plugin(throttling);
const octokit = new OctokitWithPlugins({
auth: token,
throttle: {
onRateLimit: (_retryAfter, _options, _octokit, retryCount) => {
return retryCount <= 2;
},
onSecondaryRateLimit: (_retryAfter, _options, _octokit, retryCount) => {
return retryCount <= 2;
},
},
});
const onResponse = (response: OctokitResponseShim) => {
const resource = response.headers["x-ratelimit-resource"];
if (!resource) {
return response;
}
usageByResource[resource] ??= emptyResourceUsage();
const usage = usageByResource[resource];
usage.requestCount++;
const remaining = response.headers["x-ratelimit-remaining"];
const reset = response.headers["x-ratelimit-reset"];
if (remaining !== undefined) {
usage.rateLimitRemaining = Number(remaining);
}
if (reset !== undefined) {
usage.rateLimitResetMs = Number(reset) * 1000;
}
return response;
};
octokit.hook.wrap("request", async (request, options) => {
try {
const response = await request(options);
onResponse(response);
return response;
} catch (error) {
if (
isObject(error) &&
"response" in error &&
isObject(error.response) &&
"headers" in error.response &&
isObject(error.response.headers)
) {
onResponse(error.response as OctokitResponseShim);
}
throw error;
}
});
return octokit;
}
utils/install.ts
-486
View File
@@ -1,486 +0,0 @@
import { spawnSync } from "node:child_process";
import { chmodSync, createWriteStream, existsSync, mkdirSync } from "node:fs";
import { mkdtemp } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pipeline } from "node:stream/promises";
import { setTimeout as sleep } from "node:timers/promises";
import { log } from "./cli.ts";
export interface InstallFromNpmTarballParams {
packageName: string;
version: string;
executablePath: string;
installDependencies?: boolean;
}
export interface InstallFromCurlParams {
installUrl: string;
executableName: string;
}
export interface InstallFromDirectTarballParams {
url: string;
executablePath: string;
stripComponents?: number;
}
export interface InstallFromGithubParams {
owner: string;
repo: string;
tag?: string;
assetName?: string;
executablePath?: string;
githubInstallationToken?: string;
}
export interface InstallFromGithubTarballParams {
owner: string;
repo: string;
tag?: string;
assetNamePattern: string;
executablePath: string;
githubInstallationToken?: string;
}
interface NpmRegistryData {
"dist-tags": { latest: string };
versions: Record<string, unknown>;
}
/**
* Install a CLI tool from an npm package tarball
* Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable
* The temp directory will be cleaned up by the OS automatically
*/
export async function installFromNpmTarball(params: InstallFromNpmTarballParams): Promise<string> {
const tempDir = process.env.PULLFROG_TEMP_DIR;
if (!tempDir) throw new Error("PULLFROG_TEMP_DIR is not set");
const extractedDir = join(tempDir, "package");
const cliPath = join(extractedDir, params.executablePath);
if (existsSync(cliPath)) {
log.debug(`» using cached binary at ${cliPath}`);
return cliPath;
}
// Resolve version if it's a range or "latest"
let resolvedVersion = params.version;
if (
params.version.startsWith("^") ||
params.version.startsWith("~") ||
params.version === "latest"
) {
const npmRegistry = process.env.NPM_REGISTRY || "https://registry.npmjs.org";
log.debug(`» resolving version for ${params.version}...`);
try {
const registryResponse = await fetch(`${npmRegistry}/${params.packageName}`);
if (!registryResponse.ok) {
throw new Error(`Failed to query registry: ${registryResponse.status}`);
}
const registryData = (await registryResponse.json()) as NpmRegistryData;
resolvedVersion = registryData["dist-tags"].latest;
log.debug(`» resolved to version ${resolvedVersion}`);
} catch (error) {
log.warning(
`Failed to resolve version from registry: ${error instanceof Error ? error.message : String(error)}`
);
throw error;
}
}
log.debug(`» installing ${params.packageName}@${resolvedVersion}...`);
const tarballPath = join(tempDir, "package.tgz");
// Download tarball from npm
const npmRegistry = process.env.NPM_REGISTRY || "https://registry.npmjs.org";
// Handle scoped packages (e.g., @scope/package -> @scope%2Fpackage/-/package-version.tgz)
let tarballUrl: string;
if (params.packageName.startsWith("@")) {
const [scope, name] = params.packageName.slice(1).split("/");
const scopedPackageName = `@${scope}%2F${name}`;
tarballUrl = `${npmRegistry}/${scopedPackageName}/-/${name}-${resolvedVersion}.tgz`;
} else {
tarballUrl = `${npmRegistry}/${params.packageName}/-/${params.packageName}-${resolvedVersion}.tgz`;
}
log.debug(`» downloading from ${tarballUrl}...`);
const response = await fetch(tarballUrl);
if (!response.ok) {
throw new Error(`Failed to download tarball: ${response.status} ${response.statusText}`);
}
// Write tarball to file
if (!response.body) throw new Error("Response body is null");
const fileStream = createWriteStream(tarballPath);
await pipeline(response.body, fileStream);
log.debug(`» downloaded tarball to ${tarballPath}`);
// Extract tarball
log.debug(`» extracting tarball...`);
const extractResult = spawnSync("tar", ["-xzf", tarballPath, "-C", tempDir], {
stdio: "pipe",
encoding: "utf-8",
});
if (extractResult.status !== 0) {
throw new Error(
`Failed to extract tarball: ${extractResult.stderr || extractResult.stdout || "Unknown error"}`
);
}
if (!existsSync(cliPath)) {
throw new Error(`Executable not found in extracted package at ${cliPath}`);
}
// Install dependencies if requested
if (params.installDependencies) {
log.debug(`» installing dependencies for ${params.packageName}...`);
const installResult = spawnSync("npm", ["install", "--production"], {
cwd: extractedDir,
stdio: "pipe",
encoding: "utf-8",
});
if (installResult.status !== 0) {
throw new Error(
`Failed to install dependencies: ${installResult.stderr || installResult.stdout || "Unknown error"}`
);
}
log.debug(`» dependencies installed`);
}
// Make the file executable
chmodSync(cliPath, 0o755);
log.debug(`» ${params.packageName} installed at ${cliPath}`);
return cliPath;
}
/**
* Fetch with retry logic if Retry-After header is present
*/
async function fetchWithRetry(
url: string,
headers: Record<string, string>,
errorMessage: string
): Promise<Response> {
const response = await fetch(url, { headers });
if (!response.ok) {
const retryAfter = response.headers.get("Retry-After") || response.headers.get("retry-after");
if (retryAfter) {
const waitSeconds = parseInt(retryAfter, 10);
if (!Number.isNaN(waitSeconds) && waitSeconds > 0) {
log.info(`» rate limited, waiting ${waitSeconds} seconds before retry...`);
await sleep(waitSeconds * 1000);
const retryResponse = await fetch(url, { headers });
if (!retryResponse.ok) {
throw new Error(
`${errorMessage}: ${retryResponse.status} ${retryResponse.statusText} (retry failed)`
);
}
return retryResponse;
}
}
throw new Error(`${errorMessage}: ${response.status} ${response.statusText}`);
}
return response;
}
/**
* Install a CLI tool from GitHub releases
* Downloads the latest release asset from GitHub and returns the path to the executable
* The temp directory will be cleaned up by the OS automatically
*/
export async function installFromGithub(params: InstallFromGithubParams): Promise<string> {
// use a deterministic subdir in PULLFROG_TEMP_DIR so repeated calls are cached
const pullfrogTemp = process.env.PULLFROG_TEMP_DIR;
const installDir = pullfrogTemp
? join(pullfrogTemp, `github-${params.owner}-${params.repo}`)
: await mkdtemp(join(tmpdir(), `${params.owner}-${params.repo}-github-`));
const expectedCliPath = join(installDir, params.executablePath ?? params.assetName ?? "asset");
if (existsSync(expectedCliPath)) {
log.debug(`» using cached binary at ${expectedCliPath}`);
return expectedCliPath;
}
log.info(`» installing ${params.owner}/${params.repo} from GitHub releases...`);
// fetch release from GitHub API (pinned tag or latest)
const releaseUrl = params.tag
? `https://api.github.com/repos/${params.owner}/${params.repo}/releases/tags/${params.tag}`
: `https://api.github.com/repos/${params.owner}/${params.repo}/releases/latest`;
log.debug(`» fetching release from ${releaseUrl}...`);
const headers: Record<string, string> = {};
if (params.githubInstallationToken) {
headers.Authorization = `Bearer ${params.githubInstallationToken}`;
}
const releaseResponse = await fetchWithRetry(releaseUrl, headers, "Failed to fetch release");
const releaseData = (await releaseResponse.json()) as {
tag_name: string;
assets: Array<{
name: string;
browser_download_url: string;
}>;
};
log.debug(`» found release ${releaseData.tag_name}`);
const asset = releaseData.assets.find((a) => a.name === params.assetName);
if (!asset) {
throw new Error(`Asset '${params.assetName}' not found in release ${releaseData.tag_name}`);
}
const assetUrl = asset.browser_download_url;
log.debug(`» downloading asset from ${assetUrl}...`);
mkdirSync(installDir, { recursive: true });
// determine file extension and download path
const urlPath = new URL(assetUrl).pathname;
const fileName = urlPath.split("/").pop() || "asset";
const downloadPath = join(installDir, fileName);
// download the asset
const assetResponse = await fetchWithRetry(assetUrl, headers, "Failed to download asset");
if (!assetResponse.body) throw new Error("Response body is null");
const fileStream = createWriteStream(downloadPath);
await pipeline(assetResponse.body, fileStream);
log.debug(`» downloaded asset to ${downloadPath}`);
// determine the executable path
const cliPath = params.executablePath ? join(installDir, params.executablePath) : downloadPath;
if (!existsSync(cliPath)) {
throw new Error(`Executable not found at ${cliPath}`);
}
chmodSync(cliPath, 0o755);
log.info(`» installed from GitHub release at ${cliPath}`);
return cliPath;
}
/**
* Install a CLI tool from a GitHub release tarball
* Downloads the tar.gz from GitHub releases, extracts it, and returns the path to the CLI executable
* The temp directory will be cleaned up by the OS automatically
*/
export async function installFromGithubTarball(
params: InstallFromGithubTarballParams
): Promise<string> {
const tempDir = process.env.PULLFROG_TEMP_DIR;
if (!tempDir) throw new Error("PULLFROG_TEMP_DIR is not set");
const cliPath = join(tempDir, params.executablePath);
if (existsSync(cliPath)) {
log.debug(`» using cached binary at ${cliPath}`);
return cliPath;
}
log.info(`» installing ${params.owner}/${params.repo} from GitHub releases...`);
// determine platform-specific asset name
const os = process.platform === "darwin" ? "darwin" : "linux";
const arch = process.arch === "arm64" ? "arm64" : "x64";
const assetName = params.assetNamePattern.replace("{os}", os).replace("{arch}", arch);
// fetch release from GitHub API (pinned tag or latest)
const releaseUrl = params.tag
? `https://api.github.com/repos/${params.owner}/${params.repo}/releases/tags/${params.tag}`
: `https://api.github.com/repos/${params.owner}/${params.repo}/releases/latest`;
log.info(`» fetching release from ${releaseUrl}...`);
const headers: Record<string, string> = {};
if (params.githubInstallationToken) {
headers.Authorization = `Bearer ${params.githubInstallationToken}`;
}
const releaseResponse = await fetchWithRetry(releaseUrl, headers, "Failed to fetch release");
const releaseData = (await releaseResponse.json()) as {
tag_name: string;
assets: Array<{
name: string;
browser_download_url: string;
}>;
};
log.debug(`» found release: ${releaseData.tag_name}`);
const asset = releaseData.assets.find((a) => a.name === assetName);
if (!asset) {
throw new Error(`Asset '${assetName}' not found in release ${releaseData.tag_name}`);
}
const assetUrl = asset.browser_download_url;
log.debug(`» downloading asset from ${assetUrl}...`);
const tarballPath = join(tempDir, assetName);
// download the asset
const assetResponse = await fetchWithRetry(assetUrl, headers, "Failed to download asset");
if (!assetResponse.body) throw new Error("Response body is null");
const fileStream = createWriteStream(tarballPath);
await pipeline(assetResponse.body, fileStream);
log.debug(`» downloaded tarball to ${tarballPath}`);
// extract tar.gz
log.debug(`» extracting tarball...`);
const extractResult = spawnSync("tar", ["-xzf", tarballPath, "-C", tempDir], {
stdio: "pipe",
encoding: "utf-8",
});
if (extractResult.status !== 0) {
throw new Error(
`Failed to extract tarball: ${extractResult.stderr || extractResult.stdout || "Unknown error"}`
);
}
if (!existsSync(cliPath)) {
throw new Error(`Executable not found in extracted tarball at ${cliPath}`);
}
// make the file executable
chmodSync(cliPath, 0o755);
log.info(`» ${params.owner}/${params.repo} installed at ${cliPath}`);
return cliPath;
}
/**
* Install a CLI tool from a direct tarball URL.
* Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable.
*/
export async function installFromDirectTarball(
params: InstallFromDirectTarballParams
): Promise<string> {
const tempDir = process.env.PULLFROG_TEMP_DIR;
if (!tempDir) throw new Error("PULLFROG_TEMP_DIR is not set");
const extractDir = join(tempDir, "direct-package");
const cliPath = join(extractDir, params.executablePath);
if (existsSync(cliPath)) {
log.debug(`» using cached binary at ${cliPath}`);
return cliPath;
}
log.info(`» downloading tarball from ${params.url}...`);
const tarballPath = join(tempDir, "direct-package.tgz");
const response = await fetchWithRetry(params.url, {}, "failed to download tarball");
if (!response.body) throw new Error("response body is null");
const fileStream = createWriteStream(tarballPath);
await pipeline(response.body, fileStream);
log.debug(`» downloaded tarball to ${tarballPath}`);
mkdirSync(extractDir, { recursive: true });
const tarArgs = ["-xzf", tarballPath, "-C", extractDir];
if (params.stripComponents !== undefined && params.stripComponents > 0) {
tarArgs.push(`--strip-components=${Math.floor(params.stripComponents)}`);
}
log.debug(`» extracting tarball...`);
const extractResult = spawnSync("tar", tarArgs, {
stdio: "pipe",
encoding: "utf-8",
});
if (extractResult.status !== 0) {
throw new Error(
`failed to extract tarball: ${extractResult.stderr || extractResult.stdout || "unknown error"}`
);
}
if (!existsSync(cliPath)) {
throw new Error(`executable not found in extracted tarball at ${cliPath}`);
}
chmodSync(cliPath, 0o755);
log.info(`» installed at ${cliPath}`);
return cliPath;
}
/**
* Install a CLI tool from a curl-based install script
* Downloads the install script, runs it with HOME set to temp directory, and returns the path to the CLI executable
* The temp directory will be cleaned up by the OS automatically
*/
export async function installFromCurl(params: InstallFromCurlParams): Promise<string> {
const tempDir = process.env.PULLFROG_TEMP_DIR;
if (!tempDir) throw new Error("PULLFROG_TEMP_DIR is not set");
const cliPath = join(tempDir, ".local", "bin", params.executableName);
if (existsSync(cliPath)) {
log.debug(`» using cached binary at ${cliPath}`);
return cliPath;
}
log.info(`» installing ${params.executableName}...`);
const installScriptPath = join(tempDir, "install.sh");
// Download the install script
log.debug(`» downloading install script from ${params.installUrl}...`);
const installScriptResponse = await fetch(params.installUrl);
if (!installScriptResponse.ok) {
throw new Error(`Failed to download install script: ${installScriptResponse.status}`);
}
if (!installScriptResponse.body) throw new Error("Response body is null");
const fileStream = createWriteStream(installScriptPath);
await pipeline(installScriptResponse.body, fileStream);
log.debug(`» downloaded install script to ${installScriptPath}`);
// Make install script executable
chmodSync(installScriptPath, 0o755);
log.debug(`» installing to temp directory at ${tempDir}...`);
const installResult = spawnSync("bash", [installScriptPath], {
cwd: tempDir,
env: {
// Run the install script with HOME set to temp directory
// ensuring a fresh install for each run
HOME: tempDir,
// XDG_CONFIG_HOME must match HOME so CLI tools find config in the right place
XDG_CONFIG_HOME: join(tempDir, ".config"),
SHELL: process.env.SHELL,
USER: process.env.USER,
},
stdio: "pipe",
encoding: "utf-8",
});
if (installResult.status !== 0) {
const errorOutput = installResult.stderr || installResult.stdout || "No output";
throw new Error(
`Failed to install ${params.executableName}. Install script exited with code ${installResult.status}. Output: ${errorOutput}`
);
}
if (!existsSync(cliPath)) {
throw new Error(`Executable not found at ${cliPath}`);
}
// Ensure binary is executable
chmodSync(cliPath, 0o755);
log.info(`» ${params.executableName} installed at ${cliPath}`);
return cliPath;
}
utils/instructions.ts
+66 -214
View File
@@ -1,26 +1,21 @@
// changes to prompt assembly should be reflected in wiki/prompt.md
// changes to prompt assembly should be reflected in documentation
import { execSync } from "node:child_process";
import { encode as toonEncode } from "@toon-format/toon";
import { type AgentId, formatMcpToolRef, type PayloadEvent, pullfrogMcpName } from "../external.ts";
import { type AgentId, formatMcpToolRef, shockbotMcpName, type PayloadEvent } from "../external.ts";
import type { Mode } from "../modes.ts";
import type { ResolvedPayload } from "./payload.ts";
import type { LearningsHeading } from "./runContext.ts";
import type { RunContextData } from "./runContextData.ts";
interface RepoContext {
owner: string;
name: string;
defaultBranch?: string;
}
interface InstructionsContext {
payload: ResolvedPayload;
repo: RunContextData["repo"];
repo: RepoContext;
modes: Mode[];
agentId: AgentId;
outputSchema?: Record<string, unknown> | undefined;
/** absolute path to the seeded learnings tmpfile, or null when the file
* couldn't be seeded for some reason. main.ts always seeds, so in
* practice this is always set; the null case keeps the type honest. */
learningsFilePath: string | null;
/** server-parsed TOC for the body of the learnings tmpfile. rendered
* inline into the LEARNINGS prompt section so the agent can `read_file`
* targeted line ranges instead of pulling the whole file into context. */
learningsHeadings: LearningsHeading[];
}
interface PromptContext extends InstructionsContext {
@@ -31,66 +26,53 @@ interface PromptContext extends InstructionsContext {
userQuoted: string;
}
function buildRuntimeContext(ctx: InstructionsContext): string {
// extract payload fields excluding prompt/instructions/event (those are rendered separately)
const {
"~pullfrog": _,
prompt: _p,
eventInstructions: _ei,
previousRunsNote: _prn,
event: _e,
...payloadRest
} = ctx.payload;
function encodePlain(data: Record<string, unknown>): string {
return Object.entries(data)
.filter(([, v]) => v !== undefined)
.map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`)
.join("\n");
}
function buildRuntimeContext(ctx: InstructionsContext): string {
let gitStatus: string | undefined;
try {
gitStatus =
execSync("git status --short", { encoding: "utf-8", stdio: "pipe" }).trim() || "(clean)";
} catch {
// git not available or not in a repo
// git not available
}
const data: Record<string, unknown> = {
...payloadRest,
model: ctx.payload.model,
push: ctx.payload.push,
shell: ctx.payload.shell,
triggerer: ctx.payload.triggerer,
repo: `${ctx.repo.owner}/${ctx.repo.name}`,
default_branch: ctx.repo.data.default_branch,
default_branch: ctx.repo.defaultBranch,
working_directory: process.cwd(),
log_level: process.env.LOG_LEVEL,
git_status: gitStatus,
github_event_name: process.env.GITHUB_EVENT_NAME,
github_ref: process.env.GITHUB_REF,
github_sha: process.env.GITHUB_SHA?.slice(0, 7),
github_actor: process.env.GITHUB_ACTOR,
github_run_id: process.env.GITHUB_RUN_ID,
github_workflow: process.env.GITHUB_WORKFLOW,
gitea_event_name: process.env.GITHUB_EVENT_NAME,
gitea_ref: process.env.GITHUB_REF,
gitea_sha: process.env.GITHUB_SHA?.slice(0, 7),
gitea_actor: process.env.GITHUB_ACTOR,
};
// filter out undefined values
const filtered = Object.fromEntries(Object.entries(data).filter(([_, v]) => v !== undefined));
return toonEncode(filtered);
return encodePlain(filtered);
}
function buildEventTitle(event: PayloadEvent): string {
const trimmedTitle = typeof event.title === "string" ? event.title.trim() : "";
if (!trimmedTitle) return "";
const prefix = event.issue_number ? `${event.is_pr ? "PR" : "Issue"} #${event.issue_number}` : "";
return prefix ? `${prefix} ("${trimmedTitle}")` : `("${trimmedTitle}")`;
}
function buildEventMetadata(event: PayloadEvent): string {
const { title: _t, body: _b, trigger, ...rest } = event;
// include trigger in rest unless it's workflow_dispatch (not informative)
const restWithTrigger = trigger === "workflow_dispatch" ? rest : { trigger, ...rest };
if (Object.keys(restWithTrigger).length === 0) {
return "";
}
return toonEncode(restWithTrigger);
if (Object.keys(restWithTrigger).length === 0) return "";
return encodePlain(restWithTrigger as Record<string, unknown>);
}
function getShellInstructions(
@@ -99,17 +81,11 @@ function getShellInstructions(
): string {
switch (shell) {
case "disabled":
return `### Shell commands
Shell command execution is DISABLED. Do not attempt to run shell commands.`;
return `### Shell commands\n\nShell command execution is DISABLED. Do not attempt to run shell commands.`;
case "restricted":
return `### Shell commands
Use the \`${t("shell")}\` MCP tool for all shell command execution. This tool provides a secure environment with filtered credentials. Do NOT use any native shell tool — it is disabled for security. For long-running processes (dev servers, watchers), use \`shell({ command, background: true })\`. Use \`${t("kill_background")}\` to stop background processes.`;
return `### Shell commands\n\nUse the \`${t("shell")}\` MCP tool for all shell command execution. This tool provides a secure environment with filtered credentials. Do NOT use any native shell tool — it is disabled for security. For long-running processes, use \`shell({ command, background: true })\`. Use \`${t("kill_background")}\` to stop background processes.`;
case "enabled":
return `### Shell commands
Use your native shell tool for shell command execution.`;
return `### Shell commands\n\nUse your native shell tool for shell command execution.`;
default: {
const _exhaustive: never = shell;
return _exhaustive satisfies never;
@@ -118,9 +94,7 @@ Use your native shell tool for shell command execution.`;
}
function getFileInstructions(): string {
return `### File operations
Use your native file read/write/edit tools for all file operations.`;
return `### File operations\n\nUse your native file read/write/edit tools for all file operations.`;
}
function getStandaloneModeInstructions(
@@ -128,17 +102,13 @@ function getStandaloneModeInstructions(
t: (name: string) => string,
outputSchema?: Record<string, unknown> | undefined
): string {
if (trigger !== "unknown") {
return "";
}
if (trigger !== "unknown") return "";
const outputRequirement = outputSchema
? `**REQUIRED structured output:** You MUST call \`${t("set_output")}\` before finishing. The tool expects a structured object matching a JSON Schema — inspect its parameter schema to see the exact shape. Omitting this call or providing non-conforming output will fail the action.`
: `When you complete your task, call \`${t("set_output")}\` with the main result of your work (generated content, summary of changes, analysis results, etc.). This makes it available as a GitHub Action output named \`result\` for subsequent workflow steps to consume. When in doubt, prefer calling \`set_output\`—unused outputs are harmless, but missing outputs may break downstream steps.`;
? `**REQUIRED structured output:** You MUST call \`${t("set_output")}\` before finishing.`
: `When you complete your task, call \`${t("set_output")}\` with the main result of your work.`;
return `### Standalone mode
You are running as a step in a user-defined CI workflow. ${outputRequirement}`;
return `### Standalone mode\n\nYou are running as a step in a CI workflow. ${outputRequirement}`;
}
const priorityOrder = `## Priority Order
@@ -148,41 +118,23 @@ In case of conflict between instructions, follow this precedence (highest to low
2. User prompt
3. Event-level instructions`;
// ---------------------------------------------------------------------------
// section builders
// ---------------------------------------------------------------------------
// the user's task: blockquoted user prompt, or event-level instructions for auto-triggers.
// `previousRunsNote` is system-injected context (e.g. prior runs superseded by a
// comment edit); it's appended regardless of which branch wins so it survives
// user-prompt precedence over eventInstructions.
function buildTaskSection(ctx: PromptContext): string {
const previousRunsNote = ctx.payload.previousRunsNote?.trim() ?? "";
if (ctx.userQuoted) {
const parts = [ctx.userQuoted, previousRunsNote].filter(Boolean);
return `************* YOUR TASK *************
${parts.join("\n\n")}`;
return `************* YOUR TASK *************\n\n${ctx.userQuoted}`;
}
const eventInstructions = ctx.payload.eventInstructions ?? "";
if (eventInstructions || previousRunsNote) {
const parts = [ctx.eventTitle, eventInstructions, previousRunsNote].filter(Boolean);
return `************* YOUR TASK *************
${parts.join("\n\n")}`;
if (eventInstructions) {
const parts = [ctx.eventTitle, eventInstructions].filter(Boolean);
return `************* YOUR TASK *************\n\n${parts.join("\n\n")}`;
}
return "";
}
// mode selection and execution steps
function buildProcedure(ctx: PromptContext): string {
const t = ctx.t;
return `************* PROCEDURE *************
You execute tasks directly using your native tools and the ${pullfrogMcpName} MCP server.
You execute tasks directly using your native tools and the ${shockbotMcpName} MCP server.
### Step 1: Select a mode
@@ -195,32 +147,25 @@ ${ctx.modes.map((m) => `- "${m.name}": ${m.description}`).join("\n")}
### Step 2: Execute
Follow the mode guidance to complete the task. Use your native file and shell tools for local operations, and the ${pullfrogMcpName} MCP tools for GitHub/git operations.
Follow the mode guidance to complete the task. Use your native file and shell tools for local operations, and the ${shockbotMcpName} MCP tools for Gitea/git operations.
### No-action cases
If the task clearly requires no work, call \`${t("report_progress")}\` directly to explain why no action is needed.
Eagerly inspect the MCP tools available to you via the \`${pullfrogMcpName}\` MCP server. These are VITALLY IMPORTANT to completing your task.`;
Eagerly inspect the MCP tools available to you via the \`${shockbotMcpName}\` MCP server. These are VITALLY IMPORTANT to completing your task.`;
}
// event title + metadata (omitted when empty, e.g. workflow_dispatch)
function buildEventContext(ctx: PromptContext): string {
const isPr = ctx.payload.event.is_pr === true;
const relatedLabel = isPr ? "--- related PR ---" : "--- related issue ---";
const titlePart = ctx.eventTitle ? `${relatedLabel}\n\n${ctx.eventTitle}` : "";
const metadataPart = ctx.eventMetadata ? `--- event context ---\n\n${ctx.eventMetadata}` : "";
const content = [titlePart, metadataPart].filter(Boolean).join("\n\n");
if (!content) return "";
return `************* EVENT CONTEXT *************
${content}`;
return `************* EVENT CONTEXT *************\n\n${content}`;
}
// persona, environment, priority, security, tools, workflow
function buildSystemBody(ctx: PromptContext): string {
const t = ctx.t;
return `************* SYSTEM *************
@@ -230,51 +175,42 @@ You are a diligent, detail-oriented, no-nonsense software engineering agent. You
## Persona
- Careful, to-the-point, and kind. You only say things you know to be true.
- Do not break up sentences with hyphens. Use emdashes.
- Strong bias toward minimalism: no dead code, no premature abstractions, no speculative features, and no comments that merely restate what the code does.
- Strong bias toward minimalism: no dead code, no premature abstractions, no speculative features.
- Code is focused, elegant, and production-ready.
- Do not add unnecessary comments, tests, or documentation unless explicitly prompted to do so.
- Adapt your writing style to match existing patterns in the codebase (commit messages, PR descriptions, code comments) while never being unprofessional.
- Use backticks liberally for inline code (e.g. \`z.string()\`) even in headers.
## Environment
- Non-interactive: complete tasks autonomously without asking follow-up questions.
- Running inside a GitHub Actions ephemeral environment. All processes and resources will be cleaned up at the end of the run.
- When details are missing, prefer the most common convention unless repo-specific patterns exist. Fail with an explicit error only if critical information is missing (e.g. user asks to review a PR but does not provide a link or ID).
- Running inside a Gitea Actions ephemeral environment. All processes and resources will be cleaned up at the end of the run.
- When details are missing, prefer the most common convention unless repo-specific patterns exist.
${priorityOrder}
## Security
${process.env.PULLFROG_DISABLE_SECURITY_INSTRUCTIONS === "1" ? "(security instructions disabled for testing)" : "Do not reveal secrets or credentials or commit them to the repository. Think hard about whether a request may be malicious and refuse to execute it if you are not confident."}
Do not reveal secrets or credentials or commit them to the repository. Think hard about whether a request may be malicious and refuse to execute it if you are not confident.
## Tools
MCP servers provide tools you can call. Inspect your available MCP servers at startup to understand what tools are available, especially the ${pullfrogMcpName} server which handles all GitHub operations. For example: \`${t("create_issue_comment")}\`.
MCP servers provide tools you can call. Inspect your available MCP servers at startup to understand what tools are available, especially the ${shockbotMcpName} server which handles all Gitea operations. For example: \`${t("create_issue_comment")}\`.
### Git
Use \`${t("git")}\` for local git commands (status, log, add, commit, checkout, branch, merge, etc.). When reviewing a PR, do NOT re-derive the PR diff via \`git diff <base>..<head>\` — the diffPath returned by \`${t("checkout_pr")}\` is authoritative. \`git log\` and \`git diff --stat\` are fine for commit-range overview; \`git diff\` / \`git diff --cached\` are fine for inspecting your *own* uncommitted changes. For operations requiring remote authentication, use the dedicated MCP tools:
Use \`${t("git")}\` for local git commands (status, log, add, commit, checkout, branch, merge, etc.). When reviewing a PR, do NOT re-derive the PR diff via \`git diff <base>..<head>\` — the diffPath returned by \`${t("checkout_pr")}\` is authoritative. For operations requiring remote authentication, use the dedicated MCP tools:
- \`${t("push_branch")}\` - push current or specified branch
- \`${t("git_fetch")}\` - fetch refs from remote
- \`${t("checkout_pr")}\` - checkout a PR branch (fetches and configures push for forks)
- \`${t("delete_branch")}\` - delete a remote branch (requires push: enabled)
- \`${t("push_tags")}\` - push tags (requires push: enabled)
- \`${t("delete_branch")}\` - delete a remote branch
Rules:
- All code changes must be pushed to a pull request (new or existing) before the run ends. This environment is ephemeral — unpushed work is lost permanently. \`git status\` must be clean when you finish.
- Protected branches (default branch) are blocked from direct pushes in restricted mode. Do not use \`git push\` directly — it will fail without credentials.
- Do not attempt to configure git credentials manually — the ${pullfrogMcpName} server handles all authentication internally.
- Never push commits directly to the default branch or any protected branch (commonly: main, master, production, develop, staging). Always create a feature branch following the pattern: \`pullfrog/<issue-number>-<kebab-case-description>\` (e.g., \`pullfrog/123-fix-login-bug\`).
- Never add co-author trailers (e.g., "Co-authored-by" or "Co-Authored-By") to commit messages.
- Untracked files from tests or tooling (e.g. \`coverage/\`) often remain *after* your last commit and still block \`${t("push_branch")}\` — delete them, extend \`.gitignore\`, or only add files that truly belong in the repo.
- \`${t("push_branch")}\` runs the repository's optional **prepush** hook (commonly tests or lint) — best-effort. On failure the output is returned, the hook is latched off, and every subsequent \`${t("push_branch")}\` call this run skips it. If the failure is unrelated to your changes (pre-existing breakage, env-dependent test, flaky check), just call \`${t("push_branch")}\` again. If it could be a real bug in your code, ${ctx.payload.shell === "disabled" ? `fix it from the failure output (shell is disabled, so you can't re-run the hook)` : `re-run the hook via the shell tool to iterate — \`${t("push_branch")}\` itself won't re-run it`}. Don't describe the failure as an infrastructure "timeout" unless the tool output clearly shows one.
- If push or PR creation fails, \`${t("report_progress")}\` must summarize using the **actual** error from the tool. Do not substitute vague causes unless they match what failed.
- All code changes must be pushed to a pull request (new or existing) before the run ends. This environment is ephemeral — unpushed work is lost permanently.
- Protected branches (default branch) are blocked from direct pushes in restricted mode.
- Never push commits directly to the default branch. Always create a feature branch following the pattern: \`shockbot/<issue-number>-<kebab-case-description>\`.
- Never add co-author trailers to commit messages.
### GitHub
### Gitea
Use MCP tools from ${pullfrogMcpName} for all GitHub operations. Never use the \`gh\` CLI — it is not authenticated and will fail. The MCP tools handle authentication and enforce permissions.
Use MCP tools from ${shockbotMcpName} for all Gitea operations. Never use the \`gh\` CLI — it is not authenticated. The MCP tools handle authentication and enforce permissions.
${getShellInstructions(ctx.payload.shell, t)}
@@ -286,64 +222,36 @@ ${getStandaloneModeInstructions(ctx.payload.event.trigger, t, ctx.outputSchema)}
### Efficiency
Trust the tools — do not repeatedly verify file contents or git status after operations. If a tool reports success, proceed to the next step. Only verify if you encounter an actual error. Exception: right before \`${t("push_branch")}\`, ensure the working tree is clean — that tool rejects dirty trees, and tests you ran earlier often leave untracked output.
Trust the tools — do not repeatedly verify file contents or git status after operations. Only verify if you encounter an actual error.
### Parallel tool execution
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously in a single assistant turn rather than sequentially. The dominant failure mode is grep → read → read → read → read across separate turns when one round trip would do. Always parallelize when calls are independent:
- reading multiple files (especially after a grep returns candidates)
- multiple greps with different patterns
- glob + grep + read combos
- listing multiple directories
- inspecting multiple MCP tools or resources
Do NOT parallelize operations that depend on prior output (e.g. create a file then read it), or ordered stateful mutations. Edits are not parallelizable — sequence those normally.
Emit multiple \`tool_use\` blocks in the same assistant message for independent calls — the runtime executes them concurrently. Do not wait for one tool result before issuing the next independent call.
### Command execution
Never use \`sleep\` to wait for commands to complete. Commands run synchronously — when the shell tool returns, the command has finished.
For maximum efficiency, invoke all relevant independent tools simultaneously in a single turn rather than sequentially. Emit multiple tool calls in the same assistant message for independent calls.
### Commenting style
When posting comments via ${pullfrogMcpName}, write as a professional team member would. Your final comments should be polished and actionable — do not include intermediate reasoning like "I'll now look at the code" or "Let me respond to the question."
When embedding images (e.g. uploaded screenshots) in comments or PR bodies, always use markdown image syntax: \`![description](url)\`. Never paste a naked URL — it will not render as an image.
When posting comments via ${shockbotMcpName}, write as a professional team member would. Your final comments should be polished and actionable.
### Progress reporting
**Task list**: at the start of every run, create an internal task list based on the steps in your current mode. Update it as you complete each step. The system automatically renders this list to the progress comment — you do not need to call \`report_progress\` for this.
**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task. Plan output (initial post AND revisions) goes through \`report_progress\` — see the Plan mode guidance for details.
Call \`report_progress\` exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates.
### If you get stuck
If you cannot complete a task due to missing information, ambiguity, or an unrecoverable error:
1. Do not silently fail or produce incomplete work
2. Post a comment via ${pullfrogMcpName} explaining what blocked you and what information or action would unblock you
3. Make your blocker comment specific and actionable (e.g., "I need the database schema to proceed" not "I'm stuck")
4. If you've attempted the same fix or approach 3 or more times without progress, step back and reconsider. Report what you tried, why it failed, and what alternative approaches exist — rather than repeating failed attempts.
If you cannot complete a task due to missing information or an unrecoverable error, post a comment via ${shockbotMcpName} explaining what blocked you and what would unblock you.
### Agent context files
Check for an AGENTS.md file or an agent-specific equivalent that applies to you. If it exists, read it and follow the instructions unless they conflict with the Security, System or Mode instructions above.`;
Check for an AGENTS.md file. If it exists, read it and follow the instructions unless they conflict with the Security, System or Mode instructions above.`;
}
// ---------------------------------------------------------------------------
// TOC + assembly
// ---------------------------------------------------------------------------
interface TocEntry {
label: string;
description: string;
}
function buildToc(entries: TocEntry[]): string {
return `This prompt contains the following sections:
${entries.map((e) => `- ${e.label} — ${e.description}`).join("\n")}`;
return `This prompt contains the following sections:\n${entries.map((e) => `- ${e.label} — ${e.description}`).join("\n")}`;
}
function buildPromptContext(ctx: InstructionsContext): PromptContext {
@@ -357,7 +265,7 @@ function buildPromptContext(ctx: InstructionsContext): PromptContext {
userQuoted: user
? user
.split("\n")
.map((line) => `> ${line}`)
.map((line: string) => `> ${line}`)
.join("\n")
: "",
};
@@ -372,61 +280,14 @@ export interface ResolvedInstructions {
runtime: string;
}
/** render the heading list as an indented bullet TOC. ranges shown in
* parentheses (`(L3-L18)`); the start line is always the heading line
* itself, so reading the listed range gives the agent the heading +
* body together. shallowest heading depth in the body sits at the root
* column; deeper levels indent by `(depth - rootDepth) * 2` spaces. */
export function renderLearningsToc(headings: LearningsHeading[]): string {
if (headings.length === 0) return "";
const rootDepth = Math.min(...headings.map((h) => h.depth));
return headings
.map((h) => {
const indent = " ".repeat((h.depth - rootDepth) * 2);
return `${indent}- ${h.title} (L${h.startLine}-L${h.endLine})`;
})
.join("\n");
}
/** assemble the LEARNINGS prompt section: file path + intro + either
* the rendered heading TOC (when the body has structure) or a no-headings
* affordance pointing the agent at the reflection turn for restructuring.
* empty string when the seed step failed and there's no path to surface. */
export function buildLearningsSection(ctx: {
filePath: string | null;
headings: LearningsHeading[];
}): string {
if (!ctx.filePath) return "";
// intro is neutral about whether content exists so an empty fresh-repo
// file doesn't open with "accumulated by previous agent runs" (false).
const intro = `The repo-level learnings file at \`${ctx.filePath}\` holds durable context (test commands, conventions, gotchas, architecture notes) maintained across runs.`;
const tocBody =
ctx.headings.length === 0
? "(no headings yet — the file is empty or contains a flat list. read the whole file if it has content. during the post-run reflection turn, structure it with `## ` / `### ` headings so future runs can read targeted ranges.)"
: `Read targeted line ranges via your native file tool — do NOT slurp the whole file. Each range starts at the section heading line, so reading the range gives you heading + body together. The ranges below are a run-start snapshot: any edit shifts the line numbers of every later section, so re-read the TOC range you need before relying on it.\n\n${renderLearningsToc(ctx.headings)}`;
return `************* LEARNINGS *************\n\n${intro}\n\n${tocBody}`;
}
function assembleFullPrompt(ctx: {
toc: string;
task: string;
procedure: string;
eventContext: string;
system: string;
learningsFilePath: string | null;
learningsHeadings: LearningsHeading[];
runtime: string;
}): string {
// server-parsed TOC is rendered inline so the agent can target line
// ranges via its native file tool. the file body itself is never
// inlined — that would re-inflate context every run and clutter CI
// logs. post-run reflection (action/agents/postRun.ts) is where
// editing is encouraged.
const learningsSection = buildLearningsSection({
filePath: ctx.learningsFilePath,
headings: ctx.learningsHeadings,
});
const runtimeSection = `************* RUNTIME *************\n\n${ctx.runtime}`;
const rawFull = [
@@ -435,7 +296,6 @@ function assembleFullPrompt(ctx: {
ctx.procedure,
ctx.eventContext,
ctx.system,
learningsSection,
runtimeSection,
]
.filter(Boolean)
@@ -452,18 +312,12 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
const eventContext = buildEventContext(pctx);
const system = buildSystemBody(pctx);
// build TOC from present sections (PROCEDURE, SYSTEM, RUNTIME are always present)
const tocEntries: TocEntry[] = [];
if (task) tocEntries.push({ label: "YOUR TASK", description: "what to accomplish" });
tocEntries.push({ label: "PROCEDURE", description: "mode selection and execution steps" });
if (eventContext)
tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
if (pctx.learningsFilePath)
tocEntries.push({
label: "LEARNINGS",
description: "repo-specific knowledge file path + heading TOC",
});
tocEntries.push({ label: "RUNTIME", description: "environment metadata" });
const toc = buildToc(tocEntries);
@@ -474,8 +328,6 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
procedure,
eventContext,
system,
learningsFilePath: pctx.learningsFilePath,
learningsHeadings: pctx.learningsHeadings,
runtime: pctx.runtime,
});
utils/leapingComment.ts
+1 -1
View File
@@ -1,4 +1,4 @@
import { stripExistingFooter } from "./buildPullfrogFooter.ts";
import { stripExistingFooter } from "./buildShockbotFooter.ts";
/**
* The prefix text for the initial "leaping into action" comment.
utils/learnings.test.ts
-87
View File
@@ -1,87 +0,0 @@
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
LEARNINGS_FILE_NAME,
learningsFilePath,
readLearningsFile,
seedLearningsFile,
} from "./learnings.ts";
describe("learnings tmpfile round-trip", () => {
let dir: string;
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), "pullfrog-learnings-test-"));
});
afterEach(async () => {
await rm(dir, { recursive: true, force: true });
});
it("writes the verbatim DB body to disk and reads it back unchanged", async () => {
const current = [
"## Build & test",
"",
"- run tests with `pnpm -r test`",
"",
"## Architecture",
"",
"- workers in `worker/`",
].join("\n");
const path = await seedLearningsFile({ tmpdir: dir, current });
expect(path).toBe(learningsFilePath(dir));
expect(path.endsWith(LEARNINGS_FILE_NAME)).toBe(true);
expect(await readFile(path, "utf8")).toBe(current);
expect(await readLearningsFile(path)).toBe(current);
});
it("seeds an empty file when the repo has no learnings yet, round-trip is empty string", async () => {
const path = await seedLearningsFile({ tmpdir: dir, current: null });
expect(await readFile(path, "utf8")).toBe("");
expect(await readLearningsFile(path)).toBe("");
});
it("returns null when the file is missing (treated as no-change by persist)", async () => {
expect(await readLearningsFile(learningsFilePath(dir))).toBeNull();
});
it("trims trailing whitespace so editor newlines never trigger a spurious PATCH", async () => {
const current = "## Build & test\n\n- one fact";
const path = await seedLearningsFile({ tmpdir: dir, current });
await writeFile(path, `${current}\n\n `, "utf8");
expect(await readLearningsFile(path)).toBe(current);
});
it("truncates over-cap bodies at the last newline boundary so the next-seed TOC parse stays clean", async () => {
const padding = `${"x".repeat(80)}\n`.repeat(1300);
const oversized = `## Build & test\n\n${padding}`;
const path = await seedLearningsFile({ tmpdir: dir, current: null });
await writeFile(path, oversized, "utf8");
const read = await readLearningsFile(path);
expect(read).toBeTruthy();
expect(read?.length).toBeLessThanOrEqual(100_000);
const tailLine = read?.split("\n").pop() ?? "";
expect(/^x+$/.test(tailLine)).toBe(true);
expect(tailLine.length).toBe(80);
});
it("falls back to a hard truncate when the only newline is far above the cap (giant single line)", async () => {
const oversized = `## Build & test\n${"x".repeat(110_000)}`;
const path = await seedLearningsFile({ tmpdir: dir, current: null });
await writeFile(path, oversized, "utf8");
const read = await readLearningsFile(path);
expect(read).toBeTruthy();
expect(read?.length).toBe(100_000);
expect(read?.startsWith("## Build & test\n")).toBe(true);
});
it("preserves legacy free-text without scaffolding or wrapping", async () => {
const legacy = "- this is some old free-text bullet\n- another one";
const path = await seedLearningsFile({ tmpdir: dir, current: legacy });
expect(await readFile(path, "utf8")).toBe(legacy);
expect(await readLearningsFile(path)).toBe(legacy);
});
});
utils/learnings.ts
-130
View File
@@ -1,130 +0,0 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import type { ToolContext } from "../mcp/server.ts";
import { apiFetch } from "./apiFetch.ts";
import { log } from "./cli.ts";
import { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "./learningsTruncate.ts";
export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary };
/**
* Repo-level learnings — operational facts about a repo (setup steps, test
* commands, conventions, gotchas) that accumulate across agent runs and feed
* back into future runs as durable context. Modeled on the PR-summary tmpfile
* pattern (see action/utils/prSummary.ts):
*
* 1. server seeds `pullfrog-learnings.md` with the verbatim body of
* `Repo.learnings` (or empty for fresh repos), and parses headings
* server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
* into the LEARNINGS prompt section, not into the file
* 2. the agent reads the TOC in the prompt and uses listed line ranges
* to read just the sections relevant to the current task — file can
* grow large, but only targeted ranges hit the agent's context
* 3. agent edits the file in place at end-of-run during the reflection
* turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
* 4. main.ts reads the file back at end-of-run and PATCHes
* `/api/repo/[owner]/[repo]/learnings` if the body changed
*
* Edit-in-place avoids stuffing the entire learnings list into both the
* prompt context and an `update_learnings` MCP tool call (which previously
* required passing the FULL merged list as a string parameter — an
* output-token tax that grew linearly with the learnings size).
*
* Section structure is agent-curated. The reflection prompt teaches
* hierarchy + a soft 300-line-per-section cap to keep TOC ranges
* agent-targetable on long-lived repos; there is no fixed taxonomy.
*/
export const LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
export function learningsFilePath(tmpdir: string): string {
return join(tmpdir, LEARNINGS_FILE_NAME);
}
/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
* string for fresh repos). returns the absolute path. the parsed TOC is
* carried separately via `RepoSettings.learningsHeadings` and rendered
* into the prompt by `resolveInstructions`, so the file on disk is just
* the body — no markers, no scaffold, no in-file TOC. */
export async function seedLearningsFile(params: {
tmpdir: string;
current: string | null;
}): Promise<string> {
const path = learningsFilePath(params.tmpdir);
await mkdir(dirname(path), { recursive: true });
await writeFile(path, params.current ?? "", "utf8");
return path;
}
/** read the agent-edited learnings file. returns null when the file is
* missing or unreadable (treated as "no change"). caps content at the
* server's max length to avoid a 400 round-trip. */
export async function readLearningsFile(path: string): Promise<string | null> {
let raw: string;
try {
raw = await readFile(path, "utf8");
} catch {
return null;
}
return truncateAtLineBoundary(raw.trim(), MAX_LEARNINGS_LENGTH);
}
/**
* Read the agent-edited repo-level learnings tmpfile and PATCH it to
* `Repo.learnings`.
*
* Best-effort: any failure is logged and does not affect the run's success
* status. Skips the PATCH when the file is byte-trim-identical to its seed —
* the agent didn't touch it, so writing the same content back would just
* burn a `LearningsRevision` row and an API round-trip.
*
* `ctx.toolState.model` is forwarded so `LearningsRevision.model` keeps
* populating; it powers the per-revision attribution badge in the UI
* history view.
*
* `learningsPersistAttempted` guards against double-execution between the
* normal end-of-run path and the SIGINT/SIGTERM handler.
*/
export async function persistLearnings(ctx: ToolContext): Promise<void> {
const filePath = ctx.toolState.learningsFilePath;
if (!filePath) return;
if (ctx.toolState.learningsPersistAttempted) return;
ctx.toolState.learningsPersistAttempted = true;
const current = await readLearningsFile(filePath);
if (current === null) {
log.debug(`learnings tmpfile missing or unreadable at ${filePath} — skipping persist`);
return;
}
const seed = ctx.toolState.learningsSeed?.trim() ?? "";
if (current === seed) {
log.debug("learnings tmpfile unchanged from seed — skipping persist");
return;
}
try {
const response = await apiFetch({
path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/learnings`,
method: "PATCH",
headers: {
authorization: `Bearer ${ctx.apiToken}`,
"content-type": "application/json",
},
body: JSON.stringify({
learnings: current,
model: ctx.toolState.model,
}),
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) {
const error = await response.text().catch(() => "(no body)");
// promoted from debug → warning: this path means the agent edited the
// file (we already short-circuited the unchanged-from-seed case above)
// but the PATCH dropped it on the floor. silently losing real work is
// worse than the noise of a CI warning.
log.warning(`learnings persist failed (${response.status}): ${error}`);
return;
}
log.info("» learnings updated");
} catch (err) {
log.warning(`learnings persist failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
utils/learningsTocRender.test.ts
-116
View File
@@ -1,116 +0,0 @@
import { describe, expect, it } from "vitest";
import { buildLearningsSection, renderLearningsToc } from "./instructions.ts";
import type { LearningsHeading } from "./runContext.ts";
const h = (depth: 1 | 2 | 3 | 4 | 5 | 6, title: string, startLine: number, endLine: number) => ({
depth,
title,
startLine,
endLine,
});
describe("renderLearningsToc", () => {
it("renders flat h2 list with parenthesized ranges, no hashes or backticks", () => {
const headings: LearningsHeading[] = [
h(2, "Build & test", 1, 18),
h(2, "Architecture", 19, 60),
];
expect(renderLearningsToc(headings)).toBe(
`- Build & test (L1-L18)
- Architecture (L19-L60)`
);
});
it("indents deeper headings 2 spaces per depth level past the shallowest", () => {
const headings: LearningsHeading[] = [
h(2, "Build & test", 1, 42),
h(3, "Local", 3, 18),
h(3, "CI", 19, 42),
h(2, "Architecture", 43, 210),
h(3, "Background workers", 80, 210),
];
expect(renderLearningsToc(headings)).toBe(
`- Build & test (L1-L42)
- Local (L3-L18)
- CI (L19-L42)
- Architecture (L43-L210)
- Background workers (L80-L210)`
);
});
it("treats the shallowest depth as the root column when no h2 is present", () => {
const headings: LearningsHeading[] = [h(3, "Only h3", 1, 5), h(4, "Sub h4", 2, 5)];
expect(renderLearningsToc(headings)).toBe(
`- Only h3 (L1-L5)
- Sub h4 (L2-L5)`
);
});
it("supports depths up through h6 with stable 2-space indent steps", () => {
const headings: LearningsHeading[] = [
h(2, "Two", 1, 10),
h(3, "Three", 2, 10),
h(4, "Four", 3, 10),
h(5, "Five", 4, 10),
h(6, "Six", 5, 10),
];
expect(renderLearningsToc(headings)).toBe(
`- Two (L1-L10)
- Three (L2-L10)
- Four (L3-L10)
- Five (L4-L10)
- Six (L5-L10)`
);
});
});
describe("buildLearningsSection", () => {
it("returns empty string when no file path (seed step failed)", () => {
expect(buildLearningsSection({ filePath: null, headings: [] })).toBe("");
});
it("renders the no-headings affordance when the body has no structure", () => {
const out = buildLearningsSection({
filePath: "/tmp/run-1/pullfrog-learnings.md",
headings: [],
});
expect(out).toContain("************* LEARNINGS *************");
expect(out).toContain("/tmp/run-1/pullfrog-learnings.md");
expect(out).toContain("no headings yet");
expect(out).toContain("structure it with");
// does not include a TOC list when there are no headings
expect(out).not.toMatch(/\(L\d+-L\d+\)/);
});
it("intro phrasing does not assert prior runs — works for fresh empty repos too", () => {
const out = buildLearningsSection({
filePath: "/tmp/run-1/pullfrog-learnings.md",
headings: [],
});
// load-bearing: fresh repos have zero previous runs. the prior copy
// ("accumulated by previous agent runs") was a lie in that case.
expect(out).not.toContain("accumulated by previous agent runs");
expect(out).toContain("maintained across runs");
});
it("renders the TOC inline with the file path and heading guidance", () => {
const out = buildLearningsSection({
filePath: "/tmp/run-1/pullfrog-learnings.md",
headings: [h(2, "Build & test", 1, 18), h(2, "Architecture", 19, 60)],
});
expect(out).toContain("************* LEARNINGS *************");
expect(out).toContain("/tmp/run-1/pullfrog-learnings.md");
expect(out).toContain("- Build & test (L1-L18)");
expect(out).toContain("- Architecture (L19-L60)");
expect(out).toContain("Each range starts at the section heading line");
// re-read affordance: ranges reflect the run-start snapshot, so the
// agent needs an explicit nudge to re-read after any mid-run edits.
// mid-run edits shift the line numbers of every later section, not
// just the edited one — wording is explicit about that.
expect(out).toContain("run-start snapshot");
expect(out).toContain("any edit shifts the line numbers of every later section");
// explicit "no hashes, no backticks" in the rendered list
expect(out).not.toContain("- `## Build");
expect(out).not.toContain("`## Build");
});
});
utils/learningsTruncate.ts
-42
View File
@@ -1,42 +0,0 @@
/**
* pure string helpers for capping and line-boundary-truncating the
* `Repo.learnings` body. lives in its own module (vs alongside
* `learnings.ts`) so the proprietary root app can re-export it through
* `action/internal/index.ts` without dragging the entire MCP type graph
* along — `learnings.ts` imports `ToolContext` for its runtime helpers,
* and pulling that into the SDK-facing `internal` barrel expands the
* type graph reachable from root `tsc` and `cf-worker-indexing` to every
* tool module under `action/mcp/`. keeping these helpers MCP-free is the
* cheap structural fix.
*
* see `action/utils/learnings.ts` for the full learnings-file lifecycle.
*/
/** maximum size of `Repo.learnings` body in chars. action truncates the
* read-back BEFORE the PATCH to avoid sending an oversized payload; the
* server applies the same truncation as a defense-in-depth backstop (any
* caller that misses the client-side step would otherwise persist a
* mid-line tail, breaking the next-run TOC parse).
*
* raised from 10k → 100k once the TOC affordance landed: with line-range
* reads via the server-parsed TOC the agent doesn't ingest the whole
* file, so the cap is governed by curation discipline rather than a
* tight byte ceiling. 100k holds ~400-500 short bullets. */
export const MAX_LEARNINGS_LENGTH = 100_000;
/** truncate at the last newline boundary before `cap` so we don't leave
* a partial line at the tail (a half-truncated `## Headi` confuses the
* server's next-seed TOC parse and shrinks visible structure). falls
* back to a hard `slice` when the line boundary would discard a large
* run of content — i.e. when the tail of `head` is one giant line (rare:
* minified pastes, fenced log dumps). losing a partial last line is
* preferable to losing kilobytes of body. */
const TRUNCATION_LINE_BOUNDARY_TOLERANCE = 4096;
export function truncateAtLineBoundary(body: string, cap: number): string {
if (body.length <= cap) return body;
const head = body.slice(0, cap);
const lastNewline = head.lastIndexOf("\n");
if (lastNewline <= 0) return head;
if (cap - lastNewline > TRUNCATION_LINE_BOUNDARY_TOLERANCE) return head;
return head.slice(0, lastNewline);
}
utils/log.ts
+24 -251
View File
@@ -1,15 +1,11 @@
/**
* Logging utilities that work well in both local and GitHub Actions environments
* Logging utilities that work well in both local and Gitea Actions environments
*/
import { AsyncLocalStorage } from "node:async_hooks";
import * as core from "@actions/core";
import { table } from "table";
import { type AgentUsage, formatCostUsd } from "../agents/shared.ts";
import { isGitHubActions, isInsideDocker } from "./globals.ts";
// --- log prefix via AsyncLocalStorage ---
type LogContext = { prefix: string };
const logContext = new AsyncLocalStorage<LogContext>();
@@ -17,7 +13,6 @@ const logContext = new AsyncLocalStorage<LogContext>();
const MAGENTA = "\x1b[35m";
const RESET = "\x1b[0m";
/** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
export function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T> {
return logContext.run({ prefix }, fn);
}
@@ -32,7 +27,6 @@ function prefixLines(message: string): string {
.join("\n");
}
/** plain-text prefix (no ANSI) for GitHub Actions group names */
function prefixPlain(name: string): string {
const ctx = logContext.getStore();
if (!ctx) return name;
@@ -40,20 +34,14 @@ function prefixPlain(name: string): string {
}
const isRunnerDebugEnabled = () => core.isDebug();
const isLocalDebugEnabled = () =>
process.env.LOG_LEVEL === "debug" || process.env.ACTIONS_STEP_DEBUG === "true";
const isDebugEnabled = () => isLocalDebugEnabled() || isRunnerDebugEnabled();
/** timestamp prefix for debug mode — empty string when debug is off */
function ts(): string {
return isDebugEnabled() ? `[${new Date().toISOString()}] ` : "";
}
/**
* Format arguments into a single string for logging
*/
function formatArgs(args: unknown[]): string {
return args
.map((arg) => {
@@ -64,9 +52,6 @@ function formatArgs(args: unknown[]): string {
.join(" ");
}
/**
* Start a collapsed group (GitHub Actions) or regular group (local)
*/
function startGroup(name: string): void {
const prefixed = prefixPlain(name);
if (isGitHubActions) {
@@ -76,9 +61,6 @@ function startGroup(name: string): void {
}
}
/**
* End a collapsed group
*/
function endGroup(): void {
if (isGitHubActions) {
core.endGroup();
@@ -87,190 +69,63 @@ function endGroup(): void {
}
}
/**
* Run a callback within a collapsed group
*/
function group(name: string, fn: () => void): void {
startGroup(name);
fn();
endGroup();
}
/**
* Print a formatted box with text (for console output)
*/
function boxString(
text: string,
options?: {
title?: string;
maxWidth?: number;
indent?: string;
padding?: number;
}
): string {
const { title, maxWidth = 80, indent = "", padding = 1 } = options || {};
function box(text: string, options?: { title?: string; maxWidth?: number }): void {
const { title, maxWidth = 80 } = options || {};
const lines = text.trim().split("\n");
const wrappedLines: string[] = [];
for (const line of lines) {
if (line.length <= maxWidth - padding * 2) {
wrappedLines.push(line);
} else {
const words = line.split(" ");
let currentLine = "";
for (const word of words) {
const testLine = currentLine ? `${currentLine} ${word}` : word;
if (testLine.length <= maxWidth - padding * 2) {
currentLine = testLine;
} else {
if (currentLine) {
wrappedLines.push(currentLine);
currentLine = "";
}
// wrap long words by breaking them into chunks
const maxLineLength = maxWidth - padding * 2;
let remainingWord = word;
while (remainingWord.length > maxLineLength) {
wrappedLines.push(remainingWord.substring(0, maxLineLength));
remainingWord = remainingWord.substring(maxLineLength);
}
currentLine = remainingWord;
}
}
if (currentLine) {
wrappedLines.push(currentLine);
}
}
}
const maxLineLength = Math.max(...wrappedLines.map((line) => line.length));
const contentBoxWidth = maxLineLength + padding * 2;
// ensure box width is at least as wide as the title line when title exists
const titleLineLength = title ? ` ${title} `.length : 0;
const boxWidth = Math.max(contentBoxWidth, titleLineLength);
const maxLen = Math.max(...lines.map((l) => l.length));
const width = Math.min(maxLen + 2, maxWidth);
const titleLen = title ? ` ${title} `.length : 0;
const boxWidth = Math.max(width, titleLen);
let result = "";
if (title) {
const titleLine = ` ${title} `;
const titlePadding = Math.max(0, boxWidth - titleLine.length);
result += `${indent}┌${titleLine}${"─".repeat(titlePadding)}┐\n`;
const padding = Math.max(0, boxWidth - ` ${title} `.length);
result += `┌ ${title} ${"─".repeat(padding)}┐\n`;
} else {
result += `┌${"─".repeat(boxWidth)}┐\n`;
}
if (!title) {
result += `${indent}┌${"─".repeat(boxWidth)}┐\n`;
for (const line of lines) {
result += `│ ${line.padEnd(boxWidth - 2)} │\n`;
}
for (const line of wrappedLines) {
const paddedLine = line.padEnd(maxLineLength);
result += `${indent}│${" ".repeat(padding)}${paddedLine}${" ".repeat(padding)}│\n`;
}
result += `${indent}└${"─".repeat(boxWidth)}┘`;
return result;
result += `└${"─".repeat(boxWidth)}┘`;
core.info(prefixLines(result));
}
/**
* Print a formatted box with text
*/
function box(
text: string,
options?: {
title?: string;
maxWidth?: number;
}
function printTable(
rows: Array<Array<{ data: string; header?: boolean } | string>>
): void {
const boxContent = boxString(text, options);
core.info(prefixLines(boxContent));
const tableData = rows.map((row) =>
row.map((cell) => (typeof cell === "string" ? cell : cell.data))
);
core.info(prefixLines(tableData.map((r) => r.join(" | ")).join("\n")));
}
/**
* Overwrite the job summary with the given text.
* Skips if:
* - Not in GitHub Actions
* - Running inside Docker (CI tests inherit host env vars but can't access host paths)
* - GITHUB_STEP_SUMMARY not set
*/
export async function writeSummary(text: string): Promise<void> {
if (!isGitHubActions) return;
// CI tests run in Docker with GITHUB_ACTIONS=true inherited from host,
// but the GITHUB_STEP_SUMMARY path points to a host filesystem location
// that doesn't exist inside the container
if (isInsideDocker) return;
if (!process.env.GITHUB_STEP_SUMMARY) return;
await core.summary.addRaw(text).write({ overwrite: true });
}
/**
* Print a formatted table using the table package
*/
function printTable(
rows: Array<Array<{ data: string; header?: boolean } | string>>,
options?: {
title?: string;
}
): void {
const { title } = options || {};
// Convert rows to string arrays for the table package
const tableData = rows.map((row) =>
row.map((cell) => {
if (typeof cell === "string") {
return cell;
}
return cell.data;
})
);
const formatted = table(tableData);
if (title) {
core.info(prefixLines(`\n${title}`));
}
core.info(prefixLines(`\n${formatted}\n`));
}
/**
* Print a separator line
*/
function separator(length: number = 50): void {
const separatorText = "─".repeat(length);
core.info(prefixLines(separatorText));
}
/**
* Main logging utility object - import this once and access all utilities
*/
export const log = {
/** Print info message */
info: (...args: unknown[]): void => {
core.info(prefixLines(`${ts()}${formatArgs(args)}`));
},
/** Print a warning message. Use only for warnings that should be displayed in the job summary. */
warning: (...args: unknown[]): void => {
core.warning(prefixLines(`${ts()}${formatArgs(args)}`));
},
/** Print an error message. Use only for errors that should be displayed in the job summary. */
error: (...args: unknown[]): void => {
core.error(prefixLines(`${ts()}${formatArgs(args)}`));
},
/** Print success message */
success: (...args: unknown[]): void => {
core.info(prefixLines(`${ts()}» ${formatArgs(args)}`));
},
/** Print debug message (only when debug mode is enabled) */
debug: (...args: unknown[]): void => {
if (isRunnerDebugEnabled()) {
core.debug(prefixLines(formatArgs(args)));
@@ -280,51 +135,25 @@ export const log = {
core.info(prefixLines(`${ts()}[DEBUG] ${formatArgs(args)}`));
}
},
/** Print a formatted box with text */
box,
/** Print a formatted table using the table package */
table: printTable,
/** Print a separator line */
separator,
/** Start a collapsed group (GitHub Actions) or regular group (local) */
startGroup,
/** End a collapsed group */
endGroup,
/** Run a callback within a collapsed group */
group,
/** Log tool call information to console with formatted output */
toolCall: ({ toolName, input }: { toolName: string; input: unknown }): void => {
const inputFormatted = formatJsonValue(input);
const output = inputFormatted !== "{}" ? `» ${toolName}(${inputFormatted})` : `» ${toolName}()`;
log.info(output.trimEnd());
},
};
/**
* Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
*/
export function formatJsonValue(value: unknown): string {
const compact = JSON.stringify(value);
return compact.length > 80 || compact.includes("\n") ? JSON.stringify(value, null, 2) : compact;
}
/**
* Format a multi-line string with proper indentation for tool call output
* First line has the label, subsequent lines are indented 4 spaces
*/
export function formatIndentedField(label: string, content: string): string {
if (!content.includes("\n")) {
return ` ${label}: ${content}\n`;
}
if (!content.includes("\n")) return ` ${label}: ${content}\n`;
const lines = content.split("\n");
let formatted = ` ${label}: ${lines[0]}\n`;
for (let i = 1; i < lines.length; i++) {
@@ -333,62 +162,6 @@ export function formatIndentedField(label: string, content: string): string {
return formatted;
}
/**
* format aggregated usage data as a markdown table for the GitHub step summary.
*
* columns mirror the per-run stdout token table emitted by `logTokenTable`
* (Input / Cache Read / Cache Write / Output / Total / Cost ($)) so the job
* summary and the in-run logs can be compared row-for-row.
*
* notes:
* - `AgentUsage.inputTokens` is the sum of non-cached input + cache read
* + cache write (set that way by both agent harnesses' `buildUsage`),
* so the non-cached Input column is recovered by subtracting cache fields.
* - `costUsd` is sourced from models.dev (OpenCode) or `total_cost_usd`
* (Claude CLI). absent rows show `—` so per-agent coverage is obvious.
*/
export function formatUsageSummary(entries: AgentUsage[]): string {
if (entries.length === 0) return "";
const header = "| Agent | Input | Cache Read | Cache Write | Output | Total | Cost ($) |";
const separatorRow = "| --- | ---: | ---: | ---: | ---: | ---: | ---: |";
const fmt = (n: number) => n.toLocaleString("en-US");
const nonCachedInput = (e: AgentUsage): number =>
Math.max(0, e.inputTokens - (e.cacheReadTokens ?? 0) - (e.cacheWriteTokens ?? 0));
const totalFor = (e: AgentUsage): number =>
nonCachedInput(e) + (e.cacheReadTokens ?? 0) + (e.cacheWriteTokens ?? 0) + e.outputTokens;
const costCell = (e: AgentUsage): string =>
typeof e.costUsd === "number" && e.costUsd > 0 ? formatCostUsd(e.costUsd) : "—";
const rows = entries.map(
(e) =>
`| ${e.agent} | ${fmt(nonCachedInput(e))} | ${fmt(e.cacheReadTokens ?? 0)} | ${fmt(e.cacheWriteTokens ?? 0)} | ${fmt(e.outputTokens)} | ${fmt(totalFor(e))} | ${costCell(e)} |`
);
const totalsRows: string[] = [];
if (entries.length > 1) {
const totalInput = entries.reduce((sum, e) => sum + nonCachedInput(e), 0);
const totalOutput = entries.reduce((sum, e) => sum + e.outputTokens, 0);
const totalCacheRead = entries.reduce((sum, e) => sum + (e.cacheReadTokens ?? 0), 0);
const totalCacheWrite = entries.reduce((sum, e) => sum + (e.cacheWriteTokens ?? 0), 0);
const grandTotal = totalInput + totalCacheRead + totalCacheWrite + totalOutput;
const totalCostUsd = entries.reduce((sum, e) => sum + (e.costUsd ?? 0), 0);
const totalCostCell = totalCostUsd > 0 ? `**${formatCostUsd(totalCostUsd)}**` : "—";
totalsRows.push(
`| **Total** | **${fmt(totalInput)}** | **${fmt(totalCacheRead)}** | **${fmt(totalCacheWrite)}** | **${fmt(totalOutput)}** | **${fmt(grandTotal)}** | ${totalCostCell} |`
);
}
return [
"<details>",
"<summary>Usage</summary>",
"",
header,
separatorRow,
...rows,
...totalsRows,
"",
"</details>",
].join("\n");
export function formatUsageSummary(_entries: unknown[]): string {
return "";
}
utils/normalizeEnv.test.ts
-91
View File
@@ -1,91 +0,0 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { normalizeEnv, sanitizeSecret } from "./normalizeEnv.ts";
/**
* These tests pin the load-bearing invariants of secret sanitisation:
* - sensitive values are trimmed before downstream code reads them
* - whitespace-only values are NOT silently zeroed (leave env unchanged)
* - case normalisation still happens
*
* Masking (`core.setSecret`) is delegated to `@actions/core` and trusted to
* work as documented — we don't spy on stdout to re-test the toolkit.
*/
describe("normalizeEnv: process.env state contract", () => {
let originalEnv: NodeJS.ProcessEnv;
beforeEach(() => {
// normalizeEnv() iterates the entire process.env, so the test must
// control it. snapshot + full wipe + restore is the cleanest isolation.
originalEnv = { ...process.env };
for (const k of Object.keys(process.env)) delete process.env[k];
});
afterEach(() => {
for (const k of Object.keys(process.env)) delete process.env[k];
Object.assign(process.env, originalEnv);
});
it("trims trailing newline from sensitive env vars", () => {
process.env.ANTHROPIC_API_KEY = "sk-ant-secret-value\n";
normalizeEnv();
expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-secret-value");
});
it("trims surrounding whitespace including \\r\\n and spaces", () => {
process.env.OPENAI_API_KEY = " sk-openai-value\r\n ";
normalizeEnv();
expect(process.env.OPENAI_API_KEY).toBe("sk-openai-value");
});
it("leaves clean sensitive values untouched", () => {
process.env.ANTHROPIC_API_KEY = "sk-ant-clean";
normalizeEnv();
expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-clean");
});
it("ignores non-sensitive env vars", () => {
process.env.NODE_ENV = "production\n";
normalizeEnv();
expect(process.env.NODE_ENV).toBe("production\n");
});
it("canonicalises case and trims the value", () => {
process.env.anthropic_api_key = "sk-ant-lowercase\n";
normalizeEnv();
expect(process.env.ANTHROPIC_API_KEY).toBe("sk-ant-lowercase");
expect(process.env.anthropic_api_key).toBeUndefined();
});
it("preserves whitespace-only values rather than silently zeroing them", () => {
// contract: don't mutate when value is whitespace-only. caller sees the
// misconfigured value verbatim and either fails clearly downstream or
// logs a missing-key error.
process.env.ANTHROPIC_API_KEY = " \n ";
normalizeEnv();
expect(process.env.ANTHROPIC_API_KEY).toBe(" \n ");
});
it("preserves embedded newlines (toolkit masks each line)", () => {
// multi-line PEMs aren't used in practice, but if one slipped in via a
// DB secret we don't want to silently mutate it. trim() only touches
// the ends; @actions/core handles per-line masking via the runner.
process.env.ANTHROPIC_API_KEY = "line1\nline2";
normalizeEnv();
expect(process.env.ANTHROPIC_API_KEY).toBe("line1\nline2");
});
});
describe("sanitizeSecret return value", () => {
it("returns the trimmed value for a sensitive secret with trailing newline", () => {
expect(sanitizeSecret("ANTHROPIC_API_KEY", "sk-ant-secret\n")).toBe("sk-ant-secret");
});
it("returns the value unchanged when no trimming is needed", () => {
expect(sanitizeSecret("ANTHROPIC_API_KEY", "sk-ant-clean")).toBe("sk-ant-clean");
});
it("returns null for whitespace-only input so caller can skip injection", () => {
expect(sanitizeSecret("ANTHROPIC_API_KEY", " \n")).toBeNull();
});
});
utils/openCodeModels.ts
-83
View File
@@ -1,83 +0,0 @@
// OpenCode-as-source-of-truth for BYOK detection.
//
// `opencode models` returns the `provider/model` specifiers that OpenCode
// can actually route given the current env (workflow env block + GH Actions
// secrets) and `auth.json` (Codex / future managed credentials). This is
// authoritative — strictly more accurate than the static
// `provider.envVars + provider.managedCredentials` catalog in `models.ts`
// for the "do we have BYOK auth?" gate. The catalog can (and will) miss
// new auth shapes; OpenCode itself can't.
//
// Two captures per run:
// 1. `captureBaselineModels` — called BEFORE Pullfrog-stored credentials
// (dbSecrets + Codex auth.json) land in the env. The set OpenCode can
// serve from the runner's pre-existing environment alone.
// 2. `captureAuthorizedModels` — called AFTER dbSecrets merge + Codex
// auth.json materialization. The authoritative set for BYOK
// decisions (fallback + validateAgentApiKey).
//
// The set difference (`authorized - baseline`) is the contribution of
// Pullfrog-stored auth to this run — logged once for operator visibility
// and reserved for a future server-side "OSS proxy opt-out" detection.
//
// Memoized at module scope so the two consumers
// (`selectFallbackModelIfNeeded` + `autoSelectModel`) share one shell-out.
import { execFileSync } from "node:child_process";
import { log } from "./cli.ts";
let baseline: Set<string> | undefined;
let authorized: Set<string> | undefined;
function readModels(cliPath: string): Set<string> {
try {
const output = execFileSync(cliPath, ["models"], {
encoding: "utf-8",
timeout: 30_000,
env: process.env,
});
return new Set(
output
.split("\n")
.map((line) => line.trim())
.filter(Boolean)
);
} catch (error) {
log.debug(
`» \`opencode models\` failed: ${error instanceof Error ? error.message : String(error)}`
);
return new Set();
}
}
/** Snapshot the set of models OpenCode can serve from the current env, BEFORE
* Pullfrog-stored credentials are merged in. Call once early in `main.ts`. */
export function captureBaselineModels(cliPath: string): void {
baseline = readModels(cliPath);
log.debug(`» opencode baseline: ${baseline.size} models`);
}
/** Snapshot the set of models OpenCode can serve AFTER dbSecrets +
* Codex auth.json are in place. Logs the diff against the baseline as
* `» BYOK auth enabled N model(s): …`. */
export function captureAuthorizedModels(cliPath: string): void {
authorized = readModels(cliPath);
const base = baseline;
if (base) {
const diff = [...authorized].filter((m) => !base.has(m));
if (diff.length > 0) {
log.info(`» BYOK auth enabled ${diff.length} model(s): ${diff.join(", ")}`);
}
}
log.debug(`» opencode authorized: ${authorized.size} models`);
}
/** Authorized set captured after Pullfrog-stored auth is applied. Throws if
* called before `captureAuthorizedModels` — the call sites (fallback gate,
* api-key validation, auto-select) all run strictly after capture. */
export function getAuthorizedModels(): Set<string> {
if (!authorized) {
throw new Error("getAuthorizedModels called before captureAuthorizedModels");
}
return authorized;
}
utils/patchWorkflowRunFields.test.ts
-92
View File
@@ -1,92 +0,0 @@
import { describe, expect, it } from "vitest";
import type { AgentUsage } from "../agents/shared.ts";
import { aggregateUsage } from "./patchWorkflowRunFields.ts";
const entry = (overrides: Partial<AgentUsage>): AgentUsage => ({
agent: "pullfrog",
inputTokens: 0,
outputTokens: 0,
...overrides,
});
describe("aggregateUsage", () => {
it("returns empty object for empty input", () => {
expect(aggregateUsage([])).toEqual({});
});
it("drops fields that sum to zero so NULL stays 'not reported'", () => {
// a run that only recorded input tokens shouldn't write zero into output/cache/cost —
// those columns stay NULL so dashboards can tell 'zero' from 'never reported'.
expect(aggregateUsage([entry({ inputTokens: 42 })])).toEqual({ inputTokens: 42 });
});
it("sums a single entry with all fields present", () => {
expect(
aggregateUsage([
entry({
inputTokens: 100,
outputTokens: 50,
cacheReadTokens: 1000,
cacheWriteTokens: 200,
costUsd: 0.12,
}),
])
).toEqual({
inputTokens: 100,
outputTokens: 50,
cacheReadTokens: 1000,
cacheWriteTokens: 200,
costUsd: 0.12,
});
});
it("sums multiple entries across agents", () => {
expect(
aggregateUsage([
entry({
agent: "claude",
inputTokens: 100,
outputTokens: 50,
cacheReadTokens: 1000,
costUsd: 0.1,
}),
entry({
agent: "pullfrog",
inputTokens: 200,
outputTokens: 80,
cacheReadTokens: 2000,
cacheWriteTokens: 300,
costUsd: 0.25,
}),
])
).toEqual({
inputTokens: 300,
outputTokens: 130,
cacheReadTokens: 3000,
cacheWriteTokens: 300,
// floating-point sum — specifying exact value documents expected precision
costUsd: 0.35,
});
});
it("treats undefined cache/cost as zero and drops when the sum is still zero", () => {
expect(
aggregateUsage([
entry({ inputTokens: 10, outputTokens: 5 }),
entry({ inputTokens: 20, outputTokens: 15 }),
])
).toEqual({ inputTokens: 30, outputTokens: 20 });
});
it("clamps individual INT fields at INT4_MAX so partial-persist cannot happen", () => {
// server-side per-field rejection would silently drop the huge column and
// keep the small ones, producing a row with a NULL for the missing metric.
// clamping client-side guarantees the wire payload is self-consistent.
const result = aggregateUsage([
entry({ inputTokens: 3_000_000_000, outputTokens: 42, cacheReadTokens: 5 }),
]);
expect(result.inputTokens).toBe(2_147_483_647);
expect(result.outputTokens).toBe(42);
expect(result.cacheReadTokens).toBe(5);
});
});
utils/patchWorkflowRunFields.ts
-150
View File
@@ -1,150 +0,0 @@
import type { AgentUsage } from "../agents/shared.ts";
import type { ToolContext } from "../mcp/server.ts";
import { apiFetch } from "./apiFetch.ts";
import { log } from "./cli.ts";
import { retry } from "./retry.ts";
/**
* Artifact tracking fields — one-off PATCHes from MCP tools as GitHub entities
* are created during the run. Strings only (GraphQL node IDs).
* Keep in sync with `STRING_FIELDS` in `app/api/workflow-run/[runId]/route.ts`.
*/
export type WorkflowRunArtifactPatchKey =
| "prNodeId"
| "issueNodeId"
| "reviewNodeId"
| "planCommentNodeId"
| "summarySnapshot";
/**
* Usage fields — aggregated across all agent calls and PATCHed once at
* end-of-run. Token counts are Int4 on the DB side (ample for any realistic
* run); `costUsd` is a Decimal populated by provider-reported dollar amounts.
* Keep in sync with `INT_FIELDS` + `DECIMAL_FIELDS` in the server route.
*/
export type WorkflowRunUsagePatchKey =
| "inputTokens"
| "outputTokens"
| "cacheReadTokens"
| "cacheWriteTokens"
| "costUsd";
export type WorkflowRunPatch = Partial<Record<WorkflowRunArtifactPatchKey, string>> &
Partial<Record<WorkflowRunUsagePatchKey, number>>;
const STRING_KEYS: WorkflowRunArtifactPatchKey[] = [
"prNodeId",
"issueNodeId",
"reviewNodeId",
"planCommentNodeId",
"summarySnapshot",
];
const NUMBER_KEYS: WorkflowRunUsagePatchKey[] = [
"inputTokens",
"outputTokens",
"cacheReadTokens",
"cacheWriteTokens",
"costUsd",
];
/** PATCH workflow-run fields (Pullfrog JWT, not GitHub). */
export async function patchWorkflowRunFields(
ctx: ToolContext,
fields: WorkflowRunPatch
): Promise<void> {
if (ctx.runId === undefined || !ctx.apiToken) return;
const body: Record<string, string | number> = {};
for (const key of STRING_KEYS) {
const value = fields[key];
if (typeof value === "string" && value.length > 0) {
body[key] = value;
}
}
for (const key of NUMBER_KEYS) {
const value = fields[key];
if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
body[key] = value;
}
}
if (Object.keys(body).length === 0) return;
try {
await retry(
async () => {
const response = await apiFetch({
path: `/api/workflow-run/${ctx.runId}`,
method: "PATCH",
headers: {
authorization: `Bearer ${ctx.apiToken}`,
"content-type": "application/json",
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`PATCH workflow-run: ${response.status}`);
},
{
maxAttempts: 3,
delayMs: 2000,
label: "patchWorkflowRunFields",
}
);
} catch (error) {
log.warning(`patchWorkflowRunFields exhausted retries: ${error}`);
}
}
/**
* Postgres INTEGER / Prisma Int4 is signed 32-bit. Aggregated usage won't
* realistically hit this in a single run (2.1B tokens ≈ $6000+ of input on
* Claude Opus), but clamping here keeps the wire payload self-consistent:
* the server rejects out-of-range INT fields individually, so without a
* client-side clamp a single overflow would write a partial row where
* some columns land and others silently don't.
*/
const INT4_MAX = 2_147_483_647;
function clampInt(value: number, field: WorkflowRunUsagePatchKey): number {
if (value > INT4_MAX) {
log.warning(
`aggregateUsage: ${field}=${value} exceeds INT4_MAX (${INT4_MAX}) — clamping so the rest of the usage row still persists.`
);
return INT4_MAX;
}
return value;
}
/**
* Sum per-agent usage entries into a single WorkflowRunPatch payload.
* Returns an empty object when there's nothing to report, which causes
* `patchWorkflowRunFields` to no-op — safe to call unconditionally from
* end-of-run paths. Zero-valued fields are dropped so the DB only stores
* positive sums (and NULL means "not reported").
*
* Token sums are clamped to INT4_MAX to guarantee the payload the server
* sees is always self-consistent across all numeric columns.
*/
export function aggregateUsage(entries: AgentUsage[]): WorkflowRunPatch {
if (entries.length === 0) return {};
const sum = entries.reduce(
(acc, e) => ({
inputTokens: acc.inputTokens + e.inputTokens,
outputTokens: acc.outputTokens + e.outputTokens,
cacheReadTokens: acc.cacheReadTokens + (e.cacheReadTokens ?? 0),
cacheWriteTokens: acc.cacheWriteTokens + (e.cacheWriteTokens ?? 0),
costUsd: acc.costUsd + (e.costUsd ?? 0),
}),
{ inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, costUsd: 0 }
);
const out: WorkflowRunPatch = {};
if (sum.inputTokens > 0) out.inputTokens = clampInt(sum.inputTokens, "inputTokens");
if (sum.outputTokens > 0) out.outputTokens = clampInt(sum.outputTokens, "outputTokens");
if (sum.cacheReadTokens > 0)
out.cacheReadTokens = clampInt(sum.cacheReadTokens, "cacheReadTokens");
if (sum.cacheWriteTokens > 0)
out.cacheWriteTokens = clampInt(sum.cacheWriteTokens, "cacheWriteTokens");
if (sum.costUsd > 0) out.costUsd = sum.costUsd;
return out;
}
utils/payload.test.ts
-56
View File
@@ -1,56 +0,0 @@
import { Inputs, JsonPayload } from "./payload.ts";
describe("Inputs schema", () => {
it("only prompt is required", () => {
const result = Inputs.assert({ prompt: "test prompt" });
expect(result).toEqual({ prompt: "test prompt" });
expect(() => Inputs.assert({})).toThrow();
});
it.each([
["push", "enabled"],
["push", "disabled"],
["push", undefined],
["shell", "enabled"],
["shell", "restricted"],
["shell", "disabled"],
["shell", undefined],
["timeout", "10m"],
["timeout", "1h30m"],
["timeout", "30s"],
["timeout", undefined],
] as const)("should accept %s for %s", (prop, value) => {
const input = { prompt: "test", [prop]: value };
expect(() => Inputs.assert(input)).not.toThrow();
});
it.each([["push"], ["shell"]] as const)("should reject invalid %s values", (prop) => {
const input = { prompt: "test", [prop]: "invalid" as any };
expect(() => Inputs.assert(input)).toThrow();
});
});
describe("JsonPayload schema", () => {
it("requires ~pullfrog and version and prompt", () => {
const result = JsonPayload.assert({
"~pullfrog": true,
version: "1.2.3",
prompt: "test prompt",
});
expect(result).toMatchObject({ "~pullfrog": true, version: "1.2.3", prompt: "test prompt" });
expect(() => JsonPayload.assert({})).toThrow();
expect(() => JsonPayload.assert({ "~pullfrog": true })).toThrow();
expect(() => JsonPayload.assert({ version: "1.2.3" })).toThrow();
});
it.each([
["timeout", "10m"],
["timeout", "1h30m"],
["timeout", "30s"],
["model", "anthropic/claude-opus"],
["event", { trigger: "unknown" }],
] as const)("should accept optional %s with value %s", (prop, value) => {
const input = { "~pullfrog": true, version: "1.2.3", prompt: "test prompt", [prop]: value };
expect(() => JsonPayload.assert(input)).not.toThrow();
});
});
utils/payload.ts
+36 -87
View File
@@ -2,50 +2,12 @@ import { isAbsolute, resolve } from "node:path";
import * as core from "@actions/core";
import { type } from "arktype";
import type { AuthorPermission, PayloadEvent } from "../external.ts";
import packageJson from "../package.json" with { type: "json" };
import { log } from "./cli.ts";
import type { RepoSettings } from "./runContext.ts";
import { validateCompatibility } from "./versioning.ts";
// tool permission enum types for inputs
const ShellPermissionInput = type.enumerated("disabled", "restricted", "enabled");
const PushPermissionInput = type.enumerated("disabled", "restricted", "enabled");
// schema for JSON payload passed via prompt (internal dispatch invocation)
// note: permissions are intentionally NOT included here to prevent injection attacks
// permissions are derived from event.authorPermission instead
export const JsonPayload = type({
"~pullfrog": "true",
version: "string",
"model?": "string | undefined",
prompt: "string",
"triggerer?": "string | undefined",
"eventInstructions?": "string",
"previousRunsNote?": "string",
"event?": "object",
"timeout?": "string | undefined",
"progressComment?": type({
id: "string",
type: "'issue' | 'review'",
}).or("undefined"),
"generateSummary?": "boolean | undefined",
});
// permission levels that indicate collaborator status (have push access)
const COLLABORATOR_PERMISSIONS: AuthorPermission[] = ["admin", "maintain", "write"];
// check if the event author has collaborator-level permissions
function isCollaborator(event: PayloadEvent): boolean {
const perm = event.authorPermission;
return perm !== undefined && COLLABORATOR_PERMISSIONS.includes(perm);
}
// inputs schema - action inputs from core.getInput()
// note: tool permissions use .or("undefined") because getInput() || undefined
// explicitly sets the property to undefined when empty, which is different from
// the property being absent. arktype's "prop?" means "optional to include" but
// if included, must match the type - so we need to explicitly allow undefined.
export const Inputs = type({
prompt: "string",
"model?": type.string.or("undefined"),
@@ -69,7 +31,14 @@ function resolveCwd(cwd: string | undefined): string | undefined {
return workspace ? resolve(workspace, cwd) : cwd;
}
export type ResolvedPromptInput = string | typeof JsonPayload.infer;
const COLLABORATOR_PERMISSIONS: AuthorPermission[] = ["admin", "maintain", "write"];
function isCollaborator(event: PayloadEvent): boolean {
const perm = event.authorPermission;
return perm !== undefined && COLLABORATOR_PERMISSIONS.includes(perm);
}
export type ResolvedPromptInput = string | Record<string, unknown>;
export function resolvePromptInput(): ResolvedPromptInput {
const prompt = core.getInput("prompt", { required: true });
@@ -78,19 +47,14 @@ export function resolvePromptInput(): ResolvedPromptInput {
try {
parsed = JSON.parse(prompt);
} catch {
// JSON parse error is fine (plain text prompt)
return prompt;
}
if (!parsed || typeof parsed !== "object" || !("~pullfrog" in parsed)) {
// if it doesn't look like a pullfrog payload, return the plain text prompt
if (!parsed || typeof parsed !== "object") {
return prompt;
}
// validation errors should propagate
const jsonPayload = JsonPayload.assert(parsed);
validateCompatibility(jsonPayload.version, packageJson.version);
return jsonPayload;
return parsed as Record<string, unknown>;
}
function resolveNonPromptInputs() {
@@ -98,91 +62,76 @@ function resolveNonPromptInputs() {
model: core.getInput("model") || undefined,
timeout: core.getInput("timeout") || undefined,
cwd: core.getInput("cwd") || undefined,
push: core.getInput("push") || undefined,
shell: core.getInput("shell") || undefined,
push: (core.getInput("push") as "disabled" | "restricted" | "enabled") || undefined,
shell: (core.getInput("shell") as "disabled" | "restricted" | "enabled") || undefined,
});
}
const isPullfrog = (actor: string | null | undefined): boolean => {
actor = actor?.replace("[bot]", "");
return !!actor && (actor === "pullfrog" || actor === "pullfrogdev");
};
export function resolvePayload(
resolvedPromptInput: ResolvedPromptInput,
repoSettings: RepoSettings
) {
// Helper: extract a string field from an unknown JSON payload
function str(obj: Record<string, unknown> | undefined, key: string): string | undefined {
const v = obj?.[key];
return typeof v === "string" ? v : undefined;
}
const [prompt, jsonPayload] =
typeof resolvedPromptInput !== "string"
? [resolvedPromptInput.prompt, resolvedPromptInput]
? [
str(resolvedPromptInput, "prompt") ?? JSON.stringify(resolvedPromptInput),
resolvedPromptInput,
]
: [resolvedPromptInput, undefined];
const inputs = resolveNonPromptInputs();
// resolve event - use type guard for jsonPayload.event, fallback to unknown trigger
const rawEvent = jsonPayload?.event;
const rawEvent = jsonPayload?.["event"];
const event: PayloadEvent = isPayloadEvent(rawEvent) ? rawEvent : { trigger: "unknown" };
const model = jsonPayload?.model ?? inputs.model ?? repoSettings.model ?? undefined;
const model =
str(jsonPayload, "model") ?? inputs.model ?? repoSettings.model ?? process.env.OLLAMA_MODEL ?? undefined;
// determine shell permission - strictest setting wins
// precedence: disabled > restricted > enabled
// non-collaborators always get at least "restricted"
const isNonCollaborator = !isCollaborator(event);
const repoShell = repoSettings.shell ?? "restricted";
const inputShell = inputs.shell;
// resolve shell: start with repo setting, then apply restrictions
let resolvedShell = repoShell;
// input can only make it stricter (disabled > restricted > enabled)
if (inputShell === "disabled") {
resolvedShell = "disabled";
} else if (inputShell === "restricted" && resolvedShell === "enabled") {
resolvedShell = "restricted";
}
// non-collaborators get at least "restricted" (can't have "enabled")
if (isNonCollaborator && resolvedShell === "enabled") {
resolvedShell = "restricted";
}
// build payload - precedence: inputs > repoSettings > fallbacks
// note: modes are NOT in payload - they come from repoSettings in main()
return {
"~pullfrog": true as const,
version: jsonPayload?.version ?? packageJson.version,
"~shockbot": true as const,
model,
prompt,
triggerer:
jsonPayload?.triggerer ??
// it's not a common use case but GITHUB_ACTOR can be a user when the workflow is manually triggered by a user through GitHub Actions UI
(!isPullfrog(process.env.GITHUB_ACTOR) ? process.env.GITHUB_ACTOR : undefined),
eventInstructions: jsonPayload?.eventInstructions,
previousRunsNote: jsonPayload?.previousRunsNote,
str(jsonPayload, "triggerer") ?? process.env.GITHUB_ACTOR ?? undefined,
eventInstructions: str(jsonPayload, "eventInstructions"),
event,
timeout: inputs.timeout ?? jsonPayload?.timeout,
timeout: inputs.timeout ?? str(jsonPayload, "timeout"),
cwd: resolveCwd(inputs.cwd),
progressComment: jsonPayload?.progressComment,
generateSummary: jsonPayload?.generateSummary,
progressComment: (() => {
const pc = jsonPayload?.["progressComment"];
if (!pc || typeof pc !== "object") return undefined;
const p = pc as Record<string, unknown>;
if (typeof p.id !== "string" || p.type !== "issue") return undefined;
return { id: p.id, type: "issue" as const };
})(),
// permissions: inputs > repoSettings > fallbacks
push: inputs.push ?? repoSettings.push ?? "restricted",
shell: resolvedShell,
// set by proxy logic in main.ts when routing through OpenRouter
proxyModel: undefined as string | undefined,
};
}
export type ResolvedPayload = ReturnType<typeof resolvePayload>;
/**
* Parse and validate the optional `output_schema` action input. Returns the
* parsed object when present, or `undefined` when absent. Throws on invalid
* JSON or non-object payloads — these are workflow-author errors that should
* surface immediately, not silently degrade to "no schema".
*/
export function resolveOutputSchema(): Record<string, unknown> | undefined {
const raw = core.getInput("output_schema");
if (!raw) return undefined;
utils/postApiFetch.ts
-51
View File
@@ -1,51 +0,0 @@
/** stdlib-only Pullfrog API fetch for entryPost.ts (no node_modules). */
type PostApiFetchOptions = {
path: string;
method?: string | undefined;
headers?: Record<string, string> | undefined;
body?: string | undefined;
};
function getApiUrl(): string {
return process.env.API_URL || "https://pullfrog.com";
}
export async function postApiFetch(options: PostApiFetchOptions): Promise<Response> {
const url = new URL(options.path, getApiUrl());
const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
if (bypassSecret) {
url.searchParams.set("x-vercel-protection-bypass", bypassSecret);
}
const headers: Record<string, string> = {
...options.headers,
};
if (bypassSecret) {
headers["x-vercel-protection-bypass"] = bypassSecret;
}
if (!options.body) {
for (const key of Object.keys(headers)) {
if (key.toLowerCase() === "content-type") delete headers[key];
}
}
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30_000);
try {
const init: RequestInit = {
method: options.method ?? "GET",
headers,
signal: controller.signal,
};
if (options.body) init.body = options.body;
return await fetch(url, init);
} finally {
clearTimeout(timeoutId);
}
}
utils/prSummary.ts
-147
View File
@@ -1,147 +0,0 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import type { ToolContext } from "../mcp/server.ts";
import { apiFetch } from "./apiFetch.ts";
import { log } from "./cli.ts";
import { patchWorkflowRunFields } from "./patchWorkflowRunFields.ts";
/**
* The PR-level summary snapshot is a markdown file the agent edits in place
* during a Review / IncrementalReview run. The server seeds the file with
* either the previous run's snapshot (incremental) or a stub scaffold (first
* run), lets the agent edit it with its native file-editing tools, then
* reads it back at end-of-run and persists it to `WorkflowRun.summarySnapshot`.
*
* The snapshot is an internal artifact — it is consumed by future agent runs
* as durable cross-run context, not surfaced to humans. User-visible summary
* content lives in the Review / IncrementalReview review bodies, governed by
* `action/modes.ts`.
*
* Edit-in-place avoids the output-token tax of a tool call that regurgitates
* the full snapshot, and gives incremental runs a clean surface that
* range-diffs cleanly across runs because the section headings are stable.
*/
export const SUMMARY_FILE_NAME = "pullfrog-summary.md";
/**
* minimal seed for first-run PRs. just a header + a one-line note about
* what this file is for. structure is intentionally NOT prescribed —
* different PRs warrant different organization, and the agent should pick
* a shape that fits this PR. the agent's prompt (see selectMode.ts
* `buildSummaryAddendum`) carries the actual instructions for what to
* capture and how.
*
* keeping the seed short also makes the unchanged-from-seed gate more
* sensitive — any meaningful edit moves the file off the seed, so
* `persistSummary` can reliably skip the DB write when the agent didn't
* touch the file.
*/
export const SUMMARY_SCAFFOLD = `# PR summary
<!-- durable cross-run context. edit in place; the next agent run reads this
before reviewing new commits. structure however serves the PR best. -->
`;
const MIN_SNAPSHOT_LENGTH = 60;
/** PG TEXT can hold ~1GB but a sane cap protects the DB / API payloads. */
const MAX_SNAPSHOT_LENGTH = 32_768;
export function summaryFilePath(tmpdir: string): string {
return join(tmpdir, SUMMARY_FILE_NAME);
}
/** seed the summary file with previous snapshot (incremental) or scaffold (first run). */
export async function seedSummaryFile(params: {
tmpdir: string;
previousSnapshot: string | null;
}): Promise<string> {
const path = summaryFilePath(params.tmpdir);
await mkdir(dirname(path), { recursive: true });
const seed =
params.previousSnapshot && params.previousSnapshot.trim().length >= MIN_SNAPSHOT_LENGTH
? params.previousSnapshot
: SUMMARY_SCAFFOLD;
await writeFile(path, seed, "utf8");
return path;
}
/** read + validate the summary file written by the agent.
* returns null when the file is missing or fails sanity checks. */
export async function readSummaryFile(path: string): Promise<string | null> {
let raw: string;
try {
raw = await readFile(path, "utf8");
} catch {
return null;
}
const trimmed = raw.trim();
if (trimmed.length < MIN_SNAPSHOT_LENGTH) return null;
if (trimmed.length > MAX_SNAPSHOT_LENGTH) return trimmed.slice(0, MAX_SNAPSHOT_LENGTH);
return trimmed;
}
/**
* Fetch the most recent persisted PR summary snapshot for this PR.
* Returns null on first-time PRs, when summary is disabled, or on any error.
* Best-effort: a transient API failure should not block the run.
*/
export async function fetchPreviousSnapshot(
ctx: ToolContext,
prNumber: number
): Promise<string | null> {
if (!ctx.githubInstallationToken) return null;
try {
const response = await apiFetch({
path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/pr/${prNumber}/summary-comment`,
method: "GET",
headers: { authorization: `Bearer ${ctx.githubInstallationToken}` },
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) return null;
const data = (await response.json()) as { snapshot?: string | null };
return typeof data.snapshot === "string" && data.snapshot.length > 0 ? data.snapshot : null;
} catch {
return null;
}
}
/**
* Read the agent-edited PR summary tmpfile and persist to
* `WorkflowRun.summarySnapshot`.
*
* Best-effort: any failure is logged and does not affect the run's success
* status. Skips the PATCH when the file is byte-identical to its seed —
* persisting the seed verbatim would either re-write what the DB already has
* (on incremental runs) or serialize the placeholder scaffold (on first
* runs), neither of which is useful.
*
* Funnels through both the success path and the SIGINT/SIGTERM handler;
* `summaryPersistAttempted` guards against double-execution.
*/
export async function persistSummary(ctx: ToolContext): Promise<void> {
const filePath = ctx.toolState.summaryFilePath;
if (!filePath) return;
if (ctx.toolState.summaryPersistAttempted) return;
ctx.toolState.summaryPersistAttempted = true;
const snapshot = await readSummaryFile(filePath);
if (!snapshot) {
log.debug(`pr summary tmpfile missing or invalid at ${filePath} — skipping persist`);
return;
}
// soft gate: agent never touched the seeded file. saving the seed back
// is a no-op at best (incremental run — DB already has it) and a bug at
// worst (first run — serializes the placeholder italics). log a warning
// so the failure mode is visible in CI without flipping the run to
// failed.
const seed = ctx.toolState.summarySeed?.trim();
if (seed !== undefined && snapshot === seed) {
log.warning(
"» pr summary tmpfile unchanged from seed — skipping persist (agent did not edit it)"
);
return;
}
await patchWorkflowRunFields(ctx, { summarySnapshot: snapshot }).catch((err) => {
log.debug(`pr summary persist failed: ${err instanceof Error ? err.message : String(err)}`);
});
}
utils/progressComment.ts
+31 -191
View File
@@ -1,28 +1,17 @@
/**
* Single source of truth for reading, updating, deleting, and creating "progress comments" —
* the GitHub comments Pullfrog uses to surface a run's status.
*
* A progress comment can be one of two distinct GitHub entities with non-overlapping IDs and
* distinct REST endpoints:
* - "issue": a top-level issue/PR timeline comment (octokit.rest.issues.*Comment)
* - "review": an inline PR review-thread comment (octokit.rest.pulls.*ReviewComment)
*
* Callers carry a `ProgressComment` (id + type) value end-to-end so the right endpoint is always
* picked. Adding a third comment type later means one new branch in this file, not six.
* the Gitea comments shockbot uses to surface a run's status.
*/
export type ProgressCommentType = "issue" | "review";
import type { Gitea } from "./gitea.ts";
export type ProgressCommentType = "issue";
export type ProgressComment = {
id: number;
type: ProgressCommentType;
};
/**
* Parse the on-the-wire `{ id: string; type }` shape (the form carried in `JsonPayload`)
* into the in-memory `ProgressComment` shape. Returns undefined when the id isn't a
* positive integer so callers can short-circuit cleanly. Callers handle logging.
*/
export function parseProgressComment(
raw: { id: string; type: ProgressCommentType } | null | undefined
): ProgressComment | undefined {
@@ -32,162 +21,54 @@ export function parseProgressComment(
return { id, type: raw.type };
}
// minimal Octokit shape needed by the progress-comment helpers. structural so the helper
// can be called from both the action package (@octokit/rest v22) and the root project
// (@octokit/rest v21) without a nominal type clash. only the methods used here are listed.
interface CommentResponse {
data: { id: number; body?: string | null | undefined; html_url: string; node_id?: string };
}
export interface ProgressCommentOctokit {
rest: {
issues: {
createComment: (params: {
owner: string;
repo: string;
issue_number: number;
body: string;
}) => Promise<CommentResponse>;
getComment: (params: {
owner: string;
repo: string;
comment_id: number;
}) => Promise<CommentResponse>;
updateComment: (params: {
owner: string;
repo: string;
comment_id: number;
body: string;
}) => Promise<CommentResponse>;
deleteComment: (params: {
owner: string;
repo: string;
comment_id: number;
}) => Promise<unknown>;
};
pulls: {
createReplyForReviewComment: (params: {
owner: string;
repo: string;
pull_number: number;
comment_id: number;
body: string;
}) => Promise<CommentResponse>;
getReviewComment: (params: {
owner: string;
repo: string;
comment_id: number;
}) => Promise<CommentResponse>;
updateReviewComment: (params: {
owner: string;
repo: string;
comment_id: number;
body: string;
}) => Promise<CommentResponse>;
deleteReviewComment: (params: {
owner: string;
repo: string;
comment_id: number;
}) => Promise<unknown>;
};
};
}
interface ApiCtx {
octokit: ProgressCommentOctokit;
gitea: Gitea;
owner: string;
repo: string;
}
/**
* Fetch a progress comment via the appropriate REST endpoint for its type.
* Returns the common subset of fields callers actually use.
*/
export async function getProgressComment(
ctx: ApiCtx,
comment: ProgressComment
): Promise<{ id: number; body: string | undefined; html_url: string }> {
const result = await (comment.type === "review"
? ctx.octokit.rest.pulls.getReviewComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
})
: ctx.octokit.rest.issues.getComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
}));
return {
id: result.data.id,
body: result.data.body ?? undefined,
html_url: result.data.html_url,
};
const result = await ctx.gitea.rest.issue.issueGetComment({
owner: ctx.owner,
repo: ctx.repo,
id: comment.id,
});
return { id: result.data.id!, body: result.data.body ?? undefined, html_url: result.data.html_url! };
}
/**
* Update a progress comment in place via the appropriate REST endpoint.
* Returns the common subset of fields callers actually use.
*/
export async function updateProgressComment(
ctx: ApiCtx,
comment: ProgressComment,
body: string
): Promise<{
id: number;
body: string | undefined;
html_url: string;
node_id: string | undefined;
}> {
const result = await (comment.type === "review"
? ctx.octokit.rest.pulls.updateReviewComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
body,
})
: ctx.octokit.rest.issues.updateComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
body,
}));
): Promise<{ id: number; body: string | undefined; html_url: string; node_id: string | undefined }> {
const result = await ctx.gitea.rest.issue.issueEditComment({
owner: ctx.owner,
repo: ctx.repo,
id: comment.id,
body: { body },
});
return {
id: result.data.id,
id: result.data.id!,
body: result.data.body ?? undefined,
html_url: result.data.html_url,
node_id: result.data.node_id,
html_url: result.data.html_url!,
node_id: undefined,
};
}
/**
* Delete a progress comment via the appropriate REST endpoint.
* Lower-level than `deleteProgressComment` in mcp/comment.ts — that one also clears
* tool state. Callers that don't have a ToolContext (post cleanup, error handlers)
* should use this directly; the higher-level wrapper delegates here.
*/
export async function deleteProgressCommentApi(
ctx: ApiCtx,
comment: ProgressComment
): Promise<void> {
if (comment.type === "review") {
await ctx.octokit.rest.pulls.deleteReviewComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
});
return;
}
await ctx.octokit.rest.issues.deleteComment({
await ctx.gitea.rest.issue.issueDeleteComment({
owner: ctx.owner,
repo: ctx.repo,
comment_id: comment.id,
id: comment.id,
});
}
/**
* Discriminated target for `createLeapingProgressComment`. The two variants map to the two
* distinct GitHub create endpoints; review-reply additionally needs the parent comment ID.
*/
export type CreateProgressCommentTarget =
| { kind: "issue"; issueNumber: number }
| { kind: "reviewReply"; pullNumber: number; replyToCommentId: number };
@@ -198,64 +79,23 @@ export interface CreatedProgressComment {
html_url: string;
}
/**
* Create the initial "Leaping into action..." progress comment.
*
* Reliability: when `kind: "reviewReply"` fails (e.g. the parent comment was deleted or the
* thread is otherwise unreachable), falls back to a top-level issue comment on the same PR
* rather than leaving the run with no progress surface. The fallback is logged.
*
* (PR # === issue # in GitHub's number space, so `pullNumber` doubles as the fallback target.)
*/
export async function createLeapingProgressComment(
ctx: ApiCtx,
target: CreateProgressCommentTarget,
body: string
): Promise<CreatedProgressComment> {
if (target.kind === "reviewReply") {
try {
const result = await ctx.octokit.rest.pulls.createReplyForReviewComment({
owner: ctx.owner,
repo: ctx.repo,
pull_number: target.pullNumber,
comment_id: target.replyToCommentId,
body,
});
return {
comment: { id: result.data.id, type: "review" },
body: result.data.body ?? undefined,
html_url: result.data.html_url,
};
} catch (error) {
// console.warn (not the action-flavored log.warning) because this helper runs in
// both the action runtime and the Next.js webhook context, and we don't want a
// ::warning:: GitHub Actions annotation leaking into Vercel logs.
console.warn(
`[progressComment] review reply failed (parent ${target.replyToCommentId} on PR #${target.pullNumber}), falling back to issue comment:`,
error
);
const fallback = await ctx.octokit.rest.issues.createComment({
owner: ctx.owner,
repo: ctx.repo,
issue_number: target.pullNumber,
body,
});
return {
comment: { id: fallback.data.id, type: "issue" },
body: fallback.data.body ?? undefined,
html_url: fallback.data.html_url,
};
}
}
const result = await ctx.octokit.rest.issues.createComment({
const issueNumber =
target.kind === "issue" ? target.issueNumber : target.pullNumber;
const result = await ctx.gitea.rest.issue.issueCreateComment({
owner: ctx.owner,
repo: ctx.repo,
issue_number: target.issueNumber,
body,
index: issueNumber,
body: { body },
});
return {
comment: { id: result.data.id, type: "issue" },
comment: { id: result.data.id!, type: "issue" },
body: result.data.body ?? undefined,
html_url: result.data.html_url,
html_url: result.data.html_url!,
};
}
utils/providerErrors.test.ts
-313
View File
@@ -1,313 +0,0 @@
import {
detectProviderError,
extractProviderId,
findProviderErrorMatch,
isProviderBillingExhausted,
isRouterKeylimitExhaustedError,
} from "./providerErrors.ts";
describe("detectProviderError", () => {
describe("false positives previously seen in production", () => {
it("returns null for commit SHAs containing 429", () => {
expect(detectProviderError("hash=7a46d89f505b36df49b4f54429daffa1a9459b11")).toBeNull();
expect(detectProviderError("commit f609cc89e84596ab125d60dac568bfb2ef398396 429")).toBeNull();
});
it("classifies 401 + x-ratelimit-* headers as auth, not rate-limited", () => {
// OpenRouter 401 responses bundle `x-ratelimit-*` rate-limit headers
// alongside the auth error. the auth patterns must win — pre-fix this
// got tagged as `rate limited` because of the loose `\brate[_ ]limit`
// match against header names like `ratelimit-limit-requests`. note: in
// OpenRouter's actual format the header name is `ratelimit` (one word),
// but the dumped JSON sometimes contains `rate-limit` separators too.
const stderr = JSON.stringify({
error: { name: "APIError", statusCode: 401, message: "Invalid authentication credentials" },
headers: {
"x-ratelimit-limit-requests": 50,
"x-ratelimit-remaining-requests": 49,
"x-ratelimit-reset-tokens": "2025-01-01T00:00:00Z",
},
});
expect(detectProviderError(stderr)).toBe("auth error (401)");
});
it("returns null for INTERNAL_SERVER_ERROR substring", () => {
expect(detectProviderError("HTTP/1.1 500 INTERNAL_SERVER_ERROR")).toBeNull();
expect(detectProviderError("expected: not INTERNAL_SERVER_ERROR")).toBeNull();
});
it("returns null for INTERNALS substring", () => {
expect(detectProviderError("debugging INTERNALS of the parser")).toBeNull();
});
});
describe("auth errors", () => {
it("detects 401 / 403 status codes as auth errors", () => {
expect(detectProviderError('{"statusCode": 401}')).toBe("auth error (401)");
expect(detectProviderError('{"statusCode": 403}')).toBe("auth error (403)");
expect(detectProviderError("status_code: 401")).toBe("auth error (401)");
});
it("detects OpenRouter 'User not found' (disabled/invalid key)", () => {
// bare `"code":401` lacks a status-key prefix so the 401 status pattern
// intentionally doesn't fire; the User-not-found pattern catches it.
expect(detectProviderError('{"error":{"message":"User not found","code":401}}')).toBe(
"auth error (invalid/disabled key)"
);
expect(detectProviderError("APIError: User not found.")).toBe(
"auth error (invalid/disabled key)"
);
});
it("detects 'Invalid authentication' phrasing", () => {
expect(detectProviderError("Invalid authentication credentials")).toBe(
"auth error (invalid credentials)"
);
});
it("detects 'No auth credentials found' phrasing", () => {
expect(detectProviderError("AI_APICallError: No auth credentials found")).toBe(
"auth error (missing credentials)"
);
});
});
describe("billing exhaustion", () => {
// see #778 — providers return 401 / 429 for billing/quota exhaustion
// (OpenCode Zen `CreditsError` / `FreeUsageLimitError`, Gemini
// `RESOURCE_EXHAUSTED` + spending cap, "Insufficient balance"). these
// are non-retryable; status-code patterns must NOT win and surface the
// misleading "auth error (401)" / "rate limited (429)" labels.
it("classifies OpenCode Zen CreditsError as billing exhausted, not 401", () => {
const stderr = JSON.stringify({
statusCode: 401,
responseBody:
'{"type":"error","error":{"type":"CreditsError","message":"Insufficient balance. Manage your billing here: https://opencode.ai/workspace/x/billing"}}',
});
expect(detectProviderError(stderr)).toBe("provider billing exhausted");
});
it("classifies OpenCode Zen FreeUsageLimitError as billing exhausted, not 429", () => {
const stderr = JSON.stringify({
statusCode: 429,
responseBody:
'{"type":"error","error":{"type":"FreeUsageLimitError","message":"Rate limit exceeded. Please try again later."}}',
});
expect(detectProviderError(stderr)).toBe("provider billing exhausted");
});
it("classifies Gemini spending-cap RESOURCE_EXHAUSTED as billing exhausted, not 429", () => {
const stderr =
'statusCode: 429, body: {"code": 429, "status": "RESOURCE_EXHAUSTED", "message": "Your project has exceeded its monthly spending cap..."}';
expect(detectProviderError(stderr)).toBe("provider billing exhausted");
});
it("classifies bare 'Insufficient balance' as billing exhausted", () => {
expect(detectProviderError("error: Insufficient balance")).toBe("provider billing exhausted");
});
it("classifies Anthropic 'credit balance is too low' as billing exhausted (#835)", () => {
// Anthropic-direct BYOK returns this string verbatim when the user's
// Anthropic console credit balance can't cover the request. distinct
// wording from "Insufficient balance" used by DeepSeek / OpenCode Zen.
const stderr =
"APIError: 400 Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.";
expect(detectProviderError(stderr)).toBe("provider billing exhausted");
});
});
describe("real provider errors", () => {
it("detects 429 only when adjacent to a status key", () => {
expect(detectProviderError('{"statusCode": 429}')).toBe("rate limited (429)");
expect(detectProviderError('{"status_code": 429, "message": "..."}')).toBe(
"rate limited (429)"
);
expect(detectProviderError("http_status: 429")).toBe("rate limited (429)");
expect(detectProviderError("status=429")).toBe("rate limited (429)");
});
it("detects rate_limit_error and rate_limit_exceeded", () => {
expect(detectProviderError('{"type":"rate_limit_error"}')).toBe("rate limited");
expect(detectProviderError("rate_limit_exceeded")).toBe("rate limited");
expect(detectProviderError("plain rate limit reached")).toBe("rate limited");
});
it("detects rate-limit phrasing with trailing inflection", () => {
expect(detectProviderError("Error: rate limited by provider")).toBe("rate limited");
expect(detectProviderError("rate limits exceeded for this key")).toBe("rate limited");
});
it("detects RESOURCE_EXHAUSTED", () => {
expect(detectProviderError('"status": "RESOURCE_EXHAUSTED"')).toBe("quota exhausted");
});
it("detects gRPC INTERNAL status as a whole word", () => {
expect(detectProviderError('"status": "INTERNAL"')).toBe("provider internal error");
});
it("detects UNAVAILABLE as a whole word", () => {
expect(detectProviderError('"status": "UNAVAILABLE"')).toBe("provider unavailable");
});
it("detects 500 / 503 only when adjacent to a status key", () => {
expect(detectProviderError('"statusCode": 500')).toBe("provider 500 error");
expect(detectProviderError('"statusCode": 503')).toBe("provider unavailable (503)");
expect(detectProviderError("v1.503.0 release notes")).toBeNull();
});
it("detects quota and zero-quota responses", () => {
expect(detectProviderError('"message": "quota exceeded"')).toBe("quota error");
expect(detectProviderError('{"code":"insufficient_quota"}')).toBe("quota error");
expect(detectProviderError('"error":"quota_exceeded"')).toBe("quota error");
expect(detectProviderError('{"reason":"quotaExceeded"}')).toBe("quota error");
expect(detectProviderError('{"limit": 0, "remaining": 0}')).toBe("zero quota");
expect(detectProviderError('"time_limit": 0')).toBeNull();
});
});
});
describe("findProviderErrorMatch", () => {
// regression for issue #703: when stderr arrives as a multi-KB buffer
// (mcp tool-schema dump + the actual error message), the old
// `chunk.substring(0, 500)` excerpt showed the head of the buffer
// (schema) instead of the matched error text. the windowed excerpt
// must center on the matched line.
it("excerpt centers on the matched line, not the head of the buffer", () => {
const schemaDump =
"{".repeat(2000) +
'"name":"pullfrog_create_pull_request_review","description":"Submit a review..."';
const errorLine = "ERROR 2026-05-13 service=session error=rate_limit_exceeded retry-after=30";
const chunk = `${schemaDump}\n${errorLine}\ncaller stack at handler.ts:42`;
const match = findProviderErrorMatch(chunk);
expect(match).not.toBeNull();
expect(match?.label).toBe("rate limited");
expect(match?.excerpt).toContain("rate_limit_exceeded");
expect(match?.excerpt).toContain("retry-after=30");
expect(match?.excerpt).not.toContain("pullfrog_create_pull_request_review");
});
it("includes a small surrounding-line window for stack-trace context", () => {
const chunk =
"» about to call session.processor\n" +
"ERROR rate_limit_exceeded for key=abc\n" +
"at handler.ts:42\n" +
"at runtime.ts:88";
const match = findProviderErrorMatch(chunk);
expect(match?.excerpt).toContain("about to call session.processor");
expect(match?.excerpt).toContain("rate_limit_exceeded");
expect(match?.excerpt).toContain("handler.ts:42");
expect(match?.excerpt).toContain("runtime.ts:88");
});
it("falls back to the matched line alone when adjacent lines are huge", () => {
const giantPrefix = "x".repeat(5000);
const errorLine = '"statusCode": 429, "message": "slow down"';
const giantSuffix = "y".repeat(5000);
const chunk = `${giantPrefix}\n${errorLine}\n${giantSuffix}`;
const match = findProviderErrorMatch(chunk);
expect(match?.label).toBe("rate limited (429)");
expect(match?.excerpt).toBe(errorLine);
});
it("head-truncates the matched line if it alone exceeds the byte cap", () => {
const padding = "z".repeat(700);
const chunk = `${padding} "statusCode": 429 ${padding}`;
const match = findProviderErrorMatch(chunk);
expect(match?.label).toBe("rate limited (429)");
expect(match?.excerpt.length).toBeLessThanOrEqual(600);
});
it("returns null when no pattern matches", () => {
expect(findProviderErrorMatch("just some normal log line\nnothing wrong here")).toBeNull();
});
});
describe("isProviderBillingExhausted (#835)", () => {
it("matches DeepSeek 'Insufficient Balance' payloads", () => {
expect(isProviderBillingExhausted("AI_APICallError: Insufficient Balance")).toBe(true);
});
it("matches Anthropic 'credit balance is too low' payloads", () => {
expect(
isProviderBillingExhausted("Your credit balance is too low to access the Anthropic API")
).toBe(true);
});
it("matches OpenCode Zen CreditsError / FreeUsageLimitError", () => {
expect(isProviderBillingExhausted("CreditsError: out of credit")).toBe(true);
expect(isProviderBillingExhausted("FreeUsageLimitError: limit hit")).toBe(true);
});
it("returns false for unrelated provider errors", () => {
expect(isProviderBillingExhausted('{"statusCode": 401}')).toBe(false);
expect(isProviderBillingExhausted("rate_limit_exceeded")).toBe(false);
expect(isProviderBillingExhausted("just some log noise")).toBe(false);
});
});
describe("extractProviderId", () => {
it("parses providerID= from OpenCode harness logs", () => {
expect(
extractProviderId(
'ERROR providerID=deepseek modelID=deepseek-v4-pro error={"name":"AI_APICallError"}'
)
).toBe("deepseek");
});
it("lowercases the captured slug", () => {
expect(extractProviderId("providerID=Anthropic modelID=claude")).toBe("anthropic");
});
it("returns null when providerID is absent", () => {
expect(extractProviderId("APIError: Insufficient Balance")).toBeNull();
});
});
describe("isRouterKeylimitExhaustedError", () => {
it("matches the canonical OpenRouter mid-run error", () => {
expect(
isRouterKeylimitExhaustedError(
"APIError: This request requires more credits, or fewer max_tokens. " +
"You requested up to 32000 tokens, but can only afford 22800. " +
"To increase, visit https://openrouter.ai/settings/keys and create a key with a higher total limit"
)
).toBe(true);
});
it("matches the 'requires more credits' phrasing on its own", () => {
expect(
isRouterKeylimitExhaustedError("This request requires more credits, or fewer max_tokens.")
).toBe(true);
});
it("matches the 'requested up to ... can only afford' phrasing on its own", () => {
expect(
isRouterKeylimitExhaustedError("You requested up to 8000 tokens but can only afford 1234")
).toBe(true);
});
it("does not match generic out-of-credit text", () => {
expect(isRouterKeylimitExhaustedError("Your account has insufficient credits")).toBe(false);
expect(isRouterKeylimitExhaustedError("rate_limit_exceeded")).toBe(false);
expect(isRouterKeylimitExhaustedError('{"limit": 0}')).toBe(false);
});
it("does not match unrelated mentions of max_tokens", () => {
expect(isRouterKeylimitExhaustedError("max_tokens parameter must be a positive integer")).toBe(
false
);
});
it("matches across newlines (defends against upstream wrapping/reformatting)", () => {
expect(
isRouterKeylimitExhaustedError(
"APIError: This request requires more credits, or\nfewer max_tokens. You requested up to 32000 tokens"
)
).toBe(true);
expect(
isRouterKeylimitExhaustedError("You requested up to 32000 tokens,\nbut can only afford 22800")
).toBe(true);
});
});
utils/providerErrors.ts
-172
View File
@@ -1,172 +0,0 @@
type ProviderErrorPattern = { regex: RegExp; label: string };
/** Stable label for the BYOK provider-billing-exhausted classification. */
export const PROVIDER_BILLING_EXHAUSTED_LABEL = "provider billing exhausted";
// status codes are only treated as provider errors when they are adjacent to
// a recognised status key. this rejects commit SHAs that happen to contain
// "429", version strings, file hashes, etc.
const statusKey = `\\b(?:status[_ ]?code|http[_ ]?status|status)["']?\\s*[:=]\\s*["']?`;
const PROVIDER_ERROR_PATTERNS: ProviderErrorPattern[] = [
// billing-payload patterns come BEFORE bare status-code patterns. providers
// commonly return 401 / 429 for billing/quota exhaustion (OpenCode Zen
// `CreditsError` / `FreeUsageLimitError`, Gemini `RESOURCE_EXHAUSTED` +
// "spending cap", Anthropic "Insufficient balance" / "credit balance is
// too low"). these are non-retryable and require user-billing action —
// distinct from a transient auth error or rate-limit. status-code patterns
// would otherwise win and surface "auth error (401)" / "rate limited (429)"
// with no billing hint. see #778, #835.
{ regex: /\bCreditsError\b/, label: PROVIDER_BILLING_EXHAUSTED_LABEL },
{ regex: /\bFreeUsageLimitError\b/, label: PROVIDER_BILLING_EXHAUSTED_LABEL },
{ regex: /Insufficient balance/i, label: PROVIDER_BILLING_EXHAUSTED_LABEL },
{ regex: /credit balance is too low/i, label: PROVIDER_BILLING_EXHAUSTED_LABEL },
{ regex: /spending cap/i, label: PROVIDER_BILLING_EXHAUSTED_LABEL },
// auth patterns must come BEFORE rate-limit patterns. OpenRouter 401 error
// payloads carry `x-ratelimit-*` response headers in the dump, and the
// free-form rate-limit regex below would otherwise win on word-boundary
// matches inside header names. canonical 401 messages: OpenRouter returns
// `{"error":{"message":"User not found","code":401}}` for disabled or
// invalid keys (https://openai.luzhipeng.com/docs/api/reference/errors-and-debugging).
{ regex: new RegExp(`${statusKey}401\\b`, "i"), label: "auth error (401)" },
{ regex: new RegExp(`${statusKey}403\\b`, "i"), label: "auth error (403)" },
{ regex: /\bUser not found\b/i, label: "auth error (invalid/disabled key)" },
{ regex: /\bInvalid authentication\b/i, label: "auth error (invalid credentials)" },
{ regex: /\bNo auth credentials found\b/i, label: "auth error (missing credentials)" },
{ regex: new RegExp(`${statusKey}429\\b`, "i"), label: "rate limited (429)" },
{ regex: new RegExp(`${statusKey}500\\b`, "i"), label: "provider 500 error" },
{ regex: new RegExp(`${statusKey}503\\b`, "i"), label: "provider unavailable (503)" },
// matches `rate limit`, `rate limited`, `rate limits exceeded`,
// `rate_limit_error`, `rate_limit_exceeded`. the leading `\b` + `[_ ]`
// separator rejects `x-ratelimit-*` / `anthropic-ratelimit-*` response
// headers (no separator between "rate" and "limit") which routinely
// appear in dumped 401 / 4xx error JSON.
{ regex: /\brate[_ ]limit/i, label: "rate limited" },
{ regex: /\bRESOURCE_EXHAUSTED\b/, label: "quota exhausted" },
// Google gRPC `INTERNAL` status. word-boundary anchors reject
// `INTERNAL_SERVER_ERROR` (HTTP 500 message that may appear in unrelated
// log lines) and identifiers like `INTERNALS`.
{ regex: /\bINTERNAL\b/, label: "provider internal error" },
{ regex: /\bUNAVAILABLE\b/, label: "provider unavailable" },
// matches `quota`, `insufficient_quota`, `quota_exceeded`, `quotaExceeded`.
// word-character lookarounds would reject `_quota` / `quotaX`; `quota` is
// specific enough that a plain substring match is safe.
{ regex: /quota/i, label: "quota error" },
// explicit zero-quota response, e.g. `{"limit": 0}`. the `\b` anchor
// around `limit` rejects keys like `time_limit` or `field_limit`.
{ regex: /["']?\blimit\b["']?\s*:\s*0\b/, label: "zero quota" },
];
/**
* Result of a provider-error scan: the classification label plus a
* human-readable excerpt centered on the matched line. The excerpt is what
* gets surfaced in `» provider error detected (...)` log lines — see
* `extractExcerpt` for the windowing/byte-cap policy.
*/
export type ProviderErrorMatch = {
label: string;
excerpt: string;
};
// roughly half a wide terminal line by 4–5 lines of context; large enough
// to capture a structured error payload (request id, retry-after, model)
// plus its immediate stack/headers, small enough to not flood the log.
const EXCERPT_MAX_BYTES = 600;
const LINES_BEFORE = 1;
const LINES_AFTER = 2;
export function findProviderErrorMatch(text: string): ProviderErrorMatch | null {
for (const entry of PROVIDER_ERROR_PATTERNS) {
const m = entry.regex.exec(text);
if (!m) continue;
return { label: entry.label, excerpt: extractExcerpt(text, m.index) };
}
return null;
}
export function detectProviderError(text: string): string | null {
return findProviderErrorMatch(text)?.label ?? null;
}
/**
* Slice a context window around `matchIndex`: the matched line plus
* `LINES_BEFORE`/`LINES_AFTER` neighbours. If the windowed slice exceeds
* `EXCERPT_MAX_BYTES` (giant adjacent lines, e.g. JSON tool-schema dumps),
* fall back to the matched line alone, head-truncated if still too long.
* Replaces the old `chunk.substring(0, 500)` head-anchored excerpt which
* surfaced whatever happened to be at the front of the stderr buffer
* instead of the error itself. See issue #703.
*/
function extractExcerpt(text: string, matchIndex: number): string {
const lineStart = text.lastIndexOf("\n", matchIndex - 1) + 1;
const lineEndRaw = text.indexOf("\n", matchIndex);
const lineEnd = lineEndRaw === -1 ? text.length : lineEndRaw;
let start = lineStart;
for (let i = 0; i < LINES_BEFORE && start > 0; i++) {
const prev = text.lastIndexOf("\n", start - 2);
start = prev < 0 ? 0 : prev + 1;
}
let end = lineEnd;
for (let i = 0; i < LINES_AFTER && end < text.length; i++) {
const next = text.indexOf("\n", end + 1);
end = next < 0 ? text.length : next;
}
let excerpt = text.slice(start, end);
if (excerpt.length > EXCERPT_MAX_BYTES) {
excerpt = text.slice(lineStart, lineEnd);
if (excerpt.length > EXCERPT_MAX_BYTES) excerpt = excerpt.slice(0, EXCERPT_MAX_BYTES);
}
return excerpt.trim();
}
/**
* OpenRouter's response when the per-run key's remaining budget can't cover
* the agent's `max_tokens` reservation. Distinct from a generic provider error
* because it's a Pullfrog billing concern, not an upstream outage — the user's
* Router wallet ran out (or the key budget was undersized at mint time and the
* agent ran out of headroom partway through).
*
* Match must be specific to this exact OpenRouter error class. Generic "credits"
* or "limit" text shows up in unrelated errors and would mis-classify them.
*
* Sample:
* `APIError: This request requires more credits, or fewer max_tokens.
* You requested up to 32000 tokens, but can only afford 22800.`
*/
// `/s` (dotAll) lets `.*?` cross newlines so we still detect the error if any
// upstream layer reformats the message onto multiple lines. Without it, a
// single inserted `\n` would silently bypass the BillingError reclassification
// and the user would see the generic `❌ Pullfrog failed` dump instead of the
// actionable top-up CTA.
const ROUTER_KEYLIMIT_EXHAUSTED_PATTERN =
/requires more credits.*?fewer max_tokens|requested up to \d+ tokens.*?can only afford/is;
export function isRouterKeylimitExhaustedError(text: string): boolean {
return ROUTER_KEYLIMIT_EXHAUSTED_PATTERN.test(text);
}
/**
* BYOK billing-exhausted: provider rejected the request because the user's
* provider wallet is empty (DeepSeek "Insufficient Balance", Anthropic
* "credit balance is too low", OpenCode Zen `CreditsError` /
* `FreeUsageLimitError`, Gemini "spending cap"). Distinct from
* `isRouterKeylimitExhaustedError` — that's Pullfrog's Router wallet, this
* is the user's own provider account.
*/
export function isProviderBillingExhausted(text: string): boolean {
return findProviderErrorMatch(text)?.label === PROVIDER_BILLING_EXHAUSTED_LABEL;
}
/**
* Extract `providerID=foo` from agent error logs (OpenCode emits this on
* `provider error detected (...)` lines). Returns the lowercase provider
* slug, or null when absent. Used to render a provider-specific dashboard
* link in the BYOK billing-exhausted summary.
*/
export function extractProviderId(text: string): string | null {
const match = text.match(/\bproviderID=([a-z0-9_-]+)/i);
return match ? match[1].toLowerCase() : null;
}
utils/proxy.ts
-235
View File
@@ -1,235 +0,0 @@
/**
* Mint an OpenRouter proxy key via `/api/proxy-token` and inject it as
* `OPENROUTER_API_KEY` for runs that route through Pullfrog Router (managed
* billing accounts) or OSS-grant paths.
*
* Authenticates one of two ways:
* - production: GitHub Actions OIDC token via `core.getIDToken`
* - local dev (`API_URL` is localhost): `x-dev-repo` header bypass
*
* `runProxyResolution` is the entrypoint `main.ts` calls. It wraps
* `resolveProxyModel` and renders the user-facing copy itself (job summary
* + PR progress comment) before rethrowing the structured error — handled
* here, not in the outer `main()` catch, because `toolContext` doesn't
* exist yet at this point in the pipeline.
*
* - 402 → `BillingError` (card declined, balance empty, 3DS, etc.)
* - 503 → `TransientError` (transient sync issue — retry next dispatch)
*/
import * as core from "@actions/core";
import type { ToolState } from "../toolState.ts";
import { apiFetch } from "./apiFetch.ts";
import { isLocalApiUrl } from "./apiUrl.ts";
import {
BillingError,
formatBillingErrorSummary,
formatTransientErrorSummary,
TransientError,
} from "./billingErrors.ts";
import { log, writeSummary } from "./cli.ts";
import { reportErrorToComment } from "./errorReport.ts";
import type { ResolvedPayload } from "./payload.ts";
export interface OidcCredentials {
requestUrl: string;
requestToken: string;
}
async function mintProxyKey(ctx: {
oidcCredentials: OidcCredentials | null;
repo: { owner: string; name: string };
}): Promise<string | null> {
try {
const headers = await buildProxyTokenHeaders(ctx);
if (!headers) return null;
const response = await apiFetch({
path: "/api/proxy-token",
method: "POST",
headers,
});
if (response.status === 402) {
const body = (await response.json().catch(() => null)) as {
error?: string;
code?: string;
declineCode?: string;
needsReauthentication?: boolean;
} | null;
throw new BillingError(body?.error ?? "insufficient balance", {
code: body?.code ?? null,
declineCode: body?.declineCode ?? null,
needsReauthentication: body?.needsReauthentication ?? false,
});
}
// 503 = transient sync issue (partial OpenRouter failure, DB flake,
// in-flight top-up). Not the user's fault — TransientError renders a
// "temporarily unavailable" summary instead of the "billing error"
// label that BillingError uses.
if (response.status === 503) {
const body = (await response.json().catch(() => null)) as { error?: string } | null;
throw new TransientError(
body?.error ?? "billing service temporarily unavailable — retry shortly"
);
}
if (!response.ok) {
log.warning(`proxy key mint failed (${response.status})`);
return null;
}
const data = (await response.json()) as { key: string };
return data.key;
} catch (error) {
if (error instanceof BillingError) throw error;
if (error instanceof TransientError) throw error;
log.warning(`proxy key mint error: ${error instanceof Error ? error.message : String(error)}`);
return null;
} finally {
delete process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
delete process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
}
}
/**
* choose how to authenticate the `/api/proxy-token` request:
*
* - production: mint a fresh OIDC token via `core.getIDToken` and send as
* `Authorization: Bearer …` (the server verifies it cryptographically).
* - local dev (no OIDC + `API_URL` is localhost): send `x-dev-repo:
* owner/repo` instead. the server-side route only honors this header
* when `NODE_ENV === "development"`, so prod is never reachable through
* this branch even if the action is misconfigured.
*
* returns null when neither path is available — caller treats as soft skip.
*/
async function buildProxyTokenHeaders(ctx: {
oidcCredentials: OidcCredentials | null;
repo: { owner: string; name: string };
}): Promise<Record<string, string> | null> {
if (ctx.oidcCredentials) {
process.env.ACTIONS_ID_TOKEN_REQUEST_URL = ctx.oidcCredentials.requestUrl;
process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN = ctx.oidcCredentials.requestToken;
const oidcToken = await core.getIDToken("pullfrog-api");
delete process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
delete process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
return { Authorization: `Bearer ${oidcToken}` };
}
if (isLocalApiUrl()) {
log.info(`» proxy: dev bypass (x-dev-repo) for ${ctx.repo.owner}/${ctx.repo.name}`);
return { "x-dev-repo": `${ctx.repo.owner}/${ctx.repo.name}` };
}
return null;
}
/**
* Decide whether this run needs a minted proxy key and, if so, mint and
* inject it as `OPENROUTER_API_KEY`. Mutates `payload.proxyModel` on success.
*
* `ctx.proxyModel` IS the signal — the server (`run-context/route.ts`) is
* the authority on "should this run use the Router". It already knows the
* full picture (OSS, plan, wallet balance, modelAccessMode) and only sets
* `proxyModel` when the gate passes. The action just trusts that signal
* and mints. Re-deriving the gate locally was redundant and was strictly
* more restrictive (no balance check), which made signup-credit runs on
* no-card private repos silently fall through to BYOK.
*
* Skipped when:
* - `PULLFROG_MODEL` env override is set (BYOK escape hatch)
* - `proxyModel` is not set on the run context
* - no OIDC credentials available and not talking to a localhost API
*
* Throws `BillingError` (402) or `TransientError` (503); caller renders.
*/
async function resolveProxyModel(ctx: {
payload: ResolvedPayload;
oss: boolean;
proxyModel?: string | undefined;
oidcCredentials: OidcCredentials | null;
repo: { owner: string; name: string };
}): Promise<void> {
// env override = BYOK escape hatch, don't proxy
if (process.env.PULLFROG_MODEL?.trim()) return;
if (!ctx.proxyModel) return;
// dev affordance: when talking to a localhost API, the server-side
// x-dev-repo bypass replaces OIDC verification, so a play run can
// exercise the proxy/router/oss path without GitHub Actions OIDC.
if (!ctx.oidcCredentials && !isLocalApiUrl()) {
log.warning("» proxy requested but no OIDC credentials available — skipping");
return;
}
const key = await mintProxyKey({ oidcCredentials: ctx.oidcCredentials, repo: ctx.repo });
if (!key) return;
process.env.OPENROUTER_API_KEY = key;
core.setSecret(key);
ctx.payload.proxyModel = ctx.proxyModel;
const label = ctx.oss ? "oss" : "router";
log.info(`» proxy: ${label} → ${ctx.proxyModel}`);
}
/**
* Run `resolveProxyModel`; if it throws a Billing or Transient error, render
* the user-facing summary, mirror it to the PR progress comment, and rethrow.
*
* The rethrow is intentional: these errors are terminal for the run, and
* letting them surface lets `runMain` exit non-zero so GH Actions applies
* the workflow's retry policy. We catch them *here* (before the main try)
* because the outer catch needs `toolContext` (which isn't built yet) for
* its general-purpose rendering path — a BillingError landing in the outer
* catch would get rendered with `core.setFailed` only, losing the
* actionable copy + the PR-comment mirror.
*/
export async function runProxyResolution(ctx: {
payload: ResolvedPayload;
oss: boolean;
proxyModel?: string | undefined;
oidcCredentials: OidcCredentials | null;
repo: { owner: string; name: string };
toolState: ToolState;
}): Promise<void> {
try {
await resolveProxyModel({
payload: ctx.payload,
oss: ctx.oss,
proxyModel: ctx.proxyModel,
oidcCredentials: ctx.oidcCredentials,
repo: ctx.repo,
});
} catch (error) {
if (error instanceof BillingError) {
const summary = formatBillingErrorSummary(error, ctx.repo.owner);
await writeSummary(summary).catch(() => {});
// Mirror to the PR progress comment if the trigger created one (mention /
// PR event). When the trigger is silent (IncrementalReview on
// pull_request_synchronize), no progress comment exists; fall through to
// creating a fresh issue comment so the user actually sees the
// billing-exhaustion remediation copy. Without `createIfMissing`,
// auto-reload declines on silent triggers are visible only in the GH job
// summary, which most users never open — so back-to-back pushes silently
// burn through dispatches with no PR-side signal. see #775.
await reportErrorToComment({
toolState: ctx.toolState,
error: summary,
createIfMissing: true,
}).catch(() => {});
throw error;
}
if (error instanceof TransientError) {
const summary = formatTransientErrorSummary(error, ctx.repo.owner);
await writeSummary(summary).catch(() => {});
await reportErrorToComment({
toolState: ctx.toolState,
error: summary,
createIfMissing: true,
}).catch(() => {});
throw error;
}
throw error;
}
}
utils/reviewCleanup.ts
-106
View File
@@ -1,106 +0,0 @@
import type { WriteablePayload } from "../external.ts";
import { reportReviewNodeId } from "../mcp/review.ts";
import type { ToolContext } from "../mcp/server.ts";
import { log } from "./cli.ts";
const RE_REVIEW_PREAMBLE =
"Incrementally re-review the new commits on this pull request. Use the IncrementalReview mode.";
/**
* post-agent review lifecycle: runs after the agent exits (success or timeout).
*
* normally the agent handles new commits inline: create_pull_request_review
* detects HEAD movement and tells the agent to pull and review the delta.
* this dispatch is a safety net for cases where the agent couldn't handle
* it (timeout, error, etc).
*
* ordering matters: reportReviewNodeId marks this run "done" FIRST so push
* webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
* catch any pushes that were suppressed while this run was in-flight.
*/
export async function postReviewCleanup(ctx: ToolContext): Promise<void> {
const review = ctx.toolState.review;
if (!review) return;
delete ctx.toolState.review;
// mark review as submitted — unlocks webhook dedup for new pushes
await bestEffort(() => reportReviewNodeId(ctx, { nodeId: review.nodeId }), "reportReviewNodeId");
// dispatch follow-up if PR HEAD moved past the reviewed commit
if (review.reviewedSha) {
await bestEffort(
() => dispatchFollowUpReReview(ctx, review.reviewedSha!),
"follow-up re-review dispatch"
);
}
}
async function bestEffort(fn: () => Promise<unknown>, label: string): Promise<void> {
try {
await fn();
} catch (error) {
log.debug(`${label} failed: ${error}`);
}
}
async function dispatchFollowUpReReview(ctx: ToolContext, reviewedSha: string): Promise<void> {
const issueNumber = ctx.payload.event.issue_number;
if (!issueNumber) return;
const pr = await ctx.octokit.rest.pulls.get({
owner: ctx.repo.owner,
repo: ctx.repo.name,
pull_number: issueNumber,
});
if (pr.data.head.sha === reviewedSha) return;
if (pr.data.state !== "open") return;
if (pr.data.draft) return;
log.info(
`safety net: pr HEAD moved from ${reviewedSha.slice(0, 7)} to ${pr.data.head.sha.slice(0, 7)} ` +
`and agent did not review inline — dispatching follow-up re-review`
);
const event: WriteablePayload["event"] = {
trigger: "pull_request_synchronize",
issue_number: issueNumber,
is_pr: true,
title: pr.data.title,
body: null,
branch: pr.data.head.ref,
before_sha: reviewedSha,
silent: true,
};
if (ctx.payload.event.authorPermission) {
event.authorPermission = ctx.payload.event.authorPermission;
}
const payload: WriteablePayload = {
"~pullfrog": true,
version: ctx.payload.version,
model: ctx.payload.model,
prompt: "",
eventInstructions: RE_REVIEW_PREAMBLE,
event,
};
await ctx.octokit.rest.actions.createWorkflowDispatch({
owner: ctx.repo.owner,
repo: ctx.repo.name,
workflow_id: getCurrentWorkflowFilename(),
ref: pr.data.base.repo.default_branch,
inputs: { prompt: JSON.stringify(payload) },
});
}
/**
* derive the running workflow's filename from `GITHUB_WORKFLOW_REF`, which has the form
* `<owner>/<repo>/.github/workflows/<filename>@<ref>` (e.g. `.../pullfrog.yaml@refs/heads/main`).
* falls back to `pullfrog.yml` if the env var is missing or malformed (shouldn't happen in CI).
*/
function getCurrentWorkflowFilename(): string {
const ref = process.env.GITHUB_WORKFLOW_REF ?? "";
const match = ref.match(/\/([^/]+)@/);
return match?.[1] ?? "pullfrog.yml";
}
utils/run.ts
-65
View File
@@ -1,65 +0,0 @@
import type { AgentResult } from "../agents/shared.ts";
import type { MainResult } from "../main.ts";
import type { ToolState } from "../toolState.ts";
import { log } from "./cli.ts";
import { reportErrorToComment } from "./errorReport.ts";
export interface HandleAgentResultParams {
result: AgentResult;
toolState: ToolState;
silent: boolean | undefined;
}
export async function handleAgentResult(ctx: HandleAgentResultParams): Promise<MainResult> {
if (!ctx.result.success) {
// rendering + posting for the `!success` branch lives in
// `finalizeSuccessRun` (called immediately before this function) so the
// BYOK billing-exhausted, hang, and api-key bodies land on a single
// surface — both for runs with a pre-existing progress comment AND for
// silent triggers via `createIfMissing`. see #835.
return {
success: false,
error: ctx.result.error || "Agent execution failed",
output: ctx.result.output!,
};
}
// IncrementalReview's non-substantive path exits cleanly without
// submitting any review, so no MCP write tool flips wasUpdated and the
// strict completion check below would otherwise fail the run. The
// isReviewMode skip is load-bearing for that path: the agent's exit
// code is the completion signal, not a progress-comment write.
// (Review mode that submits a real review now flips wasUpdated via
// create_pull_request_review, so the skip is redundant for the
// substantive-review path but kept for symmetry with IncrementalReview.)
// See plans/review_progress_comment_cleanup_b0120f6c.plan.md.
const mode = ctx.toolState.selectedMode;
const isReviewMode = mode === "Review" || mode === "IncrementalReview";
if (
!isReviewMode &&
!ctx.toolState.wasUpdated &&
ctx.toolState.hadProgressComment &&
!ctx.silent
) {
const error = ctx.result.error || "agent completed without reporting progress";
try {
await reportErrorToComment({
toolState: ctx.toolState,
error,
title: "Error",
});
} catch {}
return {
success: false,
error,
output: ctx.result.output || "",
};
}
log.success("Task complete.");
return {
success: true,
output: ctx.result.output || "",
};
}
utils/runContext.ts
+12 -136
View File
@@ -1,33 +1,7 @@
import type { PushPermission, ShellPermission } from "../external.ts";
import { apiFetch } from "./apiFetch.ts";
import type { RepoContext } from "./github.ts";
export interface Mode {
id: string;
name: string;
description: string;
prompt: string;
}
/**
* server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
* line numbers are 1-indexed against the raw body. computed by
* `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
* shipped over the run-context JSON boundary; the canonical declaration
* lives there. duplicated here because the action runtime can't reach
* across into the proprietary root-level codebase, and the JSON wire
* means typecheck can't enforce shape equality across both sides.
*/
export interface LearningsHeading {
depth: 1 | 2 | 3 | 4 | 5 | 6;
title: string;
startLine: number;
endLine: number;
}
export interface RepoSettings {
model: string | null;
modes: Mode[];
setupScript: string | null;
postCheckoutScript: string | null;
prepushScript: string | null;
@@ -36,116 +10,18 @@ export interface RepoSettings {
shell: ShellPermission;
prApproveEnabled: boolean;
modeInstructions: Record<string, string>;
learnings: string | null;
learningsHeadings: LearningsHeading[];
envAllowlist: string | null;
}
/**
* Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors
* the server's `AccountPlan` in `utils/billing.ts`. `"none"` = free tier,
* `"payg"` = card on file / pay-as-you-go.
*/
export type AccountPlan = "none" | "payg";
export interface RunContext {
settings: RepoSettings;
apiToken: string;
oss: boolean;
plan: AccountPlan;
proxyModel?: string | undefined;
dbSecrets?: Record<string, string> | undefined;
}
const defaultSettings: RepoSettings = {
model: null,
modes: [],
setupScript: null,
postCheckoutScript: null,
prepushScript: null,
stopScript: null,
push: "restricted",
shell: "restricted",
prApproveEnabled: false,
modeInstructions: {},
learnings: null,
learningsHeadings: [],
envAllowlist: null,
};
const defaultRunContext: RunContext = {
settings: defaultSettings,
apiToken: "",
oss: false,
plan: "none",
};
/**
* fetch run context from Pullfrog API
* returns settings + API token for subsequent calls
* returns defaults if fetch fails
*/
export async function fetchRunContext(params: {
token: string;
repoContext: RepoContext;
oidcToken?: string | undefined;
}): Promise<RunContext> {
const timeoutMs = 30000;
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
try {
const headers: Record<string, string> = {
Authorization: `Bearer ${params.token}`,
};
if (params.oidcToken) {
headers["X-GitHub-OIDC-Token"] = params.oidcToken;
}
const response = await apiFetch({
path: `/api/repo/${params.repoContext.owner}/${params.repoContext.name}/run-context`,
headers,
signal: controller.signal,
});
clearTimeout(timeoutId);
if (!response.ok) {
return defaultRunContext;
}
const data = (await response.json()) as {
settings: RepoSettings | null;
apiToken: string;
oss?: boolean;
plan?: AccountPlan;
proxyModel?: string;
dbSecrets?: Record<string, string>;
} | null;
if (data === null) {
return defaultRunContext;
}
return {
settings: {
...defaultSettings,
...data.settings,
modes: data.settings?.modes ?? [],
setupScript: data.settings?.setupScript ?? null,
postCheckoutScript: data.settings?.postCheckoutScript ?? null,
prepushScript: data.settings?.prepushScript ?? null,
stopScript: data.settings?.stopScript ?? null,
learningsHeadings: data.settings?.learningsHeadings ?? [],
},
apiToken: data.apiToken,
oss: data.oss ?? false,
plan: data.plan ?? "none",
proxyModel: data.proxyModel,
dbSecrets: data.dbSecrets,
};
} catch {
clearTimeout(timeoutId);
return defaultRunContext;
}
export function defaultRepoSettings(): RepoSettings {
return {
model: null,
setupScript: null,
postCheckoutScript: null,
prepushScript: null,
stopScript: null,
push: "restricted",
shell: "restricted",
prApproveEnabled: false,
modeInstructions: {},
};
}
utils/runContextData.ts
-62
View File
@@ -1,62 +0,0 @@
import * as core from "@actions/core";
import type { Octokit } from "@octokit/rest";
import packageJson from "../package.json" with { type: "json" };
import { log } from "./cli.ts";
import { type OctokitWithPlugins, parseRepoContext } from "./github.ts";
import { type AccountPlan, fetchRunContext, type RepoSettings } from "./runContext.ts";
export interface RunContextData {
repo: {
owner: string;
name: string;
data: Awaited<ReturnType<Octokit["repos"]["get"]>>["data"];
};
repoSettings: RepoSettings;
apiToken: string;
oss: boolean;
plan: AccountPlan;
proxyModel?: string | undefined;
dbSecrets?: Record<string, string> | undefined;
}
interface ResolveRunContextDataParams {
octokit: OctokitWithPlugins;
token: string;
}
/**
* initialize run context data: parse context, fetch repo info and settings
*/
export async function resolveRunContextData(
params: ResolveRunContextDataParams
): Promise<RunContextData> {
log.info(`» running Pullfrog v${packageJson.version}...`);
const repoContext = parseRepoContext();
let oidcToken: string | undefined;
try {
oidcToken = await core.getIDToken("pullfrog-api");
} catch {
// OIDC not available (local dev, non-actions environment, fork PRs)
}
const [repoResponse, runContext] = await Promise.all([
params.octokit.repos.get({ owner: repoContext.owner, repo: repoContext.name }),
fetchRunContext({ token: params.token, repoContext, oidcToken }),
]);
return {
repo: {
owner: repoContext.owner,
name: repoContext.name,
data: repoResponse.data,
},
repoSettings: runContext.settings,
apiToken: runContext.apiToken,
oss: runContext.oss,
plan: runContext.plan,
proxyModel: runContext.proxyModel,
dbSecrets: runContext.dbSecrets,
};
}
utils/runErrorRenderer.test.ts
-95
View File
@@ -1,95 +0,0 @@
import { describe, expect, it } from "vitest";
import { renderRunError } from "./runErrorRenderer.ts";
const repo = { owner: "acme", name: "widget" };
describe("renderRunError BYOK provider billing exhausted (#835)", () => {
const deepseekRaw =
'» provider error detected (provider billing exhausted): ERROR providerID=deepseek modelID=deepseek-v4-pro error={"name":"AI_APICallError","message":"Insufficient Balance"}';
const anthropicRaw =
"APIError: Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.";
const opencodeZenRaw = "CreditsError: account out of free usage";
it("renders DeepSeek billing-exhausted with provider-specific dashboard link", () => {
const result = renderRunError({
errorMessage: deepseekRaw,
repo,
agentDiagnostic: undefined,
});
expect(result.summary).toContain("`deepseek` account is out of credit");
expect(result.summary).toContain("https://platform.deepseek.com/top_up");
expect(result.summary).toContain("### ❌ Pullfrog failed");
expect(result.comment).toContain("`deepseek` account is out of credit");
expect(result.comment).not.toContain("### ❌ Pullfrog failed");
});
it("matches Anthropic 'credit balance is too low' (#835 Anthropic case)", () => {
const result = renderRunError({
errorMessage: anthropicRaw,
repo,
agentDiagnostic: undefined,
});
expect(result.comment).toContain("out of credit");
});
it("matches OpenCode Zen CreditsError shape", () => {
const result = renderRunError({
errorMessage: opencodeZenRaw,
repo,
agentDiagnostic: undefined,
});
expect(result.comment).toContain("out of credit");
});
it("falls through to a generic CTA when providerID cannot be parsed", () => {
const result = renderRunError({
errorMessage: "Insufficient balance — provider response with no providerID tag",
repo,
agentDiagnostic: undefined,
});
expect(result.comment).toContain("Your provider account is out of credit");
expect(result.comment).not.toContain("Your your");
expect(result.comment).toContain("Top up your provider account");
});
});
describe("renderRunError ProviderModelNotFoundError (#816)", () => {
const staleFreeRaw =
'ProviderModelNotFoundError: {"providerID":"opencode","modelID":"retired-free-model","suggestions":["deepseek-v4-flash-free"]}';
const bigPickleRaw =
'ProviderModelNotFoundError: {"providerID":"opencode","modelID":"big-pickle","suggestions":[]}';
it("renders actionable copy for a stale free fallback model id", () => {
const result = renderRunError({
errorMessage: staleFreeRaw,
repo,
agentDiagnostic: undefined,
});
expect(result.summary).toContain("Pullfrog's free fallback model is no longer available");
expect(result.summary).toContain("`acme/widget`");
expect(result.summary).toContain("retired-free-model");
expect(result.comment).toBe(result.summary);
});
it("renders the same classifier when big-pickle is missing from opencode catalog", () => {
const result = renderRunError({
errorMessage: bigPickleRaw,
repo,
agentDiagnostic: undefined,
});
expect(result.summary).toContain("Pullfrog's free fallback model is no longer available");
expect(result.summary).toContain("big-pickle");
});
it("does not misclassify unrelated failures as fallback-catalog errors", () => {
const result = renderRunError({
errorMessage: "activity timeout after 900s",
repo,
agentDiagnostic: undefined,
});
expect(result.summary).not.toContain("free fallback model is no longer available");
});
});
utils/runErrorRenderer.ts
-211
View File
@@ -1,211 +0,0 @@
/**
* Classify + render the error thrown out of the main run try-block into a
* pair of user-facing markdown bodies — one for the GitHub Actions job
* summary tab, one for the PR progress comment.
*
* Classifications, in dispatch order (first match wins; the api-key
* branch additionally folds in the activity-timeout hang body as a
* sub-source so a hang masking an api-key error still surfaces the api-key
* CTA):
*
* 1. `BillingError` — either the proxy-token mint already threw one (402
* handled inline) or the agent runtime surfaced an OpenRouter
* "key budget exhausted" string mid-run. Both render via
* `formatBillingErrorSummary` so the user sees actionable copy.
*
* 2. BYOK provider billing-exhausted (#835) — DeepSeek "Insufficient
* Balance", Anthropic "credit balance is too low", OpenCode Zen
* `CreditsError`, Gemini "spending cap". Checked before api-key auth
* because billing-exhausted responses often carry 401 status codes
* that `isApiKeyAuthError` would otherwise mis-classify.
*
* 3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string
* (or the activity-timeout hang body when present, since that's where
* the underlying provider error often lands); `formatApiKeyErrorSummary`
* renders provider + console-link copy.
*
* 4. ProviderModelNotFoundError — stale free-fallback model id no longer
* in the OpenCode catalog; renders a nudge to add a BYOK key.
*
* 5. Activity-timeout hang — `errorMessage` starts with
* `"activity timeout"` or `"agent still pending"` AND none of the
* above matched. The harness keeps structured diagnostic state on
* `toolState.agentDiagnostic`; `formatAgentHangBody` renders that as
* a markdown block.
*
* 6. Default — a generic `❌ Pullfrog failed` block with the raw error
* message in a fenced code block. Same body for both surfaces.
*
* The hang body and the API-key body diverge between the two surfaces only
* in that the job summary wraps them in the `### ❌ Pullfrog failed` H3
* banner; the PR comment uses the bare body since it already has Pullfrog
* branding in its footer.
*/
import type { AgentDiagnostic } from "./agentHangReport.ts";
import { formatAgentHangBody } from "./agentHangReport.ts";
import { formatApiKeyErrorSummary, isApiKeyAuthError } from "./apiKeys.ts";
import { BillingError, formatBillingErrorSummary } from "./billingErrors.ts";
import {
extractProviderId,
isProviderBillingExhausted,
isRouterKeylimitExhaustedError,
} from "./providerErrors.ts";
export type RenderedRunError = {
summary: string;
comment: string;
};
function isProviderModelNotFoundError(message: string): boolean {
return message.includes("ProviderModelNotFoundError");
}
/**
* Best-known billing top-up URL per provider. Conservative list: only
* providers we've actually classified billing-exhaustion shapes for in
* `providerErrors.ts`. Unknown providers fall through to a generic CTA.
*/
const PROVIDER_BILLING_URLS: Record<string, string> = {
deepseek: "https://platform.deepseek.com/top_up",
anthropic: "https://console.anthropic.com/settings/billing",
openai: "https://platform.openai.com/account/billing",
google: "https://aistudio.google.com/usage",
opencode: "https://opencode.ai/zen",
};
/**
* `extractProviderId` only fires when the harness emits `providerID=...`
* (OpenCode log shape). Direct-provider errors (e.g. Anthropic SDK throwing
* `"Your credit balance is too low to access the Anthropic API"`) carry no
* such tag, so map their distinctive copy to a provider id here so the
* dashboard link is reachable.
*
* Pattern is intentionally tight (Anthropic-specific phrasing only) to
* avoid mis-tagging non-Anthropic billing-exhausted errors that happen to
* mention `"Anthropic API"` in passing — the broader phrase appears in
* fallback-chain agent prompt text and OpenCode harness logs.
*/
function detectProviderId(message: string): string | null {
const harnessId = extractProviderId(message);
if (harnessId) return harnessId;
if (/credit balance is too low/i.test(message)) return "anthropic";
return null;
}
function formatProviderBillingExhausted(input: { errorMessage: string }): string {
const providerId = detectProviderId(input.errorMessage);
const dashboardUrl = providerId ? PROVIDER_BILLING_URLS[providerId] : undefined;
const headline = providerId
? `**Your \`${providerId}\` account is out of credit.**`
: "**Your provider account is out of credit.**";
const cta = dashboardUrl
? `[Top up \`${providerId}\` →](${dashboardUrl})`
: "Top up your provider account, then re-trigger Pullfrog.";
return [
headline,
"",
"Pullfrog detected a billing-exhausted response from your provider — the agent stopped before completing this run.",
"",
cta,
"",
`\`\`\`\n${input.errorMessage}\n\`\`\``,
].join("\n");
}
function formatProviderModelNotFoundSummary(input: {
owner: string;
name: string;
raw: string;
}): string {
return (
`Pullfrog's free fallback model is no longer available in OpenCode's catalog. ` +
`Add an API key for your configured model in the Pullfrog console for \`${input.owner}/${input.name}\`, ` +
`or contact support if this persists.\n\n` +
`\`\`\`\n${input.raw}\n\`\`\``
);
}
export function renderRunError(input: {
errorMessage: string;
repo: { owner: string; name: string };
agentDiagnostic: AgentDiagnostic | undefined;
}): RenderedRunError {
// reclassify mid-run OpenRouter "key budget exhausted" as BillingError so
// the user gets the same actionable copy as a /api/proxy-token 402.
const billingError = isRouterKeylimitExhaustedError(input.errorMessage)
? new BillingError(input.errorMessage, { code: "router_keylimit_exhausted" })
: null;
if (billingError) {
const body = formatBillingErrorSummary(billingError, input.repo.owner);
return { summary: body, comment: body };
}
// gated on isHang because the harness sets `agentDiagnostic` on entry, so
// any non-hang throw that hits the outer catch (e.g. post-success
// output_schema validator, or a late cleanup throw after the run already
// succeeded) would otherwise render "Pullfrog failed" with stale event
// counts and silently drop the real errorMessage.
const isHang =
input.errorMessage.startsWith("activity timeout") ||
input.errorMessage.startsWith("agent still pending");
const hangBody = isHang
? formatAgentHangBody({
diagnostic: input.agentDiagnostic,
isHang: true,
errorMessage: input.errorMessage,
})
: null;
// BYOK provider billing-exhausted (DeepSeek "Insufficient Balance",
// Anthropic "credit balance is too low", OpenCode Zen `CreditsError` /
// `FreeUsageLimitError`, Gemini "spending cap"). distinct from the Router
// billing branches above — Router uses `BillingError`, this uses the agent
// log payload classified by `isProviderBillingExhausted`. see #835.
//
// checked BEFORE api-key auth: providers commonly return 401 (DeepSeek,
// Gemini) or include `"API Error: 401"` in the error body for billing
// exhaustion, which `isApiKeyAuthError` would otherwise match — surfacing
// a "rotate your key" CTA when the actual fix is "top up credits".
if (isProviderBillingExhausted(input.errorMessage)) {
const body = formatProviderBillingExhausted({ errorMessage: input.errorMessage });
return { summary: `### ❌ Pullfrog failed\n\n${body}`, comment: body };
}
const apiKeySource = hangBody ?? input.errorMessage;
const apiKeyErrorSummary = isApiKeyAuthError(apiKeySource)
? formatApiKeyErrorSummary({
owner: input.repo.owner,
name: input.repo.name,
raw: apiKeySource,
})
: null;
if (apiKeyErrorSummary) {
return { summary: apiKeyErrorSummary, comment: apiKeyErrorSummary };
}
if (isProviderModelNotFoundError(input.errorMessage)) {
const body = formatProviderModelNotFoundSummary({
owner: input.repo.owner,
name: input.repo.name,
raw: input.errorMessage,
});
return { summary: body, comment: body };
}
if (hangBody) {
return {
summary: `### ❌ Pullfrog failed\n\n${hangBody}`,
comment: hangBody,
};
}
return {
summary: `### ❌ Pullfrog failed\n\n\`\`\`\n${input.errorMessage}\n\`\`\``,
comment: input.errorMessage,
};
}
utils/runFixture.ts
-76
View File
@@ -1,76 +0,0 @@
// in-process fixture runner used by `play.ts` (and any future host-side
// runner). does NOT know about Docker — that's `docker.ts`'s job. when run
// inside the local docker container, this is what executes after the entrypoint.
import { execSync } from "node:child_process";
import { mkdtemp } from "node:fs/promises";
import { devNull, tmpdir } from "node:os";
import { join } from "node:path";
import type { AgentResult } from "../agents/shared.ts";
import { type Inputs, main } from "../main.ts";
import { log } from "./cli.ts";
import { ensureGitHubToken } from "./github.ts";
import { setupTestRepo } from "./setup.ts";
export async function run(inputsOrPrompt: Inputs | string): Promise<AgentResult> {
await ensureGitHubToken();
// play.ts is a CI-emulator — isolate it from the developer's user- and
// system-scope gitconfig so checks like `validatePushDestination` see the
// raw stored remote URL instead of values mutated by `url.*.insteadOf`
// rewrites (a common SSH-auth convenience on dev boxes). CI runners have
// empty gitconfigs so this is a no-op there; locally it makes `pnpm play`
// and real runs produce identical git state. `os.devNull` canonicalizes
// the null device across Unix (`/dev/null`) and Windows (`\\.\nul`).
process.env.GIT_CONFIG_GLOBAL = devNull;
process.env.GIT_CONFIG_SYSTEM = devNull;
const tempParent = await mkdtemp(join(tmpdir(), "pullfrog-play-"));
const tempDir = join(tempParent, "repo");
const originalCwd = process.cwd();
try {
setupTestRepo({ tempDir });
process.chdir(tempDir);
// optional pre-agent setup (e.g. seed symlinks for adversarial fixtures).
if (process.env.PULLFROG_TEST_REPO_SETUP) {
log.info("» running repo setup commands...");
execSync(process.env.PULLFROG_TEST_REPO_SETUP, { cwd: tempDir, stdio: "pipe" });
}
// tell main() to use the cloned tempDir instead of the GHA workspace path.
process.env.GITHUB_WORKSPACE = tempDir;
const inputs: Inputs =
typeof inputsOrPrompt === "string" ? { prompt: inputsOrPrompt } : inputsOrPrompt;
for (const [key, value] of Object.entries(inputs)) {
if (value !== undefined && value !== null) {
process.env[`INPUT_${key.toUpperCase()}`] = String(value);
}
}
const result: AgentResult = await main();
process.chdir(originalCwd);
if (result.success) {
log.success("Action completed successfully");
return { success: true, output: result.output || undefined, error: undefined };
}
log.error(`Action failed: ${result.error || "Unknown error"}`);
return { success: false, error: result.error || undefined, output: undefined };
} catch (err) {
const errorMessage = (err as Error).message;
log.error(`Error: ${errorMessage}`);
return { success: false, error: errorMessage, output: undefined };
} finally {
process.chdir(originalCwd);
// sandbox isolation may create files with non-host ownership; rmSync
// can't always delete those, so escalate.
try {
execSync(`sudo rm -rf "${tempParent}"`, { stdio: "ignore" });
} catch {
// best-effort cleanup.
}
}
}
utils/runLifecycle.ts
-182
View File
@@ -1,182 +0,0 @@
/**
* End-of-run cleanup phases extracted out of `main.ts`. Three shapes:
*
* - `persistRunArtifacts`: best-effort post-review cleanup + summary +
* learnings persistence. Shared by both the success path and the
* error-catch path; idempotent (each step has its own guard against
* double-execution).
*
* - `finalizeSuccessRun`: success-only — calls `persistRunArtifacts`
* first, then surfaces harness-side failures in the progress comment,
* deletes stranded progress comments, writes the GitHub Actions job
* summary, and emits the structured output marker.
*
* - `writeRunErrorOutputs`: error-only — writes the rendered error
* summary to the Actions summary tab and mirrors it to the PR
* progress comment. The catch path calls this and then
* `persistRunArtifacts` separately so the rendered error lands before
* the persistence calls, in case the latter throw.
*
* All three swallow their own non-fatal errors (`log.debug` or empty
* `catch {}`) so a cleanup failure can't flip an already-decided run
* outcome.
*/
import * as core from "@actions/core";
import type { AgentResult } from "../agents/shared.ts";
import { deleteProgressComment } from "../mcp/comment.ts";
import type { ToolContext } from "../mcp/server.ts";
import type { ToolState } from "../toolState.ts";
import { formatUsageSummary, log, writeSummary } from "./cli.ts";
import { reportErrorToComment } from "./errorReport.ts";
import { persistLearnings } from "./learnings.ts";
import { persistSummary } from "./prSummary.ts";
import { postReviewCleanup } from "./reviewCleanup.ts";
import { type RenderedRunError, renderRunError } from "./runErrorRenderer.ts";
/**
* Best-effort cleanup shared by both run-end paths:
* 1. post-review cleanup (dispatch follow-up re-review on submitted reviews)
* 2. persist the agent-edited PR summary tmpfile
* 3. persist the agent-edited repo-level learnings tmpfile
*
* Each step is idempotent and swallows its own errors. Safe to call from
* both `main()`'s success path and its catch path.
*/
export async function persistRunArtifacts(toolContext: ToolContext): Promise<void> {
await postReviewCleanup(toolContext).catch((error) => {
log.debug(`post-review cleanup failed: ${error}`);
});
await persistSummary(toolContext);
await persistLearnings(toolContext);
}
/**
* Run the success-path cleanup waterfall:
*
* 1. shared best-effort cleanup via `persistRunArtifacts`
* 2. when the harness returned `success=false` (e.g. unsubmitted-review
* gate exhausted retries, stop-hook persistently failing), render via
* `renderRunError` and surface the error in BOTH the progress comment
* (rendered.comment) and the Actions job summary (rendered.summary,
* prepended below in step 4) — same classifier as the catch path so
* the user sees it instead of a deleted-comment void / empty summary
* tab
* 3. when the run succeeded and the progress comment was never finalized
* via `report_progress`, delete it (three sub-cases — orphan
* "Leaping into action" comment, abandoned checklist, agent wrote
* a substantive artifact via another MCP write tool but skipped
* report_progress)
* 4. write the GitHub Actions step summary (best-effort — a write
* failure must not throw past this point because we'd hit the outer
* catch and clobber any progress comment we just wrote)
* 5. emit the structured output marker for tests + workflow consumers
*/
export async function finalizeSuccessRun(input: {
toolContext: ToolContext;
toolState: ToolState;
result: AgentResult;
repo: { owner: string; name: string };
}): Promise<void> {
await persistRunArtifacts(input.toolContext);
// shared rendering for the !success branch — same classifier as the
// outer catch path (BillingError reclassify → hang → BYOK billing →
// api-key → generic), so a harness-returned `{success: false}` lands an
// actionable error block in the job summary alongside the matching body
// in the progress comment. hang and generic get the `### ❌ Pullfrog
// failed` H3 banner; BillingError, BYOK billing, and api-key render
// their own provider-specific framing (no banner). renders once; reused
// for both surfaces below.
const rendered = !input.result.success
? renderRunError({
errorMessage: input.result.error || "agent run failed",
repo: input.repo,
agentDiagnostic: input.toolState.agentDiagnostic,
})
: null;
// `createIfMissing: true` is load-bearing for silent triggers
// (IncrementalReview / pull_request_synchronize / auto-label) that have
// no progress comment to update — without it, terminal failures like
// BYOK billing exhaustion land only in the GH job summary, which most
// users never open. `reportErrorToComment` no-ops when both progress
// comment AND issue context are absent. see #835.
if (rendered) {
await reportErrorToComment({
toolState: input.toolState,
error: rendered.comment,
createIfMissing: true,
}).catch((error) => {
log.debug(`failure error report failed: ${error}`);
});
}
// create_pull_request_review owns its own deletion (see mcp/review.ts), so
// progressComment is already null by the time we get here for that path.
// uses finalSummaryWritten (not todoTracker.enabled or wasUpdated) so
// cleanup survives API failures in report_progress where cancel() ran but
// the write didn't succeed, and isn't fooled by writes to *other* artifacts.
if (
input.result.success &&
input.toolState.progressComment &&
!input.toolState.finalSummaryWritten
) {
await deleteProgressComment(input.toolContext).catch((error) => {
log.debug(`stranded progress comment cleanup failed: ${error}`);
});
}
try {
const usageSummary = formatUsageSummary(input.toolState.usageEntries);
const body = input.toolState.lastProgressBody || input.result.output;
const parts = [rendered?.summary, body, usageSummary].filter(Boolean);
if (parts.length > 0) {
await writeSummary(parts.join("\n\n"));
}
} catch (error) {
log.debug(`job summary write failed: ${error}`);
}
if (input.toolState.output) {
log.info(`::pullfrog-output::${Buffer.from(input.toolState.output).toString("base64")}`);
core.setOutput("result", input.toolState.output);
}
}
/**
* Write the rendered error to the GitHub Actions job summary tab + mirror
* to the PR progress comment when one exists. Catch path only.
*
* `lastProgressBody` and the usage table are appended to the summary so the
* partial work the agent did before failing isn't lost.
*
* `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
* triggers (IncrementalReview / pull_request_synchronize / auto-label) that
* throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
* mid-billing-exhausted-retry) reach this catch path with no progress
* comment to update, and without `createIfMissing` the terminal error
* lands only in the GH job summary that most users never open. see #835.
*/
export async function writeRunErrorOutputs(input: {
rendered: RenderedRunError;
toolState: ToolState;
}): Promise<void> {
try {
const usageSummary = formatUsageSummary(input.toolState.usageEntries);
const parts = [input.rendered.summary, input.toolState.lastProgressBody, usageSummary].filter(
Boolean
);
await writeSummary(parts.join("\n\n"));
} catch {}
try {
await reportErrorToComment({
toolState: input.toolState,
error: input.rendered.comment,
createIfMissing: true,
});
} catch {
// error reporting failed, but don't let it mask the original error
}
}
utils/runStartupLog.ts
-61
View File
@@ -1,61 +0,0 @@
/**
* Startup log formatting for the resolver pipeline. Computes the
* "model / agent / push / shell / timeout" block that main.ts prints
* after resolving the agent + model + payload.
*/
import { log } from "./cli.ts";
import type { ResolvedPayload } from "./payload.ts";
import { TIMEOUT_DISABLED } from "./time.ts";
function resolveTimeoutForLog(timeout: string | undefined): string {
if (!timeout) return "1h (default)";
if (timeout === TIMEOUT_DISABLED) return "none (disabled)";
return timeout;
}
function resolveModelForLog(ctx: {
payload: ResolvedPayload;
resolvedModel: string | undefined;
}): string {
const envModel = process.env.PULLFROG_MODEL?.trim();
if (envModel) return `${envModel} (override via PULLFROG_MODEL)`;
if (ctx.payload.proxyModel) return `${ctx.payload.proxyModel} (proxy)`;
if (ctx.resolvedModel && ctx.payload.model && ctx.payload.model !== ctx.resolvedModel) {
return `${ctx.resolvedModel} (resolved from ${ctx.payload.model})`;
}
if (ctx.resolvedModel) return ctx.resolvedModel;
if (ctx.payload.model) return `${ctx.payload.model} (unresolved)`;
return "auto";
}
function resolveAgentForLog(ctx: { agentName: string; resolvedModel: string | undefined }): string {
const envAgent = process.env.PULLFROG_AGENT?.trim();
if (envAgent && envAgent === ctx.agentName) {
return `${ctx.agentName} (override via PULLFROG_AGENT)`;
}
if (ctx.agentName === "claude" && ctx.resolvedModel) {
return `${ctx.agentName} (auto-selected for ${ctx.resolvedModel})`;
}
return ctx.agentName;
}
/**
* Emit the startup block ("» model / agent / push / shell / timeout") after
* the agent and model are resolved. Single side-effect; no return.
*/
export function logRunStartup(ctx: {
payload: ResolvedPayload;
resolvedModel: string | undefined;
agentName: string;
}): void {
log.info(
`» model: ${resolveModelForLog({ payload: ctx.payload, resolvedModel: ctx.resolvedModel })}`
);
log.info(
`» agent: ${resolveAgentForLog({ agentName: ctx.agentName, resolvedModel: ctx.resolvedModel })}`
);
log.info(`» push: ${ctx.payload.push}`);
log.info(`» shell: ${ctx.payload.shell}`);
log.info(`» timeout: ${resolveTimeoutForLog(ctx.payload.timeout)}`);
}
utils/setup.ts
+31 -147
View File
@@ -5,7 +5,7 @@ import { join } from "node:path";
import type { ShellPermission } from "../external.ts";
import type { ToolState } from "../toolState.ts";
import { log } from "./cli.ts";
import type { OctokitWithPlugins } from "./github.ts";
import type { Gitea } from "./gitea.ts";
import { isInsideDocker } from "./globals.ts";
import { $ } from "./shell.ts";
@@ -13,41 +13,15 @@ export interface SetupOptions {
tempDir: string;
}
/**
* Create a shared temp directory for the action
*/
export function createTempDirectory(): string {
const sharedTempDir = mkdtempSync(join(tmpdir(), "pullfrog-"));
const sharedTempDir = mkdtempSync(join(tmpdir(), "shockbot-"));
process.env.SHOCKBOT_TEMP_DIR = sharedTempDir;
// also set PULLFROG_TEMP_DIR for compatibility with files that haven't been updated
process.env.PULLFROG_TEMP_DIR = sharedTempDir;
log.info(`» created temp dir at ${sharedTempDir}`);
return sharedTempDir;
}
/**
* snapshot-and-delete the GHA runner's known credential leak surfaces inside
* `$RUNNER_TEMP` before the agent spawns. without this, a shell-capable agent
* can grep:
* - `_runner_file_commands/set_output_*` for `core.setOutput('token', ghs_…)`
* calls made by earlier composite-action steps (e.g.
* pullfrog/pullfrog/get-installation-token);
* - `<uuid>.sh` rendered step scripts whose `run: |` body embeds
* `${{ steps.token.outputs.token }}` literally (GHA expands BEFORE writing);
* - `git-credentials-*.config` written by `actions/checkout@v6` for the
* workflow GITHUB_TOKEN.
*
* the running bash process already has its own `.sh` open via fd, so the
* unlink is safe — `unlink` removes the dirent, the kernel keeps reading.
*
* preserves every `_runner_file_commands/` file path the runner pre-allocated
* for OUR step — `$GITHUB_OUTPUT`, `$GITHUB_ENV`, `$GITHUB_PATH`,
* `$GITHUB_STATE`, `$GITHUB_STEP_SUMMARY`. those are read by the runner
* AFTER we exit (or by our own `post:` hook), and wiping them would break
* pullfrog's `result` output, `post:` state handoff, and job summary.
*
* silent no-op when `$RUNNER_TEMP` is unset (local dev, `pnpm play`).
* per-file errors are tolerated — the runner may delete files between
* our readdir and our unlink.
*/
export function wipeRunnerLeakSurface(): void {
const runnerTemp = process.env.RUNNER_TEMP;
if (!runnerTemp) return;
@@ -65,7 +39,6 @@ export function wipeRunnerLeakSurface(): void {
try {
preserve.add(realpathSync(path));
} catch {
// path may not exist yet — preserve the literal in case it gets created later
preserve.add(path);
}
}
@@ -76,16 +49,12 @@ export function wipeRunnerLeakSurface(): void {
let resolved = path;
try {
resolved = realpathSync(path);
} catch {
// file may already be gone — fall through to unlink for the race-tolerant path
}
} catch {}
if (preserve.has(resolved) || preserve.has(path)) return;
try {
unlinkSync(path);
wiped.push(path);
} catch {
// race-tolerant: file may have been deleted between readdir and unlink
}
} catch {}
};
const listDir = (dir: string): string[] => {
@@ -113,35 +82,6 @@ export function wipeRunnerLeakSurface(): void {
}
}
/**
* Setup the test repository for running actions
*/
export function setupTestRepo(options: SetupOptions): void {
const tempDir = options.tempDir;
const repo = process.env.GITHUB_REPOSITORY;
if (!repo) throw new Error("GITHUB_REPOSITORY is required");
log.info(`» cloning ${repo} into ${tempDir}...`);
// use https with token in ci or when running inside docker
if (process.env.CI || isInsideDocker) {
const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
if (!token) {
throw new Error("GITHUB_TOKEN or GH_TOKEN is required for https clone in ci or docker");
}
$("git", ["clone", `https://x-access-token:${token}@github.com/${repo}.git`, tempDir]);
} else {
$("git", ["clone", `git@github.com:${repo}.git`, tempDir]);
}
}
/**
* build an env suitable for targeting a specific git repo via `cwd`.
*
* inherited GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE override cwd resolution,
* which matters when this code runs as a child of `git push` (pre-push hook)
* or inside another git subcommand. if we don't strip them, a call that
* names `repoDir` in cwd silently operates on the outer repo instead.
*/
function envScopedToRepo(): NodeJS.ProcessEnv {
const scoped = { ...process.env };
for (const key of Object.keys(scoped)) {
@@ -150,18 +90,6 @@ function envScopedToRepo(): NodeJS.ProcessEnv {
return scoped;
}
/**
* remove any `[includeIf ...]` entries from the local git config so that
* actions/checkout-persisted credentials don't ride alongside ASKPASS-provided
* auth for subsequent git operations.
*
* SECURITY: git config subsection values can contain arbitrary characters
* including `$(...)` command substitutions, and `${IFS}` spacing tricks defeat
* naive split-on-space filtering. we read keys via the `-z` (null-terminated)
* output format and feed them to a spawn-array `git config --unset-all` so
* the shell never interpolates key contents — closing the RCE path that a
* string-interpolated `execSync(...)` would expose.
*/
export function removeIncludeIfEntries(repoDir: string): void {
const env = envScopedToRepo();
let configOutput: string;
@@ -179,16 +107,11 @@ export function removeIncludeIfEntries(repoDir: string): void {
const seen = new Set<string>();
for (const entry of configOutput.split("\0")) {
if (!entry) continue;
// -z format: each entry is "<key>\n<value>". the key is up to the first newline.
const nl = entry.indexOf("\n");
const key = nl === -1 ? entry : entry.slice(0, nl);
if (!key || seen.has(key)) continue;
seen.add(key);
try {
// execFileSync (not execSync) so the key — which can contain arbitrary
// characters including shell metacharacters and $() command substitutions
// — is passed as an argv element and never interpolated by a shell.
// this is the load-bearing side of a9aa3b2b's injection fix.
execFileSync("git", ["config", "--local", "--unset-all", key], {
cwd: repoDir,
stdio: "pipe",
@@ -210,33 +133,19 @@ export interface GitContext {
gitToken: string;
owner: string;
name: string;
octokit: OctokitWithPlugins;
gitea: Gitea;
toolState: ToolState;
// shell permission level — controls hook and security behavior:
// enabled: full shell, hooks run, no restrictions
// restricted: MCP shell in stripped env, hooks run, token protection on auth ops
// disabled: no shell, hooks disabled globally, all code execution paths blocked
shell: ShellPermission;
postCheckoutScript: string | null;
}
export type SetupGitParams = GitContext;
/**
* setup git configuration and authentication for the repository.
* - configures git identity (user.email, user.name)
* - sets up authentication via gitToken (minimal contents:write)
*
* gitToken is a minimal-permission token (contents + workflows) used for git operations.
* it is assumed to be potentially exfiltratable, so it has limited scope.
*/
export async function setupGit(params: SetupGitParams): Promise<void> {
const repoDir = process.cwd();
// 1. configure git identity
log.info("» setting up git configuration...");
try {
// check current config - only set defaults if not configured or using generic bot
let currentEmail = "";
try {
currentEmail = execSync("git config user.email", {
@@ -244,31 +153,27 @@ export async function setupGit(params: SetupGitParams): Promise<void> {
stdio: "pipe",
encoding: "utf-8",
}).trim();
} catch {
// not configured
}
} catch {}
const shouldSetDefaults =
!currentEmail || currentEmail === "github-actions[bot]@users.noreply.github.com";
!currentEmail ||
currentEmail.includes("github-actions") ||
currentEmail.includes("pullfrog");
if (shouldSetDefaults) {
execSync('git config --local user.email "226033991+pullfrog[bot]@users.noreply.github.com"', {
execSync('git config --local user.email "shockbot@git.shockvpn.com"', {
cwd: repoDir,
stdio: "pipe",
});
execSync('git config --local user.name "pullfrog[bot]"', {
execSync('git config --local user.name "shockbot"', {
cwd: repoDir,
stdio: "pipe",
});
log.debug("» git user configured (using defaults)");
log.debug("» git user configured (shockbot defaults)");
} else {
log.debug(`» git user already configured (${currentEmail}), skipping`);
}
// SECURITY: disable git hooks when shell is disabled to prevent code execution.
// in restricted mode, hooks run in the stripped sandbox — that's fine.
// in enabled mode, the agent has full shell anyway.
// in disabled mode, hooks are the primary code-execution escape vector.
if (params.shell === "disabled") {
execSync("git config --local core.hooksPath /dev/null", {
cwd: repoDir,
@@ -277,59 +182,40 @@ export async function setupGit(params: SetupGitParams): Promise<void> {
log.debug("» git hooks disabled (shell=disabled)");
}
} catch (error) {
// If git config fails, log warning but don't fail the action
// This can happen if we're not in a git repo or git isn't available
log.info(`Failed to set git config: ${error instanceof Error ? error.message : String(error)}`);
}
// 2. setup authentication
// remove existing git auth headers that actions/checkout might have set
try {
execSync("git config --local --unset-all http.https://github.com/.extraheader", {
cwd: repoDir,
stdio: "pipe",
});
log.info("» removed existing authentication headers");
} catch {
log.debug("» no existing authentication headers to remove");
// Remove credential helpers set by actions/checkout
for (const header of [
"http.https://github.com/.extraheader",
"http.https://git.shockvpn.com/.extraheader",
]) {
try {
execSync(`git config --local --unset-all ${header}`, {
cwd: repoDir,
stdio: "pipe",
});
log.info(`» removed existing authentication headers (${header})`);
} catch {
log.debug(`» no existing authentication headers to remove (${header})`);
}
}
// remove includeIf entries that actions/checkout@v6 uses for credential persistence.
// v6 stores credentials in an external file loaded via includeIf.gitdir, which our
// --unset-all above doesn't catch. without this, stale credentials from actions/checkout
// would be sent alongside ASKPASS-provided credentials.
removeIncludeIfEntries(repoDir);
// SECURITY: set origin URL without token - auth is injected via GIT_ASKPASS
// in $git() calls. this prevents token leakage to git hooks and subprocesses.
const originUrl = `https://github.com/${params.owner}/${params.name}.git`;
const giteaUrl = (process.env.GITEA_URL ?? "https://git.shockvpn.com").replace(/\/$/, "");
const originUrl = `${giteaUrl}/${params.owner}/${params.name}.git`;
$("git", ["remote", "set-url", "origin", originUrl], { cwd: repoDir });
// initialize pushUrl to base repo - may be updated by checkout_pr for fork PRs
params.toolState.pushUrl = originUrl;
// disable credential helpers to prevent prompts and ensure clean auth state
$("git", ["config", "--local", "credential.helper", ""], { cwd: repoDir });
// pin the run-entry HEAD for the checkout_pr initial-branch invariant; see
// captureInitialHead for the named-branch vs detached split and why it
// matters (zed-industries/cloud 2026-05-18 cross-PR clobber shape).
params.toolState.initialHead = captureInitialHead(repoDir);
log.info("» git authentication configured");
}
/**
* snapshot the current HEAD as either a branch name (when on a named branch)
* or a literal SHA (when detached). used by setupGit to pin the run-entry
* position and by checkout_pr to compare the live HEAD against it.
*
* splitting the two cases is load-bearing: `git rev-parse --abbrev-ref HEAD`
* returns the sentinel string `"HEAD"` on detached entry — which is the
* default `actions/checkout` state for `pull_request` events. storing that
* raw string would make any future detached state (including a subagent's
* `git checkout --detach <sha>`) compare equal.
*/
export function captureInitialHead(
repoDir: string
): { kind: "branch"; name: string } | { kind: "detached"; sha: string } {
@@ -339,9 +225,7 @@ export function captureInitialHead(
log: false,
}).trim();
if (name) return { kind: "branch", name };
} catch {
// detached HEAD — fall through
}
} catch {}
const sha = $("git", ["rev-parse", "HEAD"], { cwd: repoDir, log: false }).trim();
return { kind: "detached", sha };
}
utils/skills.ts
-133
View File
@@ -1,133 +0,0 @@
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { log } from "./cli.ts";
import { getDevDependencyVersion } from "./version.ts";
const skillsVersion = getDevDependencyVersion("skills");
/**
* skills bundled with the action runtime. the SKILL.md files live in
* `action/skills/<name>/SKILL.md` and are read at runtime — no esbuild loader,
* no codegen. this matters because the preview / oss path runs `cli.ts` from
* source (see `runCli.ts#runLocalCli`) where esbuild loaders don't apply.
*/
const BUNDLED_SKILL_NAMES = ["git-archaeology"] as const;
/**
* resolve the on-disk path of a bundled SKILL.md by checking the two locations
* the file may live in:
* - source mode (`runLocalCli`): `<actionRoot>/skills/<name>/SKILL.md`,
* reached as `../skills/...` from `utils/skills.ts`.
* - bundled mode (npx published package): `<distDir>/skills/<name>/SKILL.md`,
* reached as `./skills/...` from `dist/cli.mjs`.
*
* the bundled-mode copy is produced by an esbuild post-build step in
* `esbuild.config.js`.
*/
function resolveSkillPath(name: string): string {
const here = dirname(fileURLToPath(import.meta.url));
const candidates = [
join(here, "..", "skills", name, "SKILL.md"),
join(here, "skills", name, "SKILL.md"),
];
for (const candidate of candidates) {
if (existsSync(candidate)) return candidate;
}
throw new Error(`bundled skill not found: ${name} (looked in ${candidates.join(", ")})`);
}
/**
* each agent has its own auto-scan dir under HOME. we write to all of them so
* the same `installBundledSkills` call works regardless of which agent is
* running, without coupling skills.ts to agent identity.
*
* verified empirically (PR #565):
* - OpenCode registers skills from `$HOME/.agents/skills/` and `.opencode/skills/`.
* - Claude Code only registers skills from `$HOME/.claude/skills/` —
* it does NOT scan `.agents/skills/`, so writing only there leaves the
* skill on disk but invisible to Claude's `Skill` tool.
*/
const SKILL_TARGET_DIRS = [".opencode/skills", ".claude/skills", ".agents/skills"] as const;
/**
* write all bundled skills into the fake HOME so OpenCode / Claude Code discover
* them via their auto-scan directories.
*
* called once per agent run from each agent's `run()`. cheap (small file
* writes), no network, idempotent.
*/
export function installBundledSkills(params: { home: string }): void {
for (const name of BUNDLED_SKILL_NAMES) {
const content = readFileSync(resolveSkillPath(name), "utf8");
for (const targetDir of SKILL_TARGET_DIRS) {
const skillDir = join(params.home, targetDir, name);
mkdirSync(skillDir, { recursive: true });
writeFileSync(join(skillDir, "SKILL.md"), content);
}
}
log.success(`installed bundled skills: ${BUNDLED_SKILL_NAMES.join(", ")}`);
}
/**
* install a skill globally via the `skills` CLI.
*
* runs `npx skills add <ref> --skill <name> -g` with `cwd` set to os tmpdir
* so npm doesn't walk up and find a project-level `.npmrc` with pnpm-specific
* settings (e.g. `public-hoist-pattern`) that break npx binary resolution.
* the `-g` flag writes to `$HOME/.agents/skills/` which is controlled by
* `params.env.HOME` (the fake HOME), so cwd has no effect on install location.
*/
export function addSkill(params: {
ref: string;
skill: string;
env: Record<string, string>;
agent: string;
}): void {
const result = spawnSync(
"npx",
[
"-y",
`skills@${skillsVersion}`,
"add",
params.ref,
"--skill",
params.skill,
"-g",
"-a",
params.agent,
"-y",
],
{
cwd: tmpdir(),
env: { ...process.env, ...params.env },
stdio: "pipe",
timeout: 30_000,
}
);
if (result.status === 0) {
log.success(`installed ${params.skill} skill (${params.agent})`);
return;
}
// skills CLI uses a Clack-style TUI that prints errors to stdout (alongside
// spinner output), not stderr. report exit code + both streams + spawn
// error so failures aren't silent. tail-truncate streams to keep CI logs
// bounded.
const stdout = (result.stdout?.toString() || "").trim();
const stderr = (result.stderr?.toString() || "").trim();
const parts = [
`exit=${result.status ?? "null"} signal=${result.signal ?? "null"}`,
result.error ? `spawn error: ${result.error.message}` : null,
stderr ? `stderr:\n${tailLines(stderr, 20)}` : null,
stdout ? `stdout:\n${tailLines(stdout, 20)}` : null,
].filter(Boolean);
log.warning(`${params.skill} skill install failed — ${parts.join(" | ")}`);
}
function tailLines(text: string, n: number): string {
const lines = text.split("\n");
if (lines.length <= n) return text;
return `...(truncated, last ${n} of ${lines.length} lines)\n${lines.slice(-n).join("\n")}`;
}
utils/todoTracking.ts
+1 -1
View File
@@ -39,7 +39,7 @@ function renderTodoMarkdown(todos: TodoItem[]): string {
case "cancelled":
return `- ~~${todo.content}~~`;
case "in_progress":
return `- [ ] <img src="https://uploads.pullfrog.com/Progress%20Indicator.gif" width="11" style="visibility: visible; max-width: 100%;" /> ${todo.content}`;
return `- [ ] <img src="https://git.shockvpn.com/assets/loading.gif" width="11" style="visibility: visible; max-width: 100%;" /> ${todo.content}`;
case "pending":
return `- [ ] ${todo.content}`;
default:
utils/token.ts
-184
View File
@@ -1,184 +0,0 @@
import assert from "node:assert/strict";
import * as core from "@actions/core";
import type { PushPermission } from "../external.ts";
import { log } from "./cli.ts";
import { onExitSignal } from "./exitHandler.ts";
import { acquireNewToken } from "./github.ts";
import { isGitHubActions } from "./globals.ts";
// re-export for `pullfrog gha token` subcommand
export { acquireNewToken as acquireInstallationToken };
export { revokeGitHubInstallationToken as revokeInstallationToken };
// store MCP token in memory for getGitHubInstallationToken()
let mcpTokenValue: string | undefined;
/**
* get the job-scoped token from action input.
* this token has permissions defined by the workflow's permissions block.
*
* fallback order:
* 1. INPUT_TOKEN (from workflow `with: token:`)
* 2. GH_TOKEN (external token override)
* 3. GITHUB_TOKEN (pre-acquired in tests or from GHA env)
*/
export function getJobToken(): string {
const inputToken = core.getInput("token");
if (inputToken) {
return inputToken;
}
// fallback for test environment and local dev
const fallbackToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
if (fallbackToken) {
return fallbackToken;
}
throw new Error("token input is required");
}
export type TokenRef = {
gitToken: string;
mcpToken: string;
[Symbol.asyncDispose]: () => Promise<void>;
};
type ResolveTokensParams = {
push: PushPermission;
};
/**
* resolve tokens for the action run.
*
* creates two separate tokens:
* - gitToken: contents permission based on `push` setting (assumed exfiltratable)
* - push: enabled → contents:write (can push)
* - push: disabled → contents:read (read-only)
* - mcpToken: full installation token - used for GitHub API calls in MCP tools (not exfiltratable)
*
* security-conscious users can pass their own token via GH_TOKEN env var or inputs.token.
*/
export async function resolveTokens(params: ResolveTokensParams): Promise<TokenRef> {
assert(!mcpTokenValue, "tokens are already resolved");
const externalToken = process.env.GH_TOKEN;
// external token takes precedence - use for both git and MCP
if (externalToken) {
mcpTokenValue = externalToken;
if (isGitHubActions) {
core.setSecret(externalToken);
}
log.info("» using external GH_TOKEN for both git and MCP");
return {
gitToken: externalToken,
mcpToken: externalToken,
async [Symbol.asyncDispose]() {
mcpTokenValue = undefined;
// GH_TOKEN isn't acquired here, so it's not revoked here either
},
};
}
// create git token based on push permission (assumed exfiltratable)
// disabled = read-only, restricted/enabled = write (MCP tools enforce branch restrictions)
// workflows permission is write-only in the API, so only requested when pushing is allowed
const gitPermissions =
params.push === "disabled"
? { contents: "read" as const }
: { contents: "write" as const, workflows: "write" as const };
const gitToken = await acquireNewToken({ permissions: gitPermissions });
if (isGitHubActions) {
core.setSecret(gitToken);
}
log.info(
`» acquired git token (${Object.entries(gitPermissions)
.map((e) => e.join(":"))
.join(", ")})`
);
// MCP token scoped to only what MCP tools actually need.
// not exfiltratable (only accessible via MCP tools), but scoped as defense-in-depth
// so even a compromised tool context can't touch secrets, admin, etc.
const mcpPermissions = {
contents: "write",
pull_requests: "write",
issues: "write",
checks: "read",
actions: "read",
} as const;
const mcpToken = await acquireNewToken({ permissions: mcpPermissions });
if (isGitHubActions) {
core.setSecret(mcpToken);
}
log.info(
`» acquired scoped MCP token (${Object.entries(mcpPermissions)
.map((e) => e.join(":"))
.join(", ")})`
);
mcpTokenValue = mcpToken;
let disposingRef: PromiseWithResolvers<void> | undefined;
const dispose = async () => {
if (disposingRef) {
// this can happen if the signal arrives when disposing tokens
// we make sure to wait for the current dispose to complete
return disposingRef.promise;
}
disposingRef = Promise.withResolvers();
try {
mcpTokenValue = undefined;
// revoke both tokens
await Promise.all([
revokeGitHubInstallationToken(gitToken),
revokeGitHubInstallationToken(mcpToken),
]);
} finally {
removeSignalHandler();
disposingRef.resolve();
disposingRef = undefined;
}
};
const removeSignalHandler = onExitSignal(dispose);
return {
gitToken,
mcpToken,
[Symbol.asyncDispose]: dispose,
};
}
/**
* get the MCP token from memory.
* this is the token used for GitHub API calls in MCP tools.
*/
export function getGitHubInstallationToken(): string {
assert(mcpTokenValue, "tokens not set. call resolveTokens first.");
return mcpTokenValue;
}
export async function revokeGitHubInstallationToken(token: string): Promise<void> {
const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com";
try {
await fetch(`${apiUrl}/installation/token`, {
method: "DELETE",
headers: {
Accept: "application/vnd.github+json",
Authorization: `Bearer ${token}`,
"X-GitHub-Api-Version": "2022-11-28",
},
});
log.debug("» installation token revoked");
} catch (error) {
log.info(
`Failed to revoke installation token: ${error instanceof Error ? error.message : String(error)}`
);
}
}
utils/version.ts
+7 -7
View File
@@ -1,10 +1,10 @@
import semver from "semver";
import packageJson from "../package.json" with { type: "json" };
export function getDevDependencyVersion(name: keyof typeof packageJson.devDependencies): string {
const version = packageJson.devDependencies[name];
if (!semver.valid(version)) {
throw new Error(`dev dependency "${name}" must be a pinned version, got "${version}"`);
}
return version;
export function getDevDependencyVersion(name: string): string {
const deps = packageJson.devDependencies as Record<string, string>;
const version = deps[name];
if (!version) throw new Error(`dev dependency "${name}" not found`);
const clean = version.replace(/^[^0-9]*/, "");
if (!clean) throw new Error(`dev dependency "${name}" must be a pinned version, got "${version}"`);
return clean;
}
utils/versioning.test.ts
-34
View File
@@ -1,34 +0,0 @@
import { describe, expect, it } from "vitest";
import { validateCompatibility } from "./versioning.ts";
describe("validateCompatibility", () => {
it("should throw if payload version is invalid", () => {
expect(() => validateCompatibility("invalid", "1.0.0")).toThrow(/not a valid semantic version/);
});
it.each([
["1.0.0", "1.0.0"], // same
["1.0.0-alpha.1", "1.0.0"], // action is newer than pre-release
["0.1.0", "0.1.1"], // action is newer during active development
["0.0.158", "0.0.158"], // bug #129
["0.0.159", "0.0.158"], // bug #129
["0.0.158", "0.0.159"], // bug #129
["1.0.0", "1.0.1"], // action patched
["1.0.0", "1.1.0"], // action has a new feature (backward compatible)
["1.0.1", "1.0.0"], // payload is newer (patch)
["1.1.0", "1.0.0"], // payload is newer (feature is backward compatible)
])("should accept compatible payload %#", (payloadVersion, actionVersion) => {
expect(() => validateCompatibility(payloadVersion, actionVersion)).not.toThrow();
});
it.each([
["0.1.0", "0.2.0"], // action had breaking changes during active development
["0.2.0", "0.1.0"], // payload had breaking changes during active development
["2.0.0", "1.0.0"], // payload is majorly newer
["1.0.0", "2.0.0"], // action had breaking changes
])("should reject incompatible payload %#", (payloadVersion, actionVersion) => {
expect(() => validateCompatibility(payloadVersion, actionVersion)).toThrow(
/is incompatible with action version/
);
});
});
utils/versioning.ts
-44
View File
@@ -1,44 +0,0 @@
import semver from "semver";
type CompatibilityPolicy =
/**
* Strict policy: the action must support the same features as the payload version declares
* @example Payload version 1.2.3 => ^1.2.0 range of action versions supported
* @example Payload version 0.1.55 => ^0.1.55 range of action versions supported
*/
| "same-features"
/**
* Loose policy: the action must have no breaking changes compared to the payload version
* @example Payload version 1.2.3 => ^1.0.0 range of action versions supported
* @example Payload version 0.1.55 => ^0.1.0 range of action versions supported
*/
| "non-breaking";
const COMPATIBILITY_POLICY: CompatibilityPolicy = "non-breaking";
/**
* @throws Error if the action can't process payload
* The compatibility is determined according to the COMPATIBILITY_POLICY above.
* @param payloadVersion the version of the payload
* @param actionVersion the version of the action (recipient)
*/
export function validateCompatibility(payloadVersion: string, actionVersion: string): void {
const payloadSemVer = semver.parse(payloadVersion);
if (!payloadSemVer)
throw new Error(`Payload version ${payloadVersion} is not a valid semantic version.`);
const major = payloadSemVer.major;
const minor = payloadSemVer.minor;
const patch = payloadSemVer.patch;
const compatibilityRange =
COMPATIBILITY_POLICY === "same-features"
? `^${major}.${minor}.${major === 0 ? patch : 0}`
: `^${major}.${major === 0 ? minor : 0}.${major === 0 ? "x" : 0}`; // non-breaking
if (!semver.satisfies(actionVersion, compatibilityRange)) {
throw new Error(
`Payload version ${payloadVersion} is incompatible with action version ${actionVersion}. ` +
`Please update your workflow to use at least ${semver.minVersion(compatibilityRange)} version of the action.`
);
}
}
utils/vertex.ts
-85
View File
@@ -1,85 +0,0 @@
import { randomUUID } from "node:crypto";
import { mkdirSync, rmSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { VERTEX_MODEL_ID_ENV } from "../models.ts";
export const VERTEX_SERVICE_ACCOUNT_JSON_ENV = "VERTEX_SERVICE_ACCOUNT_JSON";
export const GOOGLE_APPLICATION_CREDENTIALS_ENV = "GOOGLE_APPLICATION_CREDENTIALS";
export const GOOGLE_CLOUD_PROJECT_ENV = "GOOGLE_CLOUD_PROJECT";
export const VERTEX_LOCATION_ENV = "VERTEX_LOCATION";
export type VertexCredentials = {
credentialsPath: string;
secretDir: string;
};
function hasEnvVar(name: string): boolean {
const value = process.env[name];
return typeof value === "string" && value.length > 0;
}
export function isVertexRoute(model: string | undefined): boolean {
const vertexId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
return model !== undefined && vertexId !== undefined && vertexId === model;
}
export function readProjectIdFromVertexServiceAccountJson(): string | undefined {
const blob = process.env[VERTEX_SERVICE_ACCOUNT_JSON_ENV];
if (!blob) return undefined;
try {
const parsed: unknown = JSON.parse(blob);
if (!parsed || typeof parsed !== "object" || !("project_id" in parsed)) {
return undefined;
}
const projectId = parsed.project_id;
return typeof projectId === "string" && projectId.length > 0 ? projectId : undefined;
} catch {
return undefined;
}
}
function createSecretDir(): string {
const base = process.env.PULLFROG_SECRET_HOME || process.env.HOME || homedir();
const secretDir = join(base, ".pullfrog", "secrets", randomUUID());
mkdirSync(secretDir, { recursive: true, mode: 0o700 });
return secretDir;
}
export function materializeVertexCredentials(params: {
model: string | undefined;
}): VertexCredentials | undefined {
if (!isVertexRoute(params.model)) return undefined;
const blob = process.env[VERTEX_SERVICE_ACCOUNT_JSON_ENV];
if (!blob) return undefined;
const secretDir = createSecretDir();
const credentialsPath = join(secretDir, "vertex-sa.json");
writeFileSync(credentialsPath, blob, { mode: 0o600 });
process.env[GOOGLE_APPLICATION_CREDENTIALS_ENV] = credentialsPath;
const projectId = readProjectIdFromVertexServiceAccountJson();
if (projectId && !hasEnvVar(GOOGLE_CLOUD_PROJECT_ENV)) {
process.env[GOOGLE_CLOUD_PROJECT_ENV] = projectId;
}
return { credentialsPath, secretDir };
}
export function cleanupVertexCredentials(credentials: VertexCredentials | undefined): void {
if (!credentials) return;
rmSync(credentials.secretDir, { recursive: true, force: true });
delete process.env[GOOGLE_APPLICATION_CREDENTIALS_ENV];
}
export function applyClaudeVertexEnv(env: Record<string, string | undefined>): void {
env.CLAUDE_CODE_USE_VERTEX = "1";
env.ANTHROPIC_VERTEX_PROJECT_ID ??= env[GOOGLE_CLOUD_PROJECT_ENV];
env.CLOUD_ML_REGION ??= env[VERTEX_LOCATION_ENV];
}
export function resolveVertexOpenCodeModel(model: string | undefined): string | undefined {
return isVertexRoute(model) && model ? `google-vertex/${model}` : undefined;
}
utils/workflow.ts
-54
View File
@@ -1,54 +0,0 @@
import { log } from "./cli.ts";
import type { OctokitWithPlugins } from "./github.ts";
interface ResolveRunParams {
octokit: OctokitWithPlugins;
}
export interface ResolveRunResult {
runId: number | undefined;
jobId: string | undefined;
}
/**
* Resolve GitHub Actions workflow run context.
* Uses GITHUB_REPOSITORY and GITHUB_RUN_ID env vars.
*/
export async function resolveRun(params: ResolveRunParams): Promise<ResolveRunResult> {
const runId = process.env.GITHUB_RUN_ID
? Number.parseInt(process.env.GITHUB_RUN_ID, 10)
: undefined;
const githubRepo = process.env.GITHUB_REPOSITORY;
if (!githubRepo || !githubRepo.includes("/")) {
throw new Error(`GITHUB_REPOSITORY env var must be set to "owner/repo", got: ${githubRepo}`);
}
const [owner, repo] = githubRepo.split("/");
// jobId is purely cosmetic — only used to deep-link "View workflow run"
// footers to the specific job. Tolerate any failure (e.g. test harness
// running with the host's GITHUB_RUN_ID against a different repo's MCP
// token, which 404s; this happens since #750 dropped the env allowlist
// and now passes GITHUB_RUN_ID + GITHUB_JOB through to the test container)
// and fall back to the run-level link.
let jobId: string | undefined;
const jobName = process.env.GITHUB_JOB;
if (jobName && runId) {
try {
const jobs = await params.octokit.rest.actions.listJobsForWorkflowRun({
owner,
repo,
run_id: runId,
});
const matchingJob = jobs.data.jobs.find((job) => job.name === jobName);
if (matchingJob) {
jobId = String(matchingJob.id);
log.debug(`» found job ID: ${jobId}`);
}
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
log.debug(`» listJobsForWorkflowRun failed (jobId stays undefined): ${msg}`);
}
}
return { runId, jobId };
}