@electric-ax/agents-server 0.4.6 → 0.4.9

package/dist/index.cjs

@@ -104,7 +104,7 @@ const entities = (0, drizzle_orm_pg_core.pgTable)(`entities`, {
 	(0, drizzle_orm_pg_core.index)(`idx_entities_parent`).on(table.tenantId, table.parent),
 	(0, drizzle_orm_pg_core.index)(`idx_entities_created_by`).on(table.tenantId, table.createdBy),
 	(0, drizzle_orm_pg_core.index)(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
-	(0, drizzle_orm_pg_core.check)(`chk_entities_status`, drizzle_orm.sql`${table.status} IN ('spawning', 'running', 'idle', 'stopped')`)
+	(0, drizzle_orm_pg_core.check)(`chk_entities_status`, drizzle_orm.sql`${table.status} IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed')`)
 ]);
 const users = (0, drizzle_orm_pg_core.pgTable)(`users`, {
 	tenantId: (0, drizzle_orm_pg_core.text)(`tenant_id`).notNull().default(`default`),
@@ -358,12 +358,25 @@ async function runMigrations(postgresUrl) {
 
 //#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;
@@ -384,6 +397,27 @@ function assertRunnerAdminStatus(s) {
 	if (!VALID_RUNNER_ADMIN_STATUSES.has(s)) throw new Error(`Invalid runner admin status: "${s}"`);
 	return s;
 }
+function assertEntitySignal(s) {
+	if (!VALID_ENTITY_SIGNALS.has(s)) throw new Error(`Invalid entity signal: "${s}"`);
+	return s;
+}
+function isTerminalEntityStatus(status$4) {
+	return status$4 === `stopped` || status$4 === `killed`;
+}
+function rejectsNormalWrites(status$4) {
+	return status$4 === `stopping` || isTerminalEntityStatus(status$4);
+}
+function expectedSignalStatus(status$4, signal) {
+	switch (signal) {
+		case `SIGKILL`: return `killed`;
+		case `SIGTERM`: return status$4 === `idle` ? `stopped` : `stopping`;
+		case `SIGSTOP`: return status$4 === `idle` ? `paused` : status$4;
+		case `SIGCONT`: return status$4 === `paused` ? `idle` : status$4;
+		case `SIGINT`:
+		case `SIGHUP`:
+		case `SIGUSR`: return status$4;
+	}
+}
 /** Strip internal fields (write_token, subscription_id) from an entity. */
 function toPublicEntity(entity) {
 	return {
@@ -405,6 +439,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`;
@@ -806,7 +841,7 @@ var PostgresRegistry = class {
 		};
 	}
 	async updateStatus(entityUrl, status$4) {
-		const whereClause = status$4 === `stopped` ? this.entityWhere(entityUrl) : (0, drizzle_orm.and)(this.entityWhere(entityUrl), (0, drizzle_orm.ne)(entities.status, `stopped`));
+		const whereClause = isTerminalEntityStatus(status$4) ? this.entityWhere(entityUrl) : (0, drizzle_orm.and)(this.entityWhere(entityUrl), (0, drizzle_orm.ne)(entities.status, `stopped`), (0, drizzle_orm.ne)(entities.status, `killed`));
 		await this.db.update(entities).set({
 			status: status$4,
 			updatedAt: Date.now()
@@ -814,13 +849,17 @@ var PostgresRegistry = class {
 	}
 	async updateStatusWithTxid(entityUrl, status$4) {
 		return await this.db.transaction(async (tx) => {
-			const whereClause = status$4 === `stopped` ? this.entityWhere(entityUrl) : (0, drizzle_orm.and)(this.entityWhere(entityUrl), (0, drizzle_orm.ne)(entities.status, `stopped`));
-			await tx.update(entities).set({
+			const rows = await tx.update(entities).set({
 				status: status$4,
 				updatedAt: Date.now()
-			}).where(whereClause);
-			const result = await tx.execute(drizzle_orm.sql`SELECT pg_current_xact_id()::xid::text AS txid`);
-			return parseInt(result[0].txid);
+			}).where((0, drizzle_orm.and)(this.entityWhere(entityUrl), (0, drizzle_orm.ne)(entities.status, `stopped`), (0, drizzle_orm.ne)(entities.status, `killed`))).returning({ txid: drizzle_orm.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((0, drizzle_orm.and)((0, drizzle_orm.eq)(entities.url, entityUrl), (0, drizzle_orm.ne)(entities.status, `stopped`), (0, drizzle_orm.ne)(entities.status, `killed`))).returning({ txid: drizzle_orm.sql`pg_current_xact_id()::xid::text` });
+			return rows[0] ? parseInt(rows[0].txid) : null;
 		});
 	}
 	async setEntityTag(url, key, value) {
@@ -2447,6 +2486,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];
@@ -2611,6 +2653,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` ? (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(manifest.sourceRef) : void 0;
+		if (manifest.sourceType === `webhook`) {
+			if (typeof config?.streamUrl === `string`) return config.streamUrl;
+			if (typeof config?.endpointKey === `string`) return (0, __electric_ax_agents_runtime.getWebhookStreamPath)(config.endpointKey, typeof config.bucket === `string` ? config.bucket : void 0);
+		}
 		return void 0;
 	}
 	if (manifest.kind === `shared-state`) return typeof manifest.id === `string` ? (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(manifest.id) : void 0;
@@ -2672,6 +2718,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));
 }
@@ -2896,7 +2943,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 = __electric_ax_agents_runtime.entityStateSchema.entityCreated.insert({
@@ -3123,16 +3171,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;
@@ -3588,6 +3636,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 = __electric_ax_agents_runtime.entityStateSchema.inbox.insert({
 			key,
 			value
@@ -3615,7 +3668,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;
@@ -3636,7 +3689,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 = __electric_ax_agents_runtime.entityStateSchema.inbox.delete({ key });
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
 	}
@@ -3644,7 +3697,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;
@@ -3656,7 +3709,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);
@@ -3785,6 +3838,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 = (0, node_crypto.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 = (0, __electric_ax_agents_runtime.eventSourceSubscriptionManifestKey)(req.id);
+		const txid = (0, node_crypto.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.
 	*/
@@ -3909,26 +3991,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 = __electric_ax_agents_runtime.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()}-${(0, node_crypto.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$4, signal) {
+		if (signal === `SIGKILL`) return {
+			status: `killed`,
+			handled: true,
+			outcome: `transitioned`,
+			unregisterWakes: true
+		};
+		if (signal === `SIGTERM`) {
+			if (status$4 === `idle` || status$4 === `paused`) return {
+				status: `stopped`,
+				handled: true,
+				outcome: `transitioned`,
+				unregisterWakes: true
+			};
+			if (status$4 === `running`) return {
+				status: `stopping`,
+				handled: false,
+				outcome: `transitioned`,
+				unregisterWakes: false
+			};
+		}
+		if (status$4 === `paused` && signal !== `SIGCONT`) return {
+			status: status$4,
+			handled: true,
+			outcome: `ignored`,
+			unregisterWakes: false
+		};
+		if (signal === `SIGSTOP` && (status$4 === `idle` || status$4 === `running`)) return {
+			status: `paused`,
+			handled: status$4 === `idle`,
+			outcome: `transitioned`,
+			unregisterWakes: false
+		};
+		if (signal === `SIGCONT` && status$4 === `paused`) return {
+			status: `idle`,
+			handled: false,
+			outcome: `transitioned`,
+			unregisterWakes: false
+		};
+		return {
+			status: status$4,
+			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;
@@ -4044,7 +4231,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) {
@@ -5009,7 +5196,8 @@ var ElectricAgentsTenantRuntime = class {
 		const primaryStream = `${entityUrl}/main`;
 		const callbacks = await this.db.select().from(consumerCallbacks).where((0, drizzle_orm.and)((0, drizzle_orm.eq)(consumerCallbacks.tenantId, this.serviceId), (0, drizzle_orm.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);
 	}
 };
@@ -6559,7 +6747,8 @@ const spawnBodySchema = __sinclair_typebox.Type.Object({
 		condition: wakeConditionSchema,
 		debounceMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
 		timeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
-		includeResponse: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean())
+		includeResponse: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean()),
+		manifestKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 	}))
 });
 const sendBodySchema = __sinclair_typebox.Type.Object({
@@ -6596,6 +6785,20 @@ const forkBodySchema = __sinclair_typebox.Type.Object({
 	waitTimeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number())
 });
 const setTagBodySchema = __sinclair_typebox.Type.Object({ value: __sinclair_typebox.Type.String() });
+const entitySignalSchema = __sinclair_typebox.Type.Union([
+	__sinclair_typebox.Type.Literal(`SIGINT`),
+	__sinclair_typebox.Type.Literal(`SIGHUP`),
+	__sinclair_typebox.Type.Literal(`SIGTERM`),
+	__sinclair_typebox.Type.Literal(`SIGKILL`),
+	__sinclair_typebox.Type.Literal(`SIGSTOP`),
+	__sinclair_typebox.Type.Literal(`SIGCONT`),
+	__sinclair_typebox.Type.Literal(`SIGUSR`)
+]);
+const signalBodySchema = __sinclair_typebox.Type.Object({
+	signal: entitySignalSchema,
+	reason: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	payload: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Unknown())
+});
 const scheduleBodySchema = __sinclair_typebox.Type.Union([__sinclair_typebox.Type.Object({
 	scheduleType: __sinclair_typebox.Type.Literal(`cron`),
 	expression: __sinclair_typebox.Type.String(),
@@ -6611,6 +6814,22 @@ const scheduleBodySchema = __sinclair_typebox.Type.Union([__sinclair_typebox.Typ
 	messageType: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
 	from: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 })]);
+const subscriptionLifetimeSchema = __sinclair_typebox.Type.Union([
+	__sinclair_typebox.Type.Object({ kind: __sinclair_typebox.Type.Literal(`until_entity_stopped`) }),
+	__sinclair_typebox.Type.Object({
+		kind: __sinclair_typebox.Type.Literal(`expires_at`),
+		at: __sinclair_typebox.Type.String()
+	}),
+	__sinclair_typebox.Type.Object({ kind: __sinclair_typebox.Type.Literal(`manual`) })
+]);
+const eventSourceSubscriptionBodySchema = __sinclair_typebox.Type.Object({
+	sourceKey: __sinclair_typebox.Type.String(),
+	bucketKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	params: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Unknown())),
+	filterKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	lifetime: __sinclair_typebox.Type.Optional(subscriptionLifetimeSchema),
+	reason: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
+});
 const entitiesRegisterBodySchema = __sinclair_typebox.Type.Object({ tags: __sinclair_typebox.Type.Optional(stringRecordSchema) });
 const entitiesRouter = (0, itty_router.Router)({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
@@ -6619,6 +6838,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);
@@ -6627,6 +6847,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;
@@ -6733,6 +6955,47 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return (0, itty_router.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 = (0, __electric_ax_agents_runtime.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: (0, __electric_ax_agents_runtime.buildEventSourceManifestEntry)(resolved)
+	});
+	return (0, itty_router.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 (0, itty_router.json)(result);
+}
 async function setTag(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
 	if (principalMutationError) return principalMutationError;
@@ -6822,11 +7085,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 (0, itty_router.json)({
 		...toPublicEntity(entity),
 		txid: entity.txid
@@ -6850,6 +7115,22 @@ async function killEntity(request, ctx) {
 	ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main);
 	return (0, itty_router.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 (0, itty_router.json)(result);
+}
 
 //#endregion
 //#region src/routing/entity-types-router.ts
@@ -7330,7 +7611,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
@@ -7429,6 +7710,7 @@ const callbackForwardBodySchema = __sinclair_typebox.Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = (0, itty_router.Router)({ base: `/_electric` });
 internalRouter.get(`/health`, () => (0, itty_router.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);
@@ -7532,6 +7814,13 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return (0, itty_router.status)(204);
 }
+async function listEventSources(_request, ctx) {
+	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
+	return (0, itty_router.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);
@@ -7598,7 +7887,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 (0, itty_router.json)({ done: true });
 			}
@@ -7741,9 +8030,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})`);
@@ -7803,13 +8092,19 @@ exports.AgentsHost = AgentsHost
 exports.DEFAULT_TENANT_ID = DEFAULT_TENANT_ID
 exports.StreamClient = StreamClient
 exports.UnregisteredTenantError = UnregisteredTenantError
+exports.assertEntitySignal = assertEntitySignal
+exports.assertEntityStatus = assertEntityStatus
 exports.createDb = createDb
 exports.createEd25519WebhookSigner = createEd25519WebhookSigner
+exports.expectedSignalStatus = expectedSignalStatus
 exports.getDefaultWebhookSigner = getDefaultWebhookSigner
 exports.globalRouter = globalRouter
+exports.isTerminalEntityStatus = isTerminalEntityStatus
 exports.isUnregisteredTenantError = isUnregisteredTenantError
 exports.pathPrefixedSingleTenantDurableStreamsRoutingAdapter = pathPrefixedSingleTenantDurableStreamsRoutingAdapter
+exports.rejectsNormalWrites = rejectsNormalWrites
 exports.runMigrations = runMigrations
 exports.streamRootDurableStreamsRoutingAdapter = streamRootDurableStreamsRoutingAdapter
 exports.tenantRootDurableStreamsRoutingAdapter = tenantRootDurableStreamsRoutingAdapter
+exports.toPublicEntity = toPublicEntity
 exports.webhookSigningMetadata = webhookSigningMetadata