@electric-ax/agents-server 0.4.19 → 0.5.0

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/0016_entity_type_externally_writable_collections.sql

@@ -0,0 +1 @@
+ALTER TABLE "entity_types" ADD COLUMN "externally_writable_collections" jsonb;

package/drizzle/meta/_journal.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.19",
+  "version": "0.5.0",
   "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.4.0"
   },
   "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.18",
+    "@electric-ax/agents-server-conformance-tests": "0.1.12",
+    "@electric-ax/agents-server-ui": "0.5.0"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -14,6 +14,7 @@ import {
   timestamp,
   unique,
 } from 'drizzle-orm/pg-core'
+import type { ExternallyWritableCollectionConfig } from '../electric-agents-types.js'
 
 export const entityTypes = pgTable(
   `entity_types`,
@@ -24,6 +25,9 @@ export const entityTypes = pgTable(
     creationSchema: jsonb(`creation_schema`),
     inboxSchemas: jsonb(`inbox_schemas`),
     stateSchemas: jsonb(`state_schemas`),
+    externallyWritableCollections: jsonb(
+      `externally_writable_collections`
+    ).$type<Record<string, ExternallyWritableCollectionConfig>>(),
     slashCommands: jsonb(`slash_commands`),
     serveEndpoint: text(`serve_endpoint`),
     defaultDispatchPolicy: jsonb(`default_dispatch_policy`),
@@ -621,6 +625,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/electric-agents-types.ts

@@ -494,12 +494,31 @@ export function toPublicEntity(
   }
 }
 
+/** Per-collection config making an entity-state collection externally writable via the router. */
+export interface ExternallyWritableCollectionConfig {
+  /** Durable-stream event type for this collection, e.g. `state:comments`. */
+  type: string
+  /** Well-known contract this collection implements, e.g. `comments/v1`. */
+  contract?: string
+  /**
+   * Allowlist of external write operations. When set, the router rejects any
+   * operation not listed (403). When unset, only `insert` is permitted — the
+   * safe default, since open update/delete lets a client overwrite or remove
+   * another principal's rows by key.
+   */
+  operations?: Array<`insert` | `update` | `delete`>
+}
+
 export interface ElectricAgentsEntityType {
   name: string
   description: string
   creation_schema?: Record<string, unknown>
   inbox_schemas?: Record<string, Record<string, unknown>>
   state_schemas?: Record<string, Record<string, unknown>>
+  externally_writable_collections?: Record<
+    string,
+    ExternallyWritableCollectionConfig
+  >
   slash_commands?: Array<SlashCommandDefinition>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy
@@ -514,6 +533,10 @@ export interface RegisterEntityTypeRequest {
   creation_schema?: Record<string, unknown>
   inbox_schemas?: Record<string, Record<string, unknown>>
   state_schemas?: Record<string, Record<string, unknown>>
+  externally_writable_collections?: Record<
+    string,
+    ExternallyWritableCollectionConfig
+  >
   slash_commands?: Array<SlashCommandDefinition>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy

package/src/entity-manager.ts

@@ -71,6 +71,7 @@ import type {
   SignalRequest,
   SignalResponse,
   TypedSpawnRequest,
+  ExternallyWritableCollectionConfig,
 } from './electric-agents-types.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { Principal } from './principal.js'
@@ -131,6 +132,23 @@ export interface CreateAttachmentRequest {
   meta?: Record<string, unknown>
 }
 
+export interface WriteCollectionPrincipal {
+  url: string
+  kind: string
+  id: string
+}
+
+export interface WriteCollectionRequest {
+  operation: `insert` | `update` | `delete`
+  key?: string
+  value?: Record<string, unknown>
+  principal: WriteCollectionPrincipal
+}
+
+export interface WriteCollectionResult {
+  key: string
+}
+
 export interface ReadAttachmentResult {
   attachment: ManifestAttachmentEntry
   bytes: Uint8Array
@@ -336,6 +354,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.
  *
@@ -480,6 +506,7 @@ export class EntityManager {
       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,
@@ -2336,7 +2363,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 +2411,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 +2424,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 +2436,11 @@ export class EntityManager {
             type: `identity`,
             key: `self`,
             value: identity,
+            headers: { txid },
           })
         )
       }
+      return { txid }
     } catch (err) {
       if (this.isClosedStreamError(err)) {
         throw new ElectricAgentsError(
@@ -2422,6 +2453,106 @@ export class EntityManager {
     }
   }
 
+  async writeCollection(
+    entityUrl: string,
+    collection: string,
+    req: WriteCollectionRequest
+  ): Promise<WriteCollectionResult> {
+    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 === undefined || 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: Record<string, unknown> = {
+      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: string,
     key: string,
@@ -2431,7 +2562,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 +2594,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 +2623,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 +2828,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 +2864,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 +2897,7 @@ export class EntityManager {
       await this.entityBridgeManager.onEntityChanged(entityUrl)
     }
 
-    return updated
+    return withOptionalTxid(updated, result.txid)
   }
 
   async ensureEntitiesMembershipStream(
@@ -3871,11 +3995,16 @@ export class EntityManager {
   private async getEffectiveSchemas(entity: ElectricAgentsEntity): Promise<{
     inboxSchemas?: Record<string, Record<string, unknown>>
     stateSchemas?: Record<string, Record<string, unknown>>
+    externallyWritableCollections?: Record<
+      string,
+      ExternallyWritableCollectionConfig
+    >
   }> {
     if (!entity.type) {
       return {
         inboxSchemas: entity.inbox_schemas,
         stateSchemas: entity.state_schemas,
+        externallyWritableCollections: undefined,
       }
     }
 
@@ -3888,6 +4017,8 @@ export class EntityManager {
       stateSchemas: latestType?.state_schemas
         ? { ...(entity.state_schemas ?? {}), ...latestType.state_schemas }
         : entity.state_schemas,
+      externallyWritableCollections:
+        latestType?.externally_writable_collections,
     }
   }