@electric-ax/agents-server 0.3.0

package/src/electric-agents/schema-validator.ts

@@ -0,0 +1,143 @@
+import Ajv from 'ajv'
+import {
+  ErrCodeInvalidRequest,
+  ErrCodeSchemaValidationFailed,
+} from '../electric-agents-types.js'
+
+export class SchemaValidator {
+  private ajv: Ajv
+
+  constructor() {
+    this.ajv = new Ajv({ allErrors: true })
+  }
+
+  /**
+   * Validate data against a JSON Schema. Returns null if valid.
+   * Returns error details on failure.
+   */
+  validate(
+    schema: Record<string, unknown>,
+    data: unknown
+  ): {
+    code: string
+    message: string
+    details: Array<{ path: string; message: string }>
+  } | null {
+    const validate = this.ajv.compile(schema)
+    if (validate(data)) return null
+
+    return {
+      code: ErrCodeSchemaValidationFailed,
+      message: `Validation failed`,
+      details: (validate.errors ?? []).map((err) => ({
+        path: err.instancePath || `/`,
+        message: err.message ?? `validation error`,
+      })),
+    }
+  }
+
+  /**
+   * Check that a JSON Schema only uses allowed keywords.
+   * Returns null if valid, error details if disallowed keywords found.
+   */
+  validateSchemaSubset(schema: Record<string, unknown>): {
+    code: string
+    message: string
+    details: Array<{ path: string; message: string }>
+  } | null {
+    // Recursively walk the schema and check each key
+    const disallowed = this.findDisallowedKeywords(schema, ``)
+    if (disallowed.length === 0) return null
+
+    return {
+      code: ErrCodeInvalidRequest,
+      message: `Schema uses disallowed keywords`,
+      details: disallowed,
+    }
+  }
+
+  private findDisallowedKeywords(
+    obj: Record<string, unknown>,
+    path: string
+  ): Array<{ path: string; message: string }> {
+    const issues: Array<{ path: string; message: string }> = []
+
+    for (const [key, value] of Object.entries(obj)) {
+      if (!ALLOWED_SCHEMA_KEYWORDS.has(key)) {
+        issues.push({
+          path: path ? `${path}/${key}` : `/${key}`,
+          message: `Disallowed keyword: ${key}`,
+        })
+      }
+
+      if (Array.isArray(value)) {
+        if (key === `anyOf` || key === `oneOf` || key === `allOf`) {
+          for (const [index, item] of value.entries()) {
+            if (isPlainObject(item)) {
+              issues.push(
+                ...this.findDisallowedKeywords(item, `${path}/${key}/${index}`)
+              )
+            }
+          }
+        }
+        continue
+      }
+
+      if (!isPlainObject(value)) continue
+
+      if (key === `properties` || key === `$defs` || key === `definitions`) {
+        for (const [subKey, subValue] of Object.entries(value)) {
+          if (isPlainObject(subValue)) {
+            issues.push(
+              ...this.findDisallowedKeywords(
+                subValue,
+                `${path}/${key}/${subKey}`
+              )
+            )
+          }
+        }
+      } else if (key === `items`) {
+        issues.push(...this.findDisallowedKeywords(value, `${path}/items`))
+      }
+    }
+
+    return issues
+  }
+}
+
+const ALLOWED_SCHEMA_KEYWORDS = new Set([
+  `type`,
+  `properties`,
+  `required`,
+  `enum`,
+  `const`,
+  `minimum`,
+  `maximum`,
+  `exclusiveMinimum`,
+  `exclusiveMaximum`,
+  `minLength`,
+  `maxLength`,
+  `pattern`,
+  `items`,
+  `minItems`,
+  `maxItems`,
+  `$ref`,
+  `anyOf`,
+  `oneOf`,
+  `allOf`,
+  `not`,
+  `format`,
+  `title`,
+  `description`,
+  `default`,
+  `additionalProperties`,
+  `nullable`,
+  `$schema`,
+  `$id`,
+  `$defs`,
+  `definitions`,
+])
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === `object` && !Array.isArray(value)
+}

package/src/electric-agents-http.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared HTTP utilities for Electric Agents route handlers.
+ */
+
+import { json } from 'itty-router'
+
+export function apiError(
+  status: number,
+  code: string,
+  message: string,
+  details?: unknown
+): Response {
+  return json(
+    {
+      error: {
+        code,
+        message,
+        ...(details ? { details } : {}),
+      },
+    },
+    { status }
+  )
+}
+
+export async function readRequestBody(request: Request): Promise<Uint8Array> {
+  return new Uint8Array(await request.arrayBuffer())
+}
+
+export function responseHeaders(response: Response): Record<string, string> {
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, key) => {
+    if (
+      key === `content-encoding` ||
+      key === `content-length` ||
+      key === `transfer-encoding` ||
+      key === `connection` ||
+      key.startsWith(`access-control-`)
+    ) {
+      return
+    }
+    headers[key] = value
+  })
+  headers[`access-control-allow-origin`] = `*`
+  headers[`access-control-expose-headers`] = `*`
+  return headers
+}

package/src/electric-agents-types.ts

@@ -0,0 +1,335 @@
+/**
+ * Types for the Electric Agents entity runtime.
+ */
+
+import type { WebhookNotification } from '@electric-ax/agents-runtime'
+
+type WakeNotification = WebhookNotification
+
+export interface AuthenticatedRequestUser {
+  userId: string
+  email?: string
+  name?: string
+}
+
+export type AuthenticateRequest = (
+  request: Request
+) => Promise<AuthenticatedRequestUser | null> | AuthenticatedRequestUser | null
+
+export type EntityStatus = `spawning` | `running` | `idle` | `stopped`
+
+const VALID_ENTITY_STATUSES = new Set<string>([
+  `spawning`,
+  `running`,
+  `idle`,
+  `stopped`,
+])
+
+export function assertEntityStatus(s: string): EntityStatus {
+  if (!VALID_ENTITY_STATUSES.has(s)) {
+    throw new Error(`Invalid entity status: "${s}"`)
+  }
+  return s as EntityStatus
+}
+
+export type DispatchTarget =
+  | { type: `webhook`; url: string; subscription_id?: string }
+  | { type: `runner`; runnerId: string; subscription_id?: string }
+
+export interface DispatchPolicy {
+  readonly targets: readonly [DispatchTarget, ...ReadonlyArray<DispatchTarget>]
+}
+
+export type RunnerKind = `local` | `cloud-worker` | `sandbox` | `ci` | `server`
+export type RunnerAdminStatus = `enabled` | `disabled`
+export type RunnerLiveness = `online` | `offline`
+
+const VALID_RUNNER_KINDS = new Set<string>([
+  `local`,
+  `cloud-worker`,
+  `sandbox`,
+  `ci`,
+  `server`,
+])
+const VALID_RUNNER_ADMIN_STATUSES = new Set<string>([`enabled`, `disabled`])
+
+export function assertRunnerKind(s: string): RunnerKind {
+  if (!VALID_RUNNER_KINDS.has(s)) {
+    throw new Error(`Invalid runner kind: "${s}"`)
+  }
+  return s as RunnerKind
+}
+
+export function assertRunnerAdminStatus(s: string): RunnerAdminStatus {
+  if (!VALID_RUNNER_ADMIN_STATUSES.has(s)) {
+    throw new Error(`Invalid runner admin status: "${s}"`)
+  }
+  return s as RunnerAdminStatus
+}
+
+export type WakeDeliveryStatus =
+  | `queued`
+  | `delivered`
+  | `failed`
+  | `superseded`
+export type WakeClaimStatus = `unclaimed` | `claimed` | `completed` | `expired`
+export type ConsumerClaimStatus = `active` | `released` | `expired` | `failed`
+
+export interface SourceStreamOffset {
+  path: string
+  offset: string
+}
+
+export type PublicWakeNotification = Omit<
+  WakeNotification,
+  `callback` | `claimToken` | `entity`
+> & {
+  entity?: NonNullable<WakeNotification[`entity`]>
+}
+
+export interface ElectricAgentsUser {
+  id: string
+  display_name?: string
+  email?: string
+  avatar_url?: string
+  auth_provider?: string
+  auth_subject?: string
+  profile: Record<string, unknown>
+  metadata: Record<string, unknown>
+  created_at: string
+  updated_at: string
+}
+
+export interface RunnerActiveClaim {
+  entityPath: string
+  consumerId: string
+  claimedAt: string
+  leaseExpiresAt?: string
+}
+
+export interface ElectricAgentsRunner {
+  id: string
+  owner_user_id: string
+  label: string
+  kind: RunnerKind
+  admin_status: RunnerAdminStatus
+  liveness?: RunnerLiveness
+  last_seen_at?: string
+  liveness_lease_expires_at?: string
+  active_claims?: Array<RunnerActiveClaim>
+  wake_stream: string
+  wake_stream_offset?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface RegisterRunnerRequest {
+  id: string
+  owner_user_id: string
+  label: string
+  kind?: RunnerKind
+  admin_status?: RunnerAdminStatus
+  wake_stream?: string
+}
+
+export interface RunnerHeartbeatRequest {
+  lease_ms?: number
+  wake_stream_offset?: string
+  wakeStreamOffset?: string
+  liveness_lease_expires_at?: string
+}
+
+export interface EntityDispatchState {
+  entity_url: string
+  pending_source_streams: Array<SourceStreamOffset>
+  pending_reason?: string
+  pending_since?: string
+  outstanding_wake_id?: string
+  outstanding_wake_target?: DispatchTarget
+  outstanding_wake_created_at?: string
+  active_consumer_id?: string
+  active_runner_id?: string
+  active_epoch?: number
+  active_claimed_at?: string
+  active_lease_expires_at?: string
+  last_wake_id?: string
+  last_claimed_at?: string
+  last_released_at?: string
+  last_completed_at?: string
+  last_error?: string
+  updated_at: string
+}
+
+export interface WakeNotificationRow {
+  wake_id: string
+  entity_url: string
+  target_type: DispatchTarget[`type`]
+  target_runner_id?: string
+  target_webhook_url?: string
+  target_worker_pool_id?: string
+  runner_wake_stream?: string
+  runner_wake_stream_offset?: string
+  notification_public: PublicWakeNotification
+  delivery_status: WakeDeliveryStatus
+  claim_status: WakeClaimStatus
+  created_at: string
+  delivered_at?: string
+  claimed_at?: string
+  resolved_at?: string
+}
+
+export interface ConsumerClaim {
+  consumer_id: string
+  epoch: number
+  wake_id?: string
+  entity_url: string
+  stream_path: string
+  runner_id?: string
+  status: ConsumerClaimStatus
+  claimed_at: string
+  last_heartbeat_at?: string
+  lease_expires_at?: string
+  released_at?: string
+  acked_streams?: Array<SourceStreamOffset>
+  updated_at: string
+}
+
+export interface ElectricAgentsEntity {
+  url: string
+  type: string
+  status: EntityStatus
+  streams: {
+    main: string
+    error: string
+  }
+  subscription_id: string
+  dispatch_policy?: DispatchPolicy
+  write_token: string
+  tags: Record<string, string>
+  spawn_args?: Record<string, unknown>
+  parent?: string
+  type_revision?: number
+  inbox_schemas?: Record<string, Record<string, unknown>>
+  state_schemas?: Record<string, Record<string, unknown>>
+  created_at: number
+  updated_at: number
+}
+
+/** Public-facing entity — internal fields stripped. Standalone type so new internal fields don't silently leak. */
+export interface PublicElectricAgentsEntity {
+  url: string
+  type: string
+  status: EntityStatus
+  streams: { main: string; error: string }
+  dispatch_policy?: DispatchPolicy
+  tags: Record<string, string>
+  spawn_args?: Record<string, unknown>
+  parent?: string
+  created_at: number
+  updated_at: number
+}
+
+/** Entity row as stored in Postgres / returned by Electric shapes (no derived `streams` field). */
+export type ElectricAgentsEntityRow = Omit<
+  PublicElectricAgentsEntity,
+  `streams`
+>
+
+/** Strip internal fields (write_token, subscription_id) from an entity. */
+export function toPublicEntity(
+  entity: ElectricAgentsEntity
+): PublicElectricAgentsEntity {
+  return {
+    url: entity.url,
+    type: entity.type,
+    status: entity.status,
+    streams: entity.streams,
+    dispatch_policy: entity.dispatch_policy,
+    tags: entity.tags,
+    spawn_args: entity.spawn_args,
+    parent: entity.parent,
+    created_at: entity.created_at,
+    updated_at: entity.updated_at,
+  }
+}
+
+export interface ElectricAgentsEntityType {
+  name: string
+  description: string
+  creation_schema?: Record<string, unknown>
+  inbox_schemas?: Record<string, Record<string, unknown>>
+  state_schemas?: Record<string, Record<string, unknown>>
+  serve_endpoint?: string
+  default_dispatch_policy?: DispatchPolicy
+  revision: number
+  created_at: string
+  updated_at: string
+}
+
+export interface RegisterEntityTypeRequest {
+  name: string
+  description: string
+  creation_schema?: Record<string, unknown>
+  inbox_schemas?: Record<string, Record<string, unknown>>
+  state_schemas?: Record<string, Record<string, unknown>>
+  serve_endpoint?: string
+  default_dispatch_policy?: DispatchPolicy
+}
+
+export interface TypedSpawnRequest {
+  instance_id: string
+  args?: Record<string, unknown>
+  tags?: Record<string, string>
+  parent?: string
+  dispatch_policy?: DispatchPolicy
+  initialMessage?: unknown
+  wake?: {
+    subscriberUrl: string
+    condition:
+      | `runFinished`
+      | {
+          on: `change`
+          collections?: Array<string>
+          ops?: Array<`insert` | `update` | `delete`>
+        }
+    debounceMs?: number
+    timeoutMs?: number
+    includeResponse?: boolean
+  }
+}
+
+export interface SendRequest {
+  from?: string
+  payload?: unknown
+  key?: string
+  type?: string
+}
+
+export interface SetTagRequest {
+  value: string
+}
+
+export interface EntityListFilter {
+  type?: string
+  status?: EntityStatus
+}
+
+export const ErrCodeDuplicateURL = `DUPLICATE_URL`
+export const ErrCodeUnauthorized = `UNAUTHORIZED`
+export const ErrCodeNoSubscription = `NO_SUBSCRIPTION`
+export const ErrCodeNotFound = `NOT_FOUND`
+export const ErrCodeNotRunning = `NOT_RUNNING`
+export const ErrCodeInvalidRequest = `INVALID_REQUEST`
+export const ErrCodeUnknownEntityType = `UNKNOWN_ENTITY_TYPE`
+export const ErrCodeSchemaValidationFailed = `SCHEMA_VALIDATION_FAILED`
+export const ErrCodeUnknownMessageType = `UNKNOWN_MESSAGE_TYPE`
+export const ErrCodeUnknownEventType = `UNKNOWN_EVENT_TYPE`
+export const ErrCodeSchemaKeyExists = `SCHEMA_KEY_EXISTS`
+export const ErrCodeServeEndpointUnreachable = `SERVE_ENDPOINT_UNREACHABLE`
+export const ErrCodeServeEndpointNameMismatch = `SERVE_ENDPOINT_NAME_MISMATCH`
+export const ErrCodeForkInProgress = `FORK_IN_PROGRESS`
+export const ErrCodeForkWaitTimeout = `FORK_WAIT_TIMEOUT`
+export const ErrCodeEntityPersistFailed = `ENTITY_PERSIST_FAILED`
+export const ErrCodeAgentUiNotFound = `AGENT_UI_NOT_FOUND`
+export const ErrCodeSubscriptionNotFound = `SUBSCRIPTION_NOT_FOUND`
+export const ErrCodeCallbackNotFound = `CALLBACK_NOT_FOUND`