@agimon-ai/po-sandbox 0.0.0-alpha.0

package/dist/cockpitHarness.mjs

@@ -0,0 +1,594 @@
+import { a as BROKER_PROVIDERS_ENV, i as BROKER_PORT_ENV, n as BROKER_CONTAINER_PORT, o as BROKER_SOCKET_CONTAINER_PATH, r as BROKER_HOST_GATEWAY, s as BROKER_SOCKET_ENV, t as BROKER_ADDRESS_ENV } from "./sandboxBridge-77zC5pQR.mjs";
+import { execFileSync, spawn } from "node:child_process";
+import { PO_SANDBOX_ENV } from "@agimon-ai/po-core/sandboxHarness";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { createHash } from "node:crypto";
+//#region src/services/oauthCallback/index.ts
+const OAUTH_CALLBACK_HOST_ENV = "PI_OAUTH_CALLBACK_HOST";
+/**
+* Address the in-container callback server binds.
+*
+* Pi binds loopback by default, which a published port cannot reach: the
+* engine forwards to the container's external interface, not its loopback.
+* Only the bind address changes; the redirect the provider sees stays
+* `localhost`.
+*/
+const OAUTH_CONTAINER_BIND = "0.0.0.0";
+//#endregion
+//#region src/services/sandboxEnvironment/index.ts
+const EXACT_NAMES = /* @__PURE__ */ new Set([
+	"TERM",
+	"COLORTERM",
+	"LANG",
+	"TZ",
+	"PO_PRESET",
+	"ELICITATION_SESSION_ID",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy"
+]);
+const NAME_PREFIXES = ["LC_"];
+const NAME_SUFFIXES = [
+	"_API_KEY",
+	"_AUTH_TOKEN",
+	"_BASE_URL"
+];
+/** True for variables shaped like a provider credential or endpoint override. */
+function isCredentialEnvName(name) {
+	return NAME_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+function allowed(name) {
+	return EXACT_NAMES.has(name) || NAME_PREFIXES.some((prefix) => name.startsWith(prefix)) || NAME_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+* Projects the host environment down to what a sandboxed session may see.
+*
+* The list is an allowlist on purpose: everything a terminal accumulates
+* (agents, sockets, tokens, paths) stays on the host unless a rule names it.
+* Provider credentials pass through for now; the credential broker planned for
+* the client-server phase removes even those from the container.
+*/
+function filterSandboxEnvironment(environment) {
+	const filtered = {};
+	for (const [name, value] of Object.entries(environment)) if (value !== void 0 && allowed(name)) filtered[name] = value;
+	return filtered;
+}
+//#endregion
+//#region src/services/containerEnvironment/index.ts
+const ENABLED = "1";
+/**
+* Replaces every credential in the container with the broker's session token.
+*
+* Dropping all credential-shaped variables first is what makes the promise
+* hold for providers the broker does not carry: an unbrokered key would
+* otherwise stay readable inside the container.
+*/
+function brokeredEnvironment(filtered, broker) {
+	const environment = {};
+	for (const [name, value] of Object.entries(filtered)) if (!isCredentialEnvName(name)) environment[name] = value;
+	for (const name of broker.withheldEnv) environment[name] = broker.token;
+	if (broker.endpoint.transport === "unix") {
+		environment[BROKER_SOCKET_ENV] = BROKER_SOCKET_CONTAINER_PATH;
+		environment[BROKER_PORT_ENV] = String(BROKER_CONTAINER_PORT);
+	} else environment[BROKER_ADDRESS_ENV] = `${BROKER_HOST_GATEWAY}:${broker.endpoint.port}`;
+	environment[BROKER_PROVIDERS_ENV] = broker.providers.join(",");
+	return environment;
+}
+/**
+* The environment a sandboxed session runs with: the allowlisted host
+* variables, with every credential substituted by the broker token.
+*/
+function containerEnvironment(environment, broker, loginPorts = []) {
+	const filtered = filterSandboxEnvironment(environment);
+	const resolved = broker ? brokeredEnvironment(filtered, broker) : filtered;
+	resolved[PO_SANDBOX_ENV] = ENABLED;
+	if (loginPorts.length > 0) resolved[OAUTH_CALLBACK_HOST_ENV] = OAUTH_CONTAINER_BIND;
+	return resolved;
+}
+//#endregion
+//#region src/services/devcontainer/index.ts
+const DEVCONTAINER_DISABLED_ENV = "PO_SANDBOX_DEVCONTAINER";
+//#endregion
+//#region src/services/cockpitPlan/index.ts
+/**
+* Projects the cockpit into one detached engine run.
+*
+* Unlike a disposable container wrapped around a single interactive session,
+* this plan describes a long-lived container holding
+* the hub and every session it goes on to spawn, which changes four things:
+* it is detached rather than attached, it publishes a port rather than only
+* consuming them, its home volume is scoped to the cockpit rather than to one
+* repository, and it mounts a set of workspaces rather than a single repo.
+*/
+const CONTAINER_HOME = "/po-home";
+/**
+* One volume for the cockpit, not one per repository.
+*
+* A cockpit spans several workspaces, so there is no repository to key on. This
+* is also where `~/.po/web` lands, which is what makes paired passkeys and
+* the bundle signing key survive a container restart. A rotated signing key
+* would make every paired device refuse the cockpit, so the name must be
+* stable.
+*/
+const COCKPIT_HOME_VOLUME = "po-cockpit-home";
+const COCKPIT_LABEL = "po.cockpit";
+const COCKPIT_BINARY = "po-web";
+const LOOPBACK = "127.0.0.1";
+/**
+* The cockpit binds every interface inside the container.
+*
+* A published port reaches the container's external interface, never its
+* loopback, which is the same reason `oauthCallback.ts` sets its own bind
+* address. The host side of the publish is pinned to loopback, so this is not
+* exposed beyond the machine.
+*/
+const CONTAINER_BIND = "0.0.0.0";
+const LINUX_PLATFORM = "linux";
+const DISABLED = "0";
+/**
+* Git identity, passed as environment rather than by mounting a config.
+*
+* The agent can commit; it cannot push, because no key crosses the boundary.
+* Mounting `~/.gitconfig` would drag in whatever else it configures, and
+* forwarding an ssh agent would hand the container a live credential that
+* authenticates as the user everywhere their key reaches.
+*/
+function gitIdentityEnvironment(identity) {
+	if (identity === void 0) return {};
+	return {
+		GIT_AUTHOR_NAME: identity.name,
+		GIT_AUTHOR_EMAIL: identity.email,
+		GIT_COMMITTER_NAME: identity.name,
+		GIT_COMMITTER_EMAIL: identity.email
+	};
+}
+function buildCockpitPlan(input) {
+	const { engine, host, broker, imageTag, port } = input;
+	if (input.workspaces.length === 0) throw new Error("A cockpit container needs at least one workspace to mount.");
+	const environment = {
+		...containerEnvironment(input.environment, broker),
+		...gitIdentityEnvironment(input.gitIdentity),
+		[DEVCONTAINER_DISABLED_ENV]: DISABLED,
+		[PO_SANDBOX_ENV]: "1"
+	};
+	const environmentPairs = Object.entries(environment).sort(([left], [right]) => left.localeCompare(right));
+	return {
+		imageTag,
+		runArgs: [
+			"run",
+			"-d",
+			"--label",
+			`${COCKPIT_LABEL}=${String(port)}`,
+			"-p",
+			`${LOOPBACK}:${String(port)}:${String(port)}`,
+			...input.workspaces.flatMap((workspace) => ["-v", `${workspace.path}:${workspace.path}`]),
+			"-v",
+			`${COCKPIT_HOME_VOLUME}:${CONTAINER_HOME}`,
+			...broker?.endpoint.transport === "tcp" ? ["--add-host", `host.docker.internal:host-gateway`] : [],
+			...broker?.endpoint.transport === "unix" ? ["-v", `${broker.endpoint.socketDirectory}:/run/po`] : [],
+			"-w",
+			input.workspaces[0]?.path ?? CONTAINER_HOME,
+			"-e",
+			`HOME=${CONTAINER_HOME}`,
+			...environmentPairs.flatMap(([name, value]) => ["-e", `${name}=${value}`]),
+			...host.platform === LINUX_PLATFORM && host.userId !== void 0 ? [
+				"--user",
+				`${String(host.userId)}:${String(host.groupId ?? host.userId)}`,
+				...engine === "podman" ? ["--userns=keep-id"] : []
+			] : [],
+			...input.runFlags ?? [],
+			imageTag,
+			COCKPIT_BINARY,
+			"--host",
+			CONTAINER_BIND,
+			"--port",
+			String(port)
+		]
+	};
+}
+//#endregion
+//#region src/services/engineProcess/index.ts
+const INHERIT = "inherit";
+const PIPE = "pipe";
+const IGNORE = "ignore";
+const FORWARDED_SIGNALS = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGHUP"
+];
+/** Spawns the container engine, keeping the session's terminal attached. */
+var SpawnEngineProcessRunner = class {
+	run(command, args, options = {}) {
+		return new Promise((resolve, reject) => {
+			const child = spawn(command, args, { stdio: options.input === void 0 ? INHERIT : [
+				PIPE,
+				INHERIT,
+				INHERIT
+			] });
+			if (options.input !== void 0) child.stdin?.end(options.input);
+			const forwarders = FORWARDED_SIGNALS.map((signal) => {
+				const forward = () => {
+					child.kill(signal);
+				};
+				process.on(signal, forward);
+				return {
+					signal,
+					forward
+				};
+			});
+			const cleanup = () => {
+				for (const { signal, forward } of forwarders) process.off(signal, forward);
+			};
+			child.once("error", (error) => {
+				cleanup();
+				reject(error);
+			});
+			child.once("exit", (code, signal) => {
+				cleanup();
+				resolve(code ?? (signal ? 1 : 0));
+			});
+		});
+	}
+	capture(command, args) {
+		return new Promise((resolve) => {
+			const child = spawn(command, args, { stdio: [
+				IGNORE,
+				PIPE,
+				IGNORE
+			] });
+			let stdout = "";
+			child.stdout?.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.once("error", () => {
+				resolve(void 0);
+			});
+			child.once("exit", (code) => {
+				resolve({
+					exitCode: code ?? 1,
+					stdout
+				});
+			});
+		});
+	}
+};
+//#endregion
+//#region src/services/harness/index.ts
+const ENGINE_ENV = "PO_SANDBOX_ENGINE";
+const ENGINES = [
+	"docker",
+	"podman",
+	"nerdctl",
+	"finch"
+];
+const DOCKERFILE_NAME = "Dockerfile";
+async function detectEngine(runner, environment) {
+	const configured = environment[ENGINE_ENV]?.trim();
+	if (configured) {
+		if (ENGINES.includes(configured)) return configured;
+		throw new Error(`${ENGINE_ENV} must be one of: ${ENGINES.join(", ")}.`);
+	}
+	for (const engine of ENGINES) if ((await runner.capture(engine, ["--version"]))?.exitCode === 0) return engine;
+	throw new Error(`No container engine found. Install one of ${ENGINES.join(", ")}, or set ${ENGINE_ENV}.`);
+}
+/**
+* Builds the image if the engine does not already have it.
+*
+* Takes its definition rather than assuming one, because the interactive
+* sandbox and the cockpit container are two different images built the same
+* way. The tag already carries a digest of the definition, so a changed
+* Dockerfile misses the inspect and rebuilds.
+*/
+async function ensureImage(runner, engine, version, onProgress, definition) {
+	const tag = definition.tag;
+	if ((await runner.capture(engine, [
+		"image",
+		"inspect",
+		tag
+	]))?.exitCode === 0) return tag;
+	onProgress?.(`building ${tag} (first run for this Po version)`);
+	const context = fs.mkdtempSync(path.join(os.tmpdir(), "po-sandbox-build-"));
+	try {
+		fs.writeFileSync(path.join(context, DOCKERFILE_NAME), definition.dockerfile);
+		for (const [name, contents] of Object.entries(definition.files ?? {})) fs.writeFileSync(path.join(context, name), contents);
+		const exitCode = await runner.run(engine, [
+			"build",
+			"-t",
+			tag,
+			"--build-arg",
+			`PO_VERSION=${version}`,
+			context
+		]);
+		if (exitCode !== 0) throw new Error(`Building the ${tag} image failed with exit code ${exitCode}.`);
+	} finally {
+		fs.rmSync(context, {
+			recursive: true,
+			force: true
+		});
+	}
+	return tag;
+}
+//#endregion
+//#region src/services/runFlags/index.ts
+/**
+* Splits configured engine options into argv entries.
+*
+* Whitespace separated rather than shell parsed: the engine is spawned without
+* a shell, so quoting rules would only invent a syntax the caller does not
+* actually get.
+*/
+function parseRunFlags(configured) {
+	return (configured ?? "").split(/\s+/).filter((flag) => flag.length > 0);
+}
+const OPTION_FORM = /^--?[^\s=]+(=.*)?$/s;
+/**
+* Requires every configured entry to be a self-contained option.
+*
+* Separated values cannot be told from positional arguments without knowing
+* each option's arity, and a stray positional would silently replace the image
+* or its command. Demanding `--flag=value` removes the ambiguity instead of
+* guessing at it.
+*/
+function assertRunFlags(flags, optionName) {
+	const invalid = flags.find((flag) => !OPTION_FORM.test(flag));
+	if (invalid !== void 0) throw new Error(`${optionName} accepts engine options in --flag or --flag=value form; "${invalid}" is neither. Write a value as part of its option, for example --runtime=runsc.`);
+}
+//#endregion
+//#region src/services/sandboxImage/index.ts
+const IMAGE_REPOSITORY = "po-sandbox";
+const TAG_SAFE = /[^A-Za-z0-9_.-]/g;
+/**
+* Names one image build: a distribution version plus its image definition.
+*
+* The digest matters as much as the version. Editing the Dockerfile or the
+* bridge without it would silently reuse a cached image that predates the
+* change.
+*/
+function formatImageTag(version, digest) {
+	return `${IMAGE_REPOSITORY}:v${version.replaceAll(TAG_SAFE, "-")}-${digest}`;
+}
+/**
+* Image for the cockpit container, which holds the hub rather than one session.
+*
+* Kept separate from the sandbox image rather than folded into it. The cockpit
+* needs the web package and a tunnel client, and making every interactive
+* `--sandbox` launch pay for an extra apt repository and a larger download to
+* get them would be a poor trade.
+*
+* Installing `@agimon-ai/po-web` is enough for all three programs: its
+* `@agimon-ai/po` dependency owns both the session server executable and
+* the agent runtime.
+*/
+function cockpitDockerfile() {
+	return [
+		"FROM node:22-bookworm-slim",
+		"RUN apt-get update \\",
+		"  && apt-get install -y --no-install-recommends ca-certificates curl git gnupg nano openssh-client ripgrep \\",
+		"  && rm -rf /var/lib/apt/lists/*",
+		"RUN curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \\",
+		"  -o /usr/share/keyrings/cloudflare-main.gpg \\",
+		" && echo \"deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared bookworm main\" \\",
+		"  > /etc/apt/sources.list.d/cloudflared.list \\",
+		" && apt-get update && apt-get install -y --no-install-recommends cloudflared \\",
+		" && rm -rf /var/lib/apt/lists/*",
+		"ARG PO_VERSION",
+		"RUN npm install -g @agimon-ai/po-web@${PO_VERSION}",
+		"# World-writable so the launch can map any host user id onto it.",
+		"RUN mkdir -m 0777 /po-home",
+		"ENV PO_SANDBOX=1 HOME=/po-home",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/services/sandboxImageTag/index.ts
+const DIGEST_LENGTH = 8;
+/**
+* Tags the cockpit image separately from the sandbox one.
+*
+* Same digest scheme, different definition, so editing either Dockerfile
+* invalidates only its own image.
+*/
+function cockpitImageTag(version) {
+	const digest = createHash("sha256").update(cockpitDockerfile()).digest("hex").slice(0, DIGEST_LENGTH);
+	return formatImageTag(`${version}-cockpit`, digest);
+}
+//#endregion
+//#region src/services/cockpitHarness/index.ts
+/**
+* Runs the cockpit itself in a container, detached, holding the hub and every
+* session it goes on to spawn.
+*
+* The interactive harness next door wraps one session and blocks until it
+* exits. This one returns a handle while the container keeps running, which is
+* why it is a separate entry rather than a flag on the other.
+*/
+const RUN_FLAGS_ENV = "PO_SANDBOX_RUN_FLAGS";
+const READY_TIMEOUT_MS = 6e4;
+const READY_POLL_MS = 250;
+const HUB_ROLE = "hub";
+/**
+* Reads the host's committer identity.
+*
+* Passed into the container as environment rather than by mounting the config,
+* so the agent can commit without any credential crossing the boundary. It
+* cannot push, and that is the intended limit.
+*/
+function readGitIdentity() {
+	const read = (key) => {
+		try {
+			const value = execFileSync("git", [
+				"config",
+				"--global",
+				"--get",
+				key
+			], { encoding: "utf8" }).trim();
+			return value === "" ? void 0 : value;
+		} catch {
+			return;
+		}
+	};
+	const name = read("user.name");
+	const email = read("user.email");
+	return name !== void 0 && email !== void 0 ? {
+		name,
+		email
+	} : void 0;
+}
+/** Answers whether the hub inside the container is serving yet. */
+async function defaultProbe(port) {
+	try {
+		const response = await fetch(`http://127.0.0.1:${String(port)}/api/health`);
+		if (!response.ok) return false;
+		return (await response.json()).role === HUB_ROLE;
+	} catch {
+		return false;
+	}
+}
+async function stopContainer(runner, engine, id) {
+	const stopped = await runner.capture(engine, ["stop", id]);
+	await runner.capture(engine, [
+		"rm",
+		"-f",
+		id
+	]);
+	return stopped?.exitCode === 0;
+}
+/**
+* Whether the engine still reports this container as running.
+*
+* A removed container makes `inspect` fail rather than print `false`, so a
+* non-zero exit is read the same way: not running.
+*/
+async function isRunning(runner, engine, id) {
+	const probed = await runner.capture(engine, [
+		"inspect",
+		"-f",
+		"{{.State.Running}}",
+		id
+	]);
+	return probed?.exitCode === 0 && probed.stdout.trim() === "true";
+}
+function createCockpitHarness(dependencies = {}) {
+	const runner = dependencies.runner ?? new SpawnEngineProcessRunner();
+	const probe = dependencies.probe ?? defaultProbe;
+	const readIdentity = dependencies.gitIdentity ?? readGitIdentity;
+	const now = dependencies.now ?? (() => Date.now());
+	return {
+		async startCockpitContainer(request) {
+			if (request.workspaces.length === 0) return {
+				ok: false,
+				error: "A cockpit container needs at least one workspace to mount."
+			};
+			let engine;
+			try {
+				engine = await detectEngine(runner, request.environment);
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+			const runFlags = parseRunFlags(request.environment[RUN_FLAGS_ENV]);
+			try {
+				assertRunFlags(runFlags, RUN_FLAGS_ENV);
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+			request.onProgress?.(`using ${engine}${runFlags.length > 0 ? ` with ${runFlags.join(" ")}` : ""}`);
+			const version = dependencies.version ?? "0.0.0";
+			let imageTag;
+			try {
+				imageTag = await ensureImage(runner, engine, version, request.onProgress, {
+					tag: cockpitImageTag(version),
+					dockerfile: cockpitDockerfile()
+				});
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+			const plan = buildCockpitPlan({
+				workspaces: request.workspaces,
+				port: request.port,
+				environment: request.environment,
+				engine,
+				host: {
+					hasTty: false,
+					platform: process.platform,
+					repoKey: "",
+					version
+				},
+				imageTag,
+				runFlags,
+				...readIdentity() === void 0 ? {} : { gitIdentity: readIdentity() }
+			});
+			const started = await runner.capture(engine, plan.runArgs);
+			const containerId = started?.stdout.trim().split("\n").pop() ?? "";
+			if (started?.exitCode !== 0 || containerId === "") return {
+				ok: false,
+				error: `The cockpit container did not start: ${started?.stdout.trim() ?? "no output"}`
+			};
+			request.onProgress?.("waiting for the cockpit to answer");
+			const deadline = now() + READY_TIMEOUT_MS;
+			for (;;) {
+				if (await probe(request.port)) break;
+				if (now() >= deadline) {
+					const logs = await runner.capture(engine, [
+						"logs",
+						"--tail",
+						"20",
+						containerId
+					]);
+					await stopContainer(runner, engine, containerId);
+					return {
+						ok: false,
+						error: `The cockpit did not answer within ${String(READY_TIMEOUT_MS / 1e3)}s.\n${logs?.stdout ?? ""}`.trim()
+					};
+				}
+				await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS));
+			}
+			return {
+				ok: true,
+				handle: {
+					containerId,
+					stop: async () => {
+						await stopContainer(runner, engine, containerId);
+					},
+					alive: async () => await isRunning(runner, engine, containerId)
+				}
+			};
+		},
+		async reapCockpitContainer(containerId) {
+			for (const engine of [
+				"docker",
+				"podman",
+				"nerdctl",
+				"finch"
+			]) {
+				if ((await runner.capture(engine, ["--version"]))?.exitCode !== 0) continue;
+				return await stopContainer(runner, engine, containerId);
+			}
+			return false;
+		}
+	};
+}
+/** The module-shaped entry a host resolves from the composition. */
+async function startCockpitContainer(request) {
+	return await createCockpitHarness().startCockpitContainer(request);
+}
+async function reapCockpitContainer(containerId) {
+	return await createCockpitHarness().reapCockpitContainer(containerId);
+}
+//#endregion
+export { createCockpitHarness, reapCockpitContainer, startCockpitContainer };
+
+//# sourceMappingURL=cockpitHarness.mjs.map