@electric-ax/agents-server 0.4.0 → 0.4.1

package/dist/entrypoint.js

@@ -32,36 +32,6 @@ var __export = (target, all) => {
 	});
 };
 
-//#endregion
-//#region src/dev-asserted-auth.ts
-const DEV_ASSERTED_EMAIL_HEADER = `x-electric-asserted-email`;
-const DEV_ASSERTED_NAME_HEADER = `x-electric-asserted-name`;
-function clean(value) {
-	const trimmed = value?.trim();
-	return trimmed || void 0;
-}
-function createDevAssertedAuthenticateRequest(options) {
-	if (!options.enabled) return void 0;
-	return (request) => {
-		const email = clean(request.headers.get(DEV_ASSERTED_EMAIL_HEADER)) ?? clean(options.defaultEmail);
-		const name = clean(request.headers.get(DEV_ASSERTED_NAME_HEADER)) ?? clean(options.defaultName);
-		const userId = email ?? name;
-		if (!userId) return null;
-		return {
-			userId,
-			email,
-			name
-		};
-	};
-}
-function devAssertedAuthOptionsFromEnv(env = process.env) {
-	return {
-		enabled: env.ELECTRIC_AGENTS_DEV_ASSERTED_AUTH === `1`,
-		defaultEmail: env.ELECTRIC_ASSERTED_AUTH_EMAIL,
-		defaultName: env.ELECTRIC_ASSERTED_AUTH_NAME
-	};
-}
-
 //#endregion
 //#region src/db/schema.ts
 var schema_exports = {};
@@ -106,6 +76,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`),
@@ -116,6 +87,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')`)
 ]);
@@ -491,6 +463,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
 	};
@@ -1672,6 +1645,103 @@ async function proxyElectric(request, ctx) {
 	});
 }
 
+//#endregion
+//#region src/principal.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+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;
+	}
+}
+function getPrincipalFromRequest(request) {
+	const value = request.headers.get(ELECTRIC_PRINCIPAL_HEADER);
+	return value ? parsePrincipalKey(value) : null;
+}
+function getDevPrincipal() {
+	return parsePrincipalKey(`system:dev-local`);
+}
+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/dispatch-policy-schema.ts
 const nonEmptyStringSchema = Type.String({ minLength: 1 });
@@ -1913,6 +1983,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;
@@ -1952,6 +2040,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,
@@ -1997,6 +2086,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);
@@ -2283,6 +2373,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,
@@ -2430,25 +2521,11 @@ function buildManifestWakeRegistration(subscriberUrl, manifest, manifestKey) {
 
 //#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));
 }
@@ -2519,6 +2596,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);
@@ -2545,10 +2623,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.
 	*/
@@ -2564,6 +2695,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);
@@ -2575,7 +2707,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`;
@@ -2587,7 +2719,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,
@@ -2606,6 +2738,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;
@@ -2635,7 +2768,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
 				}
@@ -3178,10 +3311,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;
 				}
 			}
@@ -3247,6 +3380,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;
@@ -3258,7 +3392,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,
@@ -3272,6 +3406,7 @@ var EntityManager = class {
 					kind: `schedule`,
 					scheduleType: `future_send`,
 					targetUrl,
+					senderUrl,
 					fireAt: fireAt.toISOString(),
 					producerId,
 					status: `pending`
@@ -3299,9 +3434,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
@@ -3313,11 +3453,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);
@@ -3403,7 +3579,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, {
@@ -3431,9 +3607,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`
 				}
@@ -3447,9 +3623,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 });
@@ -3487,7 +3663,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);
 	}
 	/**
@@ -3637,6 +3815,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);
@@ -3686,9 +3865,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) {
@@ -3728,6 +3909,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;
 	}
@@ -3842,8 +4024,7 @@ async function assertDispatchPolicyAllowed(ctx, policy) {
 	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);
+	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);
@@ -3856,7 +4037,12 @@ async function unlinkEntityDispatchSubscription(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(() => {});
+	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;
@@ -3931,11 +4117,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()),
@@ -3954,8 +4162,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` });
@@ -3966,6 +4174,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);
@@ -3974,6 +4184,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) {
@@ -3983,12 +4198,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`);
 	}
@@ -4000,6 +4230,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;
@@ -4008,7 +4239,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)));
 }
@@ -4018,6 +4250,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);
@@ -4033,12 +4267,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);
@@ -4046,11 +4281,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);
@@ -4058,12 +4297,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);
@@ -4079,27 +4322,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
@@ -4112,11 +4375,12 @@ 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
 	});
 	return json({
@@ -4134,6 +4398,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);
@@ -4280,7 +4546,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,
@@ -4360,9 +4626,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,
@@ -4376,8 +4642,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) {
@@ -4415,9 +4681,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({
@@ -4449,8 +4714,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) {
@@ -4507,8 +4772,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)
 	};
 }
 
@@ -4916,7 +5183,7 @@ const ENTITY_SHAPE_COLUMNS = [
 	`updated_at`
 ];
 function parseElectricOffset(offset) {
-	if (offset === `-1` || offset === `now`) return offset;
+	if (offset === `-1`) return offset;
 	return /^\d+_\d+$/.test(offset) ? offset : null;
 }
 function sameMember(left, right) {
@@ -6128,6 +6395,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;
@@ -6139,7 +6407,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,
@@ -6153,6 +6421,7 @@ var ElectricAgentsTenantRuntime = class {
 					kind: `schedule`,
 					scheduleType: `future_send`,
 					targetUrl,
+					senderUrl,
 					fireAt: fireAt.toISOString(),
 					producerId,
 					status: `pending`
@@ -7062,6 +7331,7 @@ var ElectricAgentsServer = class {
 			});
 			this.electricAgentsManager = this.standaloneRuntime.manager;
 			this.entityBridgeManager = this.standaloneRuntime.entityBridgeManager;
+			await this.electricAgentsManager.ensurePrincipalEntityType();
 			const serverAdapter = createServerAdapter((request) => this.handleRequest(request));
 			const server = createServer(serverAdapter);
 			this.server = server;
@@ -7139,13 +7409,30 @@ var ElectricAgentsServer = class {
 	}
 	async handleRequest(request) {
 		if (!this._url || !this.standaloneRuntime || !this.electricAgentsManager || !this.entityBridgeManager || !this.pgDb || !this.streamsAgent || !this.options.durableStreamsUrl) return new Response(null, { status: 503 });
-		return await ossServerRouter.fetch(request, await this.buildTenantContext(request));
+		try {
+			return await ossServerRouter.fetch(request, await this.buildTenantContext(request));
+		} catch (error) {
+			if (error instanceof ElectricAgentsError) return apiError(error.status, error.code, error.message, error.details);
+			throw error;
+		}
+	}
+	allowDevPrincipalFallback() {
+		if (this.options.allowDevPrincipalFallback !== void 0) return this.options.allowDevPrincipalFallback;
+		return process.env.ELECTRIC_INSECURE === `true` || process.env.NODE_ENV !== `production` || Boolean(this.options.durableStreamsServer);
 	}
 	async buildTenantContext(request) {
 		if (!this.standaloneRuntime || !this.electricAgentsManager || !this.entityBridgeManager || !this.pgDb || !this.streamsAgent || !this.options.durableStreamsUrl) throw new Error(`agents-server runtime is not started`);
+		let principal;
+		try {
+			principal = await this.options.authenticateRequest?.(request) ?? getPrincipalFromRequest(request);
+		} catch (error) {
+			throw new ElectricAgentsError(ErrCodeInvalidRequest, error instanceof Error ? error.message : `Invalid principal`, 400);
+		}
+		if (!principal && this.allowDevPrincipalFallback()) principal = getDevPrincipal();
+		if (!principal) throw new ElectricAgentsError(ErrCodeUnauthorized, `Missing Electric-Principal`, 401);
 		return {
 			service: this.tenantId,
-			authenticatedUser: await this.options.authenticateRequest?.(request) ?? void 0,
+			principal,
 			publicUrl: this.publicUrl,
 			localUrl: this._url,
 			durableStreamsUrl: this.options.durableStreamsUrl,
@@ -7223,9 +7510,7 @@ function resolveElectricAgentsEntrypointOptions(env = process.env, cwd = process
 	const electricUrl = readEnv(env, [`ELECTRIC_AGENTS_ELECTRIC_URL`, `ELECTRIC_URL`]);
 	const electricSecret = readEnv(env, [`ELECTRIC_AGENTS_ELECTRIC_SECRET`]);
 	const baseUrl = readEnv(env, [`ELECTRIC_AGENTS_BASE_URL`, `BASE_URL`]);
-	const authenticateRequest = createDevAssertedAuthenticateRequest(devAssertedAuthOptionsFromEnv(env));
 	return {
-		...authenticateRequest ? { authenticateRequest } : {},
 		service: readEnv(env, [`ELECTRIC_AGENTS_SERVICE`, `SERVICE`]),
 		tenantId: readEnv(env, [`ELECTRIC_AGENTS_TENANT_ID`, `TENANT_ID`]),
 		baseUrl: baseUrl ? validateUrl(`base URL`, baseUrl) : void 0,