@electric-ax/agents-server 0.4.14 → 0.4.15

package/dist/index.cjs

@@ -90,6 +90,7 @@ const entities = (0, drizzle_orm_pg_core.pgTable)(`entities`, {
 	tags: (0, drizzle_orm_pg_core.jsonb)(`tags`).notNull().default({}),
 	tagsIndex: (0, drizzle_orm_pg_core.text)(`tags_index`).array().notNull().default(drizzle_orm.sql`'{}'::text[]`),
 	spawnArgs: (0, drizzle_orm_pg_core.jsonb)(`spawn_args`).default({}),
+	sandbox: (0, drizzle_orm_pg_core.jsonb)(`sandbox`),
 	parent: (0, drizzle_orm_pg_core.text)(`parent`),
 	createdBy: (0, drizzle_orm_pg_core.text)(`created_by`),
 	typeRevision: (0, drizzle_orm_pg_core.integer)(`type_revision`),
@@ -131,6 +132,7 @@ const runners = (0, drizzle_orm_pg_core.pgTable)(`runners`, {
 	kind: (0, drizzle_orm_pg_core.text)(`kind`).notNull().default(`local`),
 	adminStatus: (0, drizzle_orm_pg_core.text)(`admin_status`).notNull().default(`enabled`),
 	wakeStream: (0, drizzle_orm_pg_core.text)(`wake_stream`).notNull(),
+	sandboxProfiles: (0, drizzle_orm_pg_core.jsonb)(`sandbox_profiles`).notNull().default([]),
 	createdAt: (0, drizzle_orm_pg_core.timestamp)(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: (0, drizzle_orm_pg_core.timestamp)(`updated_at`, { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
@@ -428,6 +430,7 @@ function toPublicEntity(entity) {
 		dispatch_policy: entity.dispatch_policy,
 		tags: entity.tags,
 		spawn_args: entity.spawn_args,
+		sandbox: entity.sandbox,
 		parent: entity.parent,
 		created_by: entity.created_by,
 		created_at: entity.created_at,
@@ -496,6 +499,12 @@ var PostgresRegistry = class {
 	async createRunner(input) {
 		const now = new Date();
 		const wakeStream = input.wakeStream ?? runnerWakeStream(input.id);
+		const sandboxProfilesValue = input.sandboxProfiles ? input.sandboxProfiles.map((p) => ({
+			name: p.name,
+			label: p.label,
+			...p.description !== void 0 && { description: p.description },
+			...p.remote !== void 0 && { remote: p.remote }
+		})) : void 0;
 		await this.db.insert(runners).values({
 			tenantId: this.tenantId,
 			id: input.id,
@@ -504,6 +513,7 @@ var PostgresRegistry = class {
 			kind: input.kind ?? `local`,
 			adminStatus: input.adminStatus ?? `enabled`,
 			wakeStream,
+			...sandboxProfilesValue !== void 0 && { sandboxProfiles: sandboxProfilesValue },
 			updatedAt: now
 		}).onConflictDoUpdate({
 			target: [runners.tenantId, runners.id],
@@ -513,6 +523,7 @@ var PostgresRegistry = class {
 				kind: input.kind ?? `local`,
 				adminStatus: input.adminStatus ?? `enabled`,
 				wakeStream,
+				...sandboxProfilesValue !== void 0 && { sandboxProfiles: sandboxProfilesValue },
 				updatedAt: now
 			}
 		});
@@ -520,6 +531,30 @@ var PostgresRegistry = class {
 		if (!runner) throw new Error(`Failed to read back runner "${input.id}"`);
 		return runner;
 	}
+	/**
+	* Every sandbox profile advertised by a runner in this tenant (one entry
+	* per runner that advertises it — names may repeat across runners). Used by
+	* spawn validation for unpinned dispatch to learn whether a chosen profile
+	* is remote (so a shared sandbox can skip the single-runner guard).
+	*/
+	async listSandboxProfiles() {
+		const rows = await this.db.select({ sandboxProfiles: runners.sandboxProfiles }).from(runners).where((0, drizzle_orm.eq)(runners.tenantId, this.tenantId));
+		const profiles = [];
+		for (const row of rows) {
+			const list = row.sandboxProfiles;
+			if (!Array.isArray(list)) continue;
+			for (const entry of list) {
+				if (!entry || typeof entry.name !== `string`) continue;
+				profiles.push({
+					name: entry.name,
+					label: typeof entry.label === `string` ? entry.label : entry.name,
+					...typeof entry.description === `string` && { description: entry.description },
+					...typeof entry.remote === `boolean` && { remote: entry.remote }
+				});
+			}
+		}
+		return profiles;
+	}
 	async getRunner(id) {
 		const rows = await this.db.select().from(runners).where((0, drizzle_orm.and)((0, drizzle_orm.eq)(runners.tenantId, this.tenantId), (0, drizzle_orm.eq)(runners.id, id))).limit(1);
 		return rows[0] ? this.rowToRunner(rows[0]) : null;
@@ -780,6 +815,7 @@ var PostgresRegistry = class {
 					tags: (0, __electric_ax_agents_runtime.normalizeTags)(entity.tags),
 					tagsIndex: (0, __electric_ax_agents_runtime.buildTagsIndex)(entity.tags),
 					spawnArgs: entity.spawn_args ?? {},
+					sandbox: entity.sandbox ?? null,
 					parent: entity.parent ?? null,
 					createdBy: entity.created_by ?? null,
 					typeRevision: entity.type_revision ?? null,
@@ -1117,6 +1153,7 @@ var PostgresRegistry = class {
 			write_token: row.writeToken,
 			tags: row.tags ?? {},
 			spawn_args: row.spawnArgs,
+			sandbox: row.sandbox ?? void 0,
 			parent: row.parent ?? void 0,
 			created_by: row.createdBy ?? void 0,
 			type_revision: row.typeRevision ?? void 0,
@@ -1164,6 +1201,7 @@ var PostgresRegistry = class {
 			kind: assertRunnerKind(row.kind),
 			admin_status: assertRunnerAdminStatus(row.adminStatus),
 			wake_stream: row.wakeStream,
+			sandbox_profiles: row.sandboxProfiles ?? [],
 			created_at: row.createdAt.toISOString(),
 			updated_at: row.updatedAt.toISOString()
 		};
@@ -1294,6 +1332,7 @@ const ENTITY_SHAPE_COLUMNS = [
 	`status`,
 	`tags`,
 	`spawn_args`,
+	`sandbox`,
 	`parent`,
 	`type_revision`,
 	`inbox_schemas`,
@@ -1327,6 +1366,7 @@ function toMemberRow(entity) {
 		status: entity.status,
 		tags: entity.tags,
 		spawn_args: entity.spawn_args ?? {},
+		sandbox: entity.sandbox ?? null,
 		parent: entity.parent ?? null,
 		type_revision: entity.type_revision ?? null,
 		inbox_schemas: entity.inbox_schemas ?? null,
@@ -2007,7 +2047,7 @@ var StreamClient = class {
 			});
 		});
 	}
-	async fork(path$2, sourcePath) {
+	async fork(path$2, sourcePath, opts) {
 		return await withSpan(`stream.fork`, async (span) => {
 			span.setAttributes({
 				[ATTR.STREAM_PATH]: path$2,
@@ -2017,6 +2057,11 @@ var StreamClient = class {
 				"content-type": `application/json`,
 				"Stream-Forked-From": new URL(this.streamUrl(sourcePath)).pathname
 			};
+			if (opts?.forkPointer) {
+				const ZERO_OFFSET = `0000000000000000_0000000000000000`;
+				headers[`Stream-Fork-Offset`] = opts.forkPointer.offset ?? ZERO_OFFSET;
+				if (opts.forkPointer.subOffset > 0) headers[`Stream-Fork-Sub-Offset`] = String(opts.forkPointer.subOffset);
+			}
 			injectTraceHeaders(headers);
 			const response = await fetch(this.streamUrl(path$2), {
 				method: `PUT`,
@@ -2544,6 +2589,103 @@ async function linkStreamToTargetSubscription(ctx, target, entity, subscriptionI
 	});
 }
 
+//#endregion
+//#region src/routing/sandbox.ts
+/**
+* Resolve and validate a spawn's sandbox CHOICE into the {@link
+* EntitySandboxSelection} persisted on the entity. Sibling of
+* `dispatch-policy.ts`'s `resolveEffectiveDispatchPolicyForSpawn`: kept off the
+* EntityManager so the spawn path reads as composed resolution steps.
+*
+* Profiles are a per-runner concern: each runner advertises what it supports.
+* When the spawn pins a runner via dispatch_policy, the chosen profile must be
+* in that runner's advertised set; otherwise we'd persist an unserviceable
+* choice that fails late at first wake. For unpinned dispatch (webhook /
+* parent-inherited) we can't pick a target ahead of time, so we fall back to a
+* tenant-wide "some runner offers this" check — better than nothing.
+*/
+async function resolveSandboxForSpawn(registry, dispatchPolicy, requested, parentEntity) {
+	if (!requested) return void 0;
+	const choice = applyInheritedSandbox(requested, parentEntity);
+	if (!choice) return void 0;
+	const chosenName = choice.profile;
+	if (!chosenName) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox requires a "profile" (or "inherit": true with a parent that has a shared sandbox).`, 400);
+	const chosenIsRemote = await resolveChosenProfileRemote(registry, chosenName, dispatchPolicy);
+	assertSharedSandboxColocated(choice.key, chosenIsRemote, dispatchPolicy);
+	const selection = { profile: chosenName };
+	if (choice.key !== void 0) selection.key = choice.key;
+	else if (choice.scope !== void 0) selection.scope = choice.scope;
+	if (choice.persistent !== void 0) selection.persistent = choice.persistent;
+	if (choice.owner === false) selection.owner = false;
+	return selection;
+}
+/**
+* Resolve `inherit` against the parent's *stored* sandbox. `inherit` reuses the
+* parent's keyed sandbox as a non-owner (attach-only). It's graceful: if the
+* parent has no shareable (keyed) sandbox the child simply gets none (returns
+* `undefined`), so `spawn_worker` can always request inheritance without
+* breaking unkeyed parents. (A running parent wake resolves inherit to its live
+* explicit key in the runtime instead — this server-side path covers direct API
+* callers, where only the parent's *stored* explicit key is available.)
+*
+* For a non-inherit choice the request passes through unchanged.
+*
+* NOTE: `inherit: true` takes the parent's identity AND durability wholesale —
+* any sibling field on the request (e.g. a caller-supplied `persistent: false`)
+* is intentionally ignored, because a child attaches to the parent's existing
+* sandbox and cannot change how that sandbox is torn down. `sandboxChoiceSchema`
+* permits the `{ inherit: true, persistent: ... }` combination, so the
+* precedence is resolved here rather than rejected at the schema level.
+*/
+function applyInheritedSandbox(requested, parentEntity) {
+	if (!requested.inherit) return requested;
+	const parentKey = parentEntity?.sandbox?.key;
+	if (!parentKey) return void 0;
+	return {
+		profile: parentEntity.sandbox.profile,
+		key: parentKey,
+		persistent: parentEntity.sandbox.persistent,
+		owner: false
+	};
+}
+/**
+* Validate the chosen profile is advertised by the relevant runner(s) and
+* determine whether it is a remote (off-host) sandbox, reachable from any
+* runner. Defaults to host-local (co-location required) unless every relevant
+* advertisement marks it remote. Throws if the profile is unserviceable.
+*/
+async function resolveChosenProfileRemote(registry, chosenName, dispatchPolicy) {
+	const runnerIds = [];
+	for (const target of dispatchPolicy?.targets ?? []) if (target.type === `runner`) runnerIds.push(target.runnerId);
+	if (runnerIds.length > 0) {
+		let allRemote = true;
+		for (const runnerId of runnerIds) {
+			const runner = await registry.getRunner(runnerId);
+			const advertised = runner?.sandbox_profiles ?? [];
+			const match = advertised.find((p) => p.name === chosenName);
+			if (!match) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox profile "${chosenName}" is not advertised by runner "${runnerId}" (advertised: ${advertised.map((p) => p.name).join(`, `) || `(none)`}).`, 400);
+			if (match.remote !== true) allRemote = false;
+		}
+		return allRemote;
+	}
+	const available = await registry.listSandboxProfiles();
+	const matches = available.filter((p) => p.name === chosenName);
+	if (matches.length === 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox profile "${chosenName}" is not offered by any registered runner (available: ${[...new Set(available.map((p) => p.name))].join(`, `) || `(none)`}).`, 400);
+	return matches.every((p) => p.remote === true);
+}
+/**
+* Co-location: a shared *local* sandbox lives on one host, so every
+* collaborator must be pinned to the same single runner. Subagents inherit the
+* parent's dispatch policy, so this holds once the root is pinned. A shared
+* *remote* sandbox is reachable from any runner, so the guard does not apply.
+*/
+function assertSharedSandboxColocated(key, chosenIsRemote, dispatchPolicy) {
+	if (key === void 0 || chosenIsRemote) return;
+	const targets = dispatchPolicy?.targets ?? [];
+	const pinnedToSingleRunner = targets.length === 1 && targets[0]?.type === `runner`;
+	if (!pinnedToSingleRunner) throw new ElectricAgentsError(ErrCodeInvalidRequest, `a shared sandbox (sandbox.key / sandbox.inherit) requires the entity to be pinned to a single runner via dispatch_policy, so all collaborators share one host.`, 400);
+}
+
 //#endregion
 //#region src/principal.ts
 const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
@@ -2944,6 +3086,7 @@ var EntityManager = class {
 			if (!parentEntity) throw new ElectricAgentsError(ErrCodeNotFound, `Parent entity "${req.parent}" not found`, 404);
 		}
 		const dispatchPolicy = req.dispatch_policy ? this.validateDispatchPolicy(req.dispatch_policy, { label: `dispatch_policy` }) : parentEntity?.dispatch_policy ? applyTypeDefaultSubscriptionScope(parentEntity.dispatch_policy, entityType.default_dispatch_policy) : entityType.default_dispatch_policy;
+		const sandbox = await resolveSandboxForSpawn(this.registry, dispatchPolicy, req.sandbox, parentEntity);
 		const now = Date.now();
 		const entityData = {
 			type: typeName,
@@ -2958,6 +3101,7 @@ var EntityManager = class {
 			write_token: writeToken,
 			tags: initialTags,
 			spawn_args: req.args,
+			sandbox,
 			type_revision: entityType.revision,
 			inbox_schemas: entityType.inbox_schemas,
 			state_schemas: entityType.state_schemas,
@@ -3087,27 +3231,66 @@ var EntityManager = class {
 		const writeEntityLocks = new Set();
 		const writeStreamLocks = new Set();
 		try {
-			const sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks);
+			let sourceTree;
+			if (opts.forkPointer) {
+				const rootEntity = await this.registry.getEntity(rootUrl);
+				if (!rootEntity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+				if (isTerminalEntityStatus(rootEntity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork terminal entity "${rootEntity.url}"`, 409);
+				sourceTree = await this.listEntitySubtree(rootEntity);
+			} else sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks);
 			const sourceRoot = sourceTree[0];
 			if (sourceRoot.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
-			const snapshot = await this.readForkStateSnapshot(sourceTree);
+			let preFilteredRoot;
+			if (opts.forkPointer) {
+				const sourceEvents = await this.streamClient.readJson(sourceRoot.streams.main);
+				const flat = sourceEvents.flatMap((item) => Array.isArray(item) ? item : [item]);
+				const target = this.resolveForkPointerTarget(flat, opts.forkPointer, sourceRoot.streams.main);
+				const filteredEvents = flat.slice(0, target);
+				const rootManifests = this.reduceStateRows(filteredEvents, `manifest`);
+				const sharedStateIds = new Set();
+				for (const manifest of rootManifests.values()) this.collectSharedStateIds(manifest, sharedStateIds);
+				preFilteredRoot = {
+					manifests: rootManifests,
+					childStatuses: this.reduceStateRows(filteredEvents, `child_status`),
+					replayWatermarks: this.reduceStateRows(filteredEvents, `replay_watermark`),
+					sharedStateIds
+				};
+			}
+			const effectiveSubtree = preFilteredRoot ? this.computeEffectiveSubtree(sourceTree, sourceRoot.url, preFilteredRoot.manifests) : sourceTree;
+			if (opts.forkPointer) {
+				const descendants = effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url);
+				if (descendants.length > 0) await this.waitForGivenEntitiesIdle(descendants, opts, workLocks);
+			}
+			const snapshot = await this.readForkStateSnapshot(
+				// Skip the root when we've already pre-filtered it — avoid both a
+				// wasted HEAD read of main and a re-population that would clobber
+				// the filtered entries.
+				preFilteredRoot ? effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url) : effectiveSubtree
+);
+			if (preFilteredRoot) {
+				snapshot.manifestsByEntity.set(sourceRoot.url, preFilteredRoot.manifests);
+				snapshot.childStatusesByEntity.set(sourceRoot.url, preFilteredRoot.childStatuses);
+				snapshot.replayWatermarksByEntity.set(sourceRoot.url, preFilteredRoot.replayWatermarks);
+				for (const id of preFilteredRoot.sharedStateIds) snapshot.sharedStateIds.add(id);
+			}
 			const suffix = (0, node_crypto.randomUUID)().slice(0, 8);
-			const entityUrlMap = await this.buildForkEntityUrlMap(sourceTree, {
+			const entityUrlMap = await this.buildForkEntityUrlMap(effectiveSubtree, {
 				suffix,
 				rootUrl,
 				rootInstanceId: opts.rootInstanceId
 			});
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
-			const entityPlans = this.buildForkEntityPlans(sourceTree, entityUrlMap, stringMap);
-			this.addForkLocks(this.forkWriteLockedEntities, sourceTree.map((entity) => entity.url), writeEntityLocks);
+			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap);
+			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(id)), writeStreamLocks);
 			const createdStreams = [];
 			const createdEntities = [];
 			const activeManifestsByEntity = new Map();
 			try {
 				for (const plan of entityPlans) {
-					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main);
+					const isRoot = plan.source.url === rootUrl;
+					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && opts.forkPointer ? { forkPointer: opts.forkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
 					await this.streamClient.fork(plan.fork.streams.error, plan.source.streams.error);
 					createdStreams.push(plan.fork.streams.error);
@@ -3200,6 +3383,38 @@ var EntityManager = class {
 		}
 		held.clear();
 	}
+	/**
+	* Variant of {@link waitForIdleSubtree} that takes an explicit entity
+	* list instead of walking the registry from `rootUrl`. Used by the
+	* pointer-fork path to wait+lock only the kept descendants, since
+	* the root is being forked from history and doesn't need to be idle.
+	*/
+	async waitForGivenEntitiesIdle(entities$1, opts, workLocks) {
+		if (entities$1.length === 0) return;
+		const timeoutMs = opts.waitTimeoutMs ?? DEFAULT_FORK_WAIT_TIMEOUT_MS;
+		const pollMs = opts.waitPollMs ?? DEFAULT_FORK_WAIT_POLL_MS;
+		const refresh = async () => {
+			const refreshed = await Promise.all(entities$1.map((entity) => this.registry.getEntity(entity.url)));
+			return refreshed.filter((entity) => !!entity);
+		};
+		const deadline = Date.now() + timeoutMs;
+		while (true) {
+			const present = await refresh();
+			const stopped = present.find((entity) => isTerminalEntityStatus(entity.status));
+			if (stopped) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork terminal entity "${stopped.url}"`, 409);
+			let active = present.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
+			if (active.length === 0) {
+				this.addForkLocks(this.forkWorkLockedEntities, present.map((entity) => entity.url), workLocks);
+				const reChecked = await refresh();
+				const reActive = reChecked.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
+				if (reActive.length === 0) return;
+				this.releaseForkLocks(this.forkWorkLockedEntities, workLocks);
+				active = reActive;
+			}
+			if (Date.now() >= deadline) throw new ElectricAgentsError(ErrCodeForkWaitTimeout, `Timed out waiting for descendants to become idle`, 409, { active: active.map((entity) => entity.url) });
+			await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+		}
+	}
 	async waitForIdleSubtree(rootUrl, opts, workLocks) {
 		const timeoutMs = opts.waitTimeoutMs ?? DEFAULT_FORK_WAIT_TIMEOUT_MS;
 		const pollMs = opts.waitPollMs ?? DEFAULT_FORK_WAIT_POLL_MS;
@@ -3229,6 +3444,73 @@ var EntityManager = class {
 			await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
 		}
 	}
+	/**
+	* Translate `forkPointer` into a 1-indexed CUMULATIVE position in the
+	* source's flattened history. Throws a 400 if the pointer doesn't
+	* address a real event.
+	*
+	* Semantics (mirroring the durable-streams server interpretation):
+	* `{ offset: X, subOffset: N }` means "from anchor X, take N flattened
+	* messages forward." Concretely, the target event is the N-th event
+	* after the last event whose `headers.offset` is ≤ X. (When `X` is
+	* `null`, the anchor is the stream start and the target is the N-th
+	* event from the very beginning.) The returned position is the count
+	* of events to KEEP — events 1..position survive the filter.
+	*
+	* A pointer is valid when:
+	*   - `pointer.offset` is `null` (stream start) OR matches some
+	*     event's `headers.offset` value, AND
+	*   - `pointer.subOffset` is in `[1, total events past the anchor]`.
+	*/
+	resolveForkPointerTarget(events, pointer, streamPath) {
+		let positionAtAnchor = 0;
+		let anchorSeen = pointer.offset === null;
+		for (const event of events) {
+			const headers = isRecord(event.headers) ? event.headers : void 0;
+			const eventOffset = typeof headers?.offset === `string` ? headers.offset : void 0;
+			if (eventOffset === void 0) continue;
+			if (pointer.offset === null) continue;
+			if (eventOffset === pointer.offset) anchorSeen = true;
+			if (eventOffset <= pointer.offset) positionAtAnchor++;
+		}
+		if (!anchorSeen) throw new ElectricAgentsError(ErrCodeInvalidRequest, `fork_pointer.offset (${pointer.offset ?? `<stream-start>`}) does not match any event's Stream-Next-Offset on ${streamPath}`, 400);
+		const eventsPastAnchor = events.length - positionAtAnchor;
+		if (pointer.subOffset < 1 || pointer.subOffset > eventsPastAnchor) throw new ElectricAgentsError(ErrCodeInvalidRequest, `fork_pointer.sub_offset ${pointer.subOffset} out of range past anchor on ${streamPath} (valid: 1..${eventsPastAnchor})`, 400);
+		return positionAtAnchor + pointer.subOffset;
+	}
+	/**
+	* Compute the subset of `sourceTree` that survives the manifest filter
+	* applied at the root. After filtering the root's manifest at the fork
+	* pointer, only children whose manifest entries landed at or before the
+	* pointer remain; those kept children carry their CURRENT (HEAD) subtree
+	* along with them. Children dropped from the root's manifest, and any
+	* of their descendants, are excluded.
+	*/
+	computeEffectiveSubtree(sourceTree, rootUrl, filteredRootManifests) {
+		const keptChildUrls = new Set();
+		for (const value of filteredRootManifests.values()) if (value.kind === `child` && typeof value.entity_url === `string`) keptChildUrls.add(value.entity_url);
+		const childrenByParent = new Map();
+		for (const entity of sourceTree) {
+			if (!entity.parent) continue;
+			const list = childrenByParent.get(entity.parent) ?? [];
+			list.push(entity);
+			childrenByParent.set(entity.parent, list);
+		}
+		const rootEntity = sourceTree.find((e) => e.url === rootUrl);
+		if (!rootEntity) return [];
+		const result = [rootEntity];
+		const queue = [];
+		for (const child of childrenByParent.get(rootUrl) ?? []) if (keptChildUrls.has(child.url)) queue.push(child);
+		const seen = new Set([rootUrl]);
+		while (queue.length > 0) {
+			const entity = queue.shift();
+			if (seen.has(entity.url)) continue;
+			seen.add(entity.url);
+			result.push(entity);
+			for (const grandchild of childrenByParent.get(entity.url) ?? []) if (!seen.has(grandchild.url)) queue.push(grandchild);
+		}
+		return result;
+	}
 	async listEntitySubtree(root) {
 		const result = [];
 		const queue = [root];
@@ -4336,6 +4618,7 @@ var EntityManager = class {
 				streams: entity.streams,
 				tags: entity.tags,
 				spawnArgs: entity.spawn_args,
+				sandbox: entity.sandbox,
 				createdBy: entity.created_by
 			},
 			principal: principalFromCreatedBy(entity.created_by),
@@ -6001,11 +6284,19 @@ var WakeRegistry = class {
 		}
 		const kind = operation === `delete` ? `delete` : operation === `update` ? `update` : `insert`;
 		if (condition.ops && condition.ops.length > 0 && !condition.ops.includes(kind)) return null;
-		return { change: {
+		const change = {
 			collection: eventType,
 			kind,
 			key: event.key || ``
-		} };
+		};
+		if (eventType === `inbox`) {
+			const value = event.value;
+			if (typeof value?.from === `string`) change.from = value.from;
+			if (`payload` in (value ?? {})) change.payload = value?.payload;
+			if (typeof value?.timestamp === `string`) change.timestamp = value.timestamp;
+			if (typeof value?.message_type === `string`) change.message_type = value.message_type;
+		}
+		return { change };
 	}
 };
 
@@ -6412,13 +6703,13 @@ function buildElectricProxyTarget(options) {
 	if (options.electricSecret) target.searchParams.set(`secret`, options.electricSecret);
 	const table = options.incomingUrl.searchParams.get(`table`);
 	if (table === `entities`) {
-		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
+		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId);
 	} else if (table === `entity_types`) {
 		target.searchParams.set(`columns`, `"tenant_id","name","description","creation_schema","inbox_schemas","state_schemas","serve_endpoint","default_dispatch_policy","revision","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId);
 	} else if (table === `runners`) {
-		target.searchParams.set(`columns`, `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","created_at","updated_at"`);
+		target.searchParams.set(`columns`, `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","sandbox_profiles","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral(options.principalUrl ?? ``)}`]);
 	} else if (table === `runner_runtime_diagnostics`) {
 		target.searchParams.set(`columns`, `"tenant_id","runner_id","owner_principal","wake_stream_offset","last_seen_at","liveness_lease_expires_at","diagnostics","updated_at"`);
@@ -6844,6 +7135,28 @@ async function proxyElectric(request, ctx) {
 	});
 }
 
+//#endregion
+//#region src/sandbox-choice-schema.ts
+/**
+* Wire schema for a spawn-time sandbox CHOICE (the request input), as opposed to
+* the resolved {@link import('./electric-agents-types.js').EntitySandboxSelection}
+* persisted on the entity. The matching `SandboxChoice` type is hand-maintained
+* in `electric-agents-types.ts` — mirrors how `dispatchPolicySchema` pairs with
+* the `DispatchPolicy` type in `dispatch-policy-schema.ts`.
+*
+* Validation happens once, at the router boundary (this schema is embedded in
+* the spawn body schema); the spawn resolver consumes already-validated input,
+* so there is intentionally no separate `parse` helper here.
+*/
+const sandboxChoiceSchema = __sinclair_typebox.Type.Object({
+	profile: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	key: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	scope: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Union([__sinclair_typebox.Type.Literal(`entity`), __sinclair_typebox.Type.Literal(`wake`)])),
+	persistent: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean()),
+	owner: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean()),
+	inherit: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean())
+});
+
 //#endregion
 //#region src/routing/entities-router.ts
 const stringRecordSchema$1 = __sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.String());
@@ -6866,6 +7179,7 @@ const spawnBodySchema = __sinclair_typebox.Type.Object({
 	tags: __sinclair_typebox.Type.Optional(stringRecordSchema$1),
 	parent: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
 	dispatch_policy: __sinclair_typebox.Type.Optional(dispatchPolicySchema),
+	sandbox: __sinclair_typebox.Type.Optional(sandboxChoiceSchema),
 	initialMessage: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Unknown()),
 	wake: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Object({
 		subscriberUrl: __sinclair_typebox.Type.String(),
@@ -6907,7 +7221,11 @@ const inboxMessageBodySchema = __sinclair_typebox.Type.Object({
 });
 const forkBodySchema = __sinclair_typebox.Type.Object({
 	instance_id: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
-	waitTimeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number())
+	waitTimeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
+	fork_pointer: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Object({
+		offset: __sinclair_typebox.Type.Union([__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Null()]),
+		sub_offset: __sinclair_typebox.Type.Number()
+	}))
 });
 const setTagBodySchema = __sinclair_typebox.Type.Object({ value: __sinclair_typebox.Type.String() });
 const entitySignalSchema = __sinclair_typebox.Type.Union([
@@ -7225,7 +7543,11 @@ async function forkEntity(request, ctx) {
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
-		waitTimeoutMs: parsed.waitTimeoutMs
+		waitTimeoutMs: parsed.waitTimeoutMs,
+		...parsed.fork_pointer && { forkPointer: {
+			offset: parsed.fork_pointer.offset,
+			subOffset: parsed.fork_pointer.sub_offset
+		} }
 	});
 	for (const forkedEntity of result.entities) await linkEntityDispatchSubscription(ctx, forkedEntity);
 	return (0, itty_router.json)({
@@ -7323,6 +7645,7 @@ async function spawnEntity(request, ctx) {
 		tags: parsed.tags,
 		parent: parsed.parent,
 		dispatch_policy: dispatchPolicy,
+		sandbox: parsed.sandbox,
 		initialMessage: void 0,
 		wake: parsed.wake,
 		created_by: principal.url
@@ -7577,6 +7900,12 @@ function withLeadingSlash(path$2) {
 
 //#endregion
 //#region src/routing/runners-router.ts
+const sandboxProfileBodySchema = __sinclair_typebox.Type.Object({
+	name: __sinclair_typebox.Type.String(),
+	label: __sinclair_typebox.Type.String(),
+	description: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	remote: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean())
+});
 const registerRunnerBodySchema = __sinclair_typebox.Type.Object({
 	id: __sinclair_typebox.Type.String(),
 	owner_principal: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
@@ -7589,7 +7918,8 @@ const registerRunnerBodySchema = __sinclair_typebox.Type.Object({
 		__sinclair_typebox.Type.Literal(`server`)
 	])),
 	admin_status: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Union([__sinclair_typebox.Type.Literal(`enabled`), __sinclair_typebox.Type.Literal(`disabled`)])),
-	wake_stream: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
+	wake_stream: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	sandbox_profiles: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(sandboxProfileBodySchema))
 });
 const heartbeatBodySchema = __sinclair_typebox.Type.Object({
 	lease_ms: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
@@ -7687,7 +8017,8 @@ async function registerRunner(request, ctx) {
 		label: parsed.label,
 		kind: parsed.kind,
 		adminStatus: parsed.admin_status,
-		wakeStream: parsed.wake_stream
+		wakeStream: parsed.wake_stream,
+		sandboxProfiles: parsed.sandbox_profiles
 	});
 	await ctx.streamClient.ensure(runner.wake_stream, { contentType: `application/json` });
 	return (0, itty_router.json)(runner, { status: 201 });
@@ -7917,6 +8248,7 @@ async function notificationFromClaim(ctx, input) {
 			streams: entity.streams,
 			tags: entity.tags,
 			spawnArgs: entity.spawn_args,
+			sandbox: entity.sandbox,
 			createdBy: entity.created_by
 		},
 		principal: principalFromCreatedBy(entity.created_by)