@electric-ax/agents-server 0.4.11 → 0.4.13

package/dist/index.js

@@ -1960,7 +1960,8 @@ var StreamClient = class {
 				url: this.streamUrl(path$1),
 				headers: this.streamHeaders(),
 				contentType: opts.contentType,
-				body: opts.body
+				body: opts.body,
+				closed: opts.closed
 			});
 		});
 	}
@@ -2060,30 +2061,11 @@ var StreamClient = class {
 				offset: fromOffset ?? `-1`,
 				live: false
 			});
-			const messages = [];
-			return await new Promise((resolve$1, reject) => {
-				let settled = false;
-				let unsub = () => {};
-				const finish = (r) => {
-					if (settled) return;
-					settled = true;
-					unsub();
-					resolve$1(r);
-				};
-				unsub = response.subscribeBytes((chunk) => {
-					messages.push({
-						data: chunk.data,
-						offset: chunk.offset
-					});
-					if (chunk.upToDate || chunk.streamClosed) finish({ messages });
-				});
-				response.closed.then(() => finish({ messages })).catch((err) => {
-					if (settled) return;
-					settled = true;
-					unsub();
-					reject(err);
-				});
-			});
+			const body = await response.body();
+			return { messages: body.length === 0 ? [] : [{
+				data: body,
+				offset: response.offset
+			}] };
 		});
 	}
 	async readJson(path$1, fromOffset) {
@@ -2690,9 +2672,45 @@ function createInitialQueuePosition(date) {
 const DEFAULT_FORK_WAIT_TIMEOUT_MS = 12e4;
 const DEFAULT_FORK_WAIT_POLL_MS = 250;
 const SERVER_SIGNAL_SENDER = `/_electric/server`;
+const DEFAULT_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 function sleep(ms) {
 	return new Promise((resolve$1) => setTimeout(resolve$1, ms));
 }
+function maxAttachmentBytes() {
+	const configured = Number(process.env.ELECTRIC_AGENTS_MAX_ATTACHMENT_BYTES);
+	return Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : DEFAULT_MAX_ATTACHMENT_BYTES;
+}
+function manifestAttachmentKey(id) {
+	return `attachment:${id}`;
+}
+function getEntityAttachmentStreamPath(entityUrl, attachmentId) {
+	return `${entityUrl.replace(/\/+$/, ``)}/attachments/${attachmentId}`;
+}
+function isStreamCreateConflict(error) {
+	return !!error && typeof error === `object` && (`status` in error && error.status === 409 || `code` in error && error.code === `CONFLICT_SEQ`);
+}
+function assertCanonicalAttachmentStreamPath(entityUrl, attachment) {
+	const expected = getEntityAttachmentStreamPath(entityUrl, attachment.id);
+	if (attachment.streamPath === expected) return;
+	throw new ElectricAgentsError(ErrCodeInvalidRequest, `Attachment stream path does not match its entity and id`, 409);
+}
+function validateAttachmentId(id) {
+	if (!id || id.includes(`/`) || id.startsWith(`.`)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `attachment id must not be empty, start with ".", or contain forward slashes`, 400);
+}
+function validateAttachmentSubject(subject) {
+	if (!subject.key) throw new ElectricAgentsError(ErrCodeInvalidRequest, `attachment subject key is required`, 400);
+	if (subject.type !== `inbox` && subject.type !== `run` && subject.type !== `text` && subject.type !== `tool_call` && subject.type !== `context`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `invalid attachment subject type`, 400);
+}
+function concatByteMessages(messages) {
+	const total = messages.reduce((sum, message) => sum + message.data.length, 0);
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const message of messages) {
+		bytes.set(message.data, offset);
+		offset += message.data.length;
+	}
+	return bytes;
+}
 function omitUndefined$1(value) {
 	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
 }
@@ -3058,6 +3076,15 @@ var EntityManager = class {
 					await this.streamClient.fork(forkPath, sourcePath);
 					createdStreams.push(forkPath);
 				}
+				for (const plan of entityPlans) {
+					const manifests = snapshot.manifestsByEntity.get(plan.source.url) ?? new Map();
+					for (const manifest of manifests.values()) {
+						if (manifest.kind !== `attachment` || typeof manifest.streamPath !== `string` || typeof manifest.id !== `string`) continue;
+						const forkPath = getEntityAttachmentStreamPath(plan.fork.url, manifest.id);
+						await this.streamClient.fork(forkPath, manifest.streamPath);
+						createdStreams.push(forkPath);
+					}
+				}
 				for (const plan of entityPlans) {
 					const reconciliation = this.buildForkReconciliation(plan, snapshot, entityUrlMap, sharedStateIdMap, stringMap);
 					activeManifestsByEntity.set(plan.fork.url, reconciliation.manifests);
@@ -3467,6 +3494,16 @@ var EntityManager = class {
 				changed: true
 			};
 		}
+		if (next.kind === `attachment` && typeof next.streamPath === `string` && typeof next.id === `string`) for (const [sourceUrl, forkUrl] of entityUrlMap) {
+			const prefix = `${sourceUrl}/attachments/`;
+			if (!next.streamPath.startsWith(prefix)) continue;
+			next.streamPath = getEntityAttachmentStreamPath(forkUrl, next.id);
+			return {
+				key,
+				value: next,
+				changed: true
+			};
+		}
 		if (next.kind === `schedule` && next.scheduleType === `future_send`) {
 			let changed = false;
 			if (typeof next.targetUrl === `string`) {
@@ -3664,6 +3701,93 @@ var EntityManager = class {
 		const envelope = entityStateSchema.inbox.delete({ key });
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
 	}
+	isAttachmentStreamPath(path$1) {
+		return /^\/[^/]+\/[^/]+\/attachments\/[^/]+$/.test(path$1);
+	}
+	async createAttachment(entityUrl, req) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
+		if (this.isForkWorkLockedEntity(entityUrl)) this.assertEntityNotForkWorkLocked(entityUrl);
+		const id = req.id ?? randomUUID();
+		validateAttachmentId(id);
+		validateAttachmentSubject(req.subject);
+		const limit = maxAttachmentBytes();
+		if (req.bytes.length > limit) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Attachment exceeds maximum size of ${limit} bytes`, 413);
+		const mimeType = req.mimeType.trim() || `application/octet-stream`;
+		const streamPath = getEntityAttachmentStreamPath(entityUrl, id);
+		const manifestKey = manifestAttachmentKey(id);
+		const txid = randomUUID();
+		const now = new Date().toISOString();
+		const sha256 = createHash(`sha256`).update(req.bytes).digest(`hex`);
+		const attachment = {
+			key: manifestKey,
+			kind: `attachment`,
+			id,
+			streamPath,
+			status: `complete`,
+			subject: req.subject,
+			role: req.role ?? `input`,
+			mimeType,
+			...req.filename ? { filename: req.filename } : {},
+			byteLength: req.bytes.length,
+			sha256,
+			createdAt: now,
+			...req.createdBy ? { createdBy: req.createdBy } : {},
+			...req.meta ? { meta: req.meta } : {}
+		};
+		let streamCreated = false;
+		try {
+			await this.streamClient.create(streamPath, {
+				contentType: mimeType,
+				body: req.bytes,
+				closed: true
+			});
+			streamCreated = true;
+			await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, attachment, { txid });
+		} catch (error) {
+			if (streamCreated) await this.streamClient.delete(streamPath).catch(() => void 0);
+			if (!streamCreated && isStreamCreateConflict(error)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Attachment already exists at id "${id}"`, 409);
+			throw error;
+		}
+		return {
+			txid,
+			attachment
+		};
+	}
+	async getAttachment(entityUrl, id) {
+		validateAttachmentId(id);
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		const events = await this.streamClient.readJson(entity.streams.main);
+		const manifest = this.reduceStateRows(events, `manifest`).get(manifestAttachmentKey(id));
+		if (!manifest || manifest.kind !== `attachment`) return null;
+		return manifest;
+	}
+	async readAttachment(entityUrl, id) {
+		const attachment = await this.getAttachment(entityUrl, id);
+		if (!attachment) throw new ElectricAgentsError(ErrCodeNotFound, `Attachment not found`, 404);
+		if (attachment.status !== `complete`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Attachment is not complete`, 409);
+		assertCanonicalAttachmentStreamPath(entityUrl, attachment);
+		const result = await this.streamClient.read(attachment.streamPath);
+		return {
+			attachment,
+			bytes: concatByteMessages(result.messages)
+		};
+	}
+	async deleteAttachment(entityUrl, id) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
+		if (this.isForkWorkLockedEntity(entityUrl)) this.assertEntityNotForkWorkLocked(entityUrl);
+		const attachment = await this.getAttachment(entityUrl, id);
+		if (!attachment) throw new ElectricAgentsError(ErrCodeNotFound, `Attachment not found`, 404);
+		assertCanonicalAttachmentStreamPath(entityUrl, attachment);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestAttachmentKey(id), `delete`, void 0, { txid });
+		await this.streamClient.delete(attachment.streamPath).catch(() => void 0);
+		return { txid };
+	}
 	async setTag(entityUrl, key, req, token) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
@@ -6065,6 +6189,7 @@ async function handleStreamAppend(request, runtime, forward) {
 	const { manager } = runtime;
 	const entity = await manager.registry.getEntityByStream(path$1);
 	const isSharedState = path$1.startsWith(`/_electric/shared-state/`);
+	if (!entity && manager.isAttachmentStreamPath(path$1)) return apiError(401, ErrCodeUnauthorized, `Invalid write token`);
 	if (!entity && !isSharedState) return void 0;
 	const body = await request.readBody();
 	const event = decodeStreamAppendEvent(body);
@@ -6633,8 +6758,9 @@ async function streamAppend(request, ctx) {
 	}));
 }
 async function proxyPassThrough(request, ctx) {
-	const upstream = await forwardToDurableStreams(ctx, request);
 	const streamPath = new URL(request.url).pathname;
+	if (ctx.entityManager?.isAttachmentStreamPath(streamPath)) return new Response(null, { status: 404 });
+	const upstream = await forwardToDurableStreams(ctx, request);
 	const method = request.method.toUpperCase();
 	const endTrackedRead = method === `GET` ? await ctx.entityBridgeManager.beginClientRead(streamPath) : null;
 	try {
@@ -6787,6 +6913,13 @@ const eventSourceSubscriptionBodySchema = Type.Object({
 	lifetime: Type.Optional(subscriptionLifetimeSchema),
 	reason: Type.Optional(Type.String())
 });
+const attachmentSubjectTypes = new Set([
+	`inbox`,
+	`run`,
+	`text`,
+	`tool_call`,
+	`context`
+]);
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
 entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), spawnEntity);
@@ -6795,6 +6928,9 @@ entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity);
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity);
 entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), signalEntity);
 entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, createAttachment);
+entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, readAttachment);
+entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, deleteAttachment);
 entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), updateInboxMessage);
 entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, deleteInboxMessage);
 entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), forkEntity);
@@ -6821,6 +6957,82 @@ function requireExistingEntityRoute(request) {
 	if (!request.entityRoute) throw new Error(`existing entity middleware did not run`);
 	return request.entityRoute;
 }
+function invalidAttachmentRequest(message) {
+	throw new ElectricAgentsError(ErrCodeInvalidRequest, message, 400);
+}
+function formString(form, key) {
+	const value = form.get(key);
+	if (typeof value !== `string`) return void 0;
+	const trimmed = value.trim();
+	return trimmed || void 0;
+}
+function parseJsonFormField(form, key) {
+	const raw = formString(form, key);
+	if (!raw) return void 0;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		invalidAttachmentRequest(`Invalid JSON field: ${key}`);
+	}
+}
+function parseAttachmentSubject(form) {
+	const explicit = parseJsonFormField(form, `subject`);
+	if (explicit !== void 0) {
+		if (!explicit || typeof explicit !== `object` || Array.isArray(explicit)) invalidAttachmentRequest(`attachment subject must be an object`);
+		const subject = explicit;
+		const type$1 = subject.type;
+		const key$1 = subject.key;
+		if (typeof type$1 !== `string` || typeof key$1 !== `string`) invalidAttachmentRequest(`attachment subject requires type and key`);
+		if (!attachmentSubjectTypes.has(type$1)) invalidAttachmentRequest(`invalid attachment subject type`);
+		return {
+			type: type$1,
+			key: key$1
+		};
+	}
+	const type = formString(form, `subjectType`);
+	const key = formString(form, `subjectKey`);
+	if (!type || !key) invalidAttachmentRequest(`attachment subject is required`);
+	if (!attachmentSubjectTypes.has(type)) invalidAttachmentRequest(`invalid attachment subject type`);
+	return {
+		type,
+		key
+	};
+}
+function getUploadedFormFile(value) {
+	if (value !== null && typeof value === `object` && `arrayBuffer` in value && typeof value.arrayBuffer === `function`) return value;
+	return null;
+}
+async function parseAttachmentForm(request) {
+	const contentType = request.headers.get(`content-type`)?.toLowerCase() ?? ``;
+	if (!contentType.includes(`multipart/form-data`)) invalidAttachmentRequest(`Attachment uploads must use multipart/form-data`);
+	let form;
+	try {
+		form = await request.formData();
+	} catch {
+		invalidAttachmentRequest(`Invalid multipart form data`);
+	}
+	const file = getUploadedFormFile(form.get(`file`));
+	if (!file) invalidAttachmentRequest(`Missing file field`);
+	const role = formString(form, `role`);
+	if (role !== void 0 && role !== `input` && role !== `output`) invalidAttachmentRequest(`invalid attachment role`);
+	const fileName = formString(form, `filename`) ?? (typeof file.name === `string` ? file.name : void 0);
+	const mimeType = formString(form, `mimeType`) || (typeof file.type === `string` ? file.type : void 0) || `application/octet-stream`;
+	const meta = parseJsonFormField(form, `meta`);
+	if (meta !== void 0 && (typeof meta !== `object` || Array.isArray(meta))) invalidAttachmentRequest(`attachment meta must be an object`);
+	return {
+		id: formString(form, `id`),
+		bytes: new Uint8Array(await file.arrayBuffer()),
+		mimeType,
+		filename: fileName,
+		subject: parseAttachmentSubject(form),
+		role,
+		meta
+	};
+}
+function contentDisposition(filename) {
+	const fallback = filename.replace(/["\\\r\n]/g, `_`);
+	return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
 function rejectPrincipalEntityMutation(request, action) {
 	const { entity } = requireExistingEntityRoute(request);
 	if (entity.type !== `principal`) return void 0;
@@ -7005,6 +7217,44 @@ async function sendEntity(request, ctx) {
 	});
 	return status(204);
 }
+async function createAttachment(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
+	if (principalMutationError) return principalMutationError;
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const form = await parseAttachmentForm(request);
+	const result = await ctx.entityManager.createAttachment(entityUrl, {
+		id: form.id,
+		bytes: form.bytes,
+		mimeType: form.mimeType,
+		filename: form.filename,
+		subject: form.subject,
+		role: form.role,
+		createdBy: ctx.principal.url,
+		meta: form.meta
+	});
+	return json(result, { status: 201 });
+}
+async function readAttachment(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.readAttachment(entityUrl, decodeURIComponent(request.params.attachmentId));
+	const headers = new Headers({
+		"content-type": result.attachment.mimeType,
+		"content-length": String(result.bytes.length),
+		"cache-control": `private, max-age=31536000, immutable`
+	});
+	if (result.attachment.filename) headers.set(`content-disposition`, contentDisposition(result.attachment.filename));
+	return new Response(result.bytes, {
+		status: 200,
+		headers
+	});
+}
+async function deleteAttachment(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `stripped of attachments`);
+	if (principalMutationError) return principalMutationError;
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.deleteAttachment(entityUrl, decodeURIComponent(request.params.attachmentId));
+	return json(result);
+}
 async function updateInboxMessage(request, ctx) {
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -36,9 +36,9 @@
   "sideEffects": false,
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@durable-streams/client": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/client@5d5c217",
-    "@durable-streams/server": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/server@eac712f",
-    "@durable-streams/state": "https://pkg.pr.new/durable-streams/durable-streams/@durable-streams/state@5d5c217",
+    "@durable-streams/client": "^0.2.6",
+    "@durable-streams/server": "^0.3.5",
+    "@durable-streams/state": "^0.2.9",
     "@electric-sql/client": "^1.5.19",
     "@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.5"
+    "@electric-ax/agents-runtime": "0.3.6"
   },
   "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.9",
-    "@electric-ax/agents-server-ui": "0.4.11",
-    "@electric-ax/agents-server-conformance-tests": "0.1.8"
+    "@electric-ax/agents": "0.4.10",
+    "@electric-ax/agents-server-conformance-tests": "0.1.9",
+    "@electric-ax/agents-server-ui": "0.4.13"
   },
   "files": [
     "dist",