@electric-ax/agents-server 0.4.14 → 0.4.15

package/dist/index.js

@@ -61,6 +61,7 @@ const entities = pgTable(`entities`, {
 	tags: jsonb(`tags`).notNull().default({}),
 	tagsIndex: text(`tags_index`).array().notNull().default(sql`'{}'::text[]`),
 	spawnArgs: jsonb(`spawn_args`).default({}),
+	sandbox: jsonb(`sandbox`),
 	parent: text(`parent`),
 	createdBy: text(`created_by`),
 	typeRevision: integer(`type_revision`),
@@ -102,6 +103,7 @@ const runners = pgTable(`runners`, {
 	kind: text(`kind`).notNull().default(`local`),
 	adminStatus: text(`admin_status`).notNull().default(`enabled`),
 	wakeStream: text(`wake_stream`).notNull(),
+	sandboxProfiles: jsonb(`sandbox_profiles`).notNull().default([]),
 	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
@@ -399,6 +401,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,
@@ -467,6 +470,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,
@@ -475,6 +484,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],
@@ -484,6 +494,7 @@ var PostgresRegistry = class {
 				kind: input.kind ?? `local`,
 				adminStatus: input.adminStatus ?? `enabled`,
 				wakeStream,
+				...sandboxProfilesValue !== void 0 && { sandboxProfiles: sandboxProfilesValue },
 				updatedAt: now
 			}
 		});
@@ -491,6 +502,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(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(and(eq(runners.tenantId, this.tenantId), eq(runners.id, id))).limit(1);
 		return rows[0] ? this.rowToRunner(rows[0]) : null;
@@ -751,6 +786,7 @@ var PostgresRegistry = class {
 					tags: normalizeTags(entity.tags),
 					tagsIndex: 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,
@@ -1088,6 +1124,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,
@@ -1135,6 +1172,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()
 		};
@@ -1265,6 +1303,7 @@ const ENTITY_SHAPE_COLUMNS = [
 	`status`,
 	`tags`,
 	`spawn_args`,
+	`sandbox`,
 	`parent`,
 	`type_revision`,
 	`inbox_schemas`,
@@ -1298,6 +1337,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,
@@ -1978,7 +2018,7 @@ var StreamClient = class {
 			});
 		});
 	}
-	async fork(path$1, sourcePath) {
+	async fork(path$1, sourcePath, opts) {
 		return await withSpan(`stream.fork`, async (span) => {
 			span.setAttributes({
 				[ATTR.STREAM_PATH]: path$1,
@@ -1988,6 +2028,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$1), {
 				method: `PUT`,
@@ -2515,6 +2560,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`;
@@ -2915,6 +3057,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,
@@ -2929,6 +3072,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,
@@ -3058,27 +3202,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 = 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) => 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);
@@ -3171,6 +3354,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;
@@ -3200,6 +3415,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];
@@ -4307,6 +4589,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),
@@ -5972,11 +6255,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 };
 	}
 };
 
@@ -6383,13 +6674,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"`);
@@ -6815,6 +7106,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 = Type.Object({
+	profile: Type.Optional(Type.String()),
+	key: Type.Optional(Type.String()),
+	scope: Type.Optional(Type.Union([Type.Literal(`entity`), Type.Literal(`wake`)])),
+	persistent: Type.Optional(Type.Boolean()),
+	owner: Type.Optional(Type.Boolean()),
+	inherit: Type.Optional(Type.Boolean())
+});
+
 //#endregion
 //#region src/routing/entities-router.ts
 const stringRecordSchema$1 = Type.Record(Type.String(), Type.String());
@@ -6837,6 +7150,7 @@ const spawnBodySchema = Type.Object({
 	tags: Type.Optional(stringRecordSchema$1),
 	parent: Type.Optional(Type.String()),
 	dispatch_policy: Type.Optional(dispatchPolicySchema),
+	sandbox: Type.Optional(sandboxChoiceSchema),
 	initialMessage: Type.Optional(Type.Unknown()),
 	wake: Type.Optional(Type.Object({
 		subscriberUrl: Type.String(),
@@ -6878,7 +7192,11 @@ const inboxMessageBodySchema = Type.Object({
 });
 const forkBodySchema = Type.Object({
 	instance_id: Type.Optional(Type.String()),
-	waitTimeoutMs: Type.Optional(Type.Number())
+	waitTimeoutMs: Type.Optional(Type.Number()),
+	fork_pointer: Type.Optional(Type.Object({
+		offset: Type.Union([Type.String(), Type.Null()]),
+		sub_offset: Type.Number()
+	}))
 });
 const setTagBodySchema = Type.Object({ value: Type.String() });
 const entitySignalSchema = Type.Union([
@@ -7196,7 +7514,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 json({
@@ -7294,6 +7616,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
@@ -7548,6 +7871,12 @@ function withLeadingSlash(path$1) {
 
 //#endregion
 //#region src/routing/runners-router.ts
+const sandboxProfileBodySchema = Type.Object({
+	name: Type.String(),
+	label: Type.String(),
+	description: Type.Optional(Type.String()),
+	remote: Type.Optional(Type.Boolean())
+});
 const registerRunnerBodySchema = Type.Object({
 	id: Type.String(),
 	owner_principal: Type.Optional(Type.String()),
@@ -7560,7 +7889,8 @@ const registerRunnerBodySchema = Type.Object({
 		Type.Literal(`server`)
 	])),
 	admin_status: Type.Optional(Type.Union([Type.Literal(`enabled`), Type.Literal(`disabled`)])),
-	wake_stream: Type.Optional(Type.String())
+	wake_stream: Type.Optional(Type.String()),
+	sandbox_profiles: Type.Optional(Type.Array(sandboxProfileBodySchema))
 });
 const heartbeatBodySchema = Type.Object({
 	lease_ms: Type.Optional(Type.Number()),
@@ -7658,7 +7988,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 json(runner, { status: 201 });
@@ -7888,6 +8219,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)

package/drizzle/0010_sandbox_profiles.sql

@@ -0,0 +1,5 @@
+ALTER TABLE runners
+  ADD COLUMN sandbox_profiles jsonb NOT NULL DEFAULT '[]'::jsonb;
+--> statement-breakpoint
+ALTER TABLE entities
+  ADD COLUMN sandbox jsonb;

package/drizzle/meta/_journal.json

@@ -71,6 +71,13 @@
       "when": 1778540000000,
       "tag": "0009_entity_signal_statuses",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1779062400000,
+      "tag": "0010_sandbox_profiles",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.7"
+    "@electric-ax/agents-runtime": "0.3.8"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
@@ -65,9 +65,9 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
-    "@electric-ax/agents": "0.4.11",
-    "@electric-ax/agents-server-conformance-tests": "0.1.9",
-    "@electric-ax/agents-server-ui": "0.4.14"
+    "@electric-ax/agents": "0.4.12",
+    "@electric-ax/agents-server-conformance-tests": "0.1.10",
+    "@electric-ax/agents-server-ui": "0.4.15"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -49,6 +49,7 @@ export const entities = pgTable(
       .notNull()
       .default(sql`'{}'::text[]`),
     spawnArgs: jsonb(`spawn_args`).default({}),
+    sandbox: jsonb(`sandbox`),
     parent: text(`parent`),
     createdBy: text(`created_by`),
     typeRevision: integer(`type_revision`),
@@ -111,6 +112,7 @@ export const runners = pgTable(
     kind: text(`kind`).notNull().default(`local`),
     adminStatus: text(`admin_status`).notNull().default(`enabled`),
     wakeStream: text(`wake_stream`).notNull(),
+    sandboxProfiles: jsonb(`sandbox_profiles`).notNull().default([]),
     createdAt: timestamp(`created_at`, { withTimezone: true })
       .notNull()
       .defaultNow(),