@electric-ax/agents-server 0.4.3 → 0.4.5

package/drizzle/0007_runner_diagnostics_and_principal.sql

@@ -0,0 +1,22 @@
+UPDATE consumer_claims
+SET status = 'expired', updated_at = NOW()
+WHERE status = 'active' AND runner_id IS NOT NULL;
+--> statement-breakpoint
+UPDATE entity_dispatch_state
+SET active_runner_id = NULL,
+    active_consumer_id = NULL,
+    active_epoch = NULL,
+    active_claimed_at = NULL,
+    active_lease_expires_at = NULL,
+    updated_at = NOW()
+WHERE active_runner_id IS NOT NULL;
+--> statement-breakpoint
+DELETE FROM runners;
+--> statement-breakpoint
+ALTER TABLE runners RENAME COLUMN owner_user_id TO owner_principal;
+--> statement-breakpoint
+DROP INDEX IF EXISTS idx_runners_owner_user_id;
+--> statement-breakpoint
+CREATE INDEX idx_runners_owner_principal ON runners (tenant_id, owner_principal);
+--> statement-breakpoint
+ALTER TABLE runners ADD COLUMN diagnostics jsonb;

package/drizzle/0008_runner_runtime_diagnostics.sql

@@ -0,0 +1,50 @@
+CREATE TABLE runner_runtime_diagnostics (
+  tenant_id text NOT NULL DEFAULT 'default',
+  runner_id text NOT NULL,
+  owner_principal text NOT NULL,
+  wake_stream_offset text,
+  last_seen_at timestamp with time zone NOT NULL,
+  liveness_lease_expires_at timestamp with time zone NOT NULL,
+  diagnostics jsonb,
+  updated_at timestamp with time zone NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (tenant_id, runner_id)
+);
+--> statement-breakpoint
+CREATE INDEX idx_runner_runtime_diagnostics_owner
+  ON runner_runtime_diagnostics (tenant_id, owner_principal);
+--> statement-breakpoint
+CREATE INDEX idx_runner_runtime_diagnostics_liveness
+  ON runner_runtime_diagnostics (tenant_id, liveness_lease_expires_at);
+--> statement-breakpoint
+INSERT INTO runner_runtime_diagnostics (
+  tenant_id,
+  runner_id,
+  owner_principal,
+  wake_stream_offset,
+  last_seen_at,
+  liveness_lease_expires_at,
+  diagnostics,
+  updated_at
+)
+SELECT
+  tenant_id,
+  id,
+  owner_principal,
+  wake_stream_offset,
+  COALESCE(last_seen_at, updated_at),
+  COALESCE(liveness_lease_expires_at, updated_at),
+  diagnostics,
+  updated_at
+FROM runners
+WHERE last_seen_at IS NOT NULL
+   OR liveness_lease_expires_at IS NOT NULL
+   OR wake_stream_offset IS NOT NULL
+   OR diagnostics IS NOT NULL;
+--> statement-breakpoint
+ALTER TABLE runners DROP COLUMN diagnostics;
+--> statement-breakpoint
+ALTER TABLE runners DROP COLUMN wake_stream_offset;
+--> statement-breakpoint
+ALTER TABLE runners DROP COLUMN last_seen_at;
+--> statement-breakpoint
+ALTER TABLE runners DROP COLUMN liveness_lease_expires_at;

package/drizzle/meta/_journal.json

@@ -50,6 +50,20 @@
       "when": 1776268800000,
       "tag": "0006_principals",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1778899200000,
+      "tag": "0007_runner_diagnostics_and_principal",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1778976000000,
+      "tag": "0008_runner_runtime_diagnostics",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -36,9 +36,9 @@
   "sideEffects": false,
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@durable-streams/client": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/client@350",
-    "@durable-streams/server": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/server@350",
-    "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@350",
+    "@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@5d5c217",
+    "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@5d5c217",
     "@electric-sql/client": "^1.5.18",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@opentelemetry/api": "^1.9.1",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.2.1"
+    "@electric-ax/agents-runtime": "0.3.0"
   },
   "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.2",
-    "@electric-ax/agents-server-conformance-tests": "0.1.5",
-    "@electric-ax/agents-server-ui": "0.4.3"
+    "@electric-ax/agents-server-ui": "0.4.5",
+    "@electric-ax/agents-server-conformance-tests": "0.1.6",
+    "@electric-ax/agents": "0.4.4"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -106,16 +106,11 @@ export const runners = pgTable(
   {
     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(),
@@ -126,12 +121,11 @@ export const runners = pgTable(
   (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_admin_status`).on(table.tenantId, table.adminStatus),
-    index(`idx_runners_liveness_lease_expires_at`).on(
+    index(`idx_runners_owner_principal`).on(
       table.tenantId,
-      table.livenessLeaseExpiresAt
+      table.ownerPrincipal
     ),
+    index(`idx_runners_admin_status`).on(table.tenantId, table.adminStatus),
     check(
       `chk_runners_kind`,
       sql`${table.kind} IN ('local', 'cloud-worker', 'sandbox', 'ci', 'server')`
@@ -143,6 +137,35 @@ export const runners = pgTable(
   ]
 )
 
+export 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
+    ),
+  ]
+)
+
 export const entityDispatchState = pgTable(
   `entity_dispatch_state`,
   {

package/src/electric-agents-types.ts

@@ -2,7 +2,10 @@
  * Types for the Electric Agents entity runtime.
  */
 
-import type { WebhookNotification } from '@electric-ax/agents-runtime'
+import type {
+  PullWakeRunnerHealth,
+  WebhookNotification,
+} from '@electric-ax/agents-runtime'
 import type { Principal } from './principal.js'
 
 type WakeNotification = WebhookNotification
@@ -105,7 +108,7 @@ export interface RunnerActiveClaim {
 
 export interface ElectricAgentsRunner {
   id: string
-  owner_user_id: string
+  owner_principal: string
   label: string
   kind: RunnerKind
   admin_status: RunnerAdminStatus
@@ -115,13 +118,14 @@ export interface ElectricAgentsRunner {
   active_claims?: Array<RunnerActiveClaim>
   wake_stream: string
   wake_stream_offset?: string
+  diagnostics?: Record<string, unknown>
   created_at: string
   updated_at: string
 }
 
 export interface RegisterRunnerRequest {
   id: string
-  owner_user_id: string
+  owner_principal: string
   label: string
   kind?: RunnerKind
   admin_status?: RunnerAdminStatus
@@ -133,6 +137,48 @@ export interface RunnerHeartbeatRequest {
   wake_stream_offset?: string
   wakeStreamOffset?: string
   liveness_lease_expires_at?: string
+  diagnostics?: Record<string, unknown>
+}
+
+export type RunnerHealthStatus = `healthy` | `degraded` | `unhealthy`
+export type RunnerClientDiagnostics = Partial<
+  Omit<PullWakeRunnerHealth, `running` | `offset`>
+>
+
+export interface RunnerHealthResponse {
+  runner: {
+    id: string
+    admin_status: RunnerAdminStatus
+    liveness_status: RunnerLiveness | `expired`
+    lease_expires_at: string | null
+    lease_remaining_ms: number | null
+    wake_stream: string
+    wake_stream_offset: string | null
+    last_seen_at: string | null
+    created_at: string
+  }
+  client: RunnerClientDiagnostics | null
+  claims: {
+    active_count: number
+    active: Array<{
+      consumer_id: string
+      epoch: number
+      entity_url: string
+      stream_path: string
+      claimed_at: string
+      last_heartbeat_at: string | null
+      lease_expires_at: string | null
+    }>
+  }
+  dispatch: {
+    entities_with_active_claim: number
+    entities_with_outstanding_wake: number
+    entities_with_pending_work: number
+  }
+  health: {
+    status: RunnerHealthStatus
+    issues: Array<string>
+  }
 }
 
 export interface EntityDispatchState {

package/src/entity-registry.ts

@@ -7,6 +7,7 @@ import {
   entityDispatchState,
   entityManifestSources,
   entityTypes,
+  runnerRuntimeDiagnostics,
   runners,
   tagStreamOutbox,
 } from './db/schema.js'
@@ -73,7 +74,7 @@ export interface TagStreamOutboxRow {
 
 export interface RegisterRunnerInput {
   id: string
-  ownerUserId: string
+  ownerPrincipal: string
   label: string
   kind?: RunnerKind
   adminStatus?: RunnerAdminStatus
@@ -82,10 +83,22 @@ export interface RegisterRunnerInput {
 
 export interface HeartbeatRunnerInput {
   runnerId: string
+  ownerPrincipal: string
   heartbeatAt?: Date
   livenessLeaseExpiresAt?: Date
   leaseMs?: number
   wakeStreamOffset?: string
+  diagnostics?: Record<string, unknown>
+}
+
+export interface RunnerRuntimeDiagnostics {
+  runner_id: string
+  owner_principal: string
+  wake_stream_offset?: string
+  last_seen_at: string
+  liveness_lease_expires_at: string
+  diagnostics?: Record<string, unknown>
+  updated_at: string
 }
 
 export interface MaterializeActiveClaimInput {
@@ -140,7 +153,7 @@ export class PostgresRegistry {
       .values({
         tenantId: this.tenantId,
         id: input.id,
-        ownerUserId: input.ownerUserId,
+        ownerPrincipal: input.ownerPrincipal,
         label: input.label,
         kind: input.kind ?? `local`,
         adminStatus: input.adminStatus ?? `enabled`,
@@ -150,7 +163,7 @@ export class PostgresRegistry {
       .onConflictDoUpdate({
         target: [runners.tenantId, runners.id],
         set: {
-          ownerUserId: input.ownerUserId,
+          ownerPrincipal: input.ownerPrincipal,
           label: input.label,
           kind: input.kind ?? `local`,
           adminStatus: input.adminStatus ?? `enabled`,
@@ -176,11 +189,11 @@ export class PostgresRegistry {
   }
 
   async listRunners(filter?: {
-    ownerUserId?: string
+    ownerPrincipal?: string
   }): Promise<Array<ElectricAgentsRunner>> {
     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()
@@ -198,22 +211,66 @@ export class PostgresRegistry {
       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 !== undefined
-          ? { wakeStreamOffset: input.wakeStreamOffset }
-          : {}),
+        wakeStreamOffset: input.wakeStreamOffset,
+        diagnostics: input.diagnostics,
         updatedAt: now,
       })
+      .onConflictDoUpdate({
+        target: [
+          runnerRuntimeDiagnostics.tenantId,
+          runnerRuntimeDiagnostics.runnerId,
+        ],
+        set: {
+          lastSeenAt: now,
+          ownerPrincipal: input.ownerPrincipal,
+          livenessLeaseExpiresAt: leaseExpiresAt,
+          ...(input.wakeStreamOffset !== undefined
+            ? { wakeStreamOffset: input.wakeStreamOffset }
+            : {}),
+          ...(input.diagnostics !== undefined
+            ? { 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 !== undefined
+        ? { wake_stream_offset: input.wakeStreamOffset }
+        : {}),
+      ...(input.diagnostics !== undefined
+        ? { diagnostics: input.diagnostics }
+        : {}),
+    }
+  }
+
+  async getRunnerDiagnostics(
+    runnerId: string
+  ): Promise<RunnerRuntimeDiagnostics | null> {
+    const rows = await this.db
+      .select()
+      .from(runnerRuntimeDiagnostics)
       .where(
-        and(eq(runners.tenantId, this.tenantId), eq(runners.id, input.runnerId))
+        and(
+          eq(runnerRuntimeDiagnostics.tenantId, this.tenantId),
+          eq(runnerRuntimeDiagnostics.runnerId, runnerId)
+        )
       )
-      .returning()
-
-    return rows[0] ? this.rowToRunner(rows[0]) : null
+      .limit(1)
+    return rows[0] ? this.rowToRunnerRuntimeDiagnostics(rows[0]) : null
   }
 
   async setRunnerAdminStatus(
@@ -366,6 +423,54 @@ export class PostgresRegistry {
     return claim
   }
 
+  async getActiveClaimsForRunner(
+    runnerId: string
+  ): Promise<Array<ConsumerClaim>> {
+    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: string): Promise<{
+    entities_with_active_claim: number
+    entities_with_outstanding_wake: number
+    entities_with_pending_work: number
+  }> {
+    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 as Array<unknown> | null
+      if (pending && pending.length > 0) pendingWork++
+    }
+
+    return {
+      entities_with_active_claim: activeClaim,
+      entities_with_outstanding_wake: outstandingWake,
+      entities_with_pending_work: pendingWork,
+    }
+  }
+
   private entityTypeWhere(name: string) {
     return and(
       eq(entityTypes.tenantId, this.tenantId),
@@ -1146,27 +1251,32 @@ export class PostgresRegistry {
   }
 
   private rowToRunner(row: typeof runners.$inferSelect): ElectricAgentsRunner {
-    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 !== undefined && 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 ?? undefined,
       created_at: row.createdAt.toISOString(),
       updated_at: row.updatedAt.toISOString(),
     }
   }
 
+  private rowToRunnerRuntimeDiagnostics(
+    row: typeof runnerRuntimeDiagnostics.$inferSelect
+  ): RunnerRuntimeDiagnostics {
+    return {
+      runner_id: row.runnerId,
+      owner_principal: row.ownerPrincipal,
+      wake_stream_offset: row.wakeStreamOffset ?? undefined,
+      last_seen_at: row.lastSeenAt.toISOString(),
+      liveness_lease_expires_at: row.livenessLeaseExpiresAt.toISOString(),
+      diagnostics: (row.diagnostics as Record<string, unknown>) ?? undefined,
+      updated_at: row.updatedAt.toISOString(),
+    }
+  }
+
   private rowToConsumerClaim(
     row: typeof consumerClaims.$inferSelect
   ): ConsumerClaim {

package/src/host.ts

@@ -3,7 +3,7 @@ import { PostgresRegistry } from './entity-registry.js'
 import { EntityProjector } from './entity-projector.js'
 import { ElectricAgentsTenantRuntime } from './runtime.js'
 import { PostgresSchedulerClient, Scheduler } from './scheduler.js'
-import { StreamClient, durableStreamsServiceUrl } from './stream-client.js'
+import { StreamClient } from './stream-client.js'
 import { TagStreamOutboxDrainer } from './tag-stream-outbox-drainer.js'
 import { DEFAULT_TENANT_ID, UnregisteredTenantError } from './tenant.js'
 import { WakeRegistry } from './wake-registry.js'
@@ -313,10 +313,9 @@ export class AgentsHost {
   private createStreamClient(config: AgentsHostTenantConfig): StreamClient {
     if (config.streamClient) return config.streamClient
     if (config.durableStreamsUrl) {
-      return new StreamClient(
-        durableStreamsServiceUrl(config.durableStreamsUrl, config.serviceId),
-        { bearer: config.durableStreamsBearer }
-      )
+      return new StreamClient(config.durableStreamsUrl, {
+        bearer: config.durableStreamsBearer,
+      })
     }
     throw new Error(
       `AgentsHost tenant "${config.serviceId}" must provide a streamClient or durableStreamsUrl`

package/src/principal.ts

@@ -20,7 +20,7 @@ const PRINCIPAL_KINDS = new Set<PrincipalKind>([
 
 export function parsePrincipalKey(input: string): Principal {
   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) as PrincipalKind
   const id = input.slice(colon + 1)
   if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`)
@@ -33,24 +33,38 @@ export function principalUrl(key: string): string {
   return parsePrincipalKey(key).url
 }
 
-export function principalKeyFromUrl(url: string): string | null {
+export function parsePrincipalUrl(url: string): Principal | null {
   if (!url.startsWith(`/principal/`)) return null
   const segment = url.slice(`/principal/`.length)
   if (!segment || segment.includes(`/`)) return null
   try {
-    const key = decodeURIComponent(segment)
     // Principal URLs produced by parsePrincipalKey/principalUrl are canonical
     // encoded single path segments, but accept legacy unencoded single-segment
     // URLs here so callers can canonicalize them via parsePrincipalKey(key).url.
-    return parsePrincipalKey(key).key
+    return parsePrincipalKey(decodeURIComponent(segment))
   } catch {
     return null
   }
 }
 
+export function parsePrincipalInput(input: string): Principal | null {
+  const urlPrincipal = parsePrincipalUrl(input)
+  if (urlPrincipal) return urlPrincipal
+  try {
+    return parsePrincipalKey(input)
+  } catch {
+    return null
+  }
+}
+
+export function isPrincipalUrl(url: string): boolean {
+  return parsePrincipalUrl(url) !== null
+}
+
 export function getPrincipalFromRequest(request: Request): Principal | null {
   const value = request.headers.get(ELECTRIC_PRINCIPAL_HEADER)
-  return value ? parsePrincipalKey(value) : null
+  if (!value) return null
+  return parsePrincipalInput(value)
 }
 
 export function getDevPrincipal(): Principal {
@@ -66,9 +80,8 @@ const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
 export function isBuiltInSystemPrincipalUrl(url: string | undefined): boolean {
   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)
@@ -84,9 +97,8 @@ export function principalFromCreatedBy(
   | { url: string; key?: string | null; kind?: string; id?: string }
   | undefined {
   if (!createdBy) return undefined
-  const key = principalKeyFromUrl(createdBy)
-  if (!key) return { url: createdBy, key: null }
-  const principal = parsePrincipalKey(key)
+  const principal = parsePrincipalUrl(createdBy)
+  if (!principal) return { url: createdBy, key: null }
   return {
     url: principal.url,
     key: principal.key,

package/src/routing/context.ts

@@ -19,7 +19,7 @@ export interface TenantContext {
   principal: Principal
   publicUrl: string
   localUrl?: string
-  /** Resolved Durable Streams root URL for this tenant. */
+  /** Durable Streams backend URL prefix. Stream and control paths are appended as-is. */
   durableStreamsUrl: string
   durableStreamsBearer?: DurableStreamsBearerProvider
   durableStreamsRouting?: DurableStreamsRoutingAdapter