@electric-ax/agents-server 0.4.19 → 0.5.0

package/dist/entrypoint.js

@@ -4,7 +4,7 @@ import { DurableStreamTestServer } from "@durable-streams/server";
 import { createServer } from "node:http";
 import { createServerAdapter } from "@whatwg-node/server";
 import { Agent } from "undici";
-import { COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, createEntityRegistry, createRuntimeHandler, 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 { COMMENTS_CONTRACT, COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, createEntityRegistry, createRuntimeHandler, 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 fs, { existsSync } from "node:fs";
 import path, { dirname, resolve } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
@@ -47,6 +47,7 @@ __export(schema_exports, {
 	entityPermissionGrants: () => entityPermissionGrants,
 	entityTypePermissionGrants: () => entityTypePermissionGrants,
 	entityTypes: () => entityTypes,
+	pgSyncBridges: () => pgSyncBridges,
 	runnerRuntimeDiagnostics: () => runnerRuntimeDiagnostics,
 	runners: () => runners,
 	scheduledTasks: () => scheduledTasks,
@@ -64,6 +65,7 @@ const entityTypes = pgTable(`entity_types`, {
 	creationSchema: jsonb(`creation_schema`),
 	inboxSchemas: jsonb(`inbox_schemas`),
 	stateSchemas: jsonb(`state_schemas`),
+	externallyWritableCollections: jsonb(`externally_writable_collections`).$type(),
 	slashCommands: jsonb(`slash_commands`),
 	serveEndpoint: text(`serve_endpoint`),
 	defaultDispatchPolicy: jsonb(`default_dispatch_policy`),
@@ -368,6 +370,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(),
@@ -1134,6 +1148,22 @@ async function fileExists(filePath) {
 		return false;
 	}
 }
+/**
+* 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);
@@ -1143,7 +1173,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({
@@ -1201,9 +1236,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$2(options.tenantId);
 	if (options.permissionBypass) return `tenant_id = ${tenant}`;
@@ -2721,6 +2786,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,
@@ -2729,6 +2797,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -2742,6 +2811,7 @@ var PostgresRegistry = class {
 				creationSchema: et.creation_schema ?? null,
 				inboxSchemas: et.inbox_schemas ?? null,
 				stateSchemas: et.state_schemas ?? null,
+				externallyWritableCollections: et.externally_writable_collections ?? null,
 				slashCommands: et.slash_commands ?? null,
 				serveEndpoint: et.serve_endpoint ?? null,
 				defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -2760,6 +2830,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -2787,6 +2858,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -3190,11 +3262,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,
@@ -3212,10 +3285,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,
@@ -3378,6 +3504,7 @@ var PostgresRegistry = class {
 			creation_schema: row.creationSchema,
 			inbox_schemas: row.inboxSchemas,
 			state_schemas: row.stateSchemas,
+			externally_writable_collections: row.externallyWritableCollections ?? void 0,
 			slash_commands: row.slashCommands ?? void 0,
 			serve_endpoint: row.serveEndpoint ?? void 0,
 			default_dispatch_policy: row.defaultDispatchPolicy ?? void 0,
@@ -3435,6 +3562,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,
@@ -3515,6 +3656,9 @@ var PostgresRegistry = class {
 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;
@@ -3527,6 +3671,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);
@@ -3641,6 +3786,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.
 *
@@ -3715,6 +3867,7 @@ var EntityManager = class {
 			creation_schema: req.creation_schema,
 			inbox_schemas: req.inbox_schemas,
 			state_schemas: req.state_schemas,
+			externally_writable_collections: req.externally_writable_collections,
 			slash_commands: req.slash_commands,
 			serve_endpoint: req.serve_endpoint,
 			default_dispatch_policy: defaultDispatchPolicy,
@@ -4782,15 +4935,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`) {
@@ -4798,13 +4953,49 @@ 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;
+		}
+	}
+	async writeCollection(entityUrl, collection, req) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		const { externallyWritableCollections } = await this.getEffectiveSchemas(entity);
+		const config = externallyWritableCollections?.[collection];
+		if (!config) throw new ElectricAgentsError(ErrCodeUnauthorized, `Collection "${collection}" is not writable`, 403);
+		const allowedOperations = config.operations ?? [`insert`];
+		if (!allowedOperations.includes(req.operation)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Operation "${req.operation}" is not allowed on collection "${collection}"`, 403);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
+		if (this.isForkWorkLockedEntity(entityUrl)) this.assertEntityNotForkWorkLocked(entityUrl);
+		if (req.operation !== `delete` && (req.value === void 0 || req.value === null)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `value is required for ${req.operation}`, 400);
+		if (req.operation !== `insert` && !req.key) throw new ElectricAgentsError(ErrCodeInvalidRequest, `key is required for ${req.operation}`, 400);
+		const key = req.key ?? `${collection}-${randomUUID()}`;
+		const event = {
+			type: config.type,
+			key,
+			headers: {
+				operation: req.operation,
+				timestamp: new Date().toISOString(),
+				principal: req.principal
+			}
+		};
+		if (req.operation !== `delete`) event.value = req.value;
+		const validationError = await this.validateWriteEvent(entity, event);
+		if (validationError) throw new ElectricAgentsError(validationError.code, validationError.message, validationError.status);
+		const encoded = this.encodeChangeEvent(event);
+		try {
+			await this.streamClient.append(entity.streams.main, encoded);
 		} catch (err) {
 			if (this.isClosedStreamError(err)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
 			throw err;
 		}
+		return { key };
 	}
 	async updateInboxMessage(entityUrl, key, req) {
 		const entity = await this.registry.getEntity(entityUrl);
@@ -4821,18 +5012,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);
@@ -4921,28 +5120,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`);
@@ -5492,7 +5689,8 @@ var EntityManager = class {
 	async getEffectiveSchemas(entity) {
 		if (!entity.type) return {
 			inboxSchemas: entity.inbox_schemas,
-			stateSchemas: entity.state_schemas
+			stateSchemas: entity.state_schemas,
+			externallyWritableCollections: void 0
 		};
 		const latestType = await this.registry.getEntityType(entity.type);
 		return {
@@ -5503,7 +5701,8 @@ var EntityManager = class {
 			stateSchemas: latestType?.state_schemas ? {
 				...entity.state_schemas ?? {},
 				...latestType.state_schemas
-			} : entity.state_schemas
+			} : entity.state_schemas,
+			externallyWritableCollections: latestType?.externally_writable_collections
 		};
 	}
 	isClosedStreamError(err) {
@@ -5766,6 +5965,15 @@ const spawnBodySchema = Type.Object({
 		manifestKey: Type.Optional(Type.String())
 	}))
 });
+const writeCollectionBodySchema = Type.Object({
+	operation: Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]),
+	key: Type.Optional(Type.String()),
+	value: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+}, { additionalProperties: false });
 const sendBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	key: Type.Optional(Type.String()),
@@ -5898,6 +6106,7 @@ entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, withEntityPermissi
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`delete`), killEntity);
 entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), withEntityPermission(`signal`), signalEntity);
 entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), withEntityPermission(`write`), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/collections/:collection`, withExistingEntity, withSchema(writeCollectionBodySchema), withEntityPermission(`write`), writeCollection);
 entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, withEntityPermission(`write`), createAttachment);
 entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`read`), readAttachment);
 entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`write`), deleteAttachment);
@@ -6003,7 +6212,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) {
@@ -6201,22 +6410,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`);
@@ -6283,9 +6498,29 @@ 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 writeCollection(request, ctx) {
+	const parsed = routeBody(request);
+	await ctx.entityManager.ensurePrincipal(ctx.principal);
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const collection = request.params.collection;
+	const result = await ctx.entityManager.writeCollection(entityUrl, collection, {
+		operation: parsed.operation,
+		key: parsed.key,
+		value: parsed.value,
+		principal: {
+			url: ctx.principal.url,
+			kind: ctx.principal.kind,
+			id: ctx.principal.id
+		}
+	});
+	return json(result, { status: parsed.operation === `insert` ? 201 : 200 });
 }
 async function createAttachment(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
@@ -6328,13 +6563,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);
@@ -6384,8 +6619,13 @@ async function spawnEntity(request, ctx) {
 		headers: { "x-write-token": entity.write_token }
 	});
 }
-function getEntity(request) {
-	return json(toPublicEntity(requireExistingEntityRoute(request).entity));
+async function getEntity(request, ctx) {
+	const { entity } = requireExistingEntityRoute(request);
+	const entityType = entity.type ? await ctx.entityManager.registry.getEntityType(entity.type) : null;
+	return json({
+		...toPublicEntity(entity),
+		...entityType?.externally_writable_collections && { externally_writable_collections: entityType.externally_writable_collections }
+	});
 }
 function headEntity() {
 	return status(200);
@@ -6420,6 +6660,16 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown());
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema);
+const externallyWritableCollectionsSchema = Type.Record(Type.String(), Type.Object({
+	type: Type.String(),
+	contract: Type.Optional(Type.String()),
+	operations: Type.Optional(Type.Array(Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]))),
+	principalColumn: Type.Optional(Type.String())
+}, { additionalProperties: false }));
 const slashCommandArgumentSchema = Type.Object({
 	name: Type.String(),
 	type: Type.Union([
@@ -6450,7 +6700,8 @@ const registerEntityTypeBodySchema = Type.Object({
 	slash_commands: Type.Optional(Type.Array(slashCommandSchema)),
 	serve_endpoint: Type.Optional(Type.String()),
 	default_dispatch_policy: Type.Optional(dispatchPolicySchema),
-	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema))
+	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema)),
+	externally_writable_collections: Type.Optional(externallyWritableCollectionsSchema)
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
@@ -6581,7 +6832,20 @@ function parseExpiresAt(value) {
 	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
 	return expiresAt;
 }
+/**
+* The `comments` collection name is reserved for the canonical comments
+* contract: the UI keys its comment affordances on it, so a divergent
+* collection registered under that name (or the contract mounted under
+* another name) would break that assumption silently.
+*/
+function validateExternallyWritableCollections(collections) {
+	for (const [name, config] of Object.entries(collections ?? {})) {
+		if (name === `comments` && config.contract !== COMMENTS_CONTRACT) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The externally-writable collection name "comments" is reserved for the "${COMMENTS_CONTRACT}" contract`, 400);
+		if (config.contract === COMMENTS_CONTRACT && name !== `comments`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The "${COMMENTS_CONTRACT}" contract must be registered under the collection name "comments"`, 400);
+	}
+}
 function normalizeEntityTypeRequest(parsed) {
+	validateExternallyWritableCollections(parsed.externally_writable_collections);
 	const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint);
 	return {
 		name: parsed.name ?? ``,
@@ -6595,7 +6859,8 @@ function normalizeEntityTypeRequest(parsed) {
 			type: `webhook`,
 			url: serveEndpoint
 		}] } : void 0),
-		permission_grants: parsed.permission_grants
+		permission_grants: parsed.permission_grants,
+		externally_writable_collections: parsed.externally_writable_collections
 	};
 }
 function toPublicEntityType(entityType) {
@@ -6605,6 +6870,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`);
@@ -6679,6 +6987,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`);
 }
@@ -7129,6 +7441,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));
@@ -7512,6 +7825,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);
 
@@ -7554,7 +7870,7 @@ const ENTITY_SHAPE_COLUMNS = [
 	`created_at`,
 	`updated_at`
 ];
-function parseElectricOffset(offset) {
+function parseElectricOffset$1(offset) {
 	if (offset === `-1`) return offset;
 	return /^\d+_\d+$/.test(offset) ? offset : null;
 }
@@ -7646,7 +7962,7 @@ var EntityBridge = class {
 		});
 		await this.loadCurrentMembers();
 		if (this.initialShapeHandle && this.initialShapeOffset) {
-			const initialOffset = parseElectricOffset(this.initialShapeOffset);
+			const initialOffset = parseElectricOffset$1(this.initialShapeOffset);
 			if (initialOffset) {
 				this.startLiveStream(initialOffset, this.initialShapeHandle);
 				return;
@@ -8132,6 +8448,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),
@@ -8474,6 +8793,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,
@@ -8573,6 +8901,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) {
@@ -8587,6 +9217,7 @@ var ElectricAgentsTenantRuntime = class {
 	wakeRegistry;
 	scheduler;
 	entityBridgeManager;
+	pgSyncBridgeManager;
 	claimWriteTokens;
 	manager;
 	constructor(options) {
@@ -8611,9 +9242,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));
@@ -9377,7 +10009,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));
@@ -9488,9 +10123,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;
@@ -9513,13 +10148,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;
@@ -9563,12 +10200,15 @@ async function startStandaloneAgentsRuntime(options) {
 		wakeRegistry,
 		scheduler,
 		entityBridgeManager,
+		pgSyncBridgeManager: options.pgSyncBridgeManager,
+		pgSync: options.pgSync,
 		stopWakeRegistryOnShutdown: options.wakeRegistry ? false : true
 	});
 	const startWakeRegistry = options.startWakeRegistry ?? true;
 	const startScheduler = options.startScheduler ?? true;
 	const startTagStreamOutboxDrainer = options.startTagStreamOutboxDrainer ?? true;
 	const startEntityBridgeManager = options.startEntityBridgeManager ?? true;
+	const startPgSyncBridgeManager = options.startPgSyncBridgeManager ?? true;
 	const rehydrateOnStart = options.rehydrateOnStart ?? true;
 	let entityBridgeManagerStarted = false;
 	let tagStreamOutboxDrainerStarted = false;
@@ -9605,6 +10245,10 @@ async function startStandaloneAgentsRuntime(options) {
 			await entityBridgeManager.start();
 			entityBridgeManagerStarted = true;
 		}
+		if (startPgSyncBridgeManager) {
+			serverLog.info(`[agent-server] starting pg-sync bridge manager...`);
+			await runtime.pgSyncBridgeManager.start?.();
+		}
 		if (startTagStreamOutboxDrainer) {
 			serverLog.info(`[agent-server] starting tag stream outbox drainer...`);
 			tagStreamOutboxDrainer.start();
@@ -9632,6 +10276,7 @@ async function startStandaloneAgentsRuntime(options) {
 		manager: runtime.manager,
 		scheduler,
 		entityBridgeManager,
+		pgSyncBridgeManager: runtime.pgSyncBridgeManager,
 		tagStreamOutboxDrainer,
 		stop
 	};
@@ -9749,7 +10394,8 @@ var ElectricAgentsServer = class {
 				pgClient: client,
 				streamClient: this.streamClient,
 				electricUrl: this.options.electricUrl,
-				electricSecret: this.options.electricSecret
+				electricSecret: this.options.electricSecret,
+				pgSync: this.options.pgSync
 			});
 			this.electricAgentsManager = this.standaloneRuntime.manager;
 			this.entityBridgeManager = this.standaloneRuntime.entityBridgeManager;
@@ -9871,6 +10517,7 @@ var ElectricAgentsServer = class {
 			streamClient: this.streamClient,
 			runtime: this.standaloneRuntime.runtime,
 			entityBridgeManager: this.entityBridgeManager,
+			pgSyncBridgeManager: this.standaloneRuntime.runtime.pgSyncBridgeManager,
 			...this.options.eventSources ? { eventSources: this.options.eventSources } : {},
 			...this.options.ensureEventSourceWakeSource ? { ensureEventSourceWakeSource: this.options.ensureEventSourceWakeSource } : {},
 			...this.options.authorizeRequest ? { authorizeRequest: this.options.authorizeRequest } : {},