Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

28.8 KB
Raw Blame
// Private module: agent sub-resource handlers dispatched from [id].js.
// Not a Vercel function (underscore prefix). Handlers accept (req, res, id).

import { verifyMessage } from 'ethers';
import { Wallet } from 'ethers';
import { z } from 'zod';
import { sql } from '../../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../../_lib/auth.js';
import { assertBearerMaySpend } from '../../_lib/spend-scope.js';
import { cors, json, method, readJson, wrap, error, rateLimited, embedReadCors } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { requireCsrf } from '../../_lib/csrf.js';
import { parse } from '../../_lib/validate.js';
import { recoverAgentKey } from '../../_lib/agent-wallet.js';
import { readEmbedPolicy, validateEmbedPolicy } from '../../_lib/embed-policy.js';
import { resolveAvatarUrl } from '../../_lib/avatars.js';
import { buildAgentRegistrationMetadata } from '../../_lib/three-brand.js';
import { thumbnailUrl } from '../../_lib/r2.js';
// The one source of truth for the gesture slot vocabulary. Dependency-free, so
// importing the runtime module here keeps the API and the browser in agreement
// instead of restating the list.
import { SLOTS } from '../../../src/runtime/animation-slots.js';
// Same reasoning for gesture routines: the studio, the avatar runtime and this
// handler share one definition of a valid routine instead of three.
import { normalizeRoutines, MAX_ROUTINES } from '../../../src/runtime/choreography.js';

async function resolveAuth(req) {
	const session = await getSessionUser(req);
	if (session) return { userId: session.id };
	const bearer = await authenticateBearer(extractBearer(req));
	if (bearer) return { userId: bearer.userId, bearer };
	return null;
}

// ── actions ───────────────────────────────────────────────────────────────────

export const handleActions = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (req.method !== 'GET') return error(res, 405, 'method_not_allowed', 'GET only');

	const session = await getSessionUser(req);
	const bearer = session ? null : await authenticateBearer(extractBearer(req));
	const userId = session?.id ?? bearer?.userId;

	const [agent] =
		await sql`SELECT id, user_id, name, wallet_address FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	if (!userId || agent.user_id !== userId)
		return error(res, 403, 'forbidden', 'not authorized to view this agent');

	const url = new URL(req.url, 'http://x');
	const limit = Math.min(Number(url.searchParams.get('limit')) || 50, 200);
	const cursor = url.searchParams.get('cursor');

	// Cursor format: `<iso_timestamp>|<id>`. The `|<id>` tiebreaker prevents
	// row skipping or duplication when multiple actions share the same
	// `created_at` (sub-millisecond bursts during high-volume logging
	// previously caused either silently-dropped rows or repeated rows across
	// page boundaries because `created_at < $cursor` is not a strict total
	// order). Old cursors without a `|` keep working via the timestamp-only
	// branch below; new cursors always include the id.
	let parsedCursorTs = null;
	let parsedCursorId = null;
	if (cursor) {
		const pipe = cursor.indexOf('|');
		if (pipe > 0) {
			parsedCursorTs = cursor.slice(0, pipe);
			parsedCursorId = cursor.slice(pipe + 1);
		} else {
			parsedCursorTs = cursor;
		}
	}

	let actions;
	if (parsedCursorTs && parsedCursorId) {
		actions = await sql`
			SELECT id, type, payload, source_skill, signature, signer_address, created_at
			FROM agent_actions
			WHERE agent_id = ${id}
			  AND (created_at < ${parsedCursorTs}
			       OR (created_at = ${parsedCursorTs} AND id < ${parsedCursorId}))
			ORDER BY created_at DESC, id DESC
			LIMIT ${limit + 1}
		`;
	} else if (parsedCursorTs) {
		actions = await sql`
			SELECT id, type, payload, source_skill, signature, signer_address, created_at
			FROM agent_actions
			WHERE agent_id = ${id} AND created_at < ${parsedCursorTs}
			ORDER BY created_at DESC, id DESC
			LIMIT ${limit + 1}
		`;
	} else {
		actions = await sql`
			SELECT id, type, payload, source_skill, signature, signer_address, created_at
			FROM agent_actions
			WHERE agent_id = ${id}
			ORDER BY created_at DESC, id DESC
			LIMIT ${limit + 1}
		`;
	}

	const hasMore = actions.length > limit;
	const trimmed = hasMore ? actions.slice(0, limit) : actions;

	const decorated = trimmed.map((row) => {
		let verified = null;
		if (row.signature && row.signer_address && row.payload) {
			try {
				const recovered = verifyMessage(
					JSON.stringify(row.payload) + row.created_at.toISOString(),
					row.signature,
				);
				verified = recovered.toLowerCase() === row.signer_address.toLowerCase();
			} catch {
				verified = false;
			}
		}
		return {
			id: String(row.id),
			type: row.type,
			payload: row.payload,
			sourceSkill: row.source_skill,
			timestamp: row.created_at.toISOString(),
			signature: row.signature || null,
			signer: row.signer_address || null,
			verified,
		};
	});

	res.setHeader('Cache-Control', 'private, max-age=10');
	const last = trimmed[trimmed.length - 1];
	return json(res, 200, {
		actions: decorated,
		nextCursor: hasMore && last ? `${last.created_at.toISOString()}|${last.id}` : null,
	});
});

// ── animations ────────────────────────────────────────────────────────────────

const animationEntrySchema = z.object({
	name: z.string().trim().min(1).max(60),
	url: z
		.string()
		.trim()
		.min(1)
		.max(2048)
		.refine(
			(u) => /^(https?|ipfs|ar):\/\//.test(u) || u.startsWith('/') || /^u\//.test(u),
			'url must be http, https, ipfs, ar, root-relative, or storage key',
		),
	loop: z.boolean().default(true),
	clipName: z.string().trim().max(120).optional(),
	source: z.enum(['mixamo', 'preset', 'custom']),
	addedAt: z.string().optional(),
});

// Animation state machine — optional graph stored alongside the flat clip
// list. The runtime AnimationStateMachine fills in defaults for any state
// not explicitly mapped here; the editor only persists overrides.
const animationStateSchema = z
	.object({
		clip: z.string().trim().min(1).max(60).optional(),
		loop: z.boolean().optional(),
		crossfade: z.number().min(0).max(5).optional(),
		oneShot: z.boolean().optional(),
		returnTo: z.string().trim().min(1).max(40).nullable().optional(),
	})
	.strict();

const animationGraphSchema = z
	.object({
		states: z.record(animationStateSchema).optional(),
		transitions: z.record(z.string().trim().min(1).max(40)).optional(),
		initial: z.string().trim().min(1).max(40).optional(),
	})
	.strict();

// Gesture slot overrides: { slot: clipName }, persisted at meta.edits.animations,
// which is where src/agent-avatar.js reads an agent's per-slot bindings from.
// Keys are restricted to the fixed vocabulary (src/runtime/animation-slots.js) so
// a typo cannot create a slot nothing will ever play; values are clip names,
// deliberately not restricted to the platform manifest so an agent can point a
// slot at one of its own uploaded clips. An empty object clears every override.
const animationSlotsSchema = z
	.partialRecord(
		z.enum(/** @type {[string, ...string[]]} */ (SLOTS)),
		z
			.string()
			.trim()
			.min(1)
			.max(60)
			.regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/, 'clip name must be alphanumeric with - or _'),
	)
	.refine((map) => Object.keys(map).length <= SLOTS.length, 'too many slot overrides');

// Choreographies: named, timed gesture routines, persisted at
// meta.choreographies and served to embeds in the public manifest. Validation
// is delegated to the same runtime module the studio and the avatar use
// (src/runtime/choreography.js) rather than restated in zod, so a routine the
// browser can build is exactly a routine the server will store. An empty array
// clears them.
const choreographiesSchema = z.array(z.unknown()).max(MAX_ROUTINES).transform((list, ctx) => {
	try {
		return normalizeRoutines(list);
	} catch (err) {
		ctx.addIssue({ code: z.ZodIssueCode.custom, message: err.message });
		return z.NEVER;
	}
});

// Every field is optional and every one follows the same rule: present means
// "replace this", absent means "leave it alone". `animations` used to be
// required, which meant a caller changing one gesture slot had to resend the
// agent's whole clip list, and sending `[]` (the obvious thing when you do not
// use the list) silently wiped it.
const animationsBodySchema = z
	.object({
		animations: z.array(animationEntrySchema).max(30).optional(),
		animationGraph: animationGraphSchema.optional(),
		animationSlots: animationSlotsSchema.optional(),
		choreographies: choreographiesSchema.optional(),
	})
	.refine(
		(b) =>
			b.animations !== undefined ||
			b.animationGraph !== undefined ||
			b.animationSlots !== undefined ||
			b.choreographies !== undefined,
		'send at least one of animations, animationGraph, animationSlots, choreographies',
	);

export const handleAnimations = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'PUT,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['PUT'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

	// CSRF on state-changing session-cookie requests; bearer tokens are exempt.
	if (!(await requireCsrf(req, res, auth.userId))) return;

	const [existing] =
		await sql`SELECT id, user_id FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!existing) return error(res, 404, 'not_found', 'agent not found');
	if (existing.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');

	const rawBody = await readJson(req);
	let parsed;
	try {
		parsed = animationsBodySchema.parse(rawBody);
	} catch (err) {
		if (err.name === 'ZodError')
			return error(res, 400, 'validation_error', err.errors[0]?.message || 'invalid body', {
				fields: err.errors,
			});
		throw err;
	}

	// Only touch meta.animationGraph when the request actually carries the
	// field, so saving the clip-array on its own doesn't clobber an existing
	// graph. `null` is a valid explicit "remove the graph" signal. Same rule for
	// the slot overrides at meta.edits.animations: absent means "leave alone",
	// `{}` means "clear them".
	const has = (key) => Object.prototype.hasOwnProperty.call(rawBody || {}, key);
	if (has('animations')) {
		await sql`
			UPDATE agent_identities
			SET meta = jsonb_set(COALESCE(meta, '{}'::jsonb), '{animations}', ${JSON.stringify(parsed.animations)}::jsonb, true)
			WHERE id = ${id}
		`;
	}
	if (has('animationGraph')) {
		await sql`
			UPDATE agent_identities
			SET meta = jsonb_set(COALESCE(meta, '{}'::jsonb), '{animationGraph}',
				${parsed.animationGraph ? JSON.stringify(parsed.animationGraph) : 'null'}::jsonb, true)
			WHERE id = ${id}
		`;
	}
	if (has('animationSlots')) {
		// jsonb_set cannot create the intermediate {edits} object, so seed it first
		// for agents that have never carried one.
		await sql`
			UPDATE agent_identities
			SET meta = jsonb_set(
				CASE WHEN COALESCE(meta, '{}'::jsonb) ? 'edits'
					THEN COALESCE(meta, '{}'::jsonb)
					ELSE jsonb_set(COALESCE(meta, '{}'::jsonb), '{edits}', '{}'::jsonb, true)
				END,
				'{edits,animations}', ${JSON.stringify(parsed.animationSlots ?? {})}::jsonb, true)
			WHERE id = ${id}
		`;
	}

	if (has('choreographies')) {
		await sql`
			UPDATE agent_identities
			SET meta = jsonb_set(COALESCE(meta, '{}'::jsonb), '{choreographies}',
				${JSON.stringify(parsed.choreographies ?? [])}::jsonb, true)
			WHERE id = ${id}
		`;
	}

	// Read back what is actually stored so the response cannot drift from the row,
	// and so a partial update still reports the fields it did not touch.
	const [row] = await sql`
		SELECT meta->'animations' AS animations,
		       meta->'animationGraph' AS graph,
		       meta->'edits'->'animations' AS slots,
		       meta->'choreographies' AS choreographies
		FROM agent_identities WHERE id = ${id}
	`;
	return json(res, 200, {
		animations: row?.animations ?? [],
		animationGraph: row?.graph ?? null,
		animationSlots: row?.slots ?? null,
		choreographies: row?.choreographies ?? [],
	});
});

// ── embed-policy ──────────────────────────────────────────────────────────────

export const handleEmbedPolicy = wrap(async (req, res, id) => {
	if (embedReadCors(req, res, { authedMethods: 'GET,PUT,DELETE,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'PUT', 'DELETE'])) return;

	if (req.method === 'GET') {
		// Embed clients fetch this on every page load to gate surface/origin.
		// Treat a missing agent the same as a missing policy (fail-open) so
		// public embed contexts don't log a 404 in the console on every boot.
		const policy = await readEmbedPolicy(id);
		return json(res, 200, { policy: policy ?? null });
	}

	const session = await getSessionUser(req);
	if (!session) return error(res, 401, 'unauthorized', 'sign in required');

	// CSRF on state-changing session-cookie requests (PUT/DELETE reach here).
	if (!(await requireCsrf(req, res, session.id))) return;

	const [existing] =
		await sql`SELECT id, user_id FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!existing) return error(res, 404, 'not_found', 'agent not found');
	if (existing.user_id !== session.id) return error(res, 403, 'forbidden', 'not your agent');

	if (req.method === 'DELETE') {
		await sql`UPDATE agent_identities SET embed_policy = NULL WHERE id = ${id}`;
		return json(res, 200, { policy: null });
	}

	let normalized;
	try {
		normalized = validateEmbedPolicy(await readJson(req));
	} catch (err) {
		if (err.name === 'ZodError')
			return error(res, 400, 'validation_error', err.errors[0]?.message || 'invalid policy', {
				fields: err.errors,
			});
		throw err;
	}

	const [updated] =
		await sql`UPDATE agent_identities SET embed_policy = ${JSON.stringify(normalized)}::jsonb WHERE id = ${id} RETURNING embed_policy`;
	return json(res, 200, { policy: updated.embed_policy });
});

// ── manifest ──────────────────────────────────────────────────────────────────

export const handleManifest = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	if (!/^[0-9a-f-]{36}$/i.test(id))
		return error(res, 400, 'invalid_request', 'agent id required');

	const [row] =
		await sql`select a.id, a.name, a.description, a.avatar_id, a.skills, a.meta, a.chain_id, a.erc8004_agent_id, a.erc8004_registry, a.registration_cid, a.created_at, a.voice_provider, a.voice_id, a.voice_model, a.voice_settings, a.persona_prompt_hash, a.persona_tone_tags, a.persona_extracted_at, a.persona_traits, av.id as avatar_db_id, av.storage_key, av.content_type from agent_identities a left join avatars av on av.id = a.avatar_id and av.deleted_at is null where a.id = ${id} and a.deleted_at is null limit 1`;
	if (!row) return error(res, 404, 'not_found', 'agent not found');

	// Live signal: whether the agent has claimed its activation grant (funded +
	// on the Money Pulse). Lets other agents/SDKs prefer live counterparts. Cheap
	// indexed PK lookup; tolerant of the table not being migrated yet.
	let activated = false;
	let activatedAt = null;
	try {
		const [act] = await sql`select confirmed_at from agent_activations where agent_id = ${id} and status = 'confirmed' limit 1`;
		if (act) {
			activated = true;
			activatedAt = act.confirmed_at;
		}
	} catch (e) {
		if (e?.code !== '42P01') console.warn('[manifest] activation lookup failed', e?.message);
	}

	let bodyUri = '';
	if (row.avatar_db_id) {
		try {
			const urlInfo = await resolveAvatarUrl({
				storage_key: row.storage_key,
				visibility: 'public',
			});
			bodyUri = urlInfo?.url || '';
		} catch {}
	}

	const proto = req.headers['x-forwarded-proto'] || 'https';
	const host = req.headers['x-forwarded-host'] || req.headers.host || 'three.ws';
	const origin = process.env.PUBLIC_APP_ORIGIN?.replace(/\/$/, '') || `${proto}://${host}`;

	// Interview provenance counts. persona_traits.interview carries the full
	// record (including the owner's raw answers), but the public manifest only
	// ever reports the counts and the source, never the answers themselves.
	const interviewRaw =
		row.persona_traits && typeof row.persona_traits === 'object'
			? row.persona_traits.interview
			: null;
	const interview =
		interviewRaw && typeof interviewRaw === 'object'
			? {
					source: typeof interviewRaw.source === 'string' ? interviewRaw.source : null,
					questions_answered: Number.isFinite(interviewRaw.questions_answered)
						? interviewRaw.questions_answered
						: Array.isArray(interviewRaw.answers)
							? interviewRaw.answers.length
							: 0,
					questions_total: Number.isFinite(interviewRaw.questions_total)
						? interviewRaw.questions_total
						: null,
				}
			: null;

	const manifest = {
		$schema: 'https://3d-agent.io/schemas/manifest/0.1.json',
		spec: 'agent-manifest/0.1',
		id: row.id,
		name: row.name || 'Agent',
		description: row.description || '',
		image: '',
		tags: Array.isArray(row.meta?.tags) ? row.meta.tags : [],
		body: bodyUri ? { uri: bodyUri, format: row.content_type || 'gltf-binary' } : undefined,
		skills: Array.isArray(row.skills) ? row.skills : [],
		homeUrl: `${origin}/agents/${row.id}`,
		registrations:
			row.chain_id && row.erc8004_agent_id
				? [
						{
							agentRegistry: `eip155:${row.chain_id}:${row.erc8004_registry}`,
							agentId: row.erc8004_agent_id,
						},
					]
				: [],
		// The model and delivery settings ride along with the voice id so an
		// <agent-3d> embed, which resolves agents from this document, speaks with
		// the delivery the owner tuned and not just the right timbre.
		voice: row.voice_id
			? {
					provider: row.voice_provider || 'elevenlabs',
					voice_id: row.voice_id,
					...(row.voice_model ? { model: row.voice_model } : {}),
					...(row.voice_settings && typeof row.voice_settings === 'object'
						? { settings: row.voice_settings }
						: {}),
				}
			: { provider: 'browser' },
		persona: {
			has_persona: Boolean(row.persona_prompt_hash),
			tone_tags: row.persona_tone_tags || [],
			extracted_at: row.persona_extracted_at || null,
			// Present only when the agent's voice came from an onboarding
			// interview. Counts and source only; the answers stay private.
			...(interview ? { interview } : {}),
		},
		// Gesture slot overrides, so an embed plays this agent's own body language
		// rather than the platform defaults. Only present when the owner set some
		// (PUT /api/agents/:id/animations with animationSlots); consumers fall back
		// to DEFAULT_ANIMATION_MAP when it is absent.
		animationSlots:
			row.meta?.edits?.animations && Object.keys(row.meta.edits.animations).length
				? row.meta.edits.animations
				: undefined,
		// Named gesture routines (/choreograph). Shipped alongside the slot map so
		// an embed can play a whole performance by name — `el.playRoutine('welcome')`
		// — without a second round trip. Absent when the agent has none.
		choreographies: Array.isArray(row.meta?.choreographies) && row.meta.choreographies.length
			? row.meta.choreographies
			: undefined,
		// Live signal — funded + active on the Money Pulse via the activation grant.
		activated,
		activatedAt,
		createdAt: row.created_at,
	};

	return json(res, 200, manifest, {
		'cache-control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=86400',
		'access-control-allow-origin': '*',
	});
});

// ── registration (Metaplex / EIP-8004 agent registry document) ─────────────────

// Public EIP-8004 registration-v1 document for the agent. This is the URI the
// agent's on-chain Agent Identity PDA (Metaplex Agent Registry) points at — the
// program has no instruction to change the URI after registration, so it must be
// a stable, MUTABLE endpoint: serving it live keeps `active`, services, the 3D
// model, and any future token link current without re-registering on-chain.
export const handleRegistration = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	if (!/^[0-9a-f-]{36}$/i.test(id))
		return error(res, 400, 'invalid_request', 'agent id required');

	const [row] =
		await sql`select a.id, a.name, a.description, a.skills, a.deleted_at, a.chain_id, a.erc8004_agent_id, a.erc8004_registry, av.id as avatar_db_id, av.storage_key, av.thumbnail_key, av.content_type from agent_identities a left join avatars av on av.id = a.avatar_id and av.deleted_at is null where a.id = ${id} and a.deleted_at is null limit 1`;
	if (!row) return error(res, 404, 'not_found', 'agent not found');

	let modelUri = '';
	if (row.avatar_db_id) {
		try {
			const u = await resolveAvatarUrl({
				storage_key: row.storage_key,
				visibility: 'public',
			});
			modelUri = u?.url || '';
		} catch {}
	}
	// This document is what the agent's on-chain URI resolves to, so the image has
	// to survive forever: thumbnailUrl() drops a legacy origin-pointing `*_og.png`
	// key rather than publishing a URL that answers 404.
	const image = thumbnailUrl(row.thumbnail_key) || '';

	const proto = req.headers['x-forwarded-proto'] || 'https';
	const host = req.headers['x-forwarded-host'] || req.headers.host || 'three.ws';
	const origin = process.env.PUBLIC_APP_ORIGIN?.replace(/\/$/, '') || `${proto}://${host}`;

	const doc = buildAgentRegistrationMetadata({
		agentId: row.id,
		name: row.name || 'Agent',
		description: row.description || '',
		image,
		modelUri,
		modelFormat: row.content_type || 'gltf-binary',
		agentUrl: `${origin}/agents/${row.id}`,
		origin,
		skills: Array.isArray(row.skills) ? row.skills : [],
		erc8004:
			row.chain_id && row.erc8004_agent_id
				? {
						chainId: row.chain_id,
						agentId: row.erc8004_agent_id,
						registry: row.erc8004_registry,
					}
				: null,
	});

	return json(res, 200, doc, {
		'cache-control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=86400',
		'access-control-allow-origin': '*',
	});
});

// ── sign ──────────────────────────────────────────────────────────────────────

const signBody = z.object({
	message: z.string().min(1).max(8192),
	kind: z.enum(['personal']).default('personal'),
});

export const handleSign = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
	// A signature from the agent's custodial key can authorize off-platform value
	// (a login, an order), so a bearer needs the same wallet:write as a spend.
	assertBearerMaySpend(auth.bearer, req);

	// CSRF on state-changing session-cookie requests; bearer tokens are exempt.
	if (!(await requireCsrf(req, res, auth.userId))) return;

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl, 'too many sign requests');

	const [row] =
		await sql`SELECT id, user_id, wallet_address, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL LIMIT 1`;
	if (!row) return error(res, 404, 'not_found', 'agent not found');
	if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');

	const encryptedKey = row.meta?.encrypted_wallet_key;
	if (!encryptedKey) return error(res, 409, 'no_wallet', 'agent has no server wallet');

	const body = parse(signBody, await readJson(req));

	let signature;
	try {
		const pkHex = await recoverAgentKey(encryptedKey, {
			agentId: row.id,
			userId: auth.userId,
			reason: 'sign_message',
		});
		signature = await new Wallet(pkHex).signMessage(body.message);
	} catch (e) {
		console.error('[agents/sign] signing failed', e);
		return error(res, 500, 'sign_failed', 'could not sign message');
	}

	return json(res, 200, { address: row.wallet_address, signature });
});

// ── usage ─────────────────────────────────────────────────────────────────────

export const handleUsage = wrap(async (req, res, id) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;

	const session = await getSessionUser(req);
	if (!session) return error(res, 401, 'unauthorized', 'sign in required');

	const [agent] =
		await sql`SELECT id FROM agent_identities WHERE id = ${id} AND user_id = ${session.id} AND deleted_at IS NULL`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');

	const policy = await readEmbedPolicy(id);
	const monthlyQuota = policy?.brain?.monthly_quota ?? null;

	const [monthRow] =
		await sql`SELECT COUNT(*)::int AS total FROM usage_events WHERE agent_id = ${id} AND kind = 'llm' AND created_at >= date_trunc('month', now())`;
	const dailyRows =
		await sql`SELECT date_trunc('day', created_at)::date AS day, COUNT(*)::int AS calls FROM usage_events WHERE agent_id = ${id} AND kind = 'llm' AND created_at >= now() - interval '30 days' GROUP BY 1 ORDER BY 1`;

	return json(res, 200, {
		agentId: id,
		monthlyQuota,
		currentMonthCalls: monthRow?.total ?? 0,
		dailyBreakdown: dailyRows.map((r) => ({ day: r.day, calls: r.calls })),
	});
});

// ── memories ──────────────────────────────────────────────────────────────────

const memoryBodySchema = z.object({
	type: z.enum(['user', 'feedback', 'project', 'reference']),
	content: z.string().trim().min(1).max(4000),
	tags: z.array(z.string().trim().max(100)).max(20).optional().default([]),
	salience: z.number().min(0).max(1).optional(),
	expiresAt: z.string().datetime().optional().nullable(),
	isPublic: z.boolean().optional().default(false),
});

const memoryPatchSchema = z.object({
	isPublic: z.boolean(),
});

export const handleMemories = wrap(async (req, res, id, memoryId) => {
	if (cors(req, res, { methods: 'GET,POST,PATCH,DELETE,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET', 'POST', 'PATCH', 'DELETE'])) return;

	const session = await getSessionUser(req);
	const bearer = session ? null : await authenticateBearer(extractBearer(req));
	const userId = session?.id ?? bearer?.userId;

	// Public embeds hydrate on every page load. For anonymous GETs, return
	// an empty list rather than 401 to keep the console clean — only the
	// owner ever sees memory rows.
	if (req.method === 'GET' && !userId) return json(res, 200, { data: [] });
	if (!userId) return error(res, 401, 'unauthorized', 'sign in required');

	const [agent] =
		await sql`SELECT id FROM agent_identities WHERE id = ${id} AND user_id = ${userId} AND deleted_at IS NULL`;
	if (!agent) {
		if (req.method === 'GET') return json(res, 200, { data: [] });
		return error(res, 404, 'not_found', 'agent not found');
	}

	if (req.method === 'GET') {
		const rows = await sql`
			SELECT id, type, content, tags, salience, expires_at, created_at, is_public
			FROM agent_memories
			WHERE agent_id = ${id}
				AND (expires_at IS NULL OR expires_at > now())
			ORDER BY created_at DESC
			LIMIT 200
		`;
		return json(res, 200, { data: rows });
	}

	if (req.method === 'DELETE') {
		if (!memoryId) return error(res, 400, 'bad_request', 'memory id required');
		await sql`DELETE FROM agent_memories WHERE id = ${memoryId} AND agent_id = ${id}`;
		return json(res, 200, { deleted: true });
	}

	// PATCH /memories/:id — toggle a single memory's public visibility. Scoped
	// to this agent so a caller can't flip a memory belonging to another agent.
	if (req.method === 'PATCH') {
		if (!memoryId) return error(res, 400, 'bad_request', 'memory id required');
		const body = parse(memoryPatchSchema, await readJson(req));
		const [row] = await sql`
			UPDATE agent_memories
			SET is_public = ${body.isPublic}
			WHERE id = ${memoryId} AND agent_id = ${id}
			RETURNING id, is_public
		`;
		if (!row) return error(res, 404, 'not_found', 'memory not found');
		return json(res, 200, { id: row.id, isPublic: row.is_public });
	}

	// POST
	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(memoryBodySchema, await readJson(req));
	const [row] = await sql`
		INSERT INTO agent_memories (id, agent_id, type, content, tags, salience, expires_at, is_public)
		VALUES (gen_random_uuid(), ${id}, ${body.type}, ${body.content}, ${body.tags}, ${body.salience ?? 0.5}, ${body.expiresAt ?? null}, ${body.isPublic})
		RETURNING id
	`;
	return json(res, 201, { id: row.id });
});