@edgehero/pi-dispatch-receiver 4.3.1 → 5.0.0

package/src/poller.mjs

@@ -75,8 +75,9 @@
  *                                      close event (issue #231). Deliberately OUTSIDE the touched
  *                                      family, with a short ~1-day TTL of its own: the counter must
  *                                      decay with the outage it measures, not live with the repo.
- * All keys carry a ~35-day TTL and are refreshed TOGETHER after each successful repo poll. 35 days
- * deliberately exceeds the 31-day gh-* jobId retention (REQ-DEDUP-BY-DELIVERY-GUID): the cursor and
+ * All keys carry a ~35-day TTL (`CURSOR_TTL_SECONDS`) and are refreshed TOGETHER after each successful
+ * repo poll. It deliberately exceeds the gh-* jobId retention (`FORGE_JOB_RETENTION_S`,
+ * REQ-DEDUP-BY-DELIVERY-GUID) by four days, and is derived from it: the cursor and
  * the jobId are the poller's two dedup layers, and refreshing/expiring the cursor family as a unit
  * means an actively polled repo always has a coherent live family, while a repo REMOVED from the set
  * decays cleanly past both windows and re-arms from scratch if it ever returns. A partially expired
@@ -111,6 +112,9 @@ import { configError } from "@edgehero/pi-dispatch/config";
 import { judgeValkeyAtStart, makeRedisClient, parseConnection, valkeyClientContext } from "@edgehero/pi-dispatch/connection";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { enqueueGitHubJob, makeQueue } from "@edgehero/pi-dispatch/queue";
+import { FORGE_JOB_RETENTION_S } from "@edgehero/pi-dispatch/retention";
+import { trySteer } from "./steer.mjs";
+import { holdAfterDedup, holdBeforeLabel } from "./held.mjs";
 import { filter, hasCloseTriggers, wantsCloserAuthority } from "./filter.mjs";
 import { makeResolveGitHubAuthority } from "./github-members.mjs";
 import { parseSubset } from "./receiver.mjs";
@@ -118,8 +122,10 @@ import { loadPollerConfig } from "./poller-config.mjs";
 import { retryIdentity } from "./boot-retry.mjs";
 
 const API_URL = "https://api.github.com";
-// 35 days: strictly outlives the 31-day gh-* job retention -- see the header's cursor/TTL section.
-const CURSOR_TTL_SECONDS = 35 * 24 * 3600;
+// In SECONDS (`EX`): strictly outlives the gh-* job retention (`FORGE_JOB_RETENTION_S`) by four days, derived so that
+// lengthening the retention cannot leave the cursor the shorter of the poller's two dedup layers -- see the header's
+// cursor/TTL section.
+export const CURSOR_TTL_SECONDS = FORGE_JOB_RETENTION_S + 4 * 86_400;
 // Installation repo-list refresh cadence, in cycles (~10 minutes at the default interval): fresh
 // enough that a newly installed repo starts polling soon, cheap enough to be invisible in the quota.
 const DISCOVERY_EVERY = 10;
@@ -347,7 +353,9 @@ export async function startPoller(env = process.env, deps = {}) {
 			}
 
 			cycleNo++;
-			out({ event: "poll_cycle", repos: repos.length, fetched: stats.fetched, enqueued: stats.enqueued, notModified: stats.notModified, ms: now() - startedAt });
+			// `steered` (issue #646) only when a comment steered a run this cycle, so a cycle line without one is unchanged;
+			// `held` (issue #638) by the same rule, when a reply was held for a parking run.
+			out({ event: "poll_cycle", repos: repos.length, fetched: stats.fetched, enqueued: stats.enqueued, notModified: stats.notModified, ...(stats.steered > 0 ? { steered: stats.steered } : {}), ...(stats.held > 0 ? { held: stats.held } : {}), ms: now() - startedAt });
 			if (stopped) break;
 
 			// The delay: the configured interval, raised by any x-poll-interval hint seen this cycle, and
@@ -390,7 +398,7 @@ export async function startPoller(env = process.env, deps = {}) {
 }
 
 function emptyStats() {
-	return { fetched: 0, enqueued: 0, notModified: 0, minDelaySeconds: 0 };
+	return { fetched: 0, enqueued: 0, notModified: 0, minDelaySeconds: 0, steered: 0, held: 0 };
 }
 
 /** 1-30s of jitter for the post-rate-limit wake, spread by the injected `random`. */
@@ -932,9 +940,10 @@ async function pollReviews(ctx, api, repo, open, stats) {
  * stranger's close is the filter's own `closer-not-allowed` drop and the events cursor advances
  * past it -- an unauthorized close never wedges the feed.
  *
- * An INDETERMINATE lookup has no honest verdict, and the webhook arm's answer (503, forge
- * redelivers) has no analogue here -- the poller IS its own redelivery. So: bounded retry, then a
- * loud skip. Below the bound this THROWS, on purpose, into pollLabelEvents' scoped catch: the cycle
+ * An INDETERMINATE lookup has no honest verdict, and the webhook arm's answer (a 503, which GitHub
+ * never resends, so it waits for a hand redelivery) has no analogue here -- the poller IS its own
+ * retry. So: bounded retry, then a loud skip. Below the bound this THROWS, on purpose, into
+ * pollLabelEvents' scoped catch: the cycle
  * logs `poll_close_gate_retry`, the events cursor is still sitting BEFORE this event (the caller
  * advances it only after a handler returns), so the next cycle retries exactly this close -- and
  * only the EVENTS feed ends for the cycle, because a monotone cursor cannot skip an entry and come
@@ -973,24 +982,62 @@ async function gate(ctx, eventName, payload, deliveryId, stats) {
 
 	const result = filter(eventName, subset, ctx.cfg, ctx.selfId, deliveryId, closerAuthorized);
 	if (!result.enqueue) {
-		ctx.out({ event: "dropped", delivery: deliveryId, reason: result.reason });
-		return;
+		// Issue #638, the webhook arms' `heldBeforeLabelOr` at the poller's seam: a phrase-free reply that missed only the
+		// parked marker is held for an awaitInput run parking on its target; otherwise today's drop.
+		let rescued = null;
+		if (result.heldCandidate !== undefined) {
+			const c = result.heldCandidate;
+			rescued = await holdBeforeLabel({ redis: ctx.redis, candidate: c, kind: "github", now: ctx.now, log: ctx.out, delivery: deliveryId, target: `${c.target.type}#${c.target.number}` });
+			if (rescued !== null && rescued.enqueue !== true) {
+				stats.held = (stats.held ?? 0) + 1;
+				return;
+			}
+		}
+		// A run just parked on the target (held.mjs): the reply is the parked reply it would have been, enqueued below.
+		if (rescued?.enqueue !== true) {
+			ctx.out({ event: "dropped", delivery: deliveryId, reason: result.reason });
+			return;
+		}
 	}
-	const replicas = result.job.replicas ?? 1;
+	// Comment steering (issue #646), the webhook arms' `steerOrEnqueue` at the poller's seam: the same `trySteer` over
+	// the poller's own Valkey client, before any enqueue, only for a job the filter marked `steerMode`. A null falls
+	// through to the enqueue below unchanged, minus the marker.
+	let job = result.enqueue ? result.job : result.heldCandidate;
+	if (job.steerMode !== undefined) {
+		const { steerMode: mode, ...rest } = job;
+		const steered = await trySteer({ redis: ctx.redis, job, kind: "github", now: ctx.now, log: ctx.out });
+		// A retried cycle's comment steered before: trySteer logged `steer_redelivered`; nothing to enqueue.
+		if (steered?.redelivered === true) return;
+		if (steered !== null) {
+			stats.steered = (stats.steered ?? 0) + 1;
+			ctx.out({ event: "steered", delivery: deliveryId, repo: job.repo, target: `${job.target.type}#${job.target.number}`, mode, runs: steered.steered, runIds: steered.runIds });
+			return;
+		}
+		job = rest;
+	}
+	const replicas = job.replicas ?? 1;
 	let created = 0;
+	const deduplicated = [];
 	for (let i = 1; i <= replicas; i++) {
-		const r = await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		const r = await ctx.enqueue(replicas > 1 ? { ...job, replica: i } : job);
 		// Issue #289, the receiver arms' honesty rule at the poller's own seam: a semantic-window swallow
 		// gets its own line with the surviving id, `enqueued` counts only what was CREATED, and a bare-id
 		// return from an enqueue seam predating the shape counts as created -- the old behaviour exactly.
 		if (r && typeof r === "object" && r.deduplicated === true) {
-			ctx.out({ event: "deduplicated", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, jobId: r.jobId, survivingJobId: r.survivingJobId });
+			ctx.out({ event: "deduplicated", delivery: deliveryId, repo: job.repo, target: `${job.target.type}#${job.target.number}`, flow: job.flow, jobId: r.jobId, survivingJobId: r.survivingJobId });
+			deduplicated.push({ jobId: r.jobId, survivingJobId: r.survivingJobId });
 		} else {
 			created += 1;
 		}
 	}
+	// Issue #638: a resume comment the window swallowed against an awaitInput run still going is held for that run's
+	// settle (held.mjs asks nothing of Valkey unless the job and the swallow say so); `held` lines are its own.
+	if (deduplicated.length > 0) {
+		const held = await holdAfterDedup({ redis: ctx.redis, job, kind: "github", outcome: { created, deduplicated }, now: ctx.now, log: ctx.out, delivery: deliveryId, target: `${job.target.type}#${job.target.number}` });
+		if (held !== null) stats.held = (stats.held ?? 0) + 1;
+	}
 	stats.enqueued += created;
-	if (created > 0) ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas: created });
+	if (created > 0) ctx.out({ event: "enqueued", delivery: deliveryId, repo: job.repo, target: `${job.target.type}#${job.target.number}`, flow: job.flow, replicas: created });
 }
 
 /**

package/src/predicate.mjs

@@ -60,3 +60,40 @@ export function matchesRule(L, rule) {
 export function escapeRegExp(literal) {
 	return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+/**
+ * Which way a phrase comment steers a running job (issue #646): `"followUp"` when the word right after the FIRST
+ * occurrence of the phrase is `later` (lowercase, a whole word, separated from the phrase by spaces or tabs only),
+ * else `"steer"`. The caller has already established that the body holds the phrase.
+ *
+ * The first occurrence only, and the word immediately after it only: anywhere else `later` is ordinary prose ("fix it
+ * later today" further down must not turn a correction into a follow-up). A newline between the phrase and the word
+ * does not count, because a phrase on its own line followed by a paragraph that opens with "Later" or "later" is
+ * prose, not a grammar word. Case-sensitive for the same reason. The delivered text is always the whole body: the
+ * word chooses the mode, it is never stripped.
+ */
+export function steerModeOf(body, phrase) {
+	if (typeof body !== "string" || typeof phrase !== "string" || phrase === "") return "steer";
+	const at = body.indexOf(phrase);
+	if (at < 0) return "steer";
+	return /^[ \t]+later(?=\s|$)/.test(body.slice(at + phrase.length)) ? "followUp" : "steer";
+}
+
+/**
+ * A filter's drop result as the receiver sees it (issue #638, DES-AWAIT-INPUT-ENDS-THE-JOB). A comment route that
+ * dropped a phrase-free reply ONLY because the parked marker was not on the issue yet returns `heldResolved`, the route
+ * it would have taken with the marker; this turns that into `heldCandidate`, the JOB that route builds, through the
+ * filter's own `build`, and returns every other drop exactly as it came (no key added, so its bytes are today's). A
+ * candidate whose build refuses (an Azure work item with no repository) is no candidate.
+ *
+ * Why the filter says it and not the receiver: the agent posts its question itself and only then calls the tool, so a
+ * person can answer in the seconds before the run has parked and the marker is set. Whether that reply would have
+ * resumed the run is a question about the trigger file and the payload, which only the filter reads; whether a run is
+ * parking right now is a Valkey question, which only the receiver asks. Still a drop: the filter stays pure.
+ */
+export function heldCandidateOr(dropped, build) {
+	if (dropped?.heldResolved === undefined) return dropped;
+	const { heldResolved, ...drop } = dropped;
+	const built = build(heldResolved);
+	return built?.enqueue === true ? { ...drop, heldCandidate: built.job } : drop;
+}