@electric-ax/agents-server 0.4.0 → 0.4.2

package/drizzle/0006_principals.sql

@@ -0,0 +1,5 @@
+ALTER TABLE entities
+  ADD COLUMN created_by text;
+
+CREATE INDEX idx_entities_created_by
+  ON entities (tenant_id, created_by);

package/drizzle/meta/_journal.json

@@ -43,6 +43,13 @@
       "when": 1776265200000,
       "tag": "0005_pull_wake_control_plane",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1776268800000,
+      "tag": "0006_principals",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.2.0"
+    "@electric-ax/agents-runtime": "0.2.1"
   },
   "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-server-conformance-tests": "0.1.3",
-    "@electric-ax/agents": "0.4.0",
-    "@electric-ax/agents-server-ui": "0.4.0"
+    "@electric-ax/agents": "0.4.1",
+    "@electric-ax/agents-server-conformance-tests": "0.1.4",
+    "@electric-ax/agents-server-ui": "0.4.2"
   },
   "files": [
     "dist",
@@ -80,7 +80,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "start": "cross-env-shell \"DATABASE_URL=${DATABASE_URL:-postgresql://electric_agents:electric_agents@localhost:5432/electric_agents} ELECTRIC_URL=${ELECTRIC_URL:-http://localhost:3060} tsx --watch src/entrypoint.ts\"",
+    "start": "cross-env-shell DATABASE_URL=${DATABASE_URL:-postgresql://electric_agents:electric_agents@localhost:5432/electric_agents} ELECTRIC_URL=${ELECTRIC_URL:-http://localhost:3060} \"tsx --watch src/entrypoint.ts\"",
     "test": "vitest run",
     "coverage": "ELECTRIC_AGENTS_KEEP_BACKEND=1 pnpm exec vitest run --coverage $(find test -name '*.test.ts' ! -name 'conformance.test.ts' | sort) && pnpm exec vitest run test/conformance.test.ts",
     "typecheck": "tsc --noEmit",

package/src/authenticated-user-format.ts

@@ -1,17 +1,7 @@
-import type { AuthenticatedRequestUser } from './electric-agents-types.js'
+import type { Principal } from './principal.js'
 
-function clean(value: string | undefined): string | undefined {
-  const trimmed = value?.trim()
-  return trimmed || undefined
-}
-
-export function formatAuthenticatedUser(
-  user: AuthenticatedRequestUser | null | undefined
+export function formatRequestPrincipal(
+  principal: Principal | null | undefined
 ): string | undefined {
-  if (!user) return undefined
-  const email = clean(user.email)
-  const name = clean(user.name)
-  const userId = clean(user.userId)
-  if (name && email) return `${name} <${email}>`
-  return email ?? name ?? userId
+  return principal?.key
 }

package/src/db/index.ts

@@ -16,7 +16,7 @@ export function createDb(postgresUrl: string): {
   const poolMax = Number(process.env.ELECTRIC_AGENTS_PG_POOL_MAX ?? `100`)
   const client = postgres(postgresUrl, {
     max: poolMax,
-    fetch_types: false,
+    fetch_types: true,
   })
   const db = drizzle(client, { schema })
   return { db, client }

package/src/db/schema.ts

@@ -50,6 +50,7 @@ export const entities = pgTable(
       .default(sql`'{}'::text[]`),
     spawnArgs: jsonb(`spawn_args`).default({}),
     parent: text(`parent`),
+    createdBy: text(`created_by`),
     typeRevision: integer(`type_revision`),
     inboxSchemas: jsonb(`inbox_schemas`),
     stateSchemas: jsonb(`state_schemas`),
@@ -61,6 +62,7 @@ export const entities = pgTable(
     index(`idx_entities_type`).on(table.tenantId, table.type),
     index(`idx_entities_status`).on(table.tenantId, table.status),
     index(`idx_entities_parent`).on(table.tenantId, table.parent),
+    index(`idx_entities_created_by`).on(table.tenantId, table.createdBy),
     index(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
     check(
       `chk_entities_status`,

package/src/electric-agents-types.ts

@@ -3,18 +3,14 @@
  */
 
 import type { WebhookNotification } from '@electric-ax/agents-runtime'
+import type { Principal } from './principal.js'
 
 type WakeNotification = WebhookNotification
 
-export interface AuthenticatedRequestUser {
-  userId: string
-  email?: string
-  name?: string
-}
-
+export type RequestPrincipal = Principal
 export type AuthenticateRequest = (
   request: Request
-) => Promise<AuthenticatedRequestUser | null> | AuthenticatedRequestUser | null
+) => Promise<Principal | null> | Principal | null
 
 export type EntityStatus = `spawning` | `running` | `idle` | `stopped`
 
@@ -211,6 +207,7 @@ export interface ElectricAgentsEntity {
   type_revision?: number
   inbox_schemas?: Record<string, Record<string, unknown>>
   state_schemas?: Record<string, Record<string, unknown>>
+  created_by?: string
   created_at: number
   updated_at: number
 }
@@ -225,6 +222,7 @@ export interface PublicElectricAgentsEntity {
   tags: Record<string, string>
   spawn_args?: Record<string, unknown>
   parent?: string
+  created_by?: string
   created_at: number
   updated_at: number
 }
@@ -248,6 +246,7 @@ export function toPublicEntity(
     tags: entity.tags,
     spawn_args: entity.spawn_args,
     parent: entity.parent,
+    created_by: entity.created_by,
     created_at: entity.created_at,
     updated_at: entity.updated_at,
   }
@@ -283,6 +282,7 @@ export interface TypedSpawnRequest {
   parent?: string
   dispatch_policy?: DispatchPolicy
   initialMessage?: unknown
+  created_by?: string
   wake?: {
     subscriberUrl: string
     condition:
@@ -303,6 +303,8 @@ export interface SendRequest {
   payload?: unknown
   key?: string
   type?: string
+  mode?: `immediate` | `queued` | `paused` | `steer`
+  position?: string
 }
 
 export interface SetTagRequest {
@@ -312,6 +314,7 @@ export interface SetTagRequest {
 export interface EntityListFilter {
   type?: string
   status?: EntityStatus
+  created_by?: string
 }
 
 export const ErrCodeDuplicateURL = `DUPLICATE_URL`

package/src/entity-bridge-manager.ts

@@ -70,7 +70,7 @@ const ENTITY_SHAPE_COLUMNS = [
 ] as const
 
 function parseElectricOffset(offset: string): Offset | null {
-  if (offset === `-1` || offset === `now`) {
+  if (offset === `-1`) {
     return offset
   }
   return /^\d+_\d+$/.test(offset) ? (offset as Offset) : null

package/src/entity-manager.ts

@@ -27,6 +27,14 @@ import {
   ErrCodeUnknownMessageType,
 } from './electric-agents-types.js'
 import { parseDispatchPolicy } from './dispatch-policy-schema.js'
+import { applyTypeDefaultSubscriptionScope } from './routing/dispatch-policy.js'
+import {
+  isBuiltInSystemPrincipalUrl,
+  principalFromCreatedBy,
+  principalUrl,
+  principalIdentityStateSchema,
+  principalUpdateIdentityMessageSchema,
+} from './principal.js'
 import { EntityAlreadyExistsError } from './entity-registry.js'
 import { serverLog } from './utils/log.js'
 import {
@@ -44,7 +52,6 @@ import type { SchemaValidator } from './electric-agents/schema-validator.js'
 import type { StreamClient } from './stream-client.js'
 import type {
   DispatchPolicy,
-  DispatchTarget,
   ElectricAgentsEntity,
   ElectricAgentsEntityType,
   RegisterEntityTypeRequest,
@@ -53,6 +60,7 @@ import type {
   TypedSpawnRequest,
 } from './electric-agents-types.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
+import type { Principal } from './principal.js'
 
 type SpawnPersistResult = [
   PromiseSettledResult<void>,
@@ -65,6 +73,10 @@ type WriteTokenValidator = (
   token: string
 ) => boolean
 
+function createInitialQueuePosition(date: Date): string {
+  return `${String(date.getTime()).padStart(16, `0`)}:a0`
+}
+
 type ForkSubtreeOptions = {
   rootInstanceId?: string
   waitTimeoutMs?: number
@@ -91,33 +103,6 @@ type ForkResult = {
 const DEFAULT_FORK_WAIT_TIMEOUT_MS = 120_000
 const DEFAULT_FORK_WAIT_POLL_MS = 250
 
-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
-}
-
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -239,6 +224,13 @@ export class EntityManager {
         400
       )
     }
+    if (req.name === `principal`) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `Entity type "principal" is built in and cannot be registered or updated`,
+        400
+      )
+    }
     if (req.name.startsWith(`_`)) {
       throw new ElectricAgentsError(
         ErrCodeInvalidRequest,
@@ -290,6 +282,13 @@ export class EntityManager {
   }
 
   async deleteEntityType(name: string): Promise<void> {
+    if (name === `principal`) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `Entity type "principal" is built in and cannot be deleted`,
+        400
+      )
+    }
     const existing = await this.registry.getEntityType(name)
     if (!existing) {
       throw new ElectricAgentsError(
@@ -302,6 +301,59 @@ export class EntityManager {
     await this.registry.deleteEntityType(name)
   }
 
+  async ensurePrincipalEntityType(): Promise<ElectricAgentsEntityType> {
+    const now = new Date().toISOString()
+    return await this.registry.ensureEntityType({
+      name: `principal`,
+      description: `built-in principal entity`,
+      inbox_schemas: { update_identity: principalUpdateIdentityMessageSchema },
+      state_schemas: { identity: principalIdentityStateSchema },
+      revision: 1,
+      created_at: now,
+      updated_at: now,
+    })
+  }
+
+  async ensurePrincipal(principal: Principal): Promise<ElectricAgentsEntity> {
+    const existing = await this.registry.getEntity(principal.url)
+    if (existing) return existing
+    await this.ensurePrincipalEntityType()
+    try {
+      const entity = await this.spawn(`principal`, {
+        instance_id: principal.key,
+        args: { kind: principal.kind, id: principal.id, key: principal.key },
+        tags: { principal_kind: principal.kind, principal_id: principal.id },
+        created_by: principal.url,
+      })
+      const now = new Date().toISOString()
+      await this.streamClient.append(
+        entity.streams.main,
+        this.encodeChangeEvent({
+          type: `identity`,
+          key: `self`,
+          value: {
+            kind: principal.kind,
+            id: principal.id,
+            key: principal.key,
+            url: principal.url,
+            created_at: now,
+            updated_at: now,
+          },
+        })
+      )
+      return entity
+    } catch (error) {
+      if (
+        error instanceof ElectricAgentsError &&
+        error.code === ErrCodeDuplicateURL
+      ) {
+        const raced = await this.registry.getEntity(principal.url)
+        if (raced) return raced
+      }
+      throw error
+    }
+  }
+
   // ==========================================================================
   // Spawn
   // ==========================================================================
@@ -328,6 +380,17 @@ export class EntityManager {
     typeName: string,
     req: TypedSpawnRequest
   ): Promise<ElectricAgentsEntity & { txid: number }> {
+    if (
+      typeName === `principal` &&
+      req.created_by !== principalUrl(req.instance_id)
+    ) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `Principal entities are built in and can only be materialized by the system`,
+        400
+      )
+    }
+
     if (typeName.startsWith(`_`)) {
       throw new ElectricAgentsError(
         ErrCodeInvalidRequest,
@@ -375,7 +438,10 @@ export class EntityManager {
 
     const writeToken = randomUUID()
 
-    const entityURL = `/${typeName}/${instanceId}`
+    const entityURL =
+      typeName === `principal`
+        ? principalUrl(instanceId)
+        : `/${typeName}/${instanceId}`
     const mainPath = `${entityURL}/main`
     const errorPath = `${entityURL}/error`
 
@@ -433,6 +499,7 @@ export class EntityManager {
       inbox_schemas: entityType.inbox_schemas,
       state_schemas: entityType.state_schemas,
       created_at: now,
+      created_by: req.created_by ?? parentEntity?.created_by,
       updated_at: now,
     }
     if (req.parent) {
@@ -473,7 +540,7 @@ export class EntityManager {
       const inboxEvent = entityStateSchema.inbox.insert({
         key: `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
         value: {
-          from: req.parent ?? `spawn`,
+          from: req.created_by ?? req.parent ?? `spawn`,
           payload: req.initialMessage,
           timestamp: msgNow,
         },
@@ -1371,10 +1438,10 @@ export class EntityManager {
           changed = true
         }
       }
-      if (typeof next.from === `string`) {
-        const forkFrom = entityUrlMap.get(next.from)
-        if (forkFrom) {
-          next.from = forkFrom
+      if (typeof next.senderUrl === `string`) {
+        const forkSender = entityUrlMap.get(next.senderUrl)
+        if (forkSender) {
+          next.senderUrl = forkSender
           changed = true
         }
       }
@@ -1490,6 +1557,10 @@ export class EntityManager {
     const fireAtRaw = manifest.fireAt
     const producerId = manifest.producerId
     const targetUrl = manifest.targetUrl
+    const senderUrl =
+      typeof manifest.senderUrl === `string`
+        ? manifest.senderUrl
+        : ownerEntityUrl
     if (
       typeof fireAtRaw !== `string` ||
       typeof producerId !== `string` ||
@@ -1514,8 +1585,7 @@ export class EntityManager {
       manifestKey,
       {
         entityUrl: targetUrl,
-        from:
-          typeof manifest.from === `string` ? manifest.from : ownerEntityUrl,
+        from: senderUrl,
         payload: manifest.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -1532,6 +1602,7 @@ export class EntityManager {
             kind: `schedule`,
             scheduleType: `future_send`,
             targetUrl,
+            senderUrl,
             fireAt: fireAt.toISOString(),
             producerId,
             status: `pending`,
@@ -1584,10 +1655,23 @@ export class EntityManager {
       from: req.from,
       payload: req.payload,
       timestamp: now,
+      mode: req.mode ?? `immediate`,
+      status:
+        req.mode === `queued` || req.mode === `paused`
+          ? `pending`
+          : `processed`,
     }
     if (req.type) {
       value.message_type = req.type
     }
+    if (req.position) {
+      value.position = req.position
+    } else if (value.mode === `queued` || value.mode === `paused`) {
+      value.position = createInitialQueuePosition(new Date(now))
+    }
+    if (value.status === `processed`) {
+      value.processed_at = now
+    }
 
     const envelope = entityStateSchema.inbox.insert({
       key,
@@ -1604,6 +1688,17 @@ export class EntityManager {
       }
 
       await this.streamClient.append(entity.streams.main, encoded)
+      if (entity.type === `principal` && req.type === `update_identity`) {
+        const identity = (req.payload as { identity?: unknown })?.identity
+        await this.streamClient.append(
+          entity.streams.main,
+          this.encodeChangeEvent({
+            type: `identity`,
+            key: `self`,
+            value: identity,
+          })
+        )
+      }
     } catch (err) {
       if (this.isClosedStreamError(err)) {
         throw new ElectricAgentsError(
@@ -1616,6 +1711,69 @@ export class EntityManager {
     }
   }
 
+  async updateInboxMessage(
+    entityUrl: string,
+    key: string,
+    req: {
+      payload?: unknown
+      position?: string
+      mode?: `immediate` | `queued` | `paused` | `steer`
+      status?: `pending` | `processed` | `cancelled`
+    }
+  ): Promise<void> {
+    const entity = await this.registry.getEntity(entityUrl)
+    if (!entity) {
+      throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404)
+    }
+    if (entity.status === `stopped`) {
+      throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409)
+    }
+
+    const now = new Date().toISOString()
+    const value: Record<string, unknown> = {}
+    if (`payload` in req) value.payload = req.payload
+    if (req.position !== undefined) value.position = req.position
+    if (req.mode !== undefined) value.mode = req.mode
+    if (req.status !== undefined) {
+      value.status = req.status
+      if (req.status === `processed`) value.processed_at = now
+      if (req.status === `cancelled`) value.cancelled_at = now
+    }
+
+    if (Object.keys(value).length === 0) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `No inbox fields to update`,
+        400
+      )
+    }
+
+    const envelope = entityStateSchema.inbox.update({
+      key,
+      value,
+    } as any)
+    await this.streamClient.append(
+      entity.streams.main,
+      this.encodeChangeEvent(envelope as Record<string, unknown>)
+    )
+  }
+
+  async deleteInboxMessage(entityUrl: string, key: string): Promise<void> {
+    const entity = await this.registry.getEntity(entityUrl)
+    if (!entity) {
+      throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404)
+    }
+    if (entity.status === `stopped`) {
+      throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409)
+    }
+
+    const envelope = entityStateSchema.inbox.delete({ key } as any)
+    await this.streamClient.append(
+      entity.streams.main,
+      this.encodeChangeEvent(envelope as Record<string, unknown>)
+    )
+  }
+
   // ==========================================================================
   // Tag Updates
   // ==========================================================================
@@ -1830,7 +1988,7 @@ export class EntityManager {
       payload: unknown
       targetUrl?: string
       fireAt: string
-      from?: string
+      senderUrl?: string
       messageType?: string
     }
   ): Promise<{ txid: string }> {
@@ -1839,7 +1997,7 @@ export class EntityManager {
     }
 
     const targetUrl = req.targetUrl ?? ownerEntityUrl
-    const from = req.from ?? ownerEntityUrl
+    const from = req.senderUrl ?? ownerEntityUrl
     const fireAt = new Date(req.fireAt)
     if (Number.isNaN(fireAt.getTime())) {
       throw new ElectricAgentsError(
@@ -1883,9 +2041,9 @@ export class EntityManager {
             scheduleType: `future_send`,
             fireAt: fireAt.toISOString(),
             targetUrl,
+            senderUrl: from,
             payload: req.payload,
             producerId,
-            ...(req.from ? { from: req.from } : {}),
             ...(req.messageType ? { messageType: req.messageType } : {}),
             status: `pending`,
           },
@@ -1906,9 +2064,9 @@ export class EntityManager {
         scheduleType: `future_send`,
         fireAt: fireAt.toISOString(),
         targetUrl,
+        senderUrl: from,
         payload: req.payload,
         producerId,
-        ...(req.from ? { from: req.from } : {}),
         ...(req.messageType ? { messageType: req.messageType } : {}),
         status: `pending`,
       },
@@ -1987,6 +2145,8 @@ export class EntityManager {
         payload: req.payload,
         key: req.key,
         type: req.type,
+        mode: req.mode,
+        position: req.position,
       },
       fireAt
     )
@@ -2308,6 +2468,14 @@ export class EntityManager {
       state_schemas?: Record<string, Record<string, unknown>>
     }
   ): Promise<ElectricAgentsEntityType> {
+    if (typeName === `principal`) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `Entity type "principal" is built in and cannot be amended`,
+        400
+      )
+    }
+
     // Validate each provided schema via validateSchemaSubset.
     this.validateSchemaMap(schemas.inbox_schemas)
     this.validateSchemaMap(schemas.state_schemas)
@@ -2400,8 +2568,10 @@ export class EntityManager {
         streams: entity.streams,
         tags: entity.tags,
         spawnArgs: entity.spawn_args,
+        createdBy: entity.created_by,
       },
-      triggerEvent: `message_received`,
+      principal: principalFromCreatedBy(entity.created_by),
+      triggerEvent: `inbox`,
     }
   }
 
@@ -2491,6 +2661,18 @@ export class EntityManager {
         400
       )
     }
+    if (
+      entity.type === `principal` &&
+      req.type === `update_identity` &&
+      !isBuiltInSystemPrincipalUrl(req.from)
+    ) {
+      throw new ElectricAgentsError(
+        ErrCodeUnauthorized,
+        `Only built-in system principals can update principal identity`,
+        403
+      )
+    }
+
     if (req.payload === undefined) {
       throw new ElectricAgentsError(
         ErrCodeInvalidRequest,