@electric-ax/agents-server 0.4.2 → 0.4.4

package/dist/entrypoint.js

@@ -43,6 +43,7 @@ __export(schema_exports, {
 	entityDispatchState: () => entityDispatchState,
 	entityManifestSources: () => entityManifestSources,
 	entityTypes: () => entityTypes,
+	runnerRuntimeDiagnostics: () => runnerRuntimeDiagnostics,
 	runners: () => runners,
 	scheduledTasks: () => scheduledTasks,
 	subscriptionWebhooks: () => subscriptionWebhooks,
@@ -111,25 +112,35 @@ const users = pgTable(`users`, {
 const runners = pgTable(`runners`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	id: text(`id`).notNull(),
-	ownerUserId: text(`owner_user_id`).notNull(),
+	ownerPrincipal: text(`owner_principal`).notNull(),
 	label: text(`label`).notNull(),
 	kind: text(`kind`).notNull().default(`local`),
 	adminStatus: text(`admin_status`).notNull().default(`enabled`),
 	wakeStream: text(`wake_stream`).notNull(),
-	wakeStreamOffset: text(`wake_stream_offset`),
-	lastSeenAt: timestamp(`last_seen_at`, { withTimezone: true }),
-	livenessLeaseExpiresAt: timestamp(`liveness_lease_expires_at`, { withTimezone: true }),
 	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
 	primaryKey({ columns: [table.tenantId, table.id] }),
 	unique(`uq_runners_wake_stream`).on(table.tenantId, table.wakeStream),
-	index(`idx_runners_owner_user_id`).on(table.tenantId, table.ownerUserId),
+	index(`idx_runners_owner_principal`).on(table.tenantId, table.ownerPrincipal),
 	index(`idx_runners_admin_status`).on(table.tenantId, table.adminStatus),
-	index(`idx_runners_liveness_lease_expires_at`).on(table.tenantId, table.livenessLeaseExpiresAt),
 	check(`chk_runners_kind`, sql`${table.kind} IN ('local', 'cloud-worker', 'sandbox', 'ci', 'server')`),
 	check(`chk_runners_admin_status`, sql`${table.adminStatus} IN ('enabled', 'disabled')`)
 ]);
+const runnerRuntimeDiagnostics = pgTable(`runner_runtime_diagnostics`, {
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	runnerId: text(`runner_id`).notNull(),
+	ownerPrincipal: text(`owner_principal`).notNull(),
+	wakeStreamOffset: text(`wake_stream_offset`),
+	lastSeenAt: timestamp(`last_seen_at`, { withTimezone: true }).notNull(),
+	livenessLeaseExpiresAt: timestamp(`liveness_lease_expires_at`, { withTimezone: true }).notNull(),
+	diagnostics: jsonb(`diagnostics`),
+	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	primaryKey({ columns: [table.tenantId, table.runnerId] }),
+	index(`idx_runner_runtime_diagnostics_owner`).on(table.tenantId, table.ownerPrincipal),
+	index(`idx_runner_runtime_diagnostics_liveness`).on(table.tenantId, table.livenessLeaseExpiresAt)
+]);
 const entityDispatchState = pgTable(`entity_dispatch_state`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	entityUrl: text(`entity_url`).notNull(),
@@ -331,76 +342,6 @@ async function runMigrations(postgresUrl) {
 	await migrationClient.end();
 }
 
-//#endregion
-//#region src/routing/tenant-stream-paths.ts
-function withoutLeadingSlash(path$1) {
-	return path$1.replace(/^\/+/, ``);
-}
-function withLeadingSlash(path$1) {
-	return path$1.startsWith(`/`) ? path$1 : `/${path$1}`;
-}
-function prefixTenantStreamPath(path$1, tenantId) {
-	const normalized = withoutLeadingSlash(path$1);
-	if (!normalized || normalized === tenantId) return tenantId;
-	if (normalized.startsWith(`${tenantId}/`)) return normalized;
-	return `${tenantId}/${normalized}`;
-}
-function stripTenantStreamPrefix(path$1, tenantId) {
-	const normalized = withoutLeadingSlash(path$1);
-	if (normalized === tenantId) return ``;
-	if (normalized.startsWith(`${tenantId}/`)) return normalized.slice(tenantId.length + 1);
-	return normalized;
-}
-
-//#endregion
-//#region src/routing/durable-streams-routing-adapter.ts
-function appendSearch(target, source) {
-	target.search = source.search;
-	return target;
-}
-function removeServiceQuery(target) {
-	target.searchParams.delete(`service`);
-	return target;
-}
-function logicalStreamPathFromRequest(requestUrl, serviceId) {
-	const incomingUrl = new URL(requestUrl, `http://localhost`);
-	const segments = incomingUrl.pathname.split(`/`).filter(Boolean);
-	if (segments[0] === `v1` && segments[1] === `stream`) return {
-		incomingUrl,
-		streamPath: segments.length > 2 ? `/${segments.slice(3).join(`/`)}` : `/`
-	};
-	return {
-		incomingUrl,
-		streamPath: incomingUrl.pathname || `/${serviceId}`
-	};
-}
-function backendStreamUrl(input, backendStreamPath) {
-	const path$1 = backendStreamPath.replace(/^\/+/, ``);
-	const target = new URL(`/v1/stream/${path$1}`, input.durableStreamsUrl);
-	return target;
-}
-function streamMetaUrlWithoutService(input) {
-	const incomingUrl = new URL(input.requestUrl, `http://localhost`);
-	return removeServiceQuery(appendSearch(new URL(incomingUrl.pathname, input.durableStreamsUrl), incomingUrl));
-}
-const pathPrefixedSingleTenantDurableStreamsRoutingAdapter = {
-	streamUrl(input) {
-		const { incomingUrl, streamPath } = logicalStreamPathFromRequest(input.requestUrl, input.serviceId);
-		const target = backendStreamUrl(input, prefixTenantStreamPath(streamPath, input.serviceId));
-		return removeServiceQuery(appendSearch(target, incomingUrl));
-	},
-	streamMetaUrl: streamMetaUrlWithoutService,
-	toBackendStreamPath(serviceId, streamPath) {
-		return prefixTenantStreamPath(streamPath, serviceId);
-	},
-	toRuntimeStreamPath(serviceId, streamPath) {
-		return stripTenantStreamPrefix(streamPath, serviceId);
-	}
-};
-function resolveDurableStreamsRoutingAdapter(adapter) {
-	return adapter ?? pathPrefixedSingleTenantDurableStreamsRoutingAdapter;
-}
-
 //#endregion
 //#region src/electric-agents-http.ts
 function apiError(status$1, code, message, details) {
@@ -501,6 +442,38 @@ function electricUrlWithPath(electricUrl, path$1) {
 	return target;
 }
 
+//#endregion
+//#region src/routing/durable-streams-routing-adapter.ts
+function appendSearch(target, source) {
+	source.searchParams.forEach((value, key) => {
+		if (key !== `service`) target.searchParams.append(key, value);
+	});
+	return target;
+}
+function withoutTrailingSlash(pathname) {
+	return pathname.replace(/\/+$/, ``) || `/`;
+}
+function appendRequestPathToStreamRoot(input) {
+	const incomingUrl = new URL(input.requestUrl, `http://localhost`);
+	const path$1 = incomingUrl.pathname.replace(/^\/+/, ``);
+	const target = new URL(input.durableStreamsUrl);
+	target.pathname = path$1 ? `${withoutTrailingSlash(target.pathname)}/${path$1}` : withoutTrailingSlash(target.pathname);
+	return appendSearch(target, incomingUrl);
+}
+const streamRootDurableStreamsRoutingAdapter = {
+	streamUrl: appendRequestPathToStreamRoot,
+	controlUrl: appendRequestPathToStreamRoot,
+	toBackendStreamPath(_serviceId, streamPath) {
+		return streamPath.replace(/^\/+/, ``);
+	},
+	toRuntimeStreamPath(_serviceId, streamPath) {
+		return streamPath.replace(/^\/+/, ``);
+	}
+};
+function resolveDurableStreamsRoutingAdapter(adapter, _durableStreamsUrl) {
+	return adapter ?? streamRootDurableStreamsRoutingAdapter;
+}
+
 //#endregion
 //#region src/tracing.ts
 const tracer = trace.getTracer(`agent-server`);
@@ -575,16 +548,17 @@ async function applyDurableStreamsBearer(headers, bearer, opts = {}) {
 	const value = await resolveDurableStreamsBearer(bearer);
 	if (value) headers.set(`authorization`, value);
 }
+function appendPathToBaseUrl(baseUrl, path$1) {
+	const url = new URL(baseUrl);
+	const basePath = url.pathname.replace(/\/+$/, ``);
+	const childPath = path$1.replace(/^\/+/, ``);
+	url.pathname = childPath ? `${basePath === `/` ? `` : basePath}/${childPath}` : basePath || `/`;
+	return url.toString().replace(/\/+$/, ``);
+}
 function durableStreamsBearerHeaders(bearer) {
 	if (!bearer) return void 0;
 	return { authorization: async () => await resolveDurableStreamsBearer(bearer) ?? `` };
 }
-function durableStreamsServiceUrl(baseUrl, serviceId) {
-	const url = new URL(baseUrl);
-	if (/^\/v1\/stream\/[^/]+\/?$/.test(url.pathname)) return baseUrl.replace(/\/+$/, ``);
-	const base = baseUrl.replace(/\/+$/, ``);
-	return `${base}/v1/stream/${encodeURIComponent(serviceId)}`;
-}
 function isNotFoundError(err) {
 	return err instanceof DurableStreamError && err.code === ErrCodeNotFound || err instanceof FetchError && err.status === 404;
 }
@@ -606,7 +580,7 @@ var StreamClient = class {
 		this.options = options;
 	}
 	streamUrl(path$1) {
-		return `${this.baseUrl}${path$1}`;
+		return appendPathToBaseUrl(this.baseUrl, path$1);
 	}
 	streamHeaders() {
 		return durableStreamsBearerHeaders(this.options.bearer);
@@ -616,35 +590,14 @@ var StreamClient = class {
 		await applyDurableStreamsBearer(headers, this.options.bearer, { overwrite: opts.overwriteBearer });
 		return headers;
 	}
-	subscriptionServiceId() {
-		const url = new URL(this.baseUrl);
-		const match = /^(.*)\/v1\/stream\/([^/]+)\/?$/.exec(url.pathname);
-		return match ? decodeURIComponent(match[2]) : null;
-	}
 	backendSubscriptionPath(path$1) {
-		const normalized = normalizeSubscriptionPath(path$1);
-		const serviceId = this.subscriptionServiceId();
-		if (!serviceId) return normalized;
-		if (normalized === serviceId || normalized.startsWith(`${serviceId}/`)) return normalized;
-		return `${serviceId}/${normalized}`;
+		return normalizeSubscriptionPath(path$1);
 	}
 	runtimeSubscriptionPath(path$1) {
-		const normalized = normalizeSubscriptionPath(path$1);
-		const serviceId = this.subscriptionServiceId();
-		if (!serviceId) return normalized;
-		return normalized.startsWith(`${serviceId}/`) ? normalized.slice(serviceId.length + 1) : normalized;
+		return normalizeSubscriptionPath(path$1);
 	}
 	subscriptionUrl(subscriptionId) {
-		const url = new URL(this.baseUrl);
-		const match = /^(.*)\/v1\/stream\/([^/]+)\/?$/.exec(url.pathname);
-		if (match) {
-			const [, prefix = ``, serviceId] = match;
-			url.pathname = `${prefix}/v1/stream-meta/subscriptions/${encodeURIComponent(subscriptionId)}`;
-			url.searchParams.set(`service`, decodeURIComponent(serviceId));
-			return url.toString();
-		}
-		url.pathname = `${url.pathname.replace(/\/+$/, ``)}/v1/stream-meta/subscriptions/${encodeURIComponent(subscriptionId)}`;
-		return url.toString();
+		return appendPathToBaseUrl(this.baseUrl, `/__ds/subscriptions/${encodeURIComponent(subscriptionId)}`);
 	}
 	subscriptionChildUrl(subscriptionId, ...segments) {
 		const url = new URL(this.subscriptionUrl(subscriptionId));
@@ -673,7 +626,7 @@ var StreamClient = class {
 			});
 			const headers = {
 				"content-type": `application/json`,
-				"Stream-Forked-From": sourcePath
+				"Stream-Forked-From": new URL(this.streamUrl(sourcePath)).pathname
 			};
 			injectTraceHeaders(headers);
 			const response = await fetch(this.streamUrl(path$1), {
@@ -1026,15 +979,6 @@ var StreamClient = class {
 		if (!text$1.trim()) return {};
 		return this.subscriptionResponseBody(JSON.parse(text$1));
 	}
-	async getConsumerState(consumerId) {
-		const res = await fetch(`${this.baseUrl}/consumers/${encodeURIComponent(consumerId)}`, {
-			method: `GET`,
-			headers: await this.requestHeaders()
-		});
-		if (res.status === 404) return null;
-		if (!res.ok) throw new Error(`Consumer query failed: ${res.status} ${await res.text()}`);
-		return res.json();
-	}
 };
 
 //#endregion
@@ -1097,8 +1041,11 @@ function buildElectricProxyTarget(options) {
 		target.searchParams.set(`columns`, `"tenant_id","name","description","creation_schema","inbox_schemas","state_schemas","serve_endpoint","default_dispatch_policy","revision","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId);
 	} else if (table === `runners`) {
-		target.searchParams.set(`columns`, `"tenant_id","id","owner_user_id","label","kind","admin_status","wake_stream","wake_stream_offset","last_seen_at","liveness_lease_expires_at","created_at","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		target.searchParams.set(`columns`, `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","created_at","updated_at"`);
+		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral$2(options.principalUrl ?? ``)}`]);
+	} else if (table === `runner_runtime_diagnostics`) {
+		target.searchParams.set(`columns`, `"tenant_id","runner_id","owner_principal","wake_stream_offset","last_seen_at","liveness_lease_expires_at","diagnostics","updated_at"`);
+		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral$2(options.principalUrl ?? ``)}`]);
 	} else if (table === `entity_dispatch_state`) {
 		target.searchParams.set(`columns`, `"tenant_id","entity_url","pending_source_streams","pending_reason","pending_since","outstanding_wake_id","outstanding_wake_target","outstanding_wake_created_at","active_consumer_id","active_runner_id","active_epoch","active_claimed_at","active_lease_expires_at","last_wake_id","last_claimed_at","last_released_at","last_completed_at","last_error","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId);
@@ -1112,13 +1059,13 @@ function buildElectricProxyTarget(options) {
 	return target;
 }
 async function forwardFetchRequest(options) {
-	const routingAdapter = resolveDurableStreamsRoutingAdapter(options.durableStreamsRouting);
+	const routingAdapter = resolveDurableStreamsRoutingAdapter(options.durableStreamsRouting, options.durableStreamsUrl);
 	const routingInput = {
 		durableStreamsUrl: options.durableStreamsUrl,
 		serviceId: options.serviceId,
 		requestUrl: options.request.url
 	};
-	const upstreamUrl = options.route === `stream-meta` ? routingAdapter.streamMetaUrl(routingInput) : routingAdapter.streamUrl(routingInput);
+	const upstreamUrl = options.route === `control` ? routingAdapter.controlUrl(routingInput) : routingAdapter.streamUrl(routingInput);
 	const headers = new Headers(options.request.headers);
 	if (options.durableStreamsBearerMode !== `none`) await applyDurableStreamsBearer(headers, options.durableStreamsBearer, { overwrite: options.durableStreamsBearerMode !== `if-missing` });
 	const init = {
@@ -1144,8 +1091,8 @@ function decodeJsonObject(body) {
 	} catch {}
 	return null;
 }
-function applyTenantShapeWhere(target, tenantId) {
-	const tenantWhere = `tenant_id = ${sqlStringLiteral$2(tenantId)}`;
+function applyTenantShapeWhere(target, tenantId, extraConditions = []) {
+	const tenantWhere = [`tenant_id = ${sqlStringLiteral$2(tenantId)}`, ...extraConditions].join(` AND `);
 	const existingWhere = target.searchParams.get(`where`);
 	target.searchParams.set(`where`, existingWhere ? `${tenantWhere} AND (${existingWhere})` : tenantWhere);
 }
@@ -1434,8 +1381,21 @@ function isLoopbackHostname(hostname) {
 //#endregion
 //#region src/routing/durable-streams-router.ts
 const subscriptionProxyBodySchema = Type.Object({ webhook: Type.Optional(Type.Object({ url: Type.String() }, { additionalProperties: true })) }, { additionalProperties: true });
+const subscriptionControlActions = [
+	`callback`,
+	`claim`,
+	`ack`,
+	`release`
+];
 const durableStreamsRouter = Router();
-durableStreamsRouter.all(`/v1/stream-meta/subscriptions/*`, subscriptionProxy);
+durableStreamsRouter.put(`/__ds/subscriptions/:subscriptionId`, putSubscriptionBase);
+durableStreamsRouter.get(`/__ds/subscriptions/:subscriptionId`, getSubscriptionBase);
+durableStreamsRouter.delete(`/__ds/subscriptions/:subscriptionId`, deleteSubscriptionBase);
+durableStreamsRouter.post(`/__ds/subscriptions/:subscriptionId/streams`, postSubscriptionStreams);
+durableStreamsRouter.delete(`/__ds/subscriptions/:subscriptionId/streams/:streamPath+`, deleteSubscriptionStream);
+for (const action of subscriptionControlActions) durableStreamsRouter.post(`/__ds/subscriptions/:subscriptionId/${action}`, subscriptionAction(action));
+durableStreamsRouter.all(`/__ds`, controlPassThrough);
+durableStreamsRouter.all(`/__ds/*`, controlPassThrough);
 durableStreamsRouter.post(`*`, streamAppend);
 durableStreamsRouter.all(`*`, proxyPassThrough);
 function bodyFromBytes$1(body) {
@@ -1448,7 +1408,7 @@ function responseFromUpstream$1(response, body) {
 		headers: responseHeaders(response)
 	});
 }
-async function forwardToDurableStreams(ctx, request, body, route = `stream`, urlOverride) {
+async function forwardToDurableStreams(ctx, request, body, route = `stream`, urlOverride, durableStreamsBearerMode = `overwrite`) {
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
 	let requestBody = body;
@@ -1462,24 +1422,13 @@ async function forwardToDurableStreams(ctx, request, body, route = `stream`, url
 		body: requestBody,
 		durableStreamsUrl: ctx.durableStreamsUrl,
 		durableStreamsBearer: ctx.durableStreamsBearer,
-		durableStreamsBearerMode: usesSubscriptionScopedBearer(urlOverride ?? request.url) ? `if-missing` : `overwrite`,
+		durableStreamsBearerMode,
 		durableStreamsRouting: ctx.durableStreamsRouting,
 		serviceId: ctx.service,
 		dispatcher: ctx.durableStreamsDispatcher,
 		route
 	});
 }
-function subscriptionIdFromPath(pathname) {
-	const match = /^\/v1\/stream-meta\/subscriptions\/([^/]+)(?:\/.*)?$/.exec(pathname);
-	return match ? decodeURIComponent(match[1]) : null;
-}
-function isSubscriptionBasePath(pathname) {
-	return /^\/v1\/stream-meta\/subscriptions\/[^/]+\/?$/.test(pathname);
-}
-function usesSubscriptionScopedBearer(requestUrl) {
-	const pathname = new URL(requestUrl, `http://localhost`).pathname;
-	return /^\/v1\/stream-meta\/subscriptions\/[^/]+\/(?:ack|release|callback)\/?$/.test(pathname);
-}
 function rewriteSubscriptionBodyForBackend(payload, service, routingAdapter) {
 	if (typeof payload.pattern === `string`) payload.pattern = routingAdapter.toBackendStreamPath(service, payload.pattern);
 	if (Array.isArray(payload.streams)) payload.streams = payload.streams.map((stream) => typeof stream === `string` ? routingAdapter.toBackendStreamPath(service, stream) : stream);
@@ -1524,44 +1473,50 @@ function decodeJson(bytes) {
 		return null;
 	}
 }
-function rewriteSubscriptionStreamPathInUrl(requestUrl, service, routingAdapter) {
-	const match = /^(\/v1\/stream-meta\/subscriptions\/[^/]+\/streams\/)(.+)$/.exec(requestUrl.pathname);
-	if (!match) return requestUrl.toString();
-	const [, prefix, encodedPath] = match;
-	const streamPath = decodeURIComponent(encodedPath);
-	requestUrl.pathname = `${prefix}${encodeURIComponent(routingAdapter.toBackendStreamPath(service, streamPath))}`;
-	return requestUrl.toString();
+function routeParam$2(request, name) {
+	const value = request.params[name];
+	const raw = Array.isArray(value) ? value[0] : value;
+	return decodeURIComponent(raw ?? ``);
+}
+function subscriptionRoutingAdapter(ctx) {
+	return resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting, ctx.durableStreamsUrl);
 }
-async function subscriptionProxy(request, ctx) {
-	const url = new URL(request.url);
-	const subscriptionId = subscriptionIdFromPath(url.pathname);
-	if (!subscriptionId) return void 0;
-	const routingAdapter = resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting);
-	let requestBody;
+async function rewriteSubscriptionRequestBody(request, ctx, subscriptionId, routingAdapter) {
+	const body = await readRequestBody(request);
+	if (body.length === 0) return {
+		ok: true,
+		body,
+		targetWebhookUrl: null
+	};
+	const validation = validateBody(subscriptionProxyBodySchema, body);
+	if (!validation.ok) return {
+		ok: false,
+		response: validation.response
+	};
+	const payload = validation.value;
 	let targetWebhookUrl = null;
-	let requestUrl = request.url;
-	if ([`PUT`, `POST`].includes(request.method.toUpperCase())) {
-		requestBody = await readRequestBody(request);
-		if (requestBody.length > 0) {
-			const validation = validateBody(subscriptionProxyBodySchema, requestBody);
-			if (!validation.ok) return validation.response;
-			const payload = validation.value;
-			if (payload.webhook?.url !== void 0) {
-				targetWebhookUrl = rewriteLoopbackWebhookUrl(payload.webhook.url) ?? null;
-				payload.webhook.url = appendPathToUrl(ctx.publicUrl, `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`);
-			}
-			rewriteSubscriptionBodyForBackend(payload, ctx.service, routingAdapter);
-			requestBody = new TextEncoder().encode(JSON.stringify(payload));
-		}
+	if (payload.webhook?.url !== void 0) {
+		targetWebhookUrl = rewriteLoopbackWebhookUrl(payload.webhook.url) ?? null;
+		payload.webhook.url = appendPathToUrl(ctx.publicUrl, `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`);
 	}
-	if (request.method.toUpperCase() === `DELETE` && /\/streams\/.+$/.test(url.pathname)) requestUrl = rewriteSubscriptionStreamPathInUrl(url, ctx.service, routingAdapter);
-	const upstream = await forwardToDurableStreams(ctx, request, requestBody, `stream-meta`, requestUrl);
+	rewriteSubscriptionBodyForBackend(payload, ctx.service, routingAdapter);
+	return {
+		ok: true,
+		body: new TextEncoder().encode(JSON.stringify(payload)),
+		targetWebhookUrl
+	};
+}
+async function forwardSubscriptionRequest(request, ctx, routingAdapter, opts = {}) {
+	const upstream = await forwardToDurableStreams(ctx, request, opts.body, `control`, opts.requestUrl, opts.bearerMode ?? `overwrite`);
 	let responseBytes = upstream.body ? new Uint8Array(await upstream.arrayBuffer()) : new Uint8Array();
 	responseBytes = rewriteSubscriptionResponseForClient(responseBytes, upstream, ctx.service, routingAdapter);
-	const response = responseFromUpstream$1(upstream, responseBytes);
-	if (!upstream.ok) return response;
-	if (request.method.toUpperCase() === `DELETE` && isSubscriptionBasePath(url.pathname)) await ctx.pgDb.delete(subscriptionWebhooks).where(and(eq(subscriptionWebhooks.tenantId, ctx.service), eq(subscriptionWebhooks.subscriptionId, subscriptionId)));
-	else if (targetWebhookUrl) await ctx.pgDb.insert(subscriptionWebhooks).values({
+	return {
+		upstream,
+		response: responseFromUpstream$1(upstream, responseBytes)
+	};
+}
+async function upsertSubscriptionWebhook(ctx, subscriptionId, targetWebhookUrl) {
+	await ctx.pgDb.insert(subscriptionWebhooks).values({
 		tenantId: ctx.service,
 		subscriptionId,
 		webhookUrl: targetWebhookUrl
@@ -1569,8 +1524,64 @@ async function subscriptionProxy(request, ctx) {
 		target: [subscriptionWebhooks.tenantId, subscriptionWebhooks.subscriptionId],
 		set: { webhookUrl: targetWebhookUrl }
 	});
+}
+async function deleteSubscriptionWebhook(ctx, subscriptionId) {
+	await ctx.pgDb.delete(subscriptionWebhooks).where(and(eq(subscriptionWebhooks.tenantId, ctx.service), eq(subscriptionWebhooks.subscriptionId, subscriptionId)));
+}
+function rewriteSubscriptionStreamPathInUrl(requestUrl, service, routingAdapter, streamPath) {
+	const prefix = requestUrl.pathname.slice(0, requestUrl.pathname.indexOf(`/streams/`) + `/streams/`.length);
+	requestUrl.pathname = `${prefix}${encodeURIComponent(routingAdapter.toBackendStreamPath(service, streamPath))}`;
+	return requestUrl.toString();
+}
+async function putSubscriptionBase(request, ctx) {
+	const subscriptionId = routeParam$2(request, `subscriptionId`);
+	const routingAdapter = subscriptionRoutingAdapter(ctx);
+	const rewrite = await rewriteSubscriptionRequestBody(request, ctx, subscriptionId, routingAdapter);
+	if (!rewrite.ok) return rewrite.response;
+	const { upstream, response } = await forwardSubscriptionRequest(request, ctx, routingAdapter, { body: rewrite.body });
+	if (upstream.ok && rewrite.targetWebhookUrl) await upsertSubscriptionWebhook(ctx, subscriptionId, rewrite.targetWebhookUrl);
 	return response;
 }
+async function getSubscriptionBase(request, ctx) {
+	const routingAdapter = subscriptionRoutingAdapter(ctx);
+	return (await forwardSubscriptionRequest(request, ctx, routingAdapter)).response;
+}
+async function deleteSubscriptionBase(request, ctx) {
+	const subscriptionId = routeParam$2(request, `subscriptionId`);
+	const routingAdapter = subscriptionRoutingAdapter(ctx);
+	const { upstream, response } = await forwardSubscriptionRequest(request, ctx, routingAdapter);
+	if (upstream.ok) await deleteSubscriptionWebhook(ctx, subscriptionId);
+	return response;
+}
+async function postSubscriptionStreams(request, ctx) {
+	const subscriptionId = routeParam$2(request, `subscriptionId`);
+	const routingAdapter = subscriptionRoutingAdapter(ctx);
+	const rewrite = await rewriteSubscriptionRequestBody(request, ctx, subscriptionId, routingAdapter);
+	if (!rewrite.ok) return rewrite.response;
+	return (await forwardSubscriptionRequest(request, ctx, routingAdapter, { body: rewrite.body })).response;
+}
+async function deleteSubscriptionStream(request, ctx) {
+	const routingAdapter = subscriptionRoutingAdapter(ctx);
+	const requestUrl = rewriteSubscriptionStreamPathInUrl(new URL(request.url), ctx.service, routingAdapter, routeParam$2(request, `streamPath`));
+	return (await forwardSubscriptionRequest(request, ctx, routingAdapter, { requestUrl })).response;
+}
+function subscriptionAction(action) {
+	return async (request, ctx) => {
+		const subscriptionId = routeParam$2(request, `subscriptionId`);
+		const routingAdapter = subscriptionRoutingAdapter(ctx);
+		const rewrite = await rewriteSubscriptionRequestBody(request, ctx, subscriptionId, routingAdapter);
+		if (!rewrite.ok) return rewrite.response;
+		const bearerMode = action === `ack` || action === `release` || action === `callback` ? `if-missing` : `overwrite`;
+		return (await forwardSubscriptionRequest(request, ctx, routingAdapter, {
+			body: rewrite.body,
+			bearerMode
+		})).response;
+	};
+}
+async function controlPassThrough(request, ctx) {
+	const upstream = await forwardToDurableStreams(ctx, request, void 0, `control`);
+	return responseFromUpstream$1(upstream);
+}
 async function streamAppend(request, ctx) {
 	return await electricAgentsStreamAppendRouter.fetch(createStreamAppendRouteRequest(request), ctx.runtime, (req, body) => forwardFetchRequest({
 		request: {
@@ -1591,10 +1602,9 @@ async function proxyPassThrough(request, ctx) {
 	const upstream = await forwardToDurableStreams(ctx, request);
 	const streamPath = new URL(request.url).pathname;
 	const method = request.method.toUpperCase();
-	const isControlPath = streamPath.startsWith(`/v1/stream-meta/`);
-	const endTrackedRead = method === `GET` && !isControlPath ? await ctx.entityBridgeManager.beginClientRead(streamPath) : null;
+	const endTrackedRead = method === `GET` ? await ctx.entityBridgeManager.beginClientRead(streamPath) : null;
 	try {
-		if (method === `HEAD` && !isControlPath) await ctx.entityBridgeManager.touchByStreamPath(streamPath);
+		if (method === `HEAD`) await ctx.entityBridgeManager.touchByStreamPath(streamPath);
 		return responseFromUpstream$1(upstream);
 	} finally {
 		await endTrackedRead?.();
@@ -1625,7 +1635,8 @@ async function proxyElectric(request, ctx) {
 		incomingUrl: new URL(request.url),
 		electricUrl: ctx.electricUrl,
 		electricSecret: ctx.electricSecret,
-		tenantId: ctx.service
+		tenantId: ctx.service,
+		principalUrl: ctx.principal.url
 	});
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
@@ -1656,7 +1667,7 @@ const PRINCIPAL_KINDS = new Set([
 ]);
 function parsePrincipalKey(input) {
 	const colon = input.indexOf(`:`);
-	if (colon <= 0) throw new Error(`Invalid principal key`);
+	if (colon <= 0) throw new Error(`Invalid principal identifier`);
 	const kind = input.slice(0, colon);
 	const id = input.slice(colon + 1);
 	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
@@ -1672,20 +1683,29 @@ function parsePrincipalKey(input) {
 function principalUrl(key) {
 	return parsePrincipalKey(key).url;
 }
-function principalKeyFromUrl(url) {
+function parsePrincipalUrl(url) {
 	if (!url.startsWith(`/principal/`)) return null;
 	const segment = url.slice(`/principal/`.length);
 	if (!segment || segment.includes(`/`)) return null;
 	try {
-		const key = decodeURIComponent(segment);
-		return parsePrincipalKey(key).key;
+		return parsePrincipalKey(decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+}
+function parsePrincipalInput(input) {
+	const urlPrincipal = parsePrincipalUrl(input);
+	if (urlPrincipal) return urlPrincipal;
+	try {
+		return parsePrincipalKey(input);
 	} catch {
 		return null;
 	}
 }
 function getPrincipalFromRequest(request) {
 	const value = request.headers.get(ELECTRIC_PRINCIPAL_HEADER);
-	return value ? parsePrincipalKey(value) : null;
+	if (!value) return null;
+	return parsePrincipalInput(value);
 }
 function getDevPrincipal() {
 	return parsePrincipalKey(`system:dev-local`);
@@ -1698,9 +1718,8 @@ const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
 function isBuiltInSystemPrincipalUrl(url) {
 	if (!url?.startsWith(`/principal/`)) return false;
 	try {
-		const key = principalKeyFromUrl(url);
-		if (!key) return false;
-		const principal = parsePrincipalKey(key);
+		const principal = parsePrincipalUrl(url);
+		if (!principal) return false;
 		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
 	} catch {
 		return false;
@@ -1708,12 +1727,11 @@ function isBuiltInSystemPrincipalUrl(url) {
 }
 function principalFromCreatedBy(createdBy) {
 	if (!createdBy) return void 0;
-	const key = principalKeyFromUrl(createdBy);
-	if (!key) return {
+	const principal = parsePrincipalUrl(createdBy);
+	if (!principal) return {
 		url: createdBy,
 		key: null
 	};
-	const principal = parsePrincipalKey(key);
 	return {
 		url: principal.url,
 		key: principal.key,
@@ -1812,7 +1830,7 @@ var PostgresRegistry = class {
 		await this.db.insert(runners).values({
 			tenantId: this.tenantId,
 			id: input.id,
-			ownerUserId: input.ownerUserId,
+			ownerPrincipal: input.ownerPrincipal,
 			label: input.label,
 			kind: input.kind ?? `local`,
 			adminStatus: input.adminStatus ?? `enabled`,
@@ -1821,7 +1839,7 @@ var PostgresRegistry = class {
 		}).onConflictDoUpdate({
 			target: [runners.tenantId, runners.id],
 			set: {
-				ownerUserId: input.ownerUserId,
+				ownerPrincipal: input.ownerPrincipal,
 				label: input.label,
 				kind: input.kind ?? `local`,
 				adminStatus: input.adminStatus ?? `enabled`,
@@ -1839,20 +1857,46 @@ var PostgresRegistry = class {
 	}
 	async listRunners(filter) {
 		const conditions = [eq(runners.tenantId, this.tenantId)];
-		if (filter?.ownerUserId) conditions.push(eq(runners.ownerUserId, filter.ownerUserId));
+		if (filter?.ownerPrincipal) conditions.push(eq(runners.ownerPrincipal, filter.ownerPrincipal));
 		const rows = await this.db.select().from(runners).where(and(...conditions)).orderBy(desc(runners.createdAt));
 		return rows.map((row) => this.rowToRunner(row));
 	}
 	async heartbeatRunner(input) {
 		const now = input.heartbeatAt ?? new Date();
 		const leaseExpiresAt = input.livenessLeaseExpiresAt ?? new Date(now.getTime() + (input.leaseMs ?? DEFAULT_RUNNER_LEASE_MS));
-		const rows = await this.db.update(runners).set({
+		await this.db.insert(runnerRuntimeDiagnostics).values({
+			tenantId: this.tenantId,
+			runnerId: input.runnerId,
+			ownerPrincipal: input.ownerPrincipal,
 			lastSeenAt: now,
 			livenessLeaseExpiresAt: leaseExpiresAt,
-			...input.wakeStreamOffset !== void 0 ? { wakeStreamOffset: input.wakeStreamOffset } : {},
+			wakeStreamOffset: input.wakeStreamOffset,
+			diagnostics: input.diagnostics,
 			updatedAt: now
-		}).where(and(eq(runners.tenantId, this.tenantId), eq(runners.id, input.runnerId))).returning();
-		return rows[0] ? this.rowToRunner(rows[0]) : null;
+		}).onConflictDoUpdate({
+			target: [runnerRuntimeDiagnostics.tenantId, runnerRuntimeDiagnostics.runnerId],
+			set: {
+				lastSeenAt: now,
+				ownerPrincipal: input.ownerPrincipal,
+				livenessLeaseExpiresAt: leaseExpiresAt,
+				...input.wakeStreamOffset !== void 0 ? { wakeStreamOffset: input.wakeStreamOffset } : {},
+				...input.diagnostics !== void 0 ? { diagnostics: input.diagnostics } : {},
+				updatedAt: now
+			}
+		});
+		const runner = await this.getRunner(input.runnerId);
+		if (!runner) return null;
+		return {
+			...runner,
+			last_seen_at: now.toISOString(),
+			liveness_lease_expires_at: leaseExpiresAt.toISOString(),
+			...input.wakeStreamOffset !== void 0 ? { wake_stream_offset: input.wakeStreamOffset } : {},
+			...input.diagnostics !== void 0 ? { diagnostics: input.diagnostics } : {}
+		};
+	}
+	async getRunnerDiagnostics(runnerId) {
+		const rows = await this.db.select().from(runnerRuntimeDiagnostics).where(and(eq(runnerRuntimeDiagnostics.tenantId, this.tenantId), eq(runnerRuntimeDiagnostics.runnerId, runnerId))).limit(1);
+		return rows[0] ? this.rowToRunnerRuntimeDiagnostics(rows[0]) : null;
 	}
 	async setRunnerAdminStatus(runnerId, adminStatus) {
 		const rows = await this.db.update(runners).set({
@@ -1947,6 +1991,27 @@ var PostgresRegistry = class {
 		}).where(and(eq(entityDispatchState.tenantId, this.tenantId), eq(entityDispatchState.entityUrl, claim.entity_url), eq(entityDispatchState.activeConsumerId, input.consumerId), eq(entityDispatchState.activeEpoch, input.epoch)));
 		return claim;
 	}
+	async getActiveClaimsForRunner(runnerId) {
+		const rows = await this.db.select().from(consumerClaims).where(and(eq(consumerClaims.tenantId, this.tenantId), eq(consumerClaims.runnerId, runnerId), eq(consumerClaims.status, `active`)));
+		return rows.map((row) => this.rowToConsumerClaim(row));
+	}
+	async getDispatchStatsForRunner(runnerId) {
+		const rows = await this.db.select().from(entityDispatchState).where(and(eq(entityDispatchState.tenantId, this.tenantId), eq(entityDispatchState.activeRunnerId, runnerId)));
+		let activeClaim = 0;
+		let outstandingWake = 0;
+		let pendingWork = 0;
+		for (const row of rows) {
+			if (row.activeConsumerId) activeClaim++;
+			if (row.outstandingWakeId && !row.activeConsumerId) outstandingWake++;
+			const pending = row.pendingSourceStreams;
+			if (pending && pending.length > 0) pendingWork++;
+		}
+		return {
+			entities_with_active_claim: activeClaim,
+			entities_with_outstanding_wake: outstandingWake,
+			entities_with_pending_work: pendingWork
+		};
+	}
 	entityTypeWhere(name) {
 		return and(eq(entityTypes.tenantId, this.tenantId), eq(entityTypes.name, name));
 	}
@@ -2412,23 +2477,28 @@ var PostgresRegistry = class {
 		};
 	}
 	rowToRunner(row) {
-		const now = Date.now();
-		const livenessExpiry = row.livenessLeaseExpiresAt?.getTime();
 		return {
 			id: row.id,
-			owner_user_id: row.ownerUserId,
+			owner_principal: row.ownerPrincipal,
 			label: row.label,
 			kind: assertRunnerKind(row.kind),
 			admin_status: assertRunnerAdminStatus(row.adminStatus),
-			liveness: livenessExpiry !== void 0 && livenessExpiry > now ? `online` : `offline`,
-			last_seen_at: row.lastSeenAt?.toISOString(),
-			liveness_lease_expires_at: row.livenessLeaseExpiresAt?.toISOString(),
 			wake_stream: row.wakeStream,
-			wake_stream_offset: row.wakeStreamOffset ?? void 0,
 			created_at: row.createdAt.toISOString(),
 			updated_at: row.updatedAt.toISOString()
 		};
 	}
+	rowToRunnerRuntimeDiagnostics(row) {
+		return {
+			runner_id: row.runnerId,
+			owner_principal: row.ownerPrincipal,
+			wake_stream_offset: row.wakeStreamOffset ?? void 0,
+			last_seen_at: row.lastSeenAt.toISOString(),
+			liveness_lease_expires_at: row.livenessLeaseExpiresAt.toISOString(),
+			diagnostics: row.diagnostics ?? void 0,
+			updated_at: row.updatedAt.toISOString()
+		};
+	}
 	rowToConsumerClaim(row) {
 		return {
 			consumer_id: row.consumerId,
@@ -3967,6 +4037,7 @@ var ElectricAgentsError = class extends Error {
 
 //#endregion
 //#region src/routing/dispatch-policy.ts
+const linkedDispatchSubscriptions = new WeakMap();
 function subscriptionIdForDispatchTarget(target) {
 	if (target.subscription_id) return target.subscription_id;
 	if (target.type === `runner`) return `runner:${target.runnerId}`;
@@ -3975,7 +4046,7 @@ function subscriptionIdForDispatchTarget(target) {
 }
 function subscriptionIdForEntityDispatchTarget(target, entityUrl) {
 	const base = subscriptionIdForDispatchTarget(target);
-	if (!target.subscription_id) return base;
+	if (!target.subscription_id && target.type !== `runner`) return base;
 	const digest = createHash(`sha256`).update(entityUrl).digest(`hex`);
 	return `${base}:${digest.slice(0, 16)}`;
 }
@@ -4019,24 +4090,74 @@ function sameDispatchDestination(a, b) {
 	if (a.type === `webhook` && b.type === `webhook`) return a.url === b.url;
 	return false;
 }
+function subscriptionHasStream(ctx, existing, streamPath) {
+	const normalizedStream = streamPath.replace(/^\/+/, ``);
+	const backendStream = `${ctx.service}/${normalizedStream}`;
+	return existing.streams?.some((stream) => {
+		const path$1 = typeof stream === `string` ? stream : stream.path;
+		if (!path$1) return false;
+		const normalized = path$1.replace(/^\/+/, ``);
+		return normalized === normalizedStream || normalized === backendStream;
+	}) ?? false;
+}
+function dispatchLinkCacheKey(ctx, subscriptionId, streamPath) {
+	return `${ctx.service}:${subscriptionId}:${streamPath}`;
+}
+function getDispatchLinkCache(ctx) {
+	let cache = linkedDispatchSubscriptions.get(ctx.streamClient);
+	if (!cache) {
+		cache = new Set();
+		linkedDispatchSubscriptions.set(ctx.streamClient, cache);
+	}
+	return cache;
+}
+function isSubscriptionAlreadyExistsError(err) {
+	if (!(err instanceof DurableStreamsSubscriptionError)) return false;
+	if (err.status === 409) return true;
+	return err.code === `SUBSCRIPTION_ALREADY_EXISTS` || err.code === `ALREADY_EXISTS` || /already exists/i.test(err.errorMessage ?? err.body ?? err.message);
+}
+async function ensureSubscriptionIncludesStream(ctx, subscriptionId, streamPath, input, existing) {
+	if (!existing) try {
+		await ctx.streamClient.putSubscription(subscriptionId, input);
+		return;
+	} catch (err) {
+		if (!isSubscriptionAlreadyExistsError(err)) throw err;
+		existing = await ctx.streamClient.getSubscription(subscriptionId);
+		if (!existing) {
+			serverLog.warn(`[dispatch-policy] subscription create raced with existing subscription but it could not be read`, {
+				subscriptionId,
+				stream: streamPath
+			});
+			return;
+		}
+	}
+	if (!subscriptionHasStream(ctx, existing, streamPath)) await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
+}
 async function assertDispatchPolicyAllowed(ctx, policy) {
 	const target = policy?.targets[0];
 	if (!target || target.type !== `runner`) return;
+	if (!ctx.principal) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires an authenticated owner`, 401);
 	const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
 	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
-	if (ctx.principal && runner.owner_user_id !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires the authenticated owner`, 403);
+	if (runner.owner_principal !== ctx.principal.url) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner dispatch requires the authenticated owner`, 403);
 }
 async function linkEntityDispatchSubscription(ctx, entity) {
 	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
 	const target = dispatchPolicy?.targets[0];
 	if (!target) return;
-	await linkStreamToTargetSubscription(ctx, target, entity);
+	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
+	const cacheKey = dispatchLinkCacheKey(ctx, subscriptionId, entity.streams.main);
+	const cache = getDispatchLinkCache(ctx);
+	if (cache.has(cacheKey)) return;
+	await linkStreamToTargetSubscription(ctx, target, entity, subscriptionId);
+	cache.add(cacheKey);
 }
 async function unlinkEntityDispatchSubscription(ctx, entity) {
 	const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(ctx, entity);
 	const target = dispatchPolicy?.targets[0];
 	if (!target) return;
 	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
+	getDispatchLinkCache(ctx).delete(dispatchLinkCacheKey(ctx, subscriptionId, entity.streams.main));
 	await ctx.streamClient.removeSubscriptionStream(subscriptionId, entity.streams.main).catch((err) => {
 		serverLog.warn(`[dispatch-policy] failed to remove stream from subscription`, {
 			subscriptionId,
@@ -4044,37 +4165,32 @@ async function unlinkEntityDispatchSubscription(ctx, entity) {
 		}, err);
 	});
 }
-async function linkStreamToTargetSubscription(ctx, target, entity) {
+async function linkStreamToTargetSubscription(ctx, target, entity, subscriptionId) {
 	const streamPath = entity.streams.main;
-	const subscriptionId = subscriptionIdForEntityDispatchTarget(target, entity.url);
+	await ctx.streamClient.ensure(streamPath, { contentType: `application/json` });
 	const existing = await ctx.streamClient.getSubscription(subscriptionId);
 	if (target.type === `runner`) {
 		const runner = await ctx.entityManager.registry.getRunner(target.runnerId);
 		if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner "${target.runnerId}" not found`, 404);
 		const wakeStream = runner.wake_stream || runnerWakeStream(target.runnerId);
 		await ctx.streamClient.ensure(wakeStream, { contentType: `application/json` });
-		if (!existing) {
-			await ctx.streamClient.putSubscription(subscriptionId, {
-				type: `pull-wake`,
-				streams: [streamPath],
-				wake_stream: wakeStream,
-				description: `Electric Agents runner ${target.runnerId}`
-			});
-			return;
-		}
-		await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
+		await ensureSubscriptionIncludesStream(ctx, subscriptionId, streamPath, {
+			type: `pull-wake`,
+			streams: [streamPath],
+			wake_stream: wakeStream,
+			description: `Electric Agents runner ${target.runnerId}`
+		}, existing);
 		return;
 	}
 	const webhookUrl = rewriteLoopbackWebhookUrl(target.url);
 	if (!webhookUrl) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Webhook dispatch target must include a valid URL`, 400);
 	const forwardUrl = appendPathToUrl(ctx.publicUrl, `/_electric/webhook-forward/${encodeURIComponent(subscriptionId)}`);
-	if (!existing) await ctx.streamClient.putSubscription(subscriptionId, {
+	await ensureSubscriptionIncludesStream(ctx, subscriptionId, streamPath, {
 		type: `webhook`,
 		streams: [streamPath],
 		webhook: { url: forwardUrl },
 		description: `Electric Agents webhook ${subscriptionId}`
-	});
-	else await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath]);
+	}, existing);
 	await ctx.pgDb.insert(subscriptionWebhooks).values({
 		tenantId: ctx.service,
 		subscriptionId,
@@ -4326,10 +4442,8 @@ async function sendEntity(request, ctx) {
 	if (parsed.from !== void 0 && parsed.from !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from must match Electric-Principal`);
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
-	if (!entity.dispatch_policy) {
-		const updatedEntity = await backfillEntityDispatchPolicy(ctx, entity);
-		await linkEntityDispatchSubscription(ctx, updatedEntity);
-	}
+	const dispatchEntity = entity.dispatch_policy ? entity : await backfillEntityDispatchPolicy(ctx, entity);
+	await linkEntityDispatchSubscription(ctx, dispatchEntity);
 	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, {
 		from: principal.url,
 		payload: parsed.payload,
@@ -4378,11 +4492,11 @@ async function spawnEntity(request, ctx) {
 		wake: parsed.wake,
 		created_by: principal.url
 	});
+	await linkEntityDispatchSubscription(ctx, entity);
 	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(entity.url, {
 		from: principal.url,
 		payload: parsed.initialMessage
 	});
-	await linkEntityDispatchSubscription(ctx, entity);
 	return json({
 		...toPublicEntity(entity),
 		txid: entity.txid
@@ -4546,7 +4660,13 @@ function applyCors(response) {
 	const headers = new Headers(response.headers);
 	headers.set(`access-control-allow-origin`, `*`);
 	headers.set(`access-control-allow-methods`, `GET, POST, PUT, PATCH, DELETE, OPTIONS`);
-	headers.set(`access-control-allow-headers`, `content-type, authorization, electric-claim-token, ngrok-skip-browser-warning`);
+	headers.set(`access-control-allow-headers`, [
+		`content-type`,
+		`authorization`,
+		`electric-claim-token`,
+		ELECTRIC_PRINCIPAL_HEADER,
+		`ngrok-skip-browser-warning`
+	].join(`, `));
 	headers.set(`access-control-expose-headers`, `*`);
 	return new Response(response.body, {
 		status: response.status,
@@ -4581,11 +4701,17 @@ function getRequestSpan(req) {
 	return carrier(req)[SPAN_KEY];
 }
 
+//#endregion
+//#region src/routing/tenant-stream-paths.ts
+function withLeadingSlash(path$1) {
+	return path$1.startsWith(`/`) ? path$1 : `/${path$1}`;
+}
+
 //#endregion
 //#region src/routing/runners-router.ts
 const registerRunnerBodySchema = Type.Object({
 	id: Type.String(),
-	owner_user_id: Type.Optional(Type.String()),
+	owner_principal: Type.Optional(Type.String()),
 	label: Type.String(),
 	kind: Type.Optional(Type.Union([
 		Type.Literal(`local`),
@@ -4601,7 +4727,8 @@ const heartbeatBodySchema = Type.Object({
 	lease_ms: Type.Optional(Type.Number()),
 	wake_stream_offset: Type.Optional(Type.String()),
 	wakeStreamOffset: Type.Optional(Type.String()),
-	liveness_lease_expires_at: Type.Optional(Type.String())
+	liveness_lease_expires_at: Type.Optional(Type.String()),
+	diagnostics: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
 });
 const claimBodySchema = Type.Object({
 	subscription_id: Type.Optional(Type.String()),
@@ -4609,9 +4736,39 @@ const claimBodySchema = Type.Object({
 	generation: Type.Optional(Type.Number()),
 	ts: Type.Optional(Type.Union([Type.String(), Type.Number()]))
 }, { additionalProperties: true });
+const runnerClientStatuses = new Set([
+	`stopped`,
+	`starting`,
+	`connecting`,
+	`streaming`,
+	`reconnecting`,
+	`stopping`
+]);
+const runnerLastClaimResults = new Set([
+	`claimed`,
+	`no_work`,
+	`error`
+]);
+const runnerStringOrNullDiagnostics = [
+	`started_at`,
+	`stream_connected_since`,
+	`last_error`,
+	`last_error_at`,
+	`last_heartbeat_at`,
+	`last_claim_at`,
+	`last_dispatch_at`
+];
+const runnerNumberDiagnostics = [
+	`reconnect_count`,
+	`events_received`,
+	`claims_succeeded`,
+	`claims_skipped`,
+	`claims_failed`
+];
 const runnersRouter = Router({ base: `/_electric/runners` });
 runnersRouter.post(`/`, withSchema(registerRunnerBodySchema), registerRunner);
 runnersRouter.get(`/`, listRunners);
+runnersRouter.get(`/:id/health`, runnerHealth);
 runnersRouter.get(`/:id`, getRunner);
 runnersRouter.post(`/:id/heartbeat`, withSchema(heartbeatBodySchema), heartbeat);
 runnersRouter.post(`/:id/enable`, setEnabled);
@@ -4624,14 +4781,41 @@ function routeParam$1(request, name) {
 function firstQueryValue(value) {
 	return Array.isArray(value) ? value[0] : value;
 }
+function requireAuthenticatedPrincipal(ctx) {
+	if (ctx.principal) return ctx.principal;
+	throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner route requires an authenticated principal`, 401);
+}
+function canonicalOwnerPrincipal(input) {
+	return parsePrincipalUrl(input)?.url ?? null;
+}
+function sanitizeRunnerDiagnostics(diagnostics) {
+	if (!diagnostics) return void 0;
+	const sanitized = {};
+	if (typeof diagnostics.status === `string` && runnerClientStatuses.has(diagnostics.status)) sanitized.status = diagnostics.status;
+	if (typeof diagnostics.stream_connected === `boolean`) sanitized.stream_connected = diagnostics.stream_connected;
+	if (typeof diagnostics.last_heartbeat_ok === `boolean`) sanitized.last_heartbeat_ok = diagnostics.last_heartbeat_ok;
+	if (diagnostics.last_claim_result === null || typeof diagnostics.last_claim_result === `string` && runnerLastClaimResults.has(diagnostics.last_claim_result)) sanitized.last_claim_result = diagnostics.last_claim_result;
+	for (const key of runnerStringOrNullDiagnostics) {
+		const value = diagnostics[key];
+		if (typeof value === `string` || value === null) sanitized[key] = value;
+	}
+	for (const key of runnerNumberDiagnostics) {
+		const value = diagnostics[key];
+		if (typeof value === `number` && Number.isFinite(value) && value >= 0) sanitized[key] = value;
+	}
+	return Object.keys(sanitized).length > 0 ? sanitized : void 0;
+}
 async function registerRunner(request, ctx) {
 	const parsed = routeBody(request);
-	const ownerUserId = parsed.owner_user_id ?? ctx.principal?.key;
-	if (!ownerUserId) throw new ElectricAgentsError(ErrCodeInvalidRequest, `owner_user_id is required when no authenticated user is present`, 400);
-	if (ctx.principal && ownerUserId !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
+	const principal = requireAuthenticatedPrincipal(ctx);
+	const ownerPrincipal = parsed.owner_principal ?? principal.url;
+	if (!ownerPrincipal) throw new ElectricAgentsError(ErrCodeInvalidRequest, `owner_principal is required when no authenticated principal is present`, 400);
+	const canonicalOwner = canonicalOwnerPrincipal(ownerPrincipal);
+	if (!canonicalOwner) throw new ElectricAgentsError(ErrCodeInvalidRequest, `owner_principal must be a valid principal URL (e.g. /principal/user%3Aalice), got: ${ownerPrincipal}`, 400);
+	if (canonicalOwner !== principal.url) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_principal must match the authenticated principal`, 403);
 	const runner = await ctx.entityManager.registry.createRunner({
 		id: parsed.id,
-		ownerUserId,
+		ownerPrincipal: canonicalOwner,
 		label: parsed.label,
 		kind: parsed.kind,
 		adminStatus: parsed.admin_status,
@@ -4641,26 +4825,32 @@ async function registerRunner(request, ctx) {
 	return json(runner, { status: 201 });
 }
 async function listRunners(request, ctx) {
-	const requestedOwner = firstQueryValue(request.query.owner_user_id);
-	if (ctx.principal && requestedOwner && requestedOwner !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_user_id must match the authenticated user`, 403);
-	const runners$1 = await ctx.entityManager.registry.listRunners({ ownerUserId: ctx.principal?.key ?? requestedOwner });
+	const principal = requireAuthenticatedPrincipal(ctx);
+	const requestedOwner = firstQueryValue(request.query.owner_principal);
+	const canonicalRequestedOwner = requestedOwner ? canonicalOwnerPrincipal(requestedOwner) : void 0;
+	if (requestedOwner && !canonicalRequestedOwner) throw new ElectricAgentsError(ErrCodeInvalidRequest, `owner_principal must be a valid principal URL (e.g. /principal/user%3Aalice), got: ${requestedOwner}`, 400);
+	if (canonicalRequestedOwner && canonicalRequestedOwner !== principal.url) throw new ElectricAgentsError(ErrCodeUnauthorized, `owner_principal must match the authenticated principal`, 403);
+	const runners$1 = await ctx.entityManager.registry.listRunners({ ownerPrincipal: principal.url });
 	return json(runners$1);
 }
 async function getRunner(request, ctx) {
 	const runner = await requireRunner(ctx, routeParam$1(request, `id`));
-	assertRunnerOwnerIfAuthenticated(ctx, runner.owner_user_id);
+	assertRunnerOwnerIfAuthenticated(ctx, runner.owner_principal);
 	return json(runner);
 }
 async function heartbeat(request, ctx) {
 	const runnerId = routeParam$1(request, `id`);
+	requireAuthenticatedPrincipal(ctx);
 	const existing = await requireRunner(ctx, runnerId);
-	assertRunnerOwnerIfAuthenticated(ctx, existing.owner_user_id);
+	assertRunnerOwnerIfAuthenticated(ctx, existing.owner_principal);
 	const parsed = routeBody(request);
 	const runner = await ctx.entityManager.registry.heartbeatRunner({
 		runnerId,
+		ownerPrincipal: existing.owner_principal,
 		leaseMs: parsed.lease_ms,
 		wakeStreamOffset: parsed.wake_stream_offset ?? parsed.wakeStreamOffset,
-		livenessLeaseExpiresAt: parsed.liveness_lease_expires_at ? new Date(parsed.liveness_lease_expires_at) : void 0
+		livenessLeaseExpiresAt: parsed.liveness_lease_expires_at ? new Date(parsed.liveness_lease_expires_at) : void 0,
+		diagnostics: sanitizeRunnerDiagnostics(parsed.diagnostics)
 	});
 	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner not found`, 404);
 	return json(runner);
@@ -4673,16 +4863,18 @@ async function setDisabled(request, ctx) {
 }
 async function setRunnerStatus(request, ctx, adminStatus) {
 	const runnerId = routeParam$1(request, `id`);
+	requireAuthenticatedPrincipal(ctx);
 	const existing = await requireRunner(ctx, runnerId);
-	assertRunnerOwnerIfAuthenticated(ctx, existing.owner_user_id);
+	assertRunnerOwnerIfAuthenticated(ctx, existing.owner_principal);
 	const runner = await ctx.entityManager.registry.setRunnerAdminStatus(runnerId, adminStatus);
 	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner not found`, 404);
 	return json(runner);
 }
 async function claimWake(request, ctx) {
 	const runnerId = routeParam$1(request, `id`);
+	const principal = requireAuthenticatedPrincipal(ctx);
 	const runner = await requireRunner(ctx, runnerId);
-	if (ctx.principal && runner.owner_user_id !== ctx.principal.key) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner claim requires the authenticated owner`, 403);
+	if (runner.owner_principal !== principal.url) throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner claim requires the authenticated owner`, 403);
 	if (runner.admin_status !== `enabled`) throw new ElectricAgentsError(ErrCodeNotRunning, `Runner is disabled`, 409);
 	const parsed = routeBody(request);
 	const expectedSubscriptionId = subscriptionIdForDispatchTarget({
@@ -4713,11 +4905,95 @@ async function requireRunner(ctx, runnerId) {
 	if (!runner) throw new ElectricAgentsError(ErrCodeNotFound, `Runner not found`, 404);
 	return runner;
 }
-function assertRunnerOwnerIfAuthenticated(ctx, ownerUserId) {
-	if (!ctx.principal) return;
-	if (ownerUserId === ctx.principal.key) return;
+function assertRunnerOwnerIfAuthenticated(ctx, ownerPrincipal) {
+	requireAuthenticatedPrincipal(ctx);
+	if (ownerPrincipal === ctx.principal.url) return;
 	throw new ElectricAgentsError(ErrCodeUnauthorized, `Runner access requires the authenticated owner`, 403);
 }
+async function runnerHealth(request, ctx) {
+	const runnerId = routeParam$1(request, `id`);
+	const runner = await requireRunner(ctx, runnerId);
+	assertRunnerOwnerIfAuthenticated(ctx, runner.owner_principal);
+	const runtimeDiagnostics = await ctx.entityManager.registry.getRunnerDiagnostics(runnerId);
+	const now = Date.now();
+	const parsedLeaseExpiresAt = runtimeDiagnostics?.liveness_lease_expires_at ? new Date(runtimeDiagnostics.liveness_lease_expires_at).getTime() : null;
+	const leaseExpiresAt = parsedLeaseExpiresAt !== null && Number.isFinite(parsedLeaseExpiresAt) ? parsedLeaseExpiresAt : null;
+	let livenessStatus;
+	if (runner.admin_status === `disabled`) livenessStatus = `offline`;
+	else if (leaseExpiresAt !== null && leaseExpiresAt > now) livenessStatus = `online`;
+	else if (leaseExpiresAt !== null) livenessStatus = `expired`;
+	else livenessStatus = `offline`;
+	const [activeClaims, dispatchStats] = await Promise.all([ctx.entityManager.registry.getActiveClaimsForRunner(runnerId), ctx.entityManager.registry.getDispatchStatsForRunner(runnerId)]);
+	const clientDiagnostics = sanitizeRunnerDiagnostics(runtimeDiagnostics?.diagnostics) ?? null;
+	const issues = [];
+	let healthStatus = `healthy`;
+	const escalate = (floor) => {
+		if (floor === `unhealthy`) healthStatus = `unhealthy`;
+		else if (healthStatus === `healthy`) healthStatus = `degraded`;
+	};
+	if (runner.admin_status === `disabled`) {
+		escalate(`unhealthy`);
+		issues.push(`Runner is disabled`);
+	}
+	if (livenessStatus === `expired`) {
+		escalate(`unhealthy`);
+		const ago = leaseExpiresAt ? Math.round((now - leaseExpiresAt) / 1e3) : 0;
+		issues.push(`Heartbeat lease expired ${ago}s ago`);
+	}
+	if (livenessStatus === `offline` && runner.admin_status === `enabled`) {
+		escalate(`degraded`);
+		issues.push(`Runner has never sent a heartbeat`);
+	}
+	if (clientDiagnostics) {
+		if (clientDiagnostics.stream_connected === false) {
+			escalate(`degraded`);
+			issues.push(`Client reports stream disconnected`);
+		}
+		if (clientDiagnostics.last_heartbeat_ok === false) {
+			escalate(`degraded`);
+			issues.push(`Client reports last heartbeat failed`);
+		}
+		if (typeof clientDiagnostics.reconnect_count === `number` && clientDiagnostics.reconnect_count > 5) {
+			escalate(`degraded`);
+			issues.push(`Client has reconnected ${clientDiagnostics.reconnect_count} times`);
+		}
+	} else if (runtimeDiagnostics?.last_seen_at) {
+		escalate(`degraded`);
+		issues.push(`No client diagnostics available`);
+	}
+	const body = {
+		runner: {
+			id: runner.id,
+			admin_status: runner.admin_status,
+			liveness_status: livenessStatus,
+			lease_expires_at: leaseExpiresAt !== null ? runtimeDiagnostics?.liveness_lease_expires_at ?? null : null,
+			lease_remaining_ms: leaseExpiresAt !== null ? Math.max(0, leaseExpiresAt - now) : null,
+			wake_stream: runner.wake_stream,
+			wake_stream_offset: runtimeDiagnostics?.wake_stream_offset ?? null,
+			last_seen_at: runtimeDiagnostics?.last_seen_at ?? null,
+			created_at: runner.created_at
+		},
+		client: clientDiagnostics,
+		claims: {
+			active_count: activeClaims.length,
+			active: activeClaims.map((c) => ({
+				consumer_id: c.consumer_id,
+				epoch: c.epoch,
+				entity_url: c.entity_url,
+				stream_path: c.stream_path,
+				claimed_at: c.claimed_at,
+				last_heartbeat_at: c.last_heartbeat_at ?? null,
+				lease_expires_at: c.lease_expires_at ?? null
+			}))
+		},
+		dispatch: dispatchStats,
+		health: {
+			status: healthStatus,
+			issues
+		}
+	};
+	return json(body);
+}
 async function notificationFromClaim(ctx, input) {
 	const primary = input.claim.streams.find((stream) => stream.has_pending === true) ?? input.claim.streams[0];
 	if (!primary?.path) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Claim response did not include a stream`, 502);
@@ -4904,7 +5180,7 @@ async function webhookForward(request, ctx) {
 	let runningEntityUrl = null;
 	const parsedBody = parsedBodyResult.value;
 	const newWebhook = newWebhookPayload(parsedBody);
-	const routingAdapter = resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting);
+	const routingAdapter = resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting, ctx.durableStreamsUrl);
 	if (parsedBody) {
 		const rawPrimaryStream = newWebhook?.primaryStream ?? parsedBody.primary_stream ?? parsedBody.primaryStream ?? parsedBody.streamPath ?? null;
 		const primaryStream = typeof rawPrimaryStream === `string` ? toRuntimeStreamPath(rawPrimaryStream, ctx.service, routingAdapter) : null;
@@ -5033,7 +5309,7 @@ async function callbackForward(request, ctx) {
 		}
 		return json(responseBody);
 	}
-	const upstreamBody = encodeCallbackForwardBody(ctx.service, consumerId, requestBody, resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting));
+	const upstreamBody = encodeCallbackForwardBody(ctx.service, consumerId, requestBody, resolveDurableStreamsRoutingAdapter(ctx.durableStreamsRouting, ctx.durableStreamsUrl));
 	let upstream;
 	try {
 		const subscriptionId = durableStreamsSubscriptionCallback(target.callbackUrl);
@@ -6202,7 +6478,7 @@ var ElectricAgentsTenantRuntime = class {
 		this.service = this.serviceId;
 		this.db = options.db;
 		if (options.streamClient) this.streamClient = options.streamClient;
-		else if (options.durableStreamsUrl) this.streamClient = new StreamClient(durableStreamsServiceUrl(options.durableStreamsUrl, this.serviceId), { bearer: options.durableStreamsBearer });
+		else if (options.durableStreamsUrl) this.streamClient = new StreamClient(options.durableStreamsUrl, { bearer: options.durableStreamsBearer });
 		else throw new Error(`Either durableStreamsUrl or streamClient is required`);
 		this.registry = options.registry ?? new PostgresRegistry(this.db, this.serviceId);
 		this.wakeRegistry = options.wakeRegistry;
@@ -7120,7 +7396,7 @@ var WakeRegistry = class {
 //#region src/standalone-runtime.ts
 async function startStandaloneAgentsRuntime(options) {
 	const serviceId = options.service ?? options.tenantId ?? DEFAULT_TENANT_ID;
-	const streamClient = options.streamClient ?? (options.durableStreamsUrl ? new StreamClient(durableStreamsServiceUrl(options.durableStreamsUrl, serviceId), { bearer: options.durableStreamsBearer }) : void 0);
+	const streamClient = options.streamClient ?? (options.durableStreamsUrl ? new StreamClient(options.durableStreamsUrl, { bearer: options.durableStreamsBearer }) : void 0);
 	if (!streamClient) throw new Error(`Either durableStreamsUrl or streamClient is required`);
 	const registry = new PostgresRegistry(options.db, serviceId);
 	const wakeRegistry = options.wakeRegistry ?? new WakeRegistry(options.db, serviceId);
@@ -7268,6 +7544,11 @@ function createMockAgentBootstrap(options) {
 		registry
 	};
 }
+function durableStreamTestServerBackendUrl(origin) {
+	const url = new URL(origin);
+	url.pathname = `${url.pathname.replace(/\/+$/, ``)}/v1/stream`;
+	return url.toString().replace(/\/+$/, ``);
+}
 var ElectricAgentsServer = class {
 	server;
 	electricAgentsManager;
@@ -7284,7 +7565,7 @@ var ElectricAgentsServer = class {
 	constructor(options) {
 		if (!options.durableStreamsUrl && !options.durableStreamsServer) throw new Error(`Either durableStreamsUrl or durableStreamsServer is required`);
 		this.options = options;
-		this.streamClient = options.durableStreamsUrl ? new StreamClient(durableStreamsServiceUrl(options.durableStreamsUrl, this.tenantId), { bearer: options.durableStreamsBearer }) : null;
+		this.streamClient = options.durableStreamsUrl ? new StreamClient(options.durableStreamsUrl, { bearer: options.durableStreamsBearer }) : null;
 	}
 	get url() {
 		if (!this._url) throw new Error(`Server not started`);
@@ -7304,8 +7585,8 @@ var ElectricAgentsServer = class {
 				serverLog.info(`[agent-server] starting durable streams server...`);
 				const streamsUrl = await this.options.durableStreamsServer.start();
 				serverLog.info(`[agent-server] durable streams server started at ${streamsUrl}`);
-				this.options.durableStreamsUrl = streamsUrl;
-				this.streamClient = new StreamClient(durableStreamsServiceUrl(streamsUrl, this.tenantId), { bearer: this.options.durableStreamsBearer });
+				this.options.durableStreamsUrl = durableStreamTestServerBackendUrl(streamsUrl);
+				this.streamClient = new StreamClient(this.options.durableStreamsUrl, { bearer: this.options.durableStreamsBearer });
 			}
 			this.streamsAgent = new Agent({
 				keepAliveTimeout: 6e4,
@@ -7437,7 +7718,7 @@ var ElectricAgentsServer = class {
 			localUrl: this._url,
 			durableStreamsUrl: this.options.durableStreamsUrl,
 			durableStreamsBearer: this.options.durableStreamsBearer,
-			durableStreamsRouting: this.options.durableStreamsRouting ?? pathPrefixedSingleTenantDurableStreamsRoutingAdapter,
+			durableStreamsRouting: this.options.durableStreamsRouting,
 			durableStreamsDispatcher: this.streamsAgent,
 			electricUrl: this.options.electricUrl,
 			electricSecret: this.options.electricSecret,