@edgehero/pi-dispatch 1.0.0 → 1.2.0

package/src/processor.mjs

@@ -41,7 +41,10 @@ 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 }),
-		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
+		// 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, context }) => { 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.
 		promoteSession = () => null,
@@ -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
@@ -308,7 +351,7 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: budget.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
 		}
 
-		const { code, aborted, turns, tokens, session, usage } = await runContainer({ job, token, prepared });
+		const { code, aborted, turns, tokens, session, usage, context } = await runContainer({ job, token, prepared });
 		log("container_exit", { exitCode: code, aborted });
 
 		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
@@ -345,7 +388,7 @@ export async function runJob(job, deps) {
 				// (CONST-RETRY-INFRA-ONLY). Same completed-only rule INT-OUTBOX-CONTRACT already uses, and
 				// it sits beside the chain collection for the same reason: both must happen before the
 				// `finally` deletes jobDir. Never throws.
-				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion }) : null;
+				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context }) : null;
 				return {
 					outcome: "completed",
 					exitCode: code,
@@ -412,7 +455,8 @@ export async function runJob(job, deps) {
  * and with one number alone it is indistinguishable from an ordinary cold start.
  *
  * The runner's verdict WINS on `resumed`, because it is the one that observed the outcome. The host's
- * reason is kept when the runner has none to give (a container that died before its exit line).
+ * reason is kept when the runner has none to give (a container that died before its exit line), AND when
+ * the host itself refused -- see the second precedence rule below.
  *
  * PII-free by construction: a boolean, a fixed enum, an integer. The key and the branch name are
  * deliberately absent -- this record holds no attacker-chosen string, and a branch name is one.
@@ -420,12 +464,30 @@ export async function runJob(job, deps) {
 function mergeSession(prepared, fromRunner, promoted = null) {
 	const host = prepared?.session;
 	if (!host && !fromRunner) return null;
+	// A HOST GATE THAT REFUSED OUTRANKS THE RUNNER'S `absent`, and without this rule it never reached a
+	// record at all. A refused read stages a 0-byte file rather than nothing (session-store.mjs, where the
+	// reasoning is pi's EEXIST race), the container is handed that file either way, and pi opens it and
+	// finds no messages -- so the runner reports `absent` on EVERY host refusal. Letting that win overwrote
+	// the answer with a restatement of the question: `expired` and `pi-version-changed` reached no
+	// completed record in the feature's whole life, and `docs/sessions.md`'s promise that every cold start
+	// is nameable in the record was false for them.
+	//
+	// Narrow on purpose, `host.resume === false` and the runner's token exactly `absent`. When the host
+	// DID stage a transcript and the runner still reports `absent`, the two genuinely disagree, and that
+	// disagreement is the event this object exists to show; the runner keeps winning there. So does its
+	// `unparseable`, which reports a degrade the host could not see.
+	const hostRefused = host?.resume === false && typeof host.reason === "string";
 	return {
 		resumed: fromRunner ? fromRunner.resumed : false,
 		// A promotion that was refused is the more useful reason to surface: "locked" or
 		// "not-a-regular-file" says why the NEXT run will cold-start, which is the thing an operator
 		// chasing "it never resumes" needs. It only ever replaces a reason on the completed path.
-		reason: (promoted && !promoted.promoted ? promoted.reason : null) ?? fromRunner?.reason ?? host?.reason ?? null,
+		reason:
+			(promoted && !promoted.promoted ? promoted.reason : null) ??
+			(hostRefused && fromRunner?.reason === "absent" ? host.reason : null) ??
+			fromRunner?.reason ??
+			host?.reason ??
+			null,
 		bytes: promoted?.bytes ?? host?.bytes ?? 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";
@@ -29,7 +30,7 @@ export function makeRunContainer({
 	image, // the DEPLOYMENT default (PI_JOB_IMAGE); a trigger's own run.image overrides it per job
 	hostEnv = process.env,
 	onOutput = (c) => process.stdout.write(c),
-	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null }) }),
+	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null, context: null }) }),
 	spawnFn = spawn,
 	globalPiDir = null, // REQ-GLOBAL-PI-OVERLAY: operator's global pi overlay dir, mounted :ro; null = off
 	allowGlobalExtensions = true, // REQ-GLOBAL-PI-OVERLAY: the staged overlay's extensions load unless PI_GLOBAL_ALLOW_EXTENSIONS=0
@@ -40,11 +41,13 @@ 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.
 	return async function runContainer({ job, token, prepared, name, signal }) {
-		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null }; // killed before it could start
+		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null, context: null }; // killed before it could start
 
 		// Closed env allowlist: only the provider key + the declared PI_* vars. Throws (config) if
 		// the provider is unconfigured -- the processor turns that into a pre-spend refusal.
@@ -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) => {
@@ -125,21 +147,35 @@ export function makeRunContainer({
 			});
 			child.on("close", async (code) => {
 				const aborted = signal?.aborted === true; // capture BEFORE the await
-				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage fall back to null.
+				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage/context fall back to null.
 				let turns = null;
 				let tokens = null;
 				let session = null;
 				let usage = null;
+				let context = null;
 				try {
-					({ turns, tokens, session, usage } = await sink.close());
+					// `context = null` is a DEFAULT rather than a plain destructure: an injected sink that
+					// predates the field returns no such key, and `undefined` would then reach the record's
+					// shape where every other absence is spelled `null`.
+					({ turns, tokens, session, usage, context = null } = await sink.close());
 				} catch {
 					turns = null;
 					tokens = null;
 					session = null;
 					usage = null;
+					context = null;
 				}
-				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
+				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage, context } : { code: code ?? 1, aborted: false, turns, tokens, session, usage, context });
 			});
 		});
+
+		// 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

@@ -110,6 +110,43 @@ export function parseExitSession(text) {
 	return null;
 }
 
+/**
+ * The container's report of how full its context was when the run ended (issue #186). Shaped exactly
+ * like `parseExitSession` above and, like it, PASSED THROUGH rather than rebuilt: both integers are
+ * host-bounded numbers, so `parseExitUsage`'s revalidating rebuild is not what this needs -- that one
+ * exists because the ledger carries id STRINGS.
+ *
+ * Absent means ABSENT, never zero. A runner predating this field, a run pi could give no context window
+ * for, and a compaction that left the count unknown all produce no key at all, and the session store
+ * reads that as "no measurement" and passes rather than inventing a denominator.
+ */
+export function parseExitContext(text) {
+	if (typeof text !== "string") return null;
+	const lines = text.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue; // docker/agent noise or a truncated final line
+		}
+		if (parsed?.event !== "exit") continue;
+		const c = parsed?.context;
+		// A window of 0 is not a denominator, and a negative count is not a measurement. SAFE integers
+		// specifically: `Number.isInteger` accepts up to ~1.8e308, and anything from 1e21 up stringifies to
+		// exponential notation, which the session store's own decimal round-trip then rejects on read --
+		// so a value in that range would be written into the store and be unreadable forever after, with
+		// the gate failing open on a measurement that said the context was full.
+		if (c && typeof c === "object" && !Array.isArray(c) && Number.isSafeInteger(c.tokens) && Number.isSafeInteger(c.window) && c.tokens >= 0 && c.window > 0) {
+			return { tokens: c.tokens, window: c.window };
+		}
+		return null;
+	}
+	return null;
+}
+
 export function parseExitTokens(text) {
 	if (typeof text !== "string") return null;
 	const lines = text.split("\n");
@@ -246,7 +283,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.
  */
@@ -389,11 +426,12 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 		}
 
 		async function close({ timeoutMs = 2000 } = {}) {
-			// Capture turns/tokens/session/usage from the tail first, so they survive even if the flush errors or times out.
+			// Capture turns/tokens/session/usage/context from the tail first, so they survive even if the flush errors or times out.
 			const turns = parseExitTurns(tail);
 			const tokens = parseExitTokens(tail);
 			const session = parseExitSession(tail);
 			const usage = parseExitUsage(tail);
+			const context = parseExitContext(tail);
 			try {
 				if (stream !== null) {
 					const s = stream;
@@ -417,7 +455,7 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 			} catch (err) {
 				log("log_sink_error", { jobId, reason: err?.message });
 			}
-			return { turns, tokens, session, usage };
+			return { turns, tokens, session, usage, context };
 		}
 
 		return { write, close };

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