@edgehero/pi-dispatch-receiver 4.3.0 → 5.0.0

package/src/held.mjs

@@ -0,0 +1,120 @@
+/**
+ * Held replies, the receiver's side (issue #638, DES-AWAIT-INPUT-ENDS-THE-JOB; keys and scripts in the worker's
+ * held-replies.mjs): an answer to a run that is parking right now is held for that run's settle instead of being lost.
+ *
+ * TWO WAYS A REPLY USED TO BE LOST, two entry points here, both shared by the four webhook arms and the poller so no
+ * forge can weaken one alone (the four-copies doctrine of receiver.mjs):
+ *   (a) `holdAfterDedup`: a resume comment for an awaitInput trigger that the semantic window deduplicated against a
+ *       run still going (the parked run finishing, or a resumed run). Held under the SURVIVING job's id, which is the
+ *       run id the worker registered: the window is keyed per target and flow, so the survivor is that run.
+ *   (b) `holdBeforeLabel`: a phrase-free reply on an issue that the filter dropped ONLY because the parked marker was
+ *       not set yet (the filter's `heldCandidate`). Held under every awaitInput run live on the target.
+ * A run is live only while its worker's keeper refreshes it (held-settle.mjs), and the hold script refuses once the run
+ * has settled, so `ok` or `dup` means the run's settle will see the reply; anything else (no live run, `gone`,
+ * `closed`, `full`, a refusal, a Valkey fault) returns null and the caller answers EXACTLY as it did before this
+ * feature: a hold is a rescue for a reply that was going to be lost, never a way to lose one that was not.
+ *
+ * WHAT THE HELD REPLY BECOMES is the worker's call at the run's final outcome: the first one started as a resumed job if
+ * the run parked, dropped (today's coalescing) if it did not. The fallback stored is `fallbackJobOf`, the object the
+ * late steer stores, so "the job this comment would have been" has one spelling.
+ *
+ * Not the steer inbox, deliberately, and never consulted by `trySteer`: see held-replies.mjs for why the keys are apart.
+ * Logs carry the delivery, the kind, the target in the arm's grammar and run ids, never the comment. Never throws.
+ */
+
+import { awaitTargetKeyOf, holdReply, liveAwaitRunsForTarget, recentlyParked } from "@edgehero/pi-dispatch/held-replies";
+import { forgeMessageId } from "@edgehero/pi-dispatch/steer-inbox";
+import { fallbackJobOf } from "./steer.mjs";
+
+/** At most this many live awaitInput runs of one target take a pre-label reply: the steer fanout's bound. */
+export const HELD_FANOUT_LIMIT = 4;
+
+const nowOf = (now) => (typeof now === "function" ? now() : now);
+
+/**
+ * Whether a fanout outcome may hold anything: a COMMENT-matched job armed with both `run.resume` (it continues the
+ * parked session) and `run.awaitInput` (the trigger whose runs park), at least one replica of which the window
+ * swallowed. Free, so the caller asks it before it asks for a Valkey client.
+ */
+export function wantsHoldAfterDedup(job, outcome) {
+	return job?.trigger?.matched?.type === "comment" && job.resume === true && job.awaitInput === true && Array.isArray(outcome?.deduplicated) && outcome.deduplicated.length > 0;
+}
+
+async function holdUnder({ redis, runIds, job, kind, route, now, log, delivery, target }) {
+	const id = forgeMessageId(job?.trigger?.deliveryId);
+	if (id === null) {
+		log({ event: "held_fell_through", delivery, kind, route, reason: "no-delivery-id" });
+		return null;
+	}
+	const entry = { id, at: nowOf(now), route, fallback: fallbackJobOf(job, kind) };
+	const held = [];
+	const outcomes = {};
+	for (const runId of runIds) {
+		const r = await holdReply({ redis, runId, entry, now });
+		const outcome = typeof r === "string" ? r : (r?.error ?? "error");
+		outcomes[outcome] = (outcomes[outcome] ?? 0) + 1;
+		if (r === "ok" || r === "dup") {
+			held.push(runId);
+			log({ event: "held", delivery, repo: job.repo, target, route, runId });
+		}
+	}
+	if (held.length > 0) return { held: held.length, runIds: held };
+	log({ event: "held_fell_through", delivery, kind, route, reason: Object.keys(outcomes).length === 1 ? Object.keys(outcomes)[0] : "mixed", outcomes });
+	return null;
+}
+
+/**
+ * (a) `{ held, runIds }` when at least one surviving run took the reply, else null. `outcome` is `fanout`'s, `job` the
+ * job that was enqueued (no `steerMode`), `target` the arm's own grammar for the log.
+ */
+export async function holdAfterDedup({ redis, job, kind, outcome, now = Date.now, log = () => {}, delivery, target } = {}) {
+	try {
+		if (!wantsHoldAfterDedup(job, outcome)) return null;
+		if (!redis) {
+			log({ event: "held_fell_through", delivery, kind, route: "dedup", reason: "no-client" });
+			return null;
+		}
+		const runIds = [...new Set(outcome.deduplicated.map((d) => d?.survivingJobId).filter((r) => typeof r === "string" && r !== ""))];
+		if (runIds.length === 0) return null;
+		return await holdUnder({ redis, runIds, job, kind, route: "dedup", now, log, delivery, target });
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * (b) `{ held, runIds }` when at least one live awaitInput run on the candidate's target took the reply; `{ enqueue:
+ * true }` when none did but a run PARKED on the target within the last minute (its take raised the parked marker,
+ * held-replies.mjs): the reply was posted before the label and delivered after the take, and is enqueued as the ordinary
+ * parked reply it would have been a moment later (it coalesces against the taken job, or resumes the parked session),
+ * never dropped for the label it raced (review round 2); else null. `candidate` is the filter's `heldCandidate` (the
+ * parked-reply job, `parkedReply: true`).
+ */
+export async function holdBeforeLabel({ redis, candidate, kind, now = Date.now, log = () => {}, delivery, target } = {}) {
+	try {
+		if (!candidate || typeof candidate !== "object" || candidate.parkedReply !== true) return null;
+		const targetKey = awaitTargetKeyOf({ ...candidate, kind });
+		if (targetKey === null) return null;
+		if (!redis) {
+			log({ event: "held_fell_through", delivery, kind, route: "pre-label", reason: "no-client" });
+			return null;
+		}
+		const runs = await liveAwaitRunsForTarget({ redis, targetKey, now, limit: HELD_FANOUT_LIMIT });
+		if (!Array.isArray(runs)) {
+			log({ event: "held_fell_through", delivery, kind, route: "pre-label", reason: runs?.error ?? "error" });
+			return null;
+		}
+		const held = runs.length > 0 ? await holdUnder({ redis, runIds: runs, job: candidate, kind, route: "pre-label", now, log, delivery, target }) : null;
+		if (held !== null) return held;
+		const parked = await recentlyParked({ redis, targetKey });
+		if (parked === true) {
+			log({ event: "held_after_park", delivery, kind, repo: candidate.repo, target });
+			return { enqueue: true };
+		}
+		// No live run and no park is the ordinary case (a phrase-free comment on an issue nothing is parking on), so it
+		// logs nothing: the caller's `dropped` line is exactly today's.
+		return null;
+	} catch {
+		return null;
+	}
+}

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;
+}