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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Persona — the agent's mind, as editable structure.
//
// GET /api/agents/:id/persona — full persona for the owner: traits,
// tone tags, vocabulary, base, the
// compiled prompt, and current version.
// POST /api/agents/:id/persona/extract — (re)run the 5-question interview via
// Claude; seeds the base persona + tone.
// POST /api/agents/:id/persona/save — save edited traits/tone/vocabulary;
// compiles + signs persona_prompt and
// writes a real agent_versions entry.
// GET /api/agents/:id/persona/versions — persona version history (for diff).
// POST /api/agents/:id/persona/restore — restore a prior version as a new save.
//
// Every write path here also republishes the agent's signed manifest: the
// compiled prompt is canonicalized, signed with the platform ed25519 attester
// identity, and pinned to IPFS so the resulting CID is a permanent, portable
// record of exactly how this agent was configured. See
// api/_lib/agent-manifest-publish.js and specs/AGENT_MANIFEST.md.
import { createHash, createHmac } from 'node:crypto';
import { sql } from '../../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer, isSameSiteOrigin } from '../../_lib/auth.js';
import { cors, json, method, readJson, wrap, error, rateLimited } from '../../_lib/http.js';
import { limits } from '../../_lib/rate-limit.js';
import { env } from '../../_lib/env.js';
import {
extractPersonaFromInterview,
PersonaExtractionError,
} from '../../_lib/persona-interview-extract.js';
import { parse } from '../../_lib/validate.js';
import { publishAgentManifestSafely } from '../../_lib/agent-manifest-publish.js';
import { z } from 'zod';
import {
compilePersona,
clampTraits,
sanitizeToneTags,
sanitizeVocabulary,
PERSONA_TRAIT_KEYS,
} from '../../../src/agents/persona-compile.js';
import {
INTERVIEW_QUESTIONS,
normalizeInterview,
MAX_INTERVIEW_ANSWERS,
} from '../../../src/agents/persona-interview.js';
// Two accepted answer shapes, one interview. The structured form
// ([{ id?, question?, answer }]) is what the create-agent wizard and the current
// Brain Studio modal send: 5 to 8 questions, any of them skippable. The legacy
// form (five bare strings, positionally mapped onto the canonical questions) is
// still accepted so an older client or an SDK caller keeps working.
const extractBody = z.object({
answers: z
.union([
z.array(z.string().max(1000)).min(1).max(MAX_INTERVIEW_ANSWERS),
z
.array(
z.object({
id: z.string().max(40).optional(),
question: z.string().max(240).optional(),
answer: z.string().max(1000),
}),
)
.min(1)
.max(MAX_INTERVIEW_ANSWERS),
])
.transform((rows) =>
normalizeInterview(
rows.map((row, i) =>
typeof row === 'string'
? { id: INTERVIEW_QUESTIONS[i]?.id, question: INTERVIEW_QUESTIONS[i]?.prompt, answer: row }
: row,
),
),
)
.refine((rows) => rows.length > 0, 'Answer at least one interview question'),
});
const traitsSchema = z.record(z.string(), z.number()).default({});
const saveBody = z.object({
traits: traitsSchema,
tone_tags: z.array(z.string()).max(24).default([]),
vocabulary: z.array(z.string()).max(24).default([]),
base: z.string().max(4000).optional(),
changelog: z.string().trim().max(280).optional(),
// Interview provenance. The create-agent wizard runs the interview before the
// agent exists (POST /api/persona/interview) and hands the answers over on the
// first save, so the agent records WHICH questions produced its voice — that is
// what `persona.interview` on the public manifest reports.
interview: z
.array(
z.object({
id: z.string().max(40).optional(),
question: z.string().max(240).optional(),
answer: z.string().max(1000),
}),
)
.max(MAX_INTERVIEW_ANSWERS)
.optional(),
});
const restoreBody = z.object({ version: z.number().int().positive() });
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) {
// CSRF defense-in-depth for the cookie path: persona writes rewrite the
// agent's compiled prompt (prompt-injection persistence), so a
// cross-site POST riding the session cookie must never reach them.
// Reads stay open; bearer callers are exempt.
const isRead = ['GET', 'HEAD', 'OPTIONS'].includes(String(req.method || '').toUpperCase());
if (!isRead && !isSameSiteOrigin(req)) {
throw Object.assign(new Error('cross-site request blocked'), { status: 403, code: 'forbidden' });
}
return { userId: session.id };
}
const bearer = await authenticateBearer(extractBearer(req));
if (bearer) return { userId: bearer.userId };
return null;
}
// Sign a compiled persona prompt so chat.js / portability can verify provenance.
function signPrompt(systemPrompt) {
const hash = createHash('sha256').update(systemPrompt).digest('hex');
const sig = createHmac('sha256', env.JWT_SECRET).update(hash).digest('hex');
return { hash, sig };
}
// Read the structured persona state stored on the agent. persona_traits holds
// { values: {key:0..1}, vocabulary: [...], base: "...", interview: {...} }.
function readStructured(agent) {
const raw = agent.persona_traits && typeof agent.persona_traits === 'object' ? agent.persona_traits : {};
return {
values: clampTraits(raw.values || {}),
vocabulary: sanitizeVocabulary(raw.vocabulary || []),
base: typeof raw.base === 'string' ? raw.base : '',
interview: raw.interview && typeof raw.interview === 'object' ? raw.interview : null,
};
}
// The interview provenance block stored inside persona_traits: which questions
// were answered, when, and where the interview ran. The answers themselves are
// kept so the owner can reopen and edit them; the public manifest exposes only
// the counts (see api/agents/_id/_sub.js handleManifest).
function interviewRecord(answers, source) {
return {
source,
question_ids: answers.map((row) => row.id),
questions_answered: answers.length,
questions_total: INTERVIEW_QUESTIONS.length,
answers,
at: new Date().toISOString(),
};
}
export const handlePersona = wrap(async (req, res, id, action) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
const [agent] = await sql`
SELECT id, user_id, name, description, system_prompt, greeting, category, tags,
capabilities, persona_prompt, persona_prompt_hash, persona_tone_tags,
persona_traits, persona_extracted_at, persona_updated_at
FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL
`;
if (!agent) return error(res, 404, 'not_found', 'agent not found');
if (agent.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
// ── GET — full persona for the owner ─────────────────────────────────────
if (req.method === 'GET' && !action) {
const structured = readStructured(agent);
const [{ latest }] = await sql`
SELECT COALESCE(MAX(version), 0) AS latest FROM agent_versions WHERE agent_id = ${id}
`;
return json(res, 200, {
has_persona: Boolean(agent.persona_prompt_hash),
name: agent.name,
description: agent.description || '',
traits: structured.values,
tone_tags: agent.persona_tone_tags || [],
vocabulary: structured.vocabulary,
base: structured.base,
interview: structured.interview,
persona_prompt: agent.persona_prompt || '',
extracted_at: agent.persona_extracted_at || null,
updated_at: agent.persona_updated_at || null,
latest_version: latest,
});
}
// ── GET /versions — persona version history ──────────────────────────────
if (req.method === 'GET' && action === 'versions') {
const rows = await sql`
SELECT version, kind, changelog, persona_prompt, persona_tone_tags, persona_traits,
created_at
FROM agent_versions
WHERE agent_id = ${id} AND kind = 'persona'
ORDER BY version DESC
LIMIT 50
`;
return json(res, 200, {
versions: rows.map((r) => ({
version: r.version,
kind: r.kind,
changelog: r.changelog,
persona_prompt: r.persona_prompt || '',
tone_tags: r.persona_tone_tags || [],
traits: (r.persona_traits && r.persona_traits.values) || {},
vocabulary: (r.persona_traits && r.persona_traits.vocabulary) || [],
base: (r.persona_traits && r.persona_traits.base) || '',
created_at: r.created_at,
})),
});
}
// ── POST /extract — the 5-question interview ─────────────────────────────
if (req.method === 'POST' && action === 'extract') {
const rl = await limits.personaExtract(auth.userId);
if (!rl.success) return rateLimited(res, rl, 'persona extraction limit reached (5 per day)');
const body = parse(extractBody, await readJson(req));
const answers = body.answers;
let extracted;
try {
extracted = await extractPersonaFromInterview({
name: agent.name,
description: agent.description,
greeting: agent.greeting,
answers,
userId: auth.userId,
tool: 'persona_extract_rerun',
});
} catch (err) {
if (err instanceof PersonaExtractionError) {
return error(res, err.status, err.code, err.message);
}
throw err;
}
// The interview supplies the voice; the owner's trait sliders refine it.
// A FIRST extraction has no tuned sliders to protect, so the interview's own
// trait read is adopted. A re-run keeps whatever the owner has since dialled
// in — re-running the interview must never silently undo their edits.
const structured = readStructured(agent);
const firstExtraction = !agent.persona_prompt_hash;
const traits = firstExtraction ? extracted.traits : structured.values;
const base = extracted.base;
const tone_tags = extracted.toneTags;
const vocabulary_samples = extracted.vocabulary;
const compiled = compilePersona({
name: agent.name,
description: agent.description,
base,
traits,
toneTags: tone_tags,
vocabulary: vocabulary_samples,
});
const { hash, sig } = signPrompt(compiled);
const personaTraits = {
values: traits,
vocabulary: vocabulary_samples,
base,
interview: interviewRecord(answers, 'brain-studio'),
};
const [updated] = await sql`
UPDATE agent_identities
SET persona_prompt = ${compiled},
persona_prompt_hash = ${hash},
persona_prompt_sig = ${sig},
persona_tone_tags = ${JSON.stringify(tone_tags)}::jsonb,
persona_traits = ${JSON.stringify(personaTraits)}::jsonb,
persona_extracted_at = now(),
persona_updated_at = now(),
updated_at = now()
WHERE id = ${id}
RETURNING persona_extracted_at
`;
const manifest = await publishAgentManifestSafely(id, { reason: 'persona_extract' });
return json(res, 200, {
system_prompt: compiled,
base,
traits,
tone_tags,
vocabulary: vocabulary_samples,
questions_answered: answers.length,
hash,
extracted_at: updated.persona_extracted_at,
manifest,
});
}
// ── POST /save — persist edited traits + create a real version ───────────
if (req.method === 'POST' && action === 'save') {
const rl = await limits.widgetWrite(auth.userId);
if (!rl.success) return rateLimited(res, rl, 'too many persona saves, slow down');
const body = parse(saveBody, await readJson(req));
const prev = readStructured(agent);
const traits = clampTraits(body.traits);
const toneTags = sanitizeToneTags(body.tone_tags);
const vocabulary = sanitizeVocabulary(body.vocabulary);
const base = body.base != null ? String(body.base).trim() : prev.base;
// A save that carries interview answers is the wizard handing over an
// interview that ran before the agent existed. Record it as provenance and
// stamp persona_extracted_at, so the agent reports an interviewed persona
// exactly like a Brain Studio re-run does.
const interviewAnswers = body.interview ? normalizeInterview(body.interview) : [];
const interview = interviewAnswers.length
? interviewRecord(interviewAnswers, 'create-wizard')
: prev.interview;
const compiled = compilePersona({
name: agent.name,
description: agent.description,
base,
traits,
toneTags,
vocabulary,
});
const { hash, sig } = signPrompt(compiled);
const personaTraits = { values: traits, vocabulary, base, ...(interview ? { interview } : {}) };
const changelog = body.changelog || 'Persona updated';
const [{ next_version }] = await sql`
SELECT COALESCE(MAX(version), 0) + 1 AS next_version
FROM agent_versions WHERE agent_id = ${id}
`;
const [updatedRows] = await sql.transaction([
sql`
UPDATE agent_identities
SET persona_prompt = ${compiled},
persona_prompt_hash = ${hash},
persona_prompt_sig = ${sig},
persona_tone_tags = ${JSON.stringify(toneTags)}::jsonb,
persona_traits = ${JSON.stringify(personaTraits)}::jsonb,
persona_extracted_at = CASE WHEN ${interviewAnswers.length > 0} THEN now() ELSE persona_extracted_at END,
persona_updated_at = now(),
updated_at = now()
WHERE id = ${id}
RETURNING persona_updated_at
`,
sql`
INSERT INTO agent_versions (
agent_id, version, kind, system_prompt, greeting, category, tags,
capabilities, changelog, created_by,
persona_prompt, persona_tone_tags, persona_traits
)
VALUES (
${id}, ${next_version}, 'persona', ${agent.system_prompt}, ${agent.greeting},
${agent.category}, ${agent.tags || []},
${JSON.stringify(agent.capabilities || {})}::jsonb, ${changelog}, ${auth.userId},
${compiled}, ${JSON.stringify(toneTags)}::jsonb, ${JSON.stringify(personaTraits)}::jsonb
)
`,
]);
// The prompt that just landed is the agent's behavior, so pin the proof of
// it now. Best-effort by design: the save above is already committed and a
// pinning hiccup reports itself in `manifest.reason` rather than failing.
const manifest = await publishAgentManifestSafely(id, { reason: 'persona_save' });
return json(res, 200, {
version: next_version,
persona_prompt: compiled,
traits,
tone_tags: toneTags,
vocabulary,
base,
hash,
changelog,
updated_at: updatedRows[0]?.persona_updated_at || null,
manifest,
});
}
// ── POST /restore — re-save a prior version as the live persona ──────────
if (req.method === 'POST' && action === 'restore') {
const rl = await limits.widgetWrite(auth.userId);
if (!rl.success) return rateLimited(res, rl, 'too many persona saves, slow down');
const body = parse(restoreBody, await readJson(req));
const [snap] = await sql`
SELECT version, persona_tone_tags, persona_traits
FROM agent_versions
WHERE agent_id = ${id} AND version = ${body.version} AND kind = 'persona'
LIMIT 1
`;
if (!snap) return error(res, 404, 'not_found', 'persona version not found');
const snapTraits = snap.persona_traits && typeof snap.persona_traits === 'object' ? snap.persona_traits : {};
const traits = clampTraits(snapTraits.values || {});
const toneTags = sanitizeToneTags(snap.persona_tone_tags || []);
const vocabulary = sanitizeVocabulary(snapTraits.vocabulary || []);
const base = typeof snapTraits.base === 'string' ? snapTraits.base : '';
const compiled = compilePersona({
name: agent.name,
description: agent.description,
base,
traits,
toneTags,
vocabulary,
});
const { hash, sig } = signPrompt(compiled);
const personaTraits = { values: traits, vocabulary, base };
const changelog = `Restored persona from v${snap.version}`;
const [{ next_version }] = await sql`
SELECT COALESCE(MAX(version), 0) + 1 AS next_version
FROM agent_versions WHERE agent_id = ${id}
`;
await sql.transaction([
sql`
UPDATE agent_identities
SET persona_prompt = ${compiled},
persona_prompt_hash = ${hash},
persona_prompt_sig = ${sig},
persona_tone_tags = ${JSON.stringify(toneTags)}::jsonb,
persona_traits = ${JSON.stringify(personaTraits)}::jsonb,
persona_updated_at = now(),
updated_at = now()
WHERE id = ${id}
`,
sql`
INSERT INTO agent_versions (
agent_id, version, kind, system_prompt, greeting, category, tags,
capabilities, changelog, created_by,
persona_prompt, persona_tone_tags, persona_traits
)
VALUES (
${id}, ${next_version}, 'persona', ${agent.system_prompt}, ${agent.greeting},
${agent.category}, ${agent.tags || []},
${JSON.stringify(agent.capabilities || {})}::jsonb, ${changelog}, ${auth.userId},
${compiled}, ${JSON.stringify(toneTags)}::jsonb, ${JSON.stringify(personaTraits)}::jsonb
)
`,
]);
const manifest = await publishAgentManifestSafely(id, { reason: 'persona_restore' });
return json(res, 200, {
version: next_version,
restored_from: snap.version,
persona_prompt: compiled,
traits,
tone_tags: toneTags,
vocabulary,
base,
hash,
changelog,
manifest,
});
}
return error(res, 404, 'not_found', 'unknown persona action');
});