@electric-ax/agents-server 0.4.14 → 0.4.16

package/drizzle/0010_sandbox_profiles.sql

@@ -0,0 +1,5 @@
+ALTER TABLE runners
+  ADD COLUMN sandbox_profiles jsonb NOT NULL DEFAULT '[]'::jsonb;
+--> statement-breakpoint
+ALTER TABLE entities
+  ADD COLUMN sandbox jsonb;

package/drizzle/0011_entity_permissions.sql

@@ -0,0 +1,100 @@
+CREATE TABLE "entity_type_permission_grants" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_type" text NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "created_by" text,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "chk_type_permission_grants_permission" CHECK ("entity_type_permission_grants"."permission" IN ('spawn', 'manage')),
+  CONSTRAINT "chk_type_permission_grants_subject_kind" CHECK ("entity_type_permission_grants"."subject_kind" IN ('principal', 'principal_kind'))
+);
+--> statement-breakpoint
+CREATE TABLE "entity_lineage" (
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "ancestor_url" text NOT NULL,
+  "descendant_url" text NOT NULL,
+  "depth" integer NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "entity_lineage_pkey" PRIMARY KEY ("tenant_id", "ancestor_url", "descendant_url"),
+  CONSTRAINT "chk_entity_lineage_depth" CHECK ("entity_lineage"."depth" >= 0)
+);
+--> statement-breakpoint
+CREATE TABLE "entity_permission_grants" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_url" text NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "propagation" text DEFAULT 'self' NOT NULL,
+  "copy_to_children" boolean DEFAULT false NOT NULL,
+  "created_by" text,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "chk_entity_permission_grants_permission" CHECK ("entity_permission_grants"."permission" IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')),
+  CONSTRAINT "chk_entity_permission_grants_subject_kind" CHECK ("entity_permission_grants"."subject_kind" IN ('principal', 'principal_kind')),
+  CONSTRAINT "chk_entity_permission_grants_propagation" CHECK ("entity_permission_grants"."propagation" IN ('self', 'descendants'))
+);
+--> statement-breakpoint
+CREATE TABLE "entity_effective_permissions" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_url" text NOT NULL,
+  "source_entity_url" text NOT NULL,
+  "source_grant_id" bigint NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "uq_entity_effective_permission" UNIQUE ("tenant_id", "entity_url", "source_grant_id"),
+  CONSTRAINT "chk_entity_effective_permissions_permission" CHECK ("entity_effective_permissions"."permission" IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')),
+  CONSTRAINT "chk_entity_effective_permissions_subject_kind" CHECK ("entity_effective_permissions"."subject_kind" IN ('principal', 'principal_kind'))
+);
+--> statement-breakpoint
+CREATE TABLE "shared_state_links" (
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "shared_state_id" text NOT NULL,
+  "owner_entity_url" text NOT NULL,
+  "manifest_key" text NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "shared_state_links_pkey" PRIMARY KEY ("tenant_id", "owner_entity_url", "manifest_key")
+);
+--> statement-breakpoint
+CREATE INDEX "idx_type_permission_grants_lookup" ON "entity_type_permission_grants" USING btree ("tenant_id", "entity_type", "permission", "subject_kind", "subject_value");
+--> statement-breakpoint
+CREATE INDEX "idx_type_permission_grants_expiry" ON "entity_type_permission_grants" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_lineage_descendant" ON "entity_lineage" USING btree ("tenant_id", "descendant_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_entity" ON "entity_permission_grants" USING btree ("tenant_id", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_subject" ON "entity_permission_grants" USING btree ("tenant_id", "permission", "subject_kind", "subject_value");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_expiry" ON "entity_permission_grants" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_lookup" ON "entity_effective_permissions" USING btree ("tenant_id", "permission", "subject_kind", "subject_value", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_entity" ON "entity_effective_permissions" USING btree ("tenant_id", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_expiry" ON "entity_effective_permissions" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_shared_state_links_shared_state" ON "shared_state_links" USING btree ("tenant_id", "shared_state_id");
+--> statement-breakpoint
+CREATE INDEX "idx_shared_state_links_owner" ON "shared_state_links" USING btree ("tenant_id", "owner_entity_url");
+--> statement-breakpoint
+-- Pre-permission entity bridge rows do not carry principal attribution. Drop them
+-- so observation bridges are rebuilt with principal_url/principal_kind scoping.
+DELETE FROM "entity_bridges";
+--> statement-breakpoint
+ALTER TABLE "entity_bridges" ADD COLUMN "principal_url" text;
+--> statement-breakpoint
+ALTER TABLE "entity_bridges" ADD COLUMN "principal_kind" text;
+--> statement-breakpoint
+CREATE INDEX "idx_entity_bridges_principal" ON "entity_bridges" USING btree ("tenant_id", "principal_kind", "principal_url");

package/drizzle/0012_horton_user_manage_permission.sql

@@ -0,0 +1,25 @@
+INSERT INTO "entity_type_permission_grants" (
+  "tenant_id",
+  "entity_type",
+  "permission",
+  "subject_kind",
+  "subject_value"
+)
+SELECT
+  "entity_types"."tenant_id",
+  "entity_types"."name",
+  'manage',
+  'principal_kind',
+  'user'
+FROM "entity_types"
+WHERE "entity_types"."name" = 'horton'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM "entity_type_permission_grants"
+    WHERE "entity_type_permission_grants"."tenant_id" = "entity_types"."tenant_id"
+      AND "entity_type_permission_grants"."entity_type" = "entity_types"."name"
+      AND "entity_type_permission_grants"."permission" = 'manage'
+      AND "entity_type_permission_grants"."subject_kind" = 'principal_kind'
+      AND "entity_type_permission_grants"."subject_value" = 'user'
+      AND "entity_type_permission_grants"."expires_at" IS NULL
+  );

package/drizzle/0013_worker_user_manage_permission.sql

@@ -0,0 +1,25 @@
+INSERT INTO "entity_type_permission_grants" (
+  "tenant_id",
+  "entity_type",
+  "permission",
+  "subject_kind",
+  "subject_value"
+)
+SELECT
+  "entity_types"."tenant_id",
+  "entity_types"."name",
+  'manage',
+  'principal_kind',
+  'user'
+FROM "entity_types"
+WHERE "entity_types"."name" = 'worker'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM "entity_type_permission_grants"
+    WHERE "entity_type_permission_grants"."tenant_id" = "entity_types"."tenant_id"
+      AND "entity_type_permission_grants"."entity_type" = "entity_types"."name"
+      AND "entity_type_permission_grants"."permission" = 'manage'
+      AND "entity_type_permission_grants"."subject_kind" = 'principal_kind'
+      AND "entity_type_permission_grants"."subject_value" = 'user'
+      AND "entity_type_permission_grants"."expires_at" IS NULL
+  );

package/drizzle/meta/_journal.json

@@ -71,6 +71,34 @@
       "when": 1778540000000,
       "tag": "0009_entity_signal_statuses",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1779062400000,
+      "tag": "0010_sandbox_profiles",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1779050000000,
+      "tag": "0011_entity_permissions",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1780584581000,
+      "tag": "0012_horton_user_manage_permission",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1780588695000,
+      "tag": "0013_worker_user_manage_permission",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -37,8 +37,8 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@durable-streams/client": "^0.2.6",
-    "@durable-streams/server": "^0.3.5",
-    "@durable-streams/state": "^0.2.9",
+    "@durable-streams/server": "^0.3.7",
+    "@durable-streams/state": "^0.3.1",
     "@electric-sql/client": "^1.5.20",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@opentelemetry/api": "^1.9.1",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.7"
+    "@electric-ax/agents-runtime": "0.3.9"
   },
   "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": "0.4.11",
-    "@electric-ax/agents-server-conformance-tests": "0.1.9",
-    "@electric-ax/agents-server-ui": "0.4.14"
+    "@electric-ax/agents": "0.4.13",
+    "@electric-ax/agents-server-conformance-tests": "0.1.11",
+    "@electric-ax/agents-server-ui": "0.4.16"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -49,6 +49,7 @@ export const entities = pgTable(
       .notNull()
       .default(sql`'{}'::text[]`),
     spawnArgs: jsonb(`spawn_args`).default({}),
+    sandbox: jsonb(`sandbox`),
     parent: text(`parent`),
     createdBy: text(`created_by`),
     typeRevision: integer(`type_revision`),
@@ -71,6 +72,197 @@ export const entities = pgTable(
   ]
 )
 
+export const entityTypePermissionGrants = pgTable(
+  `entity_type_permission_grants`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityType: text(`entity_type`).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    createdBy: text(`created_by`),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index(`idx_type_permission_grants_lookup`).on(
+      table.tenantId,
+      table.entityType,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue
+    ),
+    index(`idx_type_permission_grants_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_type_permission_grants_permission`,
+      sql`${table.permission} IN ('spawn', 'manage')`
+    ),
+    check(
+      `chk_type_permission_grants_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+  ]
+)
+
+export const entityLineage = pgTable(
+  `entity_lineage`,
+  {
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    ancestorUrl: text(`ancestor_url`).notNull(),
+    descendantUrl: text(`descendant_url`).notNull(),
+    depth: integer(`depth`).notNull(),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.tenantId, table.ancestorUrl, table.descendantUrl],
+    }),
+    index(`idx_entity_lineage_descendant`).on(
+      table.tenantId,
+      table.descendantUrl
+    ),
+    check(`chk_entity_lineage_depth`, sql`${table.depth} >= 0`),
+  ]
+)
+
+export const entityPermissionGrants = pgTable(
+  `entity_permission_grants`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityUrl: text(`entity_url`).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    propagation: text(`propagation`).notNull().default(`self`),
+    copyToChildren: boolean(`copy_to_children`).notNull().default(false),
+    createdBy: text(`created_by`),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index(`idx_entity_permission_grants_entity`).on(
+      table.tenantId,
+      table.entityUrl
+    ),
+    index(`idx_entity_permission_grants_subject`).on(
+      table.tenantId,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue
+    ),
+    index(`idx_entity_permission_grants_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_entity_permission_grants_permission`,
+      sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`
+    ),
+    check(
+      `chk_entity_permission_grants_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+    check(
+      `chk_entity_permission_grants_propagation`,
+      sql`${table.propagation} IN ('self', 'descendants')`
+    ),
+  ]
+)
+
+export const entityEffectivePermissions = pgTable(
+  `entity_effective_permissions`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityUrl: text(`entity_url`).notNull(),
+    sourceEntityUrl: text(`source_entity_url`).notNull(),
+    sourceGrantId: bigint(`source_grant_id`, { mode: `number` }).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    unique(`uq_entity_effective_permission`).on(
+      table.tenantId,
+      table.entityUrl,
+      table.sourceGrantId
+    ),
+    index(`idx_entity_effective_permissions_lookup`).on(
+      table.tenantId,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue,
+      table.entityUrl
+    ),
+    index(`idx_entity_effective_permissions_entity`).on(
+      table.tenantId,
+      table.entityUrl
+    ),
+    index(`idx_entity_effective_permissions_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_entity_effective_permissions_permission`,
+      sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`
+    ),
+    check(
+      `chk_entity_effective_permissions_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+  ]
+)
+
+export const sharedStateLinks = pgTable(
+  `shared_state_links`,
+  {
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    sharedStateId: text(`shared_state_id`).notNull(),
+    ownerEntityUrl: text(`owner_entity_url`).notNull(),
+    manifestKey: text(`manifest_key`).notNull(),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.tenantId, table.ownerEntityUrl, table.manifestKey],
+    }),
+    index(`idx_shared_state_links_shared_state`).on(
+      table.tenantId,
+      table.sharedStateId
+    ),
+    index(`idx_shared_state_links_owner`).on(
+      table.tenantId,
+      table.ownerEntityUrl
+    ),
+  ]
+)
+
 export const users = pgTable(
   `users`,
   {
@@ -111,6 +303,7 @@ export const runners = pgTable(
     kind: text(`kind`).notNull().default(`local`),
     adminStatus: text(`admin_status`).notNull().default(`enabled`),
     wakeStream: text(`wake_stream`).notNull(),
+    sandboxProfiles: jsonb(`sandbox_profiles`).notNull().default([]),
     createdAt: timestamp(`created_at`, { withTimezone: true })
       .notNull()
       .defaultNow(),
@@ -434,6 +627,8 @@ export const entityBridges = pgTable(
     sourceRef: text(`source_ref`).notNull(),
     tags: jsonb(`tags`).notNull(),
     streamUrl: text(`stream_url`).notNull(),
+    principalUrl: text(`principal_url`),
+    principalKind: text(`principal_kind`),
     shapeHandle: text(`shape_handle`),
     shapeOffset: text(`shape_offset`),
     lastObserverActivityAt: timestamp(`last_observer_activity_at`, {
@@ -451,6 +646,11 @@ export const entityBridges = pgTable(
   (table) => [
     primaryKey({ columns: [table.tenantId, table.sourceRef] }),
     unique(`uq_entity_bridges_stream_url`).on(table.tenantId, table.streamUrl),
+    index(`idx_entity_bridges_principal`).on(
+      table.tenantId,
+      table.principalKind,
+      table.principalUrl
+    ),
   ]
 )
 

package/src/electric-agents-types.ts

@@ -67,6 +67,78 @@ export type RunnerKind = `local` | `cloud-worker` | `sandbox` | `ci` | `server`
 export type RunnerAdminStatus = `enabled` | `disabled`
 export type RunnerLiveness = `online` | `offline`
 
+export type PermissionSubjectKind = `principal` | `principal_kind`
+export type PermissionSubject = {
+  subject_kind: PermissionSubjectKind
+  subject_value: string
+}
+export type EntityPermission =
+  | `read`
+  | `write`
+  | `delete`
+  | `signal`
+  | `fork`
+  | `schedule`
+  | `spawn`
+  | `manage`
+export type EntityTypePermission = `spawn` | `manage`
+export type EntityPermissionPropagation = `self` | `descendants`
+
+export interface EntityPermissionGrant extends PermissionSubject {
+  id: number
+  entity_url: string
+  permission: EntityPermission
+  propagation: EntityPermissionPropagation
+  copy_to_children: boolean
+  created_by?: string
+  expires_at?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface EntityTypePermissionGrant extends PermissionSubject {
+  id: number
+  entity_type: string
+  permission: EntityTypePermission
+  created_by?: string
+  expires_at?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface EntityTypePermissionGrantInput extends PermissionSubject {
+  permission: EntityTypePermission
+  expires_at?: string
+}
+
+export type AuthorizationResource =
+  | { kind: `entity`; entity: ElectricAgentsEntity }
+  | { kind: `entity_type`; entityType: ElectricAgentsEntityType }
+  | { kind: `entity_type_registration`; entityTypeName: string }
+  | {
+      kind: `shared_state`
+      sharedStateId: string
+      linkedEntityUrls: Array<string>
+    }
+
+export type AuthorizationDecision = {
+  decision: `allow` | `deny`
+  expires_at?: string
+}
+
+export type AuthorizeRequest = (input: {
+  tenant: string
+  principal: Principal
+  verb: EntityPermission | EntityTypePermission
+  resource: AuthorizationResource
+  request?: {
+    method: string
+    url: string
+    headers: Record<string, string>
+  }
+  builtInAllowed: boolean
+}) => Promise<AuthorizationDecision> | AuthorizationDecision
+
 const VALID_RUNNER_KINDS = new Set<string>([
   `local`,
   `cloud-worker`,
@@ -130,6 +202,19 @@ export interface RunnerActiveClaim {
   leaseExpiresAt?: string
 }
 
+export interface SandboxProfileAdvertisement {
+  name: string
+  label: string
+  description?: string
+  /**
+   * True for off-host (remote-provider) profiles, reachable from any runner.
+   * Absent/false means the sandbox is host-local, so a shared sandbox on this
+   * profile requires its collaborators to be pinned to a single runner. Set
+   * by the runtime per profile (see SandboxProfile.remote).
+   */
+  remote?: boolean
+}
+
 export interface ElectricAgentsRunner {
   id: string
   owner_principal: string
@@ -143,6 +228,7 @@ export interface ElectricAgentsRunner {
   wake_stream: string
   wake_stream_offset?: string
   diagnostics?: Record<string, unknown>
+  sandbox_profiles: Array<SandboxProfileAdvertisement>
   created_at: string
   updated_at: string
 }
@@ -295,19 +381,67 @@ export function expectedSignalStatus(
   }
 }
 
+/**
+ * Resolved sandbox selection stored on an entity and replayed to the runtime at
+ * wake. Only an explicit / inherited cross-entity `key` is persisted here;
+ * `scope`-derived keys are computed at wake time (and so left unstored, keeping
+ * the co-location guard keyed on genuine cross-entity sharing). `persistent`
+ * defaults by scope at wake time when unset.
+ */
+export interface EntitySandboxSelection {
+  profile: string
+  key?: string
+  scope?: `entity` | `wake`
+  persistent?: boolean
+  /**
+   * Whether the entity owns the sandbox (create + govern teardown) or only
+   * attaches to an owner's. Stored as `false` for an attacher (e.g. an
+   * `inherit` spawn); omitted ⇒ owner (the default).
+   */
+  owner?: boolean
+}
+
+/**
+ * Spawn-time sandbox CHOICE — the request input, before resolution. Resolved
+ * into an {@link EntitySandboxSelection} by the spawn path. The wire schema for
+ * this shape lives in `sandbox-choice-schema.ts` (mirrors how `DispatchPolicy`
+ * pairs with `dispatch-policy-schema.ts`).
+ */
+export interface SandboxChoice {
+  /** Profile name advertised by the target runner. */
+  profile?: string
+  /** Explicit cross-entity key to join (or start) a shared sandbox. */
+  key?: string
+  /** Identity scope when no explicit `key`: per-entity (default) or per-wake. */
+  scope?: `entity` | `wake`
+  /** Idle-teardown durability; defaults by scope when unset. */
+  persistent?: boolean
+  /** Whether this entity owns the sandbox (default) or only attaches to one. */
+  owner?: boolean
+  /** Reuse the parent entity's resolved sandbox (attach-only). */
+  inherit?: boolean
+}
+
 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>
+  /**
+   * Resolved sandbox selection. An explicit `key` lets entities collaborate on
+   * one workspace and is the only key form persisted (it's cross-entity, so the
+   * co-location guard applies); a `scope` ('entity' default / 'wake') instead
+   * derives the key at wake time, so it's left unstored. `persistent` chooses
+   * idle durability.
+   */
+  sandbox?: EntitySandboxSelection
   parent?: string
   type_revision?: number
   inbox_schemas?: Record<string, Record<string, unknown>>
@@ -322,10 +456,11 @@ export interface PublicElectricAgentsEntity {
   url: string
   type: string
   status: EntityStatus
-  streams: { main: string; error: string }
+  streams: { main: string }
   dispatch_policy?: DispatchPolicy
   tags: Record<string, string>
   spawn_args?: Record<string, unknown>
+  sandbox?: EntitySandboxSelection
   parent?: string
   created_by?: string
   created_at: number
@@ -350,6 +485,7 @@ export function toPublicEntity(
     dispatch_policy: entity.dispatch_policy,
     tags: entity.tags,
     spawn_args: entity.spawn_args,
+    sandbox: entity.sandbox,
     parent: entity.parent,
     created_by: entity.created_by,
     created_at: entity.created_at,
@@ -378,6 +514,7 @@ export interface RegisterEntityTypeRequest {
   state_schemas?: Record<string, Record<string, unknown>>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy
+  permission_grants?: Array<EntityTypePermissionGrantInput>
 }
 
 export interface TypedSpawnRequest {
@@ -386,6 +523,12 @@ export interface TypedSpawnRequest {
   tags?: Record<string, string>
   parent?: string
   dispatch_policy?: DispatchPolicy
+  /**
+   * Sandbox selection: `profile` for a sandbox (optionally with `scope` /
+   * `persistent`), `key` to join (or start) an explicit shared one, or
+   * `inherit: true` to reuse the parent's resolved sandbox.
+   */
+  sandbox?: SandboxChoice
   initialMessage?: unknown
   created_by?: string
   wake?: {
@@ -406,6 +549,8 @@ export interface TypedSpawnRequest {
 
 export interface SendRequest {
   from?: string
+  from_principal?: string
+  from_agent?: string
   payload?: unknown
   key?: string
   type?: string