@electric-ax/agents-server 0.4.6 → 0.4.7

package/dist/index.d.ts

@@ -3227,7 +3227,10 @@ interface Principal {
 type WakeNotification = WebhookNotification;
 type RequestPrincipal = Principal;
 type AuthenticateRequest = (request: Request) => Promise<Principal | null> | Principal | null;
-type EntityStatus = `spawning` | `running` | `idle` | `stopped`;
+type EntityStatus = `spawning` | `running` | `idle` | `paused` | `stopping` | `stopped` | `killed`;
+declare const ENTITY_SIGNALS: readonly ["SIGINT", "SIGHUP", "SIGTERM", "SIGKILL", "SIGSTOP", "SIGCONT", "SIGUSR"];
+type EntitySignal = (typeof ENTITY_SIGNALS)[number];
+declare function assertEntityStatus(s: string): EntityStatus;
 type DispatchTarget = {
   type: `webhook`;
   url: string;
@@ -3354,6 +3357,10 @@ interface ConsumerClaim {
   acked_streams?: Array<SourceStreamOffset>;
   updated_at: string;
 }
+declare function assertEntitySignal(s: string): EntitySignal;
+declare function isTerminalEntityStatus(status: EntityStatus): boolean;
+declare function rejectsNormalWrites(status: EntityStatus): boolean;
+declare function expectedSignalStatus(status: EntityStatus, signal: EntitySignal): EntityStatus;
 interface ElectricAgentsEntity {
   url: string;
   type: string;
@@ -3376,7 +3383,26 @@ interface ElectricAgentsEntity {
   updated_at: number;
 }
 /** Public-facing entity — internal fields stripped. Standalone type so new internal fields don't silently leak. */
-
+interface PublicElectricAgentsEntity {
+  url: string;
+  type: string;
+  status: EntityStatus;
+  streams: {
+    main: string;
+    error: string;
+  };
+  dispatch_policy?: DispatchPolicy;
+  tags: Record<string, string>;
+  spawn_args?: Record<string, unknown>;
+  parent?: string;
+  created_by?: string;
+  created_at: number;
+  updated_at: number;
+}
+/** Entity row as stored in Postgres / returned by Electric shapes (no derived `streams` field). */
+type ElectricAgentsEntityRow = Omit<PublicElectricAgentsEntity, `streams`>;
+/** Strip internal fields (write_token, subscription_id) from an entity. */
+declare function toPublicEntity(entity: ElectricAgentsEntity): PublicElectricAgentsEntity;
 interface ElectricAgentsEntityType {
   name: string;
   description: string;
@@ -3426,9 +3452,27 @@ interface SendRequest {
   mode?: `immediate` | `queued` | `paused` | `steer`;
   position?: string;
 }
+interface SignalRequest {
+  signal: EntitySignal;
+  reason?: string;
+  payload?: unknown;
+}
+interface SignalResponse {
+  url: string;
+  signal: EntitySignal;
+  previous_state: EntityStatus;
+  new_state: EntityStatus;
+  created_at: number;
+  txid: number;
+}
 interface SetTagRequest {
   value: string;
 }
+interface EntityListFilter {
+  type?: string;
+  status?: EntityStatus;
+  created_by?: string;
+}
 
 //#endregion
 //#region src/entity-registry.d.ts
@@ -3560,7 +3604,8 @@ declare class PostgresRegistry {
     total: number;
   }>;
   updateStatus(entityUrl: string, status: EntityStatus): Promise<void>;
-  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number>;
+  updateStatusWithTxid(entityUrl: string, status: EntityStatus): Promise<number | null>;
+  touchEntityWithTxid(entityUrl: string): Promise<number | null>;
   setEntityTag(url: string, key: string, value: string): Promise<{
     entity: ElectricAgentsEntity | null;
     changed: boolean;
@@ -4194,9 +4239,12 @@ declare class EntityManager {
    */
   private extractRunResponse;
   private buildWakeMessage;
+  signal(entityUrl: string, req: SignalRequest): Promise<SignalResponse>;
   kill(entityUrl: string): Promise<{
     txid: number;
   }>;
+  private serverHandlingForSignal;
+  private appendSignalEvent;
   validateWriteEvent(entity: ElectricAgentsEntity, event: Record<string, unknown>): Promise<{
     code: string;
     message: string;
@@ -4452,4 +4500,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicWakeNotification, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, createDb, createEd25519WebhookSigner, getDefaultWebhookSigner, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, webhookSigningMetadata };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/dist/index.js

@@ -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];
@@ -2643,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));
 }
@@ -3094,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;
@@ -3559,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
@@ -3586,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;
@@ -3607,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));
 	}
@@ -3615,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;
@@ -3627,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);
@@ -3880,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;
@@ -4015,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) {
@@ -4980,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);
 	}
 };
@@ -6567,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(),
@@ -6590,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);
@@ -6793,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
@@ -6821,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
@@ -7301,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
@@ -7569,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 });
 			}
@@ -7712,9 +7899,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 +7957,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
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.1"
+    "@electric-ax/agents-runtime": "0.3.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
@@ -65,9 +65,9 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
-    "@electric-ax/agents": "0.4.5",
-    "@electric-ax/agents-server-conformance-tests": "0.1.6",
-    "@electric-ax/agents-server-ui": "0.4.6"
+    "@electric-ax/agents-server-conformance-tests": "0.1.7",
+    "@electric-ax/agents": "0.4.6",
+    "@electric-ax/agents-server-ui": "0.4.7"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -66,7 +66,7 @@ export const entities = pgTable(
     index(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
     check(
       `chk_entities_status`,
-      sql`${table.status} IN ('spawning', 'running', 'idle', 'stopped')`
+      sql`${table.status} IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed')`
     ),
   ]
 )