@electric-ax/agents-server 0.4.20 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.20",
+  "version": "0.5.1",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.13"
+    "@electric-ax/agents-runtime": "0.4.1"
   },
   "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.17",
-    "@electric-ax/agents-server-conformance-tests": "0.1.12",
-    "@electric-ax/agents-server-ui": "0.4.20"
+    "@electric-ax/agents-server-ui": "0.5.1",
+    "@electric-ax/agents": "0.4.19",
+    "@electric-ax/agents-server-conformance-tests": "0.1.12"
   },
   "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`),

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

@@ -7,7 +7,7 @@ import {
   getCronStreamPath,
   getSharedStateStreamPath,
   getNextCronFireAt,
-  eventSourceSubscriptionManifestKey,
+  webhookSourceSubscriptionManifestKey,
   manifestChildKey,
   manifestSharedStateKey,
   manifestSourceKey,
@@ -56,7 +56,7 @@ import type { queueAsPromised } from 'fastq'
 import type { SchedulerClient } from './scheduler.js'
 import type { WakeEvalResult, WakeRegistry } from './wake-registry.js'
 import type { WakeMessage } from '@electric-ax/agents-runtime'
-import type { EventSourceSubscription } from '@electric-ax/agents-runtime'
+import type { WebhookSourceSubscription } from '@electric-ax/agents-runtime'
 import type { PostgresRegistry } from './entity-registry.js'
 import type { SchemaValidator } from './electric-agents/schema-validator.js'
 import type { StreamClient } from './stream-client.js'
@@ -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
@@ -488,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,
@@ -2434,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,
@@ -3023,13 +3142,13 @@ export class EntityManager {
     return { txid }
   }
 
-  async upsertEventSourceSubscription(
+  async upsertWebhookSourceSubscription(
     entityUrl: string,
     req: {
-      subscription: EventSourceSubscription
+      subscription: WebhookSourceSubscription
       manifest: Record<string, unknown>
     }
-  ): Promise<{ txid: string; subscription: EventSourceSubscription }> {
+  ): Promise<{ txid: string; subscription: WebhookSourceSubscription }> {
     const manifestKey = req.subscription.manifestKey
     const txid = randomUUID()
     await this.writeManifestEntry(
@@ -3065,11 +3184,35 @@ export class EntityManager {
     return { txid, subscription: req.subscription }
   }
 
-  async deleteEventSourceSubscription(
+  async deleteWebhookSourceSubscription(
     entityUrl: string,
     req: { id: string }
   ): Promise<{ txid: string }> {
-    const manifestKey = eventSourceSubscriptionManifestKey(req.id)
+    const manifestKey = webhookSourceSubscriptionManifestKey(req.id)
+    const txid = randomUUID()
+    await this.writeManifestEntry(entityUrl, manifestKey, `delete`, undefined, {
+      txid,
+    })
+
+    await this.wakeRegistry.unregisterByManifestKey(
+      entityUrl,
+      manifestKey,
+      this.tenantId
+    )
+
+    return { txid }
+  }
+
+  /**
+   * Stop this entity observing a pg-sync source: drop its manifest entry and
+   * the wake it anchors. The shared pg-sync bridge (keyed by sourceRef, not by
+   * subscriber) is intentionally left running for any other observers.
+   */
+  async deletePgSyncObservation(
+    entityUrl: string,
+    req: { sourceRef: string }
+  ): Promise<{ txid: string }> {
+    const manifestKey = `source:pgSync:${req.sourceRef}`
     const txid = randomUUID()
     await this.writeManifestEntry(entityUrl, manifestKey, `delete`, undefined, {
       txid,
@@ -3876,11 +4019,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,
       }
     }
 
@@ -3893,6 +4041,8 @@ export class EntityManager {
       stateSchemas: latestType?.state_schemas
         ? { ...(entity.state_schemas ?? {}), ...latestType.state_schemas }
         : entity.state_schemas,
+      externallyWritableCollections:
+        latestType?.externally_writable_collections,
     }
   }
 

package/src/entity-registry.ts

@@ -43,6 +43,7 @@ import type {
   EntityTypePermission,
   EntityTypePermissionGrant,
   PermissionSubjectKind,
+  ExternallyWritableCollectionConfig,
 } from './electric-agents-types.js'
 import type { EntityTags, PgSyncOptions } from '@electric-ax/agents-runtime'
 import type { Principal } from './principal.js'
@@ -654,6 +655,8 @@ export class PostgresRegistry {
         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,
@@ -668,6 +671,8 @@ export class PostgresRegistry {
           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,
@@ -691,6 +696,8 @@ export class PostgresRegistry {
         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,
@@ -733,6 +740,8 @@ export class PostgresRegistry {
         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,
@@ -1566,10 +1575,16 @@ export class PostgresRegistry {
       })
       .onConflictDoUpdate({
         target: [pgSyncBridges.tenantId, pgSyncBridges.sourceRef],
+        // A conflict means the sourceRef matched, i.e. the shape-identity
+        // options are identical, so the persisted cursor and bootstrap state
+        // are still valid. Re-registration is the common path now that the
+        // sourceRef ignores per-request metadata; resetting
+        // initialSnapshotComplete here would make a later restart resume from
+        // the saved cursor while re-skipping changes until up-to-date, dropping
+        // real changes that arrived during downtime.
         set: {
           options: row.options,
           streamUrl: row.streamUrl,
-          initialSnapshotComplete: false,
           lastTouchedAt: new Date(),
           updatedAt: new Date(),
         },
@@ -1641,6 +1656,10 @@ export class PostgresRegistry {
       .where(this.pgSyncBridgeWhere(sourceRef))
   }
 
+  async deletePgSyncBridge(sourceRef: string): Promise<void> {
+    await this.db.delete(pgSyncBridges).where(this.pgSyncBridgeWhere(sourceRef))
+  }
+
   async upsertEntityBridge(row: {
     sourceRef: string
     tags: EntityTags
@@ -1957,6 +1976,11 @@ export class PostgresRegistry {
       state_schemas: row.stateSchemas as
         | Record<string, Record<string, unknown>>
         | undefined,
+      externally_writable_collections:
+        (row.externallyWritableCollections as Record<
+          string,
+          ExternallyWritableCollectionConfig
+        > | null) ?? undefined,
       slash_commands:
         (row.slashCommands as ElectricAgentsEntityType[`slash_commands`]) ??
         undefined,

package/src/index.ts

@@ -65,17 +65,17 @@ export type {
   AuthorizeRequest,
 } from './electric-agents-types.js'
 export type {
-  EventSourceBucket,
-  EventSourceContract,
-  EventSourceFilter,
-  EventSourceSubscription,
-  EventSourceSubscriptionInput,
+  WebhookSourceBucket,
+  WebhookSourceContract,
+  WebhookSourceFilter,
+  WebhookSourceSubscription,
+  WebhookSourceSubscriptionInput,
   SubscriptionLifetime,
 } from '@electric-ax/agents-runtime'
 export type { Principal, PrincipalKind } from './principal.js'
 export { globalRouter } from './routing/global-router.js'
 export type { GlobalRoutes } from './routing/global-router.js'
-export type { EventSourceCatalog, TenantContext } from './routing/context.js'
+export type { WebhookSourceCatalog, TenantContext } from './routing/context.js'
 export {
   streamRootDurableStreamsRoutingAdapter,
   pathPrefixedSingleTenantDurableStreamsRoutingAdapter,

package/src/manifest-side-effects.ts

@@ -10,10 +10,6 @@ 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 {
@@ -62,8 +58,8 @@ export function extractManifestSourceUrl(
     }
 
     if (manifest.sourceType === `pgSync`) {
-      return typeof manifest.sourceRef === `string`
-        ? getPgSyncManifestStreamPath(manifest.sourceRef)
+      return typeof config?.streamUrl === `string`
+        ? config.streamUrl
         : undefined
     }