@electric-ax/agents-server 0.3.0

package/src/manifest-side-effects.ts

@@ -0,0 +1,183 @@
+import {
+  getCronStreamPathFromSpec,
+  getSharedStateStreamPath,
+  resolveCronScheduleSpec,
+} from '@electric-ax/agents-runtime'
+import type { WakeRegistration } from './wake-registry.js'
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === `object` && value !== null && !Array.isArray(value)
+}
+
+export function extractManifestSourceUrl(
+  manifest: Record<string, unknown> | undefined
+): string | undefined {
+  if (!manifest) return undefined
+
+  if (manifest.kind === `child` || manifest.kind === `observe`) {
+    return typeof manifest.entity_url === `string`
+      ? manifest.entity_url
+      : undefined
+  }
+
+  if (manifest.kind === `source`) {
+    const config = isRecord(manifest.config) ? manifest.config : undefined
+
+    if (manifest.sourceType === `entity`) {
+      return typeof config?.entityUrl === `string`
+        ? config.entityUrl
+        : typeof manifest.sourceRef === `string`
+          ? manifest.sourceRef
+          : undefined
+    }
+
+    if (manifest.sourceType === `cron` && config) {
+      const expression = config.expression
+      if (typeof expression === `string`) {
+        return getCronStreamPathFromSpec(
+          resolveCronScheduleSpec(
+            expression,
+            typeof config.timezone === `string` ? config.timezone : undefined,
+            { fallback: `utc` }
+          )
+        )
+      }
+    }
+
+    if (manifest.sourceType === `entities`) {
+      return typeof manifest.sourceRef === `string`
+        ? `/_entities/${manifest.sourceRef}`
+        : undefined
+    }
+
+    if (manifest.sourceType === `db`) {
+      return typeof manifest.sourceRef === `string`
+        ? getSharedStateStreamPath(manifest.sourceRef)
+        : undefined
+    }
+
+    return undefined
+  }
+
+  if (manifest.kind === `shared-state`) {
+    return typeof manifest.id === `string`
+      ? getSharedStateStreamPath(manifest.id)
+      : undefined
+  }
+
+  if (
+    manifest.kind === `schedule` &&
+    manifest.scheduleType === `cron` &&
+    typeof manifest.expression === `string`
+  ) {
+    return getCronStreamPathFromSpec(
+      resolveCronScheduleSpec(
+        manifest.expression,
+        typeof manifest.timezone === `string` ? manifest.timezone : undefined,
+        { fallback: `utc` }
+      )
+    )
+  }
+
+  return undefined
+}
+
+export function extractManifestCronSpec(
+  manifest: Record<string, unknown> | undefined
+): { expression: string; timezone: string } | undefined {
+  if (!manifest) return undefined
+
+  if (manifest.kind === `source` && manifest.sourceType === `cron`) {
+    const config = isRecord(manifest.config) ? manifest.config : undefined
+    if (typeof config?.expression === `string`) {
+      return resolveCronScheduleSpec(
+        config.expression,
+        typeof config.timezone === `string` ? config.timezone : undefined,
+        { fallback: `utc` }
+      )
+    }
+  }
+
+  if (
+    manifest.kind === `schedule` &&
+    manifest.scheduleType === `cron` &&
+    typeof manifest.expression === `string`
+  ) {
+    return resolveCronScheduleSpec(
+      manifest.expression,
+      typeof manifest.timezone === `string` ? manifest.timezone : undefined,
+      { fallback: `utc` }
+    )
+  }
+
+  return undefined
+}
+
+export function buildManifestWakeRegistration(
+  subscriberUrl: string,
+  manifest: Record<string, unknown> | undefined,
+  manifestKey?: string
+): WakeRegistration | null {
+  if (!manifest) return null
+
+  const sourceUrl = extractManifestSourceUrl(manifest)
+  if (!sourceUrl) return null
+
+  const wake =
+    manifest.kind === `schedule` && manifest.scheduleType === `cron`
+      ? (manifest.wake ?? { on: `change` })
+      : manifest.wake
+
+  if (wake === `runFinished`) {
+    return {
+      subscriberUrl,
+      sourceUrl,
+      condition: `runFinished`,
+      oneShot: false,
+      manifestKey,
+    }
+  }
+
+  if (!isRecord(wake)) return null
+
+  if (wake.on === `runFinished`) {
+    return {
+      subscriberUrl,
+      sourceUrl,
+      condition: `runFinished`,
+      oneShot: false,
+      includeResponse:
+        typeof wake.includeResponse === `boolean`
+          ? wake.includeResponse
+          : undefined,
+      manifestKey,
+    }
+  }
+
+  if (wake.on !== `change`) return null
+
+  const collections = Array.isArray(wake.collections)
+    ? wake.collections.filter((c): c is string => typeof c === `string`)
+    : undefined
+  const ops = Array.isArray(wake.ops)
+    ? wake.ops.filter(
+        (op): op is `insert` | `update` | `delete` =>
+          op === `insert` || op === `update` || op === `delete`
+      )
+    : undefined
+
+  return {
+    subscriberUrl,
+    sourceUrl,
+    condition: {
+      on: `change`,
+      ...(collections ? { collections } : {}),
+      ...(ops ? { ops } : {}),
+    },
+    debounceMs:
+      typeof wake.debounceMs === `number` ? wake.debounceMs : undefined,
+    timeoutMs: typeof wake.timeoutMs === `number` ? wake.timeoutMs : undefined,
+    oneShot: false,
+    manifestKey,
+  }
+}

package/src/routing/agent-ui-router.ts

@@ -0,0 +1,81 @@
+/**
+ * Serves the bundled agent UI from packages/agents-server-ui/dist.
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Router, status } from 'itty-router'
+import { apiError } from '../electric-agents-http.js'
+import { ErrCodeAgentUiNotFound } from '../electric-agents-types.js'
+import {
+  cacheControlForAgentUiFile,
+  contentTypeForStaticFile,
+  pickAgentUiFile,
+  resolveAgentUiPath,
+} from '../utils/server-utils.js'
+import type { IRequest, RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+function resolveAgentUiDistDir(fromUrl = import.meta.url): string {
+  const moduleDir = path.dirname(fileURLToPath(fromUrl))
+  const candidates = [
+    path.resolve(moduleDir, `../../../agents-server-ui/dist`),
+    path.resolve(moduleDir, `../../agents-server-ui/dist`),
+    path.resolve(process.cwd(), `packages/agents-server-ui/dist`),
+  ]
+  return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0]!
+}
+
+const AGENT_UI_DIST_DIR = resolveAgentUiDistDir()
+
+export type AgentUiRoutes = RouterType<
+  IRequest,
+  [TenantContext],
+  Response | undefined
+>
+
+export const agentUiRouter: AgentUiRoutes = Router<
+  IRequest,
+  [TenantContext],
+  Response | undefined
+>({
+  base: `/__agent_ui`,
+})
+
+agentUiRouter.get(`/*`, serveAgentUi)
+agentUiRouter.head(`/*`, serveAgentUi)
+agentUiRouter.all(`*`, () => status(404))
+
+async function serveAgentUi(request: IRequest): Promise<Response> {
+  const requestPath = new URL(request.url).pathname
+  const relativePath = decodeURIComponent(
+    requestPath.slice(`/__agent_ui/`.length)
+  )
+  const requestedFile = relativePath.length === 0 ? `index.html` : relativePath
+  const filePath = resolveAgentUiPath(AGENT_UI_DIST_DIR, requestedFile)
+  const fallbackToIndex =
+    path.extname(requestedFile) === `` || requestedFile.endsWith(`/`)
+  const resolvedFile = await pickAgentUiFile(
+    AGENT_UI_DIST_DIR,
+    filePath,
+    fallbackToIndex
+  )
+
+  if (!resolvedFile) {
+    return apiError(
+      404,
+      ErrCodeAgentUiNotFound,
+      `Agent UI build artifacts are missing`
+    )
+  }
+
+  const body = request.method === `HEAD` ? null : await readFile(resolvedFile)
+  return new Response(body, {
+    headers: {
+      'content-type': contentTypeForStaticFile(resolvedFile),
+      'cache-control': cacheControlForAgentUiFile(resolvedFile),
+    },
+  })
+}

package/src/routing/context.ts

@@ -0,0 +1,35 @@
+import type { Agent } from 'undici'
+import type { DrizzleDB } from '../db/index.js'
+import type { EntityBridgeCoordinator } from '../entity-bridge-manager.js'
+import type { EntityManager } from '../entity-manager.js'
+import type { ElectricAgentsTenantRuntime } from '../runtime.js'
+import type { StreamClient } from '../stream-client.js'
+import type { DurableStreamsRoutingAdapter } from './durable-streams-routing-adapter.js'
+import type { AuthenticatedRequestUser } from '../electric-agents-types.js'
+import type { DurableStreamsBearerProvider } from '../stream-client.js'
+
+/**
+ * Per-request tenant context passed through every router and handler.
+ *
+ * The OSS server builds this from its single runtime. Library-mode callers can
+ * build one per request and call `globalRouter.fetch(request, ctx)` directly.
+ */
+export interface TenantContext {
+  service: string
+  authenticatedUser?: AuthenticatedRequestUser
+  publicUrl: string
+  localUrl?: string
+  durableStreamsUrl: string
+  durableStreamsBearer?: DurableStreamsBearerProvider
+  durableStreamsRouting?: DurableStreamsRoutingAdapter
+  durableStreamsDispatcher: Agent
+  electricUrl?: string
+  electricSecret?: string
+  ownAgentHandlerPaths?: ReadonlyArray<string>
+  pgDb: DrizzleDB
+  entityManager: EntityManager
+  streamClient: StreamClient
+  runtime: ElectricAgentsTenantRuntime
+  entityBridgeManager: EntityBridgeCoordinator
+  isShuttingDown: () => boolean
+}

package/src/routing/cron-router.ts

@@ -0,0 +1,45 @@
+/**
+ * HTTP routes under /_electric/cron.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+import { Router, json } from 'itty-router'
+import { routeBody, withSchema } from './schema.js'
+import type { JsonRouteRequest } from './schema.js'
+import type { RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+const cronRegisterBodySchema = Type.Object({
+  expression: Type.String(),
+  timezone: Type.Optional(Type.String()),
+})
+
+type CronRegisterBody = Static<typeof cronRegisterBodySchema>
+
+export type CronRoutes = RouterType<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>
+
+export const cronRouter: CronRoutes = Router<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>({
+  base: `/_electric/cron`,
+})
+
+cronRouter.post(`/register`, withSchema(cronRegisterBodySchema), registerCron)
+
+async function registerCron(
+  request: JsonRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<CronRegisterBody>(request)
+  const streamPath = await ctx.entityManager.getOrCreateCronStream(
+    parsed.expression,
+    parsed.timezone
+  )
+  return json({ streamUrl: streamPath })
+}

package/src/routing/dispatch-policy.ts

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto'
+import { appendPathToUrl } from '@electric-ax/agents-runtime'
+import { subscriptionWebhooks } from '../db/schema.js'
+import { ElectricAgentsError } from '../entity-manager.js'
+import {
+  ErrCodeInvalidRequest,
+  ErrCodeNotFound,
+  ErrCodeUnauthorized,
+} from '../electric-agents-types.js'
+import { runnerWakeStream } from '../entity-registry.js'
+import { rewriteLoopbackWebhookUrl } from '../utils/webhook-url.js'
+import type {
+  DispatchPolicy,
+  DispatchTarget,
+  ElectricAgentsEntity,
+} from '../electric-agents-types.js'
+import type { TenantContext } from './context.js'
+
+export function subscriptionIdForDispatchTarget(
+  target: DispatchTarget
+): string {
+  if (target.subscription_id) return target.subscription_id
+  if (target.type === `runner`) return `runner:${target.runnerId}`
+  const digest = createHash(`sha256`).update(target.url).digest(`hex`)
+  return `webhook:${digest.slice(0, 16)}`
+}
+
+function subscriptionIdForEntityDispatchTarget(
+  target: DispatchTarget,
+  entityUrl: string
+): string {
+  const base = subscriptionIdForDispatchTarget(target)
+  if (!target.subscription_id) return base
+  const digest = createHash(`sha256`).update(entityUrl).digest(`hex`)
+  return `${base}:${digest.slice(0, 16)}`
+}
+
+export async function resolveEffectiveDispatchPolicyForSpawn(
+  ctx: TenantContext,
+  typeName: string,
+  opts: { dispatchPolicy?: DispatchPolicy; parent?: string }
+): Promise<DispatchPolicy | undefined> {
+  if (opts.dispatchPolicy) return opts.dispatchPolicy
+  const entityType = await ctx.entityManager.registry.getEntityType(typeName)
+  if (opts.parent) {
+    const parent = await ctx.entityManager.registry.getEntity(opts.parent)
+    if (parent?.dispatch_policy) {
+      return applyTypeDefaultSubscriptionScope(
+        parent.dispatch_policy,
+        entityType?.default_dispatch_policy
+      )
+    }
+  }
+  return entityType?.default_dispatch_policy
+}
+
+export async function resolveEffectiveDispatchPolicyForEntity(
+  ctx: TenantContext,
+  entity: ElectricAgentsEntity
+): Promise<DispatchPolicy | undefined> {
+  if (entity.dispatch_policy) return entity.dispatch_policy
+  const entityType = await ctx.entityManager.registry.getEntityType(entity.type)
+  return entityType?.default_dispatch_policy
+}
+
+export async function backfillEntityDispatchPolicy(
+  ctx: TenantContext,
+  entity: ElectricAgentsEntity
+): Promise<ElectricAgentsEntity> {
+  if (entity.dispatch_policy) return entity
+  const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(
+    ctx,
+    entity
+  )
+  if (!dispatchPolicy) return entity
+  return (
+    (await ctx.entityManager.registry.updateEntityDispatchPolicy(
+      entity.url,
+      dispatchPolicy
+    )) ?? { ...entity, dispatch_policy: dispatchPolicy }
+  )
+}
+
+function applyTypeDefaultSubscriptionScope(
+  policy: DispatchPolicy,
+  typeDefault: DispatchPolicy | undefined
+): DispatchPolicy {
+  const target = policy.targets[0]
+  const defaultTarget = typeDefault?.targets[0]
+  if (!target || !defaultTarget?.subscription_id) return policy
+  if (!sameDispatchDestination(target, defaultTarget)) return policy
+  if (target.subscription_id === defaultTarget.subscription_id) return policy
+
+  return {
+    targets: [{ ...target, subscription_id: defaultTarget.subscription_id }],
+  }
+}
+
+function sameDispatchDestination(
+  a: DispatchTarget,
+  b: DispatchTarget
+): boolean {
+  if (a.type !== b.type) return false
+  if (a.type === `runner` && b.type === `runner`) {
+    return a.runnerId === b.runnerId
+  }
+  if (a.type === `webhook` && b.type === `webhook`) return a.url === b.url
+  return false
+}
+
+export async function assertDispatchPolicyAllowed(
+  ctx: TenantContext,
+  policy: DispatchPolicy | undefined
+): Promise<void> {
+  const target = policy?.targets[0]
+  if (!target || target.type !== `runner`) return
+
+  const runner = await ctx.entityManager.registry.getRunner(target.runnerId)
+  if (!runner) {
+    throw new ElectricAgentsError(
+      ErrCodeNotFound,
+      `Runner "${target.runnerId}" not found`,
+      404
+    )
+  }
+  if (!ctx.authenticatedUser) {
+    throw new ElectricAgentsError(
+      ErrCodeUnauthorized,
+      `Authentication is required for runner-targeted dispatch`,
+      401
+    )
+  }
+  if (runner.owner_user_id !== ctx.authenticatedUser.userId) {
+    throw new ElectricAgentsError(
+      ErrCodeUnauthorized,
+      `Runner dispatch requires the authenticated owner`,
+      403
+    )
+  }
+}
+
+export async function linkEntityDispatchSubscription(
+  ctx: TenantContext,
+  entity: ElectricAgentsEntity
+): Promise<void> {
+  const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(
+    ctx,
+    entity
+  )
+  const target = dispatchPolicy?.targets[0]
+  if (!target) return
+  await linkStreamToTargetSubscription(ctx, target, entity)
+}
+
+export async function unlinkEntityDispatchSubscription(
+  ctx: TenantContext,
+  entity: ElectricAgentsEntity
+): Promise<void> {
+  const dispatchPolicy = await resolveEffectiveDispatchPolicyForEntity(
+    ctx,
+    entity
+  )
+  const target = dispatchPolicy?.targets[0]
+  if (!target) return
+  const subscriptionId = subscriptionIdForEntityDispatchTarget(
+    target,
+    entity.url
+  )
+  await ctx.streamClient
+    .removeSubscriptionStream(subscriptionId, entity.streams.main)
+    .catch(() => {})
+}
+
+async function linkStreamToTargetSubscription(
+  ctx: TenantContext,
+  target: DispatchTarget,
+  entity: ElectricAgentsEntity
+): Promise<void> {
+  const streamPath = entity.streams.main
+  const subscriptionId = subscriptionIdForEntityDispatchTarget(
+    target,
+    entity.url
+  )
+  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])
+    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, {
+      type: `webhook`,
+      streams: [streamPath],
+      webhook: { url: forwardUrl },
+      description: `Electric Agents webhook ${subscriptionId}`,
+    })
+  } else {
+    await ctx.streamClient.addSubscriptionStreams(subscriptionId, [streamPath])
+  }
+  await ctx.pgDb
+    .insert(subscriptionWebhooks)
+    .values({
+      tenantId: ctx.service,
+      subscriptionId,
+      webhookUrl,
+    })
+    .onConflictDoUpdate({
+      target: [
+        subscriptionWebhooks.tenantId,
+        subscriptionWebhooks.subscriptionId,
+      ],
+      set: { webhookUrl },
+    })
+}