@electric-ax/agents-server 0.4.20 → 0.5.1

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/internal-router.ts

@@ -38,7 +38,7 @@ import { routeBody, validateOptionalJsonBody, withSchema } from './schema.js'
 import { withLeadingSlash } from './tenant-stream-paths.js'
 import type { IRequest, RouterType } from 'itty-router'
 import type {
-  EventSourceContract,
+  WebhookSourceContract,
   WebhookSignatureVerifierConfig,
 } from '@electric-ax/agents-runtime'
 import type { TenantContext } from './context.js'
@@ -121,7 +121,7 @@ export const internalRouter: InternalRoutes = Router<
 })
 
 internalRouter.get(`/health`, () => json({ status: `ok` }))
-internalRouter.get(`/event-sources`, listEventSources)
+internalRouter.get(`/webhook-sources`, listWebhookSources)
 internalRouter.post(
   `/wake`,
   withSchema(wakeRegistrationBodySchema),
@@ -366,17 +366,19 @@ async function registerWake(
   return status(204)
 }
 
-async function listEventSources(
+async function listWebhookSources(
   _request: IRequest,
   ctx: TenantContext
 ): Promise<Response> {
-  const eventSources = ctx.eventSources
-    ? await ctx.eventSources.listEventSources()
+  const webhookSources = ctx.webhookSources
+    ? await ctx.webhookSources.listWebhookSources()
     : []
-  return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) })
+  return json({
+    webhookSources: webhookSources.filter(isAgentVisibleWebhookSource),
+  })
 }
 
-function isAgentVisibleEventSource(source: EventSourceContract): boolean {
+function isAgentVisibleWebhookSource(source: WebhookSourceContract): boolean {
   return source.agentVisible === true && source.status === `active`
 }
 

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

@@ -8,6 +8,8 @@ import type {
 } from '@electric-ax/agents-runtime'
 import { Type, type Static } from '@sinclair/typebox'
 import { Router, json } from 'itty-router'
+import { PgSyncSourceValidationError } from '../pg-sync-bridge-manager.js'
+import { serverLog } from '../utils/log.js'
 import { apiError } from '../electric-agents-http.js'
 import { ErrCodeInvalidRequest } from '../electric-agents-types.js'
 import { routeBody, withSchema } from './schema.js'
@@ -16,7 +18,7 @@ import type { RouterType } from 'itty-router'
 import type { TenantContext } from './context.js'
 
 const pgSyncOptionsSchema = Type.Object({
-  url: Type.Optional(Type.String()),
+  url: Type.String(),
   table: Type.String(),
   columns: Type.Optional(Type.Array(Type.String())),
   where: Type.Optional(Type.String()),
@@ -72,6 +74,10 @@ async function registerPgSync(
 ): Promise<Response> {
   const { options, metadata } = routeBody<PgSyncRegisterBody>(request)
 
+  if (options.url.trim() === ``) {
+    return apiError(400, ErrCodeInvalidRequest, `pgSync url must be non-empty`)
+  }
+
   if (options.table.trim() === ``) {
     return apiError(
       400,
@@ -104,6 +110,13 @@ async function registerPgSync(
 
     return json(result)
   } catch (error) {
+    if (error instanceof PgSyncSourceValidationError) {
+      return apiError(400, ErrCodeInvalidRequest, error.message)
+    }
+    serverLog.error(
+      `[pg-sync] registration failed for table "${options.table}":`,
+      error
+    )
     return apiError(
       500,
       ErrCodeInvalidRequest,

package/src/server.ts

@@ -35,7 +35,7 @@ import type { Principal } from './principal.js'
 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 { WebhookSourceCatalog } 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'
@@ -71,8 +71,8 @@ export interface ElectricAgentsServerOptions {
   ) => Promise<Principal | null> | Principal | null
   authorizeRequest?: AuthorizeRequest
   allowDevPrincipalFallback?: boolean
-  eventSources?: EventSourceCatalog
-  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
+  webhookSources?: WebhookSourceCatalog
+  ensureWebhookSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
   pgSync?: PgSyncBridgeManagerOptions
   /**
    * Disabled by default. When set to a positive interval, periodically
@@ -450,13 +450,13 @@ export class ElectricAgentsServer {
       runtime: this.standaloneRuntime.runtime,
       entityBridgeManager: this.entityBridgeManager,
       pgSyncBridgeManager: this.standaloneRuntime.runtime.pgSyncBridgeManager,
-      ...(this.options.eventSources
-        ? { eventSources: this.options.eventSources }
+      ...(this.options.webhookSources
+        ? { webhookSources: this.options.webhookSources }
         : {}),
-      ...(this.options.ensureEventSourceWakeSource
+      ...(this.options.ensureWebhookSourceWakeSource
         ? {
-            ensureEventSourceWakeSource:
-              this.options.ensureEventSourceWakeSource,
+            ensureWebhookSourceWakeSource:
+              this.options.ensureWebhookSourceWakeSource,
           }
         : {}),
       ...(this.options.authorizeRequest

package/src/wake-registry.ts

@@ -967,6 +967,8 @@ export class WakeRegistry {
     }
     if (value && `oldValue` in value) {
       change.oldValue = value.oldValue
+    } else if (value && `old_value` in value) {
+      change.oldValue = value.old_value
     }
 
     if (eventType === `inbox`) {