@electric-ax/agents-server 0.4.20 → 0.5.0

package/dist/index.js

@@ -8,7 +8,7 @@ import postgres from "postgres";
 import { and, desc, eq, inArray, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from "node:crypto";
-import { COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { COMMENTS_CONTRACT, COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
@@ -50,6 +50,7 @@ const entityTypes = pgTable(`entity_types`, {
 	creationSchema: jsonb(`creation_schema`),
 	inboxSchemas: jsonb(`inbox_schemas`),
 	stateSchemas: jsonb(`state_schemas`),
+	externallyWritableCollections: jsonb(`externally_writable_collections`).$type(),
 	slashCommands: jsonb(`slash_commands`),
 	serveEndpoint: text(`serve_endpoint`),
 	defaultDispatchPolicy: jsonb(`default_dispatch_policy`),
@@ -837,6 +838,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -850,6 +852,7 @@ var PostgresRegistry = class {
 				creationSchema: et.creation_schema ?? null,
 				inboxSchemas: et.inbox_schemas ?? null,
 				stateSchemas: et.state_schemas ?? null,
+				externallyWritableCollections: et.externally_writable_collections ?? null,
 				slashCommands: et.slash_commands ?? null,
 				serveEndpoint: et.serve_endpoint ?? null,
 				defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -868,6 +871,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -895,6 +899,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -1540,6 +1545,7 @@ var PostgresRegistry = class {
 			creation_schema: row.creationSchema,
 			inbox_schemas: row.inboxSchemas,
 			state_schemas: row.stateSchemas,
+			externally_writable_collections: row.externallyWritableCollections ?? void 0,
 			slash_commands: row.slashCommands ?? void 0,
 			serve_endpoint: row.serveEndpoint ?? void 0,
 			default_dispatch_policy: row.defaultDispatchPolicy ?? void 0,
@@ -3469,6 +3475,7 @@ var EntityManager = class {
 			creation_schema: req.creation_schema,
 			inbox_schemas: req.inbox_schemas,
 			state_schemas: req.state_schemas,
+			externally_writable_collections: req.externally_writable_collections,
 			slash_commands: req.slash_commands,
 			serve_endpoint: req.serve_endpoint,
 			default_dispatch_policy: defaultDispatchPolicy,
@@ -4564,6 +4571,40 @@ var EntityManager = class {
 			throw err;
 		}
 	}
+	async writeCollection(entityUrl, collection, req) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		const { externallyWritableCollections } = await this.getEffectiveSchemas(entity);
+		const config = externallyWritableCollections?.[collection];
+		if (!config) throw new ElectricAgentsError(ErrCodeUnauthorized, `Collection "${collection}" is not writable`, 403);
+		const allowedOperations = config.operations ?? [`insert`];
+		if (!allowedOperations.includes(req.operation)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Operation "${req.operation}" is not allowed on collection "${collection}"`, 403);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
+		if (this.isForkWorkLockedEntity(entityUrl)) this.assertEntityNotForkWorkLocked(entityUrl);
+		if (req.operation !== `delete` && (req.value === void 0 || req.value === null)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `value is required for ${req.operation}`, 400);
+		if (req.operation !== `insert` && !req.key) throw new ElectricAgentsError(ErrCodeInvalidRequest, `key is required for ${req.operation}`, 400);
+		const key = req.key ?? `${collection}-${randomUUID()}`;
+		const event = {
+			type: config.type,
+			key,
+			headers: {
+				operation: req.operation,
+				timestamp: new Date().toISOString(),
+				principal: req.principal
+			}
+		};
+		if (req.operation !== `delete`) event.value = req.value;
+		const validationError = await this.validateWriteEvent(entity, event);
+		if (validationError) throw new ElectricAgentsError(validationError.code, validationError.message, validationError.status);
+		const encoded = this.encodeChangeEvent(event);
+		try {
+			await this.streamClient.append(entity.streams.main, encoded);
+		} catch (err) {
+			if (this.isClosedStreamError(err)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+			throw err;
+		}
+		return { key };
+	}
 	async updateInboxMessage(entityUrl, key, req) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
@@ -5256,7 +5297,8 @@ var EntityManager = class {
 	async getEffectiveSchemas(entity) {
 		if (!entity.type) return {
 			inboxSchemas: entity.inbox_schemas,
-			stateSchemas: entity.state_schemas
+			stateSchemas: entity.state_schemas,
+			externallyWritableCollections: void 0
 		};
 		const latestType = await this.registry.getEntityType(entity.type);
 		return {
@@ -5267,7 +5309,8 @@ var EntityManager = class {
 			stateSchemas: latestType?.state_schemas ? {
 				...entity.state_schemas ?? {},
 				...latestType.state_schemas
-			} : entity.state_schemas
+			} : entity.state_schemas,
+			externallyWritableCollections: latestType?.externally_writable_collections
 		};
 	}
 	isClosedStreamError(err) {
@@ -8505,6 +8548,15 @@ const spawnBodySchema = Type.Object({
 		manifestKey: Type.Optional(Type.String())
 	}))
 });
+const writeCollectionBodySchema = Type.Object({
+	operation: Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]),
+	key: Type.Optional(Type.String()),
+	value: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+}, { additionalProperties: false });
 const sendBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	key: Type.Optional(Type.String()),
@@ -8637,6 +8689,7 @@ entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, withEntityPermissi
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`delete`), killEntity);
 entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), withEntityPermission(`signal`), signalEntity);
 entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), withEntityPermission(`write`), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/collections/:collection`, withExistingEntity, withSchema(writeCollectionBodySchema), withEntityPermission(`write`), writeCollection);
 entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, withEntityPermission(`write`), createAttachment);
 entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`read`), readAttachment);
 entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`write`), deleteAttachment);
@@ -9035,6 +9088,23 @@ async function sendEntity(request, ctx) {
 	const result = await ctx.entityManager.send(entityUrl, sendReq);
 	return json(result);
 }
+async function writeCollection(request, ctx) {
+	const parsed = routeBody(request);
+	await ctx.entityManager.ensurePrincipal(ctx.principal);
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const collection = request.params.collection;
+	const result = await ctx.entityManager.writeCollection(entityUrl, collection, {
+		operation: parsed.operation,
+		key: parsed.key,
+		value: parsed.value,
+		principal: {
+			url: ctx.principal.url,
+			kind: ctx.principal.kind,
+			id: ctx.principal.id
+		}
+	});
+	return json(result, { status: parsed.operation === `insert` ? 201 : 200 });
+}
 async function createAttachment(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
 	if (principalMutationError) return principalMutationError;
@@ -9132,8 +9202,13 @@ async function spawnEntity(request, ctx) {
 		headers: { "x-write-token": entity.write_token }
 	});
 }
-function getEntity(request) {
-	return json(toPublicEntity(requireExistingEntityRoute(request).entity));
+async function getEntity(request, ctx) {
+	const { entity } = requireExistingEntityRoute(request);
+	const entityType = entity.type ? await ctx.entityManager.registry.getEntityType(entity.type) : null;
+	return json({
+		...toPublicEntity(entity),
+		...entityType?.externally_writable_collections && { externally_writable_collections: entityType.externally_writable_collections }
+	});
 }
 function headEntity() {
 	return status(200);
@@ -9168,6 +9243,16 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown());
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema);
+const externallyWritableCollectionsSchema = Type.Record(Type.String(), Type.Object({
+	type: Type.String(),
+	contract: Type.Optional(Type.String()),
+	operations: Type.Optional(Type.Array(Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]))),
+	principalColumn: Type.Optional(Type.String())
+}, { additionalProperties: false }));
 const slashCommandArgumentSchema = Type.Object({
 	name: Type.String(),
 	type: Type.Union([
@@ -9198,7 +9283,8 @@ const registerEntityTypeBodySchema = Type.Object({
 	slash_commands: Type.Optional(Type.Array(slashCommandSchema)),
 	serve_endpoint: Type.Optional(Type.String()),
 	default_dispatch_policy: Type.Optional(dispatchPolicySchema),
-	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema))
+	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema)),
+	externally_writable_collections: Type.Optional(externallyWritableCollectionsSchema)
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
@@ -9329,7 +9415,20 @@ function parseExpiresAt(value) {
 	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
 	return expiresAt;
 }
+/**
+* The `comments` collection name is reserved for the canonical comments
+* contract: the UI keys its comment affordances on it, so a divergent
+* collection registered under that name (or the contract mounted under
+* another name) would break that assumption silently.
+*/
+function validateExternallyWritableCollections(collections) {
+	for (const [name, config] of Object.entries(collections ?? {})) {
+		if (name === `comments` && config.contract !== COMMENTS_CONTRACT) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The externally-writable collection name "comments" is reserved for the "${COMMENTS_CONTRACT}" contract`, 400);
+		if (config.contract === COMMENTS_CONTRACT && name !== `comments`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The "${COMMENTS_CONTRACT}" contract must be registered under the collection name "comments"`, 400);
+	}
+}
 function normalizeEntityTypeRequest(parsed) {
+	validateExternallyWritableCollections(parsed.externally_writable_collections);
 	const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint);
 	return {
 		name: parsed.name ?? ``,
@@ -9343,7 +9442,8 @@ function normalizeEntityTypeRequest(parsed) {
 			type: `webhook`,
 			url: serveEndpoint
 		}] } : void 0),
-		permission_grants: parsed.permission_grants
+		permission_grants: parsed.permission_grants,
+		externally_writable_collections: parsed.externally_writable_collections
 	};
 }
 function toPublicEntityType(entityType) {

package/drizzle/0016_entity_type_externally_writable_collections.sql

@@ -0,0 +1 @@
+ALTER TABLE "entity_types" ADD COLUMN "externally_writable_collections" jsonb;

package/drizzle/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1779728400000,
       "tag": "0015_pg_sync_bridges",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1781200000000,
+      "tag": "0016_entity_type_externally_writable_collections",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.20",
+  "version": "0.5.0",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.13"
+    "@electric-ax/agents-runtime": "0.4.0"
   },
   "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.17",
+    "@electric-ax/agents": "0.4.18",
     "@electric-ax/agents-server-conformance-tests": "0.1.12",
-    "@electric-ax/agents-server-ui": "0.4.20"
+    "@electric-ax/agents-server-ui": "0.5.0"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -14,6 +14,7 @@ import {
   timestamp,
   unique,
 } from 'drizzle-orm/pg-core'
+import type { ExternallyWritableCollectionConfig } from '../electric-agents-types.js'
 
 export const entityTypes = pgTable(
   `entity_types`,
@@ -24,6 +25,9 @@ export const entityTypes = pgTable(
     creationSchema: jsonb(`creation_schema`),
     inboxSchemas: jsonb(`inbox_schemas`),
     stateSchemas: jsonb(`state_schemas`),
+    externallyWritableCollections: jsonb(
+      `externally_writable_collections`
+    ).$type<Record<string, ExternallyWritableCollectionConfig>>(),
     slashCommands: jsonb(`slash_commands`),
     serveEndpoint: text(`serve_endpoint`),
     defaultDispatchPolicy: jsonb(`default_dispatch_policy`),

package/src/electric-agents-types.ts

@@ -494,12 +494,31 @@ export function toPublicEntity(
   }
 }
 
+/** Per-collection config making an entity-state collection externally writable via the router. */
+export interface ExternallyWritableCollectionConfig {
+  /** Durable-stream event type for this collection, e.g. `state:comments`. */
+  type: string
+  /** Well-known contract this collection implements, e.g. `comments/v1`. */
+  contract?: string
+  /**
+   * Allowlist of external write operations. When set, the router rejects any
+   * operation not listed (403). When unset, only `insert` is permitted — the
+   * safe default, since open update/delete lets a client overwrite or remove
+   * another principal's rows by key.
+   */
+  operations?: Array<`insert` | `update` | `delete`>
+}
+
 export interface ElectricAgentsEntityType {
   name: string
   description: string
   creation_schema?: Record<string, unknown>
   inbox_schemas?: Record<string, Record<string, unknown>>
   state_schemas?: Record<string, Record<string, unknown>>
+  externally_writable_collections?: Record<
+    string,
+    ExternallyWritableCollectionConfig
+  >
   slash_commands?: Array<SlashCommandDefinition>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy
@@ -514,6 +533,10 @@ export interface RegisterEntityTypeRequest {
   creation_schema?: Record<string, unknown>
   inbox_schemas?: Record<string, Record<string, unknown>>
   state_schemas?: Record<string, Record<string, unknown>>
+  externally_writable_collections?: Record<
+    string,
+    ExternallyWritableCollectionConfig
+  >
   slash_commands?: Array<SlashCommandDefinition>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy

package/src/entity-manager.ts

@@ -71,6 +71,7 @@ import type {
   SignalRequest,
   SignalResponse,
   TypedSpawnRequest,
+  ExternallyWritableCollectionConfig,
 } from './electric-agents-types.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { Principal } from './principal.js'
@@ -131,6 +132,23 @@ export interface CreateAttachmentRequest {
   meta?: Record<string, unknown>
 }
 
+export interface WriteCollectionPrincipal {
+  url: string
+  kind: string
+  id: string
+}
+
+export interface WriteCollectionRequest {
+  operation: `insert` | `update` | `delete`
+  key?: string
+  value?: Record<string, unknown>
+  principal: WriteCollectionPrincipal
+}
+
+export interface WriteCollectionResult {
+  key: string
+}
+
 export interface ReadAttachmentResult {
   attachment: ManifestAttachmentEntry
   bytes: Uint8Array
@@ -488,6 +506,7 @@ export class EntityManager {
       creation_schema: req.creation_schema,
       inbox_schemas: req.inbox_schemas,
       state_schemas: req.state_schemas,
+      externally_writable_collections: req.externally_writable_collections,
       slash_commands: req.slash_commands,
       serve_endpoint: req.serve_endpoint,
       default_dispatch_policy: defaultDispatchPolicy,
@@ -2434,6 +2453,106 @@ export class EntityManager {
     }
   }
 
+  async writeCollection(
+    entityUrl: string,
+    collection: string,
+    req: WriteCollectionRequest
+  ): Promise<WriteCollectionResult> {
+    const entity = await this.registry.getEntity(entityUrl)
+    if (!entity) {
+      throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404)
+    }
+
+    const { externallyWritableCollections } =
+      await this.getEffectiveSchemas(entity)
+    const config = externallyWritableCollections?.[collection]
+    if (!config) {
+      throw new ElectricAgentsError(
+        ErrCodeUnauthorized,
+        `Collection "${collection}" is not writable`,
+        403
+      )
+    }
+
+    const allowedOperations = config.operations ?? [`insert`]
+    if (!allowedOperations.includes(req.operation)) {
+      throw new ElectricAgentsError(
+        ErrCodeUnauthorized,
+        `Operation "${req.operation}" is not allowed on collection "${collection}"`,
+        403
+      )
+    }
+
+    if (rejectsNormalWrites(entity.status)) {
+      throw new ElectricAgentsError(
+        ErrCodeNotRunning,
+        `Entity is not accepting writes`,
+        409
+      )
+    }
+    if (this.isForkWorkLockedEntity(entityUrl)) {
+      this.assertEntityNotForkWorkLocked(entityUrl)
+    }
+
+    if (
+      req.operation !== `delete` &&
+      (req.value === undefined || req.value === null)
+    ) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `value is required for ${req.operation}`,
+        400
+      )
+    }
+    if (req.operation !== `insert` && !req.key) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `key is required for ${req.operation}`,
+        400
+      )
+    }
+
+    const key = req.key ?? `${collection}-${randomUUID()}`
+
+    const event: Record<string, unknown> = {
+      type: config.type,
+      key,
+      headers: {
+        operation: req.operation,
+        timestamp: new Date().toISOString(),
+        principal: req.principal,
+      },
+    }
+    if (req.operation !== `delete`) {
+      event.value = req.value
+    }
+
+    const validationError = await this.validateWriteEvent(entity, event)
+    if (validationError) {
+      throw new ElectricAgentsError(
+        validationError.code,
+        validationError.message,
+        validationError.status
+      )
+    }
+
+    const encoded = this.encodeChangeEvent(event)
+    try {
+      await this.streamClient.append(entity.streams.main, encoded)
+    } catch (err) {
+      if (this.isClosedStreamError(err)) {
+        throw new ElectricAgentsError(
+          ErrCodeNotRunning,
+          `Entity is stopped`,
+          409
+        )
+      }
+      throw err
+    }
+
+    return { key }
+  }
+
   async updateInboxMessage(
     entityUrl: string,
     key: string,
@@ -3876,11 +3995,16 @@ export class EntityManager {
   private async getEffectiveSchemas(entity: ElectricAgentsEntity): Promise<{
     inboxSchemas?: Record<string, Record<string, unknown>>
     stateSchemas?: Record<string, Record<string, unknown>>
+    externallyWritableCollections?: Record<
+      string,
+      ExternallyWritableCollectionConfig
+    >
   }> {
     if (!entity.type) {
       return {
         inboxSchemas: entity.inbox_schemas,
         stateSchemas: entity.state_schemas,
+        externallyWritableCollections: undefined,
       }
     }
 
@@ -3893,6 +4017,8 @@ export class EntityManager {
       stateSchemas: latestType?.state_schemas
         ? { ...(entity.state_schemas ?? {}), ...latestType.state_schemas }
         : entity.state_schemas,
+      externallyWritableCollections:
+        latestType?.externally_writable_collections,
     }
   }
 

package/src/entity-registry.ts

@@ -43,6 +43,7 @@ import type {
   EntityTypePermission,
   EntityTypePermissionGrant,
   PermissionSubjectKind,
+  ExternallyWritableCollectionConfig,
 } from './electric-agents-types.js'
 import type { EntityTags, PgSyncOptions } from '@electric-ax/agents-runtime'
 import type { Principal } from './principal.js'
@@ -654,6 +655,8 @@ export class PostgresRegistry {
         creationSchema: et.creation_schema ?? null,
         inboxSchemas: et.inbox_schemas ?? null,
         stateSchemas: et.state_schemas ?? null,
+        externallyWritableCollections:
+          et.externally_writable_collections ?? null,
         slashCommands: et.slash_commands ?? null,
         serveEndpoint: et.serve_endpoint ?? null,
         defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -668,6 +671,8 @@ export class PostgresRegistry {
           creationSchema: et.creation_schema ?? null,
           inboxSchemas: et.inbox_schemas ?? null,
           stateSchemas: et.state_schemas ?? null,
+          externallyWritableCollections:
+            et.externally_writable_collections ?? null,
           slashCommands: et.slash_commands ?? null,
           serveEndpoint: et.serve_endpoint ?? null,
           defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -691,6 +696,8 @@ export class PostgresRegistry {
         creationSchema: et.creation_schema ?? null,
         inboxSchemas: et.inbox_schemas ?? null,
         stateSchemas: et.state_schemas ?? null,
+        externallyWritableCollections:
+          et.externally_writable_collections ?? null,
         slashCommands: et.slash_commands ?? null,
         serveEndpoint: et.serve_endpoint ?? null,
         defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -733,6 +740,8 @@ export class PostgresRegistry {
         creationSchema: et.creation_schema ?? null,
         inboxSchemas: et.inbox_schemas ?? null,
         stateSchemas: et.state_schemas ?? null,
+        externallyWritableCollections:
+          et.externally_writable_collections ?? null,
         slashCommands: et.slash_commands ?? null,
         serveEndpoint: et.serve_endpoint ?? null,
         defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -1957,6 +1966,11 @@ export class PostgresRegistry {
       state_schemas: row.stateSchemas as
         | Record<string, Record<string, unknown>>
         | undefined,
+      externally_writable_collections:
+        (row.externallyWritableCollections as Record<
+          string,
+          ExternallyWritableCollectionConfig
+        > | null) ?? undefined,
       slash_commands:
         (row.slashCommands as ElectricAgentsEntityType[`slash_commands`]) ??
         undefined,

package/src/routing/entities-router.ts

@@ -149,6 +149,19 @@ const spawnBodySchema = Type.Object({
   ),
 })
 
+const writeCollectionBodySchema = Type.Object(
+  {
+    operation: Type.Union([
+      Type.Literal(`insert`),
+      Type.Literal(`update`),
+      Type.Literal(`delete`),
+    ]),
+    key: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  },
+  { additionalProperties: false }
+)
+
 const sendBodySchema = Type.Object({
   payload: Type.Optional(Type.Unknown()),
   key: Type.Optional(Type.String()),
@@ -328,6 +341,7 @@ const eventSourceSubscriptionBodySchema = Type.Object({
 })
 
 type SpawnBody = Static<typeof spawnBodySchema>
+type WriteCollectionBody = Static<typeof writeCollectionBodySchema>
 type SendBody = Static<typeof sendBodySchema>
 type InboxMessageBody = Static<typeof inboxMessageBodySchema>
 type ForkBody = Static<typeof forkBodySchema>
@@ -408,6 +422,13 @@ entitiesRouter.post(
   withEntityPermission(`write`),
   sendEntity
 )
+entitiesRouter.post(
+  `/:type/:instanceId/collections/:collection`,
+  withExistingEntity,
+  withSchema(writeCollectionBodySchema),
+  withEntityPermission(`write`),
+  writeCollection
+)
 entitiesRouter.post(
   `/:type/:instanceId/attachments`,
   withExistingEntity,
@@ -1308,6 +1329,31 @@ async function sendEntity(
   return json(result)
 }
 
+async function writeCollection(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<WriteCollectionBody>(request)
+  await ctx.entityManager.ensurePrincipal(ctx.principal)
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const collection = request.params.collection
+  const result = await ctx.entityManager.writeCollection(
+    entityUrl,
+    collection,
+    {
+      operation: parsed.operation,
+      key: parsed.key,
+      value: parsed.value,
+      principal: {
+        url: ctx.principal.url,
+        kind: ctx.principal.kind,
+        id: ctx.principal.id,
+      },
+    }
+  )
+  return json(result, { status: parsed.operation === `insert` ? 201 : 200 })
+}
+
 async function createAttachment(
   request: AgentsRouteRequest,
   ctx: TenantContext
@@ -1473,8 +1519,21 @@ async function spawnEntity(
   )
 }
 
-function getEntity(request: AgentsRouteRequest): Response {
-  return json(toPublicEntity(requireExistingEntityRoute(request).entity))
+async function getEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { entity } = requireExistingEntityRoute(request)
+  const entityType = entity.type
+    ? await ctx.entityManager.registry.getEntityType(entity.type)
+    : null
+  return json({
+    ...toPublicEntity(entity),
+    ...(entityType?.externally_writable_collections && {
+      externally_writable_collections:
+        entityType.externally_writable_collections,
+    }),
+  })
 }
 
 function headEntity(): Response {