@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/subscription-status.mjs

@@ -0,0 +1,42 @@
+import { SUBSCRIPTION_CONNECTION_LIMIT, SUBSCRIPTION_QUOTA_BYTES } from "./subscription-limits.mjs";
+
+// One maximum quota record per connection plus its bounded safe projection fields.
+export const SUBSCRIPTION_STATUS_BYTES = SUBSCRIPTION_CONNECTION_LIMIT * (SUBSCRIPTION_QUOTA_BYTES + 16_384);
+export const subscriptionStatusKey = (host) => `dispatch:subscription-status:${host}`;
+const SAFE_HOST = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A bounded, ephemeral projection. Credential data and binding digests never enter this keyspace. */
+export async function publishSubscriptionStatus(redis, host, runtime) {
+	if (!SAFE_HOST.test(host)) throw new Error("invalid subscription owner host");
+	const status = await runtime.status();
+	const connections = status.connections.map(({ accountGroup, generation, quota, ...row }) => ({ ...row, ...(quota ? { quota: Object.fromEntries(Object.entries(quota).filter(([key]) => !["accountDigest", "generation", "bucket"].includes(key))) } : {}) }));
+	const payload = JSON.stringify({ ...status, connections });
+	if (connections.length > SUBSCRIPTION_CONNECTION_LIMIT || Buffer.byteLength(payload) > SUBSCRIPTION_STATUS_BYTES) throw new Error("subscription status exceeds its bounds");
+	await redis.set(subscriptionStatusKey(host), payload, "PX", 90_000);
+}
+export async function readSubscriptionStatus(redis, hosts, { timeoutMs = 2500 } = {}) {
+	const requested = [...new Set(hosts)].filter((host) => SAFE_HOST.test(host));
+	const names = requested.slice(0, 64);
+	let timer;
+	let results;
+	try { results = await Promise.race([Promise.all(names.map((name) => redis.get(subscriptionStatusKey(name)))), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("subscription status unavailable")), timeoutMs); timer.unref?.(); })]); }
+	finally { clearTimeout(timer); }
+	let partial = requested.length > names.length || names.length === 0 || results.some((raw) => raw === null);
+	const connections = new Map();
+	for (const [index, raw] of results.entries()) {
+		if (raw === null) continue;
+		try {
+			if (Buffer.byteLength(raw) > SUBSCRIPTION_STATUS_BYTES) throw new Error("oversized status");
+			const value = JSON.parse(raw);
+			if (value.state !== "ready" || !Array.isArray(value.connections) || value.connections.length > SUBSCRIPTION_CONNECTION_LIMIT) throw new Error("invalid status");
+			if (value.partial !== false) partial = true;
+			for (const row of value.connections) {
+				if (!row || !SAFE_HOST.test(row.ownerHost) || !SAFE_HOST.test(row.id)) { partial = true; continue; }
+				const key = `${row.ownerHost}:${row.id}`;
+				const owner = row.ownerHost === names[index];
+				if (owner || !connections.has(key)) connections.set(key, { owner, row: owner ? row : { ...row, state: "other-host" } });
+			}
+		} catch { partial = true; }
+	}
+	if ([...connections.values()].some((value) => !value.owner)) partial = true;
+	return { state: partial ? "partial" : "ready", partial, connections: [...connections.values()].map((value) => value.row) };
+}

package/src/subscription-wait.mjs

@@ -0,0 +1,11 @@
+/** Host-only control flow for a determinate, free subscription admission delay. Never queued authority. */
+export class SubscriptionWait extends Error {
+	constructor({ wait, until }) {
+		if (!["subscription-auth", "subscription-quota", "subscription-owner"].includes(wait) || !Number.isSafeInteger(until) || until < 0 || until > 253_402_300_799_999) throw new TypeError("invalid subscription admission wait");
+		super("subscription admission must wait");
+		this.name = "SubscriptionWait";
+		this.wait = wait;
+		this.until = until;
+		this.budgetReserved = false;
+	}
+}

package/src/subscriptions.mjs

@@ -92,7 +92,13 @@ export function parseSubscriptions(text, path) {
 		throw configError(`subscriptions file must declare an integer "version" >= 1 (got ${JSON.stringify(version)}): ${path}`);
 	}
 	if (version > SUBSCRIPTIONS_VERSION) {
-		throw configError(`subscriptions file written by a newer pi-dispatch (version ${version}; this build understands ${SUBSCRIPTIONS_VERSION}): ${path}`);
+		// Marked `newer`, as `parseTriggersDocument` marks its own (issue #761), so the admin's writer refuses this
+		// file for the reason the views give by this flag alone: a reading of `version` of its own can disagree at an
+		// edge such as 1e300 (`Number.isSafeInteger` against the `Number.isInteger` above), and a match on these words
+		// would break the day they are reworded.
+		const error = configError(`subscriptions file written by a newer pi-dispatch (version ${version}; this build understands ${SUBSCRIPTIONS_VERSION}): ${path}`);
+		error.newer = true;
+		throw error;
 	}
 
 	const entries = parsed.subscriptions;

package/src/thinking-level.mjs

@@ -0,0 +1,19 @@
+import { clampThinkingLevel } from "@earendil-works/pi-ai/models";
+import { modelEntryOf } from "./model-endpoints.mjs";
+import { FORK_THINKING_LEVELS } from "./fork-job.mjs";
+
+/** The pinned provider composer's two reasoning fields, including its per-level override merge. */
+export function thinkingModel({ models, provider, modelId, builtinModel = () => null }) {
+	const { defined, override } = modelEntryOf(models, provider, modelId);
+	const base = defined ? { reasoning: defined.reasoning ?? false, thinkingLevelMap: defined.thinkingLevelMap } : builtinModel(provider, modelId);
+	if (!base) return null;
+	return {
+		reasoning: override?.reasoning ?? base.reasoning,
+		thinkingLevelMap: override?.thinkingLevelMap ? { ...base.thinkingLevelMap, ...override.thinkingLevelMap } : base.thinkingLevelMap,
+	};
+}
+export function thinkingLevelAllowed(job, { models, builtinModel } = {}) {
+	if (!FORK_THINKING_LEVELS.includes(job.thinkingLevel)) return false;
+	const model = thinkingModel({ models, provider: job.provider, modelId: job.model, builtinModel });
+	return model !== null && clampThinkingLevel(model, job.thinkingLevel) === job.thinkingLevel;
+}

package/src/touch-outbox.mjs

@@ -0,0 +1,61 @@
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { cleanTouch } from "./touch-state.mjs";
+
+/**
+ * An applied action must never be repeated merely because its metric did not publish. The durable intent is written
+ * before acting, marked applied before publication, and only applied entries are replayed. An interrupted pending
+ * entry is unknown until its owner supplies proof; it cannot be guessed successful from an audit row.
+ */
+export function makeTouchOutbox({ dir, store, fs = nodeFs, log = () => {} } = {}) {
+	const path = (id) => join(dir, `${id}.json`);
+	function save(event, state) {
+		if (!dir) return false;
+		try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); fs.writeFileSync(`${path(event.id)}.tmp`, JSON.stringify({ state, event }), { mode: 0o600 }); fs.renameSync(`${path(event.id)}.tmp`, path(event.id)); return true; } catch { log("touch_outbox_unavailable", {}); return false; }
+	}
+	function drop(event) { try { fs.unlinkSync(path(event.id)); } catch {} }
+	return {
+		async begin(value) {
+			const event = cleanTouch(value);
+			if (!event) return { error: "touch-event-invalid" };
+			const durable = save(event, "pending");
+			const indexed = await store.begin(event);
+			return { event, durable, ...(indexed.ok ? { ok: true } : { error: indexed.error }) };
+		},
+		async applied(intent) {
+			if (!intent?.event) return { error: "touch-event-invalid" };
+			const durable = save(intent.event, "applied");
+			const result = await store.write(intent.event);
+			if (result.ok) drop(intent.event);
+			if (!result.ok) log("touch_record_pending", {});
+			return result.ok ? result : { error: result.error, durable };
+		},
+		async abort(intent) { if (!intent?.event) return; await store.abort(intent.event); drop(intent.event); },
+		async repair() {
+			const result = { repaired: 0, pending: 0, invalid: 0 };
+			let names; try { names = fs.readdirSync(dir); } catch { return result; }
+			for (const name of names) {
+				if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+				let row; try { const stat = fs.lstatSync(join(dir, name)); if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) throw new Error(); row = JSON.parse(fs.readFileSync(join(dir, name), "utf8")); } catch { result.invalid++; continue; }
+				const event = cleanTouch(row.event);
+				if (!event || `${event.id}.json` !== name) { result.invalid++; continue; }
+				if (row.state !== "applied") { result.pending++; await store.begin(event); continue; }
+				const sent = await store.write(event);
+				if (sent.ok) { drop(event); result.repaired++; }
+			}
+			return result;
+		},
+	};
+}
+
+/** The action runs exactly once. A metric failure is an explicit warning, never a reason to retry its side effect. */
+export async function trackTouchAction({ store, outbox = null, event, act, succeeded = (result) => result?.ok === true }) {
+	if (!store && !outbox) return act();
+	const writer = outbox ?? { begin: (e) => store.begin(e), applied: (intent) => store.write(intent.event), abort: (intent) => store.abort(intent.event) };
+	const intent = await writer.begin(event);
+	let result;
+	try { result = await act(); } catch (error) { await writer.abort(intent); throw error; }
+	if (!succeeded(result)) { await writer.abort(intent); return result; }
+	const tracked = await writer.applied(intent);
+	return tracked?.ok ? result : { ...result, touchWarning: "touch-tracking-incomplete" };
+}

package/src/touch-state.mjs

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { normalize } from "node:path";
+
+/** Closed intervention and terminal-wait facts. Text belongs to the run's private transcript, never this index. */
+export const TOUCH_CAUSES = Object.freeze(["question-answer", "approval-decision", "rerun", "config-fix", "steer", "cancel"]);
+export const WAIT_END_REASONS = Object.freeze(["approval-expired", "approval-policy-changed"]);
+export const TOUCH_INDEX = "touch:index";
+export const TOUCH_META = "touch:meta";
+export const TOUCH_PENDING = "touch:pending";
+export const TOUCH_MAX_EVENTS = 30_000;
+export const TOUCH_MAX_RETENTION_DAYS = 365;
+const ID = /^[A-Za-z0-9._:-]{1,200}$/;
+const HASH = /^[a-f0-9]{64}$/;
+const PROJECT = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const TARGET = /^[A-Za-z0-9._:/#! -]{1,300}$/;
+const ms = (v) => Number.isSafeInteger(v) && v >= 0;
+const digest = (v) => createHash("sha256").update(v).digest("hex");
+export const touchEventKey = (id) => `touch:event:${id}`;
+export const touchTtlMs = (retentionDays = 30) => (Number(retentionDays) > 0 ? Math.min(Number(retentionDays), TOUCH_MAX_RETENTION_DAYS) : TOUCH_MAX_RETENTION_DAYS) * 86400_000;
+
+/** An opaque host-authored identity keeps local folders with the same basename apart without recording a path. */
+export function touchScopeOf(job, host = null) {
+	const data = job?.data ?? job ?? {};
+	if (HASH.test(data.touchScopeId ?? "")) return data.touchScopeId;
+	if (data.kind === "local" || data.folder) return digest(`local\0${host ?? ""}\0${typeof data.folder === "string" ? normalize(data.folder) : ""}`);
+	return digest(`${data.kind ?? "unknown"}\0${data.baseUrl ?? data.host ?? ""}\0${data.repo ?? data.repository ?? ""}`);
+}
+
+/** Rebuild, never spread: even an invalid optional field refuses the event rather than carrying arbitrary text. */
+export function cleanTouch(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || !ID.test(value.runId ?? "") || !ms(value.at)) return null;
+	if (value.type !== undefined && !["stop", "touch", "wait-end"].includes(value.type)) return null;
+	if (value.type === "wait-end" ? value.cause !== undefined || !WAIT_END_REASONS.includes(value.reason) : value.type !== "stop" && !TOUCH_CAUSES.includes(value.cause)) return null;
+	if (value.answerSource !== undefined && !["forge", "console", "panel", "draft"].includes(value.answerSource)) return null;
+	if (value.draftRunId !== undefined && !ID.test(value.draftRunId)) return null;
+	if (value.scopeId !== undefined && value.scopeId !== null && !HASH.test(value.scopeId)) return null;
+	if (value.project !== undefined && value.project !== null && !PROJECT.test(value.project)) return null;
+	if (value.target !== undefined && value.target !== null && !TARGET.test(value.target)) return null;
+	for (const key of ["endedAt", "parkedAt", "receivedAt"]) if (value[key] !== undefined && value[key] !== null && !ms(value[key])) return null;
+	const type = value.type === "stop" ? "stop" : value.type === "wait-end" ? "wait-end" : "touch";
+	const id = HASH.test(value.id ?? "") ? value.id : digest(`${type}\0${value.runId}\0${value.cause ?? value.reason ?? ""}\0${value.nonce ?? value.at}`);
+	return { v: 1, id, type, runId: value.runId, ...(type === "touch" ? { cause: value.cause } : {}), ...(type === "wait-end" ? { reason: value.reason } : {}), at: value.at,
+		...(value.scopeId ? { scopeId: value.scopeId } : {}), ...(value.project ? { project: value.project } : {}),
+		...(value.target ? { target: value.target } : {}), ...(value.answerSource ? { answerSource: value.answerSource } : {}), ...(value.draftRunId ? { draftRunId: value.draftRunId } : {}), ...Object.fromEntries(["endedAt", "parkedAt", "receivedAt"].filter((k) => ms(value[k])).map((k) => [k, value[k]])) };
+}
+
+const INIT = `
+if redis.call("EXISTS", KEYS[1]) == 0 then redis.call("HSET", KEYS[1], "since", ARGV[1]) end
+redis.call("PEXPIRE", KEYS[1], ARGV[2])
+return 1
+`;
+const WRITE = `
+if redis.call("EXISTS", KEYS[2]) == 0 or (redis.call("EXISTS", KEYS[1]) == 0 and redis.call("HGET", KEYS[2], "indexed") == "1") then
+ redis.call("DEL", KEYS[2]); redis.call("HSET", KEYS[2], "since", ARGV[1])
+end
+local added = redis.call("SET", KEYS[3], ARGV[4], "NX", "PX", ARGV[3])
+redis.call("ZADD", KEYS[1], ARGV[2], ARGV[5])
+redis.call("HSET", KEYS[2], "indexed", "1")
+local aged = redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", "(" .. ARGV[6])
+if aged > 0 then local prior = tonumber(redis.call("HGET", KEYS[2], "horizon") or "0"); redis.call("HSET", KEYS[2], "horizon", math.max(prior, tonumber(ARGV[6]))) end
+local n = redis.call("ZCARD", KEYS[1])
+if n > tonumber(ARGV[7]) then
+ local removed = redis.call("ZRANGE", KEYS[1], 0, n-tonumber(ARGV[7])-1, "WITHSCORES")
+ if #removed > 0 then local prior = tonumber(redis.call("HGET", KEYS[2], "horizon") or "0"); redis.call("HSET", KEYS[2], "horizon", math.max(prior, tonumber(removed[#removed]))) end
+ redis.call("ZREMRANGEBYRANK", KEYS[1], 0, n-tonumber(ARGV[7])-1)
+end
+redis.call("PEXPIRE", KEYS[1], ARGV[3]); redis.call("PEXPIRE", KEYS[2], ARGV[3])
+redis.call("HDEL", KEYS[4], ARGV[5])
+return added and 1 or 0
+`;
+const READ = `return {redis.call("HGETALL", KEYS[1]), redis.call("ZRANGE", KEYS[2], 0, -1), redis.call("HLEN", KEYS[3]), redis.call("EXISTS", KEYS[2])}`;
+export const TOUCH_SCRIPTS = Object.freeze({ INIT, WRITE, READ });
+
+function bounded(task, timeoutMs) {
+	let timer;
+	return Promise.race([Promise.resolve().then(task), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("touch-timeout")), timeoutMs); })]).finally(() => clearTimeout(timer));
+}
+
+/** Shared by every producer. Unknown or unavailable tracking is a named state; it never becomes zero touches. */
+export function makeTouchStore({ redis, now = Date.now, retentionDays = 30, timeoutMs = 2000, prefix = "" } = {}) {
+	const ttl = touchTtlMs(retentionDays);
+	const key = (name) => `${prefix}${name}`;
+	return {
+		async initialize() {
+			try { await bounded(() => redis.eval(INIT, 1, key(TOUCH_META), now(), ttl), timeoutMs); return { ok: true }; } catch { return { error: "touch-index-unavailable" }; }
+		},
+		async begin(value) {
+			const event = cleanTouch(value);
+			if (!event) return { error: "touch-event-invalid" };
+			try { await bounded(() => redis.hset(key(TOUCH_PENDING), event.id, event.at), timeoutMs); await bounded(() => redis.pexpire(key(TOUCH_PENDING), ttl), timeoutMs); return { ok: true, event }; } catch { return { error: "touch-index-unavailable", event }; }
+		},
+		async abort(value) {
+			const event = cleanTouch(value);
+			if (!event) return { error: "touch-event-invalid" };
+			try { await bounded(() => redis.hdel(key(TOUCH_PENDING), event.id), timeoutMs); return { ok: true }; } catch { return { error: "touch-index-unavailable" }; }
+		},
+		async write(value) {
+			const event = cleanTouch(value);
+			if (!event) return { error: "touch-event-invalid" };
+			try {
+				const added = await bounded(() => redis.eval(WRITE, 4, key(TOUCH_INDEX), key(TOUCH_META), key(touchEventKey(event.id)), key(TOUCH_PENDING), now(), event.at, ttl, JSON.stringify(event), event.id, now() - ttl, TOUCH_MAX_EVENTS), timeoutMs);
+				return { ok: true, added: added === 1, event };
+			} catch { return { error: "touch-index-unavailable" }; }
+		},
+		async read() {
+			try {
+				const raw = await bounded(() => redis.eval(READ, 3, key(TOUCH_META), key(TOUCH_INDEX), key(TOUCH_PENDING)), timeoutMs);
+				if (!Array.isArray(raw) || !Array.isArray(raw[0]) || !Array.isArray(raw[1])) return { events: [], coverage: { fromMs: now(), partial: true, reasons: ["touch-index-unavailable"] } };
+				const meta = Object.fromEntries(raw[0].reduce((xs, x, i, all) => i % 2 === 0 ? [...xs, [x, all[i + 1]]] : xs, []));
+				const since = Number(meta.since);
+				const reasons = [];
+				if (!ms(since)) reasons.push("touch-tracking-not-started");
+				// A surviving epoch cannot vouch for an index that was lost. Diagnose it at READ time, before
+				// the next touch repairs the epoch; otherwise an idle fleet falsely reads the missing events as zero.
+				const indexMissing = meta.indexed === "1" && Number(raw[3]) !== 1;
+				if (indexMissing) reasons.push("touch-index-lost");
+				const unresolved = Number(raw[2]) > 0;
+				if (unresolved) reasons.push("touch-actions-unresolved");
+				const events = [];
+				let missingAt = 0;
+				for (let offset = 0; offset < raw[1].length; offset += 500) {
+					const rows = await bounded(() => redis.mget(...raw[1].slice(offset, offset + 500).map((id) => key(touchEventKey(id)))), timeoutMs);
+					for (const body of rows) {
+						let event; try { event = cleanTouch(JSON.parse(body)); } catch {}
+						if (event) events.push(event); else missingAt = now();
+					}
+				}
+				if (missingAt) reasons.push("touch-events-missing");
+				return { events, coverage: { fromMs: Math.max(ms(since) ? since : now(), Number(meta.horizon) || 0, now() - ttl, missingAt, indexMissing || unresolved ? now() : 0), partial: reasons.length > 0, reasons } };
+			} catch { return { events: [], coverage: { fromMs: now(), partial: true, reasons: ["touch-index-unavailable"] } }; }
+		},
+	};
+}