@electric-ax/agents-server 0.4.5 → 0.4.7

package/dist/index.js

@@ -7,8 +7,8 @@ import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
 import { and, desc, eq, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
-import { createHash, randomUUID } from "node:crypto";
-import { appendPathToUrl, assertTags, buildTagsIndex, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, sourceRefForTags } from "@electric-ax/agents-runtime";
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from "node:crypto";
+import { appendPathToUrl, assertTags, buildTagsIndex, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
@@ -75,7 +75,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`),
@@ -329,12 +329,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;
@@ -355,6 +368,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$1) {
+	return status$1 === `stopped` || status$1 === `killed`;
+}
+function rejectsNormalWrites(status$1) {
+	return status$1 === `stopping` || isTerminalEntityStatus(status$1);
+}
+function expectedSignalStatus(status$1, signal) {
+	switch (signal) {
+		case `SIGKILL`: return `killed`;
+		case `SIGTERM`: return status$1 === `idle` ? `stopped` : `stopping`;
+		case `SIGSTOP`: return status$1 === `idle` ? `paused` : status$1;
+		case `SIGCONT`: return status$1 === `paused` ? `idle` : status$1;
+		case `SIGINT`:
+		case `SIGHUP`:
+		case `SIGUSR`: return status$1;
+	}
+}
 /** Strip internal fields (write_token, subscription_id) from an entity. */
 function toPublicEntity(entity) {
 	return {
@@ -376,6 +410,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`;
@@ -571,7 +606,7 @@ var PostgresRegistry = class {
 		const heartbeatAt = input.heartbeatAt ?? new Date();
 		await this.db.update(consumerClaims).set({
 			lastHeartbeatAt: heartbeatAt,
-			leaseExpiresAt: input.leaseExpiresAt ?? null,
+			...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
 			updatedAt: heartbeatAt
 		}).where(and(eq(consumerClaims.tenantId, this.tenantId), eq(consumerClaims.consumerId, input.consumerId), eq(consumerClaims.epoch, input.epoch)));
 	}
@@ -584,17 +619,24 @@ var PostgresRegistry = class {
 			updatedAt: releasedAt
 		}).where(and(eq(consumerClaims.tenantId, this.tenantId), eq(consumerClaims.consumerId, input.consumerId), eq(consumerClaims.epoch, input.epoch))).returning();
 		const claim = rows[0] ? this.rowToConsumerClaim(rows[0]) : null;
-		if (claim) await this.db.update(entityDispatchState).set({
-			activeConsumerId: null,
-			activeRunnerId: null,
-			activeEpoch: null,
-			activeClaimedAt: null,
-			activeLeaseExpiresAt: null,
-			lastReleasedAt: releasedAt,
-			lastCompletedAt: releasedAt,
-			updatedAt: releasedAt
-		}).where(and(eq(entityDispatchState.tenantId, this.tenantId), eq(entityDispatchState.entityUrl, claim.entity_url), eq(entityDispatchState.activeConsumerId, input.consumerId), eq(entityDispatchState.activeEpoch, input.epoch)));
-		return claim;
+		let entityCleared = false;
+		if (claim) {
+			const cleared = await this.db.update(entityDispatchState).set({
+				activeConsumerId: null,
+				activeRunnerId: null,
+				activeEpoch: null,
+				activeClaimedAt: null,
+				activeLeaseExpiresAt: null,
+				lastReleasedAt: releasedAt,
+				lastCompletedAt: releasedAt,
+				updatedAt: releasedAt
+			}).where(and(eq(entityDispatchState.tenantId, this.tenantId), eq(entityDispatchState.entityUrl, claim.entity_url), eq(entityDispatchState.activeConsumerId, input.consumerId), eq(entityDispatchState.activeEpoch, input.epoch))).returning({ entityUrl: entityDispatchState.entityUrl });
+			entityCleared = cleared.length > 0;
+		}
+		return {
+			claim,
+			entityCleared
+		};
 	}
 	async getActiveClaimsForRunner(runnerId) {
 		const rows = await this.db.select().from(consumerClaims).where(and(eq(consumerClaims.tenantId, this.tenantId), eq(consumerClaims.runnerId, runnerId), eq(consumerClaims.status, `active`)));
@@ -770,7 +812,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()
@@ -778,13 +820,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) {
@@ -2411,6 +2457,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];
@@ -2636,6 +2685,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));
 }
@@ -3087,16 +3137,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;
@@ -3552,6 +3602,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
@@ -3579,7 +3634,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;
@@ -3600,7 +3655,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));
 	}
@@ -3608,7 +3663,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;
@@ -3620,7 +3675,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);
@@ -3873,26 +3928,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;
@@ -4008,7 +4168,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) {
@@ -4973,7 +5133,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);
 	}
 };
@@ -6115,6 +6276,87 @@ function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, `''`)}'`;
 }
 
+//#endregion
+//#region src/webhook-signing.ts
+const encoder = new TextEncoder();
+const defaultWebhookSigner = createEd25519WebhookSigner();
+function createEd25519WebhookSigner(options = {}) {
+	const privateKey = options.privateKey ? importPrivateKey(options.privateKey) : generateKeyPairSync(`ed25519`).privateKey;
+	if (privateKey.asymmetricKeyType !== `ed25519`) throw new Error(`Webhook signing key must be an Ed25519 private key`);
+	const publicJwk = buildPublicJwk(privateKey, options.kid);
+	return {
+		sign: (body) => signWebhookBody(privateKey, publicJwk.kid, body),
+		jwks: () => ({ keys: [{ ...publicJwk }] })
+	};
+}
+function getDefaultWebhookSigner() {
+	return defaultWebhookSigner;
+}
+async function webhookSigningMetadata(signer, streamRootUrl) {
+	const jwks = await signer.jwks();
+	const key = jwks.keys[0];
+	if (!key) throw new Error(`Webhook signer did not provide any public keys`);
+	return {
+		alg: `ed25519`,
+		kid: key.kid,
+		jwks_url: appendPathToUrl(streamRootUrl, `/__ds/jwks.json`)
+	};
+}
+function signWebhookBody(privateKey, kid, body) {
+	const timestamp$1 = Math.floor(Date.now() / 1e3);
+	const payload = bytesWithTimestamp(timestamp$1, body);
+	const signature = sign(null, payload, privateKey).toString(`base64url`);
+	return `t=${timestamp$1},kid=${kid},ed25519=${signature}`;
+}
+function bytesWithTimestamp(timestamp$1, body) {
+	const prefix = encoder.encode(`${timestamp$1}.`);
+	const bodyBytes = typeof body === `string` ? encoder.encode(body) : body;
+	return Buffer.concat([Buffer.from(prefix), Buffer.from(bodyBytes)]);
+}
+function importPrivateKey(input) {
+	if (isKeyObject(input)) return input;
+	if (typeof input === `string`) {
+		const trimmed = input.trim();
+		if (trimmed.startsWith(`{`)) return createPrivateKey({
+			key: JSON.parse(trimmed),
+			format: `jwk`
+		});
+		return createPrivateKey(trimmed.replace(/\\n/g, `\n`));
+	}
+	if (Buffer.isBuffer(input)) return createPrivateKey(input);
+	return createPrivateKey({
+		key: input,
+		format: `jwk`
+	});
+}
+function isKeyObject(input) {
+	return typeof input === `object` && `type` in input && input.type === `private`;
+}
+function buildPublicJwk(privateKey, kid) {
+	const exported = createPublicKey(privateKey).export({ format: `jwk` });
+	if (exported.kty !== `OKP` || exported.crv !== `Ed25519` || !exported.x) throw new Error(`Failed to export Ed25519 webhook signing key`);
+	return {
+		kty: `OKP`,
+		crv: `Ed25519`,
+		x: exported.x,
+		kid: kid ?? deriveKeyId({
+			kty: exported.kty,
+			crv: exported.crv,
+			x: exported.x
+		}),
+		use: `sig`,
+		alg: `EdDSA`
+	};
+}
+function deriveKeyId(jwk) {
+	const thumbprintInput = JSON.stringify({
+		crv: jwk.crv,
+		kty: jwk.kty,
+		x: jwk.x
+	});
+	return `ds_${createHash(`sha256`).update(thumbprintInput).digest(`base64url`)}`;
+}
+
 //#endregion
 //#region src/routing/durable-streams-router.ts
 const subscriptionProxyBodySchema = Type.Object({ webhook: Type.Optional(Type.Object({ url: Type.String() }, { additionalProperties: true })) }, { additionalProperties: true });
@@ -6131,6 +6373,7 @@ durableStreamsRouter.delete(`/__ds/subscriptions/:subscriptionId`, deleteSubscri
 durableStreamsRouter.post(`/__ds/subscriptions/:subscriptionId/streams`, postSubscriptionStreams);
 durableStreamsRouter.delete(`/__ds/subscriptions/:subscriptionId/streams/:streamPath+`, deleteSubscriptionStream);
 for (const action of subscriptionControlActions) durableStreamsRouter.post(`/__ds/subscriptions/:subscriptionId/${action}`, subscriptionAction(action));
+durableStreamsRouter.get(`/__ds/jwks.json`, webhookJwks);
 durableStreamsRouter.all(`/__ds`, controlPassThrough);
 durableStreamsRouter.all(`/__ds/*`, controlPassThrough);
 durableStreamsRouter.post(`*`, streamAppend);
@@ -6139,12 +6382,16 @@ function bodyFromBytes$1(body) {
 	return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
 }
 function responseFromUpstream$1(response, body) {
-	return new Response(body ? bodyFromBytes$1(body) : response.body, {
+	const responseBody = forbidsResponseBody$1(response.status) ? null : body !== void 0 ? bodyFromBytes$1(body) : response.body;
+	return new Response(responseBody, {
 		status: response.status,
 		statusText: response.statusText,
 		headers: responseHeaders(response)
 	});
 }
+function forbidsResponseBody$1(status$1) {
+	return status$1 === 204 || status$1 === 205 || status$1 === 304;
+}
 async function forwardToDurableStreams(ctx, request, body, route = `stream`, urlOverride, durableStreamsBearerMode = `overwrite`) {
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
@@ -6178,28 +6425,32 @@ function rewriteSubscriptionBodyForBackend(payload, service, routingAdapter) {
 		return next;
 	});
 }
-function rewriteSubscriptionResponseForClient(bytes, response, service, routingAdapter) {
+async function rewriteSubscriptionResponseForClient(bytes, response, ctx, routingAdapter) {
 	if (!response.headers.get(`content-type`)?.includes(`application/json`)) return bytes;
 	const payload = decodeJson(bytes);
 	if (!payload) return bytes;
-	if (typeof payload.pattern === `string`) payload.pattern = routingAdapter.toRuntimeStreamPath(service, payload.pattern);
+	if (typeof payload.pattern === `string`) payload.pattern = routingAdapter.toRuntimeStreamPath(ctx.service, payload.pattern);
 	if (Array.isArray(payload.streams)) payload.streams = payload.streams.map((stream) => {
-		if (typeof stream === `string`) return routingAdapter.toRuntimeStreamPath(service, stream);
+		if (typeof stream === `string`) return routingAdapter.toRuntimeStreamPath(ctx.service, stream);
 		if (stream && typeof stream === `object` && typeof stream.path === `string`) return {
 			...stream,
-			path: routingAdapter.toRuntimeStreamPath(service, stream.path)
+			path: routingAdapter.toRuntimeStreamPath(ctx.service, stream.path)
 		};
 		return stream;
 	});
-	if (typeof payload.wake_stream === `string`) payload.wake_stream = routingAdapter.toRuntimeStreamPath(service, payload.wake_stream);
-	if (typeof payload.stream === `string`) payload.stream = routingAdapter.toRuntimeStreamPath(service, payload.stream);
+	if (typeof payload.wake_stream === `string`) payload.wake_stream = routingAdapter.toRuntimeStreamPath(ctx.service, payload.wake_stream);
+	if (typeof payload.stream === `string`) payload.stream = routingAdapter.toRuntimeStreamPath(ctx.service, payload.stream);
 	if (Array.isArray(payload.acks)) payload.acks = payload.acks.map((ack) => {
 		if (!ack || typeof ack !== `object`) return ack;
 		const next = { ...ack };
-		if (typeof next.stream === `string`) next.stream = routingAdapter.toRuntimeStreamPath(service, next.stream);
-		if (typeof next.path === `string`) next.path = routingAdapter.toRuntimeStreamPath(service, next.path);
+		if (typeof next.stream === `string`) next.stream = routingAdapter.toRuntimeStreamPath(ctx.service, next.stream);
+		if (typeof next.path === `string`) next.path = routingAdapter.toRuntimeStreamPath(ctx.service, next.path);
 		return next;
 	});
+	if (payload.webhook && typeof payload.webhook === `object` && !Array.isArray(payload.webhook)) {
+		const webhook = payload.webhook;
+		webhook.signing = await webhookSigningMetadata(resolveWebhookSigner$1(ctx), ctx.publicUrl);
+	}
 	return new TextEncoder().encode(JSON.stringify(payload));
 }
 function decodeJson(bytes) {
@@ -6218,6 +6469,9 @@ function routeParam$2(request, name) {
 function subscriptionRoutingAdapter(ctx) {
 	return resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting, ctx.durableStreamsUrl);
 }
+function resolveWebhookSigner$1(ctx) {
+	return ctx.webhookSigner ?? getDefaultWebhookSigner();
+}
 async function rewriteSubscriptionRequestBody(request, ctx, subscriptionId, routingAdapter) {
 	const body = await readRequestBody(request);
 	if (body.length === 0) return {
@@ -6246,7 +6500,7 @@ async function rewriteSubscriptionRequestBody(request, ctx, subscriptionId, rout
 async function forwardSubscriptionRequest(request, ctx, routingAdapter, opts = {}) {
 	const upstream = await forwardToDurableStreams(ctx, request, opts.body, `control`, opts.requestUrl, opts.bearerMode ?? `overwrite`);
 	let responseBytes = upstream.body ? new Uint8Array(await upstream.arrayBuffer()) : new Uint8Array();
-	responseBytes = rewriteSubscriptionResponseForClient(responseBytes, upstream, ctx.service, routingAdapter);
+	responseBytes = await rewriteSubscriptionResponseForClient(responseBytes, upstream, ctx, routingAdapter);
 	return {
 		upstream,
 		response: responseFromUpstream$1(upstream, responseBytes)
@@ -6319,6 +6573,15 @@ async function controlPassThrough(request, ctx) {
 	const upstream = await forwardToDurableStreams(ctx, request, void 0, `control`);
 	return responseFromUpstream$1(upstream);
 }
+async function webhookJwks(_request, ctx) {
+	return new Response(JSON.stringify(await resolveWebhookSigner$1(ctx).jwks()), {
+		status: 200,
+		headers: {
+			"content-type": `application/jwk-set+json`,
+			"cache-control": `public, max-age=300`
+		}
+	});
+}
 async function streamAppend(request, ctx) {
 	return await electricAgentsStreamAppendRouter.fetch(createStreamAppendRouteRequest(request), ctx.runtime, (req, body) => forwardFetchRequest({
 		request: {
@@ -6458,6 +6721,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(),
@@ -6481,6 +6758,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);
@@ -6684,11 +6962,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
@@ -6712,6 +6992,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
@@ -7192,7 +7488,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
@@ -7309,12 +7605,16 @@ function bodyFromBytes(body) {
 	return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
 }
 function responseFromUpstream(response, body) {
-	return new Response(body ? bodyFromBytes(body) : response.body, {
+	const responseBody = forbidsResponseBody(response.status) ? null : body !== void 0 ? bodyFromBytes(body) : response.body;
+	return new Response(responseBody, {
 		status: response.status,
 		statusText: response.statusText,
 		headers: responseHeaders(response)
 	});
 }
+function forbidsResponseBody(status$1) {
+	return status$1 === 204 || status$1 === 205 || status$1 === 304;
+}
 function forwardHeadersFromRequest(request) {
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
@@ -7323,6 +7623,45 @@ function forwardHeadersFromRequest(request) {
 function durableStreamsSubscriptionCallback(value) {
 	return value.startsWith(DS_SUBSCRIPTION_CALLBACK_PREFIX) ? value.slice(DS_SUBSCRIPTION_CALLBACK_PREFIX.length) : null;
 }
+function resolveWebhookSigner(ctx) {
+	return ctx.webhookSigner ?? getDefaultWebhookSigner();
+}
+function durableStreamsWebhookJwksUrl(ctx) {
+	if (!ctx.durableStreamsRouting) return appendPathToUrl(ctx.durableStreamsUrl, `/__ds/jwks.json`);
+	return resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting, ctx.durableStreamsUrl).controlUrl({
+		durableStreamsUrl: ctx.durableStreamsUrl,
+		serviceId: ctx.service,
+		requestUrl: appendPathToUrl(ctx.publicUrl, `/__ds/jwks.json`)
+	}).toString();
+}
+function durableStreamsJwksFetchClient(ctx) {
+	return async (input, init) => {
+		const headers = new Headers(init?.headers);
+		await applyDurableStreamsBearer(headers, ctx.durableStreamsBearer, { overwrite: false });
+		const nextInit = {
+			...init ?? {},
+			headers
+		};
+		if (ctx.durableStreamsDispatcher) nextInit.dispatcher = ctx.durableStreamsDispatcher;
+		return await fetch(input, nextInit);
+	};
+}
+function resolveDurableStreamsWebhookSignature(ctx) {
+	if (ctx.durableStreamsWebhookSignature === false) return false;
+	return {
+		jwksUrl: ctx.durableStreamsWebhookSignature?.jwksUrl ?? durableStreamsWebhookJwksUrl(ctx),
+		toleranceSeconds: ctx.durableStreamsWebhookSignature?.toleranceSeconds,
+		cacheTtlMs: ctx.durableStreamsWebhookSignature?.cacheTtlMs,
+		fetchClient: ctx.durableStreamsWebhookSignature?.fetchClient ?? durableStreamsJwksFetchClient(ctx)
+	};
+}
+async function verifyDurableStreamsWebhook(request, ctx, body) {
+	const config = resolveDurableStreamsWebhookSignature(ctx);
+	if (config === false) return null;
+	const verification = await verifyWebhookSignature(body, request.headers.get(`webhook-signature`), config);
+	if (verification.ok) return null;
+	return apiError(verification.status, verification.status === 401 ? ErrCodeUnauthorized : `WEBHOOK_SIGNATURE_UNAVAILABLE`, verification.error);
+}
 function claimTokenFromRequest(request) {
 	const electricClaimToken = request.headers.get(`electric-claim-token`)?.trim();
 	if (electricClaimToken) return electricClaimToken;
@@ -7356,7 +7695,10 @@ async function webhookForward(request, ctx) {
 	const rootSpan = getRequestSpan(request);
 	rootSpan?.updateName(`webhook-forward`);
 	rootSpan?.setAttribute(`electric_agents.webhook.subscription_id`, subscriptionId);
-	const lookupPromise = tracer.startActiveSpan(`db.lookupSubscription`, async (span) => {
+	const body = await readRequestBody(request);
+	const signatureError = await verifyDurableStreamsWebhook(request, ctx, body);
+	if (signatureError) return signatureError;
+	const targetWebhookUrl = await tracer.startActiveSpan(`db.lookupSubscription`, async (span) => {
 		try {
 			const rows = await ctx.pgDb.select().from(subscriptionWebhooks).where(and(eq(subscriptionWebhooks.tenantId, ctx.service), eq(subscriptionWebhooks.subscriptionId, subscriptionId))).limit(1);
 			return rows[0]?.webhookUrl ?? null;
@@ -7364,7 +7706,6 @@ async function webhookForward(request, ctx) {
 			span.end();
 		}
 	});
-	const [targetWebhookUrl, body] = await Promise.all([lookupPromise, readRequestBody(request)]);
 	if (!targetWebhookUrl) return apiError(404, ErrCodeSubscriptionNotFound, `Unknown webhook subscription`);
 	const parsedBodyResult = validateOptionalJsonBody(webhookForwardBodySchema, body, request.headers.get(`content-type`));
 	if (!parsedBodyResult.ok) return parsedBodyResult.response;
@@ -7415,7 +7756,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 });
 			}
@@ -7453,6 +7794,7 @@ async function webhookForward(request, ctx) {
 	const headers = forwardHeadersFromRequest(request);
 	headers.set(`content-type`, `application/json`);
 	headers.delete(`content-length`);
+	headers.set(`webhook-signature`, await resolveWebhookSigner(ctx).sign(forwardBody));
 	let upstream;
 	try {
 		upstream = await tracer.startActiveSpan(`fetch.agent-handler`, async (span) => {
@@ -7540,8 +7882,9 @@ async function callbackForward(request, ctx) {
 			serverLog.info(`[callback-forward] done received for stream=${target.primaryStream} consumer=${consumerId}`);
 			const stillOwnsClaim = ctx.runtime.claimWriteTokens.owns(ctx.service, target.primaryStream, consumerId);
 			const entity = await ctx.entityManager.registry.getEntityByStream(target.primaryStream);
-			if (entity && stillOwnsClaim) {
-				if (epoch !== void 0) await ctx.entityManager.registry.materializeReleasedClaim?.({
+			let entityCleared = false;
+			if (epoch !== void 0) {
+				const result = await ctx.entityManager.registry.materializeReleasedClaim?.({
 					consumerId,
 					epoch,
 					ackedStreams: Array.isArray(requestBody?.acks) ? requestBody.acks.flatMap((ack) => {
@@ -7553,13 +7896,15 @@ async function callbackForward(request, ctx) {
 						}] : [];
 					}) : void 0
 				});
-				await ctx.entityManager.registry.updateStatus(entity.url, `idle`);
-				ctx.runtime.claimWriteTokens.clearStream(ctx.service, target.primaryStream);
+				entityCleared = result?.entityCleared ?? false;
+			}
+			if (entity && (entityCleared || stillOwnsClaim)) {
+				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}`);
-			} else if (stillOwnsClaim) ctx.runtime.claimWriteTokens.clearStream(ctx.service, target.primaryStream);
-			else if (entity) serverLog.info(`[callback-forward] done ignored for stale claim stream=${target.primaryStream} consumer=${consumerId}`);
-			else serverLog.warn(`[callback-forward] done received but no entity found for stream=${target.primaryStream}`);
+				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})`);
 		} else if (requestBody?.done === true) serverLog.warn(`[callback-forward] done received but skipped: upstream.ok=${upstream.ok} primaryStream=${target.primaryStream ?? `null`} consumer=${consumerId}`);
 	} catch (err) {
 		serverLog.error(`[callback-forward] error processing done for consumer=${consumerId}: ${err instanceof Error ? err.message : String(err)}`);
@@ -7612,4 +7957,4 @@ globalRouter.all(`/_electric/*`, internalRouter.fetch);
 globalRouter.all(`*`, durableStreamsRouter.fetch);
 
 //#endregion
-export { AgentsHost, DEFAULT_TENANT_ID, StreamClient, UnregisteredTenantError, createDb, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter };
+export { AgentsHost, DEFAULT_TENANT_ID, StreamClient, UnregisteredTenantError, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };