@electric-ax/agents-server 0.4.12 → 0.4.14

package/dist/index.cjs

@@ -1218,35 +1218,48 @@ const LOG_LEVEL = process.env.ELECTRIC_AGENTS_LOG_LEVEL ?? `info`;
 const IS_ELECTRON_MAIN = Boolean(process.versions.electron);
 const USE_FILE_LOGS = process.env.ELECTRIC_AGENTS_LOG_FILE !== `false`;
 const USE_PRETTY_LOGS = LOG_LEVEL !== `silent` && !process.env.VITEST && !IS_ELECTRON_MAIN;
-const LOG_DIR = USE_FILE_LOGS ? process.env.ELECTRIC_AGENTS_LOG_DIR ?? node_path.default.resolve(process.cwd(), `logs`) : void 0;
-const LOG_FILE = LOG_DIR ? node_path.default.join(LOG_DIR, `agent-server-${Date.now()}.jsonl`) : void 0;
-if (LOG_DIR) node_fs.default.mkdirSync(LOG_DIR, { recursive: true });
-const streams = [];
-if (LOG_FILE) streams.push({ stream: pino.default.destination({
-	dest: LOG_FILE,
-	sync: IS_ELECTRON_MAIN
-}) });
-if (USE_PRETTY_LOGS) streams.push({ stream: pino.default.transport({
-	target: `pino-pretty`,
-	options: {
-		colorize: true,
-		ignore: `pid,hostname,name`,
-		translateTime: `SYS:HH:MM:ss`
-	}
-}) });
-const logger = streams.length > 0 ? (0, pino.default)({
-	base: void 0,
-	level: LOG_LEVEL
-}, pino.default.multistream(streams)) : (0, pino.default)({
-	base: void 0,
-	enabled: false,
-	level: LOG_LEVEL
-});
+let _logger;
+function getLogger() {
+	if (_logger) return _logger;
+	const streams = [];
+	try {
+		if (USE_FILE_LOGS) {
+			const logDir = process.env.ELECTRIC_AGENTS_LOG_DIR ?? node_path.default.resolve(process.cwd(), `logs`);
+			node_fs.default.mkdirSync(logDir, { recursive: true });
+			const logFile = node_path.default.join(logDir, `agent-server-${Date.now()}.jsonl`);
+			streams.push({ stream: pino.default.destination({
+				dest: logFile,
+				sync: IS_ELECTRON_MAIN
+			}) });
+		}
+	} catch (err) {
+		process.stderr.write(`[agents-server] Failed to initialize file logging: ${err instanceof Error ? err.message : err}\n`);
+	}
+	try {
+		if (USE_PRETTY_LOGS) streams.push({ stream: pino.default.transport({
+			target: `pino-pretty`,
+			options: {
+				colorize: true,
+				ignore: `pid,hostname,name`,
+				translateTime: `SYS:HH:MM:ss`
+			}
+		}) });
+	} catch {}
+	_logger = streams.length > 0 ? (0, pino.default)({
+		base: void 0,
+		level: LOG_LEVEL
+	}, pino.default.multistream(streams)) : (0, pino.default)({
+		base: void 0,
+		enabled: false,
+		level: LOG_LEVEL
+	});
+	return _logger;
+}
 function formatArgs(args) {
 	const errors = [];
 	const parts = [];
-	for (const a of args) if (a instanceof Error) errors.push(a);
-	else parts.push(typeof a === `string` ? a : JSON.stringify(a));
+	for (const value of args) if (value instanceof Error) errors.push(value);
+	else parts.push(typeof value === `string` ? value : JSON.stringify(value));
 	return {
 		err: errors[0],
 		msg: parts.join(` `)
@@ -1255,20 +1268,20 @@ function formatArgs(args) {
 const serverLog = {
 	info(...args) {
 		const { msg } = formatArgs(args);
-		logger.info(msg);
+		getLogger().info(msg);
 	},
 	warn(...args) {
 		const { err, msg } = formatArgs(args);
-		if (err) logger.warn({ err }, msg);
-		else logger.warn(msg);
+		if (err) getLogger().warn({ err }, msg);
+		else getLogger().warn(msg);
 	},
 	error(...args) {
 		const { err, msg } = formatArgs(args);
-		if (err) logger.error({ err }, msg);
-		else logger.error(msg);
+		if (err) getLogger().error({ err }, msg);
+		else getLogger().error(msg);
 	},
 	event(obj, msg) {
-		logger.info(obj, msg);
+		getLogger().info(obj, msg);
 	}
 };
 
@@ -1989,7 +2002,8 @@ var StreamClient = class {
 				url: this.streamUrl(path$2),
 				headers: this.streamHeaders(),
 				contentType: opts.contentType,
-				body: opts.body
+				body: opts.body,
+				closed: opts.closed
 			});
 		});
 	}
@@ -2089,30 +2103,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$2, fromOffset) {
@@ -2266,11 +2261,11 @@ var StreamClient = class {
 		if (res.status === 404 || res.status === 204) return;
 		if (!res.ok) throw new Error(`Subscription delete failed: ${res.status} ${await res.text()}`);
 	}
-	async addSubscriptionStreams(subscriptionId, streams$1) {
+	async addSubscriptionStreams(subscriptionId, streams) {
 		const res = await fetch(this.subscriptionChildUrl(subscriptionId, `streams`), {
 			method: `POST`,
 			headers: await this.requestHeaders({ "content-type": `application/json` }),
-			body: JSON.stringify({ streams: streams$1.map((stream) => this.backendSubscriptionPath(normalizeSubscriptionStreamPath(stream))) })
+			body: JSON.stringify({ streams: streams.map((stream) => this.backendSubscriptionPath(normalizeSubscriptionStreamPath(stream))) })
 		});
 		return await this.subscriptionJson(res, `Subscription stream add failed`);
 	}
@@ -2719,9 +2714,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));
 }
@@ -3087,6 +3118,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);
@@ -3496,6 +3536,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`) {
@@ -3693,6 +3743,93 @@ var EntityManager = class {
 		const envelope = __electric_ax_agents_runtime.entityStateSchema.inbox.delete({ key });
 		await this.streamClient.append(entity.streams.main, this.encodeChangeEvent(envelope));
 	}
+	isAttachmentStreamPath(path$2) {
+		return /^\/[^/]+\/[^/]+\/attachments\/[^/]+$/.test(path$2);
+	}
+	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 ?? (0, node_crypto.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 = (0, node_crypto.randomUUID)();
+		const now = new Date().toISOString();
+		const sha256 = (0, node_crypto.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 = (0, node_crypto.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);
@@ -6094,6 +6231,7 @@ async function handleStreamAppend(request, runtime, forward) {
 	const { manager } = runtime;
 	const entity = await manager.registry.getEntityByStream(path$2);
 	const isSharedState = path$2.startsWith(`/_electric/shared-state/`);
+	if (!entity && manager.isAttachmentStreamPath(path$2)) return apiError(401, ErrCodeUnauthorized, `Invalid write token`);
 	if (!entity && !isSharedState) return void 0;
 	const body = await request.readBody();
 	const event = decodeStreamAppendEvent(body);
@@ -6662,8 +6800,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 {
@@ -6816,6 +6955,13 @@ const eventSourceSubscriptionBodySchema = __sinclair_typebox.Type.Object({
 	lifetime: __sinclair_typebox.Type.Optional(subscriptionLifetimeSchema),
 	reason: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
 });
+const attachmentSubjectTypes = new Set([
+	`inbox`,
+	`run`,
+	`text`,
+	`tool_call`,
+	`context`
+]);
 const entitiesRouter = (0, itty_router.Router)({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
 entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), spawnEntity);
@@ -6824,6 +6970,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);
@@ -6850,6 +6999,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;
@@ -7034,6 +7259,44 @@ async function sendEntity(request, ctx) {
 	});
 	return (0, itty_router.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 (0, itty_router.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 (0, itty_router.json)(result);
+}
 async function updateInboxMessage(request, ctx) {
 	const parsed = routeBody(request);
 	const { entityUrl } = requireExistingEntityRoute(request);
@@ -7634,7 +7897,7 @@ async function notificationFromClaim(ctx, input) {
 		leaseExpiresAt: input.claim.lease_ttl_ms ? new Date(Date.now() + input.claim.lease_ttl_ms) : void 0
 	});
 	await ctx.entityManager.registry.updateStatus(entity.url, `running`);
-	const streams$1 = input.claim.streams.map((stream) => ({
+	const streams = input.claim.streams.map((stream) => ({
 		path: withLeadingSlash(stream.path),
 		offset: stream.tail_offset ?? ``
 	}));
@@ -7643,7 +7906,7 @@ async function notificationFromClaim(ctx, input) {
 		epoch: input.claim.generation,
 		wakeId: input.claim.wake_id,
 		streamPath: primaryStream,
-		streams: streams$1,
+		streams,
 		callback: (0, __electric_ax_agents_runtime.appendPathToUrl)(ctx.publicUrl, `/_electric/wake-callbacks/${encodeURIComponent(input.claim.wake_id)}`),
 		claimToken: input.claim.token,
 		triggerEvent: `message_received`,

package/dist/index.d.cts

@@ -3723,6 +3723,7 @@ declare class StreamClient {
   create(path: string, opts: {
     contentType: string;
     body?: Uint8Array | string;
+    closed?: boolean;
   }): Promise<void>;
   fork(path: string, sourcePath: string): Promise<void>;
   append(path: string, data: Uint8Array | string, opts?: {
@@ -4075,6 +4076,45 @@ declare class SchemaValidator {
 //#endregion
 //#region src/entity-manager.d.ts
 type WriteTokenValidator = (entity: ElectricAgentsEntity, token: string) => boolean;
+type AttachmentSubjectType = `inbox` | `run` | `text` | `tool_call` | `context`;
+type AttachmentRole = `input` | `output`;
+interface CreateAttachmentRequest {
+  id?: string;
+  bytes: Uint8Array;
+  mimeType: string;
+  filename?: string;
+  subject: {
+    type: AttachmentSubjectType;
+    key: string;
+  };
+  role?: AttachmentRole;
+  createdBy?: string;
+  meta?: Record<string, unknown>;
+}
+interface ReadAttachmentResult {
+  attachment: ManifestAttachmentEntry;
+  bytes: Uint8Array;
+}
+type ManifestAttachmentEntry = {
+  key: string;
+  kind: `attachment`;
+  id: string;
+  streamPath: string;
+  status: `pending` | `complete` | `failed`;
+  subject: {
+    type: AttachmentSubjectType;
+    key: string;
+  };
+  role: AttachmentRole;
+  mimeType: string;
+  filename?: string;
+  byteLength?: number;
+  sha256?: string;
+  createdAt: string;
+  createdBy?: string;
+  error?: string;
+  meta?: Record<string, unknown>;
+};
 type ForkSubtreeOptions = {
   rootInstanceId?: string;
   waitTimeoutMs?: number;
@@ -4171,6 +4211,16 @@ declare class EntityManager {
     status?: `pending` | `processed` | `cancelled`;
   }): Promise<void>;
   deleteInboxMessage(entityUrl: string, key: string): Promise<void>;
+  isAttachmentStreamPath(path: string): boolean;
+  createAttachment(entityUrl: string, req: CreateAttachmentRequest): Promise<{
+    txid: string;
+    attachment: ManifestAttachmentEntry;
+  }>;
+  getAttachment(entityUrl: string, id: string): Promise<ManifestAttachmentEntry | null>;
+  readAttachment(entityUrl: string, id: string): Promise<ReadAttachmentResult>;
+  deleteAttachment(entityUrl: string, id: string): Promise<{
+    txid: string;
+  }>;
   setTag(entityUrl: string, key: string, req: SetTagRequest, token: string): Promise<ElectricAgentsEntity>;
   deleteTag(entityUrl: string, key: string, token: string): Promise<ElectricAgentsEntity>;
   ensureEntitiesMembershipStream(tags: Record<string, string>): Promise<{

package/dist/index.d.ts

@@ -3724,6 +3724,7 @@ declare class StreamClient {
   create(path: string, opts: {
     contentType: string;
     body?: Uint8Array | string;
+    closed?: boolean;
   }): Promise<void>;
   fork(path: string, sourcePath: string): Promise<void>;
   append(path: string, data: Uint8Array | string, opts?: {
@@ -4076,6 +4077,45 @@ declare class SchemaValidator {
 //#endregion
 //#region src/entity-manager.d.ts
 type WriteTokenValidator = (entity: ElectricAgentsEntity, token: string) => boolean;
+type AttachmentSubjectType = `inbox` | `run` | `text` | `tool_call` | `context`;
+type AttachmentRole = `input` | `output`;
+interface CreateAttachmentRequest {
+  id?: string;
+  bytes: Uint8Array;
+  mimeType: string;
+  filename?: string;
+  subject: {
+    type: AttachmentSubjectType;
+    key: string;
+  };
+  role?: AttachmentRole;
+  createdBy?: string;
+  meta?: Record<string, unknown>;
+}
+interface ReadAttachmentResult {
+  attachment: ManifestAttachmentEntry;
+  bytes: Uint8Array;
+}
+type ManifestAttachmentEntry = {
+  key: string;
+  kind: `attachment`;
+  id: string;
+  streamPath: string;
+  status: `pending` | `complete` | `failed`;
+  subject: {
+    type: AttachmentSubjectType;
+    key: string;
+  };
+  role: AttachmentRole;
+  mimeType: string;
+  filename?: string;
+  byteLength?: number;
+  sha256?: string;
+  createdAt: string;
+  createdBy?: string;
+  error?: string;
+  meta?: Record<string, unknown>;
+};
 type ForkSubtreeOptions = {
   rootInstanceId?: string;
   waitTimeoutMs?: number;
@@ -4172,6 +4212,16 @@ declare class EntityManager {
     status?: `pending` | `processed` | `cancelled`;
   }): Promise<void>;
   deleteInboxMessage(entityUrl: string, key: string): Promise<void>;
+  isAttachmentStreamPath(path: string): boolean;
+  createAttachment(entityUrl: string, req: CreateAttachmentRequest): Promise<{
+    txid: string;
+    attachment: ManifestAttachmentEntry;
+  }>;
+  getAttachment(entityUrl: string, id: string): Promise<ManifestAttachmentEntry | null>;
+  readAttachment(entityUrl: string, id: string): Promise<ReadAttachmentResult>;
+  deleteAttachment(entityUrl: string, id: string): Promise<{
+    txid: string;
+  }>;
   setTag(entityUrl: string, key: string, req: SetTagRequest, token: string): Promise<ElectricAgentsEntity>;
   deleteTag(entityUrl: string, key: string, token: string): Promise<ElectricAgentsEntity>;
   ensureEntitiesMembershipStream(tags: Record<string, string>): Promise<{