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.7 KB
Raw Blame
// The rules engine: everything that decides WHETHER a message is worth
// interrupting a human for, and how it should be delivered.
//
// Pure by design. No DOM, no timers, no network, no globals. The runtime
// (index.js) owns the clock and the side effects; this file owns the judgement,
// which is the part worth testing exhaustively and the part an integrator will
// want to reason about before they let anything walk onto their page.
//
// The model in one paragraph: a message arrives from a source with an optional
// `importance` (0-100). Scorers may raise or lower it. The decision function
// then answers one question, "deliver, hold, or drop", against the caller's
// rules: freshness, dedupe, importance floor, quiet hours, rate limit, focus.
// Anything held is retried by the runtime; anything dropped is reported with a
// reason, so an integrator can always answer "why didn't I hear about that?".

/** Every reason a message can fail to reach a human, as a stable string. */
export const DROP_REASONS = /** @type {const} */ ({
	DUPLICATE: 'duplicate',
	STALE: 'stale',
	BELOW_FLOOR: 'below-importance-floor',
	MUTED: 'muted',
	EMPTY: 'empty',
});

/** Reasons a message is not delivered *yet*, but will be. */
export const HOLD_REASONS = /** @type {const} */ ({
	QUIET_HOURS: 'quiet-hours',
	RATE_LIMITED: 'rate-limited',
	UNFOCUSED: 'window-not-focused',
	BUSY: 'delivering-another',
});

/** The importance a message gets when nothing said otherwise. */
export const DEFAULT_IMPORTANCE = 50;

/**
 * @typedef {object} Message
 * @property {string} [id] stable id; dedupe key when `key` is absent
 * @property {string} text the line a human hears or reads
 * @property {string} [key] explicit dedupe key (two builds of the same alert)
 * @property {number} [importance] 0-100; higher interrupts harder
 * @property {string} [from] who it is from, shown and spoken as attribution
 * @property {string} [url] where clicking through goes
 * @property {number} [at] epoch ms the underlying event happened
 * @property {string} [tone] 'neutral' | 'alert' | 'celebrate'
 * @property {string} [emote] gesture the avatar arrives with
 * @property {object} [meta] anything the integrator wants back in callbacks
 */

/**
 * @typedef {object} Rules
 * @property {number} [minImportance=50] floor a message must clear to deliver
 * @property {number} [freshnessMs=900000] older than this and it is history
 * @property {number} [dedupeTtlMs=21600000] how long a delivered key is remembered
 * @property {[number, number]|null} [quietHours=null] local [startHour, endHour)
 * @property {number} [quietHoursMinImportance=90] what still gets through quiet hours
 * @property {number} [maxPerWindow=4] deliveries allowed per rate window
 * @property {number} [rateWindowMs=60000] the rate window
 * @property {boolean} [focusOnly=true] hold while the tab is in the background
 * @property {number} [batchSize=2] delivered per burst before the rest collapse
 */

/** The defaults, exported so integrators can read them and docs can quote them. */
export const DEFAULT_RULES = Object.freeze({
	minImportance: DEFAULT_IMPORTANCE,
	freshnessMs: 15 * 60_000,
	dedupeTtlMs: 6 * 60 * 60_000,
	quietHours: null,
	quietHoursMinImportance: 90,
	maxPerWindow: 4,
	rateWindowMs: 60_000,
	focusOnly: true,
	batchSize: 2,
});

/** Merge a caller's partial rules onto the defaults. */
export function resolveRules(rules) {
	return { ...DEFAULT_RULES, ...(rules || {}) };
}

/** Clamp anything to a 0-100 importance. */
export function clampImportance(value, fallback = DEFAULT_IMPORTANCE) {
	const n = Number(value);
	if (!Number.isFinite(n)) return fallback;
	return Math.max(0, Math.min(100, Math.round(n)));
}

/**
 * Run the caller's scorers over a message, highest wins.
 *
 * A scorer is `(message) => number | undefined`. Returning undefined means "no
 * opinion", which is what lets a scorer speak only about the messages it knows
 * about. A scorer that throws is ignored rather than allowed to break delivery:
 * an integrator's bad rule must never cost a user their message.
 *
 * @param {Message} message
 * @param {Array<(m: Message) => number|undefined>} [scorers]
 * @returns {number} 0-100
 */
export function scoreMessage(message, scorers = []) {
	let score = clampImportance(message?.importance, DEFAULT_IMPORTANCE);
	for (const scorer of scorers) {
		if (typeof scorer !== 'function') continue;
		let opinion;
		try {
			opinion = scorer(message);
		} catch {
			continue;
		}
		if (opinion == null) continue;
		const n = clampImportance(opinion, null);
		if (n != null && n > score) score = n;
	}
	return score;
}

/** The dedupe key for a message: explicit key, then id, then the text itself. */
export function dedupeKeyFor(message) {
	return String(message?.key || message?.id || message?.text || '').trim();
}

/**
 * Is `hour` inside a [start, end) window that may wrap past midnight?
 * `[22, 7]` means 22:00 to 06:59.
 */
export function withinQuietHours(hour, quietHours) {
	if (!Array.isArray(quietHours) || quietHours.length !== 2) return false;
	const [start, end] = quietHours.map((h) => Number(h));
	if (!Number.isFinite(start) || !Number.isFinite(end) || start === end) return false;
	const h = Number(hour);
	return start < end ? h >= start && h < end : h >= start || h < end;
}

/**
 * Decide what happens to one message.
 *
 * @param {Message} message
 * @param {object} ctx
 * @param {Rules} ctx.rules resolved rules
 * @param {number} ctx.now epoch ms
 * @param {number} ctx.hour local hour 0-23
 * @param {Map<string, number>} ctx.seen dedupe key to the ms it was delivered
 * @param {number[]} ctx.recent delivery timestamps inside the rate window
 * @param {boolean} ctx.focused is the surface in front of the human
 * @param {boolean} [ctx.busy] is a delivery already on screen
 * @param {boolean} [ctx.muted] has the human silenced this device
 * @param {Array<(m: Message) => number|undefined>} [ctx.scorers]
 * @returns {{action:'deliver'|'hold'|'drop', reason?:string, importance:number}}
 */
export function decide(message, ctx) {
	const rules = ctx.rules;
	const importance = scoreMessage(message, ctx.scorers);
	const text = String(message?.text || '').trim();

	if (!text) return { action: 'drop', reason: DROP_REASONS.EMPTY, importance };
	if (ctx.muted) return { action: 'drop', reason: DROP_REASONS.MUTED, importance };

	const key = dedupeKeyFor(message);
	const lastSeen = ctx.seen?.get(key);
	if (lastSeen != null && ctx.now - lastSeen < rules.dedupeTtlMs) {
		return { action: 'drop', reason: DROP_REASONS.DUPLICATE, importance };
	}

	// `at` is when the underlying event happened. A source that does not know
	// (a manual announce, a webhook with no timestamp) is treated as now, so
	// freshness never silently swallows a message that has no clock on it.
	const at = Number.isFinite(Number(message?.at)) ? Number(message.at) : ctx.now;
	if (ctx.now - at > rules.freshnessMs) {
		return { action: 'drop', reason: DROP_REASONS.STALE, importance };
	}

	if (importance < rules.minImportance) {
		return { action: 'drop', reason: DROP_REASONS.BELOW_FLOOR, importance };
	}

	// Holds are ordered cheapest-to-recover first: focus and busy resolve in
	// seconds, the rate window in a minute, quiet hours in hours.
	if (ctx.busy) return { action: 'hold', reason: HOLD_REASONS.BUSY, importance };
	if (rules.focusOnly && !ctx.focused) {
		return { action: 'hold', reason: HOLD_REASONS.UNFOCUSED, importance };
	}

	const windowStart = ctx.now - rules.rateWindowMs;
	const inWindow = (ctx.recent || []).filter((t) => t > windowStart).length;
	if (inWindow >= rules.maxPerWindow) {
		return { action: 'hold', reason: HOLD_REASONS.RATE_LIMITED, importance };
	}

	if (
		withinQuietHours(ctx.hour, rules.quietHours) &&
		importance < rules.quietHoursMinImportance
	) {
		return { action: 'hold', reason: HOLD_REASONS.QUIET_HOURS, importance };
	}

	return { action: 'deliver', importance };
}

/**
 * Split a burst into what gets said and what gets summarised.
 *
 * Three alerts in one second is three interruptions; the third is noise. The
 * batch plan delivers the most important few in order and collapses the rest
 * into a single line, so a storm costs the human one extra sentence.
 *
 * @param {Array<Message & {importance?: number}>} messages
 * @param {number} [batchSize=2]
 * @returns {{deliver: Message[], collapsed: Message[], summary: string|null}}
 */
export function planBatch(messages, batchSize = DEFAULT_RULES.batchSize) {
	const list = (Array.isArray(messages) ? messages : []).filter(Boolean);
	const ordered = [...list].sort(
		(a, b) =>
			clampImportance(b.importance) - clampImportance(a.importance) ||
			(Number(b.at) || 0) - (Number(a.at) || 0),
	);
	const size = Math.max(1, Math.floor(batchSize) || 1);
	const deliver = ordered.slice(0, size);
	const collapsed = ordered.slice(size);
	return {
		deliver,
		collapsed,
		summary: collapsed.length
			? `${collapsed.length} more ${collapsed.length === 1 ? 'message' : 'messages'} waiting`
			: null,
	};
}

/**
 * How long a line should stay on screen: long enough to read comfortably,
 * capped so a verbose payload can never park an avatar in someone's corner.
 * Roughly 200 words per minute plus a beat to notice it.
 */
export function dwellMsFor(text, { min = 4200, max = 14_000, perChar = 55 } = {}) {
	const chars = String(text || '').length;
	return Math.max(min, Math.min(max, min + chars * perChar));
}

/**
 * Prune a dedupe map in place and return it. Called by the runtime on a slow
 * cadence so a long-lived page cannot grow an unbounded key set.
 */
export function pruneSeen(seen, now, ttlMs, cap = 500) {
	if (!seen) return seen;
	for (const [key, ts] of seen) {
		if (now - ts > ttlMs) seen.delete(key);
	}
	if (seen.size > cap) {
		const excess = seen.size - cap;
		let i = 0;
		for (const key of seen.keys()) {
			if (i++ >= excess) break;
			seen.delete(key);
		}
	}
	return seen;
}

/**
 * Normalise anything a source hands over into a Message.
 * Sources are allowed to be sloppy so integrators can point one at an existing
 * feed without writing a mapper; this is where that sloppiness stops.
 */
export function toMessage(raw) {
	if (raw == null) return null;
	if (typeof raw === 'string') return { text: raw.trim() } ;
	const text = String(raw.text ?? raw.message ?? raw.title ?? raw.body ?? '').trim();
	if (!text) return null;
	const at = raw.at ?? raw.timestamp ?? raw.created_at ?? raw.createdAt;
	const parsed = typeof at === 'string' ? Date.parse(at) : Number(at);
	return {
		id: raw.id != null ? String(raw.id) : undefined,
		key: raw.key != null ? String(raw.key) : undefined,
		text,
		importance: raw.importance ?? raw.priority ?? undefined,
		from: raw.from != null ? String(raw.from) : undefined,
		url: raw.url ?? raw.link ?? undefined,
		at: Number.isFinite(parsed) ? parsed : undefined,
		tone: raw.tone,
		emote: raw.emote,
		meta: raw.meta ?? undefined,
	};
}