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.

feat(companion): turn a polled lane message into a triaged, spoken delivery

nirholas831dfeb27880
diff --git a/api/_lib/companion/poll.js b/api/_lib/companion/poll.js
new file mode 100644
index 000000000..149ed35ac
--- /dev/null
+++ b/api/_lib/companion/poll.js
@@ -0,0 +1,220 @@
+// One place where a raw message from any lane becomes a delivery.
+//
+// lane poll -> contact match -> triage -> stored event -> notification
+//
+// The notification is the delivery mechanism, deliberately: it is already the
+// path that reaches every surface the user has (the bell, Web Push on a phone,
+// and the "avatar" channel, where the walking companion turns around and says
+// the line out loud). What the companion adds on top is whose voice and whose
+// body it arrives in.
+
+import { sql } from '../db.js';
+import { insertNotification } from '../notify.js';
+import { loadUserProviderKeys } from '../provider-keys.js';
+import { triage } from './triage.js';
+import {
+ getSettings,
+ matchContact,
+ insertEvent,
+ recordSourceResult,
+ dueSources,
+} from './store.js';
+import { decryptConfig } from './crypto.js';
+import { pollTelegram, verifyTelegram } from './lanes/telegram.js';
+import { pollCalendar, verifyCalendar } from './lanes/calendar.js';
+import { pollEmail, verifyEmail } from './lanes/email.js';
+
+const LANES = {
+ telegram: { poll: pollTelegram, verify: verifyTelegram },
+ calendar: { poll: pollCalendar, verify: verifyCalendar },
+ email: { poll: pollEmail, verify: verifyEmail },
+};
+
+export function laneFor(kind) {
+ return LANES[kind] || null;
+}
+
+/**
+ * Is it the middle of the user's night?
+ * Quiet hours are evaluated in the user's own timezone, and a window that wraps
+ * midnight (22 to 7) is the normal case rather than the exception.
+ */
+export function inQuietHours(settings, now = new Date()) {
+ if (settings.quiet_start === null || settings.quiet_start === undefined) return false;
+ if (settings.quiet_end === null || settings.quiet_end === undefined) return false;
+ let hour;
+ try {
+ hour = Number(new Intl.DateTimeFormat('en-US', {
+ hour: 'numeric',
+ hour12: false,
+ timeZone: settings.timezone || 'UTC',
+ }).format(now));
+ } catch {
+ hour = now.getUTCHours();
+ }
+ const { quiet_start: start, quiet_end: end } = settings;
+ if (start === end) return true;
+ return start < end ? hour >= start && hour < end : hour >= start || hour < end;
+}
+
+async function anthropicKeyFor(userId) {
+ try {
+ const [row] = await sql`select provider_keys from users where id = ${userId}`;
+ const keys = await loadUserProviderKeys(row?.provider_keys);
+ return keys.anthropic || null;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Store one raw lane item as a triaged event, and deliver it when it clears the
+ * user's bar. Returns the stored row, or null when it was a duplicate.
+ *
+ * @param {object} settings row from companion_settings
+ * @param {object} raw { source_kind, source_id?, external_id, sender, sender_id,
+ * identity_candidates?, title, body, url, occurs_at, priority_hint? }
+ * @param {object} opts { anthropicKey }
+ */
+export async function ingestItem(settings, raw, { anthropicKey = null } = {}) {
+ const userId = settings.user_id;
+ const contact = await matchContact(userId, raw.identity_candidates?.length
+ ? raw.identity_candidates
+ : [raw.sender_id, raw.sender].filter(Boolean));
+
+ const verdict = await triage(raw, contact, { anthropicKey, userId });
+
+ const stored = await insertEvent(userId, {
+ source_id: raw.source_id ?? null,
+ source_kind: raw.source_kind,
+ external_id: raw.external_id,
+ contact_id: contact?.id ?? null,
+ sender: raw.sender ?? null,
+ sender_id: raw.sender_id ?? null,
+ title: raw.title,
+ body: raw.body ?? null,
+ url: raw.url ?? null,
+ importance: verdict.importance,
+ reason: verdict.reason,
+ spoken_line: verdict.line,
+ triage_engine: verdict.engine,
+ occurs_at: raw.occurs_at ?? null,
+ });
+ // Already seen on an earlier poll: nothing to say a second time.
+ if (!stored) return null;
+
+ const loud = settings.enabled
+ && verdict.importance >= settings.threshold
+ && !inQuietHours(settings);
+
+ if (loud) {
+ await insertNotification(userId, 'companion_delivery', {
+ event_id: stored.id,
+ source: raw.source_kind,
+ sender: contact?.display_name || raw.sender || null,
+ title: raw.title,
+ line: verdict.line,
+ importance: verdict.importance,
+ reason: verdict.reason,
+ avatar_glb_url: contact?.avatar_glb_url || settings.avatar_glb_url || null,
+ voice: contact?.voice || settings.voice || null,
+ link: '/companion',
+ });
+ await sql`update companion_events set delivered_at = now() where id = ${stored.id}`;
+ stored.delivered_at = new Date().toISOString();
+ }
+
+ return { ...stored, contact, delivered: loud };
+}
+
+/**
+ * Poll one source row and ingest everything new on it.
+ * Never throws: a lane failure is recorded on the source so the setup page can
+ * show the user exactly what their provider said.
+ */
+export async function pollSource(sourceRow, { settings = null, anthropicKey = null } = {}) {
+ const lane = laneFor(sourceRow.kind);
+ if (!lane) return { ok: false, error: `unknown source kind: ${sourceRow.kind}`, ingested: 0 };
+
+ const resolvedSettings = settings || (await getSettings(sourceRow.user_id));
+ const key = anthropicKey ?? (await anthropicKeyFor(sourceRow.user_id));
+
+ try {
+ const config = sourceRow.config || (await decryptConfig(sourceRow.config_encrypted));
+ const { items, cursor } = await lane.poll({ config, cursor: sourceRow.cursor || {} });
+
+ let ingested = 0;
+ for (const item of items) {
+ const stored = await ingestItem(
+ resolvedSettings,
+ { ...item, source_kind: sourceRow.kind, source_id: sourceRow.id },
+ { anthropicKey: key },
+ );
+ if (stored) ingested += 1;
+ }
+
+ await recordSourceResult(sourceRow.id, {
+ status: 'ok',
+ error: null,
+ cursor,
+ sawEvent: ingested > 0,
+ });
+ return { ok: true, ingested, scanned: items.length };
+ } catch (err) {
+ const message = String(err?.message || err).slice(0, 400);
+ await recordSourceResult(sourceRow.id, { status: 'error', error: message });
+ return { ok: false, error: message, ingested: 0 };
+ }
+}
+
+/** Poll every enabled source on one account (the "check now" button). */
+export async function pollUser(userId, { sourceId = null } = {}) {
+ const settings = await getSettings(userId);
+ const rows = sourceId
+ ? await sql`
+ select id, user_id, kind, label, config_encrypted, cursor
+ from companion_sources where id = ${sourceId} and user_id = ${userId}
+ `
+ : await sql`
+ select id, user_id, kind, label, config_encrypted, cursor
+ from companion_sources where user_id = ${userId} and enabled = true
+ `;
+ const anthropicKey = await anthropicKeyFor(userId);
+ const results = [];
+ for (const row of rows) {
+ const result = await pollSource(row, { settings, anthropicKey });
+ results.push({ source_id: row.id, kind: row.kind, label: row.label, ...result });
+ }
+ return { sources: results, ingested: results.reduce((n, r) => n + r.ingested, 0) };
+}
+
+/**
+ * The cron pass: the least recently polled sources across every account, inside
+ * a wall-clock budget. Whatever the budget does not reach keeps its old
+ * last_polled_at and therefore sorts to the front of the next tick, so a slow
+ * lane can never starve the others.
+ */
+export async function pollDue({ limit = 40, budgetMs = 100_000 } = {}) {
+ const started = Date.now();
+ const rows = await dueSources(limit);
+ const summary = { considered: rows.length, polled: 0, ingested: 0, failed: 0, skipped: 0 };
+ const settingsCache = new Map();
+ const keyCache = new Map();
+
+ for (const row of rows) {
+ if (Date.now() - started > budgetMs) {
+ summary.skipped = rows.length - summary.polled;
+ break;
+ }
+ if (!settingsCache.has(row.user_id)) settingsCache.set(row.user_id, await getSettings(row.user_id));
+ if (!keyCache.has(row.user_id)) keyCache.set(row.user_id, await anthropicKeyFor(row.user_id));
+ const result = await pollSource(row, {
+ settings: settingsCache.get(row.user_id),
+ anthropicKey: keyCache.get(row.user_id),
+ });
+ summary.polled += 1;
+ summary.ingested += result.ingested;
+ if (!result.ok) summary.failed += 1;
+ }
+ return summary;
+}
diff --git a/api/_lib/notify-prefs.js b/api/_lib/notify-prefs.js
index 51c86e144..36eb0ae11 100644
--- a/api/_lib/notify-prefs.js
+++ b/api/_lib/notify-prefs.js
@@ -160,14 +160,14 @@ const DEFAULTS = {
social: { in_app: true, push: true, email: false, telegram: false, avatar: false },
irl: { in_app: true, push: true, email: false, telegram: false, avatar: false },
alerts: { in_app: true, push: true, email: false, telegram: true, avatar: false },
- // The user's own inbox, calendar and phone, triaged by the companion. It is
- // their material, not ours, so it never leaves the site by email; the avatar
- // saying it out loud is the feature itself.
- companion: { in_app: true, push: true, email: false, telegram: false, avatar: true },
// Only unattended completions notify (api/cron/forge-finalize.js), so email
// defaulting on is the feature, not spam: the user left the page and asked
// to hear back.
creations: { in_app: true, push: true, email: true, telegram: false, avatar: true },
+ // The companion category exists to be spoken: a message the visitor's own
+ // companion triaged as worth hearing (api/_lib/companion/triage.js). Email
+ // and telegram would just relay what the user already gets in that inbox.
+ companion: { in_app: true, push: true, email: false, telegram: false, avatar: true },
account: { in_app: true, push: true, email: true, telegram: false, avatar: true },
};