@cat-factory/server 0.322.0 → 0.323.0

package/dist/modules/publicApi/decisions/resumeBudget.d.ts

@@ -0,0 +1,22 @@
+import type { ExecutionInstance } from '@cat-factory/contracts';
+/**
+ * How many resumes this run's review has already spent.
+ *
+ * Read off the RUN rather than tracked per caller, so the budget belongs to the review: a caller
+ * that alternates keys, retries from a second process, or resumes after the app already did gets
+ * the same answer. Taken as the maximum across the steps because a chain can carry more than one
+ * `pr-reviewer` step and the count lives on each step's own review state.
+ */
+export declare function prReviewResumesSpent(execution: Pick<ExecutionInstance, 'steps'>): number;
+/**
+ * The refusal when a run's review has spent its public resume budget, or `null` while it has some
+ * left.
+ *
+ * The message names the evidence a caller should read INSTEAD of resuming again (`slices` against
+ * `reportedSlices` says whether every slice is in, `lastActivityAt` whether anything is still
+ * moving) plus the two exits. It carries no `details.reason`, like the wrong-status refusal beside
+ * it: what a caller branches on is `resumeAttempts` against `maxResumeAttempts` on the decision
+ * itself, which it can read BEFORE spending a call rather than after being refused one.
+ */
+export declare function prReviewResumeRefusal(execution: Pick<ExecutionInstance, 'steps'>): string | null;
+//# sourceMappingURL=resumeBudget.d.ts.map

package/dist/modules/publicApi/decisions/resumeBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeBudget.d.ts","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/resumeBudget.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAa/D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG,MAAM,CAKxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAQhG"}

package/dist/modules/publicApi/decisions/resumeBudget.js

@@ -0,0 +1,41 @@
+import { PUBLIC_PR_REVIEW_MAX_RESUME_ATTEMPTS } from '@cat-factory/contracts';
+// The ceiling on `POST /api/v1/runs/:runId/decisions/pr-review/resume`, kept out of the route so
+// the rule is unit-testable: the state it reasons about (several resumed reviews across a run's
+// steps) is not reachable through the wire, since a resume needs a reviewer wedged mid-review.
+//
+// WHY THE PUBLIC SURFACE BOUNDS A LOOP THE APP DOES NOT. A resume STOPS the running reviewer and
+// dispatches a fresh container, so an uncapped one is unbounded spend on a run nobody is watching:
+// a poller resuming every ten minutes on a review that legitimately takes twenty kills it, over
+// and over, each time it is about to finish. A person clicking Resume in the review window is
+// looking at what they nudged, which is the judgement a headless caller cannot supply, so the
+// ceiling belongs to the surface without the eyes rather than to the engine.
+/**
+ * How many resumes this run's review has already spent.
+ *
+ * Read off the RUN rather than tracked per caller, so the budget belongs to the review: a caller
+ * that alternates keys, retries from a second process, or resumes after the app already did gets
+ * the same answer. Taken as the maximum across the steps because a chain can carry more than one
+ * `pr-reviewer` step and the count lives on each step's own review state.
+ */
+export function prReviewResumesSpent(execution) {
+    return execution.steps.reduce((most, step) => Math.max(most, step.prReview?.resumeAttempts ?? 0), 0);
+}
+/**
+ * The refusal when a run's review has spent its public resume budget, or `null` while it has some
+ * left.
+ *
+ * The message names the evidence a caller should read INSTEAD of resuming again (`slices` against
+ * `reportedSlices` says whether every slice is in, `lastActivityAt` whether anything is still
+ * moving) plus the two exits. It carries no `details.reason`, like the wrong-status refusal beside
+ * it: what a caller branches on is `resumeAttempts` against `maxResumeAttempts` on the decision
+ * itself, which it can read BEFORE spending a call rather than after being refused one.
+ */
+export function prReviewResumeRefusal(execution) {
+    const spent = prReviewResumesSpent(execution);
+    if (spent < PUBLIC_PR_REVIEW_MAX_RESUME_ATTEMPTS)
+        return null;
+    return (`This review has already been resumed ${spent} times, which is all this API will spend on ` +
+        'one review. Read `slices`, `reportedSlices` and `lastActivityAt` to see whether it is still ' +
+        'working; resume it again from the app, or end the run with POST /api/v1/tasks/:taskId/stop.');
+}
+//# sourceMappingURL=resumeBudget.js.map

package/dist/modules/publicApi/decisions/resumeBudget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeBudget.js","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/resumeBudget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,wBAAwB,CAAA;AAG7E,iGAAiG;AACjG,gGAAgG;AAChG,+FAA+F;AAC/F,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,gGAAgG;AAChG,8FAA8F;AAC9F,8FAA8F;AAC9F,6EAA6E;AAE7E;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAA2C;IAC9E,OAAO,SAAS,CAAC,KAAK,CAAC,MAAM,CAC3B,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,IAAI,CAAC,CAAC,EAClE,CAAC,CACF,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAA2C;IAC/E,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAA;IAC7C,IAAI,KAAK,GAAG,oCAAoC;QAAE,OAAO,IAAI,CAAA;IAC7D,OAAO,CACL,wCAAwC,KAAK,8CAA8C;QAC3F,8FAA8F;QAC9F,6FAA6F,CAC9F,CAAA;AACH,CAAC"}