pullfrog 0.1.46 → 0.1.48

package/dist/utils/billingErrors.d.ts

@@ -13,8 +13,8 @@
  * 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
+ * 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.
@@ -37,28 +37,45 @@ export declare class BillingError extends Error {
 }
 /**
  * Transient service failures from `/api/proxy-token` (503: partial OpenRouter
- * usage sync, DB flake, in-flight payment intent). Not the user's fault — the
+ * 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 declare class TransientError extends Error {
     constructor(message: string);
 }
+/**
+ * Canonical paused-run paywall body (billing model v2). Single source of truth so
+ * the two surfaces that show it can never drift: the trigger-time comment (a run
+ * refused before it starts, `triggerWorkflow.postPaywallComment`) and the mid-run
+ * 402 render (`formatBillingErrorSummary` via `renderRunError`). `url` is the
+ * caller's billing surface (each passes its own, internal plan page vs console).
+ */
+export declare function commercialPaywallBody(params: {
+    reason: "commercial" | "subscription_unpaid";
+    ownerLogin: string;
+    url: string;
+}): string;
+/** commercial-gate copy for action runs, linked to the account billing card. */
+export declare function formatCommercialGateSummary(params: {
+    reason: "commercial" | "subscription_unpaid";
+    ownerLogin: string;
+}): string;
 /**
  * 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
+ *   - 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
+ *   - 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
+ *   - 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
+ *     wallet balance. Frame as
+ *     "add a card to continue", link to `#billing` 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
@@ -69,7 +86,7 @@ export declare class TransientError extends Error {
  *     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
+ *     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.
@@ -80,6 +97,6 @@ export declare function formatBillingErrorSummary(error: BillingError, owner: st
 /**
  * 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.
+ * failed, this branch is "our fault, retry shortly", not theirs.
  */
 export declare function formatTransientErrorSummary(error: TransientError, owner: string): string;

package/dist/utils/payload.d.ts

@@ -1,4 +1,4 @@
-import type { PayloadEvent } from "../external.ts";
+import { type PayloadEvent } from "../external.ts";
 import type { RepoSettings } from "./runContext.ts";
 export declare const JsonPayload: import("arktype/internal/variants/object.ts").ObjectType<{
     "~pullfrog": true;
@@ -6,6 +6,7 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     prompt: string;
     model?: string | undefined;
     modelExplicit?: boolean | undefined;
+    effort?: string | number | undefined;
     triggerer?: string | undefined;
     baseInstructions?: string | undefined;
     eventInstructions?: string;
@@ -22,12 +23,16 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
         id: string;
         type: "issue" | "review";
     } | undefined;
+    checkRun?: {
+        id: string;
+    } | undefined;
     generateSummary?: boolean | undefined;
 }, {}>;
 export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
     prompt?: string | undefined;
     prompt_file?: string | undefined;
     model?: string | undefined;
+    effort?: string | undefined;
     timeout?: string | undefined;
     push?: "disabled" | "enabled" | "restricted" | undefined;
     shell?: "disabled" | "enabled" | "restricted" | undefined;
@@ -50,6 +55,7 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
     version: string;
     model: string | undefined;
     modelExplicit: boolean;
+    effort: number | undefined;
     prompt: string;
     triggerer: string | undefined;
     baseInstructions: string | undefined;
@@ -68,10 +74,14 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
         id: string;
         type: "issue" | "review";
     } | undefined;
+    checkRun: {
+        id: string;
+    } | undefined;
     generateSummary: boolean | undefined;
     push: import("../external.ts").PushPermission;
     shell: import("../external.ts").ShellPermission;
-    statusChecks: boolean;
+    runStatusCheck: boolean;
+    approvalCheck: boolean;
     progressComments: boolean;
     proxyModel: string | undefined;
 };

package/dist/utils/runContext.d.ts

@@ -23,6 +23,7 @@ export interface LearningsHeading {
 }
 export interface RepoSettings {
     model: string | null;
+    effort: number | null;
     modes: Mode[];
     setupScript: string | null;
     postCheckoutScript: string | null;
@@ -34,6 +35,7 @@ export interface RepoSettings {
     autoMergeEnabled: boolean;
     signedCommits: boolean;
     progressComments: boolean;
+    statusChecks: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;
     learningsHeadings: LearningsHeading[];
@@ -43,11 +45,20 @@ export interface RepoSettings {
     xrepoLearningsHeadings: LearningsHeading[];
 }
 /**
- * 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.
+ * Account-level card signal. Orthogonal to repo-level OSS and Pro status.
+ * Mirrors the server's legacy-named `AccountPlan` in `utils/billing.ts`.
+ * `"none"` = no card; `"payg"` = card on file.
  */
 export type AccountPlan = "none" | "payg";
+/**
+ * The org commercial gate's refusal (billing model v2). Set when run-context
+ * returns 402 for a `paused`/`unpaid` org — the backstop for manual re-runs and
+ * self-configured triggers that never hit reserveRun. main.ts stops before
+ * installing the agent or loading account secrets and writes actionable copy.
+ * A forked action can bypass this response, so proxy-token enforces the same
+ * verdict before issuing a Pullfrog Router key.
+ */
+export type CommercialRefusal = "commercial" | "subscription_unpaid";
 export interface RunContext {
     settings: RepoSettings;
     apiToken: string;
@@ -55,6 +66,7 @@ export interface RunContext {
     plan: AccountPlan;
     proxyModel?: string | undefined;
     dbSecrets?: Record<string, string> | undefined;
+    commercialRefused?: CommercialRefusal | undefined;
     /**
      * the server tried and failed to materialize Pullfrog-stored secrets (or we
      * never got a usable response at all). distinct from an absent `dbSecrets`,

package/dist/utils/runContextData.d.ts

@@ -1,6 +1,6 @@
 import type { Octokit } from "@octokit/rest";
 import { type OctokitWithPlugins } from "./github.ts";
-import { type AccountPlan, type RepoSettings } from "./runContext.ts";
+import { type AccountPlan, type CommercialRefusal, type RepoSettings } from "./runContext.ts";
 export interface RunContextData {
     repo: {
         owner: string;
@@ -13,6 +13,7 @@ export interface RunContextData {
     plan: AccountPlan;
     proxyModel?: string | undefined;
     dbSecrets?: Record<string, string> | undefined;
+    commercialRefused?: CommercialRefusal | undefined;
     /** stored secrets couldn't be materialized for this run — not the same as
      * the user having none. see `RunContext.secretsUnavailable`. */
     secretsUnavailable?: boolean | undefined;

package/dist/utils/runEffort.d.ts

@@ -0,0 +1,27 @@
+/**
+ * reasoning effort for a run: a stored POSITION landed on the ladder of the
+ * model that actually runs. shared by both harnesses and the startup log so
+ * they can't disagree — the log must never claim a level the agent didn't send.
+ * see wiki/effort.md.
+ */
+import { type EffortPosition } from "../effort.ts";
+import { type ModelAlias } from "../models.ts";
+import type { ResolvedPayload } from "./payload.ts";
+export interface RunEffort {
+    /** the position this run resolves at — the stored one, or the default. */
+    position: EffortPosition;
+    /** false when nothing was configured and `position` is the default. */
+    configured: boolean;
+    /**
+     * the rung the harness sends — always one the model published. undefined when
+     * the model publishes no rungs or we can't place it at all; either way the
+     * flag is omitted.
+     */
+    rung: string | undefined;
+    /** the catalog alias the ladder came from, if we recognized one. */
+    alias: ModelAlias | undefined;
+}
+export declare function resolveRunEffort(ctx: {
+    payload: ResolvedPayload;
+    resolvedModel?: string | undefined;
+}): RunEffort;

package/dist/utils/runStartupLog.d.ts

@@ -1,12 +1,12 @@
 /**
  * Startup log formatting for the resolver pipeline. Computes the
- * "model / agent / push / shell / timeout" block that main.ts prints
+ * "model / effort / agent / push / shell / timeout" block that main.ts prints
  * after resolving the agent + model + payload.
  */
 import type { ResolvedPayload } from "./payload.ts";
 /**
- * Emit the startup block ("» model / agent / push / shell / timeout") after
- * the agent and model are resolved. Single side-effect; no return.
+ * Emit the startup block ("» model / effort / agent / push / shell / timeout")
+ * after the agent and model are resolved. Single side-effect; no return.
  */
 export declare function logRunStartup(ctx: {
     payload: ResolvedPayload;

package/dist/utils/runStatusCheck.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Single source of truth for the `pullfrog` commit-status check-run — the row a PR's
+ * checks list shows while a run is in flight and after it ends.
+ *
+ * Pullfrog dispatches its workflow with `ref: <default branch>`, so the GitHub Actions
+ * run attaches its check suite to the default branch head and never to the PR head.
+ * Nothing about a run is therefore visible from the PR itself unless we post this
+ * check-run against the PR head sha ourselves.
+ *
+ * Created `in_progress` by the server at dispatch — before the runner boots, and
+ * upstream of every action-side failure that would otherwise leave the PR silent
+ * (billing 402, token resolution, bad model slug, missing provider key). Moved to a
+ * terminal conclusion by whichever of three actors reaches it first, all calling
+ * `finalizeRunStatusCheck`:
+ *
+ *   1. the action at run end (`reportStatusChecks`)
+ *   2. the `workflow_run.completed` webhook (covers cancel / SIGKILL / early throw)
+ *   3. the hourly stuck-run reaper (covers a dropped webhook)
+ *
+ * That three-layer close-out is what makes an `in_progress` check safe here: a check
+ * stranded `in_progress` on a required branch-protection rule would block merges
+ * forever, which is why this file did not exist before.
+ */
+/**
+ * the run-lifecycle check. verdict-agnostic — it reports that a run happened, not what it
+ * found. this string IS the branch-protection identifier, so changing it silently breaks
+ * any repo that required the old name.
+ */
+export declare const RUN_STATUS_CHECK_NAME = "Pullfrog";
+/** the review-verdict check. opt-in, terminal-only, and deliberately separate from the above. */
+export declare const APPROVAL_CHECK_NAME = "Pullfrog approval";
+/**
+ * The terminal states we report. Exactly GitHub's check-run `conclusion` enum, which
+ * happens to be `WorkflowRunStatus` minus `running` — so the server can map a finished
+ * run's status straight across (`checkConclusionFromStatus` in utils/workflowRunStatus.ts).
+ */
+export type RunStatusCheckConclusion = "success" | "failure" | "cancelled" | "timed_out" | "action_required" | "neutral" | "skipped" | "stale";
+/**
+ * Parse the on-the-wire `{ id: string }` shape (the form carried in `JsonPayload`) into
+ * a check-run id. Mirrors `parseProgressComment` — returns undefined when the id isn't a
+ * positive integer so callers can short-circuit cleanly.
+ */
+export declare function parseCheckRunId(raw: {
+    id: string;
+} | null | undefined): number | undefined;
+interface CheckRunResponse {
+    data: {
+        id: number;
+    };
+}
+type CheckRunStatus = "queued" | "in_progress" | "completed";
+type CheckRunOutput = {
+    title: string;
+    summary: string;
+};
+type CreateCheckRunParams = {
+    owner: string;
+    repo: string;
+    name: string;
+    head_sha: string;
+    status?: CheckRunStatus;
+    conclusion?: RunStatusCheckConclusion;
+    details_url?: string;
+    output?: CheckRunOutput;
+};
+type UpdateCheckRunParams = {
+    owner: string;
+    repo: string;
+    check_run_id: number;
+    status?: CheckRunStatus;
+    conclusion?: RunStatusCheckConclusion;
+    details_url?: string;
+    output?: CheckRunOutput;
+};
+export interface RunStatusCheckOctokit {
+    rest: {
+        checks: {
+            create: (params: CreateCheckRunParams) => Promise<CheckRunResponse>;
+            update: (params: UpdateCheckRunParams) => Promise<CheckRunResponse>;
+            get: (params: {
+                owner: string;
+                repo: string;
+                check_run_id: number;
+            }) => Promise<{
+                data: {
+                    status: string;
+                };
+            }>;
+            listForRef: (params: {
+                owner: string;
+                repo: string;
+                ref: string;
+                check_name?: string;
+                status?: "queued" | "in_progress" | "completed";
+            }) => Promise<{
+                data: {
+                    check_runs: {
+                        id: number;
+                    }[];
+                };
+            }>;
+        };
+    };
+}
+/**
+ * Post the `in_progress` check-run on `headSha` and return its id for the finalizers.
+ *
+ * Best-effort: a transient 5xx, a repo that revoked `checks: write`, or a PR whose head
+ * has already been deleted must never stop a run from dispatching. Returns undefined on
+ * failure, which every caller treats as "no check to finalize".
+ */
+export declare function createRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    headSha: string;
+    detailsUrl: string | undefined;
+}): Promise<number | undefined>;
+/**
+ * Move an existing check-run to its terminal conclusion.
+ *
+ * A PATCH, not a second create: `POST /check-runs` with the same name + sha creates a
+ * SECOND row rather than replacing the first, so creating twice would show the PR two
+ * contradictory `pullfrog` rows. (That is a real bug today — `finalizeSuccessRun` posts
+ * success and a later throw posts failure, both as fresh rows.)
+ */
+export declare function finalizeRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    checkRunId: number;
+    conclusion: RunStatusCheckConclusion;
+    detailsUrl: string | undefined;
+    reviewUrl?: string | undefined;
+}): Promise<void>;
+/**
+ * Post an already-terminal check-run in one call.
+ *
+ * The fallback for runs that never got a server-created check to update: a rolling
+ * deploy where the dispatch payload predates `checkRun`, or a workflow invoked outside
+ * Pullfrog's own dispatch path (`prompt_file`, a hand-written step).
+ */
+export declare function createTerminalRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    headSha: string;
+    conclusion: RunStatusCheckConclusion;
+    detailsUrl: string | undefined;
+    reviewUrl?: string | undefined;
+}): Promise<void>;
+/**
+ * Whether this check still needs finalizing.
+ *
+ * The server-side close-outs are BACKSTOPS: they exist for runs the action could not
+ * finalize itself. Firing them unconditionally is actively harmful, because the action
+ * writes a richer summary than they can — it knows the review URL, they do not — so a
+ * blind re-PATCH silently strips that link seconds after it appears. It also resets
+ * `completed_at`, discarding the duration GitHub renders as "Successful in 2m".
+ *
+ * Returns false when GitHub cannot be reached: a backstop that cannot confirm the check
+ * is unfinished must not overwrite a good one.
+ */
+export declare function runStatusCheckNeedsFinalizing(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    checkRunId: number;
+}): Promise<boolean>;
+export {};

package/dist/utils/statusChecks.d.ts

@@ -1,24 +1,21 @@
 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.
+ * post the `Pullfrog` (run lifecycle) and `Pullfrog approval` (review verdict)
+ * commit-status check-runs.
  *
- * 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 on by default (`Repo.statusChecks`). the server already created it
+ *     `in_progress` at dispatch, so the work here is a PATCH to its terminal conclusion —
+ *     see `runStatusCheck.ts` for why a second create would leave two contradictory rows.
+ *     the terminal-create fallback covers a payload with no `checkRun` (older server
+ *     build mid-rolling-deploy, or a workflow driven outside Pullfrog's dispatch path).
+ *   - `Pullfrog approval` stays opt-in (`status_checks: enabled`) and terminal-only:
+ *     it asserts a review verdict, which only exists once a run produces one. anchored
+ *     to the exact reviewed sha so a mid-run push leaves the new head unapproved until
+ *     a follow-up re-review reports.
  *
- *   - `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.
+ * best-effort throughout: a check-post failure (transient 5xx, closed PR, revoked
+ * permission) must never flip the run's own outcome. the `workflow_run.completed` webhook
+ * and both stuck-run reaper sweeps close out a check this function fails to finalize.
  */
 export declare function reportStatusChecks(ctx: ToolContext, params: {
     runSucceeded: boolean;

package/package.json

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