@edgehero/pi-dispatch 2.1.0 → 3.1.0

package/src/runtime-settings.mjs

@@ -1,14 +1,19 @@
 import * as nodeFs from "node:fs";
 import { dirname } from "node:path";
 import { ensureUnderAccountRoot } from "./config.mjs";
+import { findDuplicateKey } from "./json-duplicates.mjs";
+import { checkDollarInvariant, parseUsdMicros } from "./money.mjs";
 
 /**
  * Runtime-settings overlay: the shared, durable truth between the admin extension and the worker
- * (INT-CONFIG-OVERLAY-CONTRACT, DES-RUNTIME-SETTINGS-FILE-OVERLAY). A flat `settings.json` with ten
+ * (INT-CONFIG-OVERLAY-CONTRACT, DES-RUNTIME-SETTINGS-FILE-OVERLAY). A flat `settings.json` with fourteen
  * optional keys -- `model`, `provider` (non-empty strings), `maxTurns`, `dailyCap`, `weeklyCap`,
  * `monthlyCap`, `maxTokens`, `dailyTokenCap` (int >= 1), `concurrency` (int 1-10), `softHoldPct`
- * (int 1-99) -- read by the worker at each job start and written atomically by the admin extension
- * (tmp + rename). `maxTokens`/`dailyTokenCap` are the optional token controls (issue #25).
+ * (int 1-99), and the dollar keys `maxCostUsd`, `dailyCostUsd`, `weeklyCostUsd`, `monthlyCostUsd`
+ * (a decimal string or number, `parseUsdMicros`) -- read by the worker at each job start and written
+ * atomically by the admin extension (tmp + rename). `maxTokens`/`dailyTokenCap` are the optional token
+ * controls (issue #25); the dollar keys are issue #501's (a window needs `maxCostUsd`, checked on the merged
+ * values by `resolveSettings`).
  *
  * `readOverlay` NEVER throws: a bad settings file returns a discriminated `{ invalid }` rather than an
  * exception, so the processor RETURNS a policy refusal (`settings-overlay-invalid`) instead of letting
@@ -25,7 +30,7 @@ import { ensureUnderAccountRoot } from "./config.mjs";
  * Custom: overlay validated inline per config.mjs precedent; zod not in deps
  */
 
-export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyCap", "monthlyCap", "maxTokens", "dailyTokenCap", "concurrency", "softHoldPct"];
+export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyCap", "monthlyCap", "maxTokens", "dailyTokenCap", "concurrency", "softHoldPct", "maxCostUsd", "dailyCostUsd", "weeklyCostUsd", "monthlyCostUsd"];
 
 /**
  * Overlay keys the OVERLAY accepts but no model-callable tool may set. `secretProfiles` maps a profile name
@@ -43,6 +48,39 @@ export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyC
  */
 export const OPERATOR_ONLY_KEYS = ["secretProfiles"];
 
+// The dollar keys' near-miss spellings (issue #501), already normalised (`overlayKeyShape`), each mapped to the key it
+// meant: the four keys, their env names (`PI_MAX_COST_USD` pasted into settings.json is the likeliest slip of all),
+// the micro-dollar spelling, `costUsd`, and the bare `maxCost` forms.
+const DOLLAR_NEAR_MISSES = Object.freeze({
+	maxcostusd: "maxCostUsd", pimaxcostusd: "maxCostUsd", maxcostmicros: "maxCostUsd", costusd: "maxCostUsd", maxcost: "maxCostUsd",
+	dailycostusd: "dailyCostUsd", pidailycostusd: "dailyCostUsd", dailycostmicros: "dailyCostUsd", dailycost: "dailyCostUsd",
+	weeklycostusd: "weeklyCostUsd", piweeklycostusd: "weeklyCostUsd", weeklycostmicros: "weeklyCostUsd", weeklycost: "weeklyCostUsd",
+	monthlycostusd: "monthlyCostUsd", pimonthlycostusd: "monthlyCostUsd", monthlycostmicros: "monthlyCostUsd", monthlycost: "monthlyCostUsd",
+});
+
+// A small FIXED look-alike table, to ASCII: Cyrillic а е о р с у х к м т н в і and Greek ο α ε ρ ν τ κ ι (lowercase
+// forms; the key is lowercased first, which maps their capitals onto these). Fullwidth forms are mapped by code point.
+const LOOK_ALIKES = new Map(Object.entries({
+	"\u0430": "a", "\u0435": "e", "\u043E": "o", "\u0440": "p", "\u0441": "c", "\u0443": "y", "\u0445": "x", "\u043A": "k", "\u043C": "m", "\u0442": "t", "\u043D": "h", "\u0432": "b", "\u0456": "i",
+	"\u03BF": "o", "\u03B1": "a", "\u03B5": "e", "\u03C1": "p", "\u03BD": "v", "\u03C4": "t", "\u03BA": "k", "\u03B9": "i",
+}));
+
+/**
+ * An overlay key's shape for the dollar near-miss check (issue #501): fullwidth forms to ASCII, lowercased, the fixed
+ * look-alike table applied, and the separators `_`, `-`, `.` and space dropped. Nothing else is removed, so a key with
+ * any other character (`host_ü`, `notés`) keeps it and can never EQUAL a target. That is the whole rule: the overlay
+ * refuses only an exact match after this, never a subsequence or a distance, because a refusal here stops every job
+ * and a false one is worse than a drop. The trigger loader keeps its own, wider sweep (`validateRunModel`): a
+ * triggers file is reviewed content refused at load, where a false hit costs an edit, not a day of jobs.
+ */
+function overlayKeyShape(key) {
+	let out = "";
+	for (const ch of key.replace(/[\uFF01-\uFF5E]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 0xfee0)).toLowerCase()) {
+		out += LOOK_ALIKES.get(ch) ?? ch;
+	}
+	return out.replace(/[_\-. ]/g, "");
+}
+
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.trim() !== "";
 }
@@ -127,14 +165,38 @@ function validateOverlay(candidate, log) {
 				overlay[key] = { ...value };
 				break;
 			}
+			case "maxCostUsd":
+			case "dailyCostUsd":
+			case "weeklyCostUsd":
+			case "monthlyCostUsd":
+				// Issue #501: the per-job dollar cap and the three dollar windows. Kept AS WRITTEN (a string or a number)
+				// once it parses, so the file the admin writes back holds what the operator typed, never a converted
+				// number; the worker converts it to micro-dollars per job, exactly as it converts env's. A window needs
+				// `maxCostUsd`, a cross-key rule this per-key check cannot see: `resolveSettings` applies it to the
+				// merged values.
+				try {
+					parseUsdMicros(value, key);
+				} catch (error) {
+					return { invalid: error.message };
+				}
+				overlay[key] = value;
+				break;
 			case "softHoldPct":
 				// A percentage of each active cap; 100 would equal the hard wall (no band) and 0 has no meaning,
 				// so the enforced band is 1-99. Absence disables the soft-hold entirely.
 				if (!isIntInRange(value, 1, 99)) return { invalid: "softHoldPct must be an integer 1-99" };
 				overlay[key] = value;
 				break;
-			default:
+			default: {
+				// Issue #501: a near miss of a DOLLAR key is refused when its shape (`overlayKeyShape`: case, the
+				// separators, a fixed look-alike table) EXACTLY equals a known misspelling: `maxcostusd`, `MaxCostUsd`,
+				// `max_cost_usd`, `max<U+0421>ostUsd`, `PI_MAX_COST_USD`, `maxCostMicros`, `costUsd`. Dropped and logged,
+				// the operator's cap would not apply while the file reads as setting one. Every other unknown key keeps
+				// the forward-compatible drop-and-log, `host_<U+00FC>` and `maxCostCents` included.
+				const meant = Object.hasOwn(DOLLAR_NEAR_MISSES, overlayKeyShape(key)) ? DOLLAR_NEAR_MISSES[overlayKeyShape(key)] : undefined;
+				if (meant !== undefined) return { invalid: `${key} is not a settings key -- did you mean ${meant}? A dollar cap the worker drops would not apply while the file reads as set` };
 				log("settings_overlay_unknown_key", { key });
+			}
 		}
 	}
 	return { overlay };
@@ -163,15 +225,20 @@ export function readOverlay(path, { fs = nodeFs, log = () => {} } = {}) {
 	} catch {
 		return { invalid: "settings file is not valid JSON" };
 	}
+	// Issue #501: a duplicate key is refused, the triggers file's rule. JSON.parse keeps the LAST value, so
+	// `{"maxCostUsd":"1","maxCostUsd":"999"}` would run under $999 while the first line reads as $1. Only the KEY
+	// is named, never a value. `writeOverlay` serialises an object, so a file it wrote never has one.
+	const duplicate = findDuplicateKey(text);
+	if (duplicate) return { invalid: `settings file has a duplicate key ${JSON.stringify(duplicate.key)}: JSON keeps the last value, so the file that reads and the file that runs differ` };
 	return validateOverlay(parsed, log);
 }
 
 /**
- * Resolve the ten effective settings from `config` and a validated `overlay`: overlay value where the
+ * Resolve the fourteen effective settings from `config` and a validated `overlay`: overlay value where the
  * overlay sets it, else the config value. Precedence is overlay > env > default only -- `config`
- * already carries env > default. `weeklyCap`/`monthlyCap`/`maxTokens`/`dailyTokenCap`/`softHoldPct` may
- * resolve to `null` (their config value when unset), meaning that window / cap / band is disabled.
- * `job.data` is NOT merged here; that layer is the processor's.
+ * already carries env > default. `weeklyCap`/`monthlyCap`/`maxTokens`/`dailyTokenCap`/`softHoldPct` and the
+ * four dollar keys may resolve to `null` (their config value when unset), meaning that window / cap / band is
+ * disabled. `job.data` is NOT merged here; that layer is the processor's.
  */
 export function effectiveSettings(config, overlay) {
 	const o = overlay ?? {};
@@ -186,9 +253,37 @@ export function effectiveSettings(config, overlay) {
 		dailyTokenCap: o.dailyTokenCap ?? config.dailyTokenCap,
 		concurrency: o.concurrency ?? config.concurrency,
 		softHoldPct: o.softHoldPct ?? config.softHoldPct,
+		maxCostUsd: o.maxCostUsd ?? config.maxCostUsd,
+		dailyCostUsd: o.dailyCostUsd ?? config.dailyCostUsd,
+		weeklyCostUsd: o.weeklyCostUsd ?? config.weeklyCostUsd,
+		monthlyCostUsd: o.monthlyCostUsd ?? config.monthlyCostUsd,
 	};
 }
 
+/**
+ * The per-job settings the worker runs with, from `config` and a `readOverlay` result: `{ invalid }` when the
+ * overlay is invalid or the MERGED values break a cross-key rule, else the effective settings plus
+ * `secretProfiles`. Pure, so the processor's one settings read (start.mjs `getSettings`) is testable without
+ * booting a worker.
+ *
+ * The dollar invariant (issue #501) runs HERE, on merged values, because `validateOverlay` sees one key at a
+ * time and the overlay alone: a window in the overlay with the per-job cap in env is valid, and a check of
+ * the overlay alone would refuse it. An invalid result becomes the `settings-overlay-invalid` refusal, before
+ * any spend.
+ *
+ * `secretProfiles` (REQ-TRIGGER-SECRETS) rides ALONGSIDE the effective keys rather than inside them:
+ * `effectiveSettings` resolves `overlay > env` over a fixed literal whose tests pin its key set, and this key
+ * deliberately has no such precedence (a name declared in both sources is refused per delivery, not silently
+ * won by either).
+ */
+export function resolveSettings(config, read) {
+	if (read.invalid) return { invalid: read.invalid };
+	const settings = effectiveSettings(config, read.overlay);
+	const broken = checkDollarInvariant(settings);
+	if (broken) return broken;
+	return { ...settings, secretProfiles: read.overlay?.secretProfiles ?? {} };
+}
+
 /**
  * Write `candidate` to `path` atomically. Validates with the same rules as `readOverlay` (an invalid
  * candidate returns `{ invalid }` and touches no file; an empty `{}` candidate is valid), serialises

package/src/schedules.mjs

@@ -15,6 +15,7 @@
 import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { configError } from "./config.mjs";
+import { triggerCapAboveDeployment } from "./money.mjs";
 import { parseTriggers } from "./triggers.mjs";
 
 /**
@@ -32,6 +33,16 @@ export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSyn
 	}
 
 	const triggers = parseTriggers(readFileSync(path, "utf8"), path);
+	// Issue #501: a trigger's run.maxCostUsd above this deployment's PI_MAX_COST_USD refuses the file, at boot
+	// (an operator is present) and on a live reload (the running schedules are kept). Every kind is checked,
+	// not only cron: the worker runs the forge jobs too, and this is the one load it does of the file. Here and
+	// not in parseTriggers, which is pure and shared with the receiver, which never sees the worker's env. The
+	// job itself runs under the smaller of the two whatever this finds (effectiveJobOf), so this is the loud
+	// half, never the only one. Env only: an overlay cap can change between jobs and is applied per job.
+	const above = triggerCapAboveDeployment(triggers, config.maxCostUsd);
+	if (above !== -1) {
+		throw configError(`trigger at index ${above}: run.maxCostUsd is above this deployment's PI_MAX_COST_USD. A trigger can only narrow the per-job cost cap, so lower it or remove it (${path})`);
+	}
 
 	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync, fleet));
 }
@@ -64,6 +75,23 @@ export function authoredCron(config, { readFileSync = fsReadFileSync, existsSync
 	}
 }
 
+/**
+ * The host paths a job container can see (issue #504 part B), for `envelopeInsideJobPaths`: every cron trigger's
+ * `run.folder` and every trigger's `run.skillsDir` in the triggers file, the `PI_DISPATCH_RUN_ROOTS` roots and
+ * `PI_GLOBAL_PI_DIR`. Read from the FILE, not from this host's served schedules: a folder another host serves today may
+ * be this host's after an edit, and the check costs nothing to be wide. Throws when the triggers file does not parse.
+ */
+export function envelopeJobPaths(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const out = { cronFolders: [], runRoots: [...(config.dispatchRunRoots ?? [])], skillsDirs: [], globalPiDir: config.globalPiDir ?? null };
+	const path = config.triggersFile;
+	if (path === null || path === undefined || !existsSync(path)) return out;
+	for (const t of parseTriggers(readFileSync(path, "utf8"), path)) {
+		if (t?.on?.type === "cron" && typeof t.run?.folder === "string") out.cronFolders.push(t.run.folder);
+		if (typeof t?.run?.skillsDir === "string") out.skillsDirs.push(t.run.skillsDir);
+	}
+	return out;
+}
+
 /**
  * Split a schedule set into the triggers THIS host serves and the ones it does not (issue #57).
  *
@@ -150,7 +178,11 @@ function normalizeCronSchedule({ on, run }, path, existsSync, fleet) {
 	// key. A command trigger carries no flow/task at all (the validator enforces the XOR), so those two
 	// keys hold undefined here and drop at JSON serialization -- the command schedule's data is exactly
 	// kind/folder/command plus the shared fields.
-	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.backend !== undefined && { backend: run.backend }), ...(run.excludeTools !== undefined && { excludeTools: run.excludeTools }), ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), ...(run.secrets !== undefined && { secrets: run.secrets }), ...(run.secretsProfile !== undefined && { secretsProfile: run.secretsProfile }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
+	//
+	// `portfolio` (issue #505) is conditional like `command`, so an unflagged schedule grows no key, and it rides at JOB
+	// level, never inside `trigger`: `trigger` is copied verbatim into `/job/event.json`, and whether a job may send a
+	// budget plan is the worker's decision to re-check against the live file, not a fact for the agent to read.
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.backend !== undefined && { backend: run.backend }), ...(run.excludeTools !== undefined && { excludeTools: run.excludeTools }), ...(run.models !== undefined && { models: run.models }), ...(run.maxCostUsd !== undefined && { maxCostUsd: run.maxCostUsd }), ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), ...(run.secrets !== undefined && { secrets: run.secrets }), ...(run.secretsProfile !== undefined && { secretsProfile: run.secretsProfile }), resume: run.resume, ...(run.portfolio !== undefined && { portfolio: run.portfolio }), trigger: { id: on.id, pattern: on.pattern } };
 	// Retention only; the deterministic repeat:<id>:<millis> jobId supplies dedup, so no jobId here, and
 	// scheduler jobs are not retried (DES-CRON-VIA-BULLMQ-SCHEDULER) so no attempts/backoff.
 	const opts = { removeOnComplete: { age: 24 * 3600 }, removeOnFail: { age: 7 * 24 * 3600 } };