@electric-ax/agents-server 0.4.19 → 0.4.20

package/drizzle/0015_pg_sync_bridges.sql

@@ -0,0 +1,14 @@
+CREATE TABLE "pg_sync_bridges" (
+	"tenant_id" text DEFAULT 'default' NOT NULL,
+	"source_ref" text NOT NULL,
+	"options" jsonb NOT NULL,
+	"stream_url" text NOT NULL,
+	"shape_handle" text,
+	"shape_offset" text,
+	"initial_snapshot_complete" boolean DEFAULT false NOT NULL,
+	"last_touched_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "pg_sync_bridges_tenant_id_source_ref_pk" PRIMARY KEY("tenant_id","source_ref"),
+	CONSTRAINT "uq_pg_sync_bridges_stream_url" UNIQUE("tenant_id","stream_url")
+);

package/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1780600000000,
       "tag": "0014_entity_type_slash_commands",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1779728400000,
+      "tag": "0015_pg_sync_bridges",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -39,7 +39,7 @@
     "@durable-streams/client": "^0.2.6",
     "@durable-streams/server": "^0.3.7",
     "@durable-streams/state": "^0.3.1",
-    "@electric-sql/client": "^1.5.20",
+    "@electric-sql/client": "^1.5.21",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@opentelemetry/api": "^1.9.1",
     "@sinclair/typebox": "^0.34.48",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.12"
+    "@electric-ax/agents-runtime": "0.3.13"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
@@ -65,9 +65,9 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
-    "@electric-ax/agents": "0.4.16",
-    "@electric-ax/agents-server-conformance-tests": "0.1.11",
-    "@electric-ax/agents-server-ui": "0.4.19"
+    "@electric-ax/agents": "0.4.17",
+    "@electric-ax/agents-server-conformance-tests": "0.1.12",
+    "@electric-ax/agents-server-ui": "0.4.20"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -621,6 +621,34 @@ export const scheduledTasks = pgTable(
   ]
 )
 
+export 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),
+  ]
+)
+
 export const entityBridges = pgTable(
   `entity_bridges`,
   {

package/src/entity-manager.ts

@@ -336,6 +336,14 @@ function cloneRecord<T extends Record<string, unknown>>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T
 }
 
+function withOptionalTxid<T>(
+  entity: T,
+  txid: number | undefined
+): T & { txid?: number } {
+  if (txid === undefined) return entity as T & { txid?: number }
+  return { ...entity, txid }
+}
+
 /**
  * Orchestrates the Electric Agents entity lifecycle: register types, spawn, send, kill.
  *
@@ -2336,7 +2344,7 @@ export class EntityManager {
     entityUrl: string,
     req: SendRequest,
     opts?: { producerId?: string }
-  ): Promise<void> {
+  ): Promise<{ txid: string }> {
     const entity = await this.validateSendRequest(entityUrl, req)
     if (
       this.isForkWorkLockedEntity(entityUrl) &&
@@ -2384,9 +2392,11 @@ export class EntityManager {
       await this.entityBridgeManager?.onEntityChanged(entityUrl)
     }
 
+    const txid = crypto.randomUUID()
     const envelope = entityStateSchema.inbox.insert({
       key,
       value,
+      headers: { txid },
     } as any)
 
     const encoded = this.encodeChangeEvent(envelope as Record<string, unknown>)
@@ -2395,7 +2405,7 @@ export class EntityManager {
         await this.streamClient.appendIdempotent(entity.streams.main, encoded, {
           producerId: opts.producerId,
         })
-        return
+        return { txid }
       }
 
       await this.streamClient.append(entity.streams.main, encoded)
@@ -2407,9 +2417,11 @@ export class EntityManager {
             type: `identity`,
             key: `self`,
             value: identity,
+            headers: { txid },
           })
         )
       }
+      return { txid }
     } catch (err) {
       if (this.isClosedStreamError(err)) {
         throw new ElectricAgentsError(
@@ -2431,7 +2443,7 @@ export class EntityManager {
       mode?: `immediate` | `queued` | `paused` | `steer`
       status?: `pending` | `processed` | `cancelled`
     }
-  ): Promise<void> {
+  ): Promise<{ txid: string }> {
     const entity = await this.registry.getEntity(entityUrl)
     if (!entity) {
       throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404)
@@ -2463,17 +2475,23 @@ export class EntityManager {
       )
     }
 
+    const txid = crypto.randomUUID()
     const envelope = entityStateSchema.inbox.update({
       key,
       value,
+      headers: { txid },
     } as any)
     await this.streamClient.append(
       entity.streams.main,
       this.encodeChangeEvent(envelope as Record<string, unknown>)
     )
+    return { txid }
   }
 
-  async deleteInboxMessage(entityUrl: string, key: string): Promise<void> {
+  async deleteInboxMessage(
+    entityUrl: string,
+    key: string
+  ): Promise<{ txid: string }> {
     const entity = await this.registry.getEntity(entityUrl)
     if (!entity) {
       throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404)
@@ -2486,11 +2504,16 @@ export class EntityManager {
       )
     }
 
-    const envelope = entityStateSchema.inbox.delete({ key } as any)
+    const txid = crypto.randomUUID()
+    const envelope = entityStateSchema.inbox.delete({
+      key,
+      headers: { txid },
+    } as any)
     await this.streamClient.append(
       entity.streams.main,
       this.encodeChangeEvent(envelope as Record<string, unknown>)
     )
+    return { txid }
   }
 
   // ==========================================================================
@@ -2686,21 +2709,12 @@ export class EntityManager {
   async setTag(
     entityUrl: string,
     key: string,
-    req: SetTagRequest,
-    token: string
-  ): Promise<ElectricAgentsEntity> {
+    req: SetTagRequest
+  ): Promise<ElectricAgentsEntity & { txid?: number }> {
     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,
@@ -2731,26 +2745,17 @@ export class EntityManager {
       await this.entityBridgeManager.onEntityChanged(entityUrl)
     }
 
-    return updated
+    return withOptionalTxid(updated, result.txid)
   }
 
   async deleteTag(
     entityUrl: string,
-    key: string,
-    token: string
-  ): Promise<ElectricAgentsEntity> {
+    key: string
+  ): Promise<ElectricAgentsEntity & { txid?: number }> {
     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,
@@ -2773,7 +2778,7 @@ export class EntityManager {
       await this.entityBridgeManager.onEntityChanged(entityUrl)
     }
 
-    return updated
+    return withOptionalTxid(updated, result.txid)
   }
 
   async ensureEntitiesMembershipStream(

package/src/entity-registry.ts

@@ -10,6 +10,7 @@ import {
   entityLineage,
   entityPermissionGrants,
   entityTypes,
+  pgSyncBridges,
   entityTypePermissionGrants,
   runnerRuntimeDiagnostics,
   runners,
@@ -43,7 +44,7 @@ import type {
   EntityTypePermissionGrant,
   PermissionSubjectKind,
 } from './electric-agents-types.js'
-import type { EntityTags } from '@electric-ax/agents-runtime'
+import type { EntityTags, PgSyncOptions } from '@electric-ax/agents-runtime'
 import type { Principal } from './principal.js'
 
 export class EntityAlreadyExistsError extends Error {
@@ -73,6 +74,19 @@ export interface EntityBridgeRow {
   updatedAt: Date
 }
 
+export interface PgSyncBridgeRow {
+  tenantId: string
+  sourceRef: string
+  options: PgSyncOptions
+  streamUrl: string
+  shapeHandle?: string
+  shapeOffset?: string
+  initialSnapshotComplete: boolean
+  lastTouchedAt: Date
+  createdAt: Date
+  updatedAt: Date
+}
+
 export interface TagStreamOutboxRow {
   id: number
   tenantId: string
@@ -623,6 +637,13 @@ export class PostgresRegistry {
     )
   }
 
+  private pgSyncBridgeWhere(sourceRef: string) {
+    return and(
+      eq(pgSyncBridges.tenantId, this.tenantId),
+      eq(pgSyncBridges.sourceRef, sourceRef)
+    )
+  }
+
   async createEntityType(et: ElectricAgentsEntityType): Promise<void> {
     await this.db
       .insert(entityTypes)
@@ -1422,6 +1443,7 @@ export class PostgresRegistry {
     entity: ElectricAgentsEntity | null
     changed: boolean
     op?: `insert` | `update` | `delete`
+    txid?: number
   }> {
     return this.mutateEntityTags(url, (oldTags) => {
       const previous = oldTags[key]
@@ -1440,7 +1462,11 @@ export class PostgresRegistry {
   async removeEntityTag(
     url: string,
     key: string
-  ): Promise<{ entity: ElectricAgentsEntity | null; changed: boolean }> {
+  ): Promise<{
+    entity: ElectricAgentsEntity | null
+    changed: boolean
+    txid?: number
+  }> {
     return this.mutateEntityTags(url, (oldTags) => {
       if (!(key in oldTags)) return null
       const { [key]: _removed, ...remaining } = oldTags
@@ -1465,6 +1491,7 @@ export class PostgresRegistry {
     entity: ElectricAgentsEntity | null
     changed: boolean
     op?: `insert` | `update`
+    txid?: number
   }> {
     return await this.db.transaction(async (tx) => {
       const [row] = await tx
@@ -1485,7 +1512,7 @@ export class PostgresRegistry {
 
       const nextTags = normalizeTags(mutation.nextTags)
       const updatedAt = Date.now()
-      await tx
+      const [updateResult] = await tx
         .update(entities)
         .set({
           tags: nextTags,
@@ -1493,6 +1520,10 @@ export class PostgresRegistry {
           updatedAt,
         })
         .where(this.entityWhere(url))
+        .returning({
+          txid: sql<string>`pg_current_xact_id()::xid::text`,
+        })
+      const txid = updateResult ? parseInt(updateResult.txid) : undefined
 
       await tx.insert(tagStreamOutbox).values({
         tenantId: this.tenantId,
@@ -1513,10 +1544,103 @@ export class PostgresRegistry {
         entity,
         changed: true,
         ...(op === `insert` || op === `update` ? { op } : {}),
+        ...(txid !== undefined ? { txid } : {}),
       }
     })
   }
 
+  async upsertPgSyncBridge(row: {
+    sourceRef: string
+    options: PgSyncOptions
+    streamUrl: string
+  }): Promise<PgSyncBridgeRow> {
+    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: string): Promise<PgSyncBridgeRow | null> {
+    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: string | null = this.tenantId
+  ): Promise<Array<PgSyncBridgeRow>> {
+    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: string): Promise<void> {
+    await this.db
+      .update(pgSyncBridges)
+      .set({ lastTouchedAt: new Date(), updatedAt: new Date() })
+      .where(this.pgSyncBridgeWhere(sourceRef))
+  }
+
+  async updatePgSyncBridgeCursor(
+    sourceRef: string,
+    shapeHandle: string,
+    shapeOffset: string,
+    initialSnapshotComplete?: boolean
+  ): Promise<void> {
+    await this.db
+      .update(pgSyncBridges)
+      .set({
+        shapeHandle,
+        shapeOffset,
+        ...(initialSnapshotComplete !== undefined
+          ? { initialSnapshotComplete }
+          : {}),
+        updatedAt: new Date(),
+      })
+      .where(this.pgSyncBridgeWhere(sourceRef))
+  }
+
+  async clearPgSyncBridgeCursor(sourceRef: string): Promise<void> {
+    await this.db
+      .update(pgSyncBridges)
+      .set({
+        shapeHandle: null,
+        shapeOffset: null,
+        initialSnapshotComplete: false,
+        updatedAt: new Date(),
+      })
+      .where(this.pgSyncBridgeWhere(sourceRef))
+  }
+
   async upsertEntityBridge(row: {
     sourceRef: string
     tags: EntityTags
@@ -1911,6 +2035,23 @@ export class PostgresRegistry {
     }
   }
 
+  private rowToPgSyncBridge(
+    row: typeof pgSyncBridges.$inferSelect
+  ): PgSyncBridgeRow {
+    return {
+      tenantId: row.tenantId,
+      sourceRef: row.sourceRef,
+      options: row.options as PgSyncOptions,
+      streamUrl: row.streamUrl,
+      shapeHandle: row.shapeHandle ?? undefined,
+      shapeOffset: row.shapeOffset ?? undefined,
+      initialSnapshotComplete: row.initialSnapshotComplete,
+      lastTouchedAt: row.lastTouchedAt,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    }
+  }
+
   private rowToEntityBridge(
     row: typeof entityBridges.$inferSelect
   ): EntityBridgeRow {

package/src/manifest-side-effects.ts

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