@electric-ax/agents-server 0.5.0 → 0.5.1

package/dist/index.cjs

@@ -1373,7 +1373,6 @@ var PostgresRegistry = class {
 			set: {
 				options: row.options,
 				streamUrl: row.streamUrl,
-				initialSnapshotComplete: false,
 				lastTouchedAt: new Date(),
 				updatedAt: new Date()
 			}
@@ -1412,6 +1411,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,
@@ -3293,9 +3295,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;
@@ -3308,7 +3307,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` ? (0, __electric_ax_agents_runtime.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 (0, __electric_ax_agents_runtime.getWebhookStreamPath)(config.endpointKey, typeof config.bucket === `string` ? config.bucket : void 0);
@@ -4900,7 +4899,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 = (0, node_crypto.randomUUID)();
 		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
@@ -4922,8 +4921,20 @@ var EntityManager = class {
 			subscription: req.subscription
 		};
 	}
-	async deleteEventSourceSubscription(entityUrl, req) {
-		const manifestKey = (0, __electric_ax_agents_runtime.eventSourceSubscriptionManifestKey)(req.id);
+	async deleteWebhookSourceSubscription(entityUrl, req) {
+		const manifestKey = (0, __electric_ax_agents_runtime.webhookSourceSubscriptionManifestKey)(req.id);
+		const txid = (0, node_crypto.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 = (0, node_crypto.randomUUID)();
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
@@ -6029,9 +6040,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,
@@ -6051,6 +6066,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;
@@ -6072,37 +6112,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 : (0, __electric_ax_agents_runtime.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
 		}
 	};
 }
@@ -6192,13 +6214,13 @@ var PgSyncBridge = class {
 					}
 					if (!(0, __electric_sql_client.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;
@@ -6247,13 +6269,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,
@@ -6264,9 +6288,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 = {
@@ -6280,6 +6311,7 @@ var PgSyncBridgeManager = class {
 		const resolvedSource = this.resolveSource(canonicalOptions);
 		const sourceRef = (0, __electric_ax_agents_runtime.sourceRefForPgSync)(canonicalOptions);
 		const streamUrl = (0, __electric_ax_agents_runtime.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,
@@ -6320,7 +6352,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());
@@ -7282,6 +7339,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;
@@ -8695,8 +8753,8 @@ const subscriptionLifetimeSchema = __sinclair_typebox.Type.Union([
 	}),
 	__sinclair_typebox.Type.Object({ kind: __sinclair_typebox.Type.Literal(`manual`) })
 ]);
-const eventSourceSubscriptionBodySchema = __sinclair_typebox.Type.Object({
-	sourceKey: __sinclair_typebox.Type.String(),
+const webhookSourceSubscriptionBodySchema = __sinclair_typebox.Type.Object({
+	webhookKey: __sinclair_typebox.Type.String(),
 	bucketKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
 	params: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Unknown())),
 	filterKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
@@ -8729,8 +8787,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);
@@ -8981,22 +9040,22 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return (0, itty_router.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 = (0, __electric_ax_agents_runtime.resolveEventSourceSubscription)({
+		resolved = (0, __electric_ax_agents_runtime.resolveWebhookSourceSubscription)({
 			contract: source,
 			entityUrl,
 			request: {
@@ -9008,18 +9067,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: (0, __electric_ax_agents_runtime.buildEventSourceManifestEntry)(resolved)
+		manifest: (0, __electric_ax_agents_runtime.buildWebhookSourceManifestEntry)(resolved)
 	});
 	return (0, itty_router.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 (0, itty_router.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 (0, itty_router.json)(result);
 }
 function tagResponseBody(entity) {
@@ -9485,7 +9551,7 @@ function toPublicEntityType(entityType) {
 //#endregion
 //#region src/routing/pg-sync-router.ts
 const pgSyncOptionsSchema = __sinclair_typebox.Type.Object({
-	url: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	url: __sinclair_typebox.Type.String(),
 	table: __sinclair_typebox.Type.String(),
 	columns: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(__sinclair_typebox.Type.String())),
 	where: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
@@ -9507,6 +9573,7 @@ const pgSyncRouter = (0, itty_router.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 {
@@ -9521,6 +9588,8 @@ async function registerPgSync(request, ctx) {
 		const result = await ctx.pgSyncBridgeManager.register(options, requestMetadata$1);
 		return (0, itty_router.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)}`);
 	}
 }
@@ -10045,7 +10114,7 @@ const wakeCallbackBodySchema = __sinclair_typebox.Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = (0, itty_router.Router)({ base: `/_electric` });
 internalRouter.get(`/health`, () => (0, itty_router.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);
@@ -10167,11 +10236,11 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return (0, itty_router.status)(204);
 }
-async function listEventSources(_request, ctx) {
-	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
-	return (0, itty_router.json)({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+async function listWebhookSources(_request, ctx) {
+	const webhookSources = ctx.webhookSources ? await ctx.webhookSources.listWebhookSources() : [];
+	return (0, itty_router.json)({ webhookSources: webhookSources.filter(isAgentVisibleWebhookSource) });
 }
-function isAgentVisibleEventSource(source) {
+function isAgentVisibleWebhookSource(source) {
 	return source.agentVisible === true && source.status === `active`;
 }
 async function subscriptionWebhook(request, ctx) {

package/dist/index.d.cts

@@ -252,7 +252,7 @@ import * as drizzle_orm_pg_core303 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core304 from "drizzle-orm/pg-core";
 import * as drizzle_orm75 from "drizzle-orm";
 import * as drizzle_orm76 from "drizzle-orm";
-import { EntityTags, EventPointer, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, PgSyncOptions, PgSyncRequestMetadata, SlashCommandDefinition, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventPointer, PgSyncOptions, PgSyncRequestMetadata, SlashCommandDefinition, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig, WebhookSourceBucket, WebhookSourceContract, WebhookSourceContract as WebhookSourceContract$1, WebhookSourceFilter, WebhookSourceSubscription, WebhookSourceSubscription as WebhookSourceSubscription$1, WebhookSourceSubscriptionInput } from "@electric-ax/agents-runtime";
 import "@sinclair/typebox";
 import { MaybePromise } from "@durable-streams/client";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -4969,6 +4969,7 @@ declare class PostgresRegistry {
   touchPgSyncBridge(sourceRef: string): Promise<void>;
   updatePgSyncBridgeCursor(sourceRef: string, shapeHandle: string, shapeOffset: string, initialSnapshotComplete?: boolean): Promise<void>;
   clearPgSyncBridgeCursor(sourceRef: string): Promise<void>;
+  deletePgSyncBridge(sourceRef: string): Promise<void>;
   upsertEntityBridge(row: {
     sourceRef: string;
     tags: EntityTags;
@@ -5746,18 +5747,28 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
-  upsertEventSourceSubscription(entityUrl: string, req: {
-    subscription: EventSourceSubscription$1;
+  upsertWebhookSourceSubscription(entityUrl: string, req: {
+    subscription: WebhookSourceSubscription$1;
     manifest: Record<string, unknown>;
   }): Promise<{
     txid: string;
-    subscription: EventSourceSubscription$1;
+    subscription: WebhookSourceSubscription$1;
   }>;
-  deleteEventSourceSubscription(entityUrl: string, req: {
+  deleteWebhookSourceSubscription(entityUrl: string, req: {
     id: string;
   }): Promise<{
     txid: string;
   }>;
+  /**
+   * 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.
+   */
+  deletePgSyncObservation(entityUrl: string, req: {
+    sourceRef: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -5836,14 +5847,17 @@ declare class EntityManager {
 //#endregion
 //#region src/pg-sync-bridge-manager.d.ts
 interface PgSyncBridgeManagerOptions {
-  url?: string;
   retry?: {
     initialDelayMs?: number;
     maxDelayMs?: number;
     random?: () => number;
     sleep?: (ms: number) => Promise<void>;
   };
+  fetchFn?: typeof fetch;
+  probeTimeoutMs?: number;
 }
+/** Registration was rejected because the source itself is invalid — map to a 4xx. */
+
 interface PgSyncBridgeCoordinator {
   start?(): Promise<void>;
   register(options: PgSyncOptions, metadata?: PgSyncRequestMetadata): Promise<{
@@ -6033,9 +6047,9 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
-interface EventSourceCatalog {
-  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
-  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+interface WebhookSourceCatalog {
+  listWebhookSources: () => Array<WebhookSourceContract$1> | Promise<Array<WebhookSourceContract$1>>;
+  getWebhookSource: (webhookKey: string) => WebhookSourceContract$1 | undefined | Promise<WebhookSourceContract$1 | undefined>;
 }
 /**
  * Per-request tenant context passed through every router and handler.
@@ -6064,8 +6078,8 @@ interface TenantContext {
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
   pgSyncBridgeManager?: PgSyncBridgeCoordinator;
-  eventSources?: EventSourceCatalog;
-  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
+  webhookSources?: WebhookSourceCatalog;
+  ensureWebhookSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   authorizeRequest?: AuthorizeRequest;
   isShuttingDown: () => boolean;
 }
@@ -6086,4 +6100,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, AuthorizationDecision, AuthorizationResource, AuthorizeRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntityPermission, EntityPermissionGrant, EntityPermissionPropagation, EntitySignal, EntityStatus, EntityTypePermission, EntityTypePermissionGrant, EntityTypePermissionGrantInput, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PermissionSubject, PermissionSubjectKind, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, 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 };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, AuthorizationDecision, AuthorizationResource, AuthorizeRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntityPermission, EntityPermissionGrant, EntityPermissionPropagation, EntitySignal, EntityStatus, EntityTypePermission, EntityTypePermissionGrant, EntityTypePermissionGrantInput, GlobalRoutes, PermissionSubject, PermissionSubjectKind, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, WebhookSourceBucket, WebhookSourceCatalog, WebhookSourceContract, WebhookSourceFilter, WebhookSourceSubscription, WebhookSourceSubscriptionInput, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/dist/index.d.ts

@@ -254,7 +254,7 @@ import * as drizzle_orm_pg_core302 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core303 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core304 from "drizzle-orm/pg-core";
 import { JsonWebKey, KeyObject } from "node:crypto";
-import { EntityTags, EventPointer, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, PgSyncOptions, PgSyncRequestMetadata, SlashCommandDefinition, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventPointer, PgSyncOptions, PgSyncRequestMetadata, SlashCommandDefinition, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig, WebhookSourceBucket, WebhookSourceContract, WebhookSourceContract as WebhookSourceContract$1, WebhookSourceFilter, WebhookSourceSubscription, WebhookSourceSubscription as WebhookSourceSubscription$1, WebhookSourceSubscriptionInput } from "@electric-ax/agents-runtime";
 import { MaybePromise } from "@durable-streams/client";
 import "@sinclair/typebox";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -4968,6 +4968,7 @@ declare class PostgresRegistry {
   touchPgSyncBridge(sourceRef: string): Promise<void>;
   updatePgSyncBridgeCursor(sourceRef: string, shapeHandle: string, shapeOffset: string, initialSnapshotComplete?: boolean): Promise<void>;
   clearPgSyncBridgeCursor(sourceRef: string): Promise<void>;
+  deletePgSyncBridge(sourceRef: string): Promise<void>;
   upsertEntityBridge(row: {
     sourceRef: string;
     tags: EntityTags;
@@ -5745,18 +5746,28 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
-  upsertEventSourceSubscription(entityUrl: string, req: {
-    subscription: EventSourceSubscription$1;
+  upsertWebhookSourceSubscription(entityUrl: string, req: {
+    subscription: WebhookSourceSubscription$1;
     manifest: Record<string, unknown>;
   }): Promise<{
     txid: string;
-    subscription: EventSourceSubscription$1;
+    subscription: WebhookSourceSubscription$1;
   }>;
-  deleteEventSourceSubscription(entityUrl: string, req: {
+  deleteWebhookSourceSubscription(entityUrl: string, req: {
     id: string;
   }): Promise<{
     txid: string;
   }>;
+  /**
+   * 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.
+   */
+  deletePgSyncObservation(entityUrl: string, req: {
+    sourceRef: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -5835,14 +5846,17 @@ declare class EntityManager {
 //#endregion
 //#region src/pg-sync-bridge-manager.d.ts
 interface PgSyncBridgeManagerOptions {
-  url?: string;
   retry?: {
     initialDelayMs?: number;
     maxDelayMs?: number;
     random?: () => number;
     sleep?: (ms: number) => Promise<void>;
   };
+  fetchFn?: typeof fetch;
+  probeTimeoutMs?: number;
 }
+/** Registration was rejected because the source itself is invalid — map to a 4xx. */
+
 interface PgSyncBridgeCoordinator {
   start?(): Promise<void>;
   register(options: PgSyncOptions, metadata?: PgSyncRequestMetadata): Promise<{
@@ -6032,9 +6046,9 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
-interface EventSourceCatalog {
-  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
-  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+interface WebhookSourceCatalog {
+  listWebhookSources: () => Array<WebhookSourceContract$1> | Promise<Array<WebhookSourceContract$1>>;
+  getWebhookSource: (webhookKey: string) => WebhookSourceContract$1 | undefined | Promise<WebhookSourceContract$1 | undefined>;
 }
 /**
  * Per-request tenant context passed through every router and handler.
@@ -6063,8 +6077,8 @@ interface TenantContext {
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
   pgSyncBridgeManager?: PgSyncBridgeCoordinator;
-  eventSources?: EventSourceCatalog;
-  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
+  webhookSources?: WebhookSourceCatalog;
+  ensureWebhookSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   authorizeRequest?: AuthorizeRequest;
   isShuttingDown: () => boolean;
 }
@@ -6085,4 +6099,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, AuthorizationDecision, AuthorizationResource, AuthorizeRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntityPermission, EntityPermissionGrant, EntityPermissionPropagation, EntitySignal, EntityStatus, EntityTypePermission, EntityTypePermissionGrant, EntityTypePermissionGrantInput, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PermissionSubject, PermissionSubjectKind, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, 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 };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, AuthorizationDecision, AuthorizationResource, AuthorizeRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntityPermission, EntityPermissionGrant, EntityPermissionPropagation, EntitySignal, EntityStatus, EntityTypePermission, EntityTypePermissionGrant, EntityTypePermissionGrantInput, GlobalRoutes, PermissionSubject, PermissionSubjectKind, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, WebhookSourceBucket, WebhookSourceCatalog, WebhookSourceContract, WebhookSourceFilter, WebhookSourceSubscription, WebhookSourceSubscriptionInput, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };