@electric-ax/agents-server 0.4.15 → 0.4.17

package/src/entity-bridge-manager.ts

@@ -3,6 +3,7 @@ import {
   assertTags,
   buildTagsIndex,
   getEntitiesStreamPath,
+  hashString,
   normalizeTags,
   sourceRefForTags,
 } from '@electric-ax/agents-runtime'
@@ -13,7 +14,9 @@ import {
 } from '@electric-sql/client'
 import { serverLog } from './utils/log.js'
 import { electricUrlWithPath } from './utils/electric-url.js'
+import { buildReadableEntitiesWhere } from './utils/server-utils.js'
 import { DEFAULT_TENANT_ID } from './tenant.js'
+import { isBuiltInSystemPrincipalUrl } from './principal.js'
 import type { EntityBridgeRow, PostgresRegistry } from './entity-registry.js'
 import type { StreamClient } from './stream-client.js'
 import type {
@@ -30,7 +33,11 @@ import type {
 export interface EntityBridgeCoordinator {
   start(): Promise<void>
   stop(): Promise<void>
-  register(tagsInput: unknown): Promise<{
+  register(
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }>
@@ -115,19 +122,44 @@ function sqlStringLiteral(value: string): string {
 
 function buildTenantTagsWhereClause(
   tenantId: string,
-  tags: EntityTags
+  tags: EntityTags,
+  principalUrl?: string,
+  principalKind?: string,
+  permissionBypass?: boolean
 ): string {
-  return `tenant_id = ${sqlStringLiteral(tenantId)} AND (${buildTagsWhereClause(tags)})`
+  const readableWhere =
+    principalUrl && principalKind
+      ? buildReadableEntitiesWhere({
+          tenantId,
+          principalUrl,
+          principalKind,
+          permissionBypass,
+        })
+      : `tenant_id = ${sqlStringLiteral(tenantId)} AND FALSE`
+  return `${readableWhere} AND (${buildTagsWhereClause(tags)})`
 }
 
 function shapeEntityKey(message: ChangeMessage<EntityShapeRow>): string {
   return message.value.url
 }
 
+function principalScopedSourceRef(
+  tagSourceRef: string,
+  principalUrl: string,
+  principalKind: string
+): string {
+  return `${tagSourceRef}-${hashString(
+    JSON.stringify({ principalKind, principalUrl })
+  )}`
+}
+
 class EntityBridge {
   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
@@ -152,6 +184,9 @@ class EntityBridge {
     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)
     this.initialShapeHandle = row.shapeHandle
     this.initialShapeOffset = row.shapeOffset
   }
@@ -316,7 +351,13 @@ class EntityBridge {
       url: electricUrlWithPath(this.electricUrl, `/v1/shape`).toString(),
       params: {
         table: `entities`,
-        where: buildTenantTagsWhereClause(this.tenantId, this.tags),
+        where: buildTenantTagsWhereClause(
+          this.tenantId,
+          this.tags,
+          this.principalUrl,
+          this.principalKind,
+          this.permissionBypass
+        ),
         ...(this.electricSecret ? { secret: this.electricSecret } : {}),
         columns: [...ENTITY_SHAPE_COLUMNS],
         replica: `full`,
@@ -564,7 +605,11 @@ export class EntityBridgeManager implements EntityBridgeCoordinator {
     )
   }
 
-  async register(tagsInput: unknown): Promise<{
+  async register(
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
@@ -573,13 +618,19 @@ export class EntityBridgeManager implements EntityBridgeCoordinator {
     }
 
     const tags = normalizeTags(assertTags(tagsInput))
-    const sourceRef = sourceRefForTags(tags)
+    const sourceRef = principalScopedSourceRef(
+      sourceRefForTags(tags),
+      principalUrl,
+      principalKind
+    )
     const streamUrl = getEntitiesStreamPath(sourceRef)
 
     const row = await this.registry.upsertEntityBridge({
       sourceRef,
       tags,
       streamUrl,
+      principalUrl,
+      principalKind,
     })
     await this.registry.touchEntityBridge(sourceRef)
     await this.ensureBridge(row)

package/src/entity-manager.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto'
 import fastq from 'fastq'
 import {
+  COMPOSER_INPUT_MESSAGE_TYPE,
   assertTags,
   entityStateSchema,
   getCronStreamPath,
@@ -11,6 +12,8 @@ import {
   manifestSharedStateKey,
   manifestSourceKey,
   resolveCronScheduleSpec,
+  validateComposerInputPayload,
+  validateSlashCommandDefinitions,
 } from '@electric-ax/agents-runtime'
 import type { EventPointer } from '@electric-ax/agents-runtime'
 import {
@@ -73,7 +76,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 +165,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
 }
@@ -431,6 +433,7 @@ export class EntityManager {
     this.validateSchema(req.creation_schema)
     this.validateSchemaMap(req.inbox_schemas)
     this.validateSchemaMap(req.state_schemas)
+    this.validateSlashCommands(req.slash_commands)
     const defaultDispatchPolicy = req.default_dispatch_policy
       ? this.validateDispatchPolicy(req.default_dispatch_policy, {
           label: `default_dispatch_policy`,
@@ -445,6 +448,7 @@ export class EntityManager {
       creation_schema: req.creation_schema,
       inbox_schemas: req.inbox_schemas,
       state_schemas: req.state_schemas,
+      slash_commands: req.slash_commands,
       serve_endpoint: req.serve_endpoint,
       default_dispatch_policy: defaultDispatchPolicy,
       revision: existing ? existing.revision + 1 : 1,
@@ -497,7 +501,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 +529,7 @@ export class EntityManager {
           },
         })
       )
+      await this.ensureUserPrincipal(principal)
       return entity
     } catch (error) {
       if (
@@ -529,12 +537,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 +641,6 @@ export class EntityManager {
         ? principalUrl(instanceId)
         : `/${typeName}/${instanceId}`
     const mainPath = `${entityURL}/main`
-    const errorPath = `${entityURL}/error`
 
     const subscriptionId = `${typeName}-handler`
 
@@ -676,7 +692,6 @@ export class EntityManager {
       url: entityURL,
       streams: {
         main: mainPath,
-        error: errorPath,
       },
       subscription_id: subscriptionId,
       dispatch_policy: dispatchPolicy,
@@ -725,6 +740,19 @@ export class EntityManager {
       createdEvent as Record<string, unknown>,
     ]
 
+    const slashCommandTimestamp = new Date().toISOString()
+    for (const command of entityType.slash_commands ?? []) {
+      const slashCommandEvent = entityStateSchema.slashCommands.insert({
+        key: command.name,
+        value: {
+          ...command,
+          source: `static`,
+          updated_at: slashCommandTimestamp,
+        },
+      } as any)
+      initialEvents.push(slashCommandEvent as Record<string, unknown>)
+    }
+
     if (req.initialMessage !== undefined) {
       const msgNow = new Date().toISOString()
       const inboxEvent = entityStateSchema.inbox.insert({
@@ -732,6 +760,7 @@ export class EntityManager {
         value: {
           from: req.created_by ?? req.parent ?? `spawn`,
           payload: req.initialMessage,
+          message_type: req.initialMessageType,
           timestamp: msgNow,
         },
       } as any)
@@ -745,8 +774,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 +785,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 +827,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 +853,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 +1062,8 @@ export class EntityManager {
       const entityPlans = this.buildForkEntityPlans(
         effectiveSubtree,
         entityUrlMap,
-        stringMap
+        stringMap,
+        opts.createdBy
       )
 
       this.addForkLocks(
@@ -1077,13 +1095,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 +1722,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 +1736,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 +1761,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 +2058,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 +2131,7 @@ export class EntityManager {
       {
         entityUrl: targetUrl,
         from: senderUrl,
+        from_agent: senderUrl,
         payload: manifest.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -2191,7 +2198,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 +2207,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 +2623,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 +2670,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 +2970,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 +3053,7 @@ export class EntityManager {
     })
   }
 
-  private async syncEntitiesManifestSource(
+  private async syncManifestLinks(
     entityUrl: string,
     manifestKey: string,
     operation: `insert` | `update` | `upsert` | `delete`,
@@ -3044,6 +3066,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 +3089,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 +3382,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 })
@@ -3494,7 +3531,9 @@ export class EntityManager {
       creation_schema: existing.creation_schema,
       inbox_schemas: mergedInbox,
       state_schemas: mergedState,
+      slash_commands: existing.slash_commands,
       serve_endpoint: existing.serve_endpoint,
+      default_dispatch_policy: existing.default_dispatch_policy,
       revision: nextRevision,
       created_at: existing.created_at,
       updated_at: now,
@@ -3583,6 +3622,20 @@ export class EntityManager {
     }
   }
 
+  private validateSlashCommands(input: unknown): void {
+    const validationError = validateSlashCommandDefinitions(input)
+    if (!validationError) {
+      return
+    }
+
+    throw new ElectricAgentsError(
+      ErrCodeSchemaValidationFailed,
+      validationError.message,
+      422,
+      validationError.details
+    )
+  }
+
   private async validateSendRequest(
     entityUrl: string,
     req: SendRequest
@@ -3599,7 +3652,17 @@ export class EntityManager {
       )
     }
 
-    if (req.type && entity.type) {
+    if (req.type === COMPOSER_INPUT_MESSAGE_TYPE) {
+      const valErr = validateComposerInputPayload(req.payload)
+      if (valErr) {
+        throw new ElectricAgentsError(
+          ErrCodeSchemaValidationFailed,
+          valErr.message,
+          422,
+          valErr.details
+        )
+      }
+    } else if (req.type && entity.type) {
       const { inboxSchemas } = await this.getEffectiveSchemas(entity)
       if (inboxSchemas) {
         const schema = inboxSchemas[req.type]