@electric-ax/agents-server 0.4.0 → 0.4.2

package/dist/index.js

@@ -61,6 +61,7 @@ const entities = pgTable(`entities`, {
 	tagsIndex: text(`tags_index`).array().notNull().default(sql`'{}'::text[]`),
 	spawnArgs: jsonb(`spawn_args`).default({}),
 	parent: text(`parent`),
+	createdBy: text(`created_by`),
 	typeRevision: integer(`type_revision`),
 	inboxSchemas: jsonb(`inbox_schemas`),
 	stateSchemas: jsonb(`state_schemas`),
@@ -71,6 +72,7 @@ const entities = pgTable(`entities`, {
 	index(`idx_entities_type`).on(table.tenantId, table.type),
 	index(`idx_entities_status`).on(table.tenantId, table.status),
 	index(`idx_entities_parent`).on(table.tenantId, table.parent),
+	index(`idx_entities_created_by`).on(table.tenantId, table.createdBy),
 	index(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
 	check(`chk_entities_status`, sql`${table.status} IN ('spawning', 'running', 'idle', 'stopped')`)
 ]);
@@ -285,7 +287,7 @@ function createDb(postgresUrl) {
 	const poolMax = Number(process.env.ELECTRIC_AGENTS_PG_POOL_MAX ?? `100`);
 	const client = postgres(postgresUrl, {
 		max: poolMax,
-		fetch_types: false
+		fetch_types: true
 	});
 	const db = drizzle(client, { schema: schema_exports });
 	return {
@@ -353,6 +355,7 @@ function toPublicEntity(entity) {
 		tags: entity.tags,
 		spawn_args: entity.spawn_args,
 		parent: entity.parent,
+		created_by: entity.created_by,
 		created_at: entity.created_at,
 		updated_at: entity.updated_at
 	};
@@ -592,6 +595,24 @@ var PostgresRegistry = class {
 			}
 		});
 	}
+	async ensureEntityType(et) {
+		const existing = await this.getEntityType(et.name);
+		if (existing) return existing;
+		await this.db.insert(entityTypes).values({
+			tenantId: this.tenantId,
+			name: et.name,
+			description: et.description,
+			creationSchema: et.creation_schema ?? null,
+			inboxSchemas: et.inbox_schemas ?? null,
+			stateSchemas: et.state_schemas ?? null,
+			serveEndpoint: et.serve_endpoint ?? null,
+			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
+			revision: et.revision,
+			createdAt: et.created_at,
+			updatedAt: et.updated_at
+		}).onConflictDoNothing();
+		return await this.getEntityType(et.name);
+	}
 	async getEntityType(name) {
 		const rows = await this.db.select().from(entityTypes).where(this.entityTypeWhere(name)).limit(1);
 		if (rows.length === 0) return null;
@@ -631,6 +652,7 @@ var PostgresRegistry = class {
 					tagsIndex: buildTagsIndex(entity.tags),
 					spawnArgs: entity.spawn_args ?? {},
 					parent: entity.parent ?? null,
+					createdBy: entity.created_by ?? null,
 					typeRevision: entity.type_revision ?? null,
 					inboxSchemas: entity.inbox_schemas ?? null,
 					stateSchemas: entity.state_schemas ?? null,
@@ -676,6 +698,7 @@ var PostgresRegistry = class {
 		if (filter?.type) conditions.push(eq(entities.type, filter.type));
 		if (filter?.status) conditions.push(eq(entities.status, filter.status));
 		if (filter?.parent) conditions.push(eq(entities.parent, filter.parent));
+		if (filter?.created_by) conditions.push(eq(entities.createdBy, filter.created_by));
 		const whereClause = and(...conditions);
 		const countResult = await this.db.select({ count: sql`count(*)` }).from(entities).where(whereClause);
 		const total = Number(countResult[0].count);
@@ -962,6 +985,7 @@ var PostgresRegistry = class {
 			tags: row.tags ?? {},
 			spawn_args: row.spawnArgs,
 			parent: row.parent ?? void 0,
+			created_by: row.createdBy ?? void 0,
 			type_revision: row.typeRevision ?? void 0,
 			inbox_schemas: row.inboxSchemas,
 			state_schemas: row.stateSchemas,
@@ -1687,6 +1711,239 @@ function parseDispatchPolicy(value, label = `dispatch_policy`) {
 	throw new Error(details ? `${label} does not match dispatch policy schema: ${details}` : `${label} does not match dispatch policy schema`);
 }
 
+//#endregion
+//#region src/utils/webhook-url.ts
+function rewriteLoopbackWebhookUrl(value) {
+	if (!value) return void 0;
+	const rewriteTarget = process.env.ELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO?.trim();
+	if (!rewriteTarget) return value;
+	const url = new URL(value);
+	if (!isLoopbackHostname(url.hostname)) return value;
+	if (rewriteTarget.includes(`://`)) {
+		const target = new URL(rewriteTarget);
+		url.protocol = target.protocol;
+		url.username = target.username;
+		url.password = target.password;
+		url.hostname = target.hostname;
+		url.port = target.port;
+		return url.toString();
+	}
+	url.host = rewriteTarget;
+	return url.toString();
+}
+function isLoopbackHostname(hostname) {
+	return hostname === `localhost` || hostname === `127.0.0.1` || hostname === `::1`;
+}
+
+//#endregion
+//#region src/routing/dispatch-policy.ts
+function subscriptionIdForDispatchTarget(target) {
+	if (target.subscription_id) return target.subscription_id;
+	if (target.type === `runner`) return `runner:${target.runnerId}`;
+	const digest = createHash(`sha256`).update(target.url).digest(`hex`);
+	return `webhook:${digest.slice(0, 16)}`;
+}
+function subscriptionIdForEntityDispatchTarget(target, entityUrl) {
+	const base = subscriptionIdForDispatchTarget(target);
+	if (!target.subscription_id) return base;
+	const digest = createHash(`sha256`).update(entityUrl).digest(`hex`);
+	return `${base}:${digest.slice(0, 16)}`;
+}
+async function resolveEffectiveDispatchPolicyForSpawn(ctx, typeName, opts) {
+	if (opts.dispatchPolicy) return opts.dispatchPolicy;
+	const entityType = await ctx.entityManager.registry.getEntityType(typeName);
+	if (opts.parent) {
+		const parent = await ctx.entityManager.registry.getEntity(opts.parent);
+		if (parent?.dispatch_policy) return applyTypeDefaultSubscriptionScope(parent.dispatch_policy, entityType?.default_dispatch_policy);
+	}
+	return entityType?.default_dispatch_policy;
+}
+async function resolveEffectiveDispatchPolicyForEntity(ctx, entity) {
+	if (entity.dispatch_policy) return entity.dispatch_policy;
+	const entityType = await ctx.entityManager.registry.getEntityType(entity.type);
+	return entityType?.default_dispatch_policy;
+}
+async function backfillEntityDispatchPolicy(ctx, entity) {
+	if (entity.dispatch_policy) return entity;
+	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
+	if (!dispatchPolicy) return entity;
+	return await ctx.entityManager.registry.updateEntityDispatchPolicy(entity.url, dispatchPolicy) ?? {
+		...entity,
+		dispatch_policy: dispatchPolicy
+	};
+}
+function applyTypeDefaultSubscriptionScope(policy, typeDefault) {
+	const target = policy.targets[0];
+	const defaultTarget = typeDefault?.targets[0];
+	if (!target || !defaultTarget?.subscription_id) return policy;
+	if (!sameDispatchDestination(target, defaultTarget)) return policy;
+	if (target.subscription_id === defaultTarget.subscription_id) return policy;
+	return { targets: [{
+		...target,
+		subscription_id: defaultTarget.subscription_id
+	}] };
+}
+function sameDispatchDestination(a, b) {
+	if (a.type !== b.type) return false;
+	if (a.type === `runner` && b.type === `runner`) return a.runnerId === b.runnerId;
+	if (a.type === `webhook` && b.type === `webhook`) return a.url === b.url;
+	return false;
+}
+async function assertDispatchPolicyAllowed(ctx, policy) {
+	const target = policy?.targets[0];
+	if (!target || target.type !== `runner`) return;
+	const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
+	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
+	if (ctx.principal && runner.owner_user_id !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires the authenticated owner`, 403);
+}
+async function linkEntityDispatchSubscription(ctx, entity) {
+	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
+	const target = dispatchPolicy?.targets[0];
+	if (!target) return;
+	await linkStreamToTargetSubscription(ctx, target, entity);
+}
+async function unlinkEntityDispatchSubscription(ctx, entity) {
+	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
+	const target = dispatchPolicy?.targets[0];
+	if (!target) return;
+	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
+	await ctx.streamClient.removeSubscriptionStream(subscriptionId, entity.streams.main).catch((err) => {
+		serverLog.warn(`[dispatch-policy] failed to remove stream from subscription`, {
+			subscriptionId,
+			stream: entity.streams.main
+		}, err);
+	});
+}
+async function linkStreamToTargetSubscription(ctx, target, entity) {
+	const streamPath = entity.streams.main;
+	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
+	const existing = await ctx.streamClient.getSubscription(subscriptionId);
+	if (target.type === `runner`) {
+		const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
+		if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
+		const wakeStream = runner.wake_stream || runnerWakeStream(target.runnerId);
+		await ctx.streamClient.ensure(wakeStream, { contentType: `application/json` });
+		if (!existing) {
+			await ctx.streamClient.putSubscription(subscriptionId, {
+				type: `pull-wake`,
+				streams: [streamPath],
+				wake_stream: wakeStream,
+				description: `Electric Agents runner ${target.runnerId}`
+			});
+			return;
+		}
+		await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
+		return;
+	}
+	const webhookUrl = rewriteLoopbackWebhookUrl(target.url);
+	if (!webhookUrl) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Webhook dispatch target must include a valid URL`, 400);
+	const forwardUrl = appendPathToUrl(ctx.publicUrl, `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`);
+	if (!existing) await ctx.streamClient.putSubscription(subscriptionId, {
+		type: `webhook`,
+		streams: [streamPath],
+		webhook: { url: forwardUrl },
+		description: `Electric Agents webhook ${subscriptionId}`
+	});
+	else await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
+	await ctx.pgDb.insert(subscriptionWebhooks).values({
+		tenantId: ctx.service,
+		subscriptionId,
+		webhookUrl
+	}).onConflictDoUpdate({
+		target: [subscriptionWebhooks.tenantId, subscriptionWebhooks.subscriptionId],
+		set: { webhookUrl }
+	});
+}
+
+//#endregion
+//#region src/principal.ts
+const PRINCIPAL_KINDS = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function parsePrincipalKey(input) {
+	const colon = input.indexOf(`:`);
+	if (colon <= 0) throw new Error(`Invalid principal key`);
+	const kind = input.slice(0, colon);
+	const id = input.slice(colon + 1);
+	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
+	if (!id || id.includes(`/`)) throw new Error(`Invalid principal id`);
+	const key = `${kind}:${id}`;
+	return {
+		kind,
+		id,
+		key,
+		url: `/principal/${encodeURIComponent(key)}`
+	};
+}
+function principalUrl(key) {
+	return parsePrincipalKey(key).url;
+}
+function principalKeyFromUrl(url) {
+	if (!url.startsWith(`/principal/`)) return null;
+	const segment = url.slice(`/principal/`.length);
+	if (!segment || segment.includes(`/`)) return null;
+	try {
+		const key = decodeURIComponent(segment);
+		return parsePrincipalKey(key).key;
+	} catch {
+		return null;
+	}
+}
+const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
+	`framework`,
+	`auth-sync`,
+	`dev-local`
+]);
+function isBuiltInSystemPrincipalUrl(url) {
+	if (!url?.startsWith(`/principal/`)) return false;
+	try {
+		const key = principalKeyFromUrl(url);
+		if (!key) return false;
+		const principal = parsePrincipalKey(key);
+		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
+	} catch {
+		return false;
+	}
+}
+function principalFromCreatedBy(createdBy) {
+	if (!createdBy) return void 0;
+	const key = principalKeyFromUrl(createdBy);
+	if (!key) return {
+		url: createdBy,
+		key: null
+	};
+	const principal = parsePrincipalKey(key);
+	return {
+		url: principal.url,
+		key: principal.key,
+		kind: principal.kind,
+		id: principal.id
+	};
+}
+const principalIdentityStateSchema = Type.Object({
+	kind: Type.Union([
+		Type.Literal(`user`),
+		Type.Literal(`agent`),
+		Type.Literal(`service`),
+		Type.Literal(`system`)
+	]),
+	id: Type.String(),
+	key: Type.String(),
+	url: Type.String(),
+	updated_at: Type.String(),
+	display_name: Type.Optional(Type.String()),
+	email: Type.Optional(Type.String()),
+	avatar_url: Type.Optional(Type.String()),
+	auth_provider: Type.Optional(Type.String()),
+	auth_subject: Type.Optional(Type.String()),
+	claims: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	created_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
+const principalUpdateIdentityMessageSchema = Type.Object({ identity: principalIdentityStateSchema }, { additionalProperties: false });
+
 //#endregion
 //#region src/manifest-side-effects.ts
 function isRecord$1(value) {
@@ -1804,25 +2061,11 @@ function extractTraceContext(headers) {
 
 //#endregion
 //#region src/entity-manager.ts
+function createInitialQueuePosition(date) {
+	return `${String(date.getTime()).padStart(16, `0`)}:a0`;
+}
 const DEFAULT_FORK_WAIT_TIMEOUT_MS = 12e4;
 const DEFAULT_FORK_WAIT_POLL_MS = 250;
-function applyTypeDefaultSubscriptionScope$1(policy, typeDefault) {
-	const target = policy.targets[0];
-	const defaultTarget = typeDefault?.targets[0];
-	if (!target || !defaultTarget?.subscription_id) return policy;
-	if (!sameDispatchDestination$1(target, defaultTarget)) return policy;
-	if (target.subscription_id === defaultTarget.subscription_id) return policy;
-	return { targets: [{
-		...target,
-		subscription_id: defaultTarget.subscription_id
-	}] };
-}
-function sameDispatchDestination$1(a, b) {
-	if (a.type !== b.type) return false;
-	if (a.type === `runner` && b.type === `runner`) return a.runnerId === b.runnerId;
-	if (a.type === `webhook` && b.type === `webhook`) return a.url === b.url;
-	return false;
-}
 function sleep(ms) {
 	return new Promise((resolve$1) => setTimeout(resolve$1, ms));
 }
@@ -1893,6 +2136,7 @@ var EntityManager = class {
 	}
 	async registerEntityType(req) {
 		if (!req.name) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: name`, 400);
+		if (req.name === `principal`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Entity type "principal" is built in and cannot be registered or updated`, 400);
 		if (req.name.startsWith(`_`)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Entity type names starting with "_" are reserved`, 400);
 		if (!req.description) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: description`, 400);
 		this.validateSchema(req.creation_schema);
@@ -1919,10 +2163,63 @@ var EntityManager = class {
 		return stored;
 	}
 	async deleteEntityType(name) {
+		if (name === `principal`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Entity type "principal" is built in and cannot be deleted`, 400);
 		const existing = await this.registry.getEntityType(name);
 		if (!existing) throw new ElectricAgentsError(ErrCodeNotFound, `Entity type "${name}" not found`, 404);
 		await this.registry.deleteEntityType(name);
 	}
+	async ensurePrincipalEntityType() {
+		const now = new Date().toISOString();
+		return await this.registry.ensureEntityType({
+			name: `principal`,
+			description: `built-in principal entity`,
+			inbox_schemas: { update_identity: principalUpdateIdentityMessageSchema },
+			state_schemas: { identity: principalIdentityStateSchema },
+			revision: 1,
+			created_at: now,
+			updated_at: now
+		});
+	}
+	async ensurePrincipal(principal) {
+		const existing = await this.registry.getEntity(principal.url);
+		if (existing) return existing;
+		await this.ensurePrincipalEntityType();
+		try {
+			const entity = await this.spawn(`principal`, {
+				instance_id: principal.key,
+				args: {
+					kind: principal.kind,
+					id: principal.id,
+					key: principal.key
+				},
+				tags: {
+					principal_kind: principal.kind,
+					principal_id: principal.id
+				},
+				created_by: principal.url
+			});
+			const now = new Date().toISOString();
+			await this.streamClient.append(entity.streams.main, this.encodeChangeEvent({
+				type: `identity`,
+				key: `self`,
+				value: {
+					kind: principal.kind,
+					id: principal.id,
+					key: principal.key,
+					url: principal.url,
+					created_at: now,
+					updated_at: now
+				}
+			}));
+			return entity;
+		} catch (error) {
+			if (error instanceof ElectricAgentsError && error.code === ErrCodeDuplicateURL) {
+				const raced = await this.registry.getEntity(principal.url);
+				if (raced) return raced;
+			}
+			throw error;
+		}
+	}
 	/**
 	* Spawn a new entity of the given type with durable streams.
 	*/
@@ -1938,6 +2235,7 @@ var EntityManager = class {
 		});
 	}
 	async spawnInner(typeName, req) {
+		if (typeName === `principal` && req.created_by !== principalUrl(req.instance_id)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Principal entities are built in and can only be materialized by the system`, 400);
 		if (typeName.startsWith(`_`)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Entity type names starting with "_" are reserved`, 400);
 		const entityType = await this.registry.getEntityType(typeName);
 		if (!entityType) throw new ElectricAgentsError(ErrCodeUnknownEntityType, `Entity type "${typeName}" not found`, 404);
@@ -1949,7 +2247,7 @@ var EntityManager = class {
 		const instanceId = req.instance_id || randomUUID();
 		if (instanceId.includes(`/`)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `instance_id must not contain forward slashes`, 400);
 		const writeToken = randomUUID();
-		const entityURL = `/${typeName}/${instanceId}`;
+		const entityURL = typeName === `principal` ? principalUrl(instanceId) : `/${typeName}/${instanceId}`;
 		const mainPath = `${entityURL}/main`;
 		const errorPath = `${entityURL}/error`;
 		const subscriptionId = `${typeName}-handler`;
@@ -1961,7 +2259,7 @@ var EntityManager = class {
 			parentEntity = await this.registry.getEntity(req.parent);
 			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$1(parentEntity.dispatch_policy, entityType.default_dispatch_policy) : entityType.default_dispatch_policy;
+		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 now = Date.now();
 		const entityData = {
 			type: typeName,
@@ -1980,6 +2278,7 @@ var EntityManager = class {
 			inbox_schemas: entityType.inbox_schemas,
 			state_schemas: entityType.state_schemas,
 			created_at: now,
+			created_by: req.created_by ?? parentEntity?.created_by,
 			updated_at: now
 		};
 		if (req.parent) entityData.parent = req.parent;
@@ -2009,7 +2308,7 @@ var EntityManager = class {
 			const inboxEvent = entityStateSchema.inbox.insert({
 				key: `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
 				value: {
-					from: req.parent ?? `spawn`,
+					from: req.created_by ?? req.parent ?? `spawn`,
 					payload: req.initialMessage,
 					timestamp: msgNow
 				}
@@ -2552,10 +2851,10 @@ var EntityManager = class {
 					changed = true;
 				}
 			}
-			if (typeof next.from === `string`) {
-				const forkFrom = entityUrlMap.get(next.from);
-				if (forkFrom) {
-					next.from = forkFrom;
+			if (typeof next.senderUrl === `string`) {
+				const forkSender = entityUrlMap.get(next.senderUrl);
+				if (forkSender) {
+					next.senderUrl = forkSender;
 					changed = true;
 				}
 			}
@@ -2621,6 +2920,7 @@ var EntityManager = class {
 		const fireAtRaw = manifest.fireAt;
 		const producerId = manifest.producerId;
 		const targetUrl = manifest.targetUrl;
+		const senderUrl = typeof manifest.senderUrl === `string` ? manifest.senderUrl : ownerEntityUrl;
 		if (typeof fireAtRaw !== `string` || typeof producerId !== `string` || typeof targetUrl !== `string`) {
 			serverLog.warn(`[agent-server] invalid forked future_send manifest entry for ${ownerEntityUrl}/${manifestKey}`);
 			return;
@@ -2632,7 +2932,7 @@ var EntityManager = class {
 		}
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
-			from: typeof manifest.from === `string` ? manifest.from : ownerEntityUrl,
+			from: senderUrl,
 			payload: manifest.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof manifest.messageType === `string` ? manifest.messageType : void 0,
@@ -2646,6 +2946,7 @@ var EntityManager = class {
 					kind: `schedule`,
 					scheduleType: `future_send`,
 					targetUrl,
+					senderUrl,
 					fireAt: fireAt.toISOString(),
 					producerId,
 					status: `pending`
@@ -2673,9 +2974,14 @@ var EntityManager = class {
 		const value = {
 			from: req.from,
 			payload: req.payload,
-			timestamp: now
+			timestamp: now,
+			mode: req.mode ?? `immediate`,
+			status: req.mode === `queued` || req.mode === `paused` ? `pending` : `processed`
 		};
 		if (req.type) value.message_type = req.type;
+		if (req.position) value.position = req.position;
+		else if (value.mode === `queued` || value.mode === `paused`) value.position = createInitialQueuePosition(new Date(now));
+		if (value.status === `processed`) value.processed_at = now;
 		const envelope = entityStateSchema.inbox.insert({
 			key,
 			value
@@ -2687,11 +2993,47 @@ var EntityManager = class {
 				return;
 			}
 			await this.streamClient.append(entity.streams.main, encoded);
+			if (entity.type === `principal` && req.type === `update_identity`) {
+				const identity = req.payload?.identity;
+				await this.streamClient.append(entity.streams.main, this.encodeChangeEvent({
+					type: `identity`,
+					key: `self`,
+					value: identity
+				}));
+			}
 		} catch (err) {
 			if (this.isClosedStreamError(err)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
 			throw err;
 		}
 	}
+	async updateInboxMessage(entityUrl, key, req) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		if (entity.status === `stopped`) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+		const now = new Date().toISOString();
+		const value = {};
+		if (`payload` in req) value.payload = req.payload;
+		if (req.position !== void 0) value.position = req.position;
+		if (req.mode !== void 0) value.mode = req.mode;
+		if (req.status !== void 0) {
+			value.status = req.status;
+			if (req.status === `processed`) value.processed_at = now;
+			if (req.status === `cancelled`) value.cancelled_at = now;
+		}
+		if (Object.keys(value).length === 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `No inbox fields to update`, 400);
+		const envelope = entityStateSchema.inbox.update({
+			key,
+			value
+		});
+		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
+	}
+	async deleteInboxMessage(entityUrl, key) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		if (entity.status === `stopped`) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+		const envelope = entityStateSchema.inbox.delete({ key });
+		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
+	}
 	async setTag(entityUrl, key, req, token) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
@@ -2777,7 +3119,7 @@ var EntityManager = class {
 	async upsertFutureSendSchedule(ownerEntityUrl, req) {
 		if (!this.scheduler) throw new Error(`Scheduler not configured`);
 		const targetUrl = req.targetUrl ?? ownerEntityUrl;
-		const from = req.from ?? ownerEntityUrl;
+		const from = req.senderUrl ?? ownerEntityUrl;
 		const fireAt = new Date(req.fireAt);
 		if (Number.isNaN(fireAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid fireAt timestamp: ${req.fireAt}`, 400);
 		await this.validateSendRequest(targetUrl, {
@@ -2805,9 +3147,9 @@ var EntityManager = class {
 					scheduleType: `future_send`,
 					fireAt: fireAt.toISOString(),
 					targetUrl,
+					senderUrl: from,
 					payload: req.payload,
 					producerId,
-					...req.from ? { from: req.from } : {},
 					...req.messageType ? { messageType: req.messageType } : {},
 					status: `pending`
 				}
@@ -2821,9 +3163,9 @@ var EntityManager = class {
 			scheduleType: `future_send`,
 			fireAt: fireAt.toISOString(),
 			targetUrl,
+			senderUrl: from,
 			payload: req.payload,
 			producerId,
-			...req.from ? { from: req.from } : {},
 			...req.messageType ? { messageType: req.messageType } : {},
 			status: `pending`
 		}, { txid });
@@ -2861,7 +3203,9 @@ var EntityManager = class {
 			from: req.from,
 			payload: req.payload,
 			key: req.key,
-			type: req.type
+			type: req.type,
+			mode: req.mode,
+			position: req.position
 		}, fireAt);
 	}
 	/**
@@ -3011,6 +3355,7 @@ var EntityManager = class {
 	* Add new input/output schema keys to an entity type directly in Postgres.
 	*/
 	async amendSchemas(typeName, schemas) {
+		if (typeName === `principal`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Entity type "principal" is built in and cannot be amended`, 400);
 		this.validateSchemaMap(schemas.inbox_schemas);
 		this.validateSchemaMap(schemas.state_schemas);
 		const existing = await this.registry.getEntityType(typeName);
@@ -3060,9 +3405,11 @@ var EntityManager = class {
 				url: entity.url,
 				streams: entity.streams,
 				tags: entity.tags,
-				spawnArgs: entity.spawn_args
+				spawnArgs: entity.spawn_args,
+				createdBy: entity.created_by
 			},
-			triggerEvent: `message_received`
+			principal: principalFromCreatedBy(entity.created_by),
+			triggerEvent: `inbox`
 		};
 	}
 	validateSchema(schema) {
@@ -3102,6 +3449,7 @@ var EntityManager = class {
 			}
 		}
 		if (!req.from) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: from`, 400);
+		if (entity.type === `principal` && req.type === `update_identity` && !isBuiltInSystemPrincipalUrl(req.from)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Only built-in system principals can update principal identity`, 403);
 		if (req.payload === void 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: payload`, 400);
 		return entity;
 	}
@@ -4501,6 +4849,7 @@ var ElectricAgentsTenantRuntime = class {
 		const fireAtRaw = value.fireAt;
 		const producerId = value.producerId;
 		const targetUrl = value.targetUrl;
+		const senderUrl = typeof value.senderUrl === `string` ? value.senderUrl : ownerEntityUrl;
 		if (typeof fireAtRaw !== `string` || typeof producerId !== `string` || typeof targetUrl !== `string`) {
 			serverLog.warn(`[agent-server] invalid future_send manifest entry for ${ownerEntityUrl}/${manifestKey}`);
 			return;
@@ -4512,7 +4861,7 @@ var ElectricAgentsTenantRuntime = class {
 		}
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
-			from: typeof value.from === `string` ? value.from : ownerEntityUrl,
+			from: senderUrl,
 			payload: value.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof value.messageType === `string` ? value.messageType : void 0,
@@ -4526,6 +4875,7 @@ var ElectricAgentsTenantRuntime = class {
 					kind: `schedule`,
 					scheduleType: `future_send`,
 					targetUrl,
+					senderUrl,
 					fireAt: fireAt.toISOString(),
 					producerId,
 					status: `pending`
@@ -5374,6 +5724,7 @@ var AgentsHost = class {
 		for (const runtime of runtimes) await this.startTenantRuntime(runtime);
 	}
 	async startTenantRuntime(runtime) {
+		await runtime.manager.ensurePrincipalEntityType();
 		if (this.rehydrateTenantOnStart) await runtime.rehydrateCronSchedules();
 		if (this.startEntityBridgeManager) await this.entityProjector.loadTenantBridges(runtime.serviceId, runtime.registry);
 	}
@@ -5391,6 +5742,7 @@ var AgentsHost = class {
 			scheduler,
 			entityBridgeManager: this.entityProjector.forTenant(serviceId, registry)
 		});
+		await runtime.manager.ensurePrincipalEntityType();
 		return runtime;
 	}
 	createStreamClient(config) {
@@ -5573,30 +5925,6 @@ function validateParsedBody(schema, parsed) {
 	};
 }
 
-//#endregion
-//#region src/utils/webhook-url.ts
-function rewriteLoopbackWebhookUrl(value) {
-	if (!value) return void 0;
-	const rewriteTarget = process.env.ELECTRIC_AGENTS_REWRITE_LOOPBACK_WEBHOOKS_TO?.trim();
-	if (!rewriteTarget) return value;
-	const url = new URL(value);
-	if (!isLoopbackHostname(url.hostname)) return value;
-	if (rewriteTarget.includes(`://`)) {
-		const target = new URL(rewriteTarget);
-		url.protocol = target.protocol;
-		url.username = target.username;
-		url.password = target.password;
-		url.hostname = target.hostname;
-		url.port = target.port;
-		return url.toString();
-	}
-	url.host = rewriteTarget;
-	return url.toString();
-}
-function isLoopbackHostname(hostname) {
-	return hostname === `localhost` || hostname === `127.0.0.1` || hostname === `::1`;
-}
-
 //#endregion
 //#region src/routing/tenant-stream-paths.ts
 function withoutLeadingSlash(path$1) {
@@ -5956,122 +6284,6 @@ async function proxyElectric(request, ctx) {
 	});
 }
 
-//#endregion
-//#region src/routing/dispatch-policy.ts
-function subscriptionIdForDispatchTarget(target) {
-	if (target.subscription_id) return target.subscription_id;
-	if (target.type === `runner`) return `runner:${target.runnerId}`;
-	const digest = createHash(`sha256`).update(target.url).digest(`hex`);
-	return `webhook:${digest.slice(0, 16)}`;
-}
-function subscriptionIdForEntityDispatchTarget(target, entityUrl) {
-	const base = subscriptionIdForDispatchTarget(target);
-	if (!target.subscription_id) return base;
-	const digest = createHash(`sha256`).update(entityUrl).digest(`hex`);
-	return `${base}:${digest.slice(0, 16)}`;
-}
-async function resolveEffectiveDispatchPolicyForSpawn(ctx, typeName, opts) {
-	if (opts.dispatchPolicy) return opts.dispatchPolicy;
-	const entityType = await ctx.entityManager.registry.getEntityType(typeName);
-	if (opts.parent) {
-		const parent = await ctx.entityManager.registry.getEntity(opts.parent);
-		if (parent?.dispatch_policy) return applyTypeDefaultSubscriptionScope(parent.dispatch_policy, entityType?.default_dispatch_policy);
-	}
-	return entityType?.default_dispatch_policy;
-}
-async function resolveEffectiveDispatchPolicyForEntity(ctx, entity) {
-	if (entity.dispatch_policy) return entity.dispatch_policy;
-	const entityType = await ctx.entityManager.registry.getEntityType(entity.type);
-	return entityType?.default_dispatch_policy;
-}
-async function backfillEntityDispatchPolicy(ctx, entity) {
-	if (entity.dispatch_policy) return entity;
-	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
-	if (!dispatchPolicy) return entity;
-	return await ctx.entityManager.registry.updateEntityDispatchPolicy(entity.url, dispatchPolicy) ?? {
-		...entity,
-		dispatch_policy: dispatchPolicy
-	};
-}
-function applyTypeDefaultSubscriptionScope(policy, typeDefault) {
-	const target = policy.targets[0];
-	const defaultTarget = typeDefault?.targets[0];
-	if (!target || !defaultTarget?.subscription_id) return policy;
-	if (!sameDispatchDestination(target, defaultTarget)) return policy;
-	if (target.subscription_id === defaultTarget.subscription_id) return policy;
-	return { targets: [{
-		...target,
-		subscription_id: defaultTarget.subscription_id
-	}] };
-}
-function sameDispatchDestination(a, b) {
-	if (a.type !== b.type) return false;
-	if (a.type === `runner` && b.type === `runner`) return a.runnerId === b.runnerId;
-	if (a.type === `webhook` && b.type === `webhook`) return a.url === b.url;
-	return false;
-}
-async function assertDispatchPolicyAllowed(ctx, policy) {
-	const target = policy?.targets[0];
-	if (!target || target.type !== `runner`) return;
-	const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
-	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
-	if (!ctx.authenticatedUser) throw new ElectricAgentsError(ErrCodeUnauthorized, `Authentication is required for runner-targeted dispatch`, 401);
-	if (runner.owner_user_id !== ctx.authenticatedUser.userId) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires the authenticated owner`, 403);
-}
-async function linkEntityDispatchSubscription(ctx, entity) {
-	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
-	const target = dispatchPolicy?.targets[0];
-	if (!target) return;
-	await linkStreamToTargetSubscription(ctx, target, entity);
-}
-async function unlinkEntityDispatchSubscription(ctx, entity) {
-	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
-	const target = dispatchPolicy?.targets[0];
-	if (!target) return;
-	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
-	await ctx.streamClient.removeSubscriptionStream(subscriptionId, entity.streams.main).catch(() => {});
-}
-async function linkStreamToTargetSubscription(ctx, target, entity) {
-	const streamPath = entity.streams.main;
-	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
-	const existing = await ctx.streamClient.getSubscription(subscriptionId);
-	if (target.type === `runner`) {
-		const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
-		if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
-		const wakeStream = runner.wake_stream || runnerWakeStream(target.runnerId);
-		await ctx.streamClient.ensure(wakeStream, { contentType: `application/json` });
-		if (!existing) {
-			await ctx.streamClient.putSubscription(subscriptionId, {
-				type: `pull-wake`,
-				streams: [streamPath],
-				wake_stream: wakeStream,
-				description: `Electric Agents runner ${target.runnerId}`
-			});
-			return;
-		}
-		await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
-		return;
-	}
-	const webhookUrl = rewriteLoopbackWebhookUrl(target.url);
-	if (!webhookUrl) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Webhook dispatch target must include a valid URL`, 400);
-	const forwardUrl = appendPathToUrl(ctx.publicUrl, `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`);
-	if (!existing) await ctx.streamClient.putSubscription(subscriptionId, {
-		type: `webhook`,
-		streams: [streamPath],
-		webhook: { url: forwardUrl },
-		description: `Electric Agents webhook ${subscriptionId}`
-	});
-	else await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
-	await ctx.pgDb.insert(subscriptionWebhooks).values({
-		tenantId: ctx.service,
-		subscriptionId,
-		webhookUrl
-	}).onConflictDoUpdate({
-		target: [subscriptionWebhooks.tenantId, subscriptionWebhooks.subscriptionId],
-		set: { webhookUrl }
-	});
-}
-
 //#endregion
 //#region src/routing/entities-router.ts
 const stringRecordSchema = Type.Record(Type.String(), Type.String());
@@ -6104,11 +6316,33 @@ const spawnBodySchema = Type.Object({
 	}))
 });
 const sendBodySchema = Type.Object({
-	from: Type.Optional(Type.String()),
 	payload: Type.Optional(Type.Unknown()),
 	key: Type.Optional(Type.String()),
 	type: Type.Optional(Type.String()),
-	afterMs: Type.Optional(Type.Number())
+	mode: Type.Optional(Type.Union([
+		Type.Literal(`immediate`),
+		Type.Literal(`queued`),
+		Type.Literal(`paused`),
+		Type.Literal(`steer`)
+	])),
+	position: Type.Optional(Type.String()),
+	afterMs: Type.Optional(Type.Number()),
+	from: Type.Optional(Type.String())
+});
+const inboxMessageBodySchema = Type.Object({
+	payload: Type.Optional(Type.Unknown()),
+	position: Type.Optional(Type.String()),
+	mode: Type.Optional(Type.Union([
+		Type.Literal(`immediate`),
+		Type.Literal(`queued`),
+		Type.Literal(`paused`),
+		Type.Literal(`steer`)
+	])),
+	status: Type.Optional(Type.Union([
+		Type.Literal(`pending`),
+		Type.Literal(`processed`),
+		Type.Literal(`cancelled`)
+	]))
 });
 const forkBodySchema = Type.Object({
 	instance_id: Type.Optional(Type.String()),
@@ -6127,8 +6361,8 @@ const scheduleBodySchema = Type.Union([Type.Object({
 	payload: Type.Unknown(),
 	targetUrl: Type.Optional(Type.String()),
 	fireAt: Type.String(),
-	from: Type.Optional(Type.String()),
-	messageType: Type.Optional(Type.String())
+	messageType: Type.Optional(Type.String()),
+	from: Type.Optional(Type.String())
 })]);
 const entitiesRegisterBodySchema = Type.Object({ tags: Type.Optional(stringRecordSchema) });
 const entitiesRouter = Router({ base: `/_electric/entities` });
@@ -6139,6 +6373,8 @@ entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity);
 entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity);
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity);
 entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), sendEntity);
+entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), updateInboxMessage);
+entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, deleteInboxMessage);
 entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), forkEntity);
 entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withSchema(setTagBodySchema), setTag);
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, removeTag);
@@ -6147,6 +6383,11 @@ entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEn
 function entityUrlFromSegments(type, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
+	if (type === `principal`) try {
+		return principalUrl(decodeURIComponent(instanceId));
+	} catch {
+		return null;
+	}
 	return `/${type}/${instanceId}`;
 }
 function firstQueryValue$1(value) {
@@ -6156,12 +6397,27 @@ function requireExistingEntityRoute(request) {
 	if (!request.entityRoute) throw new Error(`existing entity middleware did not run`);
 	return request.entityRoute;
 }
+function rejectPrincipalEntityMutation(request, action) {
+	const { entity } = requireExistingEntityRoute(request);
+	if (entity.type !== `principal`) return void 0;
+	return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be ${action}`);
+}
 async function withExistingEntity(request, ctx) {
 	const entityUrl = entityUrlFromSegments(request.params.type, request.params.instanceId);
 	if (!entityUrl) return void 0;
 	const entity = await ctx.entityManager.registry.getEntity(entityUrl);
 	if (!entity) {
 		const entityType = await ctx.entityManager.registry.getEntityType(request.params.type);
+		if (request.params.type === `principal`) try {
+			const materialized = await ctx.entityManager.ensurePrincipal(parsePrincipalKey(decodeURIComponent(request.params.instanceId)));
+			request.entityRoute = {
+				entityUrl,
+				entity: materialized
+			};
+			return void 0;
+		} catch (error) {
+			return apiError(400, ErrCodeInvalidRequest, error instanceof Error ? error.message : `Invalid principal`);
+		}
 		if (entityType) return apiError(404, ErrCodeNotFound, `Entity not found at ${entityUrl}`);
 		return apiError(404, ErrCodeUnknownEntityType, `Entity type "${request.params.type}" not found`);
 	}
@@ -6173,6 +6429,7 @@ async function withExistingEntity(request, ctx) {
 }
 async function withSpawnableEntityType(request, ctx) {
 	if (!entityUrlFromSegments(request.params.type, request.params.instanceId)) return void 0;
+	if (request.params.type === `principal`) return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be spawned directly`);
 	const entityType = await ctx.entityManager.registry.getEntityType(request.params.type);
 	if (!entityType) return apiError(404, ErrCodeUnknownEntityType, `Entity type "${request.params.type}" not found`);
 	return void 0;
@@ -6181,7 +6438,8 @@ async function listEntities({ query }, ctx) {
 	const { entities: entities$1 } = await ctx.entityManager.registry.listEntities({
 		type: firstQueryValue$1(query.type),
 		status: firstQueryValue$1(query.status),
-		parent: firstQueryValue$1(query.parent)
+		parent: firstQueryValue$1(query.parent),
+		created_by: firstQueryValue$1(query.created_by)
 	});
 	return json(entities$1.map((entity) => toPublicEntity(entity)));
 }
@@ -6191,6 +6449,8 @@ async function registerEntitiesSource(request, ctx) {
 	return json(result);
 }
 async function upsertSchedule(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `scheduled`);
+	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);
 	const scheduleId = decodeURIComponent(request.params.scheduleId);
@@ -6206,12 +6466,13 @@ async function upsertSchedule(request, ctx) {
 		return json(result);
 	}
 	if (parsed.scheduleType === `future_send`) {
+		if (parsed.from !== void 0 && parsed.from !== ctx.principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from must match Electric-Principal`);
 		const result = await ctx.entityManager.upsertFutureSendSchedule(entityUrl, {
 			id: scheduleId,
 			payload: parsed.payload,
 			targetUrl: parsed.targetUrl,
 			fireAt: parsed.fireAt,
-			from: parsed.from,
+			senderUrl: ctx.principal.url,
 			messageType: parsed.messageType
 		});
 		return json(result);
@@ -6219,11 +6480,15 @@ async function upsertSchedule(request, ctx) {
 	throw new Error(`schedule schema accepted an unknown scheduleType`);
 }
 async function deleteSchedule(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unscheduled`);
+	if (principalMutationError) return principalMutationError;
 	const { entityUrl } = requireExistingEntityRoute(request);
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return json(result);
 }
 async function setTag(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
+	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);
 	const token = writeTokenFromRequest(request);
@@ -6231,12 +6496,16 @@ async function setTag(request, ctx) {
 	return json(toPublicEntity(updated));
 }
 async function removeTag(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `untagged`);
+	if (principalMutationError) return principalMutationError;
 	const { entityUrl } = requireExistingEntityRoute(request);
 	const token = writeTokenFromRequest(request);
 	const updated = await ctx.entityManager.removeTag(entityUrl, decodeURIComponent(request.params.tagKey), token);
 	return json(toPublicEntity(updated));
 }
 async function forkEntity(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `forked`);
+	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
@@ -6252,27 +6521,47 @@ async function forkEntity(request, ctx) {
 }
 async function sendEntity(request, ctx) {
 	const parsed = routeBody(request);
+	const principal = ctx.principal;
+	if (parsed.from !== void 0 && parsed.from !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from must match Electric-Principal`);
+	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	if (!entity.dispatch_policy) {
 		const updatedEntity = await backfillEntityDispatchPolicy(ctx, entity);
 		await linkEntityDispatchSubscription(ctx, updatedEntity);
 	}
 	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, {
-		from: parsed.from,
+		from: principal.url,
 		payload: parsed.payload,
 		key: parsed.key,
-		type: parsed.type
+		type: parsed.type,
+		mode: parsed.mode,
+		position: parsed.position
 	}, new Date(Date.now() + parsed.afterMs));
 	else await ctx.entityManager.send(entityUrl, {
-		from: parsed.from,
+		from: principal.url,
 		payload: parsed.payload,
 		key: parsed.key,
-		type: parsed.type
+		type: parsed.type,
+		mode: parsed.mode,
+		position: parsed.position
 	});
 	return status(204);
 }
+async function updateInboxMessage(request, ctx) {
+	const parsed = routeBody(request);
+	const { entityUrl } = requireExistingEntityRoute(request);
+	await ctx.entityManager.updateInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey), parsed);
+	return status(204);
+}
+async function deleteInboxMessage(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	await ctx.entityManager.deleteInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey));
+	return status(204);
+}
 async function spawnEntity(request, ctx) {
 	const parsed = routeBody(request);
+	const principal = ctx.principal;
+	await ctx.entityManager.ensurePrincipal(principal);
 	const dispatchPolicy = await resolveEffectiveDispatchPolicyForSpawn(ctx, request.params.type, {
 		dispatchPolicy: parsed.dispatch_policy,
 		parent: parsed.parent
@@ -6285,13 +6574,14 @@ async function spawnEntity(request, ctx) {
 		parent: parsed.parent,
 		dispatch_policy: dispatchPolicy,
 		initialMessage: void 0,
-		wake: parsed.wake
+		wake: parsed.wake,
+		created_by: principal.url
 	});
-	await linkEntityDispatchSubscription(ctx, entity);
 	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(entity.url, {
-		from: parsed.parent ?? `spawn`,
+		from: principal.url,
 		payload: parsed.initialMessage
 	});
+	await linkEntityDispatchSubscription(ctx, entity);
 	return json({
 		...toPublicEntity(entity),
 		txid: entity.txid
@@ -6307,6 +6597,8 @@ function headEntity() {
 	return status(200);
 }
 async function killEntity(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `killed`);
+	if (principalMutationError) return principalMutationError;
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	await unlinkEntityDispatchSubscription(ctx, entity);
 	const result = await ctx.entityManager.kill(entityUrl);
@@ -6453,7 +6745,7 @@ function applyCors(response) {
 	const headers = new Headers(response.headers);
 	headers.set(`access-control-allow-origin`, `*`);
 	headers.set(`access-control-allow-methods`, `GET, POST, PUT, PATCH, DELETE, OPTIONS`);
-	headers.set(`access-control-allow-headers`, `content-type, authorization, electric-claim-token, x-electric-asserted-email, x-electric-asserted-name, ngrok-skip-browser-warning`);
+	headers.set(`access-control-allow-headers`, `content-type, authorization, electric-claim-token, ngrok-skip-browser-warning`);
 	headers.set(`access-control-expose-headers`, `*`);
 	return new Response(response.body, {
 		status: response.status,
@@ -6533,9 +6825,9 @@ function firstQueryValue(value) {
 }
 async function registerRunner(request, ctx) {
 	const parsed = routeBody(request);
-	const ownerUserId = parsed.owner_user_id ?? ctx.authenticatedUser?.userId;
+	const ownerUserId = parsed.owner_user_id ?? ctx.principal?.key;
 	if (!ownerUserId) throw new ElectricAgentsError(ErrCodeInvalidRequest, `owner_user_id is required when no authenticated user is present`, 400);
-	if (ctx.authenticatedUser && ownerUserId !== ctx.authenticatedUser.userId) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
+	if (ctx.principal && ownerUserId !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
 	const runner = await ctx.entityManager.registry.createRunner({
 		id: parsed.id,
 		ownerUserId,
@@ -6549,8 +6841,8 @@ async function registerRunner(request, ctx) {
 }
 async function listRunners(request, ctx) {
 	const requestedOwner = firstQueryValue(request.query.owner_user_id);
-	if (ctx.authenticatedUser && requestedOwner && requestedOwner !== ctx.authenticatedUser.userId) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
-	const runners$1 = await ctx.entityManager.registry.listRunners({ ownerUserId: ctx.authenticatedUser?.userId ?? requestedOwner });
+	if (ctx.principal && requestedOwner && requestedOwner !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
+	const runners$1 = await ctx.entityManager.registry.listRunners({ ownerUserId: ctx.principal?.key ?? requestedOwner });
 	return json(runners$1);
 }
 async function getRunner(request, ctx) {
@@ -6588,9 +6880,8 @@ async function setRunnerStatus(request, ctx, adminStatus) {
 }
 async function claimWake(request, ctx) {
 	const runnerId = routeParam$1(request, `id`);
-	if (!ctx.authenticatedUser) throw new ElectricAgentsError(ErrCodeUnauthorized, `Authentication is required to claim runner work`, 401);
 	const runner = await requireRunner(ctx, runnerId);
-	if (runner.owner_user_id !== ctx.authenticatedUser.userId) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner claim requires the authenticated owner`, 403);
+	if (ctx.principal && runner.owner_user_id !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner claim requires the authenticated owner`, 403);
 	if (runner.admin_status !== `enabled`) throw new ElectricAgentsError(ErrCodeNotRunning, `Runner is disabled`, 409);
 	const parsed = routeBody(request);
 	const expectedSubscriptionId = subscriptionIdForDispatchTarget({
@@ -6622,8 +6913,8 @@ async function requireRunner(ctx, runnerId) {
 	return runner;
 }
 function assertRunnerOwnerIfAuthenticated(ctx, ownerUserId) {
-	if (!ctx.authenticatedUser) return;
-	if (ownerUserId === ctx.authenticatedUser.userId) return;
+	if (!ctx.principal) return;
+	if (ownerUserId === ctx.principal.key) return;
 	throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner access requires the authenticated owner`, 403);
 }
 async function notificationFromClaim(ctx, input) {
@@ -6680,8 +6971,10 @@ async function notificationFromClaim(ctx, input) {
 			url: entity.url,
 			streams: entity.streams,
 			tags: entity.tags,
-			spawnArgs: entity.spawn_args
-		}
+			spawnArgs: entity.spawn_args,
+			createdBy: entity.created_by
+		},
+		principal: principalFromCreatedBy(entity.created_by)
 	};
 }