@edgehero/pi-dispatch 0.1.0

package/src/prepare-local.mjs

@@ -0,0 +1,76 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { materializePiDir } from "./materialize.mjs";
+
+const exec = promisify(execFile);
+
+/**
+ * Prepare a LOCAL-FOLDER job. This is the zero-GitHub path: no token, no clone, no PR. The folder
+ * on the operator's own machine becomes /workspace (bind-mounted read-write), edited in place.
+ *
+ * For v1 the folder must be a git repository, which buys two things for free: a stable ref (HEAD)
+ * to read instructions from, and git's object model, so `.pi/` materialises through the same
+ * symlink/submodule-safe path as GitHub jobs (materializePiDir). Instructions come from HEAD
+ * (committed, reviewed); work happens on the working tree in /workspace. A non-git folder is a
+ * documented v1 limitation -- `git init` it first.
+ *
+ * The task text is DATA (CONST-ISSUE-TEXT-IS-DATA): it goes into /job/prompt.md, never the
+ * instructions. The operator supplies it via the CLI (`pi-dispatch run --task`).
+ *
+ * `event` is the trigger context the dispatcher derived (cron/manual/chain); it lands in
+ * /job/event.json (INT-CONTAINER-JOB-INPUTS) -- one file per concern, alongside prompt.md. The
+ * default keeps a directly-constructed call (tests, older wiring) honest: a job with no derived
+ * context is a manual run.
+ */
+export async function prepareLocalWorkspace({ folder, task, jobDir, git = defaultGit, event = { source: "manual" } }) {
+	if (!existsSync(folder)) {
+		const error = new Error(`local folder does not exist: ${folder}`);
+		error.piDispatchConfig = true;
+		throw error;
+	}
+	if (!existsSync(join(folder, ".git"))) {
+		const error = new Error(`local folder is not a git repository (v1 requires one): ${folder}`);
+		error.piDispatchConfig = true;
+		throw error;
+	}
+
+	const sha = (await git(folder, ["rev-parse", "HEAD"])).trim();
+
+	mkdirSync(jobDir, { recursive: true });
+	// The outbox is the container's only signal channel back to the worker (INT-OUTBOX-CONTRACT). It is
+	// mounted /outbox:rw for local jobs only; the host reads it after the run to enqueue chained children.
+	const outboxDir = join(jobDir, "outbox");
+	mkdirSync(outboxDir, { recursive: true });
+	// Instructions from HEAD, via the symlink-safe git materialiser, into /job/pi (mounted :ro).
+	const written = await materializePiDir({ gitDir: folder, sha, destDir: jobDir });
+
+	// The task the operator asked for. Plain data below the instructions.
+	writeFileSync(join(jobDir, "prompt.md"), String(task ?? ""), { mode: 0o444 });
+
+	// The trigger context, /job/event.json (INT-CONTAINER-JOB-INPUTS): one file per concern, 0o444 like
+	// the prompt, written unconditionally so every local run carries its origin. `folder` is the BASENAME
+	// only -- the full path embeds the operator's OS account name and /job is agent-readable, the same
+	// PII restraint run-history's `local:<basename>` target applies. The cron-only keys (trigger,
+	// scheduledFor, previousRunAt) appear only for a cron source, nulls preserved.
+	const eventBody = {
+		source: event.source,
+		...(event.trigger ? { trigger: event.trigger } : {}),
+		folder: basename(folder),
+		sha,
+		...(event.source === "cron" ? { scheduledFor: event.scheduledFor ?? null, previousRunAt: event.previousRunAt ?? null } : {}),
+	};
+	writeFileSync(join(jobDir, "event.json"), JSON.stringify(eventBody, null, 2), { mode: 0o444 });
+
+	// The folder itself is /workspace (rw). No clone: local jobs edit in place.
+	return { workspace: folder, jobDir, outboxDir, sha, materialised: written };
+}
+
+async function defaultGit(gitDir, args) {
+	const { stdout } = await exec("git", ["-c", "core.hooksPath=/dev/null", "--no-pager", "-C", gitDir, ...args], {
+		encoding: "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+	});
+	return stdout;
+}

package/src/prepare.mjs

@@ -0,0 +1,199 @@
+import { mkdirSync, mkdtempSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveJobImage } from "./image-preflight.mjs";
+import { retainJobDir } from "./sandbox-store.mjs";
+import { prepareGithubWorkspace } from "./prepare-github.mjs";
+import { gitlabRemoteUrl } from "./gitlab-host.mjs";
+import { forgejoRemoteUrl } from "./forgejo-host.mjs";
+import { azureRemoteUrl } from "./azure-host.mjs";
+import { buildGitLabPrompt } from "./gitlab-prompt.mjs";
+import { buildForgejoPrompt } from "./forgejo-prompt.mjs";
+import { buildAzurePrompt } from "./azure-prompt.mjs";
+import { prepareLocalWorkspace } from "./prepare-local.mjs";
+
+/**
+ * The `prepareWorkspace` dispatcher the processor injects. Creates a per-job dir under `jobsDir`
+ * (holding the read-only /job inputs) and routes by job kind: local jobs go to `prepareLocalWorkspace`,
+ * forge-backed jobs to the preparer registered for their kind.
+ *
+ * The `flow` becomes a prompt hint; the actual skill is provided by the project's materialised
+ * .pi/skills.
+ *
+ * `forgeFor(job)` yields the `{ auth, host }` pair for that job's forge (start.mjs owns the map). The
+ * preparer is handed `host.resolveDefaultBranchSha` rather than the whole pair, so a preparer can only
+ * resolve a SHA -- it gets no minting capability and no comment surface it has no business holding.
+ *
+ * `findPreviousRun` (run-history's `makeFindPreviousRun`) feeds the cron event context below; the
+ * default returns null so an unwired dispatcher (tests, a bare construction) still writes a complete
+ * event with `previousRunAt: null`.
+ */
+export function makePrepareWorkspace({
+	jobsDir,
+	forgeFor,
+	// REQ-RESURRECTABLE-SANDBOX. The DEPLOYMENT default image, resolved per job against the trigger's own
+	// `run.image` through the SAME function the pre-spend preflight and run-container use -- so the tag that
+	// was checked, the tag that ran and the tag a sandbox later re-opens are one answer by construction
+	// rather than three call sites that happen to agree. Null leaves the stamp imageless, and
+	// `resolveSandbox` then refuses rather than guessing.
+	jobImage = null,
+	findPreviousRun = () => null,
+	// REQ-RESUMABLE-SESSION. The default returns null, so an unwired dispatcher -- tests, a bare
+	// construction -- prepares exactly what it always did: no /session mount, nothing on disk.
+	resolveSession = () => null,
+	prepareLocal = prepareLocalWorkspace,
+	// Keyed by `job.kind`, so a new forge is one entry rather than a new `if`. A kind with no entry falls
+	// through to the throw below, which is what makes an unrouted job loud instead of a silent no-op.
+	preparers = { github: prepareGithubWorkspace },
+}) {
+	mkdirSync(jobsDir, { recursive: true });
+	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null } = {}) {
+		const jobDir = mkdtempSync(join(jobsDir, "job-"));
+		// What `cleanup` needs to retain this run's directory, stamped here because this is the only place
+		// that holds all three 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.
+		const sandbox = { jobId: queueJobId ?? null, kind: job.kind ?? null, image: resolveJobImage(job, jobImage) };
+		if (job.kind === "local") {
+			// Harness text above, operator DATA below: the fixed pointer line names /job/event.json so a
+			// flow can discover the trigger context (mirroring the github prompt, which names the same
+			// file); nothing in-container reads it otherwise. The pointer sits AFTER the flow hint and
+			// BEFORE the operator's task, which stays verbatim (CONST-ISSUE-TEXT-IS-DATA).
+			const pointer = "Context about this run -- its trigger and schedule -- is in /job/event.json.\n\n";
+			const task = job.flow
+				? `Use the "${job.flow}" skill for this task.\n\n${pointer}${job.task ?? ""}`
+				: `${pointer}${job.task ?? ""}`;
+			const event = localEventContext(job, queueJobId, findPreviousRun);
+			return stampSandbox(await prepareLocal({ folder: job.folder, task, jobDir, event }), sandbox);
+		}
+		const prepare = preparers[job.kind];
+		if (prepare) {
+			const host = forgeFor?.(job)?.host;
+			return stampSandbox(
+				await prepare(job, token, {
+					jobDir,
+					resolveDefaultBranchSha: host?.resolveDefaultBranchSha,
+					// The head ref a pull/merge-request job keys on comes from the FORGE API, never the webhook
+					// payload: an issue_comment on a PR carries no head at all, and a payload-supplied head repo
+					// is attacker-controlled data that must not decide which transcript a job is handed.
+					resolvePullRequestHead: host?.resolvePullRequestHead,
+					resolveSession,
+					piVersion,
+				}),
+				sandbox,
+			);
+		}
+		throw new Error(`unknown job kind: ${job.kind}`);
+	};
+}
+
+/**
+ * The trigger context a local job's `/job/event.json` carries (INT-CONTAINER-JOB-INPUTS). Source is
+ * derived from the job data alone: a chained child carries `parentJobId`/`chainDepth` (queue.mjs sets
+ * them only on chains), a scheduled job carries the cron-only `trigger` field (schedules.mjs), and
+ * everything else is the operator's own `pi-dispatch run` -- manual.
+ *
+ * For cron, the scheduled-for instant comes from BullMQ's deterministic `repeat:<id>:<millis>` jobId
+ * (DES-CRON-VIA-BULLMQ-SCHEDULER) -- the wiring injects it as `queueJobId`. When the id is missing or
+ * unparseable the lookup is SKIPPED: both `scheduledFor` and `previousRunAt` are null, never a guess.
+ */
+function localEventContext(job, queueJobId, findPreviousRun) {
+	if (job.parentJobId !== undefined || job.chainDepth !== undefined) return { source: "chain" };
+	if (job.trigger) {
+		const millis = scheduledForMillis(queueJobId);
+		return {
+			source: "cron",
+			trigger: job.trigger,
+			scheduledFor: millis === null ? null : new Date(millis).toISOString(),
+			previousRunAt: millis === null ? null : (findPreviousRun({ schedulerId: job.trigger.id, beforeMillis: millis }) ?? null),
+		};
+	}
+	return { source: "manual" };
+}
+
+/** Parse the millis out of a `repeat:<id>:<millis>` BullMQ scheduled jobId, or null. */
+function scheduledForMillis(queueJobId) {
+	if (typeof queueJobId !== "string" || !queueJobId.startsWith("repeat:")) return null;
+	const tail = queueJobId.slice(queueJobId.lastIndexOf(":") + 1);
+	if (tail === "") return null;
+	const millis = Number(tail);
+	return Number.isFinite(millis) ? millis : null;
+}
+
+/**
+ * Attach the sandbox stamp to a successful prepare, and to nothing else.
+ *
+ * A preparer's determinate refusal (`{ outcome: "policy", reason: "sha-gone" }`) carries no `jobDir`, so
+ * it is returned verbatim: there is no directory to retain and the processor's policy branch reads the
+ * same object it always did.
+ */
+function stampSandbox(prepared, sandbox) {
+	if (!prepared?.jobDir) return prepared;
+	return { ...prepared, sandbox };
+}
+
+/** Remove a per-job dir after the run. The workspace (the operator's folder) is never touched here. */
+export async function cleanup(prepared) {
+	if (prepared?.jobDir) await rm(prepared.jobDir, { recursive: true, force: true });
+}
+
+/**
+ * The teardown the worker injects: retain this run's directory for a bounded window instead of deleting
+ * it, so `pi-dispatch sandbox` can re-open it (REQ-RESURRECTABLE-SANDBOX).
+ *
+ * With the window at 0 -- the documented "off" -- this IS `cleanup`, by the same `rm` on the same path,
+ * so a deployment that does not want retention keeps today's behaviour exactly rather than a
+ * near-equivalent of it. `retainJobDir` owns the other branch entirely, including removing `jobDir` on
+ * every failure path, which is why there is no `rm` here to pair with it.
+ *
+ * NEVER THROWS -- the processor already swallows this in a `finally`, and a retention fault must not be
+ * the thing that turns a paid, completed run into a failure.
+ */
+export function makeCleanup({ sandboxDir, retentionHours = 0, log = () => {} } = {}) {
+	return async function cleanupWithRetention(prepared) {
+		if (!prepared?.jobDir) return;
+		if (!sandboxDir || retentionHours <= 0) {
+			await cleanup(prepared);
+			return;
+		}
+		retainJobDir(prepared, { sandboxDir, log });
+	};
+}
+
+/**
+ * The per-forge preparer map `makePrepareWorkspace` dispatches on.
+ *
+ * Every forge shares `prepareGithubWorkspace`: the askpass helper, the hardening flags, the gone-SHA
+ * markers, the pinned detached checkout and the read-only event.json are facts about git and about this
+ * project, not about GitHub. Only two things differ, and both are injected -- where the clone comes from,
+ * and how the agent's envelope is phrased. A second copy of the clone path would be a second place to fix
+ * a clone bug, and the copy that did not get fixed would be the one nobody was looking at.
+ *
+ * Exported so the wiring is assertable: a job cloning from the wrong forge is a silent failure -- the URL
+ * simply would not exist, or worse, would.
+ */
+export function makeForgePreparers({ gitlabApiUrl = null, forgejoApiUrl = null, azureOrgUrl = null, prepareForge = prepareGithubWorkspace } = {}) {
+	return {
+		github: prepareForge,
+		gitlab: (job, token, opts) =>
+			prepareForge(job, token, {
+				...opts,
+				remoteUrlFor: (j) => gitlabRemoteUrl(gitlabApiUrl, j.repo),
+				buildPrompt: buildGitLabPrompt,
+			}),
+		forgejo: (job, token, opts) =>
+			prepareForge(job, token, {
+				...opts,
+				remoteUrlFor: (j) => forgejoRemoteUrl(forgejoApiUrl, j.repo),
+				buildPrompt: buildForgejoPrompt,
+			}),
+		azure: (job, token, opts) =>
+			prepareForge(job, token, {
+				...opts,
+				// Azure's clone URL is `<org>/<project>/_git/<repo>` -- built from the job's structured scope,
+				// not from its `repo` label, because that label is `project/repo` and reassembling a URL from
+				// a display string is how the wrong repository gets cloned.
+				remoteUrlFor: (j) => azureRemoteUrl(azureOrgUrl, j),
+				buildPrompt: buildAzurePrompt,
+			}),
+	};
+}

package/src/pricing.mjs

@@ -0,0 +1,168 @@
+/**
+ * Pricing façade over pi-ai (issue #53). pi-dispatch holds NO pricing table and computes NOTHING of
+ * its own -- pricing is pi-ai's (`calculateCost` over its per-provider model tables). The admin
+ * extension needs to re-price recorded token profiles (what-if: "this run's tokens at that model's
+ * rates") and to enumerate priced models, and it must NOT grow its own pi-ai dependency -- that would
+ * be a fourth exact pin and a second drift axis between the recorded truth and the screen. So the
+ * admin imports this worker export instead: the same anti-drift idiom as `budget`'s dayKey and
+ * `subscriptions`' parser -- one side owns the artifact, the other imports it, and the two cannot
+ * drift.
+ *
+ * Stream-time cost on the usage-ledger record stays the METERED truth; this façade prices
+ * COUNTERFACTUALS only (same posture as DES-SUBSCRIPTIONS-ARE-COUNTERFACTUAL-ONLY). Nothing here
+ * touches job execution, routing, or the record path.
+ *
+ * Import discipline: enumeration comes from "@earendil-works/pi-ai/providers/all" and the arithmetic
+ * from the root "@earendil-works/pi-ai" -- both declared side-effect-free in pi-ai's package.json
+ * (`sideEffects` names only compat/images registration modules). NEVER import
+ * "@earendil-works/pi-ai/compat" here: it registers providers at module scope, and a pricing lookup
+ * must not mutate global registries as a side effect of being asked a question.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { calculateCost } from "@earendil-works/pi-ai";
+import { getBuiltinModel, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
+
+/**
+ * Every builtin pi-ai model, flattened to `{ provider, id, cost }`. `cost` is pi-ai's ModelCost
+ * object passed BY REFERENCE -- it is pi-ai's data, callers treat it read-only. Rates are USD per
+ * 1M tokens; an all-zero table is CORRECT data for subscription-backed providers (kimi-coding,
+ * zai-coding-cn), not missing data -- `isZeroRated` is how callers tell the two apart.
+ */
+export function listPricedModels() {
+	const out = [];
+	for (const provider of getBuiltinProviders()) {
+		for (const model of getBuiltinModels(provider)) {
+			out.push({ provider, id: model.id, cost: model.cost });
+		}
+	}
+	return out;
+}
+
+/**
+ * Look up one builtin model; the pi-ai Model or null. Never throws on garbage: non-string args are
+ * refused, and because pi-ai's generated catalog is a plain object literal, keys like "__proto__"
+ * or "constructor" would resolve THROUGH the prototype chain to real objects -- so the provider must
+ * be an own catalog key and the hit must actually be a model (carrying its own id and a cost table).
+ */
+export function getPricedModel(provider, id) {
+	if (typeof provider !== "string" || typeof id !== "string") return null;
+	if (!getBuiltinProviders().includes(provider)) return null;
+	const model = getBuiltinModel(provider, id);
+	if (model === null || model === undefined || typeof model !== "object") return null;
+	if (model.id !== id || model.cost === null || typeof model.cost !== "object") return null;
+	return model;
+}
+
+/**
+ * True when all four base rates are zero -- the signature of a subscription-backed provider, whose
+ * runs meter at $0 because the plan is prepaid (see subscriptions.mjs for where the real price
+ * lives). Tiers are deliberately ignored: a zero-rate provider ships no tiers, and a priced provider
+ * with a zero base rate somewhere does not become "free" by it. Null/malformed input is false --
+ * "not zero-rated" is the safe answer for a thing that is not a model.
+ */
+export function isZeroRated(model) {
+	const cost = model?.cost;
+	if (cost === null || cost === undefined || typeof cost !== "object") return false;
+	return cost.input === 0 && cost.output === 0 && cost.cacheRead === 0 && cost.cacheWrite === 0;
+}
+
+/** Default reader for piAiVersion; injectable so tests never depend on disk layout. */
+function readTextFromDisk(path) {
+	return readFileSync(path, "utf8");
+}
+
+/**
+ * Resolve the pinned pi-ai's version from its package.json on disk. pi-ai's exports map has NO
+ * "./package.json" entry, so the file cannot be imported or require.resolved directly -- and the map
+ * carries only the "import" condition, so createRequire().resolve() on the bare specifier throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED too. import.meta.resolve is the resolution that works: it yields the
+ * ESM entry (dist/index.js), and from there we walk parent directories until a package.json names
+ * the package. Bounded walk, every step forgiving: any read/parse/mismatch just keeps climbing, and
+ * any failure overall is null, never a throw.
+ */
+function readPiAiVersion(readText) {
+	try {
+		let dir = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-ai")));
+		for (let hops = 0; hops < 8; hops++) {
+			try {
+				const parsed = JSON.parse(readText(join(dir, "package.json")));
+				if (parsed !== null && parsed.name === "@earendil-works/pi-ai") {
+					const match = /^(\d+\.\d+\.\d+)/.exec(String(parsed.version ?? ""));
+					return match === null ? null : match[1];
+				}
+			} catch {
+				// dist/ has no package.json (ENOENT), or the injected reader refused -- keep climbing.
+			}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {
+		// import.meta.resolve failed: pi-ai is not installed where we run. null says so quietly.
+	}
+	return null;
+}
+
+let defaultVersionCache;
+
+/**
+ * The pinned pi-ai's "<major.minor.patch>", or null. Lazy and cached (a null miss is cached too --
+ * the answer will not change within a process), and it never throws: the version tags counterfactual
+ * prices as `ratesVersion`, and a cosmetic label must never take the pricing path down. An injected
+ * `readText` bypasses the cache and reads fresh -- that path exists for tests.
+ */
+export function piAiVersion({ readText } = {}) {
+	if (readText !== undefined) return readPiAiVersion(readText);
+	if (defaultVersionCache === undefined) defaultVersionCache = readPiAiVersion(readTextFromDisk);
+	return defaultVersionCache;
+}
+
+/** A token count from an untrusted profile: finite and positive, or 0. */
+function tokenCount(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Price a recorded token profile at another model's rates: `{ usd, ratesVersion }`, or null when the
+ * target is not a builtin model. `quad` is `{ input, output, cacheRead, cacheWrite, cacheWrite1h }`;
+ * non-finite/negative counts are treated as 0, and the caller's object is never touched.
+ *
+ * The one judgment this façade makes is the 1h cache split. pi-ai's `calculateCost` applies the
+ * 2x-base-input premium for ANY model when `cacheWrite1h > 0`, but the premium is an ANTHROPIC
+ * billing rule -- only Anthropic ever reports the field. Carrying a source profile's 1h split onto a
+ * target that never bills it would invent cost out of thin air, so the split is forwarded only when
+ * the TARGET is anthropic; everywhere else every write is priced short. (And a profile claiming more
+ * 1h writes than writes is malformed: clamped, so pi-ai's short-write term cannot go negative.)
+ */
+export function reprice(quad, target, { readText } = {}) {
+	const model = getPricedModel(target?.provider, target?.id);
+	if (model === null) return null;
+
+	const input = tokenCount(quad?.input);
+	const output = tokenCount(quad?.output);
+	const cacheRead = tokenCount(quad?.cacheRead);
+	const cacheWrite = tokenCount(quad?.cacheWrite);
+	const cacheWrite1h = model.provider === "anthropic"
+		? Math.min(tokenCount(quad?.cacheWrite1h), cacheWrite)
+		: 0;
+
+	// A FRESH Usage every call, never a shared or caller-owned object: calculateCost MUTATES its
+	// argument in place (usage.cost.* is assigned, not returned fresh) and REQUIRES the cost skeleton
+	// to already exist -- handing it a shared object would leak one caller's price into the next, and
+	// omitting the skeleton is a TypeError (both pinned in pricing.test.mjs).
+	const usage = {
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		cacheWrite1h,
+		totalTokens: input + output + cacheRead + cacheWrite,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+	calculateCost(model, usage);
+	return { usd: usage.cost.total, ratesVersion: piAiVersion({ readText }) };
+}