@electric-ax/agents-server 0.4.20 → 0.5.0

package/dist/entrypoint.js

@@ -4,7 +4,7 @@ import { DurableStreamTestServer } from "@durable-streams/server";
 import { createServer } from "node:http";
 import { createServerAdapter } from "@whatwg-node/server";
 import { Agent } from "undici";
-import { COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, createEntityRegistry, createRuntimeHandler, 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, createEntityRegistry, createRuntimeHandler, 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 fs, { existsSync } from "node:fs";
 import path, { dirname, resolve } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
@@ -65,6 +65,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`),
@@ -2796,6 +2797,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,
@@ -2809,6 +2811,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,
@@ -2827,6 +2830,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,
@@ -2854,6 +2858,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,
@@ -3499,6 +3504,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,
@@ -3861,6 +3867,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,
@@ -4956,6 +4963,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);
@@ -5648,7 +5689,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 {
@@ -5659,7 +5701,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) {
@@ -5922,6 +5965,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()),
@@ -6054,6 +6106,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);
@@ -6452,6 +6505,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;
@@ -6549,8 +6619,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);
@@ -6585,6 +6660,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([
@@ -6615,7 +6700,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),
@@ -6746,7 +6832,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 ?? ``,
@@ -6760,7 +6859,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/dist/index.cjs

@@ -79,6 +79,7 @@ const entityTypes = (0, drizzle_orm_pg_core.pgTable)(`entity_types`, {
 	creationSchema: (0, drizzle_orm_pg_core.jsonb)(`creation_schema`),
 	inboxSchemas: (0, drizzle_orm_pg_core.jsonb)(`inbox_schemas`),
 	stateSchemas: (0, drizzle_orm_pg_core.jsonb)(`state_schemas`),
+	externallyWritableCollections: (0, drizzle_orm_pg_core.jsonb)(`externally_writable_collections`).$type(),
 	slashCommands: (0, drizzle_orm_pg_core.jsonb)(`slash_commands`),
 	serveEndpoint: (0, drizzle_orm_pg_core.text)(`serve_endpoint`),
 	defaultDispatchPolicy: (0, drizzle_orm_pg_core.jsonb)(`default_dispatch_policy`),
@@ -866,6 +867,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,
@@ -879,6 +881,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,
@@ -897,6 +900,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,
@@ -924,6 +928,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,
@@ -1569,6 +1574,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,
@@ -3498,6 +3504,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,
@@ -4593,6 +4600,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}-${(0, node_crypto.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);
@@ -5285,7 +5326,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 {
@@ -5296,7 +5338,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) {
@@ -8534,6 +8577,15 @@ const spawnBodySchema = __sinclair_typebox.Type.Object({
 		manifestKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 	}))
 });
+const writeCollectionBodySchema = __sinclair_typebox.Type.Object({
+	operation: __sinclair_typebox.Type.Union([
+		__sinclair_typebox.Type.Literal(`insert`),
+		__sinclair_typebox.Type.Literal(`update`),
+		__sinclair_typebox.Type.Literal(`delete`)
+	]),
+	key: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	value: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Unknown()))
+}, { additionalProperties: false });
 const sendBodySchema = __sinclair_typebox.Type.Object({
 	payload: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Unknown()),
 	key: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
@@ -8666,6 +8718,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);
@@ -9064,6 +9117,23 @@ async function sendEntity(request, ctx) {
 	const result = await ctx.entityManager.send(entityUrl, sendReq);
 	return (0, itty_router.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 (0, itty_router.json)(result, { status: parsed.operation === `insert` ? 201 : 200 });
+}
 async function createAttachment(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
 	if (principalMutationError) return principalMutationError;
@@ -9161,8 +9231,13 @@ async function spawnEntity(request, ctx) {
 		headers: { "x-write-token": entity.write_token }
 	});
 }
-function getEntity(request) {
-	return (0, itty_router.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 (0, itty_router.json)({
+		...toPublicEntity(entity),
+		...entityType?.externally_writable_collections && { externally_writable_collections: entityType.externally_writable_collections }
+	});
 }
 function headEntity() {
 	return (0, itty_router.status)(200);
@@ -9197,6 +9272,16 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = __sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Unknown());
 const schemaMapSchema = __sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), jsonObjectSchema);
+const externallyWritableCollectionsSchema = __sinclair_typebox.Type.Record(__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Object({
+	type: __sinclair_typebox.Type.String(),
+	contract: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	operations: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(__sinclair_typebox.Type.Union([
+		__sinclair_typebox.Type.Literal(`insert`),
+		__sinclair_typebox.Type.Literal(`update`),
+		__sinclair_typebox.Type.Literal(`delete`)
+	]))),
+	principalColumn: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
+}, { additionalProperties: false }));
 const slashCommandArgumentSchema = __sinclair_typebox.Type.Object({
 	name: __sinclair_typebox.Type.String(),
 	type: __sinclair_typebox.Type.Union([
@@ -9227,7 +9312,8 @@ const registerEntityTypeBodySchema = __sinclair_typebox.Type.Object({
 	slash_commands: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(slashCommandSchema)),
 	serve_endpoint: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
 	default_dispatch_policy: __sinclair_typebox.Type.Optional(dispatchPolicySchema),
-	permission_grants: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(typePermissionGrantInputSchema))
+	permission_grants: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Array(typePermissionGrantInputSchema)),
+	externally_writable_collections: __sinclair_typebox.Type.Optional(externallyWritableCollectionsSchema)
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = __sinclair_typebox.Type.Object({
 	inbox_schemas: __sinclair_typebox.Type.Optional(schemaMapSchema),
@@ -9358,7 +9444,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 !== __electric_ax_agents_runtime.COMMENTS_CONTRACT) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The externally-writable collection name "comments" is reserved for the "${__electric_ax_agents_runtime.COMMENTS_CONTRACT}" contract`, 400);
+		if (config.contract === __electric_ax_agents_runtime.COMMENTS_CONTRACT && name !== `comments`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The "${__electric_ax_agents_runtime.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 ?? ``,
@@ -9372,7 +9471,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) {