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.

10.3 KB
Raw Blame
// Pay-As-You-Learn Tutor: session ledger.
//
// Each tutoring session keeps a running tab: every answered question appends an
// itemized charge, and "end session" produces an itemized invoice with a
// SHA-256 attestation over the entries.
//
// Storage tiers, in order of preference:
//   1. Postgres `tutor_sessions` (DATABASE_URL). This is the platform's real
//      store and the tier production runs on; the table is created lazily.
//   2. Upstash/Vercel KV REST (UPSTASH_REDIS_REST_URL/TOKEN), for a deployment
//      that has KV but no database.
//   3. Process-local memory, for local dev with neither configured. Resume then
//      works within one server process and nowhere else.
//
// Records expire 7 days after the last write, so a learner can close the tab
// and resume the same session later.
//
// Reads propagate a storage fault to the caller: reporting "$0, no questions"
// because the store is down would tell a learner who owes money that they owe
// nothing. Writes on the paid path are best-effort, because losing a ledger row
// must never cost the learner the answer they already paid for.

import { createHash } from 'crypto';
import { sql } from '../../../api/_lib/db.js';
import { databaseConfigured } from '../../../api/_lib/env.js';

const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
const MAX_ENTRIES = 500; // hard cap so a session object can't grow unbounded
const PRUNE_INTERVAL_MS = 60 * 60 * 1000; // at most one expired-row sweep per hour per process

function kvCredentials() {
	const url =
		process.env.UPSTASH_REDIS_REST_URL ||
		process.env.three_KV_REST_API_URL ||
		process.env.KV_REST_API_URL;
	const token =
		process.env.UPSTASH_REDIS_REST_TOKEN ||
		process.env.three_KV_REST_API_TOKEN ||
		process.env.KV_REST_API_TOKEN;
	return { url, token };
}

/** Which backend this process will use: 'db', 'kv', or 'memory'. */
export function sessionBackend() {
	if (databaseConfigured()) return 'db';
	const { url, token } = kvCredentials();
	return url && token ? 'kv' : 'memory';
}

// ── Postgres tier ─────────────────────────────────────────────────────────────

let schemaReady = null;

function ensureSchema() {
	if (schemaReady) return schemaReady;
	schemaReady = (async () => {
		await sql`
			create table if not exists tutor_sessions (
				session_id    text primary key,
				status        text not null default 'open',
				total_atomics bigint not null default 0,
				session       jsonb not null,
				created_at    timestamptz not null default now(),
				updated_at    timestamptz not null default now(),
				expires_at    timestamptz not null
			)
		`;
		await sql`create index if not exists tutor_sessions_expires_idx on tutor_sessions (expires_at)`;
		return true;
	})();
	// A failed CREATE (outage, permissions) must not poison every later call with
	// the same rejected promise; drop it so the next request retries.
	schemaReady.catch(() => {
		schemaReady = null;
	});
	return schemaReady;
}

let lastPruneAt = 0;

function prunePostgres() {
	const now = Date.now();
	if (now - lastPruneAt < PRUNE_INTERVAL_MS) return;
	lastPruneAt = now;
	sql`delete from tutor_sessions where expires_at < now()`.catch((err) => {
		console.warn('[tutor] expired-session sweep failed:', err?.message || err);
	});
}

async function dbRead(sessionId) {
	await ensureSchema();
	const rows = await sql`
		select session from tutor_sessions
		where session_id = ${sessionId} and expires_at > now()
	`;
	const raw = rows?.[0]?.session;
	if (!raw) return null;
	return typeof raw === 'string' ? JSON.parse(raw) : raw;
}

async function dbWrite(session) {
	await ensureSchema();
	await sql`
		insert into tutor_sessions (session_id, status, total_atomics, session, created_at, updated_at, expires_at)
		values (
			${session.sessionId},
			${session.status},
			${session.totalAtomics},
			${JSON.stringify(session)}::jsonb,
			${session.createdAt}::timestamptz,
			now(),
			now() + ${`${SESSION_TTL_SECONDS} seconds`}::interval
		)
		on conflict (session_id) do update set
			status        = excluded.status,
			total_atomics = excluded.total_atomics,
			session       = excluded.session,
			updated_at    = now(),
			expires_at    = excluded.expires_at
	`;
	prunePostgres();
}

// ── KV tier ───────────────────────────────────────────────────────────────────

function sessionKey(sessionId) {
	return `tutor:session:v1:${sessionId}`;
}

async function kvRead(sessionId) {
	const { url, token } = kvCredentials();
	const r = await fetch(`${url}/get/${encodeURIComponent(sessionKey(sessionId))}`, {
		headers: { authorization: `Bearer ${token}` },
	});
	if (!r.ok) throw new Error(`kv get failed with ${r.status}`);
	const d = await r.json();
	return d.result ? JSON.parse(d.result) : null;
}

async function kvWrite(session) {
	const { url, token } = kvCredentials();
	// Upstash REST: the raw request body IS the stored value; TTL goes in the
	// query string. A JSON envelope body would be stored verbatim and corrupt
	// every subsequent read.
	const key = encodeURIComponent(sessionKey(session.sessionId));
	const r = await fetch(`${url}/set/${key}?EX=${SESSION_TTL_SECONDS}`, {
		method: 'POST',
		headers: { authorization: `Bearer ${token}` },
		body: JSON.stringify(session),
	});
	if (!r.ok) throw new Error(`kv set failed with ${r.status}`);
}

// ── Memory tier ───────────────────────────────────────────────────────────────

const memory = new Map();

function memoryRead(sessionId) {
	const rec = memory.get(sessionId);
	if (!rec) return null;
	if (rec.expiresAt <= Date.now()) {
		memory.delete(sessionId);
		return null;
	}
	return JSON.parse(JSON.stringify(rec.session));
}

function memoryWrite(session) {
	memory.set(session.sessionId, {
		session: JSON.parse(JSON.stringify(session)),
		expiresAt: Date.now() + SESSION_TTL_SECONDS * 1000,
	});
}

// ── Backend dispatch ──────────────────────────────────────────────────────────

/** Read the stored session, or null when this id has no tab. Throws on a store fault. */
async function readSession(sessionId) {
	const backend = sessionBackend();
	const stored =
		backend === 'db' ? await dbRead(sessionId) : backend === 'kv' ? await kvRead(sessionId) : memoryRead(sessionId);
	// A record written by a foreign writer (or an older shape) lacks the session
	// fields; treat it as absent rather than crashing the charge path.
	if (!stored || !Array.isArray(stored.entries)) return null;
	if (!Number.isFinite(stored.totalAtomics)) stored.totalAtomics = 0;
	if (!stored.status) stored.status = 'open';
	return stored;
}

async function writeSession(session) {
	const backend = sessionBackend();
	if (backend === 'db') return dbWrite(session);
	if (backend === 'kv') return kvWrite(session);
	return memoryWrite(session);
}

function emptySession(sessionId) {
	return { sessionId, createdAt: new Date().toISOString(), entries: [], totalAtomics: 0, status: 'open' };
}

/** Load a session, or a fresh empty one when this id has no tab yet. */
export async function loadSession(sessionId) {
	return (await readSession(sessionId)) || emptySession(sessionId);
}

/**
 * Append one answered-question charge to the session tab and persist it.
 * Returns the updated session.
 */
export async function appendCharge(sessionId, entry) {
	let session;
	try {
		session = await loadSession(sessionId);
	} catch (err) {
		// The learner has already paid for this answer: a ledger outage costs them
		// the running total, never the explanation itself.
		console.warn('[tutor] session ledger read failed, charging a fresh tab:', err?.message || err);
		session = emptySession(sessionId);
	}
	if (session.status === 'closed') {
		const err = new Error('session is closed, start a new session');
		err.status = 409;
		err.code = 'session_closed';
		err.expose = true;
		throw err;
	}
	session.entries.push({
		question: String(entry.question || '').slice(0, 500),
		level: entry.level,
		costAtomics: entry.costAtomics,
		outputTokens: entry.outputTokens || 0,
		sandboxRan: Boolean(entry.sandboxRan),
		at: new Date().toISOString(),
	});
	if (session.entries.length > MAX_ENTRIES) {
		session.entries = session.entries.slice(-MAX_ENTRIES);
	}
	session.totalAtomics = session.entries.reduce((sum, e) => sum + (e.costAtomics || 0), 0);
	try {
		await writeSession(session);
	} catch (err) {
		console.warn('[tutor] session ledger write failed:', err?.message || err);
	}
	return session;
}

/** Convert atomics (USDC 6dp) to a human "$x.xxxxxx" string. */
export function atomicsToUsd(atomics) {
	return (Number(atomics) / 1_000_000).toFixed(6);
}

function buildInvoice(session) {
	const lineItems = session.entries.map((e, i) => ({
		n: i + 1,
		question: e.question,
		level: e.level,
		outputTokens: e.outputTokens,
		costAtomics: e.costAtomics,
		costUsd: atomicsToUsd(e.costAtomics),
		at: e.at,
	}));

	const attestation =
		'sha256:' +
		createHash('sha256')
			.update(JSON.stringify({ sessionId: session.sessionId, lineItems, totalAtomics: session.totalAtomics }))
			.digest('hex');

	return {
		sessionId: session.sessionId,
		createdAt: session.createdAt,
		closedAt: new Date().toISOString(),
		questionCount: lineItems.length,
		lineItems,
		totalAtomics: session.totalAtomics,
		totalUsd: atomicsToUsd(session.totalAtomics),
		attestation,
	};
}

/**
 * Close a session and produce an itemized, attested invoice.
 * Idempotent: closing an already-closed session returns the stored invoice
 * verbatim, closedAt included.
 */
export async function closeSession(sessionId) {
	const stored = await readSession(sessionId);
	if (stored?.status === 'closed' && stored.invoice) return stored.invoice;

	const session = stored || emptySession(sessionId);
	const invoice = buildInvoice(session);

	// Never persist a close for an id that has no tab. Writing a `closed` record
	// for an unused id would make it permanently unusable (appendCharge rejects a
	// closed session) for whoever actually holds it.
	if (stored) {
		session.status = 'closed';
		session.invoice = invoice;
		await writeSession(session);
	}
	return invoice;
}