@electric-ax/agents-server 0.4.7 → 0.4.9

package/dist/entrypoint.js

@@ -4,7 +4,7 @@ import { DurableStreamTestServer } from "@durable-streams/server";
 import { createServer } from "node:http";
 import { createServerAdapter } from "@whatwg-node/server";
 import { Agent } from "undici";
-import { appendPathToUrl, assertTags, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import fs, { existsSync } from "node:fs";
 import path, { dirname, resolve } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
@@ -2668,6 +2668,10 @@ function extractManifestSourceUrl(manifest) {
 		}
 		if (manifest.sourceType === `entities`) return typeof manifest.sourceRef === `string` ? `/_entities/${manifest.sourceRef}` : void 0;
 		if (manifest.sourceType === `db`) return typeof manifest.sourceRef === `string` ? getSharedStateStreamPath(manifest.sourceRef) : void 0;
+		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 : void 0);
+		}
 		return void 0;
 	}
 	if (manifest.kind === `shared-state`) return typeof manifest.id === `string` ? getSharedStateStreamPath(manifest.id) : void 0;
@@ -2954,7 +2958,8 @@ var EntityManager = class {
 			debounceMs: req.wake.debounceMs,
 			timeoutMs: req.wake.timeoutMs,
 			oneShot: false,
-			includeResponse: req.wake.includeResponse
+			includeResponse: req.wake.includeResponse,
+			manifestKey: req.wake.manifestKey
 		});
 		const contentType = `application/json`;
 		const createdEvent = entityStateSchema.entityCreated.insert({
@@ -3848,6 +3853,35 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
+	async upsertEventSourceSubscription(entityUrl, req) {
+		const manifestKey = req.subscription.manifestKey;
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
+		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, req) {
+		const manifestKey = eventSourceSubscriptionManifestKey(req.id);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
 	/**
 	* Register a wake subscription from a subscriber to a source entity.
 	*/
@@ -4476,7 +4510,8 @@ const spawnBodySchema = Type.Object({
 		condition: wakeConditionSchema,
 		debounceMs: Type.Optional(Type.Number()),
 		timeoutMs: Type.Optional(Type.Number()),
-		includeResponse: Type.Optional(Type.Boolean())
+		includeResponse: Type.Optional(Type.Boolean()),
+		manifestKey: Type.Optional(Type.String())
 	}))
 });
 const sendBodySchema = Type.Object({
@@ -4542,6 +4577,22 @@ const scheduleBodySchema = Type.Union([Type.Object({
 	messageType: Type.Optional(Type.String()),
 	from: Type.Optional(Type.String())
 })]);
+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) });
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
@@ -4559,6 +4610,8 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, removeTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, 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, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -4665,6 +4718,47 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return json(result);
 }
+async function upsertEventSourceSubscription(request, ctx) {
+	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(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;
+	try {
+		resolved = resolveEventSourceSubscription({
+			contract: source,
+			entityUrl,
+			request: {
+				...parsed,
+				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, ctx) {
+	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, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
 	if (principalMutationError) return principalMutationError;
@@ -5379,6 +5473,7 @@ const callbackForwardBodySchema = Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = Router({ base: `/_electric` });
 internalRouter.get(`/health`, () => json({ status: `ok` }));
+internalRouter.get(`/event-sources`, listEventSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/webhook-forward/:subscriptionId`, webhookForward);
 internalRouter.post(`/callback-forward/:consumerId`, callbackForward);
@@ -5482,6 +5577,13 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return status(204);
 }
+async function listEventSources(_request, ctx) {
+	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
+	return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+}
+function isAgentVisibleEventSource(source) {
+	return source.agentVisible === true && source.status === `active`;
+}
 async function webhookForward(request, ctx) {
 	const subscriptionId = routeParam(request, `subscriptionId`);
 	const rootSpan = getRequestSpan(request);
@@ -8062,6 +8164,8 @@ var ElectricAgentsServer = class {
 			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 } : void 0
 		};

package/dist/index.cjs

@@ -2653,6 +2653,10 @@ function extractManifestSourceUrl(manifest) {
 		}
 		if (manifest.sourceType === `entities`) return typeof manifest.sourceRef === `string` ? `/_entities/${manifest.sourceRef}` : void 0;
 		if (manifest.sourceType === `db`) return typeof manifest.sourceRef === `string` ? (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(manifest.sourceRef) : void 0;
+		if (manifest.sourceType === `webhook`) {
+			if (typeof config?.streamUrl === `string`) return config.streamUrl;
+			if (typeof config?.endpointKey === `string`) return (0, __electric_ax_agents_runtime.getWebhookStreamPath)(config.endpointKey, typeof config.bucket === `string` ? config.bucket : void 0);
+		}
 		return void 0;
 	}
 	if (manifest.kind === `shared-state`) return typeof manifest.id === `string` ? (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(manifest.id) : void 0;
@@ -2939,7 +2943,8 @@ var EntityManager = class {
 			debounceMs: req.wake.debounceMs,
 			timeoutMs: req.wake.timeoutMs,
 			oneShot: false,
-			includeResponse: req.wake.includeResponse
+			includeResponse: req.wake.includeResponse,
+			manifestKey: req.wake.manifestKey
 		});
 		const contentType = `application/json`;
 		const createdEvent = __electric_ax_agents_runtime.entityStateSchema.entityCreated.insert({
@@ -3833,6 +3838,35 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
+	async upsertEventSourceSubscription(entityUrl, req) {
+		const manifestKey = req.subscription.manifestKey;
+		const txid = (0, node_crypto.randomUUID)();
+		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
+		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, req) {
+		const manifestKey = (0, __electric_ax_agents_runtime.eventSourceSubscriptionManifestKey)(req.id);
+		const txid = (0, node_crypto.randomUUID)();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
 	/**
 	* Register a wake subscription from a subscriber to a source entity.
 	*/
@@ -6713,7 +6747,8 @@ const spawnBodySchema = __sinclair_typebox.Type.Object({
 		condition: wakeConditionSchema,
 		debounceMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
 		timeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
-		includeResponse: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean())
+		includeResponse: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean()),
+		manifestKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 	}))
 });
 const sendBodySchema = __sinclair_typebox.Type.Object({
@@ -6779,6 +6814,22 @@ const scheduleBodySchema = __sinclair_typebox.Type.Union([__sinclair_typebox.Typ
 	messageType: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
 	from: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 })]);
+const subscriptionLifetimeSchema = __sinclair_typebox.Type.Union([
+	__sinclair_typebox.Type.Object({ kind: __sinclair_typebox.Type.Literal(`until_entity_stopped`) }),
+	__sinclair_typebox.Type.Object({
+		kind: __sinclair_typebox.Type.Literal(`expires_at`),
+		at: __sinclair_typebox.Type.String()
+	}),
+	__sinclair_typebox.Type.Object({ kind: __sinclair_typebox.Type.Literal(`manual`) })
+]);
+const eventSourceSubscriptionBodySchema = __sinclair_typebox.Type.Object({
+	sourceKey: __sinclair_typebox.Type.String(),
+	bucketKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	params: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Unknown())),
+	filterKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	lifetime: __sinclair_typebox.Type.Optional(subscriptionLifetimeSchema),
+	reason: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
+});
 const entitiesRegisterBodySchema = __sinclair_typebox.Type.Object({ tags: __sinclair_typebox.Type.Optional(stringRecordSchema) });
 const entitiesRouter = (0, itty_router.Router)({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
@@ -6796,6 +6847,8 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, removeTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, 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, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -6902,6 +6955,47 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return (0, itty_router.json)(result);
 }
+async function upsertEventSourceSubscription(request, ctx) {
+	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(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;
+	try {
+		resolved = (0, __electric_ax_agents_runtime.resolveEventSourceSubscription)({
+			contract: source,
+			entityUrl,
+			request: {
+				...parsed,
+				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: (0, __electric_ax_agents_runtime.buildEventSourceManifestEntry)(resolved)
+	});
+	return (0, itty_router.json)(result);
+}
+async function deleteEventSourceSubscription(request, ctx) {
+	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 (0, itty_router.json)(result);
+}
 async function setTag(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
 	if (principalMutationError) return principalMutationError;
@@ -7616,6 +7710,7 @@ const callbackForwardBodySchema = __sinclair_typebox.Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = (0, itty_router.Router)({ base: `/_electric` });
 internalRouter.get(`/health`, () => (0, itty_router.json)({ status: `ok` }));
+internalRouter.get(`/event-sources`, listEventSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/webhook-forward/:subscriptionId`, webhookForward);
 internalRouter.post(`/callback-forward/:consumerId`, callbackForward);
@@ -7719,6 +7814,13 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return (0, itty_router.status)(204);
 }
+async function listEventSources(_request, ctx) {
+	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
+	return (0, itty_router.json)({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+}
+function isAgentVisibleEventSource(source) {
+	return source.agentVisible === true && source.status === `active`;
+}
 async function webhookForward(request, ctx) {
 	const subscriptionId = routeParam(request, `subscriptionId`);
 	const rootSpan = getRequestSpan(request);

package/dist/index.d.cts

@@ -187,7 +187,7 @@ import * as drizzle_orm_pg_core238 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core239 from "drizzle-orm/pg-core";
 import * as drizzle_orm73 from "drizzle-orm";
 import * as drizzle_orm74 from "drizzle-orm";
-import { EntityTags, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
 import "@sinclair/typebox";
 import { MaybePromise } from "@durable-streams/client";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -3441,6 +3441,7 @@ interface TypedSpawnRequest {
     debounceMs?: number;
     timeoutMs?: number;
     includeResponse?: boolean;
+    manifestKey?: string;
   };
 }
 interface SendRequest {
@@ -4205,6 +4206,18 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
+  upsertEventSourceSubscription(entityUrl: string, req: {
+    subscription: EventSourceSubscription$1;
+    manifest: Record<string, unknown>;
+  }): Promise<{
+    txid: string;
+    subscription: EventSourceSubscription$1;
+  }>;
+  deleteEventSourceSubscription(entityUrl: string, req: {
+    id: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -4454,6 +4467,10 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
+interface EventSourceCatalog {
+  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
+  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+}
 /**
  * Per-request tenant context passed through every router and handler.
  *
@@ -4480,6 +4497,8 @@ interface TenantContext {
   streamClient: StreamClient;
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
+  eventSources?: EventSourceCatalog;
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   isShuttingDown: () => boolean;
 }
 
@@ -4499,4 +4518,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/dist/index.d.ts

@@ -189,7 +189,7 @@ import * as drizzle_orm_pg_core237 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core238 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core239 from "drizzle-orm/pg-core";
 import { JsonWebKey, KeyObject } from "node:crypto";
-import { EntityTags, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
+import { EntityTags, EventSourceBucket, EventSourceContract, EventSourceContract as EventSourceContract$1, EventSourceFilter, EventSourceSubscription, EventSourceSubscription as EventSourceSubscription$1, EventSourceSubscriptionInput, SubscriptionLifetime, WebhookNotification, WebhookSignatureVerifierConfig } from "@electric-ax/agents-runtime";
 import { MaybePromise } from "@durable-streams/client";
 import "@sinclair/typebox";
 import { AutoRouterType, IRequest } from "itty-router";
@@ -3442,6 +3442,7 @@ interface TypedSpawnRequest {
     debounceMs?: number;
     timeoutMs?: number;
     includeResponse?: boolean;
+    manifestKey?: string;
   };
 }
 interface SendRequest {
@@ -4206,6 +4207,18 @@ declare class EntityManager {
   }): Promise<{
     txid: string;
   }>;
+  upsertEventSourceSubscription(entityUrl: string, req: {
+    subscription: EventSourceSubscription$1;
+    manifest: Record<string, unknown>;
+  }): Promise<{
+    txid: string;
+    subscription: EventSourceSubscription$1;
+  }>;
+  deleteEventSourceSubscription(entityUrl: string, req: {
+    id: string;
+  }): Promise<{
+    txid: string;
+  }>;
   /**
    * Register a wake subscription from a subscriber to a source entity.
    */
@@ -4455,6 +4468,10 @@ declare function webhookSigningMetadata(signer: WebhookSigner, streamRootUrl: st
 
 //#endregion
 //#region src/routing/context.d.ts
+interface EventSourceCatalog {
+  listEventSources: () => Array<EventSourceContract$1> | Promise<Array<EventSourceContract$1>>;
+  getEventSource: (sourceKey: string) => EventSourceContract$1 | undefined | Promise<EventSourceContract$1 | undefined>;
+}
 /**
  * Per-request tenant context passed through every router and handler.
  *
@@ -4481,6 +4498,8 @@ interface TenantContext {
   streamClient: StreamClient;
   runtime: ElectricAgentsTenantRuntime;
   entityBridgeManager: EntityBridgeCoordinator;
+  eventSources?: EventSourceCatalog;
+  ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void;
   isShuttingDown: () => boolean;
 }
 
@@ -4500,4 +4519,4 @@ declare class UnregisteredTenantError extends Error {
 declare function isUnregisteredTenantError(error: unknown): error is UnregisteredTenantError;
 
 //#endregion
-export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };
+export { AgentsHost, AgentsHostOptions, AgentsHostTenantConfig, AgentsHostTenantRuntime, AuthenticateRequest, ConsumerClaim, DEFAULT_TENANT_ID, DispatchPolicy, DispatchTarget, DrizzleDB, DurableStreamsBearerProvider, DurableStreamsRoutingAdapter, DurableStreamsRoutingInput, Ed25519WebhookSignerOptions, ElectricAgentsEntity, ElectricAgentsEntityRow, ElectricAgentsEntityType, ElectricAgentsRunner, ElectricAgentsUser, EntityBridgeCoordinator, EntityDispatchState, EntityListFilter, EntitySignal, EntityStatus, EventSourceBucket, EventSourceCatalog, EventSourceContract, EventSourceFilter, EventSourceSubscription, EventSourceSubscriptionInput, GlobalRoutes, PgClient, Principal, PrincipalKind, PublicElectricAgentsEntity, PublicWakeNotification, RegisterEntityTypeRequest, RegisterRunnerRequest, RequestPrincipal, RunnerAdminStatus, RunnerHeartbeatRequest, RunnerKind, RunnerLiveness, SendRequest, SignalRequest, SignalResponse, SourceStreamOffset, StreamClient, StreamClientOptions, SubscriptionClaimResponse, SubscriptionCreateInput, SubscriptionLifetime, SubscriptionResponse, SubscriptionStreamInfo, TenantContext, TypedSpawnRequest, UnregisteredTenantError, WakeNotificationRow, WebhookJwks, WebhookPublicJwk, WebhookSigner, WebhookSigningKeyInput, WebhookSigningMetadata, assertEntitySignal, assertEntityStatus, createDb, createEd25519WebhookSigner, expectedSignalStatus, getDefaultWebhookSigner, globalRouter, isTerminalEntityStatus, isUnregisteredTenantError, pathPrefixedSingleTenantDurableStreamsRoutingAdapter, rejectsNormalWrites, runMigrations, streamRootDurableStreamsRoutingAdapter, tenantRootDurableStreamsRoutingAdapter, toPublicEntity, webhookSigningMetadata };

package/dist/index.js

@@ -8,7 +8,7 @@ import postgres from "postgres";
 import { and, desc, eq, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from "node:crypto";
-import { appendPathToUrl, assertTags, buildTagsIndex, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
@@ -2624,6 +2624,10 @@ function extractManifestSourceUrl(manifest) {
 		}
 		if (manifest.sourceType === `entities`) return typeof manifest.sourceRef === `string` ? `/_entities/${manifest.sourceRef}` : void 0;
 		if (manifest.sourceType === `db`) return typeof manifest.sourceRef === `string` ? getSharedStateStreamPath(manifest.sourceRef) : void 0;
+		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 : void 0);
+		}
 		return void 0;
 	}
 	if (manifest.kind === `shared-state`) return typeof manifest.id === `string` ? getSharedStateStreamPath(manifest.id) : void 0;
@@ -2910,7 +2914,8 @@ var EntityManager = class {
 			debounceMs: req.wake.debounceMs,
 			timeoutMs: req.wake.timeoutMs,
 			oneShot: false,
-			includeResponse: req.wake.includeResponse
+			includeResponse: req.wake.includeResponse,
+			manifestKey: req.wake.manifestKey
 		});
 		const contentType = `application/json`;
 		const createdEvent = entityStateSchema.entityCreated.insert({
@@ -3804,6 +3809,35 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
+	async upsertEventSourceSubscription(entityUrl, req) {
+		const manifestKey = req.subscription.manifestKey;
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
+		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, req) {
+		const manifestKey = eventSourceSubscriptionManifestKey(req.id);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
 	/**
 	* Register a wake subscription from a subscriber to a source entity.
 	*/
@@ -6684,7 +6718,8 @@ const spawnBodySchema = Type.Object({
 		condition: wakeConditionSchema,
 		debounceMs: Type.Optional(Type.Number()),
 		timeoutMs: Type.Optional(Type.Number()),
-		includeResponse: Type.Optional(Type.Boolean())
+		includeResponse: Type.Optional(Type.Boolean()),
+		manifestKey: Type.Optional(Type.String())
 	}))
 });
 const sendBodySchema = Type.Object({
@@ -6750,6 +6785,22 @@ const scheduleBodySchema = Type.Union([Type.Object({
 	messageType: Type.Optional(Type.String()),
 	from: Type.Optional(Type.String())
 })]);
+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) });
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
@@ -6767,6 +6818,8 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, removeTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, 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, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -6873,6 +6926,47 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return json(result);
 }
+async function upsertEventSourceSubscription(request, ctx) {
+	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(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;
+	try {
+		resolved = resolveEventSourceSubscription({
+			contract: source,
+			entityUrl,
+			request: {
+				...parsed,
+				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, ctx) {
+	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, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `tagged`);
 	if (principalMutationError) return principalMutationError;
@@ -7587,6 +7681,7 @@ const callbackForwardBodySchema = Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = Router({ base: `/_electric` });
 internalRouter.get(`/health`, () => json({ status: `ok` }));
+internalRouter.get(`/event-sources`, listEventSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/webhook-forward/:subscriptionId`, webhookForward);
 internalRouter.post(`/callback-forward/:consumerId`, callbackForward);
@@ -7690,6 +7785,13 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return status(204);
 }
+async function listEventSources(_request, ctx) {
+	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
+	return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+}
+function isAgentVisibleEventSource(source) {
+	return source.agentVisible === true && source.status === `active`;
+}
 async function webhookForward(request, ctx) {
 	const subscriptionId = routeParam(request, `subscriptionId`);
 	const rootSpan = getRequestSpan(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -39,7 +39,7 @@
     "@durable-streams/client": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/client@5d5c217",
     "@durable-streams/server": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/server@eac712f",
     "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@5d5c217",
-    "@electric-sql/client": "^1.5.18",
+    "@electric-sql/client": "^1.5.19",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@opentelemetry/api": "^1.9.1",
     "@sinclair/typebox": "^0.34.48",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.2"
+    "@electric-ax/agents-runtime": "0.3.4"
   },
   "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.8",
     "@electric-ax/agents-server-conformance-tests": "0.1.7",
-    "@electric-ax/agents": "0.4.6",
-    "@electric-ax/agents-server-ui": "0.4.7"
+    "@electric-ax/agents-server-ui": "0.4.9"
   },
   "files": [
     "dist",

package/src/electric-agents-types.ts

@@ -400,6 +400,7 @@ export interface TypedSpawnRequest {
     debounceMs?: number
     timeoutMs?: number
     includeResponse?: boolean
+    manifestKey?: string
   }
 }
 

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,
       })
     }
 
@@ -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
   // ==========================================================================

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/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,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),
 })
@@ -180,6 +204,9 @@ 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<
@@ -256,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,
@@ -467,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

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

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 }