@electric-ax/agents-server 0.4.14 → 0.4.16

package/src/routing/entity-types-router.ts

@@ -8,22 +8,27 @@ import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
 import { ElectricAgentsError } from '../entity-manager.js'
 import {
   ErrCodeNotFound,
+  ErrCodeInvalidRequest,
+  ErrCodeUnauthorized,
   ErrCodeServeEndpointNameMismatch,
   ErrCodeServeEndpointUnreachable,
 } from '../electric-agents-types.js'
 import { apiError } from '../electric-agents-http.js'
 import { routeBody, withSchema } from './schema.js'
 import { rewriteLoopbackWebhookUrl } from '../utils/webhook-url.js'
+import { canAccessEntityType, canRegisterEntityType } from '../permissions.js'
 import type {
   ElectricAgentsEntityType,
   RegisterEntityTypeRequest,
+  EntityTypePermissionGrantInput,
 } from '../electric-agents-types.js'
 import type { JsonRouteRequest } from './schema.js'
 import type { RouterType } from 'itty-router'
 import type { TenantContext } from './context.js'
 
-export interface ElectricAgentsEntityTypeRouteRequest
-  extends JsonRouteRequest {}
+export interface ElectricAgentsEntityTypeRouteRequest extends JsonRouteRequest {
+  entityTypeRoute?: { entityType: ElectricAgentsEntityType }
+}
 
 type EntityTypeRouteArgs = [TenantContext]
 type EntityTypeRouteResult = Response | undefined
@@ -41,6 +46,19 @@ type PublicEntityTypeResponse = ElectricAgentsEntityType & {
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown())
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema)
 
+const typePermissionGrantInputSchema = Type.Object(
+  {
+    subject_kind: Type.Union([
+      Type.Literal(`principal`),
+      Type.Literal(`principal_kind`),
+    ]),
+    subject_value: Type.String(),
+    permission: Type.Union([Type.Literal(`spawn`), Type.Literal(`manage`)]),
+    expires_at: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false }
+)
+
 const registerEntityTypeBodySchema = Type.Object(
   {
     name: Type.Optional(Type.String()),
@@ -50,6 +68,9 @@ const registerEntityTypeBodySchema = Type.Object(
     state_schemas: Type.Optional(schemaMapSchema),
     serve_endpoint: Type.Optional(Type.String()),
     default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+    permission_grants: Type.Optional(
+      Type.Array(typePermissionGrantInputSchema)
+    ),
   },
   { additionalProperties: false }
 )
@@ -66,6 +87,7 @@ type RegisterEntityTypeBody = Static<typeof registerEntityTypeBodySchema>
 type AmendEntityTypeSchemasBody = Static<
   typeof amendEntityTypeSchemasBodySchema
 >
+type TypePermissionGrantInput = EntityTypePermissionGrantInput
 
 export const entityTypesRouter: ElectricAgentsEntityTypeRoutes = Router<
   ElectricAgentsEntityTypeRouteRequest,
@@ -79,15 +101,47 @@ entityTypesRouter.get(`/`, listEntityTypes)
 entityTypesRouter.post(
   `/`,
   withSchema(registerEntityTypeBodySchema),
+  withEntityTypeRegistrationPermission,
   registerEntityType
 )
 entityTypesRouter.patch(
   `/:name/schemas`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
   withSchema(amendEntityTypeSchemasBodySchema),
   amendSchemas
 )
-entityTypesRouter.get(`/:name`, getEntityType)
-entityTypesRouter.delete(`/:name`, deleteEntityType)
+entityTypesRouter.get(
+  `/:name`,
+  withExistingEntityType,
+  withEntityTypeSpawnPermission,
+  getEntityType
+)
+entityTypesRouter.delete(
+  `/:name`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  deleteEntityType
+)
+entityTypesRouter.get(
+  `/:name/grants`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  listTypePermissionGrants
+)
+entityTypesRouter.post(
+  `/:name/grants`,
+  withExistingEntityType,
+  withSchema(typePermissionGrantInputSchema),
+  withEntityTypeManagePermission,
+  createTypePermissionGrant
+)
+entityTypesRouter.delete(
+  `/:name/grants/:grantId`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  deleteTypePermissionGrant
+)
 
 async function registerEntityType(
   request: ElectricAgentsEntityTypeRouteRequest,
@@ -105,6 +159,7 @@ async function registerEntityType(
   }
 
   const entityType = await ctx.entityManager.registerEntityType(normalized)
+  await applyRegistrationPermissionGrants(ctx, entityType.name, normalized)
   return json(toPublicEntityType(entityType), { status: 201 })
 }
 
@@ -113,7 +168,102 @@ async function listEntityTypes(
   ctx: TenantContext
 ): Promise<EntityTypeRouteResult> {
   const entityTypes = await ctx.entityManager.registry.listEntityTypes()
-  return json(entityTypes.map((entityType) => toPublicEntityType(entityType)))
+  const visible: Array<ElectricAgentsEntityType> = []
+  for (const entityType of entityTypes) {
+    if (await canAccessEntityType(ctx, entityType, `spawn`)) {
+      visible.push(entityType)
+    }
+  }
+  return json(visible.map((entityType) => toPublicEntityType(entityType)))
+}
+
+async function withExistingEntityType(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = await ctx.entityManager.registry.getEntityType(
+    request.params.name
+  )
+  if (!entityType) {
+    return apiError(404, ErrCodeNotFound, `Entity type not found`)
+  }
+  request.entityTypeRoute = { entityType }
+  return undefined
+}
+
+async function withEntityTypeManagePermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = request.entityTypeRoute?.entityType
+  if (!entityType) {
+    throw new Error(`entity type middleware did not run`)
+  }
+  if (
+    await canAccessEntityType(ctx, entityType, `manage`, request as Request)
+  ) {
+    return undefined
+  }
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to manage ${entityType.name}`
+  )
+}
+
+async function withEntityTypeSpawnPermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = request.entityTypeRoute?.entityType
+  if (!entityType) {
+    throw new Error(`entity type middleware did not run`)
+  }
+  if (await canAccessEntityType(ctx, entityType, `spawn`, request as Request)) {
+    return undefined
+  }
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to spawn ${entityType.name}`
+  )
+}
+
+async function withEntityTypeRegistrationPermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = normalizeEntityTypeRequest(
+    routeBody<RegisterEntityTypeBody>(request)
+  )
+  if (!parsed.name) {
+    return undefined
+  }
+
+  const existing = await ctx.entityManager.registry.getEntityType(parsed.name)
+  if (existing) {
+    request.entityTypeRoute = { entityType: existing }
+    if (
+      await canAccessEntityType(ctx, existing, `manage`, request as Request)
+    ) {
+      return undefined
+    }
+    return apiError(
+      401,
+      ErrCodeUnauthorized,
+      `Principal is not allowed to manage ${existing.name}`
+    )
+  }
+
+  if (await canRegisterEntityType(ctx, parsed, request as Request)) {
+    return undefined
+  }
+
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to register entity types`
+  )
 }
 
 async function discoverServeEndpoint(
@@ -141,10 +291,12 @@ async function discoverServeEndpoint(
     }
 
     manifest.serve_endpoint = parsed.serve_endpoint
+    manifest.permission_grants = parsed.permission_grants
 
     const entityType = await ctx.entityManager.registerEntityType(
       normalizeEntityTypeRequest(manifest)
     )
+    await applyRegistrationPermissionGrants(ctx, entityType.name, manifest)
     return json(toPublicEntityType(entityType), { status: 201 })
   } catch (err) {
     if (err instanceof ElectricAgentsError) {
@@ -161,17 +313,9 @@ async function discoverServeEndpoint(
 }
 
 async function getEntityType(
-  request: ElectricAgentsEntityTypeRouteRequest,
-  ctx: TenantContext
+  request: ElectricAgentsEntityTypeRouteRequest
 ): Promise<EntityTypeRouteResult> {
-  const entityType = await ctx.entityManager.registry.getEntityType(
-    request.params.name
-  )
-  if (!entityType) {
-    return apiError(404, ErrCodeNotFound, `Entity type not found`)
-  }
-
-  return json(toPublicEntityType(entityType))
+  return json(toPublicEntityType(request.entityTypeRoute!.entityType))
 }
 
 async function amendSchemas(
@@ -195,6 +339,90 @@ async function deleteEntityType(
   return status(204)
 }
 
+async function listTypePermissionGrants(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const grants =
+    await ctx.entityManager.registry.listEntityTypePermissionGrants(
+      request.entityTypeRoute!.entityType.name
+    )
+  return json({ grants })
+}
+
+async function createTypePermissionGrant(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = routeBody<TypePermissionGrantInput>(request)
+  const grant =
+    await ctx.entityManager.registry.createEntityTypePermissionGrant({
+      entityType: request.entityTypeRoute!.entityType.name,
+      permission: parsed.permission,
+      subjectKind: parsed.subject_kind,
+      subjectValue: parsed.subject_value,
+      expiresAt: parseExpiresAt(parsed.expires_at),
+      createdBy: ctx.principal.url,
+    })
+  return json(grant, { status: 201 })
+}
+
+async function deleteTypePermissionGrant(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const deleted =
+    await ctx.entityManager.registry.deleteEntityTypePermissionGrant(
+      request.entityTypeRoute!.entityType.name,
+      parseGrantId(request)
+    )
+  return deleted
+    ? status(204)
+    : apiError(404, ErrCodeNotFound, `Grant not found`)
+}
+
+async function applyRegistrationPermissionGrants(
+  ctx: TenantContext,
+  entityType: string,
+  request: Pick<RegisterEntityTypeRequest, `permission_grants`>
+): Promise<void> {
+  for (const grant of request.permission_grants ?? []) {
+    await ctx.entityManager.registry.ensureEntityTypePermissionGrant({
+      entityType,
+      permission: grant.permission,
+      subjectKind: grant.subject_kind,
+      subjectValue: grant.subject_value,
+      expiresAt: parseExpiresAt(grant.expires_at),
+      createdBy: ctx.principal.url,
+    })
+  }
+}
+
+function parseGrantId(request: ElectricAgentsEntityTypeRouteRequest): number {
+  const grantId = Number.parseInt(String(request.params.grantId), 10)
+  if (!Number.isSafeInteger(grantId) || grantId <= 0) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `Invalid grant id`,
+      400
+    )
+  }
+  return grantId
+}
+
+function parseExpiresAt(value: string | undefined): Date | undefined {
+  if (value === undefined) return undefined
+  const expiresAt = new Date(value)
+  if (Number.isNaN(expiresAt.getTime())) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `Invalid expires_at timestamp`,
+      400
+    )
+  }
+  return expiresAt
+}
+
 function normalizeEntityTypeRequest(
   parsed: RegisterEntityTypeBody | RegisterEntityTypeRequest
 ): RegisterEntityTypeRequest {
@@ -213,6 +441,7 @@ function normalizeEntityTypeRequest(
             targets: [{ type: `webhook`, url: serveEndpoint }],
           } as RegisterEntityTypeRequest[`default_dispatch_policy`])
         : undefined),
+    permission_grants: parsed.permission_grants,
   }
 }
 

package/src/routing/hooks.ts

@@ -85,6 +85,7 @@ export function applyCors(
       `content-type`,
       `authorization`,
       `electric-claim-token`,
+      `electric-owner-entity`,
       ELECTRIC_PRINCIPAL_HEADER,
       `ngrok-skip-browser-warning`,
     ].join(`, `)

package/src/routing/observations-router.ts

@@ -56,7 +56,8 @@ async function ensureEntitiesMembershipStream(
 ): Promise<Response> {
   const parsed = routeBody<EnsureEntitiesMembershipStreamBody>(request)
   const result = await ctx.entityManager.ensureEntitiesMembershipStream(
-    parsed.tags ?? {}
+    parsed.tags ?? {},
+    ctx.principal
   )
   return json(result)
 }

package/src/routing/runners-router.ts

@@ -34,6 +34,13 @@ export type RunnersRoutes = RouterType<
   RunnersRouteResult
 >
 
+const sandboxProfileBodySchema = Type.Object({
+  name: Type.String(),
+  label: Type.String(),
+  description: Type.Optional(Type.String()),
+  remote: Type.Optional(Type.Boolean()),
+})
+
 const registerRunnerBodySchema = Type.Object({
   id: Type.String(),
   owner_principal: Type.Optional(Type.String()),
@@ -51,6 +58,7 @@ const registerRunnerBodySchema = Type.Object({
     Type.Union([Type.Literal(`enabled`), Type.Literal(`disabled`)])
   ),
   wake_stream: Type.Optional(Type.String()),
+  sandbox_profiles: Type.Optional(Type.Array(sandboxProfileBodySchema)),
 })
 
 const heartbeatBodySchema = Type.Object({
@@ -234,6 +242,7 @@ async function registerRunner(
     kind: parsed.kind,
     adminStatus: parsed.admin_status,
     wakeStream: parsed.wake_stream,
+    sandboxProfiles: parsed.sandbox_profiles,
   })
   await ctx.streamClient.ensure(runner.wake_stream, {
     contentType: `application/json`,
@@ -639,6 +648,7 @@ async function notificationFromClaim(
       streams: entity.streams,
       tags: entity.tags,
       spawnArgs: entity.spawn_args,
+      sandbox: entity.sandbox,
       createdBy: entity.created_by,
     },
     principal: principalFromCreatedBy(entity.created_by),

package/src/routing/sandbox.ts

@@ -0,0 +1,173 @@
+import { ElectricAgentsError } from '../entity-manager.js'
+import { ErrCodeInvalidRequest } from '../electric-agents-types.js'
+import type {
+  DispatchPolicy,
+  ElectricAgentsEntity,
+  EntitySandboxSelection,
+  SandboxChoice,
+} from '../electric-agents-types.js'
+import type { PostgresRegistry } from '../entity-registry.js'
+
+/**
+ * Resolve and validate a spawn's sandbox CHOICE into the {@link
+ * EntitySandboxSelection} persisted on the entity. Sibling of
+ * `dispatch-policy.ts`'s `resolveEffectiveDispatchPolicyForSpawn`: kept off the
+ * EntityManager so the spawn path reads as composed resolution steps.
+ *
+ * Profiles are a per-runner concern: each runner advertises what it supports.
+ * When the spawn pins a runner via dispatch_policy, the chosen profile must be
+ * in that runner's advertised set; otherwise we'd persist an unserviceable
+ * choice that fails late at first wake. For unpinned dispatch (webhook /
+ * parent-inherited) we can't pick a target ahead of time, so we fall back to a
+ * tenant-wide "some runner offers this" check — better than nothing.
+ */
+export async function resolveSandboxForSpawn(
+  registry: PostgresRegistry,
+  dispatchPolicy: DispatchPolicy | undefined,
+  requested: SandboxChoice | undefined,
+  parentEntity: ElectricAgentsEntity | null
+): Promise<EntitySandboxSelection | undefined> {
+  if (!requested) return undefined
+
+  const choice = applyInheritedSandbox(requested, parentEntity)
+  // `inherit` against a parent with no shareable (keyed) sandbox yields none.
+  if (!choice) return undefined
+
+  const chosenName = choice.profile
+  if (!chosenName) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `sandbox requires a "profile" (or "inherit": true with a parent that has a shared sandbox).`,
+      400
+    )
+  }
+
+  const chosenIsRemote = await resolveChosenProfileRemote(
+    registry,
+    chosenName,
+    dispatchPolicy
+  )
+
+  assertSharedSandboxColocated(choice.key, chosenIsRemote, dispatchPolicy)
+
+  // Persist the selection. Only an explicit/inherited `key` is stored (it's
+  // cross-entity, so the guard above applies); a `scope` is kept so the wake
+  // can derive the key, but no `key` is stored for it — leaving the
+  // co-location guard correctly keyed on genuine cross-entity sharing.
+  const selection: EntitySandboxSelection = { profile: chosenName }
+  if (choice.key !== undefined) selection.key = choice.key
+  else if (choice.scope !== undefined) selection.scope = choice.scope
+  if (choice.persistent !== undefined) selection.persistent = choice.persistent
+  // Store ownership only when this entity is an attacher; owner is the
+  // default, so it's left implicit (the wake resolver defaults to owner).
+  if (choice.owner === false) selection.owner = false
+  return selection
+}
+
+/**
+ * Resolve `inherit` against the parent's *stored* sandbox. `inherit` reuses the
+ * parent's keyed sandbox as a non-owner (attach-only). It's graceful: if the
+ * parent has no shareable (keyed) sandbox the child simply gets none (returns
+ * `undefined`), so `spawn_worker` can always request inheritance without
+ * breaking unkeyed parents. (A running parent wake resolves inherit to its live
+ * explicit key in the runtime instead — this server-side path covers direct API
+ * callers, where only the parent's *stored* explicit key is available.)
+ *
+ * For a non-inherit choice the request passes through unchanged.
+ *
+ * NOTE: `inherit: true` takes the parent's identity AND durability wholesale —
+ * any sibling field on the request (e.g. a caller-supplied `persistent: false`)
+ * is intentionally ignored, because a child attaches to the parent's existing
+ * sandbox and cannot change how that sandbox is torn down. `sandboxChoiceSchema`
+ * permits the `{ inherit: true, persistent: ... }` combination, so the
+ * precedence is resolved here rather than rejected at the schema level.
+ */
+function applyInheritedSandbox(
+  requested: SandboxChoice,
+  parentEntity: ElectricAgentsEntity | null
+): SandboxChoice | undefined {
+  if (!requested.inherit) return requested
+  const parentKey = parentEntity?.sandbox?.key
+  if (!parentKey) return undefined
+  return {
+    profile: parentEntity!.sandbox!.profile,
+    key: parentKey,
+    // Adopt the parent's durability; an explicit key has no scope. The child
+    // attaches to (never owns) the parent's sandbox.
+    persistent: parentEntity!.sandbox!.persistent,
+    owner: false,
+  }
+}
+
+/**
+ * Validate the chosen profile is advertised by the relevant runner(s) and
+ * determine whether it is a remote (off-host) sandbox, reachable from any
+ * runner. Defaults to host-local (co-location required) unless every relevant
+ * advertisement marks it remote. Throws if the profile is unserviceable.
+ */
+async function resolveChosenProfileRemote(
+  registry: PostgresRegistry,
+  chosenName: string,
+  dispatchPolicy: DispatchPolicy | undefined
+): Promise<boolean> {
+  const runnerIds: Array<string> = []
+  for (const target of dispatchPolicy?.targets ?? []) {
+    if (target.type === `runner`) runnerIds.push(target.runnerId)
+  }
+
+  if (runnerIds.length > 0) {
+    let allRemote = true
+    for (const runnerId of runnerIds) {
+      const runner = await registry.getRunner(runnerId)
+      const advertised = runner?.sandbox_profiles ?? []
+      const match = advertised.find((p) => p.name === chosenName)
+      if (!match) {
+        throw new ElectricAgentsError(
+          ErrCodeInvalidRequest,
+          `sandbox profile "${chosenName}" is not advertised by runner "${runnerId}" (advertised: ${advertised.map((p) => p.name).join(`, `) || `(none)`}).`,
+          400
+        )
+      }
+      if (match.remote !== true) allRemote = false
+    }
+    return allRemote
+  }
+
+  const available = await registry.listSandboxProfiles()
+  const matches = available.filter((p) => p.name === chosenName)
+  if (matches.length === 0) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `sandbox profile "${chosenName}" is not offered by any registered runner (available: ${[...new Set(available.map((p) => p.name))].join(`, `) || `(none)`}).`,
+      400
+    )
+  }
+  // Only skip the co-location guard when every advertiser of this name is
+  // remote — a same-named host-local profile on another runner could
+  // otherwise land a collaborator on the wrong host.
+  return matches.every((p) => p.remote === true)
+}
+
+/**
+ * Co-location: a shared *local* sandbox lives on one host, so every
+ * collaborator must be pinned to the same single runner. Subagents inherit the
+ * parent's dispatch policy, so this holds once the root is pinned. A shared
+ * *remote* sandbox is reachable from any runner, so the guard does not apply.
+ */
+function assertSharedSandboxColocated(
+  key: string | undefined,
+  chosenIsRemote: boolean,
+  dispatchPolicy: DispatchPolicy | undefined
+): void {
+  if (key === undefined || chosenIsRemote) return
+  const targets = dispatchPolicy?.targets ?? []
+  const pinnedToSingleRunner =
+    targets.length === 1 && targets[0]?.type === `runner`
+  if (!pinnedToSingleRunner) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `a shared sandbox (sandbox.key / sandbox.inherit) requires the entity to be pinned to a single runner via dispatch_policy, so all collaborators share one host.`,
+      400
+    )
+  }
+}

package/src/runtime.ts

@@ -316,6 +316,8 @@ export class ElectricAgentsTenantRuntime {
         payload.entityUrl,
         {
           from: payload.from,
+          from_principal: payload.from_principal,
+          from_agent: payload.from_agent,
           payload: payload.payload,
           key: payload.key ?? `scheduled-task-${taskId}`,
           type: payload.type,
@@ -461,6 +463,7 @@ export class ElectricAgentsTenantRuntime {
       {
         entityUrl: targetUrl,
         from: senderUrl,
+        from_agent: senderUrl,
         payload: value.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -499,6 +502,14 @@ export class ElectricAgentsTenantRuntime {
       manifestKey,
       sourceRef
     )
+
+    const sharedStateId =
+      operation === `delete` ? undefined : this.extractSharedStateId(value)
+    await this.manager.registry.replaceSharedStateLink(
+      ownerEntityUrl,
+      manifestKey,
+      sharedStateId
+    )
   }
 
   private extractEntitiesSourceRef(
@@ -514,6 +525,29 @@ export class ElectricAgentsTenantRuntime {
     return undefined
   }
 
+  private extractSharedStateId(
+    manifest: Record<string, unknown> | undefined
+  ): 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 =
+      typeof manifest.config === `object` &&
+      manifest.config !== null &&
+      !Array.isArray(manifest.config)
+        ? (manifest.config as Record<string, unknown>)
+        : undefined
+    return typeof config?.id === `string` ? config.id : undefined
+  }
+
   private async maybeMarkEntityIdleAfterRunFinished(
     entityUrl: string
   ): Promise<void> {

package/src/sandbox-choice-schema.ts

@@ -0,0 +1,28 @@
+import { Type } from '@sinclair/typebox'
+
+/**
+ * Wire schema for a spawn-time sandbox CHOICE (the request input), as opposed to
+ * the resolved {@link import('./electric-agents-types.js').EntitySandboxSelection}
+ * persisted on the entity. The matching `SandboxChoice` type is hand-maintained
+ * in `electric-agents-types.ts` — mirrors how `dispatchPolicySchema` pairs with
+ * the `DispatchPolicy` type in `dispatch-policy-schema.ts`.
+ *
+ * Validation happens once, at the router boundary (this schema is embedded in
+ * the spawn body schema); the spawn resolver consumes already-validated input,
+ * so there is intentionally no separate `parse` helper here.
+ */
+export const sandboxChoiceSchema = Type.Object({
+  profile: Type.Optional(Type.String()),
+  // Explicit cross-entity identity — entities with the same key collaborate on
+  // one workspace. `inherit` reuses the parent entity's resolved sandbox.
+  key: Type.Optional(Type.String()),
+  // Identity scope when no explicit `key`: per-entity (default) or per-wake.
+  scope: Type.Optional(
+    Type.Union([Type.Literal(`entity`), Type.Literal(`wake`)])
+  ),
+  // Idle-teardown durability; defaults by scope when unset.
+  persistent: Type.Optional(Type.Boolean()),
+  // Whether this entity owns the sandbox (default) or only attaches to one.
+  owner: Type.Optional(Type.Boolean()),
+  inherit: Type.Optional(Type.Boolean()),
+})

package/src/scheduler.ts

@@ -6,6 +6,8 @@ import type { PgClient } from './db/index.js'
 export interface DelayedSendPayload {
   entityUrl: string
   from?: string
+  from_principal?: string
+  from_agent?: string
   payload: unknown
   key?: string
   type?: string