pullfrog 0.1.31 → 0.1.33

package/dist/internal/index.d.ts

@@ -8,6 +8,7 @@ export type { Mode } from "../modes.ts";
 export { modes } from "../modes.ts";
 export type { BuildPullfrogFooterParams, WorkflowRunFooterInfo, } from "../utils/buildPullfrogFooter.ts";
 export { buildPullfrogFooter, PULLFROG_DIVIDER, stripExistingFooter, } from "../utils/buildPullfrogFooter.ts";
+export { checkRunsGate, hasVerifiedCheck } from "../utils/checksGate.ts";
 export type { CodexAuthBody } from "../utils/codexOAuth.ts";
 export { decodeJwtExpMs, OAuthInvalidGrantError, parseCodexAuthBody, refreshCodexAuthBody, stringifyCodexAuthBody, } from "../utils/codexOAuth.ts";
 export type { ResourceUsage, UsageSummary } from "../utils/github.ts";

package/dist/internal.js

@@ -9,15 +9,20 @@ var providers = {
     displayName: "Anthropic",
     envVars: ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"],
     models: {
-      // claude-fable-5 is disabled globally — access has been revoked, so it
-      // can't run as-is anywhere (BYOK, Claude Code, or Router). the fallback
-      // redirects all resolution to opus and hides it from pickers; opus is the
-      // universally-available flagship, the AUTO_INTELLIGENT tier target, and
-      // the recommended pick. clear the fallback if fable access returns (#959).
+      // claude-fable-5 is selectable but not recommended/auto-selected — it's
+      // moving to usage-credits-only billing and isn't broadly available yet, so
+      // opus stays the universally-available flagship, the AUTO_INTELLIGENT tier
+      // target, and the recommended pick. an explicit fable pick hits the real
+      // API and is access-gated: it errors for accounts without access today and
+      // just works once usage credits are live — no silent opus fallback, the
+      // API is the source of truth (#959).
       "claude-fable": {
         displayName: "Claude Fable",
         resolve: "anthropic/claude-fable-5",
-        fallback: "anthropic/claude-opus",
+        // rolling alias: models.dev's OpenRouter mirror lags brand-new pinned
+        // versions (claude-fable-5 isn't indexed yet), so track ~…-latest to
+        // stay catalog-valid and auto-follow version bumps.
+        openRouterResolve: "openrouter/~anthropic/claude-fable-latest",
         subagentModel: "claude-sonnet"
       },
       "claude-opus": {
@@ -29,8 +34,8 @@ var providers = {
       },
       "claude-sonnet": {
         displayName: "Claude Sonnet",
-        resolve: "anthropic/claude-sonnet-4-6",
-        openRouterResolve: "openrouter/anthropic/claude-sonnet-4.6"
+        resolve: "anthropic/claude-sonnet-5",
+        openRouterResolve: "openrouter/anthropic/claude-sonnet-5"
       },
       "claude-haiku": {
         displayName: "Claude Haiku",
@@ -208,8 +213,8 @@ var providers = {
       },
       "claude-sonnet": {
         displayName: "Claude Sonnet",
-        resolve: "opencode/claude-sonnet-4-6",
-        openRouterResolve: "openrouter/anthropic/claude-sonnet-4.6"
+        resolve: "opencode/claude-sonnet-5",
+        openRouterResolve: "openrouter/anthropic/claude-sonnet-5"
       },
       "claude-haiku": {
         displayName: "Claude Haiku",
@@ -1240,6 +1245,26 @@ function stripExistingFooter(body) {
   return body.substring(0, dividerIndex).trimEnd();
 }
 
+// utils/checksGate.ts
+var OK_CONCLUSIONS = /* @__PURE__ */ new Set(["success", "neutral", "skipped"]);
+var PULLFROG_CHECKS = /* @__PURE__ */ new Set(["pullfrog", "pullfrog-approval"]);
+function checkRunsGate(params) {
+  for (const run of params.checkRuns) {
+    if (PULLFROG_CHECKS.has(run.name.toLowerCase())) continue;
+    if (run.status !== "completed")
+      return { ok: false, reason: `check "${run.name}" ${run.status}` };
+    if (!OK_CONCLUSIONS.has(run.conclusion ?? "")) {
+      return { ok: false, reason: `check "${run.name}" concluded ${run.conclusion}` };
+    }
+  }
+  return { ok: true, reason: "all checks passed" };
+}
+function hasVerifiedCheck(params) {
+  return params.checkRuns.some(
+    (r) => !PULLFROG_CHECKS.has(r.name.toLowerCase()) && r.status === "completed"
+  );
+}
+
 // utils/codexOAuth.ts
 var CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 var CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
@@ -1467,6 +1492,7 @@ export {
   PULLFROG_DIVIDER,
   TIMEOUT_DISABLED,
   buildPullfrogFooter,
+  checkRunsGate,
   createLeapingProgressComment,
   decodeJwtExpMs,
   defaultAutoTier,
@@ -1477,6 +1503,7 @@ export {
   getModelProvider,
   getProgressComment,
   getProviderDisplayName,
+  hasVerifiedCheck,
   isAutoTier,
   isCardGatedModel,
   isLeapingIntoActionCommentBody,

package/dist/mcp/review.d.ts

@@ -23,6 +23,41 @@ export declare const TRANSIENT_REVIEW_RETRY_DELAYS_MS: number[];
  */
 export declare function commentableLinesForFile(patch: string | undefined): CommentableLines;
 export declare function buildCommentableMap(ctx: ToolContext, pullNumber: number): Promise<Map<string, CommentableLines>>;
+/**
+ * count unresolved review threads on a PR whose root comment was authored by
+ * Pullfrog's bot. this is the full set of open Pullfrog findings on the PR —
+ * the basis for both the never-approve-with-outstanding-issues invariant (the
+ * approval gate below) and the `pullfrog-approval` status verdict. it is a
+ * function of all open findings, NOT just the latest commit's delta.
+ *
+ * outdated-but-unresolved threads still count — GitHub marks a thread
+ * `[OUTDATED]` when the anchor line moved (reformat, rename, force-push), which
+ * is not the same as the concern being addressed. human-reviewer threads are
+ * excluded: they belong to those reviewers to resolve. walks every page so a
+ * long-lived PR with >100 threads can't hide an outstanding finding.
+ */
+export declare function countOutstandingPullfrogThreads(ctx: ToolContext, pullNumber: number): Promise<number>;
+/**
+ * proactive approve-when-clean for the Fix-all / Fix-👍s flow (`fix_review`
+ * trigger). when such a run completes successfully and every Pullfrog-originated
+ * review thread it raised is resolved, post a NEW approving review summarizing
+ * the run's work.
+ *
+ * the verification step shares `countOutstandingPullfrogThreads` with the
+ * approval gate in create_pull_request_review: that gate REACTIVELY blocks a
+ * bad approval; this is the PROACTIVE approve side. approval is contingent on
+ * Pullfrog's own findings actually being addressed — never a blind post-fix
+ * approval. a Fix-👍s run that only resolved a subset naturally fails the
+ * outstanding-thread check and is left unapproved.
+ *
+ * respects `prApproveEnabled` (the repo's "Allow Pullfrog to approve PRs"
+ * opt-in): a repo that hasn't enabled binding bot approvals never gets one
+ * here. skips when the agent already rendered an explicit review verdict this
+ * run (`toolState.approval`), so an agent that found a real issue and submitted
+ * a non-approving review is never overridden. best-effort — a failure must not
+ * flip the run's outcome.
+ */
+export declare function approveAfterFix(ctx: ToolContext): Promise<void>;
 export type ReviewCommentInput = NonNullable<RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]["comments"]>[number];
 export interface DroppedComment {
     path: string;
@@ -155,6 +190,11 @@ export declare function CreatePullRequestReviewTool(ctx: ToolContext): import("f
 }>> & {
     mutates?: boolean;
 };
+type FooterOpts = {
+    body: string;
+    approved: boolean;
+    hasComments: boolean;
+};
 /**
  * clear a pending review draft stranded on the PR by a prior hard-killed run
  * (workflow timeout, OOM) so the next createReview can succeed.
@@ -196,6 +236,7 @@ export declare function clearStrandedPendingReview(ctx: ToolContext, params: {
  * comments-only) until a body-path run happened to clear the draft.
  */
 export declare function createReviewWithStrandedRecovery(ctx: ToolContext, params: RestEndpointMethodTypes["pulls"]["createReview"]["parameters"]): Promise<Awaited<ReturnType<typeof ctx.octokit.rest.pulls.createReview>>>;
+export declare function createAndSubmitWithFooter(ctx: ToolContext, params: RestEndpointMethodTypes["pulls"]["createReview"]["parameters"], opts: FooterOpts): Promise<Awaited<ReturnType<typeof ctx.octokit.rest.pulls.submitReview>>>;
 /**
  * report the review node ID so the WorkflowRun is marked as "review submitted".
  * exported for use in main.ts post-agent cleanup.

package/dist/mcp/server.d.ts

@@ -22,6 +22,7 @@ export interface ToolContext {
     postCheckoutScript: string | null;
     prepushScript: string | null;
     prApproveEnabled: boolean;
+    autoMergeEnabled: boolean;
     signedCommits: boolean;
     modeInstructions: Record<string, string>;
     toolState: ToolState;

package/dist/toolState.d.ts

@@ -100,6 +100,10 @@ export interface ToolState {
         nodeId: string;
         reviewedSha: string | undefined;
     };
+    approval?: {
+        wouldApprove: boolean;
+        sha: string | undefined;
+    };
     reviewReplies?: Map<number, {
         commentId: number;
         url: string | undefined;

package/dist/utils/agent.d.ts

@@ -10,7 +10,9 @@ import type { Agent } from "../agents/index.ts";
  *      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.
+ *      a non-curated value with a slash passes through unchanged as a raw
+ *      models.dev specifier (same as `PULLFROG_MODEL`), not auto-selected away.
+ *   3. undefined (no slug, or a bare-word non-specifier) — agent auto-selects.
  */
 export declare function resolveModel(ctx: {
     slug?: string | undefined;

package/dist/utils/autoMerge.d.ts

@@ -0,0 +1,37 @@
+import type { ToolContext } from "../mcp/server.ts";
+/**
+ * Run-end lifecycle action: merge ANY open PR that this run mechanically
+ * approved on its current head — Pullfrog acting as a full repo maintainer,
+ * contributor PRs included, not just merging its own work. There is deliberately
+ * NO agent-callable merge tool — the merge is a pure, deterministic consequence
+ * of the runtime observing a clean approved state, so a prompt-injected agent has
+ * no merge surface to reach for. Every clause is fail-closed and re-verified
+ * against GitHub's own state at merge time; any failure logs why and returns
+ * without merging. Best-effort — the caller wraps this in a `.catch`, and a
+ * merge/comment failure can never flip the run's outcome.
+ *
+ * There is NO self-authorship restriction: the approval verdict IS the trust
+ * decision (Pullfrog reviewed it and would approve), exactly like a human
+ * maintainer merging a contributor PR. The population of mergeable PRs is bounded
+ * upstream by the review triggers (`prCreated` / `prCreatedAllowNonCollaborator`)
+ * — Pullfrog can only merge what it was configured to review + approve — and the
+ * whole capability is opt-in per repo (clause 1). The remaining clauses are the
+ * maintainer's controls.
+ *
+ * The invariant (all must hold):
+ *   1. `ctx.autoMergeEnabled` — the per-repo toggle ANDed with the global
+ *      `isAutonomousMaintenanceEnabled()` kill switch, server-side (run-context).
+ *   2. `ctx.prApproveEnabled` — cannot auto-merge what it may not approve.
+ *   3. this run recorded an APPROVE verdict (`toolState.approval.wouldApprove`) —
+ *      Pullfrog's review is the merge decision.
+ *   4. the PR is open and not a draft.
+ *   5. `toolState.approval.sha === <current head sha>` — approved THIS head, so a
+ *      commit pushed after the review can't ride the approval in (409-safe below).
+ *   6. `countOutstandingPullfrogThreads === 0` — re-queried at merge time.
+ *   7. no un-dismissed human CHANGES_REQUESTED — the human veto always wins.
+ *   8. GitHub reports the PR mergeable and not blocked/dirty/behind.
+ *   9. every external check-run/commit-status on the head is complete and
+ *      non-failing (`checkRunsGate`) — red or in-flight CI never auto-merges,
+ *      even on a repo without branch protection.
+ */
+export declare function autoMergeAfterApprove(ctx: ToolContext): Promise<void>;

package/dist/utils/checksGate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared, dependency-free CI green/red predicate — the single source of truth for
+ * "given these check-runs, is this PR head safe to merge?". Consumed by the
+ * auto-merge path: `autoMerge.ts` gates the PR head at merge time, and the
+ * `pr-merge-completion` webhook re-checks it before dispatching a slow-CI re-wake.
+ * A red or in-flight sha never merges, and a sha with no confirmable green
+ * check-run is treated as unverified (refused, not merged blind).
+ *
+ * Gates on the Checks API only. The Pullfrog App deliberately holds no `statuses`
+ * permission (requesting it would force re-approval on every install — see
+ * wiki/app-permissions.md), so the legacy Commit Statuses API is unreadable
+ * (`listCommitStatusesForRef` 403s). Modern CI (GitHub Actions, etc.) reports via
+ * check-runs; a repo relying on the legacy Statuses API is covered by branch
+ * protection instead — a failing required status makes `mergeable_state` `blocked`,
+ * which the merge invariant already refuses (`NON_MERGEABLE_STATES`).
+ */
+export type CheckRun = {
+    name: string;
+    status: string;
+    conclusion: string | null;
+};
+/**
+ * Refuse if any external check-run is incomplete (queued/in_progress) or concluded
+ * anything other than success/neutral/skipped. Fail-closed on unknown/absent
+ * conclusions. Pure so the pass/fail logic is inspectable directly.
+ */
+export declare function checkRunsGate(params: {
+    checkRuns: CheckRun[];
+}): {
+    ok: boolean;
+    reason: string;
+};
+/**
+ * true when the head has ≥1 CONCLUDED non-failing EXTERNAL check-run — CI
+ * positively ran, not merely "no red was seen". paired with `checkRunsGate.ok`
+ * (any completed check is non-failing), this == "≥1 concluded non-failing check".
+ * the merge requires it: a head with ZERO check-runs passes
+ * `checkRunsGate` (nothing red) but has no verification, and since the app can't
+ * read legacy commit statuses, "zero check-runs" is indistinguishable from "green
+ * Actions but a red CircleCI status" — so we only act on a head we can positively
+ * confirm is green. Pullfrog's own verdict checks don't count as external CI.
+ */
+export declare function hasVerifiedCheck(params: {
+    checkRuns: CheckRun[];
+}): boolean;

package/dist/utils/isTransientNetworkError.d.ts

@@ -8,3 +8,12 @@
  * substrings on `error.message` (e.g. provider-specific framings).
  */
 export declare function isTransientNetworkError(error: unknown, extraPatterns?: string[]): boolean;
+/**
+ * broader transient predicate for octokit calls: an HTTP 5xx (GitHub upstream
+ * blip) OR a network-class error. distinct from `isTransientNetworkError` — an
+ * HTTP 4xx (404/401/403/422) is deterministic and fails fast. the action
+ * octokit carries only the throttling plugin + a 401 re-mint (no 5xx retry),
+ * so callers on critical paths retry idempotent GitHub reads/dispatches with
+ * this. mirrors the server's `isTransientUpstreamError`. see #999.
+ */
+export declare function isTransientOctokitError(error: unknown): boolean;

package/dist/utils/payload.d.ts

@@ -25,17 +25,25 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     generateSummary?: boolean | undefined;
 }, {}>;
 export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
-    prompt: string;
+    prompt?: string | undefined;
+    prompt_file?: string | undefined;
     model?: string | undefined;
     timeout?: string | undefined;
     push?: "disabled" | "enabled" | "restricted" | undefined;
     shell?: "disabled" | "enabled" | "restricted" | undefined;
+    status_checks?: "disabled" | "enabled" | undefined;
     cwd?: string | undefined;
     output_schema?: string | undefined;
 }, {}>;
 export type Inputs = typeof Inputs.infer;
 export type ResolvedPromptInput = string | typeof JsonPayload.infer;
 export declare function resolvePromptInput(): ResolvedPromptInput;
+/**
+ * true when `actor` is Pullfrog's own GitHub identity — the bot login
+ * (`pullfrog[bot]` / `pullfrogdev[bot]`) or the bare account. used to skip
+ * self-triggered events and to recognize Pullfrog-originated review threads.
+ */
+export declare const isPullfrog: (actor: string | null | undefined) => boolean;
 export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput, repoSettings: RepoSettings): {
     "~pullfrog": true;
     version: string;
@@ -62,6 +70,7 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
     generateSummary: boolean | undefined;
     push: import("../external.ts").PushPermission;
     shell: import("../external.ts").ShellPermission;
+    statusChecks: boolean;
     proxyModel: string | undefined;
 };
 export type ResolvedPayload = ReturnType<typeof resolvePayload>;

package/dist/utils/runContext.d.ts

@@ -31,6 +31,7 @@ export interface RepoSettings {
     push: PushPermission;
     shell: ShellPermission;
     prApproveEnabled: boolean;
+    autoMergeEnabled: boolean;
     signedCommits: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;

package/dist/utils/statusChecks.d.ts

@@ -0,0 +1,25 @@
+import type { ToolContext } from "../mcp/server.ts";
+/**
+ * post the opt-in `pullfrog` (run completion) and `pullfrog-approval` (review
+ * verdict) commit-status check-runs so they can be required by branch
+ * protection. no-op unless the `status_checks` input is enabled and the run is
+ * on a pull request.
+ *
+ * terminal-only by design: we never create an `in_progress` check. a
+ * hard-cancelled run (SIGKILL) would strand a required check `in_progress` and
+ * block merges forever; an absent required check already blocks merge the same
+ * way while the run is in flight, with no stuck-check failure mode.
+ *
+ *   - `pullfrog` is posted on every PR run: success iff the run finished
+ *     successfully, failure on error/timeout. review-verdict-agnostic.
+ *   - `pullfrog-approval` is posted only when this run produced an approval
+ *     verdict (`toolState.approval`, set by create_pull_request_review),
+ *     anchored to the reviewed sha so a mid-run push leaves the new head
+ *     unapproved until the follow-up re-review reports.
+ *
+ * best-effort throughout: a check-post failure (fork PR head not in the base
+ * repo, transient 5xx, closed PR) must never flip the run's own outcome.
+ */
+export declare function reportStatusChecks(ctx: ToolContext, params: {
+    runSucceeded: boolean;
+}): Promise<void>;

package/dist/yes/index.d.ts

@@ -4,6 +4,21 @@ export declare function range(n: number): number[];
 export declare function range(start: number, end: number): number[];
 export declare function range(n: number, fn: (i: number) => number): number[];
 export declare function schedule(fn: (i: number) => number, count: number): number[];
+/**
+ * read a retry delay (ms) from a thrown HTTP error's response headers, honoring
+ * GitHub's rate-limit backoff hints on octokit errors (`error.response.headers`):
+ *   - `retry-after` (RFC 9110 delta-seconds or an HTTP-date) — an explicit
+ *     backoff directive whenever present (covers secondary rate limits, which
+ *     carry it with `x-ratelimit-remaining > 0`).
+ *   - else `x-ratelimit-reset` (epoch seconds) but ONLY when
+ *     `x-ratelimit-remaining` is `"0"` — GitHub sends the reset header on ~every
+ *     response (~1h ahead), so it's a backoff hint only under actual primary
+ *     rate-limit exhaustion (matching octokit's throttling plugin). without this
+ *     gate a non-rate-limit retried error (e.g. a permissions 403) would be
+ *     wrongly delayed to the reset time.
+ * returns `undefined` when no applicable hint is present/parseable.
+ */
+export declare function retryAfterMs(error: unknown): number | undefined;
 type InferInput<S> = S extends StandardSchemaV1<infer I, any> ? I : never;
 type InferOutput<S> = S extends StandardSchemaV1<any, infer O> ? O : never;
 export interface OpOptions<TReturn = any> {
@@ -11,6 +26,17 @@ export interface OpOptions<TReturn = any> {
     ttl?: number;
     maxItems?: number;
     retries?: number[];
+    /**
+     * honor a server backoff hint on retries: when a retried error carries a
+     * `retry-after` / `x-ratelimit-reset` header, schedule the next retry from
+     * that value (clamped to `[fixed delay, retryAfterCap]`) instead of the fixed
+     * `retries[attempt]` backoff. `true` uses the built-in `retryAfterMs` reader;
+     * a function extracts a delay-ms from a custom error shape. errors without the
+     * header fall back to the fixed backoff.
+     */
+    retryAfter?: boolean | ((error: unknown) => number | undefined);
+    /** cap (ms) on a honored retry-after hint. default 20000. */
+    retryAfterCap?: number;
     cacheHit?: ((key: string) => void) | null;
     cacheMiss?: ((key: string) => void) | null;
     skipCache?: (result: TReturn) => boolean;

package/dist/yes.js

@@ -1022,6 +1022,34 @@ function range(a, b) {
 function schedule(fn, count) {
   return Array.from({ length: count }, (_, i) => fn(i));
 }
+var DEFAULT_RETRY_AFTER_CAP_MS = 2e4;
+function getErrorResponseHeaders(error) {
+  if (error === null || typeof error !== "object") return void 0;
+  const response = error.response;
+  if (response === null || typeof response !== "object") return void 0;
+  const headers = response.headers;
+  if (headers === null || typeof headers !== "object") return void 0;
+  return headers;
+}
+function retryAfterMs(error) {
+  const headers = getErrorResponseHeaders(error);
+  if (!headers) return void 0;
+  const retryAfter = headers["retry-after"];
+  if (typeof retryAfter === "string" && retryAfter.trim() !== "") {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+    const dateMs = Date.parse(retryAfter);
+    if (!Number.isNaN(dateMs)) return Math.max(0, dateMs - Date.now());
+  }
+  if (headers["x-ratelimit-remaining"] === "0") {
+    const reset = headers["x-ratelimit-reset"];
+    if (typeof reset === "string" && reset.trim() !== "") {
+      const resetEpoch = Number(reset);
+      if (Number.isFinite(resetEpoch)) return Math.max(0, resetEpoch * 1e3 - Date.now());
+    }
+  }
+  return void 0;
+}
 function validateSchema(schema, value) {
   const result = schema["~standard"].validate(value);
   if (result instanceof Promise) {
@@ -1159,7 +1187,15 @@ function _op(fn, options) {
               log.info({ key, error, attempt });
             }
           } else {
-            const delay = retries[attempt];
+            let delay = retries[attempt];
+            if (options.retryAfter) {
+              const extract = options.retryAfter === true ? retryAfterMs : options.retryAfter;
+              const hint = extract(error);
+              if (hint !== void 0) {
+                const cap = options.retryAfterCap ?? DEFAULT_RETRY_AFTER_CAP_MS;
+                delay = Math.max(delay, Math.min(cap, hint));
+              }
+            }
             if (namePrefix) {
               log.info(
                 `${namePrefix}attempt ${attempt + 1}/${retries.length + 1} failed, retrying in ${delay}ms`
@@ -1240,5 +1276,6 @@ function _op(fn, options) {
 export {
   op,
   range,
+  retryAfterMs,
   schedule
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",