@electric-ax/agents-server 0.4.6 → 0.4.9

package/dist/index.js

@@ -8,7 +8,7 @@ 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, 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 { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, 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`;
@@ -777,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()
@@ -785,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) {
@@ -2418,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];
@@ -2582,6 +2624,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;
@@ -2643,6 +2689,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));
 }
@@ -2867,7 +2914,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({
@@ -3094,16 +3142,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;
@@ -3559,6 +3607,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
@@ -3586,7 +3639,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;
@@ -3607,7 +3660,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));
 	}
@@ -3615,7 +3668,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;
@@ -3627,7 +3680,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);
@@ -3756,6 +3809,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.
 	*/
@@ -3880,26 +3962,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;
@@ -4015,7 +4202,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) {
@@ -4980,7 +5167,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);
 	}
 };
@@ -6530,7 +6718,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({
@@ -6567,6 +6756,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(),
@@ -6582,6 +6785,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);
@@ -6590,6 +6809,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);
@@ -6598,6 +6818,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;
@@ -6704,6 +6926,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;
@@ -6793,11 +7056,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
@@ -6821,6 +7086,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
@@ -7301,7 +7582,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
@@ -7400,6 +7681,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);
@@ -7503,6 +7785,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);
@@ -7569,7 +7858,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 });
 			}
@@ -7712,9 +8001,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})`);
@@ -7770,4 +8059,4 @@ globalRouter.all(`/_electric/*`, internalRouter.fetch);
 globalRouter.all(`*`, durableStreamsRouter.fetch);
 
 //#endregion
-export { AgentsHost, DEFAULT_TENANT_ID, StreamClient, UnregisteredTenantError, createDb, createEd25519WebhookSigner, getDefaultWebhookSigner, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, webhookSigningMetadata };
+export { AgentsHost, DEFAULT_TENANT_ID, StreamClient, UnregisteredTenantError, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/drizzle/0009_entity_signal_statuses.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "entities" DROP CONSTRAINT "chk_entities_status";
+--> statement-breakpoint
+ALTER TABLE "entities" ADD CONSTRAINT "chk_entities_status" CHECK ("entities"."status" IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed'));

package/drizzle/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1778976000000,
       "tag": "0008_runner_runtime_diagnostics",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1778540000000,
+      "tag": "0009_entity_signal_statuses",
+      "breakpoints": true
     }
   ]
 }