@edgehero/pi-dispatch 0.1.1 → 0.2.0

package/src/triggers.mjs

@@ -40,12 +40,22 @@ export { FORGE_KINDS };
  * what their forge's documentation says and can grep for it there.
  *
  * GitLab has no `labeled`: adding a label to a merge request arrives as `update` carrying a
- * `changes.labels` diff, and `open`/`reopen` are its spellings of `opened`/`reopened`. `approved` has no
- * GitHub counterpart at all and is a genuinely useful gate (a member approved the MR). `merge` and
+ * `changes.labels` diff, and `open`/`reopen` are its spellings of `opened`/`reopened`. `merge` and
  * `close` are omitted on purpose: a job started by a merge or a close has nothing left to act on.
+ *
+ * `review_submitted` (issue #66) is github's fifth and the one compound word here. It names the
+ * `pull_request_review` event's `submitted` action, so both halves are greppable in GitHub's own docs, the
+ * same reason Forgejo's `label_updated` is spelled Forgejo's way. It is also the first case where ONE
+ * `on.type` covers TWO GitHub event names: a review is an event about a pull request, and GitLab's
+ * analogue `approved` already rides `on.type: "pull_request"`, so making GitHub's a fifth `on.type` would
+ * have made one forge's review a type and the other's an action. The gate on it is the REVIEWER's
+ * `author_association`, never the PR author's -- see filter.mjs and CONST-TRIGGER-AUTHOR-GATE.
  */
 const PR_ACTIONS = {
-	github: new Set(["labeled", "opened", "synchronize", "reopened"]),
+	github: new Set(["labeled", "opened", "synchronize", "reopened", "review_submitted"]),
+	// GitLab's `approved` is its review gate (a member approved the MR). It is NOT github's
+	// `review_submitted` renamed: `approved` is one verdict, `review_submitted` is every verdict, which is
+	// what `on.reviewState` below exists to narrow.
 	gitlab: new Set(["open", "update", "reopen", "approved"]),
 	// Forgejo's own spellings. `label_updated` is its `labeled` and `synchronized` its `synchronize` -- a
 	// one-letter difference that an operator would otherwise discover as a trigger that loads clean and
@@ -59,6 +69,24 @@ const PR_ACTIONS = {
 	azure: new Set(["created", "updated"]),
 };
 
+/**
+ * The verdicts a submitted GitHub review can carry, in the webhook's own (lower-case) spelling, and the
+ * vocabulary of the optional `on.reviewState` narrowing (issue #66).
+ *
+ * The narrowing exists because `review_submitted` is a WIDER paid surface than any other GitHub trigger:
+ * an approve, a request-changes and a drive-by "lgtm thanks" all submit a review, and unlike a comment
+ * trigger there is no phrase in the way and unlike a label trigger there is no label. `["changes_requested"]`
+ * is the arming most operators actually want. Omitted means all three, so the default is the issue's own
+ * shape and the narrowing only ever subtracts.
+ *
+ * `dismissed` is absent because it is an ACTION on the `pull_request_review` event, not a state a
+ * submitted review carries.
+ */
+const REVIEW_STATES = new Set(["approved", "changes_requested", "commented"]);
+
+/** The one action `on.reviewState` can narrow. Spelled once, read by the validator and named in its error. */
+const REVIEW_ACTION = "review_submitted";
+
 // A cron id flows into BullMQ's deterministic `repeat:<id>:<nextMillis>` jobId, so a `:` corrupts that
 // parse; the charset also excludes `:` and the dedicated check names the reason.
 const ID_CHARSET = /^[A-Za-z0-9._-]+$/;
@@ -183,6 +211,12 @@ function normalizeCron(on, run, index, path, state) {
 
 	const packages = validatePackagesFlag(run, `cron trigger "${id}"`, path);
 	const image = validateImageRef(run, `cron trigger "${id}"`, path);
+	const skillsDir = validateSkillsDir(run, `cron trigger "${id}"`, path);
+	validateInstructions(run, `cron trigger "${id}"`, path, { cron: true });
+	// RETURNED, not discarded like validateReplicas below, because `resume` still has a legal value on a
+	// cron entry: only `true` is refused (the local path has nothing to resume with), so what survives is
+	// `false` or absent. Both must keep reaching the job payload unchanged -- an operator who wrote down
+	// today's default must not get a `data` that disagrees with the file they reviewed.
 	const resume = validateResumeFlag(run, `cron trigger "${id}"`, path);
 	// Called and DISCARDED: on a cron trigger this can only refuse, and the refusal is the point. The
 	// returned `run` below deliberately grows no `replicas` key -- a cron entry can never carry one.
@@ -195,7 +229,7 @@ function normalizeCron(on, run, index, path, state) {
 	// freeze today's default into every stored repeatable.
 	return {
 		on: { type: "cron", id, pattern },
-		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume },
+		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...(skillsDir !== undefined && { skillsDir }) },
 	};
 }
 
@@ -230,9 +264,25 @@ function validatePackagesFlag(run, at, path) {
  * to host disk and replayed into a later job on the same key. Disclosures default off. Absent and `false`
  * both mean today's behaviour, with not one byte written to disk and no /session mount in the argv.
  *
- * Carried on all four kinds for `run.image`'s reason rather than cron-only like `run.github`: continuing a
- * conversation is a property of the FLOW, and a cron trigger's flow is a flow. A cron job keys on its own
- * scheduler id (session-key.mjs), which is the one key in this feature chosen by nobody untrusted.
+ * REFUSED on a CRON trigger, and the refusal is the honest half of this validator rather than a limit of
+ * the feature. `resolveSession` is handed to the FORGE preparers only (prepare.mjs); the local branch
+ * returns before it is ever in scope, and prepare-local.mjs contains no session code at all -- so an armed
+ * cron trigger stages no transcript, mounts no /session, promotes nothing, and then exits 0 as though it
+ * had. `validateReplicas` states the argument in one line and it applies verbatim here: a field accepted
+ * where it does nothing is how an operator comes to trust one that does nothing.
+ *
+ * "NOT YET COVERED", not impossible -- validateReplicas' own distinction, kept because the two are
+ * different facts and an operator planning work needs the right one. The local key already exists and is
+ * the strongest key in this feature: session-key.mjs keys a cron job on its scheduler id, which is
+ * operator-authored, unique across the file, stable across fires, and chosen by nobody untrusted. Nothing
+ * reaches it. Wiring `resolveSession` into the local path is a feature, and this line is what stops the
+ * flag from pretending that feature landed in the meantime.
+ *
+ * Only `true` is refused, and the asymmetry with validateReplicas -- which refuses ANY value on cron -- is
+ * deliberate. `run.replicas: 1` is refused because a one-member replica set is a flag that does nothing,
+ * so the field has no legal no-op value; `run.resume: false` IS the documented default, so refusing it
+ * would refuse an operator for writing down the behaviour they already have, and would change a normalized
+ * shape that has to stay byte-identical.
  *
  * Strictly boolean and fail-loud, the house rule -- and here the damaging misreading is a truthy `"false"`
  * string, which reads to an operator as an opt-out and would arm the disclosure instead. That is the exact
@@ -240,7 +290,9 @@ function validatePackagesFlag(run, at, path) {
  *
  * Type here, reality at job start, exactly as `run.image` splits it: this cannot know whether
  * PI_SESSIONS_DIR is set, whether a key resolves, or whether a transcript exists. Those are the worker's
- * to answer, and all but the first degrade to a cold start rather than refusing.
+ * to answer, and all but the first degrade to a cold start rather than refusing -- the first is the one
+ * pre-spend policy refusal, `sessions-dir-unset` in processor.mjs (REQ-RESUMABLE-SESSION fails CLOSED
+ * there and only there).
  *
  * `at` is the caller's message prefix. Returns the flag, undefined when absent, so an unflagged trigger
  * normalizes byte-identically to today's.
@@ -249,6 +301,14 @@ function validateResumeFlag(run, at, path) {
 	if (run.resume !== undefined && typeof run.resume !== "boolean") {
 		throw configError(`${at}: run.resume must be true or false when present: ${path}`);
 	}
+	// `run.kind === "local"` IS "this is a cron trigger": normalizeTrigger has already refused every other
+	// pairing of on.type and run.kind, so the matrix makes the two synonyms. The same test validateReplicas
+	// keys its first refusal on, for the same reason -- neither wants to be re-taught the matrix.
+	if (run.resume === true && run.kind === "local") {
+		throw configError(
+			`${at}: run.resume is not yet covered for cron triggers (forge triggers only in this version) -- resolveSession is handed to the forge preparers only, so a local job would stage no transcript, mount no /session and promote nothing, then exit 0 as though it had; the local session key exists in session-key.mjs and nothing reaches it, so this is a gap to close, not a limit: ${path}`,
+		);
+	}
 	return run.resume;
 }
 
@@ -298,6 +358,98 @@ function validateImageRef(run, at, path) {
 	return image;
 }
 
+/**
+ * `run.skillsDir` (issue #60): a directory of operator-authored skills on the WORKER host, copied into
+ * this trigger's jobs and layered between the repo's own `.pi/skills` and the global overlay.
+ *
+ * Accepted on all four run kinds, for `run.image`'s reason restated: a skill set is a capability of the
+ * FLOW, and a label/comment/PR trigger runs the flows a cron trigger runs. The copy site in prepare.mjs
+ * is shared by every kind, so accepting it everywhere accepts it where it works.
+ *
+ * TWO checks are deliberately NOT here, and both would be bugs if they were.
+ *
+ * EXISTENCE is not checked, because BOTH services parse this file and the receiver may run on a
+ * different host entirely, where a worker-side path means nothing. That is `run.folder`'s split
+ * exactly: type here, reality where it can be known -- at worker boot for cron (schedules.mjs) and
+ * pre-spend per job for every kind (processor.mjs).
+ *
+ * ABSOLUTENESS is not checked either, and this one is subtler. `path.isAbsolute` is OS-DEPENDENT:
+ * `"C:\\skills"` is absolute on win32 and relative on posix. This worker is cross-platform (see
+ * materialize.mjs's safeJoin, written with path.relative for that reason), so enforcing it in the
+ * SHARED validator would let a Windows worker and a Linux receiver disagree about whether the same
+ * reviewed file is valid -- a file that loads on one service and refuses on the other is worse than a
+ * late refusal. The worker enforces it where the answer is knowable.
+ *
+ * No charset either: this is an absolute host path chosen by an operator who can already name any path
+ * in `run.folder`, so traversal is not a threat model here. Containment is enforced where it can be, on
+ * the DESTINATION side, by copy-tree.mjs's validated-segment rebuild and safeJoin.
+ */
+function validateSkillsDir(run, at, path) {
+	const dir = run.skillsDir;
+	if (dir === undefined) return undefined;
+	if (typeof dir !== "string" || dir.trim() === "") {
+		throw configError(`${at}: run.skillsDir must be a non-empty string when present: ${path}`);
+	}
+	// Whitespace is refused rather than trimmed, for validateImageRef's reason: the file is the reviewed
+	// artifact and must not disagree with what runs.
+	if (dir !== dir.trim()) {
+		throw configError(`${at}: run.skillsDir must not have leading or trailing whitespace (got ${JSON.stringify(dir)}): ${path}`);
+	}
+	return dir;
+}
+
+/**
+ * The ceiling on `run.instructions` (REQ-PER-TRIGGER-INSTRUCTION, issue #60).
+ *
+ * NOT a caching bound, and the entry says so rather than letting a reader assume it. The text is written
+ * once into /job/prompt.md and `session.prompt()` is called once, so the pattern
+ * CONST-PERSONA-IN-CACHED-PREFIX names -- injecting a persistent user message on every prompt -- is not
+ * what this is; and at the pin, pi-ai attaches cache_control to the LAST USER MESSAGE as well as the
+ * system prompt, so after turn one this sits in the cached prefix at roughly the persona's rate anyway.
+ *
+ * What the cap is actually for is two other things. A field with no bound invites a 200 KB style guide
+ * pasted in, which overflows context inside a PAID container on every delivery of that trigger, with no
+ * pre-spend signal -- a cap turns that into a free load-time refusal in both services. And it keeps the
+ * field in its lane: a standing instruction is a sentence or two, and anything longer belongs in the
+ * flow's own SKILL.md (versioned, reviewed) or in the overlay persona (deploy-time, system prompt). The
+ * refusal message names both destinations, so the cap teaches rather than merely blocks.
+ */
+const INSTRUCTIONS_MAX = 2000;
+
+/**
+ * `run.instructions` (issue #60): one line of operator standing text, rendered into the USER prompt's
+ * envelope above the fenced data region.
+ *
+ * REFUSED on cron, and it is a DIFFERENT refusal from run.replicas' "not yet covered": cron already has
+ * an operator-authored free-text field landing in the same region of the same file. A local job's prompt
+ * is `flow hint + pointer + run.task` with no envelope, no data heading and no fence (prepare.mjs), so
+ * there is no "standing" region distinct from the task for a second field to occupy. Two fields writing
+ * one region with an undefined combination order is worse than a field that does nothing, because both
+ * would appear to work.
+ *
+ * Whitespace is NOT refused here, unlike run.image, and the divergence is deliberate: that rule exists
+ * because whitespace changes what an image REFERENCE means, and it does not change what prose means. A
+ * trailing newline in a multi-line JSON string is a papercut, not a hazard. A whitespace-ONLY value is
+ * refused, because that is a field the operator believes they set.
+ *
+ * Refused rather than truncated at the cap, for validateImageRef's reason: the file is the reviewed
+ * artifact and must not disagree with what runs.
+ */
+function validateInstructions(run, at, path, { cron = false } = {}) {
+	const text = run.instructions;
+	if (text === undefined) return undefined;
+	if (cron) {
+		throw configError(`${at}: run.instructions is not accepted on a cron trigger -- a local job's prompt IS run.task, the same operator-authored text in the same place. Put the standing instruction at the top of run.task: ${path}`);
+	}
+	if (typeof text !== "string" || text.trim() === "") {
+		throw configError(`${at}: run.instructions must be a non-empty string when present: ${path}`);
+	}
+	if (text.length > INSTRUCTIONS_MAX) {
+		throw configError(`${at}: run.instructions is ${text.length} characters, over the ${INSTRUCTIONS_MAX} cap -- a standing instruction is a sentence or two. Anything longer belongs in the flow's own SKILL.md, or in the global overlay's APPEND_SYSTEM.md if it applies to every job: ${path}`);
+	}
+	return text;
+}
+
 /**
  * Validate an `{any, all, none}` label predicate. Selectors are validated as arrays of non-empty strings
  * BEFORE the positive-selector count, because `.length` is truthy on a string too -- a string selector
@@ -406,12 +558,14 @@ function normalizeLabel(on, run, index, path) {
 	}
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
+	const skillsDir = validateSkillsDir(run, at, path);
+	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
 	const repository = validateRepository(run, "label", at, path);
 	const replicas = validateReplicas(run, at, path);
 	return {
 		on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -432,12 +586,14 @@ function normalizeComment(on, run, index, path, state) {
 	}
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
+	const skillsDir = validateSkillsDir(run, at, path);
+	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
 	const repository = validateRepository(run, "comment", at, path);
 	const replicas = validateReplicas(run, at, path);
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -458,6 +614,8 @@ function normalizePullRequest(on, run, index, path) {
 		}
 	}
 
+	const reviewState = validateReviewState(on, actions, run, at, path);
+
 	// A `labeled` PR trigger is gated by its label predicate (the collaborator-applied label is the
 	// approval), so it MUST carry a positive selector -- exactly as a label trigger does. Auto actions
 	// (opened/synchronize/reopened) are gated by author_association in the filter, so a predicate is
@@ -481,11 +639,52 @@ function normalizePullRequest(on, run, index, path) {
 	}
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
+	const skillsDir = validateSkillsDir(run, at, path);
+	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
 	validateRepository(run, "pull_request", at, path);
 	const replicas = validateReplicas(run, at, path);
 	return {
-		on: { type: "pull_request", action: [...actions], any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas },
+		on: {
+			type: "pull_request",
+			action: [...actions],
+			// Absent rather than present-and-undefined: an unnarrowed rule's normalized shape must stay
+			// byte-identical to the one every pre-#66 trigger file produces.
+			...(reviewState !== undefined && { reviewState }),
+			any: predicate.any,
+			all: predicate.all,
+			none: predicate.none,
+		},
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }) },
 	};
 }
+
+/**
+ * The optional `on.reviewState` narrowing (issue #66). Returns the normalized array, or `undefined` when
+ * unset, which means every verdict fires.
+ *
+ * All four refusals are the same call the action vocabulary makes at the top of `normalizePullRequest`: a
+ * narrowing that can never apply does not crash anything downstream, it simply sits in the file looking
+ * configured while the trigger either fires on everything or on nothing. Refusing at load is what turns
+ * that into a message. The `review_submitted` requirement is the sharpest of the four -- a `reviewState`
+ * beside `["opened","synchronize"]` reads as "only run for these verdicts" and does the exact opposite.
+ */
+function validateReviewState(on, actions, run, at, path) {
+	if (on.reviewState === undefined) return undefined;
+	if (run.kind !== "github") {
+		throw configError(`${at}: on.reviewState is github-only (got ${run.kind}), no other forge reports a review verdict: ${path}`);
+	}
+	if (!actions.includes(REVIEW_ACTION)) {
+		throw configError(`${at}: on.reviewState requires on.action to include ${JSON.stringify(REVIEW_ACTION)}, otherwise it narrows nothing: ${path}`);
+	}
+	if (!Array.isArray(on.reviewState) || on.reviewState.length === 0) {
+		throw configError(`${at}: on.reviewState must be a non-empty array: ${path}`);
+	}
+	const expected = [...REVIEW_STATES].join("|");
+	for (const s of on.reviewState) {
+		if (!REVIEW_STATES.has(s)) {
+			throw configError(`${at}: on.reviewState has an unsupported review state ${JSON.stringify(s)} (expected ${expected}): ${path}`);
+		}
+	}
+	return [...on.reviewState];
+}