@electric-ax/agents-server 0.5.0 → 0.5.1

package/dist/index.js

@@ -8,7 +8,7 @@ import postgres from "postgres";
 import { and, desc, eq, inArray, 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 { COMMENTS_CONTRACT, COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { COMMENTS_CONTRACT, COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildTagsIndex, buildWebhookSourceManifestEntry, canonicalPgSyncOptions, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveWebhookSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature, webhookSourceSubscriptionManifestKey } 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";
@@ -1344,7 +1344,6 @@ var PostgresRegistry = class {
 			set: {
 				options: row.options,
 				streamUrl: row.streamUrl,
-				initialSnapshotComplete: false,
 				lastTouchedAt: new Date(),
 				updatedAt: new Date()
 			}
@@ -1383,6 +1382,9 @@ var PostgresRegistry = class {
 			updatedAt: new Date()
 		}).where(this.pgSyncBridgeWhere(sourceRef));
 	}
+	async deletePgSyncBridge(sourceRef) {
+		await this.db.delete(pgSyncBridges).where(this.pgSyncBridgeWhere(sourceRef));
+	}
 	async upsertEntityBridge(row) {
 		await this.db.insert(entityBridges).values({
 			tenantId: this.tenantId,
@@ -3264,9 +3266,6 @@ function assertSharedSandboxColocated(key, chosenIsRemote, dispatchPolicy) {
 function isRecord$1(value) {
 	return typeof value === `object` && value !== null && !Array.isArray(value);
 }
-function getPgSyncManifestStreamPath(sourceRef) {
-	return `/_electric/pg-sync/${sourceRef}`;
-}
 function extractManifestSourceUrl(manifest) {
 	if (!manifest) return void 0;
 	if (manifest.kind === `child` || manifest.kind === `observe`) return typeof manifest.entity_url === `string` ? manifest.entity_url : void 0;
@@ -3279,7 +3278,7 @@ 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 === `pgSync`) return typeof manifest.sourceRef === `string` ? getPgSyncManifestStreamPath(manifest.sourceRef) : void 0;
+		if (manifest.sourceType === `pgSync`) return typeof config?.streamUrl === `string` ? config.streamUrl : 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);
@@ -4871,7 +4870,7 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
-	async upsertEventSourceSubscription(entityUrl, req) {
+	async upsertWebhookSourceSubscription(entityUrl, req) {
 		const manifestKey = req.subscription.manifestKey;
 		const txid = randomUUID();
 		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
@@ -4893,8 +4892,20 @@ var EntityManager = class {
 			subscription: req.subscription
 		};
 	}
-	async deleteEventSourceSubscription(entityUrl, req) {
-		const manifestKey = eventSourceSubscriptionManifestKey(req.id);
+	async deleteWebhookSourceSubscription(entityUrl, req) {
+		const manifestKey = webhookSourceSubscriptionManifestKey(req.id);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
+	/**
+	* Stop this entity observing a pg-sync source: drop its manifest entry and
+	* the wake it anchors. The shared pg-sync bridge (keyed by sourceRef, not by
+	* subscriber) is intentionally left running for any other observers.
+	*/
+	async deletePgSyncObservation(entityUrl, req) {
+		const manifestKey = `source:pgSync:${req.sourceRef}`;
 		const txid = randomUUID();
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
@@ -6000,9 +6011,13 @@ var Scheduler = class {
 
 //#endregion
 //#region src/pg-sync-bridge-manager.ts
-const PG_SYNC_ELECTRIC_SHAPE_URL = process.env.ELECTRIC_AGENTS_PG_SYNC_ELECTRIC_URL ?? `http://localhost:3000/v1/shape`;
+/** Registration was rejected because the source itself is invalid — map to a 4xx. */
+var PgSyncSourceValidationError = class extends Error {
+	name = `PgSyncSourceValidationError`;
+};
 const DEFAULT_RETRY_INITIAL_DELAY_MS = 1e3;
 const DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
+const DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function buildElectricShapeParams(options) {
 	return {
 		table: options.table,
@@ -6022,6 +6037,31 @@ function buildElectricShapeParams(options) {
 		...options.metadata?.wakeId ? { electric_agents_wake_id: options.metadata.wakeId } : {}
 	};
 }
+/**
+* Build the one-shot URL used to validate a shape source at registration
+* time. Approximates the query-param encoding of the Electric TS client
+* (arrays comma-joined, where-clause params as `params[n]`) — unlike the
+* client it does not quote column identifiers, so probe and stream encoding
+* can diverge for exotic column names.
+*/
+function buildShapeProbeUrl(sourceUrl, options) {
+	let url;
+	try {
+		url = new URL(sourceUrl);
+	} catch {
+		throw new PgSyncSourceValidationError(`pgSync url "${sourceUrl}" is not a valid URL`);
+	}
+	if (url.protocol !== `http:` && url.protocol !== `https:`) throw new PgSyncSourceValidationError(`pgSync url "${sourceUrl}" must be an HTTP(S) Electric shape endpoint, not a database connection string`);
+	for (const [key, value] of Object.entries(buildElectricShapeParams(options))) {
+		if (value === void 0 || value === null) continue;
+		if (Array.isArray(value)) if (key === `params`) value.forEach((item, index$1) => url.searchParams.set(`params[${index$1 + 1}]`, String(item)));
+		else url.searchParams.set(key, value.join(`,`));
+		else if (typeof value === `object`) for (const [k, v] of Object.entries(value)) url.searchParams.set(`${key}[${k}]`, String(v));
+		else url.searchParams.set(key, String(value));
+	}
+	url.searchParams.set(`offset`, `now`);
+	return url;
+}
 function jsonSafe(value) {
 	if (typeof value === `bigint`) return value.toString();
 	if (value === null || typeof value !== `object`) return value;
@@ -6043,37 +6083,19 @@ function rowKeyForMessage(message) {
 	const candidate = headers.key ?? headers.rowKey ?? message.value?.id ?? message.value?.key ?? message.old_value?.id ?? message.old_value?.key;
 	return candidate === void 0 ? void 0 : stableJson(candidate);
 }
-function pgSyncMessageToDurableEvent(message, optionsOrSourceRef) {
+function pgSyncMessageToDurableEvent(message) {
 	const operation = message.headers.operation;
 	if (operation !== `insert` && operation !== `update` && operation !== `delete`) return null;
-	const sourceRef = typeof optionsOrSourceRef === `string` ? optionsOrSourceRef : sourceRefForPgSync(optionsOrSourceRef);
-	const rowKey = rowKeyForMessage(message);
-	const offset = message.headers.offset;
-	if (typeof offset !== `string` || offset.length === 0) return null;
-	const messageKeyPart = offset;
-	const messageKey = `${sourceRef}:${operation}:${messageKeyPart}`;
-	const timestamp$1 = new Date().toISOString();
-	const oldValue = message.old_value;
-	const safeValue = jsonSafe(message.value);
-	const safeOldValue = jsonSafe(oldValue);
-	const safeHeaders = jsonSafe(message.headers);
+	const key = message.key ?? (typeof message.headers.key === `string` ? message.headers.key : void 0) ?? rowKeyForMessage(message);
+	if (!key) return null;
+	const safeMessage = jsonSafe(message);
 	return {
 		type: `pg_sync_change`,
-		key: messageKey,
-		value: {
-			key: messageKey,
-			table: typeof optionsOrSourceRef === `string` ? void 0 : optionsOrSourceRef.table,
-			operation,
-			...rowKey !== void 0 ? { rowKey } : {},
-			...message.value !== void 0 ? { value: safeValue } : {},
-			...oldValue !== void 0 ? { oldValue: safeOldValue } : {},
-			headers: safeHeaders,
-			...typeof offset === `string` ? { offset } : {},
-			receivedAt: timestamp$1
-		},
+		key,
+		value: safeMessage,
 		headers: {
-			operation,
-			timestamp: timestamp$1
+			...jsonSafe(message.headers),
+			operation
 		}
 	};
 }
@@ -6163,13 +6185,13 @@ var PgSyncBridge = class {
 					}
 					if (!isChangeMessage(message)) continue;
 					if (!this.skipChangesUntilUpToDate) {
-						const event = pgSyncMessageToDurableEvent(message, this.options);
+						const event = pgSyncMessageToDurableEvent(message);
 						if (event) {
 							if (!this.producer) throw new Error(`pg-sync producer is not started`);
 							await this.producer.append(JSON.stringify(event));
 							await this.producer.flush?.();
 							await this.evaluateWakes?.(this.streamUrl, event);
-						}
+						} else serverLog.warn(`[pg-sync-bridge] dropped change message for ${this.sourceRef} (unknown operation or missing row key):`, message.headers);
 					}
 					await this.persistCursor(stream);
 					this.retryAttempt = 0;
@@ -6218,13 +6240,15 @@ var PgSyncBridge = class {
 var PgSyncBridgeManager = class {
 	bridges = new Map();
 	starting = new Map();
-	url;
 	retry;
+	fetchFn;
+	probeTimeoutMs;
 	constructor(streamClient, evaluateWakes, registry, options = {}) {
 		this.streamClient = streamClient;
 		this.evaluateWakes = evaluateWakes;
 		this.registry = registry;
-		this.url = options.url ?? PG_SYNC_ELECTRIC_SHAPE_URL;
+		this.fetchFn = options.fetchFn;
+		this.probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
 		this.retry = {
 			initialDelayMs: options.retry?.initialDelayMs ?? DEFAULT_RETRY_INITIAL_DELAY_MS,
 			maxDelayMs: options.retry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
@@ -6235,9 +6259,16 @@ var PgSyncBridgeManager = class {
 	async start() {
 		const rows = await this.registry?.listPgSyncBridges?.();
 		if (!rows) return;
-		await Promise.all(rows.map((row) => this.ensureBridge(row).catch((error) => {
-			serverLog.warn(`[pg-sync-bridge] failed to start ${row.sourceRef}:`, error);
-		})));
+		await Promise.all(rows.map(async (row) => {
+			if (!row.options.url) {
+				serverLog.warn(`[pg-sync-bridge] deleting registration ${row.sourceRef}: it predates required source URLs; re-register the observation with an explicit Electric shape URL`);
+				await this.registry?.deletePgSyncBridge?.(row.sourceRef);
+				return;
+			}
+			await this.ensureBridge(row).catch((error) => {
+				serverLog.warn(`[pg-sync-bridge] failed to start ${row.sourceRef}:`, error);
+			});
+		}));
 	}
 	async register(options, metadata) {
 		const mergedMetadata = {
@@ -6251,6 +6282,7 @@ var PgSyncBridgeManager = class {
 		const resolvedSource = this.resolveSource(canonicalOptions);
 		const sourceRef = sourceRefForPgSync(canonicalOptions);
 		const streamUrl = getPgSyncStreamPath(sourceRef, this.registry?.tenantId);
+		if (!this.bridges.has(sourceRef) && !this.starting.has(sourceRef)) await this.probeSource(resolvedSource, canonicalOptions);
 		const row = await this.registry?.upsertPgSyncBridge({
 			sourceRef,
 			options: canonicalOptions,
@@ -6291,7 +6323,32 @@ var PgSyncBridgeManager = class {
 		await start;
 	}
 	resolveSource(options) {
-		return { url: options.url ?? this.url };
+		if (!options.url) throw new PgSyncSourceValidationError(`pgSync source url is required; no server default is configured`);
+		return { url: options.url };
+	}
+	/**
+	* One-shot fetch of the shape log before a bridge is created, so a bad
+	* URL or rejected shape fails the registration instead of dying silently
+	* in the bridge's retry loop.
+	*/
+	async probeSource(source, options) {
+		const probeUrl = buildShapeProbeUrl(source.url, options);
+		const fetchFn = this.fetchFn ?? globalThis.fetch;
+		let response;
+		try {
+			response = await fetchFn(probeUrl, { signal: AbortSignal.timeout(this.probeTimeoutMs) });
+		} catch (error) {
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} is unreachable: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!response.ok) {
+			const body = (await response.text().catch(() => `<failed to read body>`)).slice(0, 500);
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} rejected the shape request (${response.status})${body ? `: ${body}` : ``}`);
+		}
+		if (!response.headers.get(`electric-handle`)) {
+			const suggestion = new URL(source.url);
+			suggestion.pathname = `/v1/shape`;
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} responded but is not a shape log (missing electric-handle header) — the Electric shape API is usually served at ${suggestion.origin}/v1/shape`);
+		}
 	}
 	async stop() {
 		await Promise.allSettled(this.starting.values());
@@ -7253,6 +7310,7 @@ var WakeRegistry = class {
 		};
 		if (value && `value` in value) change.value = value.value;
 		if (value && `oldValue` in value) change.oldValue = value.oldValue;
+		else if (value && `old_value` in value) change.oldValue = value.old_value;
 		if (eventType === `inbox`) {
 			if (typeof value?.from === `string`) change.from = value.from;
 			if (typeof value?.from_principal === `string`) change.from_principal = value.from_principal;
@@ -8666,8 +8724,8 @@ const subscriptionLifetimeSchema = Type.Union([
 	}),
 	Type.Object({ kind: Type.Literal(`manual`) })
 ]);
-const eventSourceSubscriptionBodySchema = Type.Object({
-	sourceKey: Type.String(),
+const webhookSourceSubscriptionBodySchema = Type.Object({
+	webhookKey: Type.String(),
 	bucketKey: Type.Optional(Type.String()),
 	params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	filterKey: Type.Optional(Type.String()),
@@ -8700,8 +8758,9 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withEntityPermission(`write`), deleteTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), withEntityPermission(`schedule`), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withEntityPermission(`schedule`), deleteSchedule);
-entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertEventSourceSubscription);
-entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteEventSourceSubscription);
+entitiesRouter.put(`/:type/:instanceId/webhook-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(webhookSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertWebhookSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/webhook-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteWebhookSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/pg-sync-observations/:sourceRef`, withExistingEntity, withEntityPermission(`write`), deletePgSyncObservation);
 entitiesRouter.get(`/:type/:instanceId/grants`, withExistingEntity, withEntityPermission(`manage`), listEntityPermissionGrants);
 entitiesRouter.post(`/:type/:instanceId/grants`, withExistingEntity, withSchema(entityPermissionGrantInputSchema), withEntityPermission(`manage`), createEntityPermissionGrant);
 entitiesRouter.delete(`/:type/:instanceId/grants/:grantId`, withExistingEntity, withEntityPermission(`manage`), deleteEntityPermissionGrant);
@@ -8952,22 +9011,22 @@ 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`);
+async function upsertWebhookSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `subscribed to webhook sources`);
 	if (principalMutationError) return principalMutationError;
-	const catalog = ctx.eventSources;
-	if (!catalog) return apiError(404, ErrCodeNotFound, `No event source catalog is configured`);
+	const catalog = ctx.webhookSources;
+	if (!catalog) return apiError(404, ErrCodeNotFound, `No webhook 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`);
+	const source = await catalog.getWebhookSource(parsed.webhookKey);
+	if (!source) return apiError(404, ErrCodeNotFound, `Webhook source "${parsed.webhookKey}" 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({
+		resolved = resolveWebhookSourceSubscription({
 			contract: source,
 			entityUrl,
 			request: {
@@ -8979,18 +9038,25 @@ async function upsertEventSourceSubscription(request, ctx) {
 	} 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, {
+	await ctx.ensureWebhookSourceWakeSource?.(resolved.subscription.sourceUrl);
+	const result = await ctx.entityManager.upsertWebhookSourceSubscription(entityUrl, {
 		subscription: resolved.subscription,
-		manifest: buildEventSourceManifestEntry(resolved)
+		manifest: buildWebhookSourceManifestEntry(resolved)
 	});
 	return json(result);
 }
-async function deleteEventSourceSubscription(request, ctx) {
-	const principalMutationError = rejectPrincipalEntityMutation(request, `unsubscribed from event sources`);
+async function deleteWebhookSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unsubscribed from webhook sources`);
 	if (principalMutationError) return principalMutationError;
 	const { entityUrl } = requireExistingEntityRoute(request);
-	const result = await ctx.entityManager.deleteEventSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
+	const result = await ctx.entityManager.deleteWebhookSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
+	return json(result);
+}
+async function deletePgSyncObservation(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unobserved a pg-sync source`);
+	if (principalMutationError) return principalMutationError;
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.deletePgSyncObservation(entityUrl, { sourceRef: decodeURIComponent(request.params.sourceRef) });
 	return json(result);
 }
 function tagResponseBody(entity) {
@@ -9456,7 +9522,7 @@ function toPublicEntityType(entityType) {
 //#endregion
 //#region src/routing/pg-sync-router.ts
 const pgSyncOptionsSchema = Type.Object({
-	url: Type.Optional(Type.String()),
+	url: Type.String(),
 	table: Type.String(),
 	columns: Type.Optional(Type.Array(Type.String())),
 	where: Type.Optional(Type.String()),
@@ -9478,6 +9544,7 @@ const pgSyncRouter = Router({ base: `/_electric/pg-sync` });
 pgSyncRouter.post(`/register`, withSchema(pgSyncRegisterBodySchema), registerPgSync);
 async function registerPgSync(request, ctx) {
 	const { options, metadata } = routeBody(request);
+	if (options.url.trim() === ``) return apiError(400, ErrCodeInvalidRequest, `pgSync url must be non-empty`);
 	if (options.table.trim() === ``) return apiError(400, ErrCodeInvalidRequest, `pgSync table must be non-empty`);
 	if (!ctx.pgSyncBridgeManager) return apiError(503, ErrCodeInvalidRequest, `pgSync bridge manager is not configured`);
 	try {
@@ -9492,6 +9559,8 @@ async function registerPgSync(request, ctx) {
 		const result = await ctx.pgSyncBridgeManager.register(options, requestMetadata$1);
 		return json(result);
 	} catch (error) {
+		if (error instanceof PgSyncSourceValidationError) return apiError(400, ErrCodeInvalidRequest, error.message);
+		serverLog.error(`[pg-sync] registration failed for table "${options.table}":`, error);
 		return apiError(500, ErrCodeInvalidRequest, `pgSync registration failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
@@ -10016,7 +10085,7 @@ const wakeCallbackBodySchema = 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.get(`/webhook-sources`, listWebhookSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/subscription-webhooks/:subscriptionId`, subscriptionWebhook);
 internalRouter.post(`/wake-callbacks/:consumerId`, wakeCallback);
@@ -10138,11 +10207,11 @@ 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) });
+async function listWebhookSources(_request, ctx) {
+	const webhookSources = ctx.webhookSources ? await ctx.webhookSources.listWebhookSources() : [];
+	return json({ webhookSources: webhookSources.filter(isAgentVisibleWebhookSource) });
 }
-function isAgentVisibleEventSource(source) {
+function isAgentVisibleWebhookSource(source) {
 	return source.agentVisible === true && source.status === `active`;
 }
 async function subscriptionWebhook(request, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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.4.0"
+    "@electric-ax/agents-runtime": "0.4.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": "0.4.18",
-    "@electric-ax/agents-server-conformance-tests": "0.1.12",
-    "@electric-ax/agents-server-ui": "0.5.0"
+    "@electric-ax/agents-server-ui": "0.5.1",
+    "@electric-ax/agents": "0.4.19",
+    "@electric-ax/agents-server-conformance-tests": "0.1.12"
   },
   "files": [
     "dist",

package/src/entity-manager.ts

@@ -7,7 +7,7 @@ import {
   getCronStreamPath,
   getSharedStateStreamPath,
   getNextCronFireAt,
-  eventSourceSubscriptionManifestKey,
+  webhookSourceSubscriptionManifestKey,
   manifestChildKey,
   manifestSharedStateKey,
   manifestSourceKey,
@@ -56,7 +56,7 @@ import type { queueAsPromised } from 'fastq'
 import type { SchedulerClient } from './scheduler.js'
 import type { WakeEvalResult, WakeRegistry } from './wake-registry.js'
 import type { WakeMessage } from '@electric-ax/agents-runtime'
-import type { EventSourceSubscription } from '@electric-ax/agents-runtime'
+import type { WebhookSourceSubscription } from '@electric-ax/agents-runtime'
 import type { PostgresRegistry } from './entity-registry.js'
 import type { SchemaValidator } from './electric-agents/schema-validator.js'
 import type { StreamClient } from './stream-client.js'
@@ -3142,13 +3142,13 @@ export class EntityManager {
     return { txid }
   }
 
-  async upsertEventSourceSubscription(
+  async upsertWebhookSourceSubscription(
     entityUrl: string,
     req: {
-      subscription: EventSourceSubscription
+      subscription: WebhookSourceSubscription
       manifest: Record<string, unknown>
     }
-  ): Promise<{ txid: string; subscription: EventSourceSubscription }> {
+  ): Promise<{ txid: string; subscription: WebhookSourceSubscription }> {
     const manifestKey = req.subscription.manifestKey
     const txid = randomUUID()
     await this.writeManifestEntry(
@@ -3184,11 +3184,35 @@ export class EntityManager {
     return { txid, subscription: req.subscription }
   }
 
-  async deleteEventSourceSubscription(
+  async deleteWebhookSourceSubscription(
     entityUrl: string,
     req: { id: string }
   ): Promise<{ txid: string }> {
-    const manifestKey = eventSourceSubscriptionManifestKey(req.id)
+    const manifestKey = webhookSourceSubscriptionManifestKey(req.id)
+    const txid = randomUUID()
+    await this.writeManifestEntry(entityUrl, manifestKey, `delete`, undefined, {
+      txid,
+    })
+
+    await this.wakeRegistry.unregisterByManifestKey(
+      entityUrl,
+      manifestKey,
+      this.tenantId
+    )
+
+    return { txid }
+  }
+
+  /**
+   * Stop this entity observing a pg-sync source: drop its manifest entry and
+   * the wake it anchors. The shared pg-sync bridge (keyed by sourceRef, not by
+   * subscriber) is intentionally left running for any other observers.
+   */
+  async deletePgSyncObservation(
+    entityUrl: string,
+    req: { sourceRef: string }
+  ): Promise<{ txid: string }> {
+    const manifestKey = `source:pgSync:${req.sourceRef}`
     const txid = randomUUID()
     await this.writeManifestEntry(entityUrl, manifestKey, `delete`, undefined, {
       txid,

package/src/entity-registry.ts

@@ -1575,10 +1575,16 @@ export class PostgresRegistry {
       })
       .onConflictDoUpdate({
         target: [pgSyncBridges.tenantId, pgSyncBridges.sourceRef],
+        // A conflict means the sourceRef matched, i.e. the shape-identity
+        // options are identical, so the persisted cursor and bootstrap state
+        // are still valid. Re-registration is the common path now that the
+        // sourceRef ignores per-request metadata; resetting
+        // initialSnapshotComplete here would make a later restart resume from
+        // the saved cursor while re-skipping changes until up-to-date, dropping
+        // real changes that arrived during downtime.
         set: {
           options: row.options,
           streamUrl: row.streamUrl,
-          initialSnapshotComplete: false,
           lastTouchedAt: new Date(),
           updatedAt: new Date(),
         },
@@ -1650,6 +1656,10 @@ export class PostgresRegistry {
       .where(this.pgSyncBridgeWhere(sourceRef))
   }
 
+  async deletePgSyncBridge(sourceRef: string): Promise<void> {
+    await this.db.delete(pgSyncBridges).where(this.pgSyncBridgeWhere(sourceRef))
+  }
+
   async upsertEntityBridge(row: {
     sourceRef: string
     tags: EntityTags

package/src/index.ts

@@ -65,17 +65,17 @@ export type {
   AuthorizeRequest,
 } from './electric-agents-types.js'
 export type {
-  EventSourceBucket,
-  EventSourceContract,
-  EventSourceFilter,
-  EventSourceSubscription,
-  EventSourceSubscriptionInput,
+  WebhookSourceBucket,
+  WebhookSourceContract,
+  WebhookSourceFilter,
+  WebhookSourceSubscription,
+  WebhookSourceSubscriptionInput,
   SubscriptionLifetime,
 } from '@electric-ax/agents-runtime'
 export type { Principal, PrincipalKind } from './principal.js'
 export { globalRouter } from './routing/global-router.js'
 export type { GlobalRoutes } from './routing/global-router.js'
-export type { EventSourceCatalog, TenantContext } from './routing/context.js'
+export type { WebhookSourceCatalog, TenantContext } from './routing/context.js'
 export {
   streamRootDurableStreamsRoutingAdapter,
   pathPrefixedSingleTenantDurableStreamsRoutingAdapter,

package/src/manifest-side-effects.ts

@@ -10,10 +10,6 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === `object` && value !== null && !Array.isArray(value)
 }
 
-function getPgSyncManifestStreamPath(sourceRef: string): string {
-  return `/_electric/pg-sync/${sourceRef}`
-}
-
 export function extractManifestSourceUrl(
   manifest: Record<string, unknown> | undefined
 ): string | undefined {
@@ -62,8 +58,8 @@ export function extractManifestSourceUrl(
     }
 
     if (manifest.sourceType === `pgSync`) {
-      return typeof manifest.sourceRef === `string`
-        ? getPgSyncManifestStreamPath(manifest.sourceRef)
+      return typeof config?.streamUrl === `string`
+        ? config.streamUrl
         : undefined
     }