@electric-ax/agents-server 0.4.6 → 0.4.9

package/dist/entrypoint.js

@@ -4,7 +4,7 @@ import { DurableStreamTestServer } from "@durable-streams/server";
 import { createServer } from "node:http";
 import { createServerAdapter } from "@whatwg-node/server";
 import { Agent } from "undici";
-import { appendPathToUrl, assertTags, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import fs, { existsSync } from "node:fs";
 import path, { dirname, resolve } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
@@ -90,7 +90,7 @@ const entities = pgTable(`entities`, {
 	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')`)
+	check(`chk_entities_status`, sql`${table.status} IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed')`)
 ]);
 const users = pgTable(`users`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
@@ -367,12 +367,25 @@ function responseHeaders(response) {
 
 //#endregion
 //#region src/electric-agents-types.ts
+const ENTITY_SIGNALS = [
+	`SIGINT`,
+	`SIGHUP`,
+	`SIGTERM`,
+	`SIGKILL`,
+	`SIGSTOP`,
+	`SIGCONT`,
+	`SIGUSR`
+];
 const VALID_ENTITY_STATUSES = new Set([
 	`spawning`,
 	`running`,
 	`idle`,
-	`stopped`
+	`paused`,
+	`stopping`,
+	`stopped`,
+	`killed`
 ]);
+const VALID_ENTITY_SIGNALS = new Set(ENTITY_SIGNALS);
 function assertEntityStatus(s) {
 	if (!VALID_ENTITY_STATUSES.has(s)) throw new Error(`Invalid entity status: "${s}"`);
 	return s;
@@ -393,6 +406,12 @@ function assertRunnerAdminStatus(s) {
 	if (!VALID_RUNNER_ADMIN_STATUSES.has(s)) throw new Error(`Invalid runner admin status: "${s}"`);
 	return s;
 }
+function isTerminalEntityStatus(status$1) {
+	return status$1 === `stopped` || status$1 === `killed`;
+}
+function rejectsNormalWrites(status$1) {
+	return status$1 === `stopping` || isTerminalEntityStatus(status$1);
+}
 /** Strip internal fields (write_token, subscription_id) from an entity. */
 function toPublicEntity(entity) {
 	return {
@@ -414,6 +433,7 @@ const ErrCodeUnauthorized = `UNAUTHORIZED`;
 const ErrCodeNotFound = `NOT_FOUND`;
 const ErrCodeNotRunning = `NOT_RUNNING`;
 const ErrCodeInvalidRequest = `INVALID_REQUEST`;
+const ErrCodeInvalidSignal = `INVALID_SIGNAL`;
 const ErrCodeUnknownEntityType = `UNKNOWN_ENTITY_TYPE`;
 const ErrCodeSchemaValidationFailed = `SCHEMA_VALIDATION_FAILED`;
 const ErrCodeUnknownMessageType = `UNKNOWN_MESSAGE_TYPE`;
@@ -2274,7 +2294,7 @@ var PostgresRegistry = class {
 		};
 	}
 	async updateStatus(entityUrl, status$1) {
-		const whereClause = status$1 === `stopped` ? this.entityWhere(entityUrl) : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`));
+		const whereClause = isTerminalEntityStatus(status$1) ? this.entityWhere(entityUrl) : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`), ne(entities.status, `killed`));
 		await this.db.update(entities).set({
 			status: status$1,
 			updatedAt: Date.now()
@@ -2282,13 +2302,17 @@ var PostgresRegistry = class {
 	}
 	async updateStatusWithTxid(entityUrl, status$1) {
 		return await this.db.transaction(async (tx) => {
-			const whereClause = status$1 === `stopped` ? this.entityWhere(entityUrl) : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`));
-			await tx.update(entities).set({
+			const rows = await tx.update(entities).set({
 				status: status$1,
 				updatedAt: Date.now()
-			}).where(whereClause);
-			const result = await tx.execute(sql`SELECT pg_current_xact_id()::xid::text AS txid`);
-			return parseInt(result[0].txid);
+			}).where(and(this.entityWhere(entityUrl), ne(entities.status, `stopped`), ne(entities.status, `killed`))).returning({ txid: sql`pg_current_xact_id()::xid::text` });
+			return rows[0] ? parseInt(rows[0].txid) : null;
+		});
+	}
+	async touchEntityWithTxid(entityUrl) {
+		return await this.db.transaction(async (tx) => {
+			const rows = await tx.update(entities).set({ updatedAt: Date.now() }).where(and(eq(entities.url, entityUrl), ne(entities.status, `stopped`), ne(entities.status, `killed`))).returning({ txid: sql`pg_current_xact_id()::xid::text` });
+			return rows[0] ? parseInt(rows[0].txid) : null;
 		});
 	}
 	async setEntityTag(url, key, value) {
@@ -2644,6 +2668,10 @@ function extractManifestSourceUrl(manifest) {
 		}
 		if (manifest.sourceType === `entities`) return typeof manifest.sourceRef === `string` ? `/_entities/${manifest.sourceRef}` : void 0;
 		if (manifest.sourceType === `db`) return typeof manifest.sourceRef === `string` ? getSharedStateStreamPath(manifest.sourceRef) : void 0;
+		if (manifest.sourceType === `webhook`) {
+			if (typeof config?.streamUrl === `string`) return config.streamUrl;
+			if (typeof config?.endpointKey === `string`) return getWebhookStreamPath(config.endpointKey, typeof config.bucket === `string` ? config.bucket : void 0);
+		}
 		return void 0;
 	}
 	if (manifest.kind === `shared-state`) return typeof manifest.id === `string` ? getSharedStateStreamPath(manifest.id) : void 0;
@@ -2705,6 +2733,7 @@ function createInitialQueuePosition(date) {
 }
 const DEFAULT_FORK_WAIT_TIMEOUT_MS = 12e4;
 const DEFAULT_FORK_WAIT_POLL_MS = 250;
+const SERVER_SIGNAL_SENDER = `/_electric/server`;
 function sleep(ms) {
 	return new Promise((resolve$1) => setTimeout(resolve$1, ms));
 }
@@ -2929,7 +2958,8 @@ var EntityManager = class {
 			debounceMs: req.wake.debounceMs,
 			timeoutMs: req.wake.timeoutMs,
 			oneShot: false,
-			includeResponse: req.wake.includeResponse
+			includeResponse: req.wake.includeResponse,
+			manifestKey: req.wake.manifestKey
 		});
 		const contentType = `application/json`;
 		const createdEvent = entityStateSchema.entityCreated.insert({
@@ -3156,16 +3186,16 @@ var EntityManager = class {
 			if (!root) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
 			if (root.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
 			const subtree = await this.listEntitySubtree(root);
-			const stopped = subtree.find((entity) => entity.status === `stopped`);
-			if (stopped) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork stopped entity "${stopped.url}"`, 409);
-			let active = subtree.filter((entity) => entity.status !== `idle`);
+			const stopped = subtree.find((entity) => isTerminalEntityStatus(entity.status));
+			if (stopped) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork terminal entity "${stopped.url}"`, 409);
+			let active = subtree.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
 			if (active.length === 0) {
 				this.addForkLocks(this.forkWorkLockedEntities, subtree.map((entity) => entity.url), workLocks);
 				const lockedRoot = await this.registry.getEntity(rootUrl);
 				if (!lockedRoot) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
 				const lockedSubtree = await this.listEntitySubtree(lockedRoot);
 				this.addForkLocks(this.forkWorkLockedEntities, lockedSubtree.map((entity) => entity.url), workLocks);
-				const lockedActive = lockedSubtree.filter((entity) => entity.status !== `idle`);
+				const lockedActive = lockedSubtree.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
 				if (lockedActive.length === 0) return lockedSubtree;
 				this.releaseForkLocks(this.forkWorkLockedEntities, workLocks);
 				active = lockedActive;
@@ -3621,6 +3651,11 @@ var EntityManager = class {
 		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 wakePausedEntity = entity.status === `paused` && req.mode !== `paused`;
+		if (wakePausedEntity) {
+			await this.registry.updateStatus(entityUrl, `idle`);
+			await this.entityBridgeManager?.onEntityChanged(entityUrl);
+		}
 		const envelope = entityStateSchema.inbox.insert({
 			key,
 			value
@@ -3648,7 +3683,7 @@ var EntityManager = class {
 	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);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		const now = new Date().toISOString();
 		const value = {};
 		if (`payload` in req) value.payload = req.payload;
@@ -3669,7 +3704,7 @@ var EntityManager = class {
 	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);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		const envelope = entityStateSchema.inbox.delete({ key });
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
 	}
@@ -3677,7 +3712,7 @@ var EntityManager = class {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
 		if (!this.isValidWriteToken(entity, token)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Invalid write token`, 401);
-		if (entity.status === `stopped`) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		if (typeof req.value !== `string`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Tag values must be strings`, 400);
 		const result = await this.registry.setEntityTag(entityUrl, key, req.value);
 		const updated = result.entity;
@@ -3689,7 +3724,7 @@ var EntityManager = class {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
 		if (!this.isValidWriteToken(entity, token)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Invalid write token`, 401);
-		if (entity.status === `stopped`) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		const result = await this.registry.removeEntityTag(entityUrl, key);
 		const updated = result.entity;
 		if (!updated) throw new ElectricAgentsError(ErrCodeEntityPersistFailed, `Entity not found after tag delete`, 500);
@@ -3818,6 +3853,35 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
+	async upsertEventSourceSubscription(entityUrl, req) {
+		const manifestKey = req.subscription.manifestKey;
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		await this.wakeRegistry.register({
+			tenantId: this.tenantId,
+			subscriberUrl: entityUrl,
+			sourceUrl: req.subscription.sourceUrl,
+			condition: {
+				on: `change`,
+				collections: [`webhook_event`],
+				ops: [`insert`]
+			},
+			oneShot: false,
+			manifestKey
+		});
+		return {
+			txid,
+			subscription: req.subscription
+		};
+	}
+	async deleteEventSourceSubscription(entityUrl, req) {
+		const manifestKey = eventSourceSubscriptionManifestKey(req.id);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
 	/**
 	* Register a wake subscription from a subscriber to a source entity.
 	*/
@@ -3942,26 +4006,131 @@ var EntityManager = class {
 			}
 		};
 	}
-	async kill(entityUrl) {
+	async signal(entityUrl, req) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
-		await this.wakeRegistry.unregisterBySubscriber(entityUrl, this.tenantId);
-		await this.wakeRegistry.unregisterBySource(entityUrl, this.tenantId);
-		const txid = await this.registry.updateStatusWithTxid(entityUrl, `stopped`);
-		if (this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
-		const stoppedEvent = entityStateSchema.entityStopped.insert({
-			key: `stopped`,
-			value: { timestamp: new Date().toISOString() }
+		if (isTerminalEntityStatus(entity.status)) throw new ElectricAgentsError(ErrCodeInvalidSignal, `Cannot signal a ${entity.status} entity`, 409);
+		const now = new Date();
+		const previousState = entity.status;
+		const handling = this.serverHandlingForSignal(previousState, req.signal);
+		const txid = handling.status === previousState ? await this.registry.touchEntityWithTxid(entityUrl) : await this.registry.updateStatusWithTxid(entityUrl, handling.status);
+		if (txid === null) throw new ElectricAgentsError(ErrCodeInvalidSignal, `Cannot signal entity because it is already terminal`, 409);
+		const key = `sig-${now.getTime()}-${randomUUID().slice(0, 8)}`;
+		const signalValue = {
+			signal: req.signal,
+			status: handling.handled ? `handled` : `unhandled`,
+			sender: SERVER_SIGNAL_SENDER,
+			timestamp: now.toISOString()
+		};
+		if (req.reason !== void 0) signalValue.reason = req.reason;
+		if (req.payload !== void 0) signalValue.payload = req.payload;
+		if (handling.handled) {
+			signalValue.handled_at = now.toISOString();
+			signalValue.handled_by = SERVER_SIGNAL_SENDER;
+			signalValue.outcome = handling.outcome;
+			signalValue.previous_state = previousState;
+			signalValue.new_state = handling.status;
+		}
+		const signalEvent = {
+			type: `signal`,
+			key,
+			value: signalValue,
+			headers: {
+				operation: `insert`,
+				timestamp: now.toISOString(),
+				txid: String(txid)
+			}
+		};
+		const shouldCloseStreams = isTerminalEntityStatus(handling.status);
+		await this.appendSignalEvent(entity, signalEvent, shouldCloseStreams);
+		if (!shouldCloseStreams) await this.evaluateWakes(entityUrl, signalEvent);
+		if (handling.unregisterWakes) {
+			await this.wakeRegistry.unregisterBySubscriber(entityUrl, this.tenantId);
+			await this.wakeRegistry.unregisterBySource(entityUrl, this.tenantId);
+		}
+		if (handling.status !== previousState && this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
+		return {
+			url: entityUrl,
+			signal: req.signal,
+			previous_state: previousState,
+			new_state: handling.status,
+			created_at: now.getTime(),
+			txid
+		};
+	}
+	async kill(entityUrl) {
+		const response = await this.signal(entityUrl, {
+			signal: `SIGKILL`,
+			reason: `Legacy kill command`
 		});
-		const eofData = this.encodeChangeEvent(stoppedEvent);
-		for (const streamPath of [entity.streams.main, entity.streams.error]) try {
-			await this.streamClient.append(streamPath, eofData, { close: true });
+		return { txid: response.txid };
+	}
+	serverHandlingForSignal(status$1, signal) {
+		if (signal === `SIGKILL`) return {
+			status: `killed`,
+			handled: true,
+			outcome: `transitioned`,
+			unregisterWakes: true
+		};
+		if (signal === `SIGTERM`) {
+			if (status$1 === `idle` || status$1 === `paused`) return {
+				status: `stopped`,
+				handled: true,
+				outcome: `transitioned`,
+				unregisterWakes: true
+			};
+			if (status$1 === `running`) return {
+				status: `stopping`,
+				handled: false,
+				outcome: `transitioned`,
+				unregisterWakes: false
+			};
+		}
+		if (status$1 === `paused` && signal !== `SIGCONT`) return {
+			status: status$1,
+			handled: true,
+			outcome: `ignored`,
+			unregisterWakes: false
+		};
+		if (signal === `SIGSTOP` && (status$1 === `idle` || status$1 === `running`)) return {
+			status: `paused`,
+			handled: status$1 === `idle`,
+			outcome: `transitioned`,
+			unregisterWakes: false
+		};
+		if (signal === `SIGCONT` && status$1 === `paused`) return {
+			status: `idle`,
+			handled: false,
+			outcome: `transitioned`,
+			unregisterWakes: false
+		};
+		return {
+			status: status$1,
+			handled: false,
+			outcome: `ignored`,
+			unregisterWakes: false
+		};
+	}
+	async appendSignalEvent(entity, signalEvent, closeStreams) {
+		const signalData = this.encodeChangeEvent(signalEvent);
+		if (!closeStreams) {
+			await this.streamClient.append(entity.streams.main, signalData);
+			return;
+		}
+		const errorCloseEvent = {
+			type: `signal`,
+			key: signalEvent.key,
+			value: signalEvent.value,
+			headers: signalEvent.headers
+		};
+		const errorSignalData = this.encodeChangeEvent(errorCloseEvent);
+		for (const [streamPath, data] of [[entity.streams.main, signalData], [entity.streams.error, errorSignalData]]) try {
+			await this.streamClient.append(streamPath, data, { close: true });
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			if (/closed/i.test(message) || /not found/i.test(message) || /404/.test(message) || /409/.test(message)) continue;
 			throw err;
 		}
-		return { txid };
 	}
 	async validateWriteEvent(entity, event) {
 		if (!entity.type) return null;
@@ -4077,7 +4246,7 @@ var EntityManager = class {
 	async validateSendRequest(entityUrl, 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);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		if (req.type && entity.type) {
 			const { inboxSchemas } = await this.getEffectiveSchemas(entity);
 			if (inboxSchemas) {
@@ -4250,6 +4419,9 @@ async function assertDispatchPolicyAllowed(ctx, policy) {
 	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
 	if (runner.owner_principal !== ctx.principal.url) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires the authenticated owner`, 403);
 }
+function shouldLinkDispatchBeforeInitialMessage(policy) {
+	return policy?.targets[0] !== void 0;
+}
 async function linkEntityDispatchSubscription(ctx, entity) {
 	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
 	const target = dispatchPolicy?.targets[0];
@@ -4338,7 +4510,8 @@ const spawnBodySchema = Type.Object({
 		condition: wakeConditionSchema,
 		debounceMs: Type.Optional(Type.Number()),
 		timeoutMs: Type.Optional(Type.Number()),
-		includeResponse: Type.Optional(Type.Boolean())
+		includeResponse: Type.Optional(Type.Boolean()),
+		manifestKey: Type.Optional(Type.String())
 	}))
 });
 const sendBodySchema = Type.Object({
@@ -4375,6 +4548,20 @@ const forkBodySchema = Type.Object({
 	waitTimeoutMs: Type.Optional(Type.Number())
 });
 const setTagBodySchema = Type.Object({ value: Type.String() });
+const entitySignalSchema = Type.Union([
+	Type.Literal(`SIGINT`),
+	Type.Literal(`SIGHUP`),
+	Type.Literal(`SIGTERM`),
+	Type.Literal(`SIGKILL`),
+	Type.Literal(`SIGSTOP`),
+	Type.Literal(`SIGCONT`),
+	Type.Literal(`SIGUSR`)
+]);
+const signalBodySchema = Type.Object({
+	signal: entitySignalSchema,
+	reason: Type.Optional(Type.String()),
+	payload: Type.Optional(Type.Unknown())
+});
 const scheduleBodySchema = Type.Union([Type.Object({
 	scheduleType: Type.Literal(`cron`),
 	expression: Type.String(),
@@ -4390,6 +4577,22 @@ const scheduleBodySchema = Type.Union([Type.Object({
 	messageType: Type.Optional(Type.String()),
 	from: Type.Optional(Type.String())
 })]);
+const subscriptionLifetimeSchema = Type.Union([
+	Type.Object({ kind: Type.Literal(`until_entity_stopped`) }),
+	Type.Object({
+		kind: Type.Literal(`expires_at`),
+		at: Type.String()
+	}),
+	Type.Object({ kind: Type.Literal(`manual`) })
+]);
+const eventSourceSubscriptionBodySchema = Type.Object({
+	sourceKey: Type.String(),
+	bucketKey: Type.Optional(Type.String()),
+	params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	filterKey: Type.Optional(Type.String()),
+	lifetime: Type.Optional(subscriptionLifetimeSchema),
+	reason: Type.Optional(Type.String())
+});
 const entitiesRegisterBodySchema = Type.Object({ tags: Type.Optional(stringRecordSchema) });
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
@@ -4398,6 +4601,7 @@ entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spa
 entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity);
 entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity);
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity);
+entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), signalEntity);
 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);
@@ -4406,6 +4610,8 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, removeTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, deleteSchedule);
+entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), upsertEventSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, deleteEventSourceSubscription);
 function entityUrlFromSegments(type, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -4512,6 +4718,47 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return json(result);
 }
+async function upsertEventSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `subscribed to event sources`);
+	if (principalMutationError) return principalMutationError;
+	const catalog = ctx.eventSources;
+	if (!catalog) return apiError(404, ErrCodeNotFound, `No event source catalog is configured`);
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const parsed = routeBody(request);
+	const source = await catalog.getEventSource(parsed.sourceKey);
+	if (!source) return apiError(404, ErrCodeNotFound, `Event source "${parsed.sourceKey}" not found`);
+	if (parsed.lifetime?.kind === `expires_at`) {
+		const expiresAt = new Date(parsed.lifetime.at);
+		if (Number.isNaN(expiresAt.getTime())) return apiError(400, ErrCodeInvalidRequest, `Invalid expires_at lifetime timestamp`);
+	}
+	let resolved;
+	try {
+		resolved = resolveEventSourceSubscription({
+			contract: source,
+			entityUrl,
+			request: {
+				...parsed,
+				id: decodeURIComponent(request.params.subscriptionId)
+			},
+			createdBy: `tool`
+		});
+	} catch (error) {
+		return apiError(400, ErrCodeInvalidRequest, error instanceof Error ? error.message : String(error));
+	}
+	await ctx.ensureEventSourceWakeSource?.(resolved.subscription.sourceUrl);
+	const result = await ctx.entityManager.upsertEventSourceSubscription(entityUrl, {
+		subscription: resolved.subscription,
+		manifest: buildEventSourceManifestEntry(resolved)
+	});
+	return json(result);
+}
+async function deleteEventSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unsubscribed from event sources`);
+	if (principalMutationError) return principalMutationError;
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.deleteEventSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
+	return json(result);
+}
 async function setTag(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
 	if (principalMutationError) return principalMutationError;
@@ -4601,11 +4848,13 @@ async function spawnEntity(request, ctx) {
 		wake: parsed.wake,
 		created_by: principal.url
 	});
-	await linkEntityDispatchSubscription(ctx, entity);
+	const linkBeforeInitialMessage = parsed.initialMessage !== void 0 && shouldLinkDispatchBeforeInitialMessage(dispatchPolicy);
+	if (linkBeforeInitialMessage) await linkEntityDispatchSubscription(ctx, entity);
 	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(entity.url, {
 		from: principal.url,
 		payload: parsed.initialMessage
 	});
+	if (!linkBeforeInitialMessage) await linkEntityDispatchSubscription(ctx, entity);
 	return json({
 		...toPublicEntity(entity),
 		txid: entity.txid
@@ -4629,6 +4878,22 @@ async function killEntity(request, ctx) {
 	ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main);
 	return json(result);
 }
+async function signalEntity(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `signaled`);
+	if (principalMutationError) return principalMutationError;
+	const parsed = routeBody(request);
+	const { entityUrl, entity } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.signal(entityUrl, {
+		signal: parsed.signal,
+		reason: parsed.reason,
+		payload: parsed.payload
+	});
+	if (result.new_state === `stopped` || result.new_state === `killed`) {
+		await unlinkEntityDispatchSubscription(ctx, entity);
+		ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main);
+	}
+	return json(result);
+}
 
 //#endregion
 //#region src/routing/entity-types-router.ts
@@ -5109,7 +5374,7 @@ async function notificationFromClaim(ctx, input) {
 	const primaryStream = withLeadingSlash(primary.path);
 	const entity = await ctx.entityManager.registry.getEntityByStream(primaryStream);
 	if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Claim stream is not attached to an entity`, 404);
-	if (entity.status === `stopped`) {
+	if (entity.status === `stopped` || entity.status === `paused`) {
 		await ctx.streamClient.releaseSubscription(input.subscriptionId, input.claim.token, {
 			wake_id: input.claim.wake_id,
 			generation: input.claim.generation
@@ -5208,6 +5473,7 @@ const callbackForwardBodySchema = Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = Router({ base: `/_electric` });
 internalRouter.get(`/health`, () => json({ status: `ok` }));
+internalRouter.get(`/event-sources`, listEventSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/webhook-forward/:subscriptionId`, webhookForward);
 internalRouter.post(`/callback-forward/:consumerId`, callbackForward);
@@ -5311,6 +5577,13 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return status(204);
 }
+async function listEventSources(_request, ctx) {
+	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
+	return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+}
+function isAgentVisibleEventSource(source) {
+	return source.agentVisible === true && source.status === `active`;
+}
 async function webhookForward(request, ctx) {
 	const subscriptionId = routeParam(request, `subscriptionId`);
 	const rootSpan = getRequestSpan(request);
@@ -5377,7 +5650,7 @@ async function webhookForward(request, ctx) {
 				serverLog.warn(`[webhook-forward] consumerCallbacks upsert failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
 			}) : void 0;
 			const [entity, enriched] = await Promise.all([entityPromise, enrichPromise]);
-			if (entity?.status === `stopped`) {
+			if (entity?.status === `stopped` || entity?.status === `paused`) {
 				if (upsertPromise) await upsertPromise;
 				return json({ done: true });
 			}
@@ -5520,9 +5793,9 @@ async function callbackForward(request, ctx) {
 				entityCleared = result?.entityCleared ?? false;
 			}
 			if (entity && (entityCleared || stillOwnsClaim)) {
-				await ctx.entityManager.registry.updateStatus(entity.url, `idle`);
+				await ctx.entityManager.registry.updateStatus(entity.url, entity.status === `stopping` ? `stopped` : `idle`);
 				await ctx.entityBridgeManager.onEntityChanged(entity.url);
-				serverLog.info(`[callback-forward] status updated to idle for ${entity.url}`);
+				serverLog.info(`[callback-forward] status updated after done for ${entity.url}`);
 			} else if (!entity) serverLog.warn(`[callback-forward] done received but no entity found for stream=${target.primaryStream}`);
 			if (stillOwnsClaim) ctx.runtime.claimWriteTokens.clearStream(ctx.service, target.primaryStream);
 			else if (entity) serverLog.info(`[callback-forward] done arrived after in-memory token evicted (stream=${target.primaryStream} consumer=${consumerId})`);
@@ -6875,7 +7148,8 @@ var ElectricAgentsTenantRuntime = class {
 		const primaryStream = `${entityUrl}/main`;
 		const callbacks = await this.db.select().from(consumerCallbacks).where(and(eq(consumerCallbacks.tenantId, this.serviceId), eq(consumerCallbacks.primaryStream, primaryStream))).limit(1);
 		if (callbacks.length > 0) return;
-		await this.manager.registry.updateStatus(entityUrl, `idle`);
+		const entity = await this.manager.registry.getEntity(entityUrl);
+		await this.manager.registry.updateStatus(entityUrl, entity?.status === `stopping` ? `stopped` : `idle`);
 		await this.entityBridgeManager.onEntityChanged(entityUrl);
 	}
 };
@@ -7890,6 +8164,8 @@ var ElectricAgentsServer = class {
 			streamClient: this.streamClient,
 			runtime: this.standaloneRuntime.runtime,
 			entityBridgeManager: this.entityBridgeManager,
+			...this.options.eventSources ? { eventSources: this.options.eventSources } : {},
+			...this.options.ensureEventSourceWakeSource ? { ensureEventSourceWakeSource: this.options.ensureEventSourceWakeSource } : {},
 			isShuttingDown: () => this.shuttingDown,
 			mockAgent: this.mockAgentBootstrap ? { runtime: this.mockAgentBootstrap.runtime } : void 0
 		};