@electric-ax/agents-server 0.4.5 → 0.4.6

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";
@@ -571,7 +571,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 +584,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`)));
@@ -6115,6 +6122,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 +6219,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 +6228,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 +6271,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 +6315,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 +6346,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 +6419,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: {
@@ -7309,12 +7418,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 +7436,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 +7508,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 +7519,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;
@@ -7453,6 +7607,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 +7695,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 +7709,15 @@ async function callbackForward(request, ctx) {
 						}] : [];
 					}) : void 0
 				});
+				entityCleared = result?.entityCleared ?? false;
+			}
+			if (entity && (entityCleared || stillOwnsClaim)) {
 				await ctx.entityManager.registry.updateStatus(entity.url, `idle`);
-				ctx.runtime.claimWriteTokens.clearStream(ctx.service, target.primaryStream);
 				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}`);
+			} 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 +7770,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, createDb, createEd25519WebhookSigner, getDefaultWebhookSigner, globalRouter, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, webhookSigningMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -37,7 +37,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@durable-streams/client": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/client@5d5c217",
-    "@durable-streams/server": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/server@5d5c217",
+    "@durable-streams/server": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/server@eac712f",
     "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@5d5c217",
     "@electric-sql/client": "^1.5.18",
     "@mariozechner/pi-agent-core": "^0.70.2",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.0"
+    "@electric-ax/agents-runtime": "0.3.1"
   },
   "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-server-ui": "0.4.5",
+    "@electric-ax/agents": "0.4.5",
     "@electric-ax/agents-server-conformance-tests": "0.1.6",
-    "@electric-ax/agents": "0.4.4"
+    "@electric-ax/agents-server-ui": "0.4.6"
   },
   "files": [
     "dist",

package/src/entity-registry.ts

@@ -360,11 +360,17 @@ export class PostgresRegistry {
     input: MaterializeHeartbeatClaimInput
   ): Promise<void> {
     const heartbeatAt = input.heartbeatAt ?? new Date()
+    // Only touch leaseExpiresAt when the caller explicitly provides one.
+    // The lease was set at materializeActiveClaim time from the upstream
+    // lease_ttl_ms and remains the authoritative expiry; heartbeats are
+    // alive-pings, not lease extensions.
     await this.db
       .update(consumerClaims)
       .set({
         lastHeartbeatAt: heartbeatAt,
-        leaseExpiresAt: input.leaseExpiresAt ?? null,
+        ...(input.leaseExpiresAt !== undefined
+          ? { leaseExpiresAt: input.leaseExpiresAt }
+          : {}),
         updatedAt: heartbeatAt,
       })
       .where(
@@ -378,7 +384,7 @@ export class PostgresRegistry {
 
   async materializeReleasedClaim(
     input: MaterializeReleasedClaimInput
-  ): Promise<ConsumerClaim | null> {
+  ): Promise<{ claim: ConsumerClaim | null; entityCleared: boolean }> {
     const releasedAt = input.releasedAt ?? new Date()
     const rows = await this.db
       .update(consumerClaims)
@@ -398,8 +404,13 @@ export class PostgresRegistry {
       .returning()
 
     const claim = rows[0] ? this.rowToConsumerClaim(rows[0]) : null
+    let entityCleared = false
     if (claim) {
-      await this.db
+      // entityCleared distinguishes "we were the active dispatch and now it's
+      // empty" from "a newer claim was already active for this entity." The
+      // WHERE clause matches our (consumerId, epoch) so an evicted-by-newer
+      // case correctly returns zero rows.
+      const cleared = await this.db
         .update(entityDispatchState)
         .set({
           activeConsumerId: null,
@@ -419,8 +430,10 @@ export class PostgresRegistry {
             eq(entityDispatchState.activeEpoch, input.epoch)
           )
         )
+        .returning({ entityUrl: entityDispatchState.entityUrl })
+      entityCleared = cleared.length > 0
     }
-    return claim
+    return { claim, entityCleared }
   }
 
   async getActiveClaimsForRunner(

package/src/entrypoint-lib.ts

@@ -139,6 +139,10 @@ export function resolveElectricAgentsEntrypointOptions(
     `ELECTRIC_URL`,
   ])
   const electricSecret = readEnv(env, [`ELECTRIC_AGENTS_ELECTRIC_SECRET`])
+  const webhookSigningKey = readEnv(env, [
+    `ELECTRIC_AGENTS_WEBHOOK_SIGNING_PRIVATE_KEY`,
+    `WEBHOOK_SIGNING_PRIVATE_KEY`,
+  ])
   const baseUrl = readEnv(env, [`ELECTRIC_AGENTS_BASE_URL`, `BASE_URL`])
   return {
     service: readEnv(env, [`ELECTRIC_AGENTS_SERVICE`, `SERVICE`]),
@@ -153,6 +157,7 @@ export function resolveElectricAgentsEntrypointOptions(
       ? validateUrl(`Electric URL`, electricUrl)
       : undefined,
     electricSecret,
+    webhookSigningKey,
     host: readEnv(env, [`ELECTRIC_AGENTS_HOST`, `HOST`]) ?? DEFAULT_HOST,
     port: readPort(env),
     workingDirectory:

package/src/index.ts

@@ -46,6 +46,19 @@ export type {
   DurableStreamsRoutingAdapter,
   DurableStreamsRoutingInput,
 } from './routing/durable-streams-routing-adapter.js'
+export {
+  createEd25519WebhookSigner,
+  getDefaultWebhookSigner,
+  webhookSigningMetadata,
+} from './webhook-signing.js'
+export type {
+  Ed25519WebhookSignerOptions,
+  WebhookJwks,
+  WebhookPublicJwk,
+  WebhookSigner,
+  WebhookSigningKeyInput,
+  WebhookSigningMetadata,
+} from './webhook-signing.js'
 export type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 export {
   DEFAULT_TENANT_ID,

package/src/routing/context.ts

@@ -1,4 +1,5 @@
 import type { Agent } from 'undici'
+import type { WebhookSignatureVerifierConfig } from '@electric-ax/agents-runtime'
 import type { DrizzleDB } from '../db/index.js'
 import type { EntityBridgeCoordinator } from '../entity-bridge-manager.js'
 import type { EntityManager } from '../entity-manager.js'
@@ -7,6 +8,7 @@ import type { StreamClient } from '../stream-client.js'
 import type { DurableStreamsRoutingAdapter } from './durable-streams-routing-adapter.js'
 import type { Principal } from '../principal.js'
 import type { DurableStreamsBearerProvider } from '../stream-client.js'
+import type { WebhookSigner } from '../webhook-signing.js'
 
 /**
  * Per-request tenant context passed through every router and handler.
@@ -24,6 +26,10 @@ export interface TenantContext {
   durableStreamsBearer?: DurableStreamsBearerProvider
   durableStreamsRouting?: DurableStreamsRoutingAdapter
   durableStreamsDispatcher: Agent
+  durableStreamsWebhookSignature?:
+    | false
+    | Partial<WebhookSignatureVerifierConfig>
+  webhookSigner?: WebhookSigner
   electricUrl?: string
   electricSecret?: string
   ownAgentHandlerPaths?: ReadonlyArray<string>