pr-shepherd 0.53.0 → 0.54.0

package/bin/quota-budgets.d.mts

@@ -0,0 +1,16 @@
+import type { GraphqlQuotaWarningBand } from "./config/load.mts";
+import type { ApiResourceUsage, GraphqlQuotaWarning } from "./types.mts";
+type Usage = Pick<ApiResourceUsage, "resource" | "remaining" | "limit" | "used" | "resetAt">;
+/**
+ * One warning for the budgets that are low on this tick. A GraphQL warning
+ * recommends REST only when REST core is still above its bands. When both are
+ * low, the result uses the later reset and does not recommend a switch.
+ */
+export declare function composeQuotaWarning(input: {
+    graphqlWarning?: GraphqlQuotaWarning;
+    coreWarning?: GraphqlQuotaWarning;
+    graphql?: Usage;
+    core?: Usage;
+    bands: GraphqlQuotaWarningBand[];
+}): GraphqlQuotaWarning | undefined;
+export {};

package/bin/quota-budgets.mjs

@@ -0,0 +1,65 @@
+/** True when this sample is at or below a configured remaining-percent band. */
+function budgetBelowBand(usage, bands) {
+    if (usage === undefined || usage.limit <= 0 || bands.length === 0)
+        return false;
+    return bands.some((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent);
+}
+/**
+ * One warning for the budgets that are low on this tick. A GraphQL warning
+ * recommends REST only when REST core is still above its bands. When both are
+ * low, the result uses the later reset and does not recommend a switch.
+ */
+export function composeQuotaWarning(input) {
+    const graphqlBelow = budgetBelowBand(input.graphql, input.bands);
+    const coreBelow = budgetBelowBand(input.core, input.bands);
+    const graphql = input.graphqlWarning;
+    const core = input.coreWarning;
+    if (graphql && core)
+        return combineWarnings(graphql, core);
+    if (graphql && coreBelow && input.core)
+        return combineWarnings(graphql, describeBudget(input.core, input.bands));
+    if (core && graphqlBelow && input.graphql) {
+        return combineWarnings(core, describeBudget(input.graphql, input.bands));
+    }
+    return graphql ?? core;
+}
+function describeBudget(usage, bands) {
+    const active = bands
+        .filter((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent)
+        .reduce((lowest, band) => (band.remainingPercent < lowest.remainingPercent ? band : lowest));
+    return {
+        resource: usage.resource === "core" ? "core" : "graphql",
+        thresholdPercent: active.remainingPercent,
+        remaining: usage.remaining,
+        limit: usage.limit,
+        ...(usage.used !== undefined && { used: usage.used }),
+        resetAt: usage.resetAt,
+        pollIntervalMinutes: active.pollIntervalMinutes,
+        pollTimeoutMinutes: active.pollIntervalMinutes * 2,
+    };
+}
+function combineWarnings(left, right) {
+    const later = left.resetAt >= right.resetAt ? left : right;
+    const interval = Math.max(left.pollIntervalMinutes, right.pollIntervalMinutes);
+    return {
+        resource: "combined",
+        thresholdPercent: Math.min(left.thresholdPercent, right.thresholdPercent),
+        remaining: later.remaining,
+        limit: later.limit,
+        ...(later.used !== undefined && { used: later.used }),
+        resetAt: later.resetAt,
+        pollIntervalMinutes: interval,
+        pollTimeoutMinutes: interval * 2,
+        budgets: [toBudget(left), toBudget(right)].sort((a, b) => a.resource.localeCompare(b.resource)),
+    };
+}
+function toBudget(warning) {
+    return {
+        resource: warning.resource === "core" ? "core" : "graphql",
+        thresholdPercent: warning.thresholdPercent,
+        remaining: warning.remaining,
+        limit: warning.limit,
+        ...(warning.used !== undefined && { used: warning.used }),
+        resetAt: warning.resetAt,
+    };
+}

package/bin/quota-warning.mjs

@@ -2,5 +2,15 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    const opening = warning.resource === "combined"
+        ? "GitHub's GraphQL and REST core quotas are both low. Keep using pr-shepherd at the cadence below. Do not shift incidental calls between GraphQL and REST."
+        : warning.resource === "core"
+            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh\` calls (\`gh pr view\`, \`gh pr review\`, \`gh api\`) while REST core is below its warning threshold.`
+            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool.`;
+    const resetLabel = warning.resource === "combined"
+        ? "both quotas have reset"
+        : warning.resource === "core"
+            ? "the REST core quota resets"
+            : "the GraphQL quota resets";
+    return `${prefix} ${opening} Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after ${resetLabel} at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/bin/state/check-blockers.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+export interface CheckBlockerRef {
+    owner: string;
+    name: string;
+    number: number;
+    kind: "pull" | "issue";
+}
+export interface CheckBlockerRecord {
+    checkName: string;
+    blocker: CheckBlockerRef;
+    /** Unix seconds. */
+    recordedAt: number;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function formatCheckBlockerRef(blocker: CheckBlockerRef): string;
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export declare function readCheckBlockers(key: StateKey): Promise<CheckBlockerRecord[]>;
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export declare function writeCheckBlocker(key: StateKey, record: CheckBlockerRecord): Promise<boolean>;
+/** Drop one check's record. A missing record is success and does not create a file. */
+export declare function clearCheckBlocker(key: StateKey, checkName: string): Promise<boolean>;
+export {};

package/bin/state/check-blockers.mjs

@@ -0,0 +1,88 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+const FILE = "check-blockers.json";
+export function formatCheckBlockerRef(blocker) {
+    return `${blocker.owner}/${blocker.name}#${blocker.number}`;
+}
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export async function readCheckBlockers(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, FILE), "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return [];
+        const blockers = parsed.blockers;
+        if (!Array.isArray(blockers))
+            return [];
+        return blockers.filter(isRecord);
+    }
+    catch {
+        return [];
+    }
+}
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export async function writeCheckBlocker(key, record) {
+    const blockers = (await readCheckBlockers(key)).filter((item) => item.checkName !== record.checkName);
+    blockers.push(record);
+    return writeAll(key, blockers);
+}
+/** Drop one check's record. A missing record is success and does not create a file. */
+export async function clearCheckBlocker(key, checkName) {
+    const current = await readCheckBlockers(key);
+    const blockers = current.filter((item) => item.checkName !== checkName);
+    if (blockers.length === current.length)
+        return true;
+    return writeAll(key, blockers);
+}
+async function writeAll(key, blockers) {
+    let tmp;
+    try {
+        const path = resolvePrStatePath(key, FILE);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, `${JSON.stringify({ blockers })}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // The failed write may not have created the temp file.
+            }
+        }
+    }
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.checkName === "string" &&
+        record.checkName.length > 0 &&
+        typeof record.recordedAt === "number" &&
+        Number.isFinite(record.recordedAt) &&
+        isBlocker(record.blocker));
+}
+function isBlocker(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const blocker = value;
+    return ((blocker.kind === "pull" || blocker.kind === "issue") &&
+        typeof blocker.owner === "string" &&
+        typeof blocker.name === "string" &&
+        typeof blocker.number === "number" &&
+        Number.isInteger(blocker.number) &&
+        blocker.number > 0);
+}

package/bin/state/graphql-quota-policy.mjs

@@ -32,7 +32,7 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         return { state };
     return {
         warning: {
-            resource: "graphql",
+            resource: sample.resource === "core" ? "core" : "graphql",
             thresholdPercent: active.remainingPercent,
             remaining: effective.remaining,
             limit: effective.limit,

package/bin/state/graphql-quota-warnings.d.mts

@@ -1,6 +1,6 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlQuotaWarning, GraphqlApiUsage } from "../types.mts";
+import type { ApiResourceUsage, GraphqlQuotaWarning } from "../types.mts";
 export declare function evaluateWorktreeGraphqlQuotaWarning(key: {
     owner: string;
     repo: string;
-}, bands: GraphqlQuotaWarningBand[], sample: GraphqlApiUsage, persist: boolean, now?: number): Promise<GraphqlQuotaWarning | undefined>;
+}, bands: GraphqlQuotaWarningBand[], sample: ApiResourceUsage, persist: boolean, now?: number): Promise<GraphqlQuotaWarning | undefined>;

package/bin/state/graphql-quota-warnings.mjs

@@ -10,9 +10,10 @@ const sessionStates = new Map();
 export async function evaluateWorktreeGraphqlQuotaWarning(key, bands, sample, persist, now = Date.now() / 1000) {
     if (bands.length === 0)
         return undefined;
-    const path = await warningStatePath(key);
+    const quotaResource = sample.resource === "core" ? "core" : "graphql";
+    const path = await warningStatePath(key, quotaResource);
     if (path === undefined) {
-        const sessionKey = `${key.owner}/${key.repo}`;
+        const sessionKey = `${key.owner}/${key.repo}/${quotaResource}`;
         if (!persist) {
             return evaluateGraphqlQuotaWarning(bands, sample, sessionStates.get(sessionKey) ?? null, now)
                 .warning;
@@ -50,7 +51,7 @@ async function serializeStateUpdate(key, update) {
     });
     return result;
 }
-async function warningStatePath(key) {
+async function warningStatePath(key, resource) {
     let worktreeKey;
     try {
         worktreeKey = await getWorktreeKey();
@@ -58,7 +59,7 @@ async function warningStatePath(key) {
     catch {
         return undefined;
     }
-    return join(resolveRepoStateDir(key), "worktrees", `${worktreeKey}-graphql-quota-warnings.json`);
+    return join(resolveRepoStateDir(key), "worktrees", `${worktreeKey}-${resource}-quota-warnings.json`);
 }
 async function readState(path) {
     try {

package/bin/types/api-usage.d.mts

@@ -5,6 +5,8 @@ export interface ApiResourceUsage {
     used?: number;
     remaining: number;
     resetAt: number;
+    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
+    credentialFingerprint?: string;
 }
 export interface GraphqlApiUsage extends ApiResourceUsage {
     /** Exact sum reported by rateLimit.cost for GraphQL queries in this command. */
@@ -13,8 +15,15 @@ export interface GraphqlApiUsage extends ApiResourceUsage {
     unmeasuredRequestCount: number;
     /** Exact sum reported by rateLimit.nodeCount for measured GraphQL queries. */
     nodeCount: number;
-    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
-    credentialFingerprint?: string;
+}
+/** One budget inside a combined GraphQL and REST core warning. */
+export interface QuotaWarningBudget {
+    resource: "graphql" | "core";
+    thresholdPercent: number;
+    remaining: number;
+    limit: number;
+    used?: number;
+    resetAt: number;
 }
 export interface ApiUsage {
     credentialSources: string[];
@@ -22,7 +31,7 @@ export interface ApiUsage {
     rest?: ApiResourceUsage[];
 }
 export interface GraphqlQuotaWarning {
-    resource: "graphql";
+    resource: "graphql" | "core" | "combined";
     thresholdPercent: number;
     remaining: number;
     limit: number;
@@ -30,4 +39,6 @@ export interface GraphqlQuotaWarning {
     resetAt: number;
     pollIntervalMinutes: number;
     pollTimeoutMinutes: number;
+    /** Both budgets when GraphQL and REST core are low together. */
+    budgets?: QuotaWarningBudget[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.54.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.54.0", "pr-shepherd-mcp"]
   }
 }