@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/src/model-ref.mjs

@@ -0,0 +1,151 @@
+/**
+ * The one spelling of "what a model or provider id may look like" in a record (issues #501, #502).
+ *
+ * PURE and import-free, on purpose: `triggers.mjs` is the shared validator the receiver loads and the admin
+ * bundle inlines, and the model-reference checks that land on top of this (a trigger's `run.provider` and
+ * `run.model`, an allowed-model list) must be importable there without dragging anything in.
+ *
+ * Applied AFTER lowercasing, as the run record's ledger always has (`parseExitUsage`), so the pattern never
+ * has to admit uppercase.
+ *
+ * WHY IT WIDENED. The ledger's old pattern, `^[a-z0-9][a-z0-9._:/-]{0,63}$`, refused real catalog ids, and
+ * one refused row nulls the whole `usage` block, so a job on such a model recorded no ledger at all. Measured
+ * on 2026-10-02 against pi-ai 0.99.1's builtin catalog (`getAllBuiltinModels` over all 42 providers, chat,
+ * image and classifier models, 1,589 ids): the old pattern refused 55. Two shapes:
+ *   - 37 contain an `@` or start with `~`: `cloudflare-ai-gateway`'s `workers-ai/@cf/...` and openrouter's
+ *     `~vendor/model` aliases;
+ *   - 18 START with `@`: `cloudflare-workers-ai`'s own `@cf/vendor/model` ids.
+ * Ollama tags (`qwen2.5:0.5b-instruct-q4_K_M`) carry `_`, which it refused too. This pattern admits all 1,589
+ * builtin ids and every provider id. The longest builtin id is 56 characters, inside the 64 cap.
+ *
+ * What it still refuses, and why that is kept: a first character (after one optional `~` or `@`) that is
+ * not a letter or digit, so `.hidden`, `../etc`, `/abs` and `:x` fail at character one, as before; any
+ * character outside the class (space, quote, backslash, control bytes); and anything over 64 characters.
+ */
+export const MODEL_REF_PATTERN = /^(?=.{1,64}$)[~@]?[a-z0-9][a-z0-9._:/@_-]*$/;
+
+/**
+ * A trigger's provider id (issue #502). Narrower than a model id: no `/`, `:` or `@` and no leading `~`.
+ * Those characters exist in MODEL ids (`@cf/...`, `openrouter/~...`, Ollama `name:tag`), never in a provider
+ * id, and an allowed-model entry (`provider/model`) splits at the first `/`, so a provider carrying one could
+ * never be listed. Applied after lowercasing, like `MODEL_REF_PATTERN`.
+ */
+export const PROVIDER_REF_PATTERN = /^(?=.{1,64}$)[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Validate the optional `run.provider`, `run.model`, `run.maxTurns` and `run.models` of one trigger (issue #502) and return
+ * the fields that were present, so a normalizer can spread them and an absent field stays absent. Shared by
+ * the trigger loader and the console, so both refuse with the same words.
+ *
+ * A model is checked against `MODEL_REF_PATTERN`, the ledger's own pattern, so any model a trigger can name
+ * is one whose usage row the host keeps. The original case is what the job runs with, because pi matches
+ * model ids case-sensitively; only the CHECK lowercases.
+ *
+ * Errors name the trigger and the key and never echo the value: an operator-typed id is not secret, but the
+ * console renders this message to a model, and a key name is all an operator needs to find the line.
+ */
+export function validateModelRef(run, at, path) {
+	// `configError`'s exact shape (config.mjs), built here rather than imported so this module stays
+	// import-free: run-history.mjs imports it too, and must not drag config.mjs's fs and os in with it.
+	const configError = (message) => Object.assign(new Error(message), { piDispatchConfig: true });
+	const out = {};
+	// ASCII is checked on the ORIGINAL before lowercasing, because lowercasing is not closed over ASCII:
+	// the Kelvin sign (U+212A) lowercases to a plain `k`, so a lowercase-then-match check alone would pass
+	// a homoglyph that then reaches the job verbatim and names a model nobody listed.
+	const ascii = (value) => /^[\x21-\x7E]+$/.test(value);
+	// NULL IS ABSENT, for all three. Before #502 a hand-written cron entry's `"model": null` loaded and
+	// meant the deployment default (the worker fills `job.data ?? overlay ?? env`, and `??` passes over
+	// null), so refusing it now would turn a working file into one that refuses to load for no gain.
+	if (run?.provider != null) {
+		const provider = run.provider;
+		if (typeof provider !== "string" || !ascii(provider) || !PROVIDER_REF_PATTERN.test(provider.toLowerCase())) {
+			throw configError(`${at}: run.provider must be a provider id of 1 to 64 characters: letters, digits, dot, dash and underscore, starting with a letter or digit: ${path}`);
+		}
+		out.provider = provider;
+	}
+	if (run?.model != null) {
+		const model = run.model;
+		if (typeof model !== "string" || !ascii(model) || !MODEL_REF_PATTERN.test(model.toLowerCase())) {
+			throw configError(`${at}: run.model must be a model id of 1 to 64 characters: letters, digits and . _ - : / @, starting with a letter or digit (or ~ or @ then one): ${path}`);
+		}
+		out.model = model;
+	}
+	if (run?.maxTurns != null) {
+		if (!Number.isSafeInteger(run.maxTurns) || run.maxTurns < 1) {
+			throw configError(`${at}: run.maxTurns must be a positive integer: ${path}`);
+		}
+		out.maxTurns = run.maxTurns;
+	}
+	// `run.models` (issue #502): the models this trigger's job may call. Null is absent, the rule above.
+	if (run?.models != null) {
+		const problem = modelListProblem(run.models);
+		if (problem !== null) throw configError(`${at}: run.models ${problem}: ${path}`);
+		// The main model must be on its own list, refused HERE when the trigger names all three, because the
+		// file alone answers it. When the provider or the model comes from the deployment default instead,
+		// the worker answers it at job start (`model-not-allowed`, pre-spend).
+		if (out.provider !== undefined && out.model !== undefined && !modelOnList(run.models, out.provider, out.model)) {
+			throw configError(`${at}: run.models does not list this trigger's own run.provider/run.model, so every job it starts would be refused: ${path}`);
+		}
+		out.models = [...run.models];
+	}
+	return out;
+}
+
+/** The most entries an allowed-model list may carry (issue #502). Past this a list is a catalog, not a policy. */
+export const MAX_ALLOWED_MODELS = 16;
+
+/**
+ * One allowed-model entry, `provider/model`, split at the FIRST `/` (issue #502): a provider id carries no `/`
+ * while a model id may (`openrouter`'s `vendor/model`, cloudflare's `@cf/vendor/model`). The runner splits the
+ * same way (`image/runner/src/config.mjs`). Each half passes the same rule `run.provider` and `run.model` do,
+ * ASCII checked before lowercasing for the reason `validateModelRef` gives. Returns `{ provider, model }` in
+ * the ORIGINAL case, or `null` when the entry is malformed.
+ */
+export function splitModelEntry(entry) {
+	if (typeof entry !== "string" || !/^[\x21-\x7E]+$/.test(entry)) return null;
+	const slash = entry.indexOf("/");
+	if (slash <= 0) return null;
+	const provider = entry.slice(0, slash);
+	const model = entry.slice(slash + 1);
+	if (!PROVIDER_REF_PATTERN.test(provider.toLowerCase()) || !MODEL_REF_PATTERN.test(model.toLowerCase())) return null;
+	return { provider, model };
+}
+
+/**
+ * An allowed-model list (issue #502), from a trigger's `run.models` or the deployment's `PI_ALLOWED_MODELS`:
+ * the problem as a sentence, or null when the list is good. ONE rule for both sources, so a list an operator
+ * moves from a trigger into the env (or back) means the same thing in both places.
+ *   - 1 to 16 entries. EMPTY is refused, never read as "unrestricted" or as "nothing allowed": the first fails
+ *     open, the second refuses every call of a job whose operator meant something else, and an empty list in a
+ *     reviewed file is more likely a template bug than either. Absent (or null) is how a list says "none".
+ *   - every entry `provider/model`, see `splitModelEntry`.
+ *   - no duplicates, compared CASE-INSENSITIVELY. Matching at the runner is exact, so `openai/GPT-x` beside
+ *     `openai/gpt-x` is at best a dead entry and at worst the one that was meant; either way it is a typo the
+ *     file should not keep, and the run record's ledger lowercases ids, where the two would be one row.
+ * The entry text is never echoed: the position is, and the console renders this message to a model.
+ */
+export function modelListProblem(list) {
+	if (!Array.isArray(list)) return "must be an array of provider/model strings";
+	if (list.length === 0) return "must not be empty (leave it out for no restriction)";
+	if (list.length > MAX_ALLOWED_MODELS) return `must have at most ${MAX_ALLOWED_MODELS} entries`;
+	const seen = new Set();
+	for (let i = 0; i < list.length; i++) {
+		if (splitModelEntry(list[i]) === null) return `entry ${i + 1} must be provider/model: a provider id, a slash, then a model id (each 1 to 64 characters, no spaces)`;
+		const key = list[i].toLowerCase();
+		if (seen.has(key)) return `entry ${i + 1} repeats an earlier entry (compared ignoring case)`;
+		seen.add(key);
+	}
+	return null;
+}
+
+/**
+ * Is `provider/model` on the list? EXACT and case-sensitive, the runner guard's rule, because pi resolves model
+ * ids case-sensitively: an entry differing only in case names a model pi would not pick. Both halves are
+ * compared, so a list naming `openai/x` does not admit `azure-openai-responses/x`.
+ */
+export function modelOnList(list, provider, model) {
+	if (!Array.isArray(list)) return true;
+	return list.some((entry) => {
+		const ref = splitModelEntry(entry);
+		return ref !== null && ref.provider === provider && ref.model === model;
+	});
+}

package/src/models-json.mjs

@@ -0,0 +1,262 @@
+/**
+ * The overlay `models.json`, read the way pi reads it (issue #502, PR #536's review): pi 0.99.1's
+ * `ModelConfig.load` (`pi-coding-agent/dist/core/model-config.js`) strips a leading BOM, strips `//` comments and
+ * trailing commas outside strings, parses, and then checks the whole document against its TypeBox schema. ANY
+ * schema error drops the WHOLE file: pi then knows none of its providers or models.
+ *
+ * The worker must agree with that verdict in both directions, because it decides with it before any spend:
+ *   - a file pi accepts (comments, a BOM, a trailing comma) must not be refused here, or a working overlay model
+ *     reads as unknown;
+ *   - a file pi drops (a `contextWindow: "big"` on some other provider) must not be accepted here, or the job is
+ *     admitted, reserves, starts a container, and the runner exits 2 on a model pi never loaded.
+ *
+ * MIRRORED, not imported: the worker depends on pi-ai only and does not import pi-coding-agent, and the module is
+ * not an exported path of that package. The mirror is held to pi by a DIFFERENTIAL test
+ * (`worker/test/models-json.test.mjs`) that runs pi's own `ModelConfig.load` at the pin over a corpus of valid and
+ * mutated files and requires the same verdict on every one, so a pi bump that moves the schema fails there.
+ *
+ * Pure: text in, `{ value }` or `{ error }` out. The fs read stays in `readOverlayModels` (model-endpoints.mjs).
+ */
+
+/** pi's `stripBom` (`utils/text.js`): one leading U+FEFF. */
+export function stripBom(text) {
+	return text.startsWith("\uFEFF") ? text.slice(1) : text;
+}
+
+/**
+ * pi's `stripJsonComments` (`utils/json.js`): `//` line comments and trailing commas, strings untouched. pi writes it
+ * as two global regex replaces (a string or a `//` comment, then a string or a comma before `}` or `]`), which
+ * are QUADRATIC on an unterminated string (PR #546's review: `'"' + '\\"'.repeat(n)` at 160 KB took 13 s on the
+ * worker's event loop, once per job). This is the same function as one linear scan per pass, held to pi's own output
+ * by a differential test over the corpus and adversarial cases (`models-json.test.mjs`).
+ *
+ * How it stays linear and exact. At a `"` the regex tries a string: escapes `\` plus any one code unit but a line
+ * terminator (`.` without the `s` flag), other code units but `"` and `\`, up to the first unescaped `"`. When that
+ * fails (end of text, or a `\` before a line terminator or at the end), the regex moves ONE code unit on. Every `"`
+ * up to the failure point is then an escaped one in the failed attempt's reading, so a string tried there reads the
+ * same code units from the next boundary on and fails at the same point. Those starts are skipped, not retried.
+ */
+const isLineTerminator = (c) => c === "\n" || c === "\r" || c === "\u2028" || c === "\u2029";
+
+/** Where the string opened at `start` closes (the index of its closing `"`), else `{ failAt }`. */
+function stringEnd(input, start) {
+	let j = start + 1;
+	while (j < input.length) {
+		const c = input[j];
+		if (c === '"') return { end: j };
+		if (c === "\\") {
+			if (j + 1 >= input.length || isLineTerminator(input[j + 1])) return { failAt: j };
+			j += 2;
+		} else j += 1;
+	}
+	return { failAt: input.length };
+}
+
+/** One pass: strings kept, and at any other code unit `other(i)` returns `[text to emit, next index]` or null. */
+function scanPass(input, other) {
+	let out = "";
+	let i = 0;
+	let failedUntil = -1; // a `"` at or before this index cannot open a string (see above)
+	while (i < input.length) {
+		if (input[i] === '"' && i > failedUntil) {
+			const r = stringEnd(input, i);
+			if (r.end !== undefined) {
+				out += input.slice(i, r.end + 1);
+				i = r.end + 1;
+				continue;
+			}
+			failedUntil = r.failAt;
+		}
+		const step = input[i] === '"' ? null : other(i);
+		if (step === null) {
+			out += input[i];
+			i += 1;
+		} else {
+			out += step[0];
+			i = step[1];
+		}
+	}
+	return out;
+}
+
+const isJsSpace = (c) => /\s/.test(c);
+
+export function stripJsonComments(input) {
+	const noComments = scanPass(input, (i) => {
+		if (input[i] !== "/" || input[i + 1] !== "/") return null;
+		let j = i + 2;
+		while (j < input.length && input[j] !== "\n") j += 1;
+		return ["", j];
+	});
+	return scanPass(noComments, (i) => {
+		if (noComments[i] !== ",") return null;
+		let j = i + 1;
+		while (j < noComments.length && isJsSpace(noComments[j])) j += 1;
+		if (noComments[j] !== "}" && noComments[j] !== "]") return null;
+		return [noComments.slice(i + 1, j + 1), j + 1];
+	});
+}
+
+// A minimal interpreter for the TypeBox kinds pi's schema uses. TypeBox's defaults, as compiled at the pin: an
+// Object admits extra keys and refuses arrays and null; a Number is a finite number; a Record checks every own value
+// whose key has no line terminator.
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const T = {
+	str: ({ minLength = 0 } = {}) => (v) => typeof v === "string" && v.length >= minLength,
+	num: ({ exclusiveMinimum } = {}) => (v) => typeof v === "number" && Number.isFinite(v) && (exclusiveMinimum === undefined || v > exclusiveMinimum),
+	int: ({ minimum, maximum } = {}) => (v) => Number.isInteger(v) && (minimum === undefined || v >= minimum) && (maximum === undefined || v <= maximum),
+	bool: () => (v) => typeof v === "boolean",
+	lit: (x) => (v) => v === x,
+	nul: () => (v) => v === null,
+	unknown: () => () => true,
+	union: (...xs) => (v) => xs.some((x) => x(v)),
+	arr: (x, { maxItems } = {}) => (v) => Array.isArray(v) && (maxItems === undefined || v.length <= maxItems) && v.every((e) => x(e)),
+	// TypeBox compiles `Record(String, X)` to `patternProperties: { "^.*$": X }`, and `.` matches no line terminator, so a
+	// key holding `\n`, `\r`, U+2028 or U+2029 matches no pattern and its value is never checked (PR #536's review,
+	// measured against pi at the pin). Mirrored: such a key's value passes, as it does for pi.
+	rec: (x) => (v) => isObj(v) && Object.entries(v).every(([k, e]) => !/^.*$/.test(k) || x(e)),
+	// `props` maps a key to [check, optional]. A required key must be present.
+	obj: (props) => (v) => isObj(v) && Object.entries(props).every(([k, [check, optional]]) => (Object.hasOwn(v, k) ? check(v[k]) : optional === true)),
+};
+const opt = (check) => [check, true];
+const req = (check) => [check, false];
+
+// The schema, transcribed from model-config.js at the 0.99.1 pin, in its order.
+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({
+	allow_fallbacks: opt(T.bool()),
+	require_parameters: opt(T.bool()),
+	data_collection: opt(T.union(T.lit("deny"), T.lit("allow"))),
+	zdr: opt(T.bool()),
+	enforce_distillable_text: opt(T.bool()),
+	order: opt(T.arr(T.str())),
+	only: opt(T.arr(T.str())),
+	ignore: opt(T.arr(T.str())),
+	quantizations: opt(T.arr(T.str())),
+	sort: opt(T.union(T.str(), T.obj({ by: opt(T.str()), partition: opt(T.union(T.str(), T.nul())) }))),
+	max_price: opt(T.obj({ prompt: opt(numOrStr), completion: opt(numOrStr), image: opt(numOrStr), audio: opt(numOrStr), request: opt(numOrStr) })),
+	preferred_min_throughput: opt(T.union(T.num(), PercentileCutoffs)),
+	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())) });
+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) });
+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 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)) });
+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()),
+	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());
+const ModelDefinition = T.obj({
+	id: req(nonEmpty),
+	name: opt(nonEmpty),
+	api: opt(nonEmpty),
+	baseUrl: opt(nonEmpty),
+	reasoning: opt(T.bool()),
+	thinkingLevelMap: opt(ThinkingLevelMap),
+	input: opt(inputKinds),
+	inputLimits: opt(ModelInputLimits),
+	cost: opt(ModelCost),
+	promptCache: opt(ModelPromptCache),
+	contextWindow: opt(T.num()),
+	maxTokens: opt(T.num()),
+	samplingParams: opt(T.rec(T.unknown())),
+	headers: opt(headers),
+	compat: opt(ProviderCompat),
+});
+const ModelOverride = T.obj({
+	name: opt(nonEmpty),
+	reasoning: opt(T.bool()),
+	thinkingLevelMap: opt(ThinkingLevelMap),
+	input: opt(inputKinds),
+	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()),
+	samplingParams: opt(T.rec(T.unknown())),
+	headers: opt(headers),
+	compat: opt(ProviderCompat),
+});
+const ProviderConfig = T.obj({
+	name: opt(nonEmpty),
+	baseUrl: opt(nonEmpty),
+	apiKey: opt(nonEmpty),
+	api: opt(nonEmpty),
+	oauth: opt(T.lit("radius")),
+	headers: opt(headers),
+	compat: opt(ProviderCompat),
+	authHeader: opt(T.bool()),
+	models: opt(T.arr(ModelDefinition)),
+	modelOverrides: opt(T.rec(ModelOverride)),
+});
+const ModelsConfig = T.obj({ providers: req(T.rec(ProviderConfig)) });
+
+/**
+ * Parse overlay `models.json` TEXT as pi does. `{ value }` when pi would load it, else `{ error }` with a fixed
+ * phrase (never the file's text: models.json may hold keys, and a JSON.parse message quotes around the fault).
+ */
+export function parseModelsJson(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(stripJsonComments(stripBom(String(text))));
+	} catch {
+		return { error: "is not valid JSON" };
+	}
+	if (!ModelsConfig(parsed)) return { error: "does not match pi's models.json schema, so pi would load none of it" };
+	return { value: parsed };
+}

package/src/money.mjs

@@ -0,0 +1,144 @@
+/**
+ * The money type (issue #501): every dollar amount pi-dispatch stores, compares or sends is an INTEGER number
+ * of micro-dollars (1 USD = 1,000,000). Integers add exactly, in JavaScript and in Valkey's INCRBY alike; a
+ * float total drifts, and a cap compared against a drifted total is a cap that admits one call too many.
+ *
+ * PURE and import-free, on `model-ref.mjs`'s rule: `triggers.mjs` (which the receiver loads and the admin
+ * bundle inlines) and `runtime-settings.mjs` (which the admin imports) both validate with it, and neither may
+ * drag config.mjs's fs and os in with it.
+ */
+
+/** Micro-dollars in one dollar. */
+export const MICROS_PER_USD = 1_000_000;
+
+/** The largest amount a setting may name: 1,000,000 USD. Far above any real cap, and it keeps every sum safe. */
+export const MAX_USD_MICROS = 1_000_000 * MICROS_PER_USD;
+
+// At most 7 integer digits (the range check below does the real bounding), at most 6 decimals, no sign, no
+// exponent, no leading zeros, no whitespace. The integer part is limited so the arithmetic below stays far
+// inside Number.MAX_SAFE_INTEGER whatever it is handed.
+const USD_PATTERN = /^(0|[1-9]\d{0,6})(\.\d{1,6})?$/;
+
+/** The dollar keys a deployment can set, in the order the settings list them. */
+export const DOLLAR_SETTING_KEYS = Object.freeze(["maxCostUsd", "dailyCostUsd", "weeklyCostUsd", "monthlyCostUsd"]);
+/** Each dollar key's environment variable: one table for config.mjs, doctor and the console. */
+export const DOLLAR_ENV_NAMES = Object.freeze({ maxCostUsd: "PI_MAX_COST_USD", dailyCostUsd: "PI_DAILY_COST_USD", weeklyCostUsd: "PI_WEEKLY_COST_USD", monthlyCostUsd: "PI_MONTHLY_COST_USD" });
+/** The three dollar WINDOWS, each of which needs a per-job cap to reserve (`checkDollarInvariant`). */
+export const DOLLAR_WINDOW_KEYS = Object.freeze(["dailyCostUsd", "weeklyCostUsd", "monthlyCostUsd"]);
+
+// config.mjs's `configError` shape, built here so this module stays import-free (model-ref.mjs does the same).
+function configError(message) {
+	return Object.assign(new Error(message), { piDispatchConfig: true });
+}
+
+/**
+ * Parse a dollar amount into integer micro-dollars, or throw a tagged config error naming `key`.
+ *
+ A STRING is read exactly as written, and that is the form to recommend: the pattern below is applied to
+ * the operator's own characters, so `"1e3"`, `"0.1234567"` and `" 2"` are refused.
+ *
+ * A NUMBER is read by its VALUE, as `String(n)`, the decimal JavaScript prints for it. JSON has already
+ * turned the operator's characters into a float before this runs, so what they typed is gone: `1e2` in a
+ * JSON file is the number 100 and passes as $100, `0.5e1` passes as $5, and `1.00000000000000001` has lost
+ * its last digits to the float and passes as $1. Only a value whose PRINTED form breaks the pattern is
+ * refused: `1e-7` prints "1e-7", `0.1 + 0.2` prints "0.30000000000000004", `1e21` prints "1e+21". So "never
+ * rounded, no exponents" holds for strings; for a number it holds for the value JavaScript prints.
+ *
+ * The conversion is INTEGER-ONLY: the whole part times 1,000,000 plus the decimals padded to six digits.
+ * `Math.round(n * 1e6)` WITHOUT the pattern was the obvious alternative and is wrong, because it would quietly
+ * accept a value with seven decimals and pick a cap the operator never wrote. (With the pattern in front, it
+ * would compute the same integer; the integer form keeps the rule visible.)
+ *
+ * Above 0 and at most 1,000,000 USD. Zero is refused on purpose: a setting of 0 would read as "no cap" to
+ * anyone skimming a file, while the runner reads it as "no priced call at all". The error names the key, never
+ * the value: a value an operator typed into the wrong field could be anything.
+ */
+export function parseUsdMicros(value, key) {
+	const text = typeof value === "string" ? value : typeof value === "number" && Number.isFinite(value) ? String(value) : null;
+	const match = text === null ? null : USD_PATTERN.exec(text);
+	if (match) {
+		const whole = Number(match[1]);
+		const fraction = Number((match[2] ?? ".").slice(1).padEnd(6, "0"));
+		const micros = whole * MICROS_PER_USD + fraction;
+		if (micros > 0 && micros <= MAX_USD_MICROS) return micros;
+	}
+	throw configError(`${key} must be a dollar amount above 0 and at most 1000000, with at most 6 decimals, written as a plain decimal (a string or a number)`);
+}
+
+/**
+ * The same parse, for a value that may be absent: `null` and `undefined` are `null` (no cap), anything else is
+ * `parseUsdMicros`. Absence is how every dollar setting is switched off; 0 is not (see above).
+ */
+export function optionalUsdMicros(value, key) {
+	return value === null || value === undefined ? null : parseUsdMicros(value, key);
+}
+
+/**
+ * Integer micro-dollars as a plain dollar decimal, at least two decimals and no trailing zeros past them:
+ * 2500000 is "2.50", 1 is "0.000001". For messages and displays; never parsed back by anything that enforces.
+ */
+export function formatMicros(micros) {
+	if (!Number.isSafeInteger(micros) || micros < 0) throw new TypeError("formatMicros: want a non-negative safe integer");
+	const whole = Math.floor(micros / MICROS_PER_USD);
+	const fraction = String(micros % MICROS_PER_USD).padStart(6, "0").replace(/0+$/, "").padEnd(2, "0");
+	return `${whole}.${fraction}`;
+}
+
+/**
+ * The cross-key rule (issue #501): a dollar window without `maxCostUsd` is invalid, because a window reserves
+ * each job's per-job cap before the container starts, and without a cap there is no amount to reserve.
+ *
+ * It runs on MERGED values, never per key: an env `PI_MAX_COST_USD` with an overlay `dailyCostUsd` is valid,
+ * and a per-key check of the overlay alone would refuse it. `settings` holds the four keys as they were set
+ * (any value but `null`/`undefined` counts as set). Returns `null`, or `{ invalid }` naming the first window
+ * that lacks a cap.
+ */
+export function checkDollarInvariant(settings) {
+	const set = (key) => settings?.[key] !== null && settings?.[key] !== undefined;
+	if (set("maxCostUsd")) return null;
+	const window = DOLLAR_WINDOW_KEYS.find(set);
+	return window === undefined ? null : { invalid: `${window} needs maxCostUsd: a dollar window reserves each job's per-job cost cap before it starts, so it cannot be set without one` };
+}
+
+/**
+ * The per-job cost cap a job runs under, in micro-dollars, or `null` for none (issue #501): the SMALLER of the
+ * trigger's `run.maxCostUsd` and the deployment's `maxCostUsd`, each counted only when set.
+ *
+ * A trigger can only NARROW. Where both are set the smaller wins, so a trigger can never lift a job above the
+ * deployment's cap (and a value above the env cap refuses the worker's load of the file too, `loadSchedules`). Where only the trigger sets one, it
+ * applies: a deployment that set no cap asked for none, and a trigger that asks for one is still a narrowing.
+ *
+ * The deployment value is validated before it gets here (config.mjs at boot, `validateOverlay` per job). The
+ * trigger value is validated by the loader in both services, so a malformed one reaches this only from a
+ * hand-built queue entry. That one does not throw (this runs at pickup, where a throw is a retry) and does not
+ * fall back to the deployment cap either, which would quietly drop a cap that was asked for: it reads as 0,
+ * the cap that refuses every priced call, and the run stops with `cost-cap`. `onMalformed(key)` is called
+ * when that happens, so the worker logs it rather than leaving a $0 cap unexplained.
+ */
+export function effectiveCostCapMicros(triggerValue, deploymentValue, onMalformed = () => {}) {
+	let trigger;
+	try {
+		trigger = optionalUsdMicros(triggerValue, "run.maxCostUsd");
+	} catch {
+		// Fail closed, and say so: `onMalformed` is told the KEY (never the value), so the caller can log it.
+		trigger = 0;
+		onMalformed("maxCostUsd");
+	}
+	const deployment = optionalUsdMicros(deploymentValue, "maxCostUsd");
+	if (trigger === null) return deployment;
+	if (deployment === null) return trigger;
+	return Math.min(trigger, deployment);
+}
+
+/**
+ * The first parsed trigger whose `run.maxCostUsd` is above the deployment's `maxCostUsd`, as its index in
+ * `triggers`, or -1 (issue #501). A trigger may only narrow the per-job cap, so a value above it can only be a
+ * mistake: the job would run under the deployment's cap anyway, while the file reads as allowing more. Pure,
+ * so `triggers.mjs` stays env-free and the worker's trigger load and doctor ask the same question. An unset
+ * deployment cap has nothing to be above.
+ */
+export function triggerCapAboveDeployment(triggers, deploymentValue) {
+	const deployment = optionalUsdMicros(deploymentValue, "maxCostUsd");
+	if (deployment === null) return -1;
+	return triggers.findIndex((t) => t?.run?.maxCostUsd !== undefined && t.run.maxCostUsd !== null && parseUsdMicros(t.run.maxCostUsd, "run.maxCostUsd") > deployment);
+}

package/src/octokit-log.mjs

@@ -0,0 +1,65 @@
+/**
+ * The `log` option every Octokit this project builds is given (issue #530), so no GitHub client writes a plain line
+ * into a process whose log stream is one JSON object per line.
+ *
+ * Octokit's own default logger is `console.warn` and `console.error`, and `@octokit/rest` carries the request-log
+ * plugin, which calls `log.error` with `GET /user - 401 with id ... in 12ms` for every failed request. A worker booted
+ * with `GITHUB_AUTH_SOURCE=pat` and a refused token printed exactly that beside its `github_auth_unavailable` line, and
+ * a pipeline that parses each line as JSON breaks on it.
+ *
+ * - `debug`, `info` and `error` are dropped. The request-log plugin is the only caller of `info` and `error`, and its
+ *   `error` is always followed by the rejection itself, which the caller already reports in its own words (the boot
+ *   line's `reason`, a job's refusal). Logging it twice would also put a request path into the stream.
+ * - `warn` is KEPT, as one JSON event: it is how `@octokit/request` says an endpoint is deprecated and how
+ *   `@octokit/auth-app` says it retried past clock skew, and neither has another surface. Dropping it would make an
+ *   endpoint that GitHub is about to remove fail with no warning at all.
+ *
+ * `log` is the caller's `(event, fields)` logger. Without one the warning still goes out as JSON, on stderr, where
+ * Octokit's own `console.warn` would have put it.
+ *
+ * An Octokit takes it TWICE, which is why the sites spread `octokitLogOptions` rather than pass `log` alone: the
+ * deprecation warning is written by `@octokit/request`'s fetch wrapper, which reads `request.log` and falls back to
+ * `console`, never the client's own `log` (measured on @octokit/request 10.0.11: with `log` alone the warning still
+ * reached stderr as a plain line).
+ */
+export function octokitLog(log = stderrJson) {
+	return {
+		debug() {},
+		info() {},
+		warn: (message) => log("github_client_warning", { message: String(message) }),
+		error() {},
+	};
+}
+
+/** The two places an Octokit reads its logger from, as constructor options to spread. */
+export function octokitLogOptions(log) {
+	const logger = octokitLog(log);
+	return { log: logger, request: { log: logger } };
+}
+
+/**
+ * What a failure log line may say about a GitHub answer: `{ status, requestId }` from the first Octokit `RequestError`
+ * on the error or its `cause` chain, else `{}` (issue #530's review). Dropping Octokit's own error line above also
+ * dropped `x-github-request-id`, which is what GitHub support asks for; this puts it back on OUR event.
+ *
+ * Only those two fields, never the headers object, the request or the response: a RequestError carries the request
+ * options and the response body, and only the `authorization` header is redacted there (measured on
+ * @octokit/request-error with this project's pins), not a token in a URL or body. A RequestError is recognised by its name, which
+ * `@octokit/request-error` sets to "HttpError", and an integer status; a gitlab, forgejo or azure error has neither, so
+ * it adds nothing. The id is GitHub's text, kept only in its own shape (hex, `:` and `.`), so the field can never carry
+ * anything else into the log.
+ */
+const REQUEST_ID_RE = /^[A-Za-z0-9:.]{1,100}$/;
+export function githubFailureFields(error) {
+	for (let e = error, depth = 0; e && depth < 5; e = e.cause, depth += 1) {
+		if (e.name === "HttpError" && Number.isInteger(e.status)) {
+			const id = e.response?.headers?.["x-github-request-id"];
+			return { status: e.status, ...(typeof id === "string" && REQUEST_ID_RE.test(id) ? { requestId: id } : {}) };
+		}
+	}
+	return {};
+}
+
+function stderrJson(event, fields) {
+	process.stderr.write(`${JSON.stringify({ event, ...fields })}\n`);
+}