@electric-ax/agents-server 0.4.19 → 0.5.0

package/src/routing/entities-router.ts

@@ -39,6 +39,7 @@ import type {
   ElectricAgentsEntity,
   ElectricAgentsEntityType,
   EntityPermission,
+  PublicElectricAgentsEntity,
   SendRequest,
 } from '../electric-agents-types.js'
 import type { JsonRouteRequest } from './schema.js'
@@ -148,6 +149,19 @@ const spawnBodySchema = Type.Object({
   ),
 })
 
+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()),
@@ -327,6 +341,7 @@ const eventSourceSubscriptionBodySchema = Type.Object({
 })
 
 type SpawnBody = Static<typeof spawnBodySchema>
+type WriteCollectionBody = Static<typeof writeCollectionBodySchema>
 type SendBody = Static<typeof sendBodySchema>
 type InboxMessageBody = Static<typeof inboxMessageBodySchema>
 type ForkBody = Static<typeof forkBodySchema>
@@ -407,6 +422,13 @@ entitiesRouter.post(
   withEntityPermission(`write`),
   sendEntity
 )
+entitiesRouter.post(
+  `/:type/:instanceId/collections/:collection`,
+  withExistingEntity,
+  withSchema(writeCollectionBodySchema),
+  withEntityPermission(`write`),
+  writeCollection
+)
 entitiesRouter.post(
   `/:type/:instanceId/attachments`,
   withExistingEntity,
@@ -658,7 +680,12 @@ async function parseAttachmentForm(
 }
 
 function contentDisposition(filename: string): string {
-  const fallback = filename.replace(/["\\\r\n]/g, `_`)
+  // Header values are converted to WebIDL ByteString by undici, so every
+  // character in the raw header value must fit in a single byte. Keep the
+  // RFC 5987 filename* parameter for the full UTF-8 filename, but make the
+  // legacy filename fallback ASCII-only to avoid throwing on names containing
+  // e.g. narrow no-break spaces or emoji.
+  const fallback = filename.replace(/[^\x20-\x7e]|["\\]/g, `_`)
   return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`
 }
 
@@ -1083,6 +1110,16 @@ async function deleteEventSourceSubscription(
   return json(result)
 }
 
+function tagResponseBody(
+  entity: ElectricAgentsEntity & { txid?: number }
+): PublicElectricAgentsEntity & { txid?: number } {
+  const publicEntity = toPublicEntity(entity)
+  if (entity.txid !== undefined) {
+    return { ...publicEntity, txid: entity.txid }
+  }
+  return publicEntity
+}
+
 async function setTag(
   request: AgentsRouteRequest,
   ctx: TenantContext
@@ -1095,14 +1132,12 @@ async function setTag(
 
   const parsed = routeBody<SetTagBody>(request)
   const { entityUrl } = requireExistingEntityRoute(request)
-  const token = writeTokenFromRequest(request)
   const updated = await ctx.entityManager.setTag(
     entityUrl,
     decodeURIComponent(request.params.tagKey),
-    { value: parsed.value },
-    token
+    { value: parsed.value }
   )
-  return json(toPublicEntity(updated))
+  return json(tagResponseBody(updated))
 }
 
 async function deleteTag(
@@ -1116,13 +1151,11 @@ async function deleteTag(
   if (principalMutationError) return principalMutationError
 
   const { entityUrl } = requireExistingEntityRoute(request)
-  const token = writeTokenFromRequest(request)
   const updated = await ctx.entityManager.deleteTag(
     entityUrl,
-    decodeURIComponent(request.params.tagKey),
-    token
+    decodeURIComponent(request.params.tagKey)
   )
-  return json(toPublicEntity(updated))
+  return json(tagResponseBody(updated))
 }
 
 async function forkEntity(
@@ -1289,11 +1322,36 @@ async function sendEntity(
       sendReq,
       new Date(Date.now() + parsed.afterMs)
     )
-  } else {
-    await ctx.entityManager.send(entityUrl, sendReq)
+    return status(204)
   }
 
-  return status(204)
+  const result = await ctx.entityManager.send(entityUrl, sendReq)
+  return json(result)
+}
+
+async function writeCollection(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<WriteCollectionBody>(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(
@@ -1368,12 +1426,12 @@ async function updateInboxMessage(
 ): Promise<Response> {
   const parsed = routeBody<InboxMessageBody>(request)
   const { entityUrl } = requireExistingEntityRoute(request)
-  await ctx.entityManager.updateInboxMessage(
+  const result = await ctx.entityManager.updateInboxMessage(
     entityUrl,
     decodeURIComponent(request.params.messageKey),
     parsed
   )
-  return status(204)
+  return json(result)
 }
 
 async function deleteInboxMessage(
@@ -1381,11 +1439,11 @@ async function deleteInboxMessage(
   ctx: TenantContext
 ): Promise<Response> {
   const { entityUrl } = requireExistingEntityRoute(request)
-  await ctx.entityManager.deleteInboxMessage(
+  const result = await ctx.entityManager.deleteInboxMessage(
     entityUrl,
     decodeURIComponent(request.params.messageKey)
   )
-  return status(204)
+  return json(result)
 }
 
 async function spawnEntity(
@@ -1461,8 +1519,21 @@ async function spawnEntity(
   )
 }
 
-function getEntity(request: AgentsRouteRequest): Response {
-  return json(toPublicEntity(requireExistingEntityRoute(request).entity))
+async function getEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  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(): Response {

package/src/routing/entity-types-router.ts

@@ -4,6 +4,7 @@
 
 import { Type, type Static } from '@sinclair/typebox'
 import { Router, json, status } from 'itty-router'
+import { COMMENTS_CONTRACT } from '@electric-ax/agents-runtime'
 import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
 import { ElectricAgentsError } from '../entity-manager.js'
 import {
@@ -45,6 +46,29 @@ type PublicEntityTypeResponse = ElectricAgentsEntityType & {
 
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown())
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema)
+// `principalColumn` is accepted and ignored: older runtimes still send it
+// (the column is fixed to `_principal` now), and rejecting it would break
+// registration during version skew.
+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(),
@@ -93,6 +117,9 @@ const registerEntityTypeBodySchema = Type.Object(
     permission_grants: Type.Optional(
       Type.Array(typePermissionGrantInputSchema)
     ),
+    externally_writable_collections: Type.Optional(
+      externallyWritableCollectionsSchema
+    ),
   },
   { additionalProperties: false }
 )
@@ -445,9 +472,37 @@ function parseExpiresAt(value: string | undefined): Date | undefined {
   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: RegisterEntityTypeRequest[`externally_writable_collections`]
+): void {
+  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: RegisterEntityTypeBody | RegisterEntityTypeRequest
 ): RegisterEntityTypeRequest {
+  validateExternallyWritableCollections(parsed.externally_writable_collections)
   const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint)
   return {
     name: parsed.name ?? ``,
@@ -465,6 +520,7 @@ function normalizeEntityTypeRequest(
           } as RegisterEntityTypeRequest[`default_dispatch_policy`])
         : undefined),
     permission_grants: parsed.permission_grants,
+    externally_writable_collections: parsed.externally_writable_collections,
   }
 }
 

package/src/routing/global-router.ts

@@ -29,5 +29,8 @@ export const globalRouter: GlobalRoutes = AutoRouter<
 })
 
 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)

package/src/routing/hooks.ts

@@ -1,6 +1,7 @@
 import { SpanKind, SpanStatusCode } from '@opentelemetry/api'
 import { apiError } from '../electric-agents-http.js'
 import { ElectricAgentsError } from '../entity-manager.js'
+import { ElectricProxyError } from '../utils/server-utils.js'
 import { ELECTRIC_PRINCIPAL_HEADER } from '../principal.js'
 import { ATTR, extractTraceContext, tracer } from '../tracing.js'
 import { serverLog } from '../utils/log.js'
@@ -112,6 +113,12 @@ export function errorMapper(err: unknown, req: IRequest): Response {
   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`)
 }

package/src/routing/internal-router.ts

@@ -30,6 +30,7 @@ import { resolveDurableStreamsRoutingAdapter } from './durable-streams-routing-a
 import { electricProxyRouter } from './electric-proxy-router.js'
 import { entitiesRouter } from './entities-router.js'
 import { entityTypesRouter } from './entity-types-router.js'
+import { pgSyncRouter } from './pg-sync-router.js'
 import { getRequestSpan } from './hooks.js'
 import { observationsRouter } from './observations-router.js'
 import { runnersRouter } from './runners-router.js'
@@ -135,6 +136,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))

package/src/routing/pg-sync-router.ts

@@ -0,0 +1,113 @@
+/**
+ * HTTP routes for pg-sync observation source registration.
+ */
+
+import type {
+  PgSyncOptions,
+  PgSyncRequestMetadata,
+} from '@electric-ax/agents-runtime'
+import { Type, type Static } from '@sinclair/typebox'
+import { Router, json } from 'itty-router'
+import { apiError } from '../electric-agents-http.js'
+import { ErrCodeInvalidRequest } from '../electric-agents-types.js'
+import { routeBody, withSchema } from './schema.js'
+import type { JsonRouteRequest } from './schema.js'
+import type { RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+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),
+})
+
+type PgSyncRegisterBody = Static<typeof pgSyncRegisterBodySchema>
+
+export type PgSyncRoutes = RouterType<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>
+
+export const pgSyncRouter: PgSyncRoutes = Router<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>({
+  base: `/_electric/pg-sync`,
+})
+
+pgSyncRouter.post(
+  `/register`,
+  withSchema(pgSyncRegisterBodySchema),
+  registerPgSync
+)
+
+async function registerPgSync(
+  request: JsonRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { options, metadata } = routeBody<PgSyncRegisterBody>(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: PgSyncRequestMetadata = {
+      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 as PgSyncOptions,
+      requestMetadata
+    )
+
+    return json(result)
+  } catch (error) {
+    return apiError(
+      500,
+      ErrCodeInvalidRequest,
+      `pgSync registration failed: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+}

package/src/runtime.ts

@@ -14,7 +14,12 @@ import { isPermanentElectricAgentsError } from './scheduler.js'
 import { StreamClient } from './stream-client.js'
 import { DEFAULT_TENANT_ID } from './tenant.js'
 import type { DrizzleDB } from './db/index.js'
+import { PgSyncBridgeManager } from './pg-sync-bridge-manager.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
+import type {
+  PgSyncBridgeCoordinator,
+  PgSyncBridgeManagerOptions,
+} from './pg-sync-bridge-manager.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 import type {
   CronTickPayload,
@@ -40,6 +45,8 @@ export interface ElectricAgentsTenantRuntimeOptions {
   wakeRegistry: WakeRegistry
   scheduler: SchedulerClient
   entityBridgeManager: EntityBridgeCoordinator
+  pgSyncBridgeManager?: PgSyncBridgeCoordinator
+  pgSync?: PgSyncBridgeManagerOptions
   claimWriteTokens?: ClaimWriteTokenStore
   stopWakeRegistryOnShutdown?: boolean
 }
@@ -53,6 +60,7 @@ export class ElectricAgentsTenantRuntime {
   readonly wakeRegistry: WakeRegistry
   readonly scheduler: SchedulerClient
   readonly entityBridgeManager: EntityBridgeCoordinator
+  readonly pgSyncBridgeManager: PgSyncBridgeCoordinator
   readonly claimWriteTokens: ClaimWriteTokenStore
   readonly manager: EntityManager
 
@@ -92,10 +100,21 @@ export class ElectricAgentsTenantRuntime {
         ),
       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(): Promise<void> {
-    await this.manager.shutdown()
+    await Promise.all([
+      this.manager.shutdown(),
+      this.pgSyncBridgeManager.stop(),
+    ])
   }
 
   async rehydrateCronSchedules(): Promise<void> {

package/src/scheduler.ts

@@ -228,6 +228,14 @@ export function isPermanentElectricAgentsError(err: unknown): boolean {
   )
 }
 
+function cronTaskStreamPath(
+  payload: DelayedSendPayload | CronTickPayload
+): string | null {
+  return typeof (payload as { streamPath?: unknown }).streamPath === `string`
+    ? (payload as { streamPath: string }).streamPath
+    : null
+}
+
 function normalizeTask(row: ScheduledTaskRow): {
   id: number
   tenantId: string
@@ -680,6 +688,24 @@ export class Scheduler implements SchedulerClient {
         task.fireAt
       )
 
+      const streamPath = cronTaskStreamPath(task.payload)
+      const subscriberRows = streamPath
+        ? await sql<Array<{ exists: number }>>`
+            select 1 as exists
+            from wake_registrations
+            where tenant_id = ${tenantId}
+              and source_url = ${streamPath}
+            limit 1
+          `
+        : []
+
+      // Cron streams are virtual shared sources. If no wake registrations
+      // still point at this cron stream (e.g. the owning manifest schedule was
+      // deleted), stop the chain here instead of keeping a forever-global tick
+      // alive. Rehydration/getOrCreateCronStream will seed a fresh tick when a
+      // subscription is recreated.
+      if (subscriberRows.length === 0) return
+
       await sql`
         insert into scheduled_tasks (
           tenant_id,

package/src/server.ts

@@ -36,6 +36,7 @@ import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { DurableStreamsRoutingAdapter } from './routing/durable-streams-routing-adapter.js'
 import type { OssServerContext } from './routing/oss-server-router.js'
 import type { EventSourceCatalog } from './routing/context.js'
+import type { PgSyncBridgeManagerOptions } from './pg-sync-bridge-manager.js'
 import type { StartedStandaloneAgentsRuntime } from './standalone-runtime.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 import type {
@@ -72,6 +73,7 @@ export interface ElectricAgentsServerOptions {
   allowDevPrincipalFallback?: boolean
   eventSources?: EventSourceCatalog
   ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
+  pgSync?: PgSyncBridgeManagerOptions
   /**
    * Disabled by default. When set to a positive interval, periodically
    * recovers expired dispatch claims and stale outstanding wakes.
@@ -242,6 +244,7 @@ export class ElectricAgentsServer {
         streamClient: this.streamClient,
         electricUrl: this.options.electricUrl,
         electricSecret: this.options.electricSecret,
+        pgSync: this.options.pgSync,
       })
       this.electricAgentsManager = this.standaloneRuntime.manager
       this.entityBridgeManager = this.standaloneRuntime.entityBridgeManager
@@ -446,6 +449,7 @@ export class ElectricAgentsServer {
       streamClient: this.streamClient,
       runtime: this.standaloneRuntime.runtime,
       entityBridgeManager: this.entityBridgeManager,
+      pgSyncBridgeManager: this.standaloneRuntime.runtime.pgSyncBridgeManager,
       ...(this.options.eventSources
         ? { eventSources: this.options.eventSources }
         : {}),

package/src/standalone-runtime.ts

@@ -11,6 +11,10 @@ import { WakeRegistry } from './wake-registry.js'
 import type { DrizzleDB, PgClient } from './db/index.js'
 import type { EntityManager } from './entity-manager.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
+import type {
+  PgSyncBridgeCoordinator,
+  PgSyncBridgeManagerOptions,
+} from './pg-sync-bridge-manager.js'
 import type { CronTickPayload, DelayedSendPayload } from './scheduler.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 
@@ -30,8 +34,11 @@ export interface StandaloneAgentsRuntimeOptions {
   startScheduler?: boolean
   startTagStreamOutboxDrainer?: boolean
   startEntityBridgeManager?: boolean
+  startPgSyncBridgeManager?: boolean
   rehydrateOnStart?: boolean
   entityBridgeManager?: EntityBridgeCoordinator
+  pgSyncBridgeManager?: PgSyncBridgeCoordinator
+  pgSync?: PgSyncBridgeManagerOptions
 }
 
 export interface StartedStandaloneAgentsRuntime {
@@ -46,6 +53,7 @@ export interface StartedStandaloneAgentsRuntime {
   manager: EntityManager
   scheduler: Scheduler
   entityBridgeManager: EntityBridgeCoordinator
+  pgSyncBridgeManager: PgSyncBridgeCoordinator
   tagStreamOutboxDrainer: TagStreamOutboxDrainer
   stop: () => Promise<void>
 }
@@ -104,6 +112,8 @@ export async function startStandaloneAgentsRuntime(
     wakeRegistry,
     scheduler,
     entityBridgeManager,
+    pgSyncBridgeManager: options.pgSyncBridgeManager,
+    pgSync: options.pgSync,
     stopWakeRegistryOnShutdown: options.wakeRegistry ? false : true,
   })
 
@@ -112,6 +122,7 @@ export async function startStandaloneAgentsRuntime(
   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
@@ -153,6 +164,10 @@ export async function startStandaloneAgentsRuntime(
       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()
@@ -181,6 +196,7 @@ export async function startStandaloneAgentsRuntime(
     manager: runtime.manager,
     scheduler,
     entityBridgeManager,
+    pgSyncBridgeManager: runtime.pgSyncBridgeManager,
     tagStreamOutboxDrainer,
     stop,
   }