@edgehero/pi-dispatch 1.0.0 → 1.1.0

package/src/processor.mjs

@@ -41,6 +41,9 @@ export async function runJob(job, deps) {
 		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
 		// omits it behaves exactly as before -- the container's own failure stays the backstop.
 		imagePreflight = async () => ({ ok: true }),
+		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
+		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
+		egressPreflight = async () => ({ ok: true }),
 		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
@@ -184,6 +187,46 @@ export async function runJob(job, deps) {
 			throw new InfraRetry("docker unavailable, image preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
 		}
 
+		// REQ-EGRESS-ALLOWLIST. The egress policy this deployment claims must be able to serve this job
+		// BEFORE the job costs anything. It is one `docker inspect` when the policy is armed and ZERO spawns
+		// when it is not, so a deployment without one pays nothing at all.
+		//
+		// PLACEMENT, and it is the same ladder the image preflight sits at the top of. A missing proxy blocks
+		// EVERY job of EVERY kind on this host -- like a missing image -- and unlike a missing image it blocks
+		// them EXPENSIVELY: the container starts, the provider is unreachable, the runner exits 1, exit 1 is
+		// the retryable class, `attempts: 2`, and `releaseBudget` refunds only `container-never-started` --
+		// this container started. So each such job spends two job-count slots and buys nothing with either,
+		// and a cron-driven deployment empties its daily cap before anyone reads the first failure. That cost
+		// is what makes this a pre-spend gate rather than a doc: measured at three provider attempts,
+		// `Request timed out.`, exit 1, ~40 seconds, zero tokens (docs/egress.md).
+		//
+		// A RETURN, never a throw (CONST-RETRY-INFRA-ONLY): retrying never makes an absent proxy appear.
+		const egress = await egressPreflight(job);
+		if (egress.proxyMissing || egress.proxyStopped) {
+			const proxy = egress.proxyMissing ?? egress.proxyStopped;
+			const state = egress.proxyMissing ? "is not on this host" : "is not running";
+			await comment(job, `Refused: this deployment runs jobs behind an egress policy and its allowlist proxy "${proxy}" ${state}, so the job could not reach the provider and would burn its budget slot proving it. Start it with \`docker compose -f deploy/docker-compose.yml --profile egress up -d\`, or set PI_EGRESS=0 to run without an egress policy. Not run.`);
+			// The proxy's NAME is operator-authored deployment config, never payload -- the same PII class as
+			// the image ref on the refusal above.
+			log(egress.proxyMissing ? "refused_egress_proxy_missing" : "refused_egress_proxy_stopped", { proxy });
+			return {
+				outcome: "policy",
+				reason: egress.proxyMissing ? "egress-proxy-missing" : "egress-proxy-stopped",
+				exitCode: null,
+				turns: null,
+				tokens: null,
+				provider: job.provider ?? null,
+				model: job.model ?? null,
+				budgetReserved: false, // refused before reserveBudget, so no job-count slot was consumed
+			};
+		}
+		if (egress.unavailable) {
+			// The daemon did not answer, so this is indeterminate rather than a refusal -- the same
+			// determinate/indeterminate split the image preflight draws one gate up, and thrown for the same
+			// reason. Pre-reserve, so the refund below is a no-op and still honest if this gate ever moves.
+			throw new InfraRetry("docker unavailable, egress preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+		}
+
 		// REQ-RESUMABLE-SESSION's one fail-CLOSED case. Everything else in that feature fails OPEN and
 		// NAMES itself -- absent, expired, too-large, unparseable, locked, promote-failed -- because a cold
 		// start is a correct run. This one cannot be: with no `sessionsDir`, resolveSession returns null

package/src/run-container.mjs

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { buildDockerRunArgs, CONTAINER_SESSION_FILE } from "./docker-run.mjs";
+import { createJobNetwork, networkNameFor, removeJobNetwork } from "./egress.mjs";
 import { buildContainerEnv } from "./env-allowlist.mjs";
 import { resolveJobImage } from "./image-preflight.mjs";
 import { InfraRetry } from "./processor.mjs";
@@ -40,6 +41,8 @@ export function makeRunContainer({
 	forwardEnv = [],
 	authFromPi = false, // fall back to ~/.pi/agent/auth.json for the provider key when the env has none
 	forgeHosts = {}, // per-forge self-hosted instance URLs, so a forge CLI in the container talks to the right one
+	egress = false, // REQ-EGRESS-ALLOWLIST: put this job on its own --internal network behind the allowlist proxy
+	egressProxy, // the proxy component attached to that network; undefined = egress.mjs's default name
 }) {
 	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
 	// a rejection, uniformly awaitable by the processor and by tests.
@@ -59,6 +62,8 @@ export function makeRunContainer({
 			forgeKind: job?.kind,
 			forgeHosts,
 			hostEnv,
+			egress, // REQ-EGRESS-ALLOWLIST: emits HTTPS_PROXY/HTTP_PROXY/NO_PROXY/NODE_USE_ENV_PROXY, or nothing
+			egressProxy,
 			allowGlobalExtensions, // REQ-GLOBAL-PI-OVERLAY: false emits the explicit PI_GLOBAL_ALLOW_EXTENSIONS=0 opt-out
 			// REQ-GLOBAL-PI-OVERLAY: the per-job value comes off `job` (like maxTurns), the staged set off
 			// the closure (like allowGlobalExtensions) -- so a trigger can withhold what the operator staged.
@@ -84,6 +89,10 @@ export function makeRunContainer({
 			authFromPi, // source the provider key from pi's auth.json when the env has none
 		});
 
+		// `-net` on this container's own name (egress.mjs). null when no policy is armed, and docker-run's
+		// guard then omits the flag entirely, so the argv is byte-identical to one built before this feature.
+		const network = egress ? networkNameFor(name) : null;
+
 		const args = buildDockerRunArgs({
 			// Same split as packagePaths above: the per-job value off `job`, the deployment value off the closure,
 			// so a trigger can name its own toolchain (INT-TRIGGERS-FILE-CONTRACT). Resolved through the SAME
@@ -99,13 +108,26 @@ export function makeRunContainer({
 			sessionDir: prepared.session?.hostDir,
 			globalPiDir, // undefined/null -> docker-run's guard skips the /opt/pi-global mount
 			name,
+			network, // REQ-EGRESS-ALLOWLIST: null when no policy is armed, and the flag is then absent
 		});
 
+		// REQ-EGRESS-ALLOWLIST. This job's own --internal network, created here rather than at boot because
+		// it holds exactly two endpoints -- this container and the proxy -- and that is what makes job-to-job
+		// traffic structurally impossible rather than merely discouraged. A shared network could not do it:
+		// `enable_icc=false` would block job-to-job AND job-to-proxy, since ICC governs every container pair
+		// on the bridge and the proxy is a container.
+		//
+		// A failure to build it is INFRA, not policy: nothing has been spent, a retry may well succeed, and
+		// `container-never-started` is literally true, so the reservation is given back (processor.mjs).
+		if (network && !(await createJobNetwork(spawnFn, { network, proxy: egressProxy }))) {
+			throw new InfraRetry("container-never-started", { reason: "container-never-started" });
+		}
+
 		// Host-side per-job log sink, teed off `onOutput`. `name` is `pi-job-<jobId>`; the sink
 		// sanitizes internally. No container mount, no env var -- the sink lives on this side only.
 		const sink = openJobLog(name);
 
-		return await new Promise((resolve, reject) => {
+		const run = new Promise((resolve, reject) => {
 			const child = spawnFn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
 			// A throwing sink.write is swallowed so a misbehaving sink cannot break the tee or hang the run.
 			const tee = (chunk) => {
@@ -141,5 +163,14 @@ export function makeRunContainer({
 				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
 			});
 		});
+
+		// The network outlives the container by exactly this `finally`. Best-effort and never throwing: the
+		// container has already exited, its code is the job's answer, and a teardown fault must not rewrite
+		// that answer. What a failure leaves behind is a memberless network, which the boot reaper sweeps.
+		try {
+			return await run;
+		} finally {
+			if (network) await removeJobNetwork(spawnFn, { network, proxy: egressProxy });
+		}
 	};
 }

package/src/run-history.mjs

@@ -246,7 +246,7 @@ function rebuildUsage(u) {
  * path embeds the operator's OS account name.
  *
  * `reason` is a fixed enum passthrough (worker-abort | over-budget | unprotected-branch |
- * runner-policy | job-image-missing | ...), never free-form or payload text. `exitCode`, `turns`, and `budgetReserved`
+ * runner-policy | job-image-missing | egress-proxy-missing | ...), never free-form or payload text. `exitCode`, `turns`, and `budgetReserved`
  * default to `null` when the outcome does not carry them, so the record shape is stable whether or not
  * the source reports those fields.
  */

package/src/sandbox-cli.mjs

@@ -1,6 +1,8 @@
+import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import { loadConfig } from "./config.mjs";
 import { sanitizeJobId } from "./run-history.mjs";
+import { createJobNetwork, egressEnv, networkNameFor, removeJobNetwork } from "./egress.mjs";
 import { buildSandboxRunArgs, launchSandbox, listRunningSandboxes, parsePublish, resolveSandbox, sandboxContainerName } from "./sandbox.mjs";
 import { listSandboxes, pinSandbox } from "./sandbox-store.mjs";
 
@@ -22,6 +24,9 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY),
 		running = listRunningSandboxes,
 		launch = launchSandbox,
+		// The docker spawn used for this session's egress network, seamed like `launch` so the tests never
+		// touch a daemon. Not used when PI_EGRESS=0.
+		spawnNetwork = spawn,
 		now = () => Date.now(),
 	} = deps;
 
@@ -89,6 +94,10 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		else err(`warning: could not pin ${jobId}: ${pinned.reason}\n`);
 	}
 
+	// REQ-EGRESS-ALLOWLIST: this session's own network, exactly like a job's, named off its own container
+	// so the reaper's `pi-job-` filter never touches it -- a worker restart must not tear the network out
+	// from under a shell an operator is sitting in.
+	const network = config.egress ? networkNameFor(resolved.name) : null;
 	const args = buildSandboxRunArgs({
 		image: resolved.manifest.image,
 		name: resolved.name,
@@ -97,15 +106,27 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		publish,
 		term: env.TERM,
 		idleSeconds: config.sandboxIdleMinutes * 60,
+		network,
+		egressEnv: egressEnv({ proxy: config.egressProxy, armed: config.egress }),
 	});
 
 	out(`opening ${resolved.name} — image ${resolved.manifest.image}, workspace ${resolved.manifest.workspace}\n`);
 	out("no credentials are set in this container. exit the shell to dispose of it.\n");
 	if (publish.length > 0) out(`published: ${publish.filter((f) => f !== "-p").join(", ")}\n`);
 
-	const { code, error } = await launch({ args });
-	if (error) return fail(err, `could not start docker: ${error.message}`);
-	return code ?? 0;
+	// No pre-spend gate here, deliberately: that is a MONEY gate and a sandbox spends nothing. A missing
+	// proxy fails at `docker run` with docker's own message, in front of an operator at a terminal, which
+	// is the one place a late failure is cheap.
+	if (network && !(await createJobNetwork(spawnNetwork, { network, proxy: config.egressProxy }))) {
+		return fail(err, `could not create the egress network ${network} -- is the proxy running? \`docker compose -f deploy/docker-compose.yml --profile egress up -d\``);
+	}
+	try {
+		const { code, error } = await launch({ args });
+		if (error) return fail(err, `could not start docker: ${error.message}`);
+		return code ?? 0;
+	} finally {
+		if (network) await removeJobNetwork(spawnNetwork, { network, proxy: config.egressProxy });
+	}
 }
 
 /**

package/src/sandbox.mjs

@@ -79,8 +79,10 @@ function inPortRange(n) {
  * @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
+ * @param network      this session's own egress network (REQ-EGRESS-ALLOWLIST); null = the default bridge
+ * @param egressEnv    the proxy variables that go with it, or {} when no policy is armed
  */
-export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0 }) {
+export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0, network = null, egressEnv: proxyEnv = {} }) {
 	return buildDockerRunArgs({
 		image,
 		name,
@@ -89,9 +91,20 @@ export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish =
 		// 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.
+		// A sandbox joins the SAME kind of network a job did, by the same builder, so the boundary cannot
+		// land on job containers and miss this one. Leaving sandboxes on the default bridge was the tempting
+		// alternative and it is the wrong one: it reads as a convenience (install a missing dependency while
+		// debugging) and it is a WIDER reach than the run the sandbox exists to reproduce. A shell that can
+		// go where the run could not is not reproducing the run. Nothing an operator wants is lost, because
+		// the forge and the registry are on the allowlist a job needed anyway.
+		network,
 		env: {
 			TERM: term || undefined,
 			TMOUT: idleSeconds > 0 ? String(idleSeconds) : undefined,
+			// Still NO CREDENTIALS, and that clause is untouched: a proxy URL is not a credential, and
+			// buildContainerEnv is still not reused here. The env is two variables about the terminal and,
+			// when a policy is armed, three about the network.
+			...proxyEnv,
 		},
 		// 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