@electric-ax/agents-server 0.4.18 → 0.4.20

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 { COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { 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 { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
@@ -32,6 +32,7 @@ __export(schema_exports, {
 	entityPermissionGrants: () => entityPermissionGrants,
 	entityTypePermissionGrants: () => entityTypePermissionGrants,
 	entityTypes: () => entityTypes,
+	pgSyncBridges: () => pgSyncBridges,
 	runnerRuntimeDiagnostics: () => runnerRuntimeDiagnostics,
 	runners: () => runners,
 	scheduledTasks: () => scheduledTasks,
@@ -353,6 +354,18 @@ const scheduledTasks = pgTable(`scheduled_tasks`, {
 	index(`idx_scheduled_tasks_manifest_pending`).on(table.tenantId, table.ownerEntityUrl, table.manifestKey).where(sql`${table.kind} = 'delayed_send' AND ${table.completedAt} IS NULL AND ${table.manifestKey} IS NOT NULL`),
 	index(`idx_scheduled_tasks_stale_claims`).on(table.tenantId, table.claimedAt).where(sql`${table.completedAt} IS NULL AND ${table.claimedAt} IS NOT NULL`)
 ]);
+const pgSyncBridges = pgTable(`pg_sync_bridges`, {
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	sourceRef: text(`source_ref`).notNull(),
+	options: jsonb(`options`).notNull(),
+	streamUrl: text(`stream_url`).notNull(),
+	shapeHandle: text(`shape_handle`),
+	shapeOffset: text(`shape_offset`),
+	initialSnapshotComplete: boolean(`initial_snapshot_complete`).notNull().default(false),
+	lastTouchedAt: timestamp(`last_touched_at`, { withTimezone: true }).notNull().defaultNow(),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [primaryKey({ columns: [table.tenantId, table.sourceRef] }), unique(`uq_pg_sync_bridges_stream_url`).on(table.tenantId, table.streamUrl)]);
 const entityBridges = pgTable(`entity_bridges`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	sourceRef: text(`source_ref`).notNull(),
@@ -813,6 +826,9 @@ var PostgresRegistry = class {
 	entityBridgeWhere(sourceRef) {
 		return and(eq(entityBridges.tenantId, this.tenantId), eq(entityBridges.sourceRef, sourceRef));
 	}
+	pgSyncBridgeWhere(sourceRef) {
+		return and(eq(pgSyncBridges.tenantId, this.tenantId), eq(pgSyncBridges.sourceRef, sourceRef));
+	}
 	async createEntityType(et) {
 		await this.db.insert(entityTypes).values({
 			tenantId: this.tenantId,
@@ -1282,11 +1298,12 @@ var PostgresRegistry = class {
 			};
 			const nextTags = normalizeTags(mutation.nextTags);
 			const updatedAt = Date.now();
-			await tx.update(entities).set({
+			const [updateResult] = await tx.update(entities).set({
 				tags: nextTags,
 				tagsIndex: buildTagsIndex(nextTags),
 				updatedAt
-			}).where(this.entityWhere(url));
+			}).where(this.entityWhere(url)).returning({ txid: sql`pg_current_xact_id()::xid::text` });
+			const txid = updateResult ? parseInt(updateResult.txid) : void 0;
 			await tx.insert(tagStreamOutbox).values({
 				tenantId: this.tenantId,
 				entityUrl: url,
@@ -1304,10 +1321,63 @@ var PostgresRegistry = class {
 			return {
 				entity,
 				changed: true,
-				...op === `insert` || op === `update` ? { op } : {}
+				...op === `insert` || op === `update` ? { op } : {},
+				...txid !== void 0 ? { txid } : {}
 			};
 		});
 	}
+	async upsertPgSyncBridge(row) {
+		await this.db.insert(pgSyncBridges).values({
+			tenantId: this.tenantId,
+			sourceRef: row.sourceRef,
+			options: row.options,
+			streamUrl: row.streamUrl,
+			lastTouchedAt: new Date(),
+			updatedAt: new Date()
+		}).onConflictDoUpdate({
+			target: [pgSyncBridges.tenantId, pgSyncBridges.sourceRef],
+			set: {
+				options: row.options,
+				streamUrl: row.streamUrl,
+				initialSnapshotComplete: false,
+				lastTouchedAt: new Date(),
+				updatedAt: new Date()
+			}
+		});
+		const existing = await this.getPgSyncBridge(row.sourceRef);
+		if (!existing) throw new Error(`Failed to load pgSync bridge ${row.sourceRef}`);
+		return existing;
+	}
+	async getPgSyncBridge(sourceRef) {
+		const rows = await this.db.select().from(pgSyncBridges).where(this.pgSyncBridgeWhere(sourceRef)).limit(1);
+		return rows[0] ? this.rowToPgSyncBridge(rows[0]) : null;
+	}
+	async listPgSyncBridges(tenantId = this.tenantId) {
+		const rows = tenantId === null ? await this.db.select().from(pgSyncBridges) : await this.db.select().from(pgSyncBridges).where(eq(pgSyncBridges.tenantId, tenantId));
+		return rows.map((row) => this.rowToPgSyncBridge(row));
+	}
+	async touchPgSyncBridge(sourceRef) {
+		await this.db.update(pgSyncBridges).set({
+			lastTouchedAt: new Date(),
+			updatedAt: new Date()
+		}).where(this.pgSyncBridgeWhere(sourceRef));
+	}
+	async updatePgSyncBridgeCursor(sourceRef, shapeHandle, shapeOffset, initialSnapshotComplete) {
+		await this.db.update(pgSyncBridges).set({
+			shapeHandle,
+			shapeOffset,
+			...initialSnapshotComplete !== void 0 ? { initialSnapshotComplete } : {},
+			updatedAt: new Date()
+		}).where(this.pgSyncBridgeWhere(sourceRef));
+	}
+	async clearPgSyncBridgeCursor(sourceRef) {
+		await this.db.update(pgSyncBridges).set({
+			shapeHandle: null,
+			shapeOffset: null,
+			initialSnapshotComplete: false,
+			updatedAt: new Date()
+		}).where(this.pgSyncBridgeWhere(sourceRef));
+	}
 	async upsertEntityBridge(row) {
 		await this.db.insert(entityBridges).values({
 			tenantId: this.tenantId,
@@ -1527,6 +1597,20 @@ var PostgresRegistry = class {
 			updated_at: row.updatedAt
 		};
 	}
+	rowToPgSyncBridge(row) {
+		return {
+			tenantId: row.tenantId,
+			sourceRef: row.sourceRef,
+			options: row.options,
+			streamUrl: row.streamUrl,
+			shapeHandle: row.shapeHandle ?? void 0,
+			shapeOffset: row.shapeOffset ?? void 0,
+			initialSnapshotComplete: row.initialSnapshotComplete,
+			lastTouchedAt: row.lastTouchedAt,
+			createdAt: row.createdAt,
+			updatedAt: row.updatedAt
+		};
+	}
 	rowToEntityBridge(row) {
 		return {
 			tenantId: row.tenantId,
@@ -3174,6 +3258,9 @@ 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;
@@ -3186,6 +3273,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 === `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);
@@ -3300,6 +3388,13 @@ function isRecord(value) {
 function cloneRecord(value) {
 	return JSON.parse(JSON.stringify(value));
 }
+function withOptionalTxid(entity, txid) {
+	if (txid === void 0) return entity;
+	return {
+		...entity,
+		txid
+	};
+}
 /**
 * Orchestrates the Electric Agents entity lifecycle: register types, spawn, send, kill.
 *
@@ -4441,15 +4536,17 @@ var EntityManager = class {
 			await this.registry.updateStatus(entityUrl, `idle`);
 			await this.entityBridgeManager?.onEntityChanged(entityUrl);
 		}
+		const txid = crypto.randomUUID();
 		const envelope = entityStateSchema.inbox.insert({
 			key,
-			value
+			value,
+			headers: { txid }
 		});
 		const encoded = this.encodeChangeEvent(envelope);
 		try {
 			if (opts?.producerId) {
 				await this.streamClient.appendIdempotent(entity.streams.main, encoded, { producerId: opts.producerId });
-				return;
+				return { txid };
 			}
 			await this.streamClient.append(entity.streams.main, encoded);
 			if (entity.type === `principal` && req.type === `update_identity`) {
@@ -4457,9 +4554,11 @@ var EntityManager = class {
 				await this.streamClient.append(entity.streams.main, this.encodeChangeEvent({
 					type: `identity`,
 					key: `self`,
-					value: identity
+					value: identity,
+					headers: { txid }
 				}));
 			}
+			return { txid };
 		} catch (err) {
 			if (this.isClosedStreamError(err)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
 			throw err;
@@ -4480,18 +4579,26 @@ var EntityManager = class {
 			if (req.status === `cancelled`) value.cancelled_at = now;
 		}
 		if (Object.keys(value).length === 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `No inbox fields to update`, 400);
+		const txid = crypto.randomUUID();
 		const envelope = entityStateSchema.inbox.update({
 			key,
-			value
+			value,
+			headers: { txid }
 		});
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
+		return { txid };
 	}
 	async deleteInboxMessage(entityUrl, key) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
 		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
-		const envelope = entityStateSchema.inbox.delete({ key });
+		const txid = crypto.randomUUID();
+		const envelope = entityStateSchema.inbox.delete({
+			key,
+			headers: { txid }
+		});
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
+		return { txid };
 	}
 	isAttachmentStreamPath(path$1) {
 		return /^\/[^/]+\/[^/]+\/attachments\/[^/]+$/.test(path$1);
@@ -4580,28 +4687,26 @@ var EntityManager = class {
 		await this.streamClient.delete(attachment.streamPath).catch(() => void 0);
 		return { txid };
 	}
-	async setTag(entityUrl, key, req, token) {
+	async setTag(entityUrl, key, req) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
-		if (!this.isValidWriteToken(entity, token)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Invalid write token`, 401);
 		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		if (typeof req.value !== `string`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Tag values must be strings`, 400);
 		const result = await this.registry.setEntityTag(entityUrl, key, req.value);
 		const updated = result.entity;
 		if (!updated) throw new ElectricAgentsError(ErrCodeEntityPersistFailed, `Entity not found after tag write`, 500);
 		if (result.changed && this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
-		return updated;
+		return withOptionalTxid(updated, result.txid);
 	}
-	async deleteTag(entityUrl, key, token) {
+	async deleteTag(entityUrl, key) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
-		if (!this.isValidWriteToken(entity, token)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Invalid write token`, 401);
 		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
 		const result = await this.registry.removeEntityTag(entityUrl, key);
 		const updated = result.entity;
 		if (!updated) throw new ElectricAgentsError(ErrCodeEntityPersistFailed, `Entity not found after tag delete`, 500);
 		if (result.changed && this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
-		return updated;
+		return withOptionalTxid(updated, result.txid);
 	}
 	async ensureEntitiesMembershipStream(tags, principal) {
 		if (!this.entityBridgeManager) throw new Error(`Entity bridge manager not configured`);
@@ -5397,6 +5502,9 @@ function isPermanentElectricAgentsError(err) {
 	const name = typeof err === `object` && err !== null && `name` in err ? err.name : void 0;
 	return name === `ElectricAgentsError` && typeof status$1 === `number` && status$1 >= 400 && status$1 < 500;
 }
+function cronTaskStreamPath(payload) {
+	return typeof payload.streamPath === `string` ? payload.streamPath : null;
+}
 function normalizeTask(row) {
 	return {
 		id: Number(row.id),
@@ -5739,6 +5847,15 @@ var Scheduler = class {
       `;
 			if (completed.length === 0) return;
 			const nextFireAt = getNextCronFireAt(task.cronExpression, task.cronTimezone, task.fireAt);
+			const streamPath = cronTaskStreamPath(task.payload);
+			const subscriberRows = streamPath ? await sql$1`
+            select 1 as exists
+            from wake_registrations
+            where tenant_id = ${tenantId}
+              and source_url = ${streamPath}
+            limit 1
+          ` : [];
+			if (subscriberRows.length === 0) return;
 			await sql$1`
         insert into scheduled_tasks (
           tenant_id,
@@ -5838,6 +5955,308 @@ 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`;
+const DEFAULT_RETRY_INITIAL_DELAY_MS = 1e3;
+const DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
+function buildElectricShapeParams(options) {
+	return {
+		table: options.table,
+		...options.columns !== void 0 ? { columns: [...options.columns] } : {},
+		...options.where !== void 0 ? { where: options.where } : {},
+		...options.params !== void 0 ? { params: Array.isArray(options.params) ? [...options.params] : { ...options.params } } : {},
+		...options.replica !== void 0 ? { replica: options.replica } : {},
+		...options.metadata?.tenantId ? { electric_agents_tenant_id: options.metadata.tenantId } : {},
+		...options.metadata?.principalKind ? { electric_agents_principal_kind: options.metadata.principalKind } : {},
+		...options.metadata?.principalId ? { electric_agents_principal_id: options.metadata.principalId } : {},
+		...options.metadata?.principalKey ? { electric_agents_principal_key: options.metadata.principalKey } : {},
+		...options.metadata?.principalUrl ? { electric_agents_principal_url: options.metadata.principalUrl } : {},
+		...options.metadata?.entityUrl ? { electric_agents_entity_url: options.metadata.entityUrl } : {},
+		...options.metadata?.entityType ? { electric_agents_entity_type: options.metadata.entityType } : {},
+		...options.metadata?.streamPath ? { electric_agents_stream_path: options.metadata.streamPath } : {},
+		...options.metadata?.runtimeConsumerId ? { electric_agents_runtime_consumer_id: options.metadata.runtimeConsumerId } : {},
+		...options.metadata?.wakeId ? { electric_agents_wake_id: options.metadata.wakeId } : {}
+	};
+}
+function jsonSafe(value) {
+	if (typeof value === `bigint`) return value.toString();
+	if (value === null || typeof value !== `object`) return value;
+	if (Array.isArray(value)) return value.map(jsonSafe);
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, jsonSafe(item)]));
+}
+function stableJson(value) {
+	if (typeof value === `bigint`) return JSON.stringify(value.toString());
+	if (value === null || typeof value !== `object`) return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(`,`)}]`;
+	return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(`,`)}}`;
+}
+function parseElectricOffset(offset) {
+	if (offset === `-1`) return offset;
+	return /^\d+_\d+$/.test(offset) ? offset : null;
+}
+function rowKeyForMessage(message) {
+	const headers = message.headers;
+	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) {
+	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);
+	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
+		},
+		headers: {
+			operation,
+			timestamp: timestamp$1
+		}
+	};
+}
+function cursorFromRow(row) {
+	return row?.shapeHandle && row.shapeOffset ? {
+		handle: row.shapeHandle,
+		offset: row.shapeOffset,
+		initialSnapshotComplete: row.initialSnapshotComplete
+	} : void 0;
+}
+var PgSyncBridge = class {
+	producer = null;
+	unsubscribe = null;
+	abortController = null;
+	skipChangesUntilUpToDate = false;
+	recovering = false;
+	committedCursor;
+	retryAttempt = 0;
+	constructor(sourceRef, streamUrl, options, resolvedSource, retry, streamClient, registry, evaluateWakes, initialCursor) {
+		this.sourceRef = sourceRef;
+		this.streamUrl = streamUrl;
+		this.options = options;
+		this.resolvedSource = resolvedSource;
+		this.retry = retry;
+		this.streamClient = streamClient;
+		this.registry = registry;
+		this.evaluateWakes = evaluateWakes;
+		this.initialCursor = initialCursor;
+		this.committedCursor = initialCursor;
+	}
+	async start() {
+		if (!this.producer) this.producer = new IdempotentProducer(new DurableStream({
+			url: `${this.streamClient.baseUrl}${this.streamUrl}`,
+			contentType: `application/json`
+		}), `pg-sync-bridge-${this.sourceRef}`);
+		if (this.initialCursor) {
+			const offset = parseElectricOffset(this.initialCursor.offset);
+			if (offset) {
+				this.startStream(offset, this.initialCursor.handle, !this.initialCursor.initialSnapshotComplete);
+				return;
+			}
+		}
+		await this.registry?.clearPgSyncBridgeCursor(this.sourceRef);
+		this.startStream(`now`, void 0, true);
+	}
+	async stop() {
+		this.unsubscribe?.();
+		this.abortController?.abort();
+		this.unsubscribe = null;
+		this.abortController = null;
+		try {
+			await this.producer?.flush();
+		} finally {
+			await this.producer?.detach();
+			this.producer = null;
+		}
+	}
+	startStream(offset, handle, skipChangesUntilUpToDate = false, log = offset === `now` ? `changes_only` : `full`) {
+		this.unsubscribe?.();
+		this.abortController?.abort();
+		this.skipChangesUntilUpToDate = skipChangesUntilUpToDate;
+		this.abortController = new AbortController();
+		const stream = new ShapeStream({
+			url: this.resolvedSource.url,
+			params: buildElectricShapeParams(this.options),
+			offset,
+			log,
+			...handle ? { handle } : {},
+			signal: this.abortController.signal
+		});
+		this.unsubscribe = stream.subscribe(async (messages) => {
+			try {
+				for (const message of messages) {
+					if (isControlMessage(message)) {
+						if (message.headers.control === `must-refetch`) {
+							await this.registry?.clearPgSyncBridgeCursor(this.sourceRef);
+							this.startStream(`now`, void 0, true);
+							return;
+						}
+						if (message.headers.control === `up-to-date`) {
+							this.skipChangesUntilUpToDate = false;
+							await this.persistCursor(stream, true);
+							continue;
+						}
+						await this.persistCursor(stream);
+						continue;
+					}
+					if (!isChangeMessage(message)) continue;
+					if (!this.skipChangesUntilUpToDate) {
+						const event = pgSyncMessageToDurableEvent(message, this.options);
+						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);
+						}
+					}
+					await this.persistCursor(stream);
+					this.retryAttempt = 0;
+				}
+			} catch (error) {
+				serverLog.warn(`[pg-sync-bridge] subscription callback failed for ${this.sourceRef}:`, error);
+				await this.recoverStream();
+			}
+		}, (error) => {
+			if (this.abortController?.signal.aborted) return;
+			serverLog.warn(`[pg-sync-bridge] subscription failed for ${this.sourceRef}:`, error);
+			this.recoverStream();
+		});
+	}
+	async recoverStream() {
+		if (this.recovering) return;
+		this.recovering = true;
+		try {
+			const attempt = this.retryAttempt++;
+			const baseDelay = Math.min(this.retry.initialDelayMs * 2 ** attempt, this.retry.maxDelayMs);
+			const jitter = Math.floor(baseDelay * .2 * this.retry.random());
+			const delay = baseDelay + jitter;
+			if (delay > 0) await this.retry.sleep(delay);
+			const offset = this.committedCursor ? parseElectricOffset(this.committedCursor.offset) : null;
+			if (offset && this.committedCursor) this.startStream(offset, this.committedCursor.handle, !this.committedCursor.initialSnapshotComplete);
+			else {
+				await this.registry?.clearPgSyncBridgeCursor(this.sourceRef);
+				this.startStream(`now`, void 0, true);
+			}
+		} finally {
+			this.recovering = false;
+		}
+	}
+	async persistCursor(stream, initialSnapshotComplete = !this.skipChangesUntilUpToDate) {
+		const shapeHandle = stream.shapeHandle;
+		const shapeOffset = stream.lastOffset;
+		if (!shapeHandle || !shapeOffset || shapeOffset === `-1`) return;
+		await this.registry?.updatePgSyncBridgeCursor(this.sourceRef, shapeHandle, shapeOffset, initialSnapshotComplete);
+		this.committedCursor = {
+			handle: shapeHandle,
+			offset: shapeOffset,
+			initialSnapshotComplete
+		};
+	}
+};
+var PgSyncBridgeManager = class {
+	bridges = new Map();
+	starting = new Map();
+	url;
+	retry;
+	constructor(streamClient, evaluateWakes, registry, options = {}) {
+		this.streamClient = streamClient;
+		this.evaluateWakes = evaluateWakes;
+		this.registry = registry;
+		this.url = options.url ?? PG_SYNC_ELECTRIC_SHAPE_URL;
+		this.retry = {
+			initialDelayMs: options.retry?.initialDelayMs ?? DEFAULT_RETRY_INITIAL_DELAY_MS,
+			maxDelayMs: options.retry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
+			random: options.retry?.random ?? Math.random,
+			sleep: options.retry?.sleep ?? ((ms) => new Promise((resolve$1) => setTimeout(resolve$1, ms)))
+		};
+	}
+	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);
+		})));
+	}
+	async register(options, metadata) {
+		const mergedMetadata = {
+			...options.metadata,
+			...metadata
+		};
+		const canonicalOptions = {
+			...canonicalPgSyncOptions(options),
+			...Object.keys(mergedMetadata).length > 0 ? { metadata: mergedMetadata } : {}
+		};
+		const resolvedSource = this.resolveSource(canonicalOptions);
+		const sourceRef = sourceRefForPgSync(canonicalOptions);
+		const streamUrl = getPgSyncStreamPath(sourceRef, this.registry?.tenantId);
+		const row = await this.registry?.upsertPgSyncBridge({
+			sourceRef,
+			options: canonicalOptions,
+			streamUrl
+		});
+		await this.streamClient.ensure(streamUrl, { contentType: `application/json` });
+		if (!this.bridges.has(sourceRef)) {
+			let start = this.starting.get(sourceRef);
+			if (!start) {
+				start = (async () => {
+					const bridge = new PgSyncBridge(sourceRef, streamUrl, canonicalOptions, resolvedSource, this.retry, this.streamClient, this.registry, this.evaluateWakes, cursorFromRow(row));
+					await bridge.start();
+					this.bridges.set(sourceRef, bridge);
+				})().finally(() => this.starting.delete(sourceRef));
+				this.starting.set(sourceRef, start);
+			}
+			await start;
+		}
+		return {
+			sourceRef,
+			streamUrl
+		};
+	}
+	async ensureBridge(row) {
+		if (this.bridges.has(row.sourceRef)) return;
+		let start = this.starting.get(row.sourceRef);
+		if (!start) {
+			start = (async () => {
+				await this.streamClient.ensure(row.streamUrl, { contentType: `application/json` });
+				const canonicalOptions = canonicalPgSyncOptions(row.options);
+				const resolvedSource = this.resolveSource(canonicalOptions);
+				const bridge = new PgSyncBridge(row.sourceRef, row.streamUrl, canonicalOptions, resolvedSource, this.retry, this.streamClient, this.registry, this.evaluateWakes, cursorFromRow(row));
+				await bridge.start();
+				this.bridges.set(row.sourceRef, bridge);
+			})().finally(() => this.starting.delete(row.sourceRef));
+			this.starting.set(row.sourceRef, start);
+		}
+		await start;
+	}
+	resolveSource(options) {
+		return { url: options.url ?? this.url };
+	}
+	async stop() {
+		await Promise.allSettled(this.starting.values());
+		await Promise.all([...this.bridges.values()].map((bridge) => bridge.stop()));
+		this.bridges.clear();
+	}
+};
+
 //#endregion
 //#region src/runtime.ts
 function omitUndefined(value) {
@@ -5852,6 +6271,7 @@ var ElectricAgentsTenantRuntime = class {
 	wakeRegistry;
 	scheduler;
 	entityBridgeManager;
+	pgSyncBridgeManager;
 	claimWriteTokens;
 	manager;
 	constructor(options) {
@@ -5876,9 +6296,10 @@ var ElectricAgentsTenantRuntime = class {
 			writeTokenValidator: (entity, token) => this.claimWriteTokens.isValid(this.serviceId, entity.streams.main, token),
 			stopWakeRegistryOnShutdown: options.stopWakeRegistryOnShutdown ?? false
 		});
+		this.pgSyncBridgeManager = options.pgSyncBridgeManager ?? new PgSyncBridgeManager(this.streamClient, (sourceUrl, event) => this.manager.evaluateWakes(sourceUrl, event), this.registry, options.pgSync);
 	}
 	async stop() {
-		await this.manager.shutdown();
+		await Promise.all([this.manager.shutdown(), this.pgSyncBridgeManager.stop()]);
 	}
 	async rehydrateCronSchedules() {
 		const rows = await this.db.select({ sourceUrl: wakeRegistrations.sourceUrl }).from(wakeRegistrations).where(eq(wakeRegistrations.tenantId, this.serviceId));
@@ -6642,7 +7063,10 @@ var WakeRegistry = class {
 		}
 		if (!isChangeMessage(message)) return;
 		if (message.headers.operation === `delete`) {
-			this.removeCachedRegistrationByDbId(Number(message.key));
+			const oldValue = message.old_value;
+			const oldId = Number(oldValue?.id);
+			if (Number.isFinite(oldId)) this.removeCachedRegistrationByDbId(oldId);
+			else this.resetCachedRegistrations();
 			return;
 		}
 		this.upsertCachedRegistration(this.normalizeShapeRow(message.value));
@@ -6753,9 +7177,9 @@ var WakeRegistry = class {
 	matchCondition(reg, event) {
 		if (reg.condition === `runFinished`) {
 			if (event.type !== `run`) return null;
-			const value = event.value;
+			const value$1 = event.value;
 			const headers$1 = event.headers;
-			const status$1 = value?.status;
+			const status$1 = value$1?.status;
 			const operation$1 = headers$1?.operation;
 			if (operation$1 !== `update`) return null;
 			if (status$1 !== `completed` && status$1 !== `failed`) return null;
@@ -6778,13 +7202,15 @@ var WakeRegistry = class {
 		}
 		const kind = operation === `delete` ? `delete` : operation === `update` ? `update` : `insert`;
 		if (condition.ops && condition.ops.length > 0 && !condition.ops.includes(kind)) return null;
+		const value = event.value;
 		const change = {
 			collection: eventType,
 			kind,
 			key: event.key || ``
 		};
+		if (value && `value` in value) change.value = value.value;
+		if (value && `oldValue` in value) change.oldValue = value.oldValue;
 		if (eventType === `inbox`) {
-			const value = event.value;
 			if (typeof value?.from === `string`) change.from = value.from;
 			if (typeof value?.from_principal === `string`) change.from_principal = value.from_principal;
 			if (typeof value?.from_agent === `string`) change.from_agent = value.from_agent;
@@ -7188,6 +7614,22 @@ function resolveDurableStreamsRoutingAdapter(adapter, _durableStreamsUrl) {
 
 //#endregion
 //#region src/utils/server-utils.ts
+/**
+* Raised when an Electric shape proxy request must be rejected for security
+* reasons (an un-scoped table, or a client `where` clause that could escape the
+* enforced per-tenant/per-principal scoping). The global `errorMapper` hook
+* maps this to an HTTP error response. Defined here (rather than reusing
+* `ElectricAgentsError`) to keep this module free of the heavy entity-manager
+* import graph.
+*/
+var ElectricProxyError = class extends Error {
+	constructor(code, message, status$1) {
+		super(message);
+		this.code = code;
+		this.status = status$1;
+		this.name = `ElectricProxyError`;
+	}
+};
 function buildElectricProxyTarget(options) {
 	const targetPath = options.incomingUrl.pathname.replace(`/_electric/electric`, ``);
 	const target = electricUrlWithPath(options.electricUrl, targetPath);
@@ -7197,7 +7639,12 @@ function buildElectricProxyTarget(options) {
 	applyElectricUrlQueryParams(target, options.electricUrl);
 	if (targetPath !== `/v1/shape`) return target;
 	if (options.electricSecret) target.searchParams.set(`secret`, options.electricSecret);
-	const table = options.incomingUrl.searchParams.get(`table`);
+	const clientWhere = options.incomingUrl.searchParams.get(`where`);
+	if (clientWhere !== null && !isSelfContainedWhereClause(clientWhere)) throw new ElectricProxyError(`INVALID_WHERE`, `Invalid where clause`, 400);
+	const tableParams = options.incomingUrl.searchParams.getAll(`table`);
+	if (tableParams.length !== 1) throw new ElectricProxyError(`TABLE_NOT_ALLOWED`, `Table is not available through the Electric proxy`, 403);
+	const table = tableParams[0];
+	target.searchParams.set(`table`, table);
 	if (table === `entities`) {
 		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","created_by","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
 		applyShapeWhere(target, buildReadableEntitiesWhere({
@@ -7255,9 +7702,39 @@ function buildElectricProxyTarget(options) {
 			principalKind: options.principalKind ?? ``,
 			permissionBypass: options.permissionBypass
 		}));
-	}
+	} else throw new ElectricProxyError(`TABLE_NOT_ALLOWED`, `Table is not available through the Electric proxy`, 403);
 	return target;
 }
+/**
+* Returns true when a client-supplied Electric `where` clause is self-contained:
+* its parentheses are balanced, never close below the top level, all string
+* (`'`) and identifier (`"`) literals are terminated, and it contains no SQL
+* comment markers. Such a clause cannot break out of the `(...)` group it is
+* wrapped in when AND-combined with the enforced scoping predicate, nor comment
+* out the trailing paren the proxy appends. Characters inside string/identifier
+* literals are ignored. Comment markers are rejected unconditionally (even where
+* harmless) as a conservative defensive measure; dollar-quoted and `E''` strings
+* are not modeled and only ever cause fail-safe over-rejection, never a bypass.
+*/
+function isSelfContainedWhereClause(where) {
+	let depth = 0;
+	let quote = null;
+	for (let i = 0; i < where.length; i++) {
+		const ch = where[i];
+		if (quote !== null) {
+			if (ch === quote) if (where[i + 1] === quote) i++;
+			else quote = null;
+			continue;
+		}
+		if (ch === `'` || ch === `"`) quote = ch;
+		else if (ch === `(`) depth++;
+		else if (ch === `)`) {
+			depth--;
+			if (depth < 0) return false;
+		} else if (ch === `-` && where[i + 1] === `-` || ch === `/` && where[i + 1] === `*`) return false;
+	}
+	return depth === 0 && quote === null;
+}
 function buildReadableEntitiesWhere(options) {
 	const tenant = sqlStringLiteral(options.tenantId);
 	if (options.permissionBypass) return `tenant_id = ${tenant}`;
@@ -7893,7 +8370,10 @@ async function authorizeDurableStreamAccess(request, ctx) {
 	}
 	if (method === `PUT` || method === `POST`) {
 		const ownerEntityUrl = request.headers.get(SHARED_STATE_OWNER_ENTITY_HEADER)?.trim() || void 0;
-		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) return void 0;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) {
+			if (ownerEntityUrl) await ctx.entityManager.registry.replaceSharedStateLink(ownerEntityUrl, `shared-state:${sharedStateId}`, sharedStateId);
+			return void 0;
+		}
 		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to write shared state`);
 	}
 	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to access shared state`);
@@ -8262,7 +8742,7 @@ async function parseAttachmentForm(request) {
 	};
 }
 function contentDisposition(filename) {
-	const fallback = filename.replace(/["\\\r\n]/g, `_`);
+	const fallback = filename.replace(/[^\x20-\x7e]|["\\]/g, `_`);
 	return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
 }
 function rejectPrincipalEntityMutation(request, action) {
@@ -8460,22 +8940,28 @@ async function deleteEventSourceSubscription(request, ctx) {
 	const result = await ctx.entityManager.deleteEventSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
 	return json(result);
 }
+function tagResponseBody(entity) {
+	const publicEntity = toPublicEntity(entity);
+	if (entity.txid !== void 0) return {
+		...publicEntity,
+		txid: entity.txid
+	};
+	return publicEntity;
+}
 async function setTag(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tag updated`);
 	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);
-	const token = writeTokenFromRequest(request);
-	const updated = await ctx.entityManager.setTag(entityUrl, decodeURIComponent(request.params.tagKey), { value: parsed.value }, token);
-	return json(toPublicEntity(updated));
+	const updated = await ctx.entityManager.setTag(entityUrl, decodeURIComponent(request.params.tagKey), { value: parsed.value });
+	return json(tagResponseBody(updated));
 }
 async function deleteTag(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tag deleted`);
 	if (principalMutationError) return principalMutationError;
 	const { entityUrl } = requireExistingEntityRoute(request);
-	const token = writeTokenFromRequest(request);
-	const updated = await ctx.entityManager.deleteTag(entityUrl, decodeURIComponent(request.params.tagKey), token);
-	return json(toPublicEntity(updated));
+	const updated = await ctx.entityManager.deleteTag(entityUrl, decodeURIComponent(request.params.tagKey));
+	return json(tagResponseBody(updated));
 }
 async function forkEntity(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `forked`);
@@ -8542,9 +9028,12 @@ async function sendEntity(request, ctx) {
 		mode: parsed.mode,
 		position: parsed.position
 	};
-	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, sendReq, new Date(Date.now() + parsed.afterMs));
-	else await ctx.entityManager.send(entityUrl, sendReq);
-	return status(204);
+	if (parsed.afterMs && parsed.afterMs > 0) {
+		await ctx.entityManager.enqueueDelayedSend(entityUrl, sendReq, new Date(Date.now() + parsed.afterMs));
+		return status(204);
+	}
+	const result = await ctx.entityManager.send(entityUrl, sendReq);
+	return json(result);
 }
 async function createAttachment(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
@@ -8587,13 +9076,13 @@ async function deleteAttachment(request, ctx) {
 async function updateInboxMessage(request, ctx) {
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);
-	await ctx.entityManager.updateInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey), parsed);
-	return status(204);
+	const result = await ctx.entityManager.updateInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey), parsed);
+	return json(result);
 }
 async function deleteInboxMessage(request, ctx) {
 	const { entityUrl } = requireExistingEntityRoute(request);
-	await ctx.entityManager.deleteInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey));
-	return status(204);
+	const result = await ctx.entityManager.deleteInboxMessage(entityUrl, decodeURIComponent(request.params.messageKey));
+	return json(result);
 }
 async function spawnEntity(request, ctx) {
 	const parsed = routeBody(request);
@@ -8864,6 +9353,49 @@ function toPublicEntityType(entityType) {
 	};
 }
 
+//#endregion
+//#region src/routing/pg-sync-router.ts
+const pgSyncOptionsSchema = Type.Object({
+	url: Type.Optional(Type.String()),
+	table: Type.String(),
+	columns: Type.Optional(Type.Array(Type.String())),
+	where: Type.Optional(Type.String()),
+	params: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Record(Type.String(), Type.String())])),
+	replica: Type.Optional(Type.Union([Type.Literal(`default`), Type.Literal(`full`)]))
+});
+const pgSyncRequestMetadataSchema = Type.Object({
+	entityUrl: Type.Optional(Type.String()),
+	entityType: Type.Optional(Type.String()),
+	streamPath: Type.Optional(Type.String()),
+	runtimeConsumerId: Type.Optional(Type.String()),
+	wakeId: Type.Optional(Type.String())
+});
+const pgSyncRegisterBodySchema = Type.Object({
+	options: pgSyncOptionsSchema,
+	metadata: Type.Optional(pgSyncRequestMetadataSchema)
+});
+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.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 {
+		const requestMetadata$1 = {
+			tenantId: ctx.service,
+			principalKind: ctx.principal.kind,
+			principalId: ctx.principal.id,
+			principalKey: ctx.principal.key,
+			principalUrl: ctx.principal.url,
+			...metadata ?? {}
+		};
+		const result = await ctx.pgSyncBridgeManager.register(options, requestMetadata$1);
+		return json(result);
+	} catch (error) {
+		return apiError(500, ErrCodeInvalidRequest, `pgSync registration failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 //#endregion
 //#region src/routing/hooks.ts
 const SPAN_KEY = Symbol(`agents-server.otel-span`);
@@ -8938,6 +9470,10 @@ function errorMapper(err, req) {
 		});
 	}
 	if (err instanceof ElectricAgentsError) return apiError(err.status, err.code, err.message, err.details);
+	if (err instanceof ElectricProxyError) {
+		serverLog.warn(`[agent-server] Electric proxy rejected request (${err.code}): ${req.url}`);
+		return apiError(err.status, err.code, err.message);
+	}
 	serverLog.error(`[agent-server] Unhandled error:`, err);
 	return apiError(500, `INTERNAL_SERVER_ERROR`, `Internal server error`);
 }
@@ -9388,6 +9924,7 @@ internalRouter.all(`/runners`, runnersRouter.fetch);
 internalRouter.all(`/runners/*`, runnersRouter.fetch);
 internalRouter.all(`/entities/*`, entitiesRouter.fetch);
 internalRouter.all(`/entity-types/*`, entityTypesRouter.fetch);
+internalRouter.all(`/pg-sync/*`, pgSyncRouter.fetch);
 internalRouter.all(`/observations/*`, observationsRouter.fetch);
 internalRouter.get(`/electric/*`, electricProxyRouter.fetch);
 internalRouter.all(`*`, () => status(404));
@@ -9771,6 +10308,9 @@ const globalRouter = AutoRouter({
 	finally: [otelEndSpan, applyCors]
 });
 globalRouter.all(`/_electric/shared-state/*`, durableStreamsRouter.fetch);
+globalRouter.all(`/_electric/pg-sync/register`, internalRouter.fetch);
+globalRouter.get(`/_electric/pg-sync/*`, durableStreamsRouter.fetch);
+globalRouter.head(`/_electric/pg-sync/*`, durableStreamsRouter.fetch);
 globalRouter.all(`/_electric/*`, internalRouter.fetch);
 globalRouter.all(`*`, durableStreamsRouter.fetch);