@edgehero/pi-dispatch 0.1.0

package/src/sandbox.mjs

@@ -0,0 +1,171 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { configError } from "./config.mjs";
+import { buildDockerRunArgs } from "./docker-run.mjs";
+import { sanitizeJobId } from "./run-history.mjs";
+import { readManifest } from "./sandbox-store.mjs";
+
+/**
+ * sandbox.mjs -- the operator session's container shape (INT-SANDBOX-CONTRACT).
+ *
+ * A SECOND container shape, deliberately not a second copy of the first. The argv comes from
+ * `buildDockerRunArgs` through its `extraFlags` seam, so `ISOLATION_FLAGS`, `--memory` and `--cpus` reach
+ * this container BY CONSTRUCTION: a future change to the boundary cannot land on job containers and miss
+ * this one, which is the whole reason for reusing the builder rather than writing a leaner argv here.
+ *
+ * What differs from a job, and every difference is the point:
+ *   - `-i -t --entrypoint bash`. `INT-CONTAINER-RUNTIME-CONTRACT` says "No TTY (`-it` absent)" and stays
+ *     true; this is a different contract for a different object, not an amendment to that one.
+ *   - NO CREDENTIALS. Not the minted forge token, not the provider key, not one forwarded host variable.
+ *     `buildContainerEnv` is deliberately NOT reused: it writes the mint into that forge's variable names
+ *     (env-allowlist.mjs) and throws outright when no provider credential resolves, so a credential-free
+ *     container cannot be produced from it. The env here is two variables, both about the terminal.
+ *   - No `/outbox`, no `/session`, no `/opt/pi-global`. The agent is not running; there is nothing to
+ *     chain, no transcript to continue and no overlay to layer.
+ *
+ * The agent is not running. The operator is at the keyboard and brings their own auth if they need it.
+ */
+
+const exec = promisify(execFile);
+
+/**
+ * The name namespace, and it is load-bearing. The boot reaper filters `name=pi-job-`
+ * (`makeReaper` in start.mjs) and docker matches that as a SUBSTRING, so a sandbox must not contain it --
+ * otherwise a worker restart kills the shell an operator is sitting in. `pi-sandbox-` is outside that
+ * filter on purpose, and a test pins it.
+ */
+export const SANDBOX_NAME_PREFIX = "pi-sandbox-";
+
+/** `pi-sandbox-<jobId>`. `sanitizeJobId` already maps to `[A-Za-z0-9._-]`, which is a legal docker name. */
+export function sandboxContainerName(jobId) {
+	return `${SANDBOX_NAME_PREFIX}${sanitizeJobId(jobId)}`;
+}
+
+/**
+ * Turn `--publish` values into docker flags, BOUND TO LOOPBACK, always.
+ *
+ * `3000` publishes container 3000 on host 3000; `8080:3000` publishes container 3000 on host 8080. An
+ * explicit bind address is refused rather than honoured: this container holds whatever the agent wrote,
+ * and the deployment's own admin surface is 127.0.0.1-only for the same reason
+ * (`DES-PANEL-SEPARATE-FROM-RECEIVER`). Making the LAN case merely inconvenient would be a worse answer
+ * than making it unavailable.
+ */
+export function parsePublish(values = []) {
+	const flags = [];
+	for (const raw of values) {
+		const match = /^(\d{1,5})(?::(\d{1,5}))?$/.exec(String(raw).trim());
+		const host = match && Number(match[1]);
+		const container = match && Number(match[2] ?? match[1]);
+		if (!match || !inPortRange(host) || !inPortRange(container)) {
+			throw configError(`invalid --publish ${JSON.stringify(raw)} (want <port> or <hostPort>:<containerPort>; the bind address is always 127.0.0.1)`);
+		}
+		flags.push("-p", `127.0.0.1:${host}:${container}`);
+	}
+	return flags;
+}
+
+function inPortRange(n) {
+	return Number.isInteger(n) && n >= 1 && n <= 65535;
+}
+
+/**
+ * Build the `docker run` argv for one operator session (excluding the leading "docker").
+ *
+ * @param image        the image the original run used, from its manifest
+ * @param name         `pi-sandbox-<jobId>`
+ * @param workspace    host path mounted /workspace:rw -- the retained clone, or the operator's own folder
+ * @param jobDir       the retained per-job dir, mounted /job:ro exactly as the run had it
+ * @param publish      already-parsed `-p` flags
+ * @param term         the host's TERM, so the shell renders
+ * @param idleSeconds  bash's own TMOUT; 0 omits it
+ */
+export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0 }) {
+	return buildDockerRunArgs({
+		image,
+		name,
+		workspace,
+		jobDir,
+		// The ONLY two variables, and neither is a credential. TERM so the shell renders; TMOUT so a
+		// forgotten session closes itself. `buildDockerRunArgs` skips undefined, so an unset TERM or a
+		// disabled idle timeout emits nothing rather than an empty string.
+		env: {
+			TERM: term || undefined,
+			TMOUT: idleSeconds > 0 ? String(idleSeconds) : undefined,
+		},
+		// Ahead of the env and the mounts, and well ahead of the image, which buildDockerRunArgs keeps as
+		// the final positional. `--entrypoint` also clears the image's CMD; this repo's Dockerfile sets
+		// none, so `bash` runs bare and `-it` makes it interactive, in the baked WORKDIR as the baked
+		// non-root USER.
+		extraFlags: ["-i", "-t", "--entrypoint", "bash", ...publish],
+	});
+}
+
+/**
+ * The JOB IDS of sandboxes running right now -- ids, not container names, because that is the shape both
+ * consumers want: the reaper compares them to directory names, and `--list` marks rows.
+ *
+ * THROWS when docker cannot be asked, and that is the point: "none are running" and "I could not find out"
+ * must not arrive as the same empty array. The reaper deletes directories, and it treats the second case as
+ * a reason to skip the whole sweep -- swallowing the error here would quietly turn a docker outage into a
+ * blind sweep that can pull a bind mount out from under a live shell. The CLI, which only draws a column,
+ * degrades on its own.
+ *
+ * TIMED, unlike the boot container reaper's own `docker ps`: an unreachable daemon does not fail the CLI
+ * fast, it blocks, and this call sits in front of a worker that has not started draining yet.
+ */
+export async function listRunningSandboxes({ execFn = exec } = {}) {
+	const { stdout } = await execFn("docker", ["ps", "--filter", `name=${SANDBOX_NAME_PREFIX}`, "--format", "{{.Names}}"], { timeout: 5000 });
+	return stdout
+		.split("\n")
+		.map((n) => n.trim())
+		.filter((n) => n.startsWith(SANDBOX_NAME_PREFIX))
+		.map((n) => n.slice(SANDBOX_NAME_PREFIX.length));
+}
+
+/**
+ * Resolve one retained run into a launchable argv, or a NAMED refusal.
+ *
+ * Split out from the launch so both callers -- the CLI and the admin panel -- refuse identically, and so
+ * the whole decision is testable without docker. Every refusal names what to do next, the posture
+ * `doctor` sets: a bare "not found" for a run the operator watched finish ten minutes ago is the least
+ * useful thing this could say.
+ */
+export function resolveSandbox({ jobId, sandboxDir, retentionHours, publish = [], fs, fileExists = existsSync }) {
+	if (!jobId) return { refused: "no-job-id", message: "a job id is required (see `pi-dispatch sandbox --list`)" };
+
+	const manifest = readManifest({ sandboxDir, jobId, ...(fs ? { fs } : {}) });
+	if (!manifest) {
+		return retentionHours === 0
+			? { refused: "retention-off", message: "workspace retention is off — set PI_SANDBOX_RETENTION_HOURS to a positive number to make future runs resurrectable" }
+			: { refused: "absent", message: `no retained workspace for ${jobId} — it was swept after ${retentionHours}h, or the run predates retention (\`pi-dispatch sandbox --list\` shows what is left)` };
+	}
+	if (!manifest.image) {
+		return { refused: "no-image", message: `the manifest for ${jobId} names no image, so the sandbox cannot reproduce the run` };
+	}
+	if (!manifest.workspace || !fileExists(manifest.workspace)) {
+		// The common cause for a local run: the operator's folder moved or was deleted. Naming the path is
+		// the whole diagnosis, so name it.
+		return { refused: "workspace-gone", message: `the workspace for ${jobId} is no longer at ${manifest.workspace} — a local folder that moved cannot be re-opened` };
+	}
+
+	return { manifest, name: sandboxContainerName(jobId), publish };
+}
+
+/**
+ * Launch one operator session, attached to the caller's terminal, and resolve its exit code.
+ *
+ * `spawn`, never `spawnSync`, and `stdio: "inherit"`: the same shape pi itself uses to hand the terminal
+ * to `$EDITOR` (`extension-editor.js`), whose comment records why the synchronous form is wrong -- on
+ * Windows it can keep libuv's console read active and race the child for input.
+ *
+ * The caller owns the terminal around this: the CLI simply has one, and the admin panel brackets the call
+ * with `tui.stop()`/`tui.start()`.
+ */
+export function launchSandbox({ args, spawnFn = spawn }) {
+	return new Promise((resolve) => {
+		const child = spawnFn("docker", args, { stdio: "inherit" });
+		child.on("error", (err) => resolve({ code: null, error: err }));
+		child.on("close", (code) => resolve({ code }));
+	});
+}

package/src/scheduler-stall-guard.mjs

@@ -0,0 +1,67 @@
+/**
+ * Per-scheduler stall accounting -- the money backstop for cron (constitution.md:203-216).
+ *
+ * BullMQ's `maxStalledCount` does not cover scheduler jobs: `moveStalledJobsToWait` derives
+ * `isRepeatableJob` from the job's `rjk` field and skips the stall-fail for a live scheduler, so a
+ * wedged scheduled run is re-processed -- paid -- on every stall, indefinitely. `maxStalledCount: 0`
+ * bounds ordinary jobs; nothing in BullMQ bounds scheduler jobs. This guard counts stalls per
+ * scheduler over a rolling window and tears the scheduler down once the count exceeds a threshold.
+ *
+ * Injected `redis` (ioredis-compatible), `removeJobScheduler`, and `log` keep the logic testable with
+ * no queue, no bullmq import, and no real Valkey.
+ *
+ * Custom: per-scheduler stall accounting; BullMQ's maxStalledCount does not cover scheduler jobs -- constitution.md:203-216 carve-out ("BullMQ will never do this for us")
+ */
+
+// The Redis hash of per-scheduler stall counts (field = schedulerId, value = count). Exported so the admin
+// panel can read it (HGETALL) for the cron drill-in without re-deriving the key string.
+export const STALL_KEY = "pi-dispatch:sched-stalls";
+
+// A rolling window: the EXPIRE is re-set on every stall, so a scheduler that stops stalling for a full
+// day drops back to zero. This prevents unrelated transient stalls weeks apart from accumulating into a
+// false teardown -- only sustained stalling inside one window trips the threshold.
+const STALL_WINDOW_SECONDS = 24 * 60 * 60;
+
+/**
+ * Build the `stalled` listener. `threshold` is how many stalls a single scheduler may accrue before
+ * teardown, compared STRICT `>` to mirror BullMQ's own `stalledCount > maxStalledJobCount`.
+ * `removeJobScheduler(schedulerId)` tears a scheduler down; `log(event, fields)` records stable ids
+ * only, never task or body content.
+ *
+ * The returned `onStalled` never rejects: BullMQ's `stalled` event is fire-and-forget (void-invoked),
+ * so a rejection here would surface as an unhandled rejection with no handler to catch it.
+ */
+export function makeStallGuard({ redis, threshold, removeJobScheduler, log }) {
+	return async function onStalled(jobId) {
+		try {
+			// Ordinary jobs are bounded by `maxStalledCount: 0`; only scheduler jobs reach this accounting.
+			if (!jobId.startsWith("repeat:")) return;
+
+			const schedulerId = jobId.slice("repeat:".length, jobId.lastIndexOf(":"));
+			if (schedulerId === "") {
+				// Degenerate `repeat:<n>` / `repeat::<n>` with no scheduler segment: an empty hash field would
+				// pool every such id into one counter, so log and skip rather than hincrby an empty key.
+				log("scheduler_stall_unparsed", { jobId });
+				return;
+			}
+
+			const count = Number(await redis.hincrby(STALL_KEY, schedulerId, 1));
+			await redis.expire(STALL_KEY, STALL_WINDOW_SECONDS);
+
+			if (count > threshold) {
+				try {
+					await removeJobScheduler(schedulerId);
+				} catch (error) {
+					// A scheduler already gone (removed concurrently, or between the stall and now) is the goal
+					// state, not an error -- swallow it so hdel and the teardown alert still run.
+					log("scheduler_teardown_remove_failed", { schedulerId, error: error?.message });
+				}
+				await redis.hdel(STALL_KEY, schedulerId);
+				// The loud log is the "alert" half of the constitution's "removeJobScheduler -- or alert".
+				log("scheduler_torn_down", { schedulerId, stalls: count });
+			}
+		} catch (error) {
+			log("scheduler_stall_guard_error", { jobId, error: error?.message });
+		}
+	};
+}

package/src/schedules.mjs

@@ -0,0 +1,62 @@
+/**
+ * Select the worker's cron schedules from the unified triggers file (DES-CRON-VIA-BULLMQ-SCHEDULER,
+ * issue #20). The worker owns exactly the `on.type:"cron"` entries; the receiver owns the webhook types.
+ * The shared validator (`triggers.mjs`) parses and validates the WHOLE file fail-loud -- the diagonal,
+ * the `id` charset, cron field count -- so this module only selects the cron subset, checks that each
+ * `run.folder` exists on disk (the one fs-dependent check the pure validator cannot make), and normalizes
+ * to the shape the caller hands to BullMQ's `upsertJobScheduler` (`schedulerId`, `name`, `pattern`, and
+ * the `data`/`opts` job template).
+ *
+ * Fail-loud, like config.mjs: a misconfigured triggers file makes the worker refuse to start with a clear
+ * message rather than upserting a broken scheduler that silently never fires. Every load-time rejection is
+ * a `configError` so the CLI/entry prints it cleanly and exits non-zero.
+ */
+
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { configError } from "./config.mjs";
+import { parseTriggers } from "./triggers.mjs";
+
+/**
+ * Parse, validate, and select the cron schedules from the triggers file named by `config.triggersFile`.
+ * Returns `[]` when cron is disabled (`triggersFile` null/absent) -- a worker with no cron triggers is a
+ * valid deployment. `readFileSync`/`existsSync` are injectable so tests exercise the full path with no
+ * real filesystem.
+ */
+export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.triggersFile;
+	if (path === null || path === undefined) return []; // cron disabled
+
+	if (!existsSync(path)) {
+		throw configError(`triggers file does not exist: ${path}`);
+	}
+
+	const triggers = parseTriggers(readFileSync(path, "utf8"), path);
+
+	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync));
+}
+
+function normalizeCronSchedule({ on, run }, path, existsSync) {
+	// The pure validator already guaranteed a non-empty, `:`-free, charset-valid, unique id and a
+	// well-formed pattern; folder existence is the one fs-dependent check it deferred to here.
+	if (!existsSync(run.folder)) {
+		throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
+	}
+
+	// Absent provider/model/maxTurns stay absent (undefined) so the value resolves at job start against the
+	// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT). data key order matches
+	// queue.mjs -- the shape the processor's runJob consumes. The three per-trigger fields ride along the same
+	// way and are kept adjacent: `github` (the scoped token flag), `packages` (load the operator-staged pi
+	// packages) and `image` (which container image this schedule's jobs run in) -- INT-TRIGGERS-FILE-CONTRACT,
+	// REQ-GLOBAL-PI-OVERLAY. `image` is a SELECTOR rather than an opt-in: absent does not mean "off", it means
+	// the deployment default, resolved at job start (image-preflight.mjs). Undefined drops out at JSON
+	// serialization, so an unflagged schedule stays byte-identical to today's. `trigger` is the one
+	// cron-only field: it is carried into the local `/job/event.json` (INT-CONTAINER-JOB-INPUTS) so a
+	// scheduled job can name its own trigger; the INT-TRIGGERS-FILE-CONTRACT byte-match acceptance is
+	// amended for exactly this field.
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, resume: run.resume, 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 } };
+
+	return { schedulerId: on.id, name: "local", pattern: on.pattern, data, opts };
+}