@edgehero/pi-dispatch 4.1.0 → 4.3.0

package/src/mcp-preflight.mjs

@@ -0,0 +1,262 @@
+/**
+ * The pickup's MCP question (REQ-MCP-OPERATOR-SERVERS, DES-MCP-EGRESS-PREFLIGHT): can this job use the overlay MCP
+ * servers its trigger names (`run.mcp`)? Answered before anything is spent (CONST-BUDGET-BEFORE-TOKENS), from the
+ * overlay's `mcp.json` read once for the job, and the answer carries the per-job document `prepare` writes to
+ * `/job/mcp.json`, so the servers the job connects are exactly the servers this check passed.
+ *
+ * One of:
+ *   { ok: true, document }        `document` null when the job names no server
+ *   { refused, name, why }        a determinate refusal, returned (CONST-RETRY-INFRA-ONLY): `refused` is the reason
+ *   { unavailable: code }         the overlay could not be read just now, an errno that may pass: retried
+ *
+ * The refusals, in the order they are asked:
+ *   mcp-list-invalid         the job's own list is not one the loader writes (queue data from another version, or a
+ *                            hand-added job);
+ *   mcp-config-invalid       the overlay's mcp.json cannot be read whole (or there is no overlay, or no file, when the
+ *                            job names a server other than `forge`);
+ *   mcp-server-unknown       a name the file does not offer, offers disabled, or refuses (doctor names why); or
+ *                            `forge` on a job that is not a github or gitlab one;
+ *   mcp-secret-reserved      a reference to a variable this deployment writes or pi reads for the job itself (a
+ *                            credential the job spends with, `providerKeyNames`; a minted forge token; the egress or
+ *                            runner variables): a server must never be handed the job's own credentials. Asked of
+ *                            every reference before the next rule;
+ *   mcp-secret-unmapped      a reference the job will not have: not a `run.secrets` name, and not a PI_FORWARD_ENV
+ *                            name the worker's environment holds a value for;
+ *   mcp-excluded             the trigger's own run.excludeTools leaves a server no way in that it had: its tools and
+ *                            its resources reachable only through tools it removed (`mcpRouteProblem`);
+ *   mcp-egress-unreachable   with the egress policy on, a streamable HTTP server the proxy would not let the job reach,
+ *                            or the forge server's API host (api.github.com, or the configured GitLab's) unlisted;
+ *   mcp-package-runner       with the egress policy on, a package runner whose registry the allowlist does not hold.
+ *
+ * `forge` (DES-FORGE-MCP) is not read from the overlay: its entry is the worker's (`forgeMcpServer`), so a job naming
+ * only it needs no mcp.json at all, and it is exempt from the two secret rules, its one reference being the forge token
+ * the worker itself writes into the container for this job. The overlay's top-level switches still govern it when the
+ * file is there, so a file that is there and cannot be read refuses it like any other server.
+ */
+import { allowlistEntryFor, egressRefusalFor, packageRunnerHosts } from "./egress-allowlist.mjs";
+import { FORGE_MCP_KINDS, FORGE_MCP_SERVER_NAME, forgeMcpEgressUrl, forgeMcpServer, gitlabUrlProblem, jobMcpDocument, MCP_SERVER_NAME_RE, readOverlayMcp } from "./mcp-config.mjs";
+import { MCP_SERVERS_MAX, mcpServerToolPattern } from "./triggers.mjs";
+
+/**
+ * Errnos a read of the overlay may pass on a second try. Restated from model-catalog.mjs `OVERLAY_TRANSIENT_READ_CODES`
+ * rather than imported, since that module loads pi's catalog; mcp-preflight.test.mjs holds the two equal.
+ */
+export const MCP_TRANSIENT_READ_CODES = new Set(["EIO", "EAGAIN", "EMFILE", "ENFILE"]);
+
+/** A variable reference in a pi config value, `$NAME` or `${NAME}`, anywhere in the string (pi's own grammar). */
+const CONFIG_REF_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/**
+ * The credentials a job is set up to spend with, as variable names: each builtin key variable of the providers it may
+ * call (`providers`: its main provider and the ones on its model list), and every variable the overlay models.json
+ * references anywhere (a custom provider's `apiKey` in any form, its headers, a model's or an override's headers),
+ * since pi reads each of them for model calls. A builtin provider the job cannot call (its model list does not name
+ * it, `jobProviders`) is not counted: its variable is one the operator may hand a server on purpose (`HF_TOKEN` for a
+ * Hugging Face MCP server), as `run.secrets` may. A custom provider whose key is a `!command` names no variable this
+ * can see: the operator who writes both files is the one who can avoid that pairing.
+ */
+export function providerKeyNames({ providers = [], candidatesOf = () => [], overlayModels = null } = {}) {
+	const names = new Set();
+	for (const provider of providers) for (const name of candidatesOf(provider) ?? []) if (typeof name === "string") names.add(name);
+	const walk = (value) => {
+		if (typeof value === "string") for (const match of value.matchAll(CONFIG_REF_RE)) names.add(match[1] ?? match[2]);
+		else if (value !== null && typeof value === "object") Object.values(value).forEach(walk);
+	};
+	walk(overlayModels);
+	return names;
+}
+
+/**
+ * The providers a job may call: its own, and each on its model list (the trigger's, else the deployment's), which the
+ * runner's model guard holds every call to. With no list there is no guard, and the job may call any provider whose
+ * key its container holds (a pi child of its own, `--provider` and all), so every builtin provider (`everyProvider`)
+ * counts. An operator who hands a server a provider's variable on purpose (`HF_TOKEN`) gives that trigger a list.
+ */
+export function jobProviders(job, { defaultProvider = null, allowedModels = null, everyProvider = [] } = {}) {
+	const list = Array.isArray(job?.models) ? job.models : Array.isArray(allowedModels) ? allowedModels : null;
+	const listed = list === null ? everyProvider : list.map((ref) => (typeof ref === "string" ? ref.split("/")[0] : ref?.provider));
+	return [...new Set([job?.provider ?? defaultProvider, ...listed].filter((p) => typeof p === "string" && p !== ""))];
+}
+
+/**
+ * The check, bound to this deployment. `reserved(job)` is the set of variable names the job's own container holds for
+ * itself; `hostEnv` is the worker's environment, which decides whether a PI_FORWARD_ENV name reaches the job at all;
+ * `allowlist()` and `endpoints()` are read only when a server needs them, and `allowlist()` throws what its read threw.
+ * `gitlabUrl` is the worker's configured GitLab URL (null when it serves no GitLab), which a gitlab job's forge server
+ * calls.
+ */
+export function makeMcpCheck({ globalPiDir, forwardEnv = [], hostEnv = {}, egress = false, reserved = () => new Set(), allowlist = () => [], endpoints = () => [], read = readOverlayMcp, gitlabUrl = null }) {
+	return (job) => {
+		const listed = job?.mcp;
+		if (listed === undefined) return { ok: true, document: null };
+		// The loader's shape, asked again: queue data is not always the current receiver's (an older or newer service,
+		// a hand-added job, a stored repeatable), and a list that is not one must neither pass as "none" nor reach the
+		// public comment. The name is withheld from the comment when it is not a valid name.
+		if (!Array.isArray(listed) || listed.length === 0 || listed.length > MCP_SERVERS_MAX || new Set(listed).size !== listed.length || listed.some((name) => typeof name !== "string" || !MCP_SERVER_NAME_RE.test(name))) {
+			return { refused: "mcp-list-invalid", name: null, why: "the job's run.mcp is not a list of server names the loader accepts" };
+		}
+		const names = listed;
+		const overlayNames = names.filter((name) => name !== FORGE_MCP_SERVER_NAME);
+		let parsed;
+		try {
+			parsed = read(globalPiDir || "");
+		} catch (error) {
+			if (!error?.mcpConfig && MCP_TRANSIENT_READ_CODES.has(error?.code)) return { unavailable: error.code };
+			return { refused: "mcp-config-invalid", name: null, why: error?.mcpConfig ? "the overlay's mcp.json cannot be read whole" : `the overlay's mcp.json cannot be read (${error?.code ?? "unreadable"})` };
+		}
+		if (parsed === null) {
+			if (overlayNames.length > 0) return { refused: "mcp-config-invalid", name: null, why: globalPiDir ? "the overlay holds no mcp.json" : "this deployment has no overlay (PI_GLOBAL_PI_DIR)" };
+			// Only `forge`: the overlay's defaults, as an empty file reads.
+			parsed = { autoEnableCodemode: true, codemodeModels: true, servers: {}, refused: [] };
+		}
+		const refusedHere = new Map(parsed.refused.map((r) => [r.name, r.problem]));
+		let servers = parsed.servers;
+		if (overlayNames.length !== names.length) {
+			// The kind is queue data like the list: a job from elsewhere naming `forge` on a kind with no forge server (or
+			// no forge token) is refused here, never handed another forge's entry.
+			if (!FORGE_MCP_KINDS.includes(job.kind)) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: "the forge's own server is offered to a github or gitlab job only" };
+			if (job.kind === "gitlab" && (typeof gitlabUrl !== "string" || gitlabUrl === "")) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: "this worker has no GitLab URL configured" };
+			const urlProblem = job.kind === "gitlab" ? gitlabUrlProblem(gitlabUrl) : null;
+			if (urlProblem !== null) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: `GITLAB_URL cannot be handed to the forge server: ${urlProblem}` };
+			servers = { ...parsed.servers, [FORGE_MCP_SERVER_NAME]: forgeMcpServer(job.kind, { gitlabUrl }) };
+		}
+		for (const name of overlayNames) {
+			const server = Object.hasOwn(servers, name) ? servers[name] : undefined;
+			if (!server) return { refused: "mcp-server-unknown", name, why: refusedHere.has(name) ? "the overlay's mcp.json refuses it" : "the overlay's mcp.json does not offer it" };
+			if (server.enabled === false) return { refused: "mcp-server-unknown", name, why: "the overlay's mcp.json turns it off" };
+		}
+		// A forwarded name reaches the job only when the worker holds a value for it (env-allowlist.mjs buildContainerEnv).
+		const forwarded = forwardEnv.filter((ref) => typeof hostEnv[ref] === "string" && hostEnv[ref] !== "");
+		const mapped = new Set([...Object.keys(job.secrets ?? {}), ...forwarded]);
+		let own;
+		try {
+			own = reserved(job);
+		} catch (error) {
+			// The overlay models.json read inside `reserved` that may pass on a retry: without it, a custom provider's
+			// credential would drop out of the set for this one pickup.
+			if (MCP_TRANSIENT_READ_CODES.has(error?.code)) return { unavailable: error.code };
+			throw error;
+		}
+		// The forge server is exempt from both rules: its one reference is the token the worker mints for this job and
+		// writes under exactly that name, which is the reason every other server is refused it.
+		for (const name of overlayNames) {
+			for (const ref of servers[name].refs) {
+				if (own.has(ref)) return { refused: "mcp-secret-reserved", name, why: `it references ${ref}, which this deployment uses for the job's own credentials` };
+			}
+		}
+		for (const name of overlayNames) {
+			for (const ref of servers[name].refs) {
+				if (!mapped.has(ref)) return { refused: "mcp-secret-unmapped", name, why: `it references ${ref}, which the trigger does not pass (run.secrets, or a PI_FORWARD_ENV name the worker holds a value for)` };
+			}
+		}
+		const cut = mcpRouteProblem(servers, names, new Set(Array.isArray(job.excludeTools) ? job.excludeTools : []), { autoEnableCodemode: parsed.autoEnableCodemode });
+		if (cut !== null) return { refused: "mcp-excluded", name: cut.name, why: cut.why };
+		if (egress) {
+			let list = null;
+			let declared = null;
+			// The allowlist read that may pass on a retry is retried, like the overlay's; any other failure refuses, since
+			// without the list no server outside a declared endpoint can be judged reachable.
+			const readList = () => {
+				try {
+					return allowlist();
+				} catch (error) {
+					if (MCP_TRANSIENT_READ_CODES.has(error?.code)) throw Object.assign(new Error("transient"), { transient: error.code });
+					throw Object.assign(new Error("unreadable"), { unreadable: error?.code ?? "unreadable" });
+				}
+			};
+			try {
+				for (const name of names) {
+					const server = servers[name];
+					if (name === FORGE_MCP_SERVER_NAME) {
+						// Its API host, judged as a streamable HTTP server's url is: the proxy sees the same CONNECT either way.
+						list ??= readList();
+						declared ??= endpoints();
+						const refusal = egressRefusalFor(forgeMcpEgressUrl(job.kind, { gitlabUrl }), { allowlist: list, endpoints: declared });
+						if (refusal !== null) return { refused: "mcp-egress-unreachable", name, why: refusal };
+					} else if (server.transport === "http") {
+						list ??= readList();
+						declared ??= endpoints();
+						const refusal = egressRefusalFor(server.url, { allowlist: list, endpoints: declared });
+						if (refusal !== null) return { refused: "mcp-egress-unreachable", name, why: refusal };
+					} else if (server.packageRunner) {
+						list ??= readList();
+						const missing = packageRunnerHosts(server.command).filter((host) => allowlistEntryFor(list, host) === null);
+						if (missing.length > 0) return { refused: "mcp-package-runner", name, why: `it fetches its server from ${missing.join(" and ")}, which egress-allowlist.conf does not hold` };
+					}
+				}
+			} catch (error) {
+				if (error?.transient) return { unavailable: error.transient };
+				if (error?.unreadable) return { refused: "mcp-egress-unreachable", name: null, why: `egress-allowlist.conf cannot be read (${error.unreadable})` };
+				throw error;
+			}
+		}
+		return { ok: true, document: jobMcpDocument({ ...parsed, servers }, names) };
+	};
+}
+
+/**
+ * A server's exposures as pi reads them (`getMcpToolExposure`): an exact tool name first, then the patterns in order,
+ * the first that matches winning, else the server's own. So a pattern after `*` never applies, and `*` replaces the
+ * default; any exact name and any earlier pattern may still match a tool.
+ */
+function exposuresOf(server) {
+	const own = server.exposure ?? "codemode";
+	const entries = Object.entries(server.toolExposure ?? {}).filter(([key]) => !key.startsWith("dispatch_"));
+	const tools = entries.filter(([key]) => !key.includes("*")).map(([, value]) => value);
+	let base = own;
+	for (const [key, value] of entries.filter(([key]) => key.includes("*"))) {
+		if (key === "*") {
+			base = value;
+			break;
+		}
+		tools.push(value);
+	}
+	return { own, tools: [base, ...tools] };
+}
+
+/**
+ * Whether each named server keeps a way in through the tools `excluded` leaves, as pi 1.1.0 routes them: a `direct` tool
+ * needs nothing; a `codemode` or `deferred` tool is reached by whichever discovery tool is active, since codemode calls
+ * both kinds and tool_search loads both, and pi activates codemode when some server has a codemode tool (and
+ * `autoEnableCodemode` is not false) and tool_search when some server has a deferred one; the resource tools take their
+ * server's own exposure, and a `hidden` server's resources are never offered. Judged only for what the trigger's
+ * exclusions take away: a server the overlay leaves no way in is the overlay's, not this trigger's to be refused for.
+ * Returns `{ name, why }` for the first server the exclusions cut off, or null.
+ */
+export function mcpRouteProblem(servers, names, excluded, { autoEnableCodemode = true } = {}) {
+	const routes = (removed) => {
+		const all = names.map((name) => exposuresOf(servers[name]));
+		const has = (kind) => all.some(({ own, tools }) => own === kind || tools.includes(kind));
+		const discovery = (!removed.has("codemode") && autoEnableCodemode !== false && has("codemode")) || (!removed.has("tool_search") && has("deferred"));
+		const reach = (exposure) => exposure === "direct" || ((exposure === "codemode" || exposure === "deferred") && discovery);
+		const widest = ["direct", "codemode", "deferred"].find((kind) => all.some(({ own }) => own === kind)) ?? "hidden";
+		return names.map((name, i) => {
+			const { own, tools } = all[i];
+			const toolRoute = !removed.has(mcpServerToolPattern(name)) && tools.some(reach);
+			// pi registers the resource tools once, with the widest exposure among the servers that offer resources
+			// and are not hidden (syncResourceTools), and read_mcp_resource reads any of them. Whether a server lists
+			// resources is unknown until it connects, so each one that is not hidden is assumed to.
+			const resourceRoute = !removed.has("read_mcp_resource") && own !== "hidden" && reach(widest);
+			return toolRoute || resourceRoute;
+		});
+	};
+	const before = routes(new Set());
+	const after = routes(excluded);
+	const i = names.findIndex((_, k) => before[k] && !after[k]);
+	return i < 0 ? null : { name: names[i], why: "run.excludeTools removes every tool that reaches it (its own, the discovery tools that reach them, and read_mcp_resource)" };
+}
+
+/**
+ * The refusal's public sentence, per reason. Fixed text: the comment posts on the issue, and `why` can name an
+ * internal host or a variable, which belong in the worker's log, not in a thread anyone can read.
+ */
+export const MCP_REFUSAL_COMMENT = Object.freeze({
+	"mcp-list-invalid": "the list this job carries is not one the triggers file's loader writes (a service in this deployment may be at another version)",
+	"mcp-config-invalid": "this deployment's list of MCP servers (mcp.json in the overlay) cannot be used",
+	"mcp-server-unknown": "this deployment does not offer that server",
+	"mcp-secret-reserved": "that server would be handed a credential this deployment keeps for the job itself",
+	"mcp-secret-unmapped": "a credential that server needs is not passed by this trigger",
+	"mcp-excluded": "this trigger's run.excludeTools removes every way the job could reach that server",
+	"mcp-egress-unreachable": "the egress policy does not let a job reach that server",
+	"mcp-package-runner": "the egress policy does not let a job reach the registry that server is fetched from",
+});

package/src/model-catalog.mjs

@@ -125,6 +125,8 @@ export function overlayProviderProblem(config, providerId) {
 		if (!api) return "no-api";
 		const baseUrl = def.baseUrl ?? config.baseUrl ?? defaults?.baseUrl;
 		if (!baseUrl) return "no-baseUrl";
+		// pi 1.2.0's schema refuses both first (a token count must be above zero), so a file reaching here holds none; kept
+		// because provider-composer.js still checks them, and the mirror follows that file, not the schema in front of it.
 		if (def.contextWindow !== undefined && def.contextWindow <= 0) return "contextWindow";
 		if (def.maxTokens !== undefined && def.maxTokens <= 0) return "maxTokens";
 		const composed = { id: def.id, api, baseUrl };

package/src/model-endpoints.mjs

@@ -363,7 +363,12 @@ export function modelEntryOf(models, provider, modelId) {
 	return { entry, defined, override: override !== null && typeof override === "object" ? override : null };
 }
 
-function matching(baseUrl, endpoints) {
+/**
+ * The declared endpoints a URL dials: those whose host AND port `baseUrlTarget` reads from it. The one match, for a
+ * model's baseUrl here, an MCP server's url at the pickup's egress check (`egressRefusalFor`) and doctor's endpoint
+ * probes alike, so the three cannot disagree on which endpoint a URL is.
+ */
+export function endpointsAt(baseUrl, endpoints) {
 	const target = baseUrlTarget(baseUrl);
 	if (target === null || !Array.isArray(endpoints)) return [];
 	return endpoints.filter((e) => e.host === target.host && e.port === target.port);
@@ -380,7 +385,7 @@ export function endpointsForModel({ models, provider, modelId, endpoints }) {
 	if (entry === null) return [];
 	const model = modelsOf(entry).find((m) => m.id === modelId);
 	const baseUrl = typeof model?.baseUrl === "string" ? model.baseUrl : entry.baseUrl;
-	return matching(baseUrl, endpoints);
+	return endpointsAt(baseUrl, endpoints);
 }
 
 /**
@@ -391,7 +396,7 @@ export function endpointsForModel({ models, provider, modelId, endpoints }) {
 export function endpointsForProvider({ models, provider, endpoints }) {
 	const entry = providerOf(models, provider);
 	if (entry === null) return [];
-	return modelsOf(entry).map((m) => ({ modelId: m.id, endpoints: matching(typeof m.baseUrl === "string" ? m.baseUrl : entry.baseUrl, endpoints) }));
+	return modelsOf(entry).map((m) => ({ modelId: m.id, endpoints: endpointsAt(typeof m.baseUrl === "string" ? m.baseUrl : entry.baseUrl, endpoints) }));
 }
 
 /**

package/src/models-json.mjs

@@ -121,8 +121,13 @@ const T = {
 const opt = (check) => [check, true];
 const req = (check) => [check, false];
 
-// The schema, transcribed from model-config.js at the pin (1.0.3; worker/test/models-json.test.mjs holds the file's
-// content hash), in its order.
+// The schema, transcribed at the pin (1.2.0; worker/test/models-json.test.mjs holds each file's content hash). Since
+// 1.2.0 model-config.js builds it from two pi-ai modules, `providers/model-schema.js` (cost, prompt cache, input
+// limits, thinking map, modalities) and `providers/compat-schema.js` (compat), so all three are pinned.
+//
+// The change that matters in 1.2.0: `compat` was a UNION of three object schemas that each admit extra keys, so a value
+// one api's schema refused passed through another (`supportsStore: "x"` loaded). It is now ONE object, the superset of
+// five apis' properties, so every known compat key is type-checked wherever `compat` appears.
 const PercentileCutoffs = T.obj({ p50: opt(T.num()), p75: opt(T.num()), p90: opt(T.num()), p99: opt(T.num()) });
 const numOrStr = T.union(T.num(), T.str());
 const OpenRouterRouting = T.obj({
@@ -141,70 +146,76 @@ const OpenRouterRouting = T.obj({
 	preferred_max_latency: opt(T.union(T.num(), PercentileCutoffs)),
 });
 const VercelGatewayRouting = T.obj({ only: opt(T.arr(T.str())), order: opt(T.arr(T.str())) });
+// model-schema.js: `Partial(Record(Enum(levels), String | Null))`, which checks the seven level keys and admits others.
 const ThinkingValue = T.union(T.str(), T.nul());
 const ThinkingLevelMap = T.obj({ off: opt(ThinkingValue), minimal: opt(ThinkingValue), low: opt(ThinkingValue), medium: opt(ThinkingValue), high: opt(ThinkingValue), xhigh: opt(ThinkingValue), max: opt(ThinkingValue) });
 // pi 1.0.2 (issue #587): a model's sampling parameters, and the same per thinking level, merged per call over them.
 const SamplingParams = T.rec(T.unknown());
 const SamplingParamsByThinkingLevel = T.obj({ off: opt(SamplingParams), minimal: opt(SamplingParams), low: opt(SamplingParams), medium: opt(SamplingParams), high: opt(SamplingParams), xhigh: opt(SamplingParams), max: opt(SamplingParams) });
-const KwargScalar = T.union(T.str(), T.num(), T.bool(), T.nul());
-const KwargVariable = T.obj({ $var: req(T.union(T.lit("thinking.enabled"), T.lit("thinking.effort"))), omitWhenOff: opt(T.bool()) });
-const Kwarg = T.union(KwargScalar, KwargVariable);
+const KwargValue = T.union(T.str(), T.num(), T.bool(), T.nul(), T.obj({ $var: req(T.union(T.lit("thinking.enabled"), T.lit("thinking.effort"), T.lit("thinking.budget"))), omitWhenOff: opt(T.bool()) }));
 const affinity = T.union(T.lit("openai"), T.lit("openai-nosession"), T.lit("openrouter"));
-const OpenAICompletionsCompat = T.obj({
-	supportsStore: opt(T.bool()),
-	supportsDeveloperRole: opt(T.bool()),
-	supportsReasoningEffort: opt(T.bool()),
-	supportsUsageInStreaming: opt(T.bool()),
-	supportsFinishReason: opt(T.bool()),
-	maxTokensField: opt(T.union(T.lit("max_completion_tokens"), T.lit("max_tokens"))),
-	requiresToolResultName: opt(T.bool()),
-	requiresAssistantAfterToolResult: opt(T.bool()),
-	requiresThinkingAsText: opt(T.bool()),
-	requiresReasoningContentOnAssistantMessages: opt(T.bool()),
-	thinkingFormat: opt(T.union(...["openai", "openrouter", "together", "baseten", "deepseek", "zai", "qwen", "chat-template", "qwen-chat-template", "string-thinking", "ant-ling"].map((x) => T.lit(x)))),
-	chatTemplateKwargs: opt(T.rec(Kwarg)),
-	chatTemplateArgs: opt(T.rec(Kwarg)),
-	cacheControlFormat: opt(T.lit("anthropic")),
-	openRouterRouting: opt(OpenRouterRouting),
-	vercelGatewayRouting: opt(VercelGatewayRouting),
-	supportsOpenAIGrammarTools: opt(T.bool()),
-	supportsStrictMode: opt(T.bool()),
-	sendSessionAffinityHeaders: opt(T.bool()),
-	sessionAffinityFormat: opt(affinity),
-	supportsLongCacheRetention: opt(T.bool()),
-	vllmPriority: opt(T.num()),
-});
-const OpenAIResponsesCompat = T.obj({
-	supportsDeveloperRole: opt(T.bool()),
-	sessionAffinityFormat: opt(affinity),
-	supportsLongCacheRetention: opt(T.bool()),
-	supportsStrictMode: opt(T.bool()),
-	supportsOpenAIGrammarTools: opt(T.bool()),
-	supportsMaxOutputTokens: opt(T.bool()),
-});
 const costRates = { input: req(T.num()), output: req(T.num()), cacheRead: req(T.num()), cacheWrite: req(T.num()) };
 const ModelCostTier = T.obj({ inputTokensAbove: req(T.num()), ...costRates });
 const ModelCost = T.obj({ ...costRates, tiers: opt(T.arr(ModelCostTier)) });
+// `Partial(Record(Enum(["short", "long"]), Number > 0))`, like the thinking map.
 const ModelPromptCache = T.obj({ short: opt(T.num({ exclusiveMinimum: 0 })), long: opt(T.num({ exclusiveMinimum: 0 })) });
 const posInt = T.int({ minimum: 1 });
 const ImageResize = T.obj({ maxWidth: opt(posInt), maxHeight: opt(posInt), maxBytes: opt(posInt), jpegQuality: opt(T.int({ minimum: 1, maximum: 100 })) });
 const ModelInputLimits = T.obj({ maxRequestBytes: opt(posInt), images: opt(T.obj({ resize: opt(ImageResize), maxPerMessage: opt(posInt), maxPerRequest: opt(posInt) })) });
-const AnthropicMessagesCompat = T.obj({
-	supportsEagerToolInputStreaming: opt(T.bool()),
-	supportsLongCacheRetention: opt(T.bool()),
-	sendSessionAffinityHeaders: opt(T.bool()),
-	supportsCacheControlOnTools: opt(T.bool()),
-	supportsTemperature: opt(T.bool()),
-	forceAdaptiveThinking: opt(T.bool()),
-	allowEmptySignature: opt(T.bool()),
-	supportsStrictTools: opt(T.bool()),
-	supportsMidConvoEffort: opt(T.bool()),
+// compat-schema.js's ProviderCompatSchema: the merged properties of the OpenAI completions, OpenAI responses, Anthropic
+// messages, Bedrock and Mistral schemas. A key two of them share takes pi's generic override, which for every shared
+// key here is the same type as each api's own (a boolean, or the three-way affinity format), so the superset is exact.
+const bool = opt(T.bool());
+const ProviderCompat = T.obj({
+	// OpenAI completions
+	supportsStore: bool,
+	supportsDeveloperRole: bool,
+	supportsReasoningEffort: bool,
+	supportsUsageInStreaming: bool,
+	supportsFinishReason: bool,
+	maxTokensField: opt(T.union(T.lit("max_completion_tokens"), T.lit("max_tokens"))),
+	requiresToolResultName: bool,
+	requiresAssistantAfterToolResult: bool,
+	requiresThinkingAsText: bool,
+	requiresReasoningContentOnAssistantMessages: bool,
+	thinkingFormat: opt(T.union(...["openai", "openrouter", "deepseek", "together", "baseten", "zai", "qwen", "chat-template", "qwen-chat-template", "string-thinking", "ant-ling"].map((x) => T.lit(x)))),
+	chatTemplateKwargs: opt(T.rec(KwargValue)),
+	chatTemplateArgs: opt(T.rec(KwargValue)),
+	openRouterRouting: opt(OpenRouterRouting),
+	vercelGatewayRouting: opt(VercelGatewayRouting),
+	zaiToolStream: bool,
+	thinkingTokenBudgetField: opt(T.union(T.lit("thinking_token_budget"), T.lit("thinking_budget"), T.lit("thinking_budget_tokens"))),
+	supportsThinkingTokenBudget: bool,
+	supportsOpenAIGrammarTools: bool,
+	supportsMidConvoSystemMessages: bool,
+	supportsMidConvoToolAdditions: bool,
+	supportsStrictMode: bool,
+	cacheControlFormat: opt(T.lit("anthropic")),
+	sendSessionAffinityHeaders: bool,
+	sessionAffinityFormat: opt(affinity),
+	supportsLongCacheRetention: bool,
+	vllmPriority: opt(T.num()),
+	// OpenAI responses
+	supportsAdditionalTools: bool,
+	supportsToolSearch: bool,
+	supportsExplicitPromptCacheMode: bool,
+	supportsMaxOutputTokens: bool,
+	// Anthropic messages
+	supportsEagerToolInputStreaming: bool,
+	supportsCacheControlOnTools: bool,
+	supportsTemperature: bool,
+	forceAdaptiveThinking: bool,
+	allowEmptySignature: bool,
+	supportsStrictTools: bool,
+	supportsMidConvoEffort: bool,
+	supportsMidConvoToolChanges: bool,
 	allowedFallbackModels: opt(T.arr(T.obj({ provider: req(T.str({ minLength: 1 })), model: req(T.str({ minLength: 1 })), cost: req(ModelCost) }), { maxItems: 3 })),
 });
-const ProviderCompat = T.union(OpenAICompletionsCompat, OpenAIResponsesCompat, AnthropicMessagesCompat);
 const nonEmpty = T.str({ minLength: 1 });
 const inputKinds = T.arr(T.union(T.lit("text"), T.lit("image")));
 const headers = T.rec(T.str());
+// 1.2.0: a token count must be above zero, where any number passed before.
+const tokenCount = T.num({ exclusiveMinimum: 0 });
 const ModelDefinition = T.obj({
 	id: req(nonEmpty),
 	name: opt(nonEmpty),
@@ -216,8 +227,8 @@ const ModelDefinition = T.obj({
 	inputLimits: opt(ModelInputLimits),
 	cost: opt(ModelCost),
 	promptCache: opt(ModelPromptCache),
-	contextWindow: opt(T.num()),
-	maxTokens: opt(T.num()),
+	contextWindow: opt(tokenCount),
+	maxTokens: opt(tokenCount),
 	samplingParams: opt(SamplingParams),
 	samplingParamsByThinkingLevel: opt(SamplingParamsByThinkingLevel),
 	headers: opt(headers),
@@ -231,8 +242,8 @@ const ModelOverride = T.obj({
 	inputLimits: opt(ModelInputLimits),
 	cost: opt(T.obj({ input: opt(T.num()), output: opt(T.num()), cacheRead: opt(T.num()), cacheWrite: opt(T.num()), tiers: opt(T.arr(ModelCostTier)) })),
 	promptCache: opt(ModelPromptCache),
-	contextWindow: opt(T.num()),
-	maxTokens: opt(T.num()),
+	contextWindow: opt(tokenCount),
+	maxTokens: opt(tokenCount),
 	samplingParams: opt(SamplingParams),
 	samplingParamsByThinkingLevel: opt(SamplingParamsByThinkingLevel),
 	headers: opt(headers),
@@ -250,7 +261,8 @@ const ProviderConfig = T.obj({
 	models: opt(T.arr(ModelDefinition)),
 	modelOverrides: opt(T.rec(ModelOverride)),
 });
-const ModelsConfig = T.obj({ providers: req(T.rec(ProviderConfig)) });
+// 1.2.0: a `$schema` key (the published https://pi.dev/schemas/models.schema.json) is declared, as a string.
+const ModelsConfig = T.obj({ $schema: opt(T.str()), providers: req(T.rec(ProviderConfig)) });
 
 /**
  * Parse overlay `models.json` TEXT as pi does. `{ value }` when pi would load it, else `{ error }` with a fixed

package/src/outbox.mjs

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { readFlowGate as realReadFlowGate } from "./flow-gate.mjs";
 import { chainedJobId } from "./job-id.mjs";
 import { enqueueLocalJob } from "./queue.mjs";
+import { withoutMcpExclusions } from "./triggers.mjs";
 
 /**
  * The outbox chain collector: the host-side reader of a completed LOCAL parent's `/outbox`, the
@@ -207,7 +208,9 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// parent would chain a child that can edit and run bash, a widening no operator wrote.
 					// Off `job.data`, never off `req` -- the request file can neither set nor drop it (explicit
 					// property reads only, above), so the agent cannot widen its child by omitting a key.
-					excludeTools: job.data?.excludeTools,
+					// Less the names of the parent's MCP tools: the child connects no server (`mcp` below), its runner knows
+					// none of them, and they would refuse it at start while removing nothing.
+					excludeTools: withoutMcpExclusions(job.data?.excludeTools),
 					// `secrets`/`secretsProfile` are deliberately ABSENT, and the two lines above are exactly why
 					// this comment exists: their reasoning reads as though it should apply here too, and it must
 					// not. An image and a skills directory are toolchain; a resolved credential is a capability.
@@ -219,6 +222,9 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// `portfolio` (issue #505) is ABSENT for the same reason, and more plainly: it is budget authority, granted
 					// to one cron trigger the operator reviewed. A child is an agent's request, so inheriting the flag would let
 					// a portfolio job queue a second plan writer of its own choosing.
+					// `mcp` (REQ-MCP-OPERATOR-SERVERS) is ABSENT for the secrets' reason: a server is reached with the
+					// credentials its trigger maps, a capability granted to the trigger the operator reviewed. A child
+					// without it connects no server, which is the narrowing direction.
 					chainDepth: childDepth,
 					parentJobId: job.id,
 					// chainedJobId deliberately does NOT take the image: the child's identity is (parent, flow, task).

package/src/parked.mjs

@@ -0,0 +1,18 @@
+/**
+ * REQ-AWAIT-INPUT, the reply half (issue #625): the forge marker on an issue whose last run is waiting for an answer.
+ *
+ * Imported by both services, like capabilities.mjs, because the receiver routes on it and the worker writes it: two
+ * spellings of one label would be two places for one to drift while every test stayed green.
+ *
+ * THE LABEL IS A HINT, THE SIDECAR IS THE TRUTH. The receiver cannot read the session store (on a fleet it may not
+ * even run beside one), so a label the forge already sends in every comment payload is what lets it route a reply
+ * that carries no trigger phrase. Anyone who may label an issue can set it, so it decides nothing on its own: the
+ * worker refuses such a reply before any spend unless the key's `parked` sidecar exists (`not-parked`). And it
+ * widens WHICH comments start a job, never WHO may: the comment trigger's author gate still runs first.
+ */
+export const PARKED_LABEL = "pi-awaiting-input";
+
+/** Whether a subset's `[{ name }]` label list (or Azure's tag list, the same shape) carries the marker. */
+export function hasParkedLabel(labels) {
+	return Array.isArray(labels) && labels.some((label) => label?.name === PARKED_LABEL);
+}

package/src/prepare.mjs

@@ -1,8 +1,9 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveBackendName } from "./backend-registry.mjs";
 import { ensureJobsDir } from "./config.mjs";
+import { JOB_MCP_FILE } from "./mcp-config.mjs";
 import { resolveJobImage } from "./image-preflight.mjs";
 import { retainJobDir } from "./sandbox-store.mjs";
 import { prepareGithubWorkspace } from "./prepare-github.mjs";
@@ -84,7 +85,7 @@ export function makePrepareWorkspace({
 	removeDir = (dir) => rmSync(dir, { recursive: true, force: true }),
 }) {
 	ensureDir(jobsDir);
-	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false, size = null } = {}) {
+	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false, size = null, mcp = null } = {}) {
 		ensureDir(jobsDir);
 		const jobDir = mkdtempSync(join(jobsDir, "job-"));
 		// Issue #524: a THROW out of anything below leaves `jobDir` to nobody. The processor tears down only what
@@ -94,7 +95,7 @@ export function makePrepareWorkspace({
 		// covers the thrown ones, in one place for every kind, rather than in each preparer that can throw.
 		// A retry makes a fresh directory, so nothing is lost by removing this one.
 		try {
-			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size });
+			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size, mcp });
 		} catch (error) {
 			// GUARDED: a removal that fails (a busy mount, a permission flipped mid-job) must never replace the error
 			// that is the job's actual outcome. The directory is then left, which is what happened before this catch.
@@ -105,7 +106,7 @@ export function makePrepareWorkspace({
 		}
 	};
 
-	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size }) {
+	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size, mcp }) {
 		// The trigger's injected skills (REQ-PER-TRIGGER-SKILLS, issue #60), COPIED here rather than
 		// mounted, and copied ONCE for every job kind because this is where local and forge converge.
 		//
@@ -126,6 +127,13 @@ export function makePrepareWorkspace({
 			// a host path by a later edit (the same shape packages.mjs's `dropped` record has).
 			log("trigger_skills_injected", { dirs: injected.dirs, files: injected.files, bytes: injected.bytes });
 		}
+		// The job's MCP servers (REQ-MCP-OPERATOR-SERVERS), as the processor's check passed them: written here, beside the
+		// injected skills, for their reason (no new mount, and fixed for the life of the job). References only, never a
+		// value (mcp-config.mjs `jobMcpDocument`), and read-only to the job like everything under /job.
+		if (mcp) {
+			writeFileSync(join(jobDir, JOB_MCP_FILE), `${JSON.stringify(mcp, null, 2)}\n`, { mode: 0o444 });
+			log("mcp_config_written", { servers: Object.keys(mcp.servers).length, refs: Object.values(mcp.refs).reduce((n, list) => n + list.length, 0) });
+		}
 		// What `cleanup` needs to retain this run's directory, stamped here because this is the only place
 		// that holds all of it at once. Applied to the RESULT rather than mutated in, so a preparer's
 		// `{ outcome: "policy" }` refusal -- which carries no jobDir -- is passed through untouched.