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.

16.0 KB
Raw Blame
// @ts-check
// The audit trail and dedupe ledger of the X mention bot.
//
// Every mention the reader (x-mentions.js) returns is recorded here once,
// with the intent the pure parser (x-mention-intents.js) gave it, before
// anything else happens. The tweet id is the primary key, so two overlapping
// polls that both see a mention race on one INSERT ... ON CONFLICT DO
// NOTHING and exactly one of them wins the right to handle it. The decision,
// the reply (or, in dry-run mode, the reply it would have posted) and any
// error are written back onto the same row. The table is
// x_mention_events (migration 20261008170000_x_mention_events.sql).
//
// Polling cursors are one app_settings row per account,
// `x_mentions_cursor:<kind>:<ref>` (e.g. x_mentions_cursor:company:trythreews,
// x_mentions_cursor:agent:<agent id>), and only ever move forward.

import { sql } from './db.js';

export const DECISIONS = Object.freeze(['reply', 'skip', 'rate_limited', 'unsafe', 'budget', 'error', 'pending', 'paused']);
export const ACCOUNT_KINDS = Object.freeze(['company', 'agent']);
export const MENTION_TEXT_MAX = 4000;
const TEXT_MAX = 2000;
const SNOWFLAKE_RE = /^\d{1,25}$/;

export class MentionStoreError extends Error {
	/** @param {string} message @param {string} code */
	constructor(message, code) {
		super(message);
		this.name = 'MentionStoreError';
		this.code = code;
	}
}

function capText(v, max = TEXT_MAX) {
	if (v == null) return null;
	const s = String(v);
	return s.length > max ? s.slice(0, max) : s;
}

function accountOf(account) {
	const kind = account?.kind;
	const ref = account?.ref != null ? String(account.ref) : '';
	if (!ACCOUNT_KINDS.includes(kind) || !ref) throw new MentionStoreError('account must be { kind: company|agent, ref }', 'bad_account');
	return { kind, ref };
}

/** The app_settings key holding one account's mention cursor. */
export function cursorKey(account) {
	const { kind, ref } = accountOf(account);
	return `x_mentions_cursor:${kind}:${ref}`;
}

/** The newest mention id already read for an account, or null before the first poll. */
export async function getCursor(account) {
	const [row] = await sql`select value from app_settings where key = ${cursorKey(account)}`;
	const id = row?.value?.since_id;
	return id ? String(id) : null;
}

/**
 * Move an account's cursor forward to `sinceId`. A cursor never moves back:
 * when two polls finish out of order, the older one's write is a no-op.
 * @returns {Promise<boolean>} true when the cursor moved
 */
export async function advanceCursor(account, sinceId) {
	const id = String(sinceId ?? '');
	if (!SNOWFLAKE_RE.test(id)) throw new MentionStoreError(`not an X post id: ${id.slice(0, 40)}`, 'bad_cursor');
	const value = JSON.stringify({ since_id: id });
	const rows = await sql`
		insert into app_settings (key, value) values (${cursorKey(account)}, ${value}::jsonb)
		on conflict (key) do update
			set value = excluded.value, updated_at = now()
			where coalesce((app_settings.value->>'since_id')::numeric, 0) < (excluded.value->>'since_id')::numeric
		returning key
	`;
	return rows.length > 0;
}

/**
 * Record a mention once. The first caller for a tweet id gets
 * `inserted: true` and owns its handling; every later caller gets false.
 *
 * @param {{ mention: any, parsed: { intent: string, args?: object, reason?: string }, dryRun?: boolean, decision?: string|null, reason?: string|null }} input
 * @returns {Promise<{ inserted: boolean, tweetId: string }>}
 */
export async function recordMention({ mention, parsed, dryRun = true, decision = null, reason = null }) {
	const tweetId = String(mention?.id ?? '');
	if (!SNOWFLAKE_RE.test(tweetId)) throw new MentionStoreError('mention has no X post id', 'bad_mention');
	const authorId = mention?.userId || mention?.author?.id;
	if (!authorId) throw new MentionStoreError('mention has no author id', 'bad_mention');
	const { kind, ref } = accountOf(mention?.account);
	if (!parsed?.intent) throw new MentionStoreError('mention was not parsed', 'bad_intent');
	if (decision != null && !DECISIONS.includes(decision)) throw new MentionStoreError(`unknown decision: ${decision}`, 'bad_decision');
	const createdAt = mention.createdAt && Number.isFinite(Date.parse(mention.createdAt)) ? mention.createdAt : null;
	const rows = await sql`
		insert into x_mention_events (
			tweet_id, account_kind, account_ref, author_id, author_username, conversation_id,
			mention_text, mention_created_at, intent, args, decision, reason, dry_run, decided_at
		) values (
			${tweetId}, ${kind}, ${ref}, ${String(authorId)}, ${mention.username || mention.author?.username || null},
			${mention.conversationId || mention.chatId || null}, ${capText(mention.text, MENTION_TEXT_MAX)}, ${createdAt},
			${parsed.intent}, ${JSON.stringify(parsed.args || {})}::jsonb, ${decision},
			${capText(reason ?? parsed.reason ?? null)}, ${dryRun !== false}, ${decision ? new Date().toISOString() : null}
		)
		on conflict (tweet_id) do nothing
		returning tweet_id
	`;
	return { inserted: rows.length > 0, tweetId };
}

/**
 * Write a decision and its reply back onto a recorded mention. Fields left
 * undefined keep their value. A reply_tweet_id, once set, is never replaced:
 * one mention gets one reply.
 *
 * @param {string} tweetId
 * @param {{ decision?: string, reason?: string, replyText?: string, replyMediaUrl?: string, replyLink?: string, replyTweetId?: string, creationId?: string, error?: string, dryRun?: boolean }} fields
 * @returns {Promise<object|null>} the updated row, or null when no such mention
 */
export async function updateDecision(tweetId, fields = {}) {
	const id = String(tweetId ?? '');
	if (!SNOWFLAKE_RE.test(id)) throw new MentionStoreError('not an X post id', 'bad_mention');
	const d = fields.decision ?? null;
	if (d != null && !DECISIONS.includes(d)) throw new MentionStoreError(`unknown decision: ${d}`, 'bad_decision');
	const replyTweetId = fields.replyTweetId != null ? String(fields.replyTweetId) : null;
	const rows = await sql`
		update x_mention_events set
			decision        = coalesce(${d}, decision),
			reason          = coalesce(${capText(fields.reason)}, reason),
			reply_text      = coalesce(${capText(fields.replyText)}, reply_text),
			reply_media_url = coalesce(${capText(fields.replyMediaUrl)}, reply_media_url),
			reply_link      = coalesce(${capText(fields.replyLink)}, reply_link),
			reply_tweet_id  = coalesce(reply_tweet_id, ${replyTweetId}),
			replied_at      = case when reply_tweet_id is null and ${replyTweetId}::text is not null then now() else replied_at end,
			creation_id     = coalesce(${fields.creationId != null ? String(fields.creationId) : null}, creation_id),
			error           = coalesce(${capText(fields.error)}, error),
			dry_run         = coalesce(${typeof fields.dryRun === 'boolean' ? fields.dryRun : null}::boolean, dry_run),
			decided_at      = case when ${d}::text is not null then now() else decided_at end,
			updated_at      = now()
		where tweet_id = ${id}
		returning *
	`;
	return rows[0] || null;
}

/** One recorded mention, or null. */
export async function getMentionEvent(tweetId) {
	const [row] = await sql`select * from x_mention_events where tweet_id = ${String(tweetId)}`;
	return row || null;
}

/**
 * How many mentions from one author were recorded in the trailing window,
 * optionally limited to some decisions (e.g. ['reply'] for a reply cap) and
 * to one of our accounts.
 *
 * @param {string} authorId
 * @param {{ windowSeconds?: number, decisions?: string[]|null, account?: { kind: string, ref: string }|null }} [opts]
 */
export async function countByAuthor(authorId, { windowSeconds = 3600, decisions = null, account = null } = {}) {
	const secs = Math.max(1, Math.round(Number(windowSeconds) || 3600));
	const list = decisions && decisions.length ? decisions.filter((x) => DECISIONS.includes(x)) : null;
	const acct = account ? accountOf(account) : null;
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where author_id = ${String(authorId)}
		  and created_at > now() - make_interval(secs => ${secs})
		  and (${list ? list.join(',') : null}::text is null or decision = any(string_to_array(${list ? list.join(',') : null}::text, ',')))
		  and (${acct?.kind ?? null}::text is null or (account_kind = ${acct?.kind ?? null} and account_ref = ${acct?.ref ?? null}))
	`;
	return row?.n ?? 0;
}

/**
 * The most recent recorded mentions of one account, newest first, optionally
 * only one decision (the dry-run console lists `reply` rows with dry_run).
 *
 * @param {{ kind: string, ref: string }} account
 * @param {{ limit?: number, decision?: string|null, dryRun?: boolean|null }} [opts]
 */
export async function recentDecisions(account, { limit = 50, decision = null, dryRun = null } = {}) {
	const { kind, ref } = accountOf(account);
	if (decision != null && !DECISIONS.includes(decision)) throw new MentionStoreError(`unknown decision: ${decision}`, 'bad_decision');
	const n = Math.max(1, Math.min(500, Math.round(Number(limit) || 50)));
	return sql`
		select * from x_mention_events
		where account_kind = ${kind} and account_ref = ${ref}
		  and (${decision}::text is null or decision = ${decision})
		  and (${dryRun}::boolean is null or dry_run = ${dryRun})
		order by created_at desc, tweet_id desc
		limit ${n}
	`;
}

/**
 * Cross-account mention listing for the operator console (/x/ops): every
 * account the bot watches, filterable by account, intent, decision and
 * dry-run status. Unlike recentDecisions (one agent's own settings panel),
 * no account is required: an operator reviews the whole bot, not one agent.
 *
 * @param {{ accountKind?: string|null, accountRef?: string|null, intent?: string|null, decision?: string|null, dryRun?: boolean|null, authorId?: string|null, limit?: number, offset?: number }} [opts]
 */
export async function adminListMentions({
	accountKind = null,
	accountRef = null,
	intent = null,
	decision = null,
	dryRun = null,
	authorId = null,
	limit = 50,
	offset = 0,
} = {}) {
	if (accountKind != null && !ACCOUNT_KINDS.includes(accountKind)) throw new MentionStoreError(`unknown account kind: ${accountKind}`, 'bad_account');
	if (decision != null && !DECISIONS.includes(decision)) throw new MentionStoreError(`unknown decision: ${decision}`, 'bad_decision');
	const n = Math.max(1, Math.min(200, Math.round(Number(limit) || 50)));
	const off = Math.max(0, Math.round(Number(offset) || 0));
	const ref = accountRef != null ? String(accountRef) : null;
	const author = authorId != null ? String(authorId) : null;
	return sql`
		select * from x_mention_events
		where (${accountKind}::text is null or account_kind = ${accountKind})
		  and (${ref}::text is null or account_ref = ${ref})
		  and (${intent}::text is null or intent = ${intent})
		  and (${decision}::text is null or decision = ${decision})
		  and (${dryRun}::boolean is null or dry_run = ${dryRun})
		  and (${author}::text is null or author_id = ${author})
		order by created_at desc, tweet_id desc
		limit ${n} offset ${off}
	`;
}

/** Count of mentions matching the same filters adminListMentions uses, for pagination. */
export async function adminCountMentions({
	accountKind = null,
	accountRef = null,
	intent = null,
	decision = null,
	dryRun = null,
	authorId = null,
} = {}) {
	if (accountKind != null && !ACCOUNT_KINDS.includes(accountKind)) throw new MentionStoreError(`unknown account kind: ${accountKind}`, 'bad_account');
	if (decision != null && !DECISIONS.includes(decision)) throw new MentionStoreError(`unknown decision: ${decision}`, 'bad_decision');
	const ref = accountRef != null ? String(accountRef) : null;
	const author = authorId != null ? String(authorId) : null;
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where (${accountKind}::text is null or account_kind = ${accountKind})
		  and (${ref}::text is null or account_ref = ${ref})
		  and (${intent}::text is null or intent = ${intent})
		  and (${decision}::text is null or decision = ${decision})
		  and (${dryRun}::boolean is null or dry_run = ${dryRun})
		  and (${author}::text is null or author_id = ${author})
	`;
	return row?.n ?? 0;
}

/**
 * How many replies we recorded in one conversation on one of our accounts,
 * optionally only inside a trailing window. Dry-run replies count: they are
 * recorded with decision `reply` exactly like live ones.
 *
 * @param {string} conversationId
 * @param {{ windowSeconds?: number|null, account: { kind: string, ref: string } }} opts
 */
export async function countRepliesInConversation(conversationId, { windowSeconds = null, account }) {
	const acct = accountOf(account);
	const secs = windowSeconds ? Math.max(1, Math.round(Number(windowSeconds))) : null;
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where conversation_id = ${String(conversationId)}
		  and decision = 'reply'
		  and account_kind = ${acct.kind} and account_ref = ${acct.ref}
		  and (${secs}::int is null or created_at > now() - make_interval(secs => ${secs}))
	`;
	return row?.n ?? 0;
}

/**
 * Replies one account has recorded in the trailing window, dry-run rows
 * included, so a daily cap holds the same in dry run as it will live.
 *
 * @param {{ kind: string, ref: string }} account
 * @param {{ windowSeconds?: number }} [opts]
 */
export async function countAccountReplies(account, { windowSeconds = 86400 } = {}) {
	const acct = accountOf(account);
	const secs = Math.max(1, Math.round(Number(windowSeconds) || 86400));
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where account_kind = ${acct.kind} and account_ref = ${acct.ref}
		  and decision = 'reply'
		  and created_at > now() - make_interval(secs => ${secs})
	`;
	return row?.n ?? 0;
}

/**
 * Merge a patch into a recorded mention's args. Used to stamp the human a bot
 * mention is answered on behalf of (`on_behalf_of`) so rate limits and the
 * bot loop cap can find it later.
 *
 * @param {string} tweetId
 * @param {Record<string, unknown>} patch
 */
export async function mergeArgs(tweetId, patch) {
	const id = String(tweetId ?? '');
	if (!SNOWFLAKE_RE.test(id)) throw new MentionStoreError('not an X post id', 'bad_mention');
	const rows = await sql`
		update x_mention_events set args = coalesce(args, '{}'::jsonb) || ${JSON.stringify(patch || {})}::jsonb, updated_at = now()
		where tweet_id = ${id}
		returning tweet_id
	`;
	return rows.length > 0;
}

/**
 * Mentions attributed to one human in the trailing window: the ones they wrote
 * themselves plus the ones a known bot wrote on their behalf, so a person gets
 * one allowance however they reach us.
 *
 * @param {string} principalId  the human's X user id
 * @param {{ windowSeconds?: number, decisions?: string[]|null, account?: { kind: string, ref: string }|null }} [opts]
 */
export async function countByPrincipal(principalId, { windowSeconds = 3600, decisions = null, account = null } = {}) {
	const secs = Math.max(1, Math.round(Number(windowSeconds) || 3600));
	const list = decisions && decisions.length ? decisions.filter((x) => DECISIONS.includes(x)) : null;
	const acct = account ? accountOf(account) : null;
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where (author_id = ${String(principalId)} or args->'on_behalf_of'->>'id' = ${String(principalId)})
		  and created_at > now() - make_interval(secs => ${secs})
		  and (${list ? list.join(',') : null}::text is null or decision = any(string_to_array(${list ? list.join(',') : null}::text, ',')))
		  and (${acct?.kind ?? null}::text is null or (account_kind = ${acct?.kind ?? null} and account_ref = ${acct?.ref ?? null}))
	`;
	return row?.n ?? 0;
}

/**
 * Replies already sent to a bot on behalf of a human in one conversation.
 * The bot loop cap reads this: one per conversation, ever.
 *
 * @param {string} conversationId
 * @param {{ account: { kind: string, ref: string } }} opts
 */
export async function countBotRepliesInConversation(conversationId, { account }) {
	const acct = accountOf(account);
	const [row] = await sql`
		select count(*)::int as n from x_mention_events
		where conversation_id = ${String(conversationId)}
		  and decision = 'reply'
		  and args->'on_behalf_of' is not null
		  and account_kind = ${acct.kind} and account_ref = ${acct.ref}
	`;
	return row?.n ?? 0;
}