@edgehero/pi-dispatch 4.1.0 → 4.3.0

package/src/triggers.mjs

@@ -32,6 +32,8 @@ import { imageRefProblem } from "./image-ref.mjs";
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
 import { findDuplicateKey } from "./json-duplicates.mjs";
+// The server-name rule, from the one module that parses the overlay's list (its body is import-inert).
+import { FORGE_MCP_KINDS, FORGE_MCP_SERVER_NAME, MCP_SERVER_NAME_RE } from "./mcp-config.mjs";
 import { validateModelRef } from "./model-ref.mjs";
 import { parseUsdMicros } from "./money.mjs";
 import { PROVIDER_STEERING_VARS } from "./provider-steering.mjs";
@@ -189,6 +191,29 @@ const REVIEW_ACTION = "review_submitted";
  */
 // EXPORTED for the two pinned-set bolts and for the admin, which states the vocabulary to an operator.
 export const EXCLUDABLE_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+/**
+ * The tools a job's MCP brings (REQ-MCP-OPERATOR-SERVERS, image/runner/src/mcp.mjs), excludable only by a trigger that
+ * names servers: codemode, tool_search and pi's three resource tools. One server's tools are excluded as a whole by
+ * `mcpServerToolPattern(name)`; a single tool of a server is not, since its name (pi's sanitized `mcp__<server>__<tool>`)
+ * is unknown until the server lists it, and a misspelled one would exclude nothing. That is the overlay's
+ * `toolExposure: "hidden"`, the operator's.
+ */
+export const MCP_EXCLUDABLE_TOOL_NAMES = new Set(["codemode", "tool_search", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+/**
+ * `excludeTools` without the entries that name the job's MCP tools, or undefined when nothing is left: what a job that
+ * connects no MCP server carries (a chained child, which never inherits `run.mcp`). Its runner knows none of those
+ * names, and with no MCP there is nothing for them to remove, so dropping them narrows nothing.
+ */
+export function withoutMcpExclusions(excludeTools) {
+	if (!Array.isArray(excludeTools)) return excludeTools;
+	const kept = excludeTools.filter((name) => !MCP_EXCLUDABLE_TOOL_NAMES.has(name) && !String(name).startsWith("mcp__"));
+	return kept.length > 0 ? kept : undefined;
+}
+
+/** The excludeTools entry that removes every tool of one named server: pi's namespace, `-` written as `_`. */
+export function mcpServerToolPattern(name) {
+	return `mcp__${String(name).replace(/-/g, "_")}__*`;
+}
 
 // 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.
@@ -400,6 +425,9 @@ function normalizeCron(on, run, index, path, state) {
 	// `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 for its refusal only (issue #625): `true` needs run.resume, which cron refuses, so the returned `run`
+	// grows no `awaitInput` key, exactly as it grows no `replicas` one.
+	validateAwaitInputFlag(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.
 	validateReplicas(run, `cron trigger "${id}"`, path);
@@ -416,6 +444,7 @@ function normalizeCron(on, run, index, path, state) {
 	// A cron job's session narrows like any other: the field selects what the container's agent can do,
 	// which is orthogonal to what triggered it (issue #291).
 	const excludeTools = validateExcludeTools(on, run, `cron trigger "${id}"`, path);
+	const mcp = validateMcp(on, run, `cron trigger "${id}"`, path, { kind: "local" });
 	// Validated since #502; before it these three were copied untouched, so `run.provider: 7` loaded.
 	const ref = validateRunModel(on, run, `cron trigger "${id}"`, path);
 	// Issue #505: the portfolio flag. Strictly boolean, the house rule (`run.github`'s reason: a truthy string must not
@@ -430,7 +459,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: ref.provider, model: ref.model, maxTurns: ref.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(ref.models !== undefined && { models: ref.models }), ...(ref.maxCostUsd !== undefined && { maxCostUsd: ref.maxCostUsd }), ...(portfolio !== undefined && { portfolio }) },
+		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: ref.provider, model: ref.model, maxTurns: ref.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...(ref.models !== undefined && { models: ref.models }), ...(ref.maxCostUsd !== undefined && { maxCostUsd: ref.maxCostUsd }), ...(portfolio !== undefined && { portfolio }) },
 	};
 }
 
@@ -531,6 +560,28 @@ function validateResumeFlag(run, at, path) {
 	return run.resume;
 }
 
+/**
+ * Validate the per-trigger `run.awaitInput` flag (REQ-AWAIT-INPUT, issue #625): whether the job is offered the tool
+ * that ends a run to wait for a person's answer. Strictly boolean, validateResumeFlag's rule and for its reason: a
+ * truthy `"false"` would arm what the operator meant to leave off.
+ *
+ * `true` needs `run.resume: true` beside it, and that one rule carries every other refusal: a parked run is only
+ * worth anything if the next run resumes its transcript, and `run.resume` is already refused on cron and beside
+ * `run.command`, `run.replicas` and `run.secrets`, each for a reason that holds here too. So this adds no list of
+ * its own, which is one place fewer for the two to disagree.
+ *
+ * Returns the flag, undefined when absent, so an unflagged trigger normalizes byte-identically to today's.
+ */
+function validateAwaitInputFlag(run, at, path) {
+	if (run.awaitInput !== undefined && typeof run.awaitInput !== "boolean") {
+		throw configError(`${at}: run.awaitInput must be true or false when present: ${path}`);
+	}
+	if (run.awaitInput === true && run.resume !== true) {
+		throw configError(`${at}: run.awaitInput needs run.resume: true beside it -- a run that stops to wait for an answer is continued by the next run on the same issue or pull request, and only run.resume keeps the transcript it would continue from: ${path}`);
+	}
+	return run.awaitInput;
+}
+
 /**
  * Validate the per-trigger `run.image` reference, shared by all four normalizers. It selects the Docker image
  * this trigger's job containers run in, overriding the deployment-wide `PI_JOB_IMAGE` for this trigger only;
@@ -1368,14 +1419,22 @@ function validateExcludeTools(on, run, at, path) {
 	if (!Array.isArray(excludeTools) || excludeTools.length === 0) {
 		throw configError(`${at}: run.excludeTools must be a non-empty array of tool names when present (got ${JSON.stringify(excludeTools)}) -- an empty exclusion is a field that does nothing, and accepted-and-ignored is how an operator comes to trust one that does: ${path}`);
 	}
+	// With run.mcp, the tools the job's MCP brings are known too (its shape is the next validator's to judge; here a
+	// name that is not a valid server name simply adds no pattern).
+	const known = new Set(EXCLUDABLE_TOOL_NAMES);
+	if (Array.isArray(run?.mcp) && run.mcp.length > 0) {
+		for (const name of MCP_EXCLUDABLE_TOOL_NAMES) known.add(name);
+		for (const name of run.mcp) if (typeof name === "string" && MCP_SERVER_NAME_RE.test(name)) known.add(mcpServerToolPattern(name));
+	}
 	const seen = new Set();
 	for (let i = 0; i < excludeTools.length; i++) {
 		const name = excludeTools[i];
 		if (!isNonEmptyString(name)) {
 			throw configError(`${at}: run.excludeTools[${i}] must be a non-empty string naming a pi tool (got ${JSON.stringify(name)}): ${path}`);
 		}
-		if (!EXCLUDABLE_TOOL_NAMES.has(name)) {
-			throw configError(`${at}: run.excludeTools[${i}] ${JSON.stringify(name)} is not a tool the pinned pi knows (known: ${[...EXCLUDABLE_TOOL_NAMES].join(", ")}) -- pi ignores unknown names silently, so a misspelled exclusion would exclude nothing while the file reads as though it did: ${path}`);
+		if (!known.has(name)) {
+			const mcpHint = MCP_EXCLUDABLE_TOOL_NAMES.has(name) || name.startsWith("mcp__") ? " (an MCP tool is excludable only by a trigger whose run.mcp names its server, and a server's tools only all at once, as mcp__<server>__*)" : "";
+			throw configError(`${at}: run.excludeTools[${i}] ${JSON.stringify(name)} is not a tool the pinned pi knows (known: ${[...known].join(", ")})${mcpHint} -- pi ignores unknown names silently, so a misspelled exclusion would exclude nothing while the file reads as though it did: ${path}`);
 		}
 		if (seen.has(name)) {
 			throw configError(`${at}: run.excludeTools names ${JSON.stringify(name)} twice -- the entries are a removal set, so the second can never change the answer: ${path}`);
@@ -1386,6 +1445,84 @@ function validateExcludeTools(on, run, at, path) {
 	return [...excludeTools];
 }
 
+/** The most MCP servers one trigger may name. A bound, not a budget: each one is a connection the job opens at start. */
+export const MCP_SERVERS_MAX = 8;
+
+/** The spellings of `run.mcp` a key is refused for, compared after `mcpKeySkeleton`. */
+const MCP_NEAR_MISSES = Object.freeze(["mcp", "mcps", "mcpserver", "mcpservers"]);
+
+/** An ASCII key reduced to its letters and digits, lowercased: `MCP_Servers` and `mcp-servers` both read `mcpservers`. */
+export function mcpKeySkeleton(key) {
+	return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * Whether `key` (not the field itself) is refused as a spelling of `run.mcp` rather than dropped: an ASCII key whose
+ * skeleton is one of the field's spellings, or a key that is not plain ASCII and whose plain letters are all letters
+ * of `mcpservers`. A key in another script can be drawn exactly like this one (Greek, Cyrillic, Cherokee, small
+ * capitals, fullwidth forms), which no table of lookalikes keeps up with, but any such key keeps at most the field's
+ * own letters in ASCII. An unrelated non-ASCII key (`fl\u00f6w`) keeps others and still loads, and a lookalike of
+ * another field (`m\u043edels`) is left to that field's sweep.
+ */
+export function isMcpNearMiss(key) {
+	if (key === "mcp") return false;
+	if (/^[\x20-\x7E]*$/.test(key)) return MCP_NEAR_MISSES.includes(mcpKeySkeleton(key));
+	return [...key.matchAll(/[a-z]/gi)].every(([letter]) => "mcpservers".includes(letter.toLowerCase()));
+}
+
+/**
+ * `run.mcp` -- the overlay MCP servers this trigger's jobs connect (REQ-MCP-OPERATOR-SERVERS), by name.
+ *
+ * NAMES ONLY. A server's definition is the operator's, in the overlay's `mcp.json` (INT-OVERLAY-MCP-CONFIG), so a
+ * trigger edit can choose among the servers the deployment offers and never point a credential at a new host. The
+ * loader is fs-free, so whether a name is in the overlay is checked where the file is read: at the job's pickup,
+ * before anything is spent, and by doctor. Absent means none: a job connects no MCP server unless its trigger says
+ * so. The near-miss sweep is excludeTools': a dropped `run.mcp` runs the job without the servers its flow was written
+ * against, while the file reads as though it named them.
+ *
+ * One name is not the overlay's: `forge` (DES-FORGE-MCP) is the job's own forge, through that forge's MCP server and
+ * the job's own token, and the worker writes its entry. Accepted on a github or gitlab trigger only, and refused here
+ * on the rest, since whether it can ever work is a fact about the kind: a cron job holds no forge token of its own, and
+ * forgejo and azure have no forge MCP server this repository has verified.
+ */
+function validateMcp(on, run, at, path, { kind }) {
+	for (const [label, source, exactIsLegal] of [
+		["run", run, true],
+		["on", on, false],
+	]) {
+		for (const key of Object.keys(source ?? {})) {
+			if (exactIsLegal ? isMcpNearMiss(key) : key === "mcp" || isMcpNearMiss(key)) {
+				if (!/^[\x20-\x7E]*$/.test(key)) {
+					throw configError(`${at}: ${label}.${JSON.stringify(key)} is not a field: a key outside plain ASCII with no plain letter other than run.mcp's can be drawn exactly like run.mcp, which the loader would drop while the file reads as though it named servers. Write field names in plain ASCII: ${path}`);
+				}
+				throw configError(`${at}: ${label}.${key} is not a field -- did you mean run.mcp? A list of MCP servers the loader drops runs the job without them while the file reads as though it named them, so a near miss is refused rather than dropped: ${path}`);
+			}
+		}
+	}
+	const mcp = run?.mcp;
+	if (mcp === undefined) return undefined;
+	if (!Array.isArray(mcp) || mcp.length === 0) {
+		throw configError(`${at}: run.mcp must be a non-empty array of server names from the overlay's mcp.json when present (got ${JSON.stringify(mcp)}); leave it out for none: ${path}`);
+	}
+	if (mcp.length > MCP_SERVERS_MAX) {
+		throw configError(`${at}: run.mcp names ${mcp.length} servers, more than ${MCP_SERVERS_MAX}: ${path}`);
+	}
+	const seen = new Set();
+	for (let i = 0; i < mcp.length; i++) {
+		const name = mcp[i];
+		if (typeof name !== "string" || !MCP_SERVER_NAME_RE.test(name)) {
+			throw configError(`${at}: run.mcp[${i}] must name a server of the overlay's mcp.json: lowercase letters and digits, words joined by single -, up to 32 (got ${JSON.stringify(name)}): ${path}`);
+		}
+		if (seen.has(name)) throw configError(`${at}: run.mcp names ${JSON.stringify(name)} twice: ${path}`);
+		seen.add(name);
+		if (name === FORGE_MCP_SERVER_NAME && !FORGE_MCP_KINDS.includes(kind)) {
+			const why = kind === "local" ? "a cron job holds no forge token of its own for the server to use" : `${kind} has no forge MCP server this deployment has verified yet`;
+			throw configError(`${at}: run.mcp names "forge", the job's own forge server, which a ${FORGE_MCP_KINDS.join(" or ")} trigger may name and this one may not: ${why}: ${path}`);
+		}
+	}
+	return [...mcp];
+}
+
 /**
  * `run.waitFor` -- the conditions that must all clear before this trigger's job starts (issue #230).
  *
@@ -1537,6 +1674,7 @@ function normalizeLabel(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	const repository = validateRepository(run, "label", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1544,10 +1682,11 @@ function normalizeLabel(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, 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, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1579,6 +1718,7 @@ function normalizeComment(on, run, index, path, state) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	const repository = validateRepository(run, "comment", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1586,10 +1726,11 @@ function normalizeComment(on, run, index, path, state) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1648,6 +1789,7 @@ function normalizeIssue(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	validateRepository(run, "issue", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1655,6 +1797,7 @@ function normalizeIssue(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: {
@@ -1665,7 +1808,7 @@ function normalizeIssue(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1735,6 +1878,7 @@ function normalizePullRequest(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	validateRepository(run, "pull_request", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1742,6 +1886,7 @@ function normalizePullRequest(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: {
@@ -1757,7 +1902,7 @@ function normalizePullRequest(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }