@electric-ax/agents-server 0.4.15 → 0.4.16

package/src/entity-manager.ts

@@ -73,7 +73,6 @@ import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { Principal } from './principal.js'
 
 type SpawnPersistResult = [
-  PromiseSettledResult<void>,
   PromiseSettledResult<void>,
   PromiseSettledResult<number>,
 ]
@@ -163,14 +162,14 @@ type ForkSubtreeOptions = {
   rootInstanceId?: string
   waitTimeoutMs?: number
   waitPollMs?: number
+  createdBy?: string
   /**
    * Optional anchor pointing at an event on the source root's `main` stream.
    * When set: only events at or before the pointer are kept on the root's
    * forked `main`, and the root's manifest is filtered so that descendants
    * spawned after the pointer are dropped from the fork (their now-orphan
    * subtrees are not forked). The pointer applies only to the root's
-   * `main` stream — `error` and shared-state streams clone at HEAD
-   * regardless.
+   * `main` stream; shared-state streams clone at HEAD regardless.
    */
   forkPointer?: EventPointer
 }
@@ -497,7 +496,10 @@ export class EntityManager {
 
   async ensurePrincipal(principal: Principal): Promise<ElectricAgentsEntity> {
     const existing = await this.registry.getEntity(principal.url)
-    if (existing) return existing
+    if (existing) {
+      await this.ensureUserPrincipal(principal)
+      return existing
+    }
     await this.ensurePrincipalEntityType()
     try {
       const entity = await this.spawn(`principal`, {
@@ -522,6 +524,7 @@ export class EntityManager {
           },
         })
       )
+      await this.ensureUserPrincipal(principal)
       return entity
     } catch (error) {
       if (
@@ -529,12 +532,21 @@ export class EntityManager {
         error.code === ErrCodeDuplicateURL
       ) {
         const raced = await this.registry.getEntity(principal.url)
-        if (raced) return raced
+        if (raced) {
+          await this.ensureUserPrincipal(principal)
+          return raced
+        }
       }
       throw error
     }
   }
 
+  private async ensureUserPrincipal(principal: Principal): Promise<void> {
+    if (principal.kind === `user`) {
+      await this.registry.ensureUserForPrincipal(principal)
+    }
+  }
+
   // ==========================================================================
   // Spawn
   // ==========================================================================
@@ -624,7 +636,6 @@ export class EntityManager {
         ? principalUrl(instanceId)
         : `/${typeName}/${instanceId}`
     const mainPath = `${entityURL}/main`
-    const errorPath = `${entityURL}/error`
 
     const subscriptionId = `${typeName}-handler`
 
@@ -676,7 +687,6 @@ export class EntityManager {
       url: entityURL,
       streams: {
         main: mainPath,
-        error: errorPath,
       },
       subscription_id: subscriptionId,
       dispatch_policy: dispatchPolicy,
@@ -745,8 +755,8 @@ export class EntityManager {
     const queueEnterT0 = performance.now()
     const queueWaiting = this.spawnPersistQueue.length()
     const queueRunning = this.spawnPersistQueue.running()
-    const [mainStreamResult, errorStreamResult, entityResult] =
-      await this.spawnPersistQueue.push(async () => {
+    const [mainStreamResult, entityResult] = await this.spawnPersistQueue.push(
+      async () => {
         // Create entity first so it's visible in the DB before stream
         // creation can trigger webhooks that look up the entity.
         let entityTxid: number
@@ -756,41 +766,34 @@ export class EntityManager {
           )
         } catch (err) {
           return [
-            { status: `fulfilled`, value: undefined },
             { status: `fulfilled`, value: undefined },
             { status: `rejected`, reason: err },
           ] as SpawnPersistResult
         }
 
-        const [mainStreamResult, errorStreamResult] = await Promise.allSettled([
+        const [mainStreamResult] = await Promise.allSettled([
           this.streamClient.create(mainPath, {
             contentType,
             body: initialBody,
           }),
-          this.streamClient.create(errorPath, { contentType }),
         ])
 
         return [
           mainStreamResult,
-          errorStreamResult,
           { status: `fulfilled`, value: entityTxid },
         ] as SpawnPersistResult
-      })
+      }
+    )
     const parallelMs = +(performance.now() - queueEnterT0).toFixed(2)
 
     if (
       mainStreamResult.status === `rejected` ||
-      errorStreamResult.status === `rejected` ||
       entityResult.status === `rejected`
     ) {
       const entityReason =
         entityResult.status === `rejected` ? entityResult.reason : null
       const streamReason =
-        mainStreamResult.status === `rejected`
-          ? mainStreamResult.reason
-          : errorStreamResult.status === `rejected`
-            ? errorStreamResult.reason
-            : null
+        mainStreamResult.status === `rejected` ? mainStreamResult.reason : null
       const isDuplicate = entityReason instanceof EntityAlreadyExistsError
       const isStreamConflict =
         !!streamReason &&
@@ -805,9 +808,6 @@ export class EntityManager {
         if (mainStreamResult.status === `fulfilled`) {
           rollbacks.push(this.streamClient.delete(mainPath))
         }
-        if (errorStreamResult.status === `fulfilled`) {
-          rollbacks.push(this.streamClient.delete(errorPath))
-        }
         if (entityResult.status === `fulfilled`) {
           rollbacks.push(this.registry.deleteEntity(entityURL))
         }
@@ -834,9 +834,7 @@ export class EntityManager {
       const failure =
         mainStreamResult.status === `rejected`
           ? mainStreamResult.reason
-          : errorStreamResult.status === `rejected`
-            ? errorStreamResult.reason
-            : (entityResult as PromiseRejectedResult).reason
+          : (entityResult as PromiseRejectedResult).reason
       if (failure instanceof Error) throw failure
       throw new ElectricAgentsError(
         `SPAWN_FAILED`,
@@ -1045,7 +1043,8 @@ export class EntityManager {
       const entityPlans = this.buildForkEntityPlans(
         effectiveSubtree,
         entityUrlMap,
-        stringMap
+        stringMap,
+        opts.createdBy
       )
 
       this.addForkLocks(
@@ -1077,13 +1076,6 @@ export class EntityManager {
               : undefined
           )
           createdStreams.push(plan.fork.streams.main)
-          // `error` always clones at HEAD — no canonical mapping
-          // between main-offset and error-offset.
-          await this.streamClient.fork(
-            plan.fork.streams.error,
-            plan.source.streams.error
-          )
-          createdStreams.push(plan.fork.streams.error)
         }
 
         for (const [sourceId, forkId] of sharedStateIdMap) {
@@ -1711,7 +1703,6 @@ export class EntityManager {
     for (const [sourceUrl, forkUrl] of entityUrlMap) {
       stringMap.set(sourceUrl, forkUrl)
       stringMap.set(`${sourceUrl}/main`, `${forkUrl}/main`)
-      stringMap.set(`${sourceUrl}/error`, `${forkUrl}/error`)
     }
     for (const [sourceId, forkId] of sharedStateIdMap) {
       stringMap.set(sourceId, forkId)
@@ -1726,7 +1717,8 @@ export class EntityManager {
   private buildForkEntityPlans(
     entitiesToFork: Array<ElectricAgentsEntity>,
     entityUrlMap: Map<string, string>,
-    stringMap: Map<string, string>
+    stringMap: Map<string, string>,
+    createdBy?: string
   ): Array<ForkEntityPlan> {
     const now = Date.now()
     return entitiesToFork.map((source) => {
@@ -1750,12 +1742,12 @@ export class EntityManager {
         status: `idle`,
         streams: {
           main: `${forkUrl}/main`,
-          error: `${forkUrl}/error`,
         },
         subscription_id: `${type}-handler`,
         write_token: randomUUID(),
         spawn_args: spawnArgs,
         parent,
+        created_by: createdBy ?? source.created_by,
         created_at: now,
         updated_at: now,
       }
@@ -2047,12 +2039,7 @@ export class EntityManager {
     manifests: Map<string, Record<string, unknown>>
   ): Promise<void> {
     for (const [manifestKey, manifest] of manifests) {
-      await this.syncEntitiesManifestSource(
-        entityUrl,
-        manifestKey,
-        `upsert`,
-        manifest
-      )
+      await this.syncManifestLinks(entityUrl, manifestKey, `upsert`, manifest)
 
       const wake = buildManifestWakeRegistration(
         entityUrl,
@@ -2125,6 +2112,7 @@ export class EntityManager {
       {
         entityUrl: targetUrl,
         from: senderUrl,
+        from_agent: senderUrl,
         payload: manifest.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -2191,7 +2179,7 @@ export class EntityManager {
       `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
 
     const value: Record<string, unknown> = {
-      from: req.from,
+      from: req.from_principal ?? req.from,
       payload: req.payload,
       timestamp: now,
       mode: req.mode ?? `immediate`,
@@ -2200,6 +2188,12 @@ export class EntityManager {
           ? `pending`
           : `processed`,
     }
+    if (req.from_principal) {
+      value.from_principal = req.from_principal
+    }
+    if (req.from_agent) {
+      value.from_agent = req.from_agent
+    }
     if (req.type) {
       value.message_type = req.type
     }
@@ -2610,14 +2604,21 @@ export class EntityManager {
     return updated
   }
 
-  async ensureEntitiesMembershipStream(tags: Record<string, string>): Promise<{
+  async ensureEntitiesMembershipStream(
+    tags: Record<string, string>,
+    principal: { url: string; kind: string }
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
     if (!this.entityBridgeManager) {
       throw new Error(`Entity bridge manager not configured`)
     }
-    return this.entityBridgeManager.register(this.validateTags(tags))
+    return this.entityBridgeManager.register(
+      this.validateTags(tags),
+      principal.url,
+      principal.kind
+    )
   }
 
   async writeManifestEntry(
@@ -2650,12 +2651,12 @@ export class EntityManager {
       await this.streamClient.appendIdempotent(entity.streams.main, encoded, {
         producerId: opts.producerId,
       })
-      await this.syncEntitiesManifestSource(entityUrl, key, operation, value)
+      await this.syncManifestLinks(entityUrl, key, operation, value)
       return
     }
 
     await this.streamClient.append(entity.streams.main, encoded)
-    await this.syncEntitiesManifestSource(entityUrl, key, operation, value)
+    await this.syncManifestLinks(entityUrl, key, operation, value)
   }
 
   async upsertCronSchedule(
@@ -2950,6 +2951,8 @@ export class EntityManager {
       {
         entityUrl,
         from: req.from,
+        from_principal: req.from_principal,
+        from_agent: req.from_agent,
         payload: req.payload,
         key: req.key,
         type: req.type,
@@ -3031,7 +3034,7 @@ export class EntityManager {
     })
   }
 
-  private async syncEntitiesManifestSource(
+  private async syncManifestLinks(
     entityUrl: string,
     manifestKey: string,
     operation: `insert` | `update` | `upsert` | `delete`,
@@ -3044,6 +3047,14 @@ export class EntityManager {
       manifestKey,
       sourceRef
     )
+
+    const sharedStateId =
+      operation === `delete` ? undefined : this.extractSharedStateId(value)
+    await this.registry.replaceSharedStateLink(
+      entityUrl,
+      manifestKey,
+      sharedStateId
+    )
   }
 
   private extractEntitiesSourceRef(
@@ -3059,6 +3070,24 @@ export class EntityManager {
     return undefined
   }
 
+  private extractSharedStateId(
+    manifest?: Record<string, unknown>
+  ): string | undefined {
+    if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) {
+      return manifest.id
+    }
+
+    if (manifest?.kind !== `source` || manifest.sourceType !== `db`) {
+      return undefined
+    }
+
+    if (typeof manifest.sourceRef === `string`) {
+      return manifest.sourceRef
+    }
+    const config = isRecord(manifest.config) ? manifest.config : undefined
+    return typeof config?.id === `string` ? config.id : undefined
+  }
+
   /**
    * Read a child entity's stream and extract concatenated text deltas
    * for a specific run, plus any error messages for that run.
@@ -3334,19 +3363,8 @@ export class EntityManager {
       return
     }
 
-    const errorCloseEvent = {
-      type: `signal`,
-      key: signalEvent.key,
-      value: signalEvent.value,
-      headers: signalEvent.headers,
-    }
-    const errorSignalData = this.encodeChangeEvent(
-      errorCloseEvent as unknown as Record<string, unknown>
-    )
-
     for (const [streamPath, data] of [
       [entity.streams.main, signalData],
-      [entity.streams.error, errorSignalData],
     ] as const) {
       try {
         await this.streamClient.append(streamPath, data, { close: true })

package/src/entity-projector.ts

@@ -3,6 +3,7 @@ import {
   assertTags,
   buildTagsIndex,
   getEntitiesStreamPath,
+  hashString,
   normalizeTags,
   sourceRefForTags,
 } from '@electric-ax/agents-runtime'
@@ -15,6 +16,7 @@ import { PostgresRegistry } from './entity-registry.js'
 import { electricUrlWithPath } from './utils/electric-url.js'
 import { serverLog } from './utils/log.js'
 import { isUnregisteredTenantError } from './tenant.js'
+import { isBuiltInSystemPrincipalUrl } from './principal.js'
 import type { DrizzleDB } from './db/index.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { EntityBridgeRow } from './entity-registry.js'
@@ -37,6 +39,7 @@ interface EntityShapeRow extends Row<unknown> {
   type: string
   status: `spawning` | `running` | `idle` | `stopped`
   tags: EntityTags
+  created_by?: string | null
   spawn_args?: Record<string, unknown> | null
   sandbox?: { profile: string } | null
   parent?: string | null
@@ -53,6 +56,7 @@ const ENTITY_SHAPE_COLUMNS = [
   `type`,
   `status`,
   `tags`,
+  `created_by`,
   `spawn_args`,
   `sandbox`,
   `parent`,
@@ -89,6 +93,16 @@ function sourceRefFromStreamPath(streamPath: string): string | null {
   return match?.[1] ?? null
 }
 
+function principalScopedSourceRef(
+  tagSourceRef: string,
+  principalUrl: string,
+  principalKind: string
+): string {
+  return `${tagSourceRef}-${hashString(
+    JSON.stringify({ principalKind, principalUrl })
+  )}`
+}
+
 function sameMember(
   left: EntityMembershipRow | undefined,
   right: EntityMembershipRow
@@ -125,6 +139,9 @@ class ProjectedEntityBridge {
   readonly sourceRef: string
   readonly tags: EntityTags
   readonly streamUrl: string
+  private readonly principalUrl?: string
+  private readonly principalKind?: string
+  private readonly permissionBypass: boolean
 
   private currentMembers = new Map<string, EntityMembershipRow>()
   private producer: IdempotentProducer | null = null
@@ -132,12 +149,16 @@ class ProjectedEntityBridge {
 
   constructor(
     row: EntityBridgeRow,
+    private registry: PostgresRegistry,
     private streamClient: StreamClient
   ) {
     this.tenantId = row.tenantId
     this.sourceRef = row.sourceRef
     this.tags = normalizeTags(row.tags)
     this.streamUrl = row.streamUrl
+    this.principalUrl = row.principalUrl
+    this.principalKind = row.principalKind
+    this.permissionBypass = isBuiltInSystemPrincipalUrl(row.principalUrl)
   }
 
   async start(initialEntities: Iterable<EntityShapeRow>): Promise<void> {
@@ -159,7 +180,7 @@ class ProjectedEntityBridge {
       }
     )
     await this.loadCurrentMembers()
-    this.reconcile(initialEntities)
+    await this.reconcile(initialEntities)
   }
 
   async stop(): Promise<void> {
@@ -175,13 +196,14 @@ class ProjectedEntityBridge {
     }
   }
 
-  reconcile(entities: Iterable<EntityShapeRow>): void {
+  async reconcile(entities: Iterable<EntityShapeRow>): Promise<void> {
     if (this.stopped) return
 
     const staleMembers = new Map(this.currentMembers)
     for (const entity of entities) {
       if (entity.tenant_id !== this.tenantId) continue
       if (!entityMatchesTags(entity, this.tags)) continue
+      if (!(await this.canReadEntity(entity))) continue
       staleMembers.delete(entity.url)
       this.upsertEntity(entity)
     }
@@ -192,11 +214,14 @@ class ProjectedEntityBridge {
     }
   }
 
-  applyEntity(entity: EntityShapeRow): void {
+  async applyEntity(entity: EntityShapeRow): Promise<void> {
     if (this.stopped) return
     if (entity.tenant_id !== this.tenantId) return
 
-    if (!entityMatchesTags(entity, this.tags)) {
+    if (
+      !entityMatchesTags(entity, this.tags) ||
+      !(await this.canReadEntity(entity))
+    ) {
       const existing = this.currentMembers.get(entity.url)
       if (!existing) return
       this.append(`delete`, existing)
@@ -231,6 +256,16 @@ class ProjectedEntityBridge {
     }
   }
 
+  private async canReadEntity(entity: EntityShapeRow): Promise<boolean> {
+    if (this.permissionBypass) return true
+    if (!this.principalUrl || !this.principalKind) return false
+    if (entity.created_by === this.principalUrl) return true
+    return await this.registry.hasEntityPermission(entity.url, `read`, {
+      principalUrl: this.principalUrl,
+      principalKind: this.principalKind,
+    })
+  }
+
   private async ensureStream(): Promise<void> {
     if (!(await this.streamClient.exists(this.streamUrl))) {
       await this.streamClient.create(this.streamUrl, {
@@ -377,7 +412,9 @@ export class EntityProjector {
   async register(
     tenantId: string,
     registry: PostgresRegistry,
-    tagsInput: unknown
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
   ): Promise<{ sourceRef: string; streamUrl: string }> {
     if (!this.electricUrl) {
       throw new Error(
@@ -388,12 +425,18 @@ export class EntityProjector {
     await this.start()
     this.registries.set(tenantId, registry)
     const tags = normalizeTags(assertTags(tagsInput))
-    const sourceRef = sourceRefForTags(tags)
+    const sourceRef = principalScopedSourceRef(
+      sourceRefForTags(tags),
+      principalUrl,
+      principalKind
+    )
     const streamUrl = getEntitiesStreamPath(sourceRef)
     const row = await registry.upsertEntityBridge({
       sourceRef,
       tags,
       streamUrl,
+      principalUrl,
+      principalKind,
     })
     await registry.touchEntityBridge(sourceRef)
     await this.ensureProjection(row)
@@ -436,8 +479,12 @@ export class EntityProjector {
     }
   }
 
-  async onEntityChanged(_tenantId: string, _entityUrl: string): Promise<void> {
-    // Membership updates come from the shared Electric entities shape.
+  async onEntityChanged(tenantId: string, entityUrl: string): Promise<void> {
+    const entity = this.entities.get(entityKey(tenantId, entityUrl))
+    if (!entity) return
+    for (const projection of this.projectionsForTenant(tenantId)) {
+      await projection.applyEntity(entity)
+    }
   }
 
   async loadTenantBridges(
@@ -523,18 +570,20 @@ export class EntityProjector {
         }
         if (message.headers.control === `up-to-date`) {
           this.upToDate = true
-          this.reconcileAll()
+          await this.reconcileAll()
           this.readyResolve?.()
         }
         continue
       }
 
       if (!isChangeMessage(message)) continue
-      this.applyChangeMessage(message)
+      await this.applyChangeMessage(message)
     }
   }
 
-  private applyChangeMessage(message: ChangeMessage<EntityShapeRow>): void {
+  private async applyChangeMessage(
+    message: ChangeMessage<EntityShapeRow>
+  ): Promise<void> {
     const entity = message.value
     const key = entityKey(entity.tenant_id, entity.url)
     if (message.headers.operation === `delete`) {
@@ -550,7 +599,7 @@ export class EntityProjector {
     this.entities.set(key, entity)
     if (this.upToDate) {
       for (const projection of this.projectionsForTenant(entity.tenant_id)) {
-        projection.applyEntity(entity)
+        await projection.applyEntity(entity)
       }
     }
   }
@@ -642,7 +691,11 @@ export class EntityProjector {
         }
         throw error
       }
-      const projection = new ProjectedEntityBridge(row, streamClient)
+      const projection = new ProjectedEntityBridge(
+        row,
+        this.registryForTenant(row.tenantId),
+        streamClient
+      )
       await projection.start(this.entitiesForTenant(row.tenantId))
       this.projections.set(key, projection)
     })().finally(() => {
@@ -665,9 +718,9 @@ export class EntityProjector {
     )
   }
 
-  private reconcileAll(): void {
+  private async reconcileAll(): Promise<void> {
     for (const projection of this.projections.values()) {
-      projection.reconcile(this.entitiesForTenant(projection.tenantId))
+      await projection.reconcile(this.entitiesForTenant(projection.tenantId))
     }
   }
 
@@ -733,14 +786,20 @@ export class EntityProjectorTenantFacade implements EntityBridgeCoordinator {
 
   async stop(): Promise<void> {}
 
-  async register(tagsInput: unknown): Promise<{
+  async register(
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
     return await this.projector.register(
       this.tenantId,
       this.registry,
-      tagsInput
+      tagsInput,
+      principalUrl,
+      principalKind
     )
   }