@electric-ax/agents-server 0.4.6 → 0.4.9

package/src/entity-registry.ts

@@ -15,6 +15,7 @@ import {
   assertEntityStatus,
   assertRunnerAdminStatus,
   assertRunnerKind,
+  isTerminalEntityStatus,
 } from './electric-agents-types.js'
 import { DEFAULT_TENANT_ID } from './tenant.js'
 import type { DrizzleDB } from './db/index.js'
@@ -726,10 +727,13 @@ export class PostgresRegistry {
   }
 
   async updateStatus(entityUrl: string, status: EntityStatus): Promise<void> {
-    const whereClause =
-      status === `stopped`
-        ? this.entityWhere(entityUrl)
-        : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`))
+    const whereClause = isTerminalEntityStatus(status)
+      ? this.entityWhere(entityUrl)
+      : and(
+          this.entityWhere(entityUrl),
+          ne(entities.status, `stopped`),
+          ne(entities.status, `killed`)
+        )
 
     await this.db
       .update(entities)
@@ -740,21 +744,41 @@ export class PostgresRegistry {
   async updateStatusWithTxid(
     entityUrl: string,
     status: EntityStatus
-  ): Promise<number> {
+  ): Promise<number | null> {
     return await this.db.transaction(async (tx) => {
-      const whereClause =
-        status === `stopped`
-          ? this.entityWhere(entityUrl)
-          : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`))
-
-      await tx
+      const rows = await tx
         .update(entities)
         .set({ status, updatedAt: Date.now() })
-        .where(whereClause)
-      const result = await tx.execute(
-        sql`SELECT pg_current_xact_id()::xid::text AS txid`
-      )
-      return parseInt((result[0] as { txid: string }).txid)
+        .where(
+          and(
+            this.entityWhere(entityUrl),
+            ne(entities.status, `stopped`),
+            ne(entities.status, `killed`)
+          )
+        )
+        .returning({
+          txid: sql<string>`pg_current_xact_id()::xid::text`,
+        })
+      return rows[0] ? parseInt(rows[0].txid) : null
+    })
+  }
+
+  async touchEntityWithTxid(entityUrl: string): Promise<number | null> {
+    return await this.db.transaction(async (tx) => {
+      const rows = await tx
+        .update(entities)
+        .set({ updatedAt: Date.now() })
+        .where(
+          and(
+            eq(entities.url, entityUrl),
+            ne(entities.status, `stopped`),
+            ne(entities.status, `killed`)
+          )
+        )
+        .returning({
+          txid: sql<string>`pg_current_xact_id()::xid::text`,
+        })
+      return rows[0] ? parseInt(rows[0].txid) : null
     })
   }
 

package/src/index.ts

@@ -15,6 +15,14 @@ export type {
   SubscriptionResponse,
   SubscriptionStreamInfo,
 } from './stream-client.js'
+export {
+  assertEntitySignal,
+  assertEntityStatus,
+  expectedSignalStatus,
+  isTerminalEntityStatus,
+  rejectsNormalWrites,
+  toPublicEntity,
+} from './electric-agents-types.js'
 export type {
   AuthenticateRequest,
   ConsumerClaim,
@@ -32,11 +40,31 @@ export type {
   RunnerLiveness,
   SourceStreamOffset,
   WakeNotificationRow,
+  ElectricAgentsEntity,
+  ElectricAgentsEntityRow,
+  ElectricAgentsEntityType,
+  EntityStatus,
+  EntitySignal,
+  PublicElectricAgentsEntity,
+  EntityListFilter,
+  RegisterEntityTypeRequest,
+  SendRequest,
+  SignalRequest,
+  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

@@ -217,6 +217,12 @@ export async function assertDispatchPolicyAllowed(
   }
 }
 
+export function shouldLinkDispatchBeforeInitialMessage(
+  policy: DispatchPolicy | undefined
+): boolean {
+  return policy?.targets[0] !== undefined
+}
+
 export async function linkEntityDispatchSubscription(
   ctx: TenantContext,
   entity: ElectricAgentsEntity

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'
@@ -18,6 +22,7 @@ import {
   backfillEntityDispatchPolicy,
   linkEntityDispatchSubscription,
   resolveEffectiveDispatchPolicyForSpawn,
+  shouldLinkDispatchBeforeInitialMessage,
   unlinkEntityDispatchSubscription,
 } from './dispatch-policy.js'
 import { routeBody, withSchema } from './schema.js'
@@ -25,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
@@ -83,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()),
     })
   ),
 })
@@ -133,6 +140,22 @@ const setTagBodySchema = Type.Object({
   value: Type.String(),
 })
 
+const entitySignalSchema = Type.Union([
+  Type.Literal(`SIGINT`),
+  Type.Literal(`SIGHUP`),
+  Type.Literal(`SIGTERM`),
+  Type.Literal(`SIGKILL`),
+  Type.Literal(`SIGSTOP`),
+  Type.Literal(`SIGCONT`),
+  Type.Literal(`SIGUSR`),
+])
+
+const signalBodySchema = Type.Object({
+  signal: entitySignalSchema,
+  reason: Type.Optional(Type.String()),
+  payload: Type.Optional(Type.Unknown()),
+})
+
 const scheduleBodySchema = Type.Union([
   Type.Object({
     scheduleType: Type.Literal(`cron`),
@@ -152,6 +175,24 @@ const scheduleBodySchema = Type.Union([
   }),
 ])
 
+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()),
+})
+
 const entitiesRegisterBodySchema = Type.Object({
   tags: Type.Optional(stringRecordSchema),
 })
@@ -161,7 +202,11 @@ type SendBody = Static<typeof sendBodySchema>
 type InboxMessageBody = Static<typeof inboxMessageBodySchema>
 type ForkBody = Static<typeof forkBodySchema>
 type SetTagBody = Static<typeof setTagBodySchema>
+type SignalBody = Static<typeof signalBodySchema>
 type ScheduleBody = Static<typeof scheduleBodySchema>
+type EventSourceSubscriptionBody = Static<
+  typeof eventSourceSubscriptionBodySchema
+>
 type EntitiesRegisterBody = Static<typeof entitiesRegisterBodySchema>
 
 export const entitiesRouter: EntitiesRoutes = Router<
@@ -187,6 +232,12 @@ entitiesRouter.put(
 entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity)
 entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity)
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity)
+entitiesRouter.post(
+  `/:type/:instanceId/signal`,
+  withExistingEntity,
+  withSchema(signalBodySchema),
+  signalEntity
+)
 entitiesRouter.post(
   `/:type/:instanceId/send`,
   withExistingEntity,
@@ -232,6 +283,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,
@@ -443,6 +505,98 @@ 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
@@ -614,13 +768,21 @@ async function spawnEntity(
     wake: parsed.wake,
     created_by: principal.url,
   })
-  await linkEntityDispatchSubscription(ctx, entity)
+  const linkBeforeInitialMessage =
+    parsed.initialMessage !== undefined &&
+    shouldLinkDispatchBeforeInitialMessage(dispatchPolicy)
+  if (linkBeforeInitialMessage) {
+    await linkEntityDispatchSubscription(ctx, entity)
+  }
   if (parsed.initialMessage !== undefined) {
     await ctx.entityManager.send(entity.url, {
       from: principal.url,
       payload: parsed.initialMessage,
     })
   }
+  if (!linkBeforeInitialMessage) {
+    await linkEntityDispatchSubscription(ctx, entity)
+  }
 
   return json(
     { ...toPublicEntity(entity), txid: entity.txid },
@@ -655,3 +817,27 @@ async function killEntity(
   ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main)
   return json(result)
 }
+
+async function signalEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const principalMutationError = rejectPrincipalEntityMutation(
+    request,
+    `signaled`
+  )
+  if (principalMutationError) return principalMutationError
+
+  const parsed = routeBody<SignalBody>(request)
+  const { entityUrl, entity } = requireExistingEntityRoute(request)
+  const result = await ctx.entityManager.signal(entityUrl, {
+    signal: parsed.signal,
+    reason: parsed.reason,
+    payload: parsed.payload,
+  })
+  if (result.new_state === `stopped` || result.new_state === `killed`) {
+    await unlinkEntityDispatchSubscription(ctx, entity)
+    ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main)
+  }
+  return json(result)
+}

package/src/routing/internal-router.ts

@@ -36,7 +36,10 @@ import { runnersRouter } from './runners-router.js'
 import { routeBody, validateOptionalJsonBody, withSchema } from './schema.js'
 import { withLeadingSlash } from './tenant-stream-paths.js'
 import type { IRequest, RouterType } from 'itty-router'
-import type { WebhookSignatureVerifierConfig } from '@electric-ax/agents-runtime'
+import type {
+  EventSourceContract,
+  WebhookSignatureVerifierConfig,
+} from '@electric-ax/agents-runtime'
 import type { TenantContext } from './context.js'
 import type { DurableStreamsRoutingAdapter } from './durable-streams-routing-adapter.js'
 import type { WebhookSigner } from '../webhook-signing.js'
@@ -117,6 +120,7 @@ export const internalRouter: InternalRoutes = Router<
 })
 
 internalRouter.get(`/health`, () => json({ status: `ok` }))
+internalRouter.get(`/event-sources`, listEventSources)
 internalRouter.post(
   `/wake`,
   withSchema(wakeRegistrationBodySchema),
@@ -335,6 +339,20 @@ async function registerWake(
   return status(204)
 }
 
+async function listEventSources(
+  _request: IRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const eventSources = ctx.eventSources
+    ? await ctx.eventSources.listEventSources()
+    : []
+  return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) })
+}
+
+function isAgentVisibleEventSource(source: EventSourceContract): boolean {
+  return source.agentVisible === true && source.status === `active`
+}
+
 async function webhookForward(
   request: IRequest,
   ctx: TenantContext
@@ -479,7 +497,7 @@ async function webhookForward(
         enrichPromise,
       ])
 
-      if (entity?.status === `stopped`) {
+      if (entity?.status === `stopped` || entity?.status === `paused`) {
         if (upsertPromise) await upsertPromise
         return json({ done: true })
       }
@@ -764,10 +782,13 @@ async function callbackForward(
       //   the token is intact even though entityDispatchState may diverge.
       // If both are false, a newer wake owns the entity — leave status as-is.
       if (entity && (entityCleared || stillOwnsClaim)) {
-        await ctx.entityManager.registry.updateStatus(entity.url, `idle`)
+        await ctx.entityManager.registry.updateStatus(
+          entity.url,
+          entity.status === `stopping` ? `stopped` : `idle`
+        )
         await ctx.entityBridgeManager.onEntityChanged(entity.url)
         serverLog.info(
-          `[callback-forward] status updated to idle for ${entity.url}`
+          `[callback-forward] status updated after done for ${entity.url}`
         )
       } else if (!entity) {
         serverLog.warn(

package/src/routing/runners-router.ts

@@ -575,7 +575,7 @@ async function notificationFromClaim(
       404
     )
   }
-  if (entity.status === `stopped`) {
+  if (entity.status === `stopped` || entity.status === `paused`) {
     await ctx.streamClient.releaseSubscription(
       input.subscriptionId,
       input.claim.token,

package/src/runtime.ts

@@ -533,7 +533,11 @@ export class ElectricAgentsTenantRuntime {
       return
     }
 
-    await this.manager.registry.updateStatus(entityUrl, `idle`)
+    const entity = await this.manager.registry.getEntity(entityUrl)
+    await this.manager.registry.updateStatus(
+      entityUrl,
+      entity?.status === `stopping` ? `stopped` : `idle`
+    )
     await this.entityBridgeManager.onEntityChanged(entityUrl)
   }
 }

package/src/server.ts

@@ -34,6 +34,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 { StartedStandaloneAgentsRuntime } from './standalone-runtime.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 import type {
@@ -67,6 +68,8 @@ export interface ElectricAgentsServerOptions {
     request: Request
   ) => Promise<Principal | null> | Principal | null
   allowDevPrincipalFallback?: boolean
+  eventSources?: EventSourceCatalog
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
   /**
    * Disabled by default. When set to a positive interval, periodically
    * recovers expired dispatch claims and stale outstanding wakes.
@@ -441,6 +444,15 @@ export class ElectricAgentsServer {
       streamClient: this.streamClient,
       runtime: this.standaloneRuntime.runtime,
       entityBridgeManager: this.entityBridgeManager,
+      ...(this.options.eventSources
+        ? { eventSources: this.options.eventSources }
+        : {}),
+      ...(this.options.ensureEventSourceWakeSource
+        ? {
+            ensureEventSourceWakeSource:
+              this.options.ensureEventSourceWakeSource,
+          }
+        : {}),
       isShuttingDown: () => this.shuttingDown,
       mockAgent: this.mockAgentBootstrap
         ? { runtime: this.mockAgentBootstrap.runtime }