feat(coding-agent): add sandbox-backed session foundations

packages/coding-agent/.changes/res-1264-sandbox-backed-sessions.md

@@ -0,0 +1 @@
+- Added the durable lifecycle, transport, journal, command, provider, messaging, observation, and workspace-codec foundations for sandbox-backed Prime Agent sessions. Hosted capability advertisement remains gated until the complete runtime composition and end-to-end cleanup checks are ready.

packages/coding-agent/package.json

@@ -69,6 +69,7 @@
 		"typebox": "^1.3.9",
 		"undici": "^7.29.0",
 		"uuid": "^14.0.0",
+		"ws": "^8.18.0",
 		"yaml": "^2.9.0"
 	},
 	"overrides": {
@@ -86,6 +87,7 @@
 		"@types/ms": "^2.1.0",
 		"@types/node": "^24.3.0",
 		"@types/proper-lockfile": "^4.1.4",
+		"@types/ws": "^8.18.1",
 		"esbuild": "^0.28.1",
 		"shx": "^0.4.0",
 		"typescript": "^7.0.2",

packages/coding-agent/src/cli.ts

@@ -1,15 +1,40 @@
 #!/usr/bin/env node
-// The Node 22+ module graph fails at link time on older Node, so it must load
-// behind the dynamic import, after the dependency-free guard runs.
+// ---- Pre-guard static runtime dispatch -------------------------------------
+// Runs BEFORE the Node version guard and heavy imports.  Only static imports
+// and synchronous parsing — no dynamic import(), no async, no I/O.
+// The Node 22+ module graph fails at link time on older Node, so the heavy
+// import("./cli-main.js") is inside the version guard.  The version check
+// and dispatch parser are simple enough to parse on any Node that can import
+// ESM (Node >= 16).
 import { assertNodeVersion } from "./cli/node-version-check.js";
+import { detectReservedArgv } from "./cli/sandbox-runtime-dispatch.js";
 
-const supported = assertNodeVersion({
-	version: process.versions.node,
-	log: console.error,
-	exit: (code) => process.exit(code),
-});
+const dispatchResult = detectReservedArgv(process.argv.slice(2));
+if (dispatchResult.handed) {
+	// Dispatch consumed the flag.  Set exit code and exit without running
+	// normal startup.  Do NOT call process.exit() — let the event loop drain
+	// naturally so any pending microtasks or promise reactions settle.
+	process.exitCode = dispatchResult.exitCode;
+} else {
+	// Normal startup path — Node version guard then heavy imports.
+	await runNormalStartup();
+}
+
+// =============================================================================
+// Normal startup function
+// =============================================================================
+
+async function runNormalStartup(): Promise<void> {
+	const supported = assertNodeVersion({
+		version: process.versions.node,
+		log: console.error,
+		exit: (code) => {
+			process.exitCode = code;
+		},
+	});
 
-if (supported) {
-	const { runCli } = await import("./cli-main.js");
-	await runCli();
+	if (supported) {
+		const { runCli } = await import("./cli-main.js");
+		await runCli();
+	}
 }

packages/coding-agent/src/cli/command-registry.ts

@@ -218,6 +218,8 @@ const TOP_LEVEL_OPTION_GROUPS: ReadonlyArray<{ heading: string; options: readonl
 			["--no-session", "Do not save the session"],
 			["--goal <objective>", "Seed a persistent goal for a new root session"],
 			["--goal-token-budget <n>", "Set a positive token budget for --goal"],
+			["--sandbox", "Create the session in a Prime Sandbox"],
+			["--sandbox-options <json>", "JSON options (region only) for the sandbox"],
 		],
 	},
 	{

packages/coding-agent/src/cli/daemon-command.ts

@@ -10,7 +10,8 @@ import type { AgentSessionRuntimeConfig } from "../core/agent-session-config.js"
 import { type AgentCronJob, formatAgentCronJob } from "../core/cron-jobs.js";
 import { looksLikeSessionPath } from "../core/session-resolver.js";
 import { DaemonClient, type DaemonClientMessageListener } from "../modes/daemon/daemon-client.js";
-import type { DaemonOutbound, DaemonResponse } from "../modes/daemon/daemon-protocol.js";
+import type { DaemonOutbound, DaemonResponse, SandboxOptions } from "../modes/daemon/daemon-protocol.js";
+import { normalizeSandboxOptions } from "../modes/daemon/daemon-protocol.js";
 import { matchesSessionIdSuffix } from "../modes/daemon/daemon-session-id.js";
 import type { SessionSummary } from "../modes/daemon/daemon-session-list.js";
 import { defaultDaemonSocketPath, normalizeSocketPath } from "../modes/daemon/daemon-socket.js";
@@ -284,6 +285,8 @@ async function runOpen(parsed: ParsedDaemonClientCommand): Promise<void> {
 				config: sessionArgs.config,
 				sessionPath: sessionArgs.sessionPath,
 				continueRecent: sessionArgs.continueRecent,
+				sandbox: sessionArgs.sandbox,
+				sandboxOptions: sessionArgs.sandboxOptions,
 			});
 			if (response.success || !autoName || !response.error.includes(`Agent name "${sessionName}" is unavailable`)) {
 				break;
@@ -307,6 +310,8 @@ interface ParsedSessionArgs {
 	config?: AgentSessionRuntimeConfig;
 	sessionPath?: string;
 	continueRecent?: boolean;
+	sandbox?: boolean;
+	sandboxOptions?: SandboxOptions;
 }
 
 const SESSION_BOOLEAN_FLAGS = new Set([
@@ -341,6 +346,8 @@ function parseSessionArgs(args: string[]): ParsedSessionArgs {
 	const pathBaseCwd = findSessionCwdArg(args) ?? process.cwd();
 	let sessionPath: string | undefined;
 	let continueRecent: boolean | undefined;
+	let sandbox: boolean | undefined;
+	let sandboxOptions: SandboxOptions | undefined;
 
 	for (let index = 0; index < args.length; index++) {
 		const arg = args[index];
@@ -383,6 +390,12 @@ function parseSessionArgs(args: string[]): ParsedSessionArgs {
 			if (parsedOption.continueRecent !== undefined) {
 				continueRecent = parsedOption.continueRecent;
 			}
+			if (parsedOption.sandbox !== undefined) {
+				sandbox = parsedOption.sandbox;
+			}
+			if (parsedOption.sandboxOptions !== undefined) {
+				sandboxOptions = parsedOption.sandboxOptions;
+			}
 			index += parsedOption.consumed;
 			continue;
 		}
@@ -401,6 +414,8 @@ function parseSessionArgs(args: string[]): ParsedSessionArgs {
 		config: Object.keys(config).length > 0 ? config : undefined,
 		sessionPath,
 		continueRecent,
+		sandbox,
+		sandboxOptions: sandboxOptions && Object.keys(sandboxOptions).length > 0 ? sandboxOptions : undefined,
 	};
 }
 
@@ -410,6 +425,8 @@ interface ParsedSessionOption {
 	value?: string;
 	sessionPath?: string;
 	continueRecent?: boolean;
+	sandbox?: boolean;
+	sandboxOptions?: SandboxOptions;
 }
 
 function parseSessionOption(
@@ -566,6 +583,22 @@ function parseSessionOption(
 			// Session-specific flag: do NOT propagate to daemon startup args.
 			return { consumed: 1 };
 		}
+		case "--sandbox":
+			return { consumed: 0, sandbox: true };
+		case "--sandbox-options": {
+			const value = readValue();
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(value);
+			} catch {
+				throw new Error("--sandbox-options must be valid JSON");
+			}
+			const normalised = normalizeSandboxOptions(parsed);
+			if (!normalised) {
+				throw new Error("--sandbox-options contains invalid fields");
+			}
+			return { consumed: 1, sandboxOptions: normalised };
+		}
 		case "--foreground":
 		case "--no-detach":
 		case "--background":
@@ -782,6 +815,8 @@ async function runCreate(client: DaemonClient, args: string[], json: boolean): P
 		config: sessionArgs.config,
 		sessionPath: sessionArgs.sessionPath,
 		continueRecent: sessionArgs.continueRecent,
+		sandbox: sessionArgs.sandbox,
+		sandboxOptions: sessionArgs.sandboxOptions,
 	});
 	const data = requireSuccess(response);
 	if (json) {

packages/coding-agent/src/cli/sandbox-runtime-dispatch.ts

@@ -0,0 +1,99 @@
+/**
+ * Static early CLI dispatch for B14 runtime modes.
+ *
+ * Detects the two reserved flags BEFORE normal config/UI/provider/plugin
+ * startup.  Static imports only — no dynamic/inline imports, no `any`,
+ * no sync fs, no shell, no resources.
+ *
+ * Only argv[0] is checked.  A standalone "--" at argv[0] passes through.
+ * If argv[0] IS a reserved flag, dispatch ALWAYS hands it — the process
+ * never enters normal provider/UI startup.  Extra trailing arguments still
+ * hand (INVALID_RUNTIME_ARGUMENTS) rather than passing through.
+ * Appearances of a reserved flag at argv[1+] are never intercepted.
+ *
+ * Without production orchestration (launcher/publisher/relay host) both
+ * modes fail closed with ORCHESTRATION_UNAVAILABLE. No sandbox_sessions
+ * support is advertised.
+ *
+ * The dispatch function never calls process.exit() — that is the caller's
+ * responsibility.  The CLI may set exitCode 1 without logging secrets.
+ *
+ * No dynamic/inline imports, no `any`, no sync FS, no shell, no
+ * caller-controlled paths or dependencies.
+ */
+
+import { parseSandboxBootstrapMode } from "../core/sandbox-fd3-bootstrap-mode.js";
+
+// ---------------------------------------------------------------------------
+// Flags
+// ---------------------------------------------------------------------------
+
+const WRAPPER_FLAG = "--prime-agent-fd3-bootstrap";
+const RUNTIME_FLAG = "--prime-agent-runtime-fd3";
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export type RuntimeDispatchExitCode = 1;
+
+export type RuntimeDispatchCode = "ORCHESTRATION_UNAVAILABLE" | "INVALID_RUNTIME_ARGUMENTS";
+
+export type RuntimeDispatchResult =
+	/** Neither reserved flag was present — continue with normal startup. */
+	| Readonly<{ ok: false; handed: false }>
+	/** Dispatch handled the flag and the process should exit with the given code. */
+	| Readonly<{ ok: true; handed: true; code: RuntimeDispatchCode; exitCode: RuntimeDispatchExitCode }>;
+
+// ---------------------------------------------------------------------------
+// Detect reserved flag at argv[0]
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether argv[0] is a reserved runtime flag.
+ *
+ * If argv[0] IS a reserved flag the result is ALWAYS handed: the process
+ * must never pass through to normal provider/UI startup.  A valid exact
+ * 3-element form returns ORCHESTRATION_UNAVAILABLE; any other form returns
+ * INVALID_RUNTIME_ARGUMENTS.  Both use exitCode 1.
+ *
+ * Only argv[0] is checked — the normal argument position that replaces the
+ * default CLI command.  A standalone "--" at argv[0] passes through.
+ * Reserved flags at argv[1+] pass through (normal arguments).
+ *
+ * This is synchronous (pure parse) and never calls process.exit().
+ */
+export function detectReservedArgv(argv: readonly string[]): RuntimeDispatchResult {
+	// Empty argv or standalone "--" separator — pass through.
+	if (argv.length < 1 || argv[0] === "--") {
+		return Object.freeze({ ok: false as const, handed: false as const });
+	}
+
+	// Not a recognised reserved flag — pass through.
+	if (argv[0] !== WRAPPER_FLAG && argv[0] !== RUNTIME_FLAG) {
+		return Object.freeze({ ok: false as const, handed: false as const });
+	}
+
+	// argv[0] IS a reserved flag — always hand.
+	// Pass the full argv to the accepted mode parser.
+	const raw = parseSandboxBootstrapMode(argv);
+
+	if (raw.ok) {
+		// Flag, --ready-nonce, and hex are all valid.
+		// Without hosted orchestration, fail closed.
+		return Object.freeze({
+			ok: true as const,
+			handed: true as const,
+			code: "ORCHESTRATION_UNAVAILABLE" as const,
+			exitCode: 1 as const,
+		});
+	}
+
+	// Flag recognised but malformed (wrong length, wrong nonce, extras, etc.)
+	return Object.freeze({
+		ok: true as const,
+		handed: true as const,
+		code: "INVALID_RUNTIME_ARGUMENTS" as const,
+		exitCode: 1 as const,
+	});
+}

packages/coding-agent/src/core/agent-messages.ts

@@ -118,6 +118,7 @@ export interface AgentSessionMessagePayload {
 	/** Sender relationship from the receiver's point of view. */
 	fromRelationship?: AgentFamilyRelationship;
 	target: AgentSessionMessageEndpoint;
+	semanticDigest?: string;
 }
 
 export interface AgentSessionMessageDetails {
@@ -126,6 +127,8 @@ export interface AgentSessionMessageDetails {
 	from?: AgentSessionMessageSender;
 	fromRelationship?: AgentFamilyRelationship;
 	target?: AgentSessionMessageEndpoint;
+	/** Canonical SHA-256 digest used for transcript idempotency verification. */
+	semanticDigest?: string;
 }
 
 export interface AgentSessionMessage extends CustomMessage<AgentSessionMessageDetails> {
@@ -409,18 +412,22 @@ export function createAgentSessionMessage(
 	payload: AgentSessionMessagePayload,
 	timestamp = Date.now(),
 ): AgentSessionMessage {
+	const details: AgentSessionMessageDetails = {
+		id: payload.id,
+		message: payload.message,
+		from: payload.from,
+		fromRelationship: payload.fromRelationship,
+		target: payload.target,
+	};
+	if (typeof payload.semanticDigest === "string" && /^[0-9a-f]{64}$/.test(payload.semanticDigest)) {
+		details.semanticDigest = payload.semanticDigest;
+	}
 	return {
 		role: "custom",
 		customType: AGENT_MESSAGE_CUSTOM_TYPE,
 		content: createAgentSessionMessagePrompt(payload),
 		display: true,
-		details: {
-			id: payload.id,
-			message: payload.message,
-			from: payload.from,
-			fromRelationship: payload.fromRelationship,
-			target: payload.target,
-		},
+		details,
 		timestamp,
 	};
 }