@electric-ax/agents-server 0.4.7 → 0.4.11

package/src/electric-agents/default-entity-schemas.ts

@@ -1 +1 @@
-export { DEFAULT_OUTPUT_SCHEMAS } from '@electric-ax/agents-runtime'
+export { DEFAULT_STATE_SCHEMAS } from '@electric-ax/agents-runtime'

package/src/electric-agents-types.ts

@@ -400,6 +400,7 @@ export interface TypedSpawnRequest {
     debounceMs?: number
     timeoutMs?: number
     includeResponse?: boolean
+    manifestKey?: string
   }
 }
 
@@ -456,4 +457,4 @@ export const ErrCodeForkWaitTimeout = `FORK_WAIT_TIMEOUT`
 export const ErrCodeEntityPersistFailed = `ENTITY_PERSIST_FAILED`
 export const ErrCodeAgentUiNotFound = `AGENT_UI_NOT_FOUND`
 export const ErrCodeSubscriptionNotFound = `SUBSCRIPTION_NOT_FOUND`
-export const ErrCodeCallbackNotFound = `CALLBACK_NOT_FOUND`
+export const ErrCodeWakeCallbackNotFound = `WAKE_CALLBACK_NOT_FOUND`

package/src/entity-manager.ts

@@ -6,6 +6,7 @@ import {
   getCronStreamPath,
   getSharedStateStreamPath,
   getNextCronFireAt,
+  eventSourceSubscriptionManifestKey,
   manifestChildKey,
   manifestSharedStateKey,
   manifestSourceKey,
@@ -50,6 +51,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 { PostgresRegistry } from './entity-registry.js'
 import type { SchemaValidator } from './electric-agents/schema-validator.js'
 import type { StreamClient } from './stream-client.js'
@@ -554,6 +556,7 @@ export class EntityManager {
         timeoutMs: req.wake.timeoutMs,
         oneShot: false,
         includeResponse: req.wake.includeResponse,
+        manifestKey: req.wake.manifestKey,
       })
     }
 
@@ -1672,7 +1675,7 @@ export class EntityManager {
   // ==========================================================================
 
   /**
-   * Deliver a message to an entity's main stream, with optional input schema
+   * Deliver a message to an entity's main stream, with optional inbox schema
    * validation.
    */
   async send(
@@ -1885,7 +1888,7 @@ export class EntityManager {
     return updated
   }
 
-  async removeTag(
+  async deleteTag(
     entityUrl: string,
     key: string,
     token: string
@@ -1927,7 +1930,7 @@ export class EntityManager {
     return updated
   }
 
-  async registerEntitiesSource(tags: Record<string, string>): Promise<{
+  async ensureEntitiesMembershipStream(tags: Record<string, string>): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
@@ -2162,6 +2165,67 @@ export class EntityManager {
     return { txid }
   }
 
+  async upsertEventSourceSubscription(
+    entityUrl: string,
+    req: {
+      subscription: EventSourceSubscription
+      manifest: Record<string, unknown>
+    }
+  ): Promise<{ txid: string; subscription: EventSourceSubscription }> {
+    const manifestKey = req.subscription.manifestKey
+    const txid = randomUUID()
+    await this.writeManifestEntry(
+      entityUrl,
+      manifestKey,
+      `upsert`,
+      req.manifest,
+      {
+        txid,
+      }
+    )
+
+    // The manifest is the durable source of truth. Register side effects after
+    // it is appended so failures can be repaired by manifest replay.
+    await this.wakeRegistry.unregisterByManifestKey(
+      entityUrl,
+      manifestKey,
+      this.tenantId
+    )
+    await this.wakeRegistry.register({
+      tenantId: this.tenantId,
+      subscriberUrl: entityUrl,
+      sourceUrl: req.subscription.sourceUrl,
+      condition: {
+        on: `change`,
+        collections: [`webhook_event`],
+        ops: [`insert`],
+      },
+      oneShot: false,
+      manifestKey,
+    })
+
+    return { txid, subscription: req.subscription }
+  }
+
+  async deleteEventSourceSubscription(
+    entityUrl: string,
+    req: { id: string }
+  ): Promise<{ txid: string }> {
+    const manifestKey = eventSourceSubscriptionManifestKey(req.id)
+    const txid = randomUUID()
+    await this.writeManifestEntry(entityUrl, manifestKey, `delete`, undefined, {
+      txid,
+    })
+
+    await this.wakeRegistry.unregisterByManifestKey(
+      entityUrl,
+      manifestKey,
+      this.tenantId
+    )
+
+    return { txid }
+  }
+
   // ==========================================================================
   // Wake Evaluation
   // ==========================================================================
@@ -2678,7 +2742,7 @@ export class EntityManager {
   // ==========================================================================
 
   /**
-   * Add new input/output schema keys to an entity type directly in Postgres.
+   * Add new inbox/state schema keys to an entity type directly in Postgres.
    */
   async amendSchemas(
     typeName: string,
@@ -2767,7 +2831,7 @@ export class EntityManager {
 
   /**
    * Enrich webhook payload with entity context.
-   * Called by ElectricAgentsServer during webhook forwarding to inject entity context.
+   * Called by ElectricAgentsServer during subscription webhook dispatch to inject entity context.
    */
   async enrichPayload(
     payload: Record<string, unknown>,

package/src/index.ts

@@ -53,10 +53,18 @@ export type {
   SignalResponse,
   TypedSpawnRequest,
 } from './electric-agents-types.js'
+export type {
+  EventSourceBucket,
+  EventSourceContract,
+  EventSourceFilter,
+  EventSourceSubscription,
+  EventSourceSubscriptionInput,
+  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 { TenantContext } from './routing/context.js'
+export type { EventSourceCatalog, TenantContext } from './routing/context.js'
 export {
   streamRootDurableStreamsRoutingAdapter,
   pathPrefixedSingleTenantDurableStreamsRoutingAdapter,

package/src/manifest-side-effects.ts

@@ -1,5 +1,6 @@
 import {
   getCronStreamPathFromSpec,
+  getWebhookStreamPath,
   getSharedStateStreamPath,
   resolveCronScheduleSpec,
 } from '@electric-ax/agents-runtime'
@@ -56,6 +57,16 @@ export function extractManifestSourceUrl(
         : undefined
     }
 
+    if (manifest.sourceType === `webhook`) {
+      if (typeof config?.streamUrl === `string`) return config.streamUrl
+      if (typeof config?.endpointKey === `string`) {
+        return getWebhookStreamPath(
+          config.endpointKey,
+          typeof config.bucket === `string` ? config.bucket : undefined
+        )
+      }
+    }
+
     return undefined
   }
 

package/src/routing/context.ts

@@ -1,5 +1,8 @@
 import type { Agent } from 'undici'
-import type { WebhookSignatureVerifierConfig } from '@electric-ax/agents-runtime'
+import type {
+  EventSourceContract,
+  WebhookSignatureVerifierConfig,
+} from '@electric-ax/agents-runtime'
 import type { DrizzleDB } from '../db/index.js'
 import type { EntityBridgeCoordinator } from '../entity-bridge-manager.js'
 import type { EntityManager } from '../entity-manager.js'
@@ -10,6 +13,18 @@ import type { Principal } from '../principal.js'
 import type { DurableStreamsBearerProvider } from '../stream-client.js'
 import type { WebhookSigner } from '../webhook-signing.js'
 
+export interface EventSourceCatalog {
+  listEventSources: () =>
+    | Array<EventSourceContract>
+    | Promise<Array<EventSourceContract>>
+  getEventSource: (
+    sourceKey: string
+  ) =>
+    | EventSourceContract
+    | undefined
+    | Promise<EventSourceContract | undefined>
+}
+
 /**
  * Per-request tenant context passed through every router and handler.
  *
@@ -38,5 +53,7 @@ export interface TenantContext {
   streamClient: StreamClient
   runtime: ElectricAgentsTenantRuntime
   entityBridgeManager: EntityBridgeCoordinator
+  eventSources?: EventSourceCatalog
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
   isShuttingDown: () => boolean
 }

package/src/routing/dispatch-policy.ts

@@ -326,7 +326,7 @@ async function linkStreamToTargetSubscription(
   }
   const forwardUrl = appendPathToUrl(
     ctx.publicUrl,
-    `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`
+    `/_electric/subscription-webhooks/${encodeURIComponent(subscriptionId)}`
   )
   await ensureSubscriptionIncludesStream(
     ctx,

package/src/routing/durable-streams-router.ts

@@ -332,7 +332,7 @@ async function rewriteSubscriptionRequestBody(
     targetWebhookUrl = rewriteLoopbackWebhookUrl(payload.webhook.url) ?? null
     payload.webhook.url = appendPathToUrl(
       ctx.publicUrl,
-      `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`
+      `/_electric/subscription-webhooks/${encodeURIComponent(subscriptionId)}`
     )
   }
 

package/src/routing/durable-streams-routing-adapter.ts

@@ -13,9 +13,7 @@ export interface DurableStreamsRoutingAdapter {
 
 function appendSearch(target: URL, source: URL): URL {
   source.searchParams.forEach((value, key) => {
-    if (key !== `service`) {
-      target.searchParams.append(key, value)
-    }
+    target.searchParams.append(key, value)
   })
   return target
 }

package/src/routing/entities-router.ts

@@ -3,6 +3,10 @@
  */
 
 import { Type, type Static } from '@sinclair/typebox'
+import {
+  buildEventSourceManifestEntry,
+  resolveEventSourceSubscription,
+} from '@electric-ax/agents-runtime'
 import { Router, json, status } from 'itty-router'
 import { apiError } from '../electric-agents-http.js'
 import { parsePrincipalKey, principalUrl } from '../principal.js'
@@ -26,6 +30,7 @@ import type { ElectricAgentsEntity } from '../electric-agents-types.js'
 import type { JsonRouteRequest } from './schema.js'
 import type { RouterType } from 'itty-router'
 import type { TenantContext } from './context.js'
+import type { EventSourceSubscriptionInput } from '@electric-ax/agents-runtime'
 
 interface AgentsRouteRequest extends JsonRouteRequest {
   entityRoute?: ExistingEntityRoute
@@ -84,6 +89,7 @@ const spawnBodySchema = Type.Object({
       debounceMs: Type.Optional(Type.Number()),
       timeoutMs: Type.Optional(Type.Number()),
       includeResponse: Type.Optional(Type.Boolean()),
+      manifestKey: Type.Optional(Type.String()),
     })
   ),
 })
@@ -169,8 +175,22 @@ const scheduleBodySchema = Type.Union([
   }),
 ])
 
-const entitiesRegisterBodySchema = Type.Object({
-  tags: Type.Optional(stringRecordSchema),
+const subscriptionLifetimeSchema = Type.Union([
+  Type.Object({ kind: Type.Literal(`until_entity_stopped`) }),
+  Type.Object({
+    kind: Type.Literal(`expires_at`),
+    at: Type.String(),
+  }),
+  Type.Object({ kind: Type.Literal(`manual`) }),
+])
+
+const eventSourceSubscriptionBodySchema = Type.Object({
+  sourceKey: Type.String(),
+  bucketKey: Type.Optional(Type.String()),
+  params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  filterKey: Type.Optional(Type.String()),
+  lifetime: Type.Optional(subscriptionLifetimeSchema),
+  reason: Type.Optional(Type.String()),
 })
 
 type SpawnBody = Static<typeof spawnBodySchema>
@@ -180,7 +200,9 @@ type ForkBody = Static<typeof forkBodySchema>
 type SetTagBody = Static<typeof setTagBodySchema>
 type SignalBody = Static<typeof signalBodySchema>
 type ScheduleBody = Static<typeof scheduleBodySchema>
-type EntitiesRegisterBody = Static<typeof entitiesRegisterBodySchema>
+type EventSourceSubscriptionBody = Static<
+  typeof eventSourceSubscriptionBodySchema
+>
 
 export const entitiesRouter: EntitiesRoutes = Router<
   AgentsRouteRequest,
@@ -191,11 +213,6 @@ export const entitiesRouter: EntitiesRoutes = Router<
 })
 
 entitiesRouter.get(`/`, listEntities)
-entitiesRouter.post(
-  `/register`,
-  withSchema(entitiesRegisterBodySchema),
-  registerEntitiesSource
-)
 entitiesRouter.put(
   `/:type/:instanceId`,
   withSpawnableEntityType,
@@ -243,7 +260,7 @@ entitiesRouter.post(
 entitiesRouter.delete(
   `/:type/:instanceId/tags/:tagKey`,
   withExistingEntity,
-  removeTag
+  deleteTag
 )
 entitiesRouter.put(
   `/:type/:instanceId/schedules/:scheduleId`,
@@ -256,6 +273,17 @@ entitiesRouter.delete(
   withExistingEntity,
   deleteSchedule
 )
+entitiesRouter.put(
+  `/:type/:instanceId/event-source-subscriptions/:subscriptionId`,
+  withExistingEntity,
+  withSchema(eventSourceSubscriptionBodySchema),
+  upsertEventSourceSubscription
+)
+entitiesRouter.delete(
+  `/:type/:instanceId/event-source-subscriptions/:subscriptionId`,
+  withExistingEntity,
+  deleteEventSourceSubscription
+)
 
 function entityUrlFromSegments(
   type: string,
@@ -391,17 +419,6 @@ async function listEntities(
   return json(entities.map((entity) => toPublicEntity(entity)))
 }
 
-async function registerEntitiesSource(
-  request: AgentsRouteRequest,
-  ctx: TenantContext
-): Promise<Response> {
-  const parsed = routeBody<EntitiesRegisterBody>(request)
-  const result = await ctx.entityManager.registerEntitiesSource(
-    parsed.tags ?? {}
-  )
-  return json(result)
-}
-
 async function upsertSchedule(
   request: AgentsRouteRequest,
   ctx: TenantContext
@@ -467,13 +484,105 @@ async function deleteSchedule(
   return json(result)
 }
 
+async function upsertEventSourceSubscription(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const principalMutationError = rejectPrincipalEntityMutation(
+    request,
+    `subscribed to event sources`
+  )
+  if (principalMutationError) return principalMutationError
+
+  const catalog = ctx.eventSources
+  if (!catalog) {
+    return apiError(
+      404,
+      ErrCodeNotFound,
+      `No event source catalog is configured`
+    )
+  }
+
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const parsed = routeBody<EventSourceSubscriptionBody>(request)
+  const source = await catalog.getEventSource(parsed.sourceKey)
+  if (!source) {
+    return apiError(
+      404,
+      ErrCodeNotFound,
+      `Event source "${parsed.sourceKey}" not found`
+    )
+  }
+
+  if (parsed.lifetime?.kind === `expires_at`) {
+    const expiresAt = new Date(parsed.lifetime.at)
+    if (Number.isNaN(expiresAt.getTime())) {
+      return apiError(
+        400,
+        ErrCodeInvalidRequest,
+        `Invalid expires_at lifetime timestamp`
+      )
+    }
+  }
+
+  let resolved: ReturnType<typeof resolveEventSourceSubscription>
+  try {
+    resolved = resolveEventSourceSubscription({
+      contract: source,
+      entityUrl,
+      request: {
+        ...(parsed as EventSourceSubscriptionInput),
+        id: decodeURIComponent(request.params.subscriptionId),
+      },
+      createdBy: `tool`,
+    })
+  } catch (error) {
+    return apiError(
+      400,
+      ErrCodeInvalidRequest,
+      error instanceof Error ? error.message : String(error)
+    )
+  }
+
+  await ctx.ensureEventSourceWakeSource?.(resolved.subscription.sourceUrl)
+
+  const result = await ctx.entityManager.upsertEventSourceSubscription(
+    entityUrl,
+    {
+      subscription: resolved.subscription,
+      manifest: buildEventSourceManifestEntry(resolved),
+    }
+  )
+  return json(result)
+}
+
+async function deleteEventSourceSubscription(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const principalMutationError = rejectPrincipalEntityMutation(
+    request,
+    `unsubscribed from event sources`
+  )
+  if (principalMutationError) return principalMutationError
+
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const result = await ctx.entityManager.deleteEventSourceSubscription(
+    entityUrl,
+    {
+      id: decodeURIComponent(request.params.subscriptionId),
+    }
+  )
+  return json(result)
+}
+
 async function setTag(
   request: AgentsRouteRequest,
   ctx: TenantContext
 ): Promise<Response> {
   const principalMutationError = rejectPrincipalEntityMutation(
     request,
-    `tagged`
+    `tag updated`
   )
   if (principalMutationError) return principalMutationError
 
@@ -489,19 +598,19 @@ async function setTag(
   return json(toPublicEntity(updated))
 }
 
-async function removeTag(
+async function deleteTag(
   request: AgentsRouteRequest,
   ctx: TenantContext
 ): Promise<Response> {
   const principalMutationError = rejectPrincipalEntityMutation(
     request,
-    `untagged`
+    `tag deleted`
   )
   if (principalMutationError) return principalMutationError
 
   const { entityUrl } = requireExistingEntityRoute(request)
   const token = writeTokenFromRequest(request)
-  const updated = await ctx.entityManager.removeTag(
+  const updated = await ctx.entityManager.deleteTag(
     entityUrl,
     decodeURIComponent(request.params.tagKey),
     token

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

@@ -35,32 +35,32 @@ export type ElectricAgentsEntityTypeRoutes = RouterType<
 >
 
 type PublicEntityTypeResponse = ElectricAgentsEntityType & {
-  input_schemas?: Record<string, Record<string, unknown>>
-  output_schemas?: Record<string, Record<string, unknown>>
   revision: number
 }
 
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown())
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema)
 
-const registerEntityTypeBodySchema = Type.Object({
-  name: Type.Optional(Type.String()),
-  description: Type.Optional(Type.String()),
-  creation_schema: Type.Optional(jsonObjectSchema),
-  inbox_schemas: Type.Optional(schemaMapSchema),
-  state_schemas: Type.Optional(schemaMapSchema),
-  input_schemas: Type.Optional(schemaMapSchema),
-  output_schemas: Type.Optional(schemaMapSchema),
-  serve_endpoint: Type.Optional(Type.String()),
-  default_dispatch_policy: Type.Optional(dispatchPolicySchema),
-})
+const registerEntityTypeBodySchema = Type.Object(
+  {
+    name: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    creation_schema: Type.Optional(jsonObjectSchema),
+    inbox_schemas: Type.Optional(schemaMapSchema),
+    state_schemas: Type.Optional(schemaMapSchema),
+    serve_endpoint: Type.Optional(Type.String()),
+    default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+  },
+  { additionalProperties: false }
+)
 
-const amendEntityTypeSchemasBodySchema = Type.Object({
-  input_schemas: Type.Optional(schemaMapSchema),
-  output_schemas: Type.Optional(schemaMapSchema),
-  inbox_schemas: Type.Optional(schemaMapSchema),
-  state_schemas: Type.Optional(schemaMapSchema),
-})
+const amendEntityTypeSchemasBodySchema = Type.Object(
+  {
+    inbox_schemas: Type.Optional(schemaMapSchema),
+    state_schemas: Type.Optional(schemaMapSchema),
+  },
+  { additionalProperties: false }
+)
 
 type RegisterEntityTypeBody = Static<typeof registerEntityTypeBodySchema>
 type AmendEntityTypeSchemasBody = Static<
@@ -181,8 +181,8 @@ async function amendSchemas(
   const parsed = routeBody<AmendEntityTypeSchemasBody>(request)
 
   const updated = await ctx.entityManager.amendSchemas(request.params.name, {
-    inbox_schemas: parsed.inbox_schemas ?? parsed.input_schemas,
-    state_schemas: parsed.state_schemas ?? parsed.output_schemas,
+    inbox_schemas: parsed.inbox_schemas,
+    state_schemas: parsed.state_schemas,
   })
   return json(toPublicEntityType(updated))
 }
@@ -199,13 +199,12 @@ function normalizeEntityTypeRequest(
   parsed: RegisterEntityTypeBody | RegisterEntityTypeRequest
 ): RegisterEntityTypeRequest {
   const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint)
-  const compatibilityFields = parsed as RegisterEntityTypeBody
   return {
     name: parsed.name ?? ``,
     description: parsed.description ?? ``,
     creation_schema: parsed.creation_schema,
-    inbox_schemas: parsed.inbox_schemas ?? compatibilityFields.input_schemas,
-    state_schemas: parsed.state_schemas ?? compatibilityFields.output_schemas,
+    inbox_schemas: parsed.inbox_schemas,
+    state_schemas: parsed.state_schemas,
     serve_endpoint: serveEndpoint,
     default_dispatch_policy:
       parsed.default_dispatch_policy ??
@@ -222,8 +221,6 @@ function toPublicEntityType(
 ): PublicEntityTypeResponse {
   return {
     ...entityType,
-    input_schemas: entityType.inbox_schemas,
-    output_schemas: entityType.state_schemas,
     revision: entityType.revision,
   }
 }

package/src/routing/hooks.ts

@@ -121,7 +121,7 @@ export function rejectIfShuttingDown(
 ): Response | undefined {
   if (!ctx.isShuttingDown()) return undefined
   const path = new URL(req.url).pathname
-  if (!path.startsWith(`/_electric/webhook-forward/`)) return undefined
+  if (!path.startsWith(`/_electric/subscription-webhooks/`)) return undefined
   return apiError(503, `SERVER_STOPPING`, `Server is shutting down`)
 }