RuntimeHandler

Factory functions that create the runtime request router and Node HTTP adapter. The router handles webhook wake delivery from the Electric Agents runtime server and registers entity types on startup.

Source: @electric-ax/agents-runtime

RuntimeRouter

interface RuntimeRouter {
  handleRequest(request: Request): Promise<Response | null>
  handleWebhookRequest(request: Request): Promise<Response>
  dispatchWebhookWake(notification: WebhookNotification): void
  drainWakes(): Promise<void>
  waitForSettled(): Promise<void>
  abortWakes(): void
  debugState(): RuntimeDebugState
  readonly typeNames: string[]
  registerTypes(): Promise<void>
}

Method	Return Type	Description
handleRequest(request)	Promise<Response | null>	Route a fetch Request. Returns null if the request path does not match webhookPath.
handleWebhookRequest(request)	Promise<Response>	Handle a webhook request directly, without route matching.
dispatchWebhookWake(notification)	void	Dispatch an already-parsed webhook notification. Runs the wake handler in the background.
drainWakes()	Promise<void>	Wait for all in-flight wake handlers to settle. Throws if any wake errored.
waitForSettled()	Promise<void>	Wait for all in-flight wake handlers to settle.
abortWakes()	void	Abort in-flight wakes so host shutdown can complete quickly.
debugState()	RuntimeDebugState	Return a runtime-local snapshot for tests and shutdown diagnostics.
typeNames	string[]	Names of all registered entity types (read-only).
registerTypes()	Promise<void>	Register all entity types with the Electric Agents runtime server. Uses upsert semantics — safe to call on every startup.

RuntimeHandler

Extends RuntimeRouter with a Node HTTP adapter.

interface RuntimeHandler extends RuntimeRouter {
  onEnter(req: IncomingMessage, res: ServerResponse): Promise<void>
}

Method	Parameters	Description
onEnter(req, res)	Node IncomingMessage, ServerResponse	Node HTTP adapter. Converts the request to a fetch Request and delegates to handleWebhookRequest.

RuntimeDebugState

interface RuntimeDebugState {
  pendingWakeCount: number
  pendingWakeLabels: string[]
  wakeErrorCount: number
  typeNames: string[]
}

Field	Type	Description
pendingWakeCount	number	Number of in-flight wake handlers.
pendingWakeLabels	string[]	Labels identifying each pending wake (for diagnostics).
wakeErrorCount	number	Number of wake handlers that have errored.
typeNames	string[]	Names of all registered entity types.

Factory functions

function createRuntimeRouter(config: RuntimeRouterConfig): RuntimeRouter

function createRuntimeHandler(config: RuntimeHandlerConfig): RuntimeHandler

Both factory functions accept the same runtime router configuration.

RuntimeRouterConfig

interface RuntimeRouterConfig {
  baseUrl: string
  serveEndpoint?: string
  webhookPath?: string
  handlerUrl?: string
  registry?: EntityRegistry
  subscriptionPathForType?: (typeName: string) => string
  idleTimeout?: number
  heartbeatInterval?: number
  createElectricTools?: (context: {
    entityUrl: string
    entityType: string
    args: Readonly<Record<string, unknown>>
    db: EntityStreamDBWithActions
    events: Array<ChangeEvent>
    upsertCronSchedule(opts: {
      id: string
      expression: string
      timezone?: string
      payload?: unknown
      debounceMs?: number
      timeoutMs?: number
    }): Promise<{ txid: string }>
    upsertFutureSendSchedule(opts: {
      id: string
      payload: unknown
      targetUrl?: string
      fireAt: string
      from?: string
      messageType?: string
    }): Promise<{ txid: string }>
    deleteSchedule(opts: { id: string }): Promise<{ txid: string }>
  }) => AgentTool[] | Promise<AgentTool[]>
  onWakeError?: (error: Error) => boolean | void
  registrationConcurrency?: number
}

Field	Type	Default	Description
baseUrl	string	-	Base URL of the Electric Agents runtime server (e.g. "http://localhost:4437"). Required.
serveEndpoint	string	-	Full webhook callback URL exposed by your app. Used for type registration.
webhookPath	string	pathname from serveEndpoint / handlerUrl, or "/electric-agents"	Path matched by handleRequest().
handlerUrl	string	-	Backward-compatible alias for serveEndpoint; prefer serveEndpoint in new code.
registry	EntityRegistry	default registry	Entity registry for this handler. Falls back to the module-level default registry.
subscriptionPathForType	(typeName: string) => string	-	Override the webhook subscription path used per entity type registration.
idleTimeout	number	20000	Idle timeout in milliseconds before closing a wake.
heartbeatInterval	number	30000	Heartbeat interval in milliseconds.
createElectricTools	(context) => AgentTool[] | Promise<...>	-	Optional tool factory invoked for each wake context before handler execution. Provides extra tools to the agent.
onWakeError	(error: Error) => boolean | void	-	Observer for background wake failures. Return true to mark the error as handled so it is not rethrown on drain.
registrationConcurrency	number	8	Max number of concurrent entity-type registrations.