@edgehero/pi-dispatch 0.3.0 → 1.1.0

package/src/triggers.mjs

@@ -191,13 +191,20 @@ function normalizeCron(on, run, index, path, state) {
 		throw configError(`cron trigger "${id}": on.pattern must have 5 or 6 space-separated fields, got ${fieldCount}: ${path}`);
 	}
 
+	// FIRST among the run checks (all four normalizers do this), so a command-only entry is never told to
+	// add the flow it deliberately does not have, and a flow+command entry gets the exclusion message
+	// rather than whichever single-field check happens to run first.
+	const command = validateCommand(run, `cron trigger "${id}"`, path, { onType: "cron" });
+
 	if (!isNonEmptyString(run.folder)) {
 		throw configError(`cron trigger "${id}": run.folder must be a non-empty string: ${path}`);
 	}
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`cron trigger "${id}": run.flow must be a non-empty string: ${path}`);
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`cron trigger "${id}": run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
-	if (!isNonEmptyString(run.task)) {
+	// Gated on the flow path only: a command job's prompt IS the command line, and validateCommand has
+	// already refused any run.task written beside one.
+	if (command === undefined && !isNonEmptyString(run.task)) {
 		throw configError(`cron trigger "${id}": run.task must be a non-empty string: ${path}`);
 	}
 
@@ -229,7 +236,7 @@ function normalizeCron(on, run, index, path, state) {
 	// freeze today's default into every stored repeatable.
 	return {
 		on: { type: "cron", id, pattern },
-		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...(skillsDir !== undefined && { skillsDir }) },
+		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }) },
 	};
 }
 
@@ -271,8 +278,9 @@ function validatePackagesFlag(run, at, path) {
  * had. `validateReplicas` states the argument in one line and it applies verbatim here: a field accepted
  * where it does nothing is how an operator comes to trust one that does nothing.
  *
- * "NOT YET COVERED", not impossible -- validateReplicas' own distinction, kept because the two are
- * different facts and an operator planning work needs the right one. The local key already exists and is
+ * "NOT YET COVERED", not impossible -- a distinction this file keeps because the two are different facts
+ * and an operator planning work needs the right one. `run.replicas` carried the same wording for the same
+ * reason until #187 closed its gap; this one is still open, which is why the phrasing outlived it. The local key already exists and is
  * the strongest key in this feature: session-key.mjs keys a cron job on its scheduler id, which is
  * operator-authored, unique across the file, stable across fires, and chosen by nobody untrusted. Nothing
  * reaches it. Wiring `resolveSession` into the local path is a feature, and this line is what stops the
@@ -420,8 +428,9 @@ const INSTRUCTIONS_MAX = 2000;
  * `run.instructions` (issue #60): one line of operator standing text, rendered into the USER prompt's
  * envelope above the fenced data region.
  *
- * REFUSED on cron, and it is a DIFFERENT refusal from run.replicas' "not yet covered": cron already has
- * an operator-authored free-text field landing in the same region of the same file. A local job's prompt
+ * REFUSED on cron, and it is a DIFFERENT refusal from the "not yet covered" shape (run.resume's, since
+ * #187 retired run.replicas'): cron already has an operator-authored free-text field landing in the same
+ * region of the same file. A local job's prompt
  * is `flow hint + pointer + run.task` with no envelope, no data heading and no fence (prepare.mjs), so
  * there is no "standing" region distinct from the task for a second field to occupy. Two fields writing
  * one region with an undefined combination order is worse than a field that does nothing, because both
@@ -450,6 +459,85 @@ function validateInstructions(run, at, path, { cron = false } = {}) {
 	return text;
 }
 
+/**
+ * `run.command` (issue #189): dispatch a REGISTERED pi extension command headlessly, instead of a flow.
+ * The runner half is already merged: it exports the name via PI_COMMAND, refuses pre-spend when
+ * `getCommand` does not know it, and prompts with the exact `/name args` line and nothing else, so the
+ * arguments reach the command handler precisely as written here. Shared by all four normalizers so both
+ * services refuse the same file identically; the runner re-validates at the paid boundary regardless.
+ *
+ * EXACTLY ONE of run.flow / run.command, and the exclusion is checked BEFORE every normalizer's
+ * flow-required check on purpose: the two mistakes need their own messages. A flow+command entry no
+ * longer says which one runs and must hear that, not whichever single-field complaint fires first; a
+ * command-only entry must never be told to add the flow it deliberately does not have.
+ *
+ * The value rules each refuse something specific:
+ *   - no leading "/": the runner PREPENDS the slash when it builds the prompt, so a written one would
+ *     dispatch "//name" -- a command no registry holds, refused only after review already passed it.
+ *   - surrounding whitespace is REFUSED, never trimmed (validateImageRef's rule): the arguments pass to
+ *     the handler verbatim, so a silent trim is the reviewed file disagreeing with what runs.
+ *   - no control characters. A newline would smuggle a SECOND line into what the operator reviewed as
+ *     one command line, and the whole class is refused rather than the newline alone because every
+ *     member is invisible in review, which is the hazard. The regex is spelled in \u escapes for the
+ *     same reason: a literal ESC in this source would be exactly the unreviewable byte it refuses.
+ *
+ * Cross-field refusals, validateReplicas' posture (a field accepted where it does nothing is one an
+ * operator sets and then trusts):
+ *   - run.task on cron: a command job's prompt IS the `/name args` line, so there is no task text for
+ *     the runner to render -- two prompts written for one job, with only one ever sent.
+ *   - run.instructions on the webhook kinds: instructions land in the prompt ENVELOPE, which a command
+ *     job bypasses entirely, so nothing would render them. (Cron refuses instructions already, with its
+ *     own run.task message, and that refusal stays the one a cron entry gets.)
+ *   - run.resume: true on any kind: what a resumed session should do with a re-dispatched command is
+ *     UNDESIGNED -- "not yet covered", validateResumeFlag's own vocabulary, because it is a gap to
+ *     close and not a limit. Only `true` is refused; `false` is the documented default and refusing it
+ *     would refuse an operator for writing down the behaviour they already have.
+ *
+ * Everything else stays orthogonal on purpose -- replicas, image, packages, skillsDir, repository,
+ * github. Those gate the CONTAINER a job runs in, and a command job runs in the same container a flow
+ * job does.
+ *
+ * A COMMENT command trigger has no default flow, which leaves the receiver's `<phrase> <flow>` comment
+ * override with nothing to override. That token is made inert by the receiver's FILTER, not refused
+ * here: the override lives in adversarial comment text, which this file-shape validator never sees.
+ *
+ * `at` is the caller's message prefix, `onType` selects the cross-field set. Returns the command,
+ * undefined when absent, and the callers spread it conditionally: a flow trigger must not grow the key
+ * at all, so an unflagged file normalizes byte-identically to today's (deepEqual pins depend on it).
+ */
+function validateCommand(run, at, path, { onType }) {
+	const raw = run.command;
+	if (run.flow !== undefined && raw !== undefined) {
+		throw configError(`${at}: exactly one of run.flow or run.command must be set -- a trigger dispatches either a flow or a registered command, and with both present the file does not say which one runs: ${path}`);
+	}
+	if (raw === undefined) return undefined;
+	if (!isNonEmptyString(raw)) {
+		throw configError(`${at}: run.command must be a non-empty string -- the registered command name, optionally followed by its arguments: ${path}`);
+	}
+	if (raw !== raw.trim()) {
+		throw configError(`${at}: run.command must not have leading or trailing whitespace -- the arguments reach the command handler verbatim, so trimming here would make the reviewed file disagree with what runs (got ${JSON.stringify(raw)}): ${path}`);
+	}
+	if (raw.startsWith("/")) {
+		throw configError(`${at}: run.command must not start with "/" -- the runner prepends the slash when it builds the /name args prompt, so a written one would dispatch "//name" (got ${JSON.stringify(raw)}): ${path}`);
+	}
+	// The class is the RUNNER's (parseCommand, image/runner/src/config.mjs), DEL included: the two
+	// must refuse identically, or a value that loads here refuses in-container with the budget
+	// slot already burned -- the drift INT-TRIGGERS-FILE-CONTRACT promises cannot happen.
+	if (/[\u0000-\u001F\u007F]/.test(raw)) {
+		throw configError(`${at}: run.command must not contain control characters -- a newline would smuggle a second line into what the operator reviewed as one command line (got ${JSON.stringify(raw)}): ${path}`);
+	}
+	if (onType === "cron" && run.task !== undefined) {
+		throw configError(`${at}: run.command and run.task cannot be combined -- a command job's prompt IS the /name args line, so there is no task text for the runner to render; put the arguments in run.command: ${path}`);
+	}
+	if (onType !== "cron" && run.instructions !== undefined) {
+		throw configError(`${at}: run.command and run.instructions cannot be combined -- instructions render into the prompt envelope, and a command job's prompt is the exact /name args line with no envelope, so nothing would render them: ${path}`);
+	}
+	if (run.resume === true) {
+		throw configError(`${at}: combining run.command and run.resume is not yet covered -- what a resumed session should do with a re-dispatched command is undesigned, so this is a gap to close, not a limit: ${path}`);
+	}
+	return raw;
+}
+
 /**
  * Validate an `{any, all, none}` label predicate. Selectors are validated as arrays of non-empty strings
  * BEFORE the positive-selector count, because `.length` is truthy on a string too -- a string selector
@@ -511,12 +599,12 @@ function validateRepository(run, onType, at, path) {
  *
  * WHY EACH REFUSAL:
  *   - a LOCAL (cron) trigger: its `/workspace` IS the operator's folder, bind-mounted read-write and edited
- *     in place, so two replicas would stomp each other's working tree with no gate and no undo. A github
+ *     in place, so two replicas would stomp each other's working tree with no gate and no undo. A forge
  *     job gets its own `mkdtemp`'d clone, which is the entire reason this is safe there and not here.
- *     Checked FIRST so a cron trigger gets that reason rather than the forge-coverage one below.
- *   - a non-github forge: every forge mints its branch through the same `issueBranch`, so extending this is
- *     mechanical -- but it is not done, and the message says "not yet covered" rather than "impossible"
- *     because those are different facts and an operator planning work needs the right one.
+ *     Checked FIRST, and since #187 that ordering carries the whole kind gate rather than merely picking
+ *     which reason a cron trigger hears. Every forge mints its branch through the same `issueBranch`, so
+ *     anything that is not `local` is now allowed; move this below the range check and a cron entry
+ *     carrying `replicas: 2` would be ACCEPTED, not refused with a different message.
  *   - a non-integer, `< 2`, or `> REPLICAS_MAX`. `1` is REFUSED rather than accepted: a one-member replica
  *     set is a field that does nothing, and this validator's whole job is to make sure nothing does nothing.
  *   - `run.resume: true`. A resumed run continues ONE lineage; replicas exist to fork it. This is the
@@ -538,9 +626,6 @@ function validateReplicas(run, at, path) {
 	if (run.kind === "local") {
 		throw configError(`${at}: run.replicas is not available on a cron trigger -- a local job's /workspace IS the operator's folder, bind-mounted read-write, so two replicas would edit one working tree with no gate and no undo: ${path}`);
 	}
-	if (run.kind !== "github") {
-		throw configError(`${at}: run.replicas is not yet covered for ${run.kind} triggers (github only in this version); every forge mints its branch the same way, so this is a gap to close, not a limit: ${path}`);
-	}
 	if (!Number.isInteger(replicas) || replicas < 2 || replicas > REPLICAS_MAX) {
 		throw configError(`${at}: run.replicas must be an integer between 2 and ${REPLICAS_MAX} when present -- ${REPLICAS_MAX} is the ceiling because PI_CONCURRENCY defaults to 3, so a further replica would queue instead of racing, and 1 is refused because a one-member replica set is a flag that does nothing (got ${JSON.stringify(replicas)}): ${path}`);
 	}
@@ -553,8 +638,10 @@ function validateReplicas(run, at, path) {
 function normalizeLabel(on, run, index, path) {
 	const at = `trigger at index ${index}`;
 	const predicate = validatePredicate(on, index, path, true);
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: label trigger run.flow must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why.
+	const command = validateCommand(run, at, path, { onType: "label" });
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`${at}: label trigger run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
@@ -565,7 +652,7 @@ function normalizeLabel(on, run, index, path) {
 	const replicas = validateReplicas(run, at, path);
 	return {
 		on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -574,8 +661,12 @@ function normalizeComment(on, run, index, path, state) {
 	if (!isNonEmptyString(on.phrase)) {
 		throw configError(`${at}: comment trigger on.phrase must be a non-empty string: ${path}`);
 	}
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why. A command
+	// trigger has NO default flow for the `<phrase> <flow>` comment override to replace; making that
+	// token inert is the receiver filter's job, not a shape this validator can see.
+	const command = validateCommand(run, at, path, { onType: "comment" });
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string (or use run.command): ${path}`);
 	}
 	// At most one comment trigger PER FORGE. The cap exists because the receiver holds one comment rule
 	// per forge and a second would be silently unreachable -- so it is a cap on ambiguity, not on count,
@@ -593,7 +684,7 @@ function normalizeComment(on, run, index, path, state) {
 	const replicas = validateReplicas(run, at, path);
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -634,8 +725,10 @@ function normalizePullRequest(on, run, index, path) {
 		throw configError(`${at}: an azure pull_request trigger cannot carry a label predicate -- Azure DevOps attaches tags to work items, never to pull requests, so any/all/none could never match: ${path}`);
 	}
 	const predicate = validatePredicate(on, index, path, requirePositive);
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: pull_request trigger run.flow must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why.
+	const command = validateCommand(run, at, path, { onType: "pull_request" });
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`${at}: pull_request trigger run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
@@ -655,7 +748,7 @@ function normalizePullRequest(on, run, index, path) {
 			all: predicate.all,
 			none: predicate.none,
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }) },
 	};
 }
 

package/src/up.mjs

@@ -24,6 +24,7 @@ import { spawn as nodeSpawn } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { connect as netConnect } from "node:net";
 import { join } from "node:path";
+import { egressArmed as egressArmedFn } from "./egress.mjs";
 import { updateEnvFile } from "./env-file.mjs";
 
 // The one image up may ever fetch, and the local name jobs run under. Literal on purpose (not
@@ -63,6 +64,31 @@ const VALKEY_RUN_ARGS = [
 	"yes",
 ];
 
+// deploy/docker-compose.yml's `egress` profile, reproduced as one docker run (REQ-EGRESS-ALLOWLIST):
+// same digest-pinned image, same two mounts, same explicit container name, same restart policy, on the
+// same upstream network. Written out here for the same reason VALKEY_RUN_ARGS is -- an operator who runs
+// `up` and one who runs compose must end up with the same component, and two ways of starting one thing
+// is two places for it to drift.
+//
+// The per-job networks are NOT here: the worker creates one per job and attaches this container to it for
+// the life of that run. This is only the proxy and its way out.
+const EGRESS_NETWORK_ARGS = ["network", "create", "pi-dispatch-egress-out"];
+const EGRESS_RUN_ARGS = [
+	"run",
+	"-d",
+	"--name",
+	"pi-dispatch-egress-proxy",
+	"--restart",
+	"unless-stopped",
+	"--network",
+	"pi-dispatch-egress-out",
+	"-v",
+	"./deploy/egress-proxy.conf:/etc/squid/squid.conf:ro",
+	"-v",
+	"./egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro",
+	"ubuntu/squid@sha256:6a097f68bae708cedbabd6188d68c7e2e7a38cedd05a176e1cc0ba29e3bbe029",
+];
+
 export async function runUp(argv = [], deps = {}) {
 	const {
 		env = process.env,
@@ -173,6 +199,38 @@ export async function runUp(argv = [], deps = {}) {
 		summary.push(["WEBHOOK_SECRET", "no .env here — skipped (set it wherever your env lives)"]);
 	}
 
+	// (e2) the egress policy's proxy, and ONLY when the operator has already armed it. up never invents
+	// operator policy -- the same doctrine that keeps it pulling this repo's own image and no other -- so a
+	// deployment that has not set PI_EGRESS hears nothing about this at all.
+	//
+	// AFTER init, deliberately: init has just scaffolded egress-allowlist.conf, and starting a proxy whose
+	// allowlist file does not exist gets a directory created by docker where a file belonged and a squid
+	// that fails confusingly. If the file is still missing, this step declines itself and says which file.
+	if (egressArmedFn(env)) {
+		if ((await runCmd(spawn, "docker", ["inspect", "--format={{.State.Running}}", "pi-dispatch-egress-proxy"])) === 0) {
+			out("\n✓ Egress proxy already present (pi-dispatch-egress-proxy)\n");
+			summary.push(["egress", "proxy already present — left untouched"]);
+		} else if (!fs.existsSync(join(cwd, "egress-allowlist.conf"))) {
+			out("\n✗ the egress policy is on but egress-allowlist.conf is not here — not starting a proxy with no allowlist\n");
+			summary.push(["egress", "skipped — no egress-allowlist.conf in this folder; run `pi-dispatch init` here, then `up` again"]);
+		} else if (
+			await consent("The egress policy is on (PI_EGRESS=0 opts out) but the allowlist proxy is not running. up would start it (same semantics as deploy/docker-compose.yml --profile egress):", [`docker ${EGRESS_NETWORK_ARGS.join(" ")}`, `docker ${quoteArgs(EGRESS_RUN_ARGS)}`], { yes, out, prompt })
+		) {
+			// The network may already exist from a previous run; that is not a failure, so its code is not
+			// checked. The proxy is what matters and it is checked.
+			await runStreamed(spawn, "docker", EGRESS_NETWORK_ARGS, out);
+			if ((await runStreamed(spawn, "docker", EGRESS_RUN_ARGS, out)) !== 0) {
+				out("✗ could not start the egress proxy — continuing; doctor below will re-check it\n");
+				summary.push(["egress", "start failed — every job refuses pre-spend until it is up (costs no budget, runs nothing)"]);
+			} else {
+				summary.push(["egress", "started pi-dispatch-egress-proxy on pi-dispatch-egress-out"]);
+			}
+		} else {
+			out("skipped — start it later with `docker compose -f deploy/docker-compose.yml --profile egress up -d`\n");
+			summary.push(["egress", "skipped (declined) — every job is refused pre-spend until the proxy is up (PI_EGRESS=0 opts out)"]);
+		}
+	}
+
 	// (f) doctor — always, verbatim: up converges what it can, doctor is the judge of what remains
 	// (provider key, forge env, overlay …), and its verdict is up's exit code.
 	out("\ndoctor:\n");