@withbuddi/buddi 0.1.0-pre.20 → 0.1.0-pre.22

package/node_modules/@buddi/gateway/dist/telegram/voice.js

@@ -0,0 +1,220 @@
+/**
+ * Voice on Telegram (docs/telegram.md, Voice).
+ *
+ * In: a voice note is transcribed by the speech plugin's `speech.transcribe`
+ * and run as if the owner had typed it; nothing is echoed back, the transcript
+ * is the owner's message in the conversation. Out: when the owner spoke (or
+ * chose `/voice always`), the answer is synthesized with `speech.say` (which
+ * rewrites it for the ear first) and sent as a voice note, alone or with the
+ * text as its caption (`/voice voice|both`).
+ *
+ * The two choices live in the chat's row (core.surface_chat_voice) and, when
+ * the plugin is there, in its own copy (`speech.telegram_voice`, Settings →
+ * Speech → On Telegram): the plugin's copy wins where it has one, and
+ * `/voice` writes both.
+ *
+ * buddi does not know the speech plugin: it calls its tools **by name**
+ * through the registry, as the owner (`OWNER_AGENT_ID`), so no approval card
+ * is raised for the owner's own voice note and the plugin's daily caps still
+ * count it. No plugin, or nothing set up on Settings → Speech, is one
+ * sentence saying where to fix it.
+ */
+import { localDateString, OWNER_AGENT_ID } from '@buddi/core';
+export const VOICE_WHEN = ['spoken', 'always', 'off'];
+export const VOICE_FORM = ['voice', 'both'];
+export const DEFAULT_CHAT_VOICE = { when: 'spoken', form: 'voice' };
+/** Telegram's caption ceiling: past it the text follows as its own message. */
+export const MAX_VOICE_CAPTION_CHARS = 1024;
+/** An answer longer than this is not read aloud: text only, and nothing said about it. */
+export const MAX_SPOKEN_CHARS = 4000;
+export const TRANSCRIBE_TOOL = 'speech.transcribe';
+export const SAY_TOOL = 'speech.say';
+/** Owner-only, so never in `registry.list()`: reached by invoking it. */
+export const TELEGRAM_VOICE_TOOL = 'speech.telegram_voice';
+/** A refusal's words, sorted: nothing set up, a language it cannot speak, or anything else. */
+export function classifySpeechRefusal(message) {
+    if (/not-english/.test(message))
+        return 'not-english';
+    if (/not set up|is not installed|no account is chosen|chosen in Settings → Speech no longer exists|is disabled in Settings|is not connected/.test(message)) {
+        return 'unconfigured';
+    }
+    return 'failed';
+}
+/** The two tools through the registry, as the owner. */
+export function createSpeechHooks(deps) {
+    const has = (name) => deps.registry.list().some((t) => t.name === name);
+    const invoke = async (name, args, conversationId) => {
+        if (!has(name))
+            return { ok: false, reason: 'missing', message: `${name} is not installed` };
+        const { conversationId: _none, ...ctx } = deps.ctx;
+        // A conversation only when the surface names one (the dashboard does), so the use is counted against it.
+        const result = await deps.registry.invoke(name, args, { ...ctx, ...(conversationId ? { conversationId } : {}), agentId: OWNER_AGENT_ID, now: deps.now });
+        if (result.ok)
+            return { ok: true, output: result.output };
+        if (result.reason === 'unknown-tool')
+            return { ok: false, reason: 'missing', message: result.message };
+        return { ok: false, reason: classifySpeechRefusal(result.message), message: result.message };
+    };
+    /** An owner-only tool, invoked straight away; undefined when it is not there or refused. */
+    const ownerCall = async (name, args) => {
+        const { conversationId: _none, ...ctx } = deps.ctx;
+        const result = await deps.registry.invoke(name, args, { ...ctx, agentId: OWNER_AGENT_ID, now: deps.now });
+        return result.ok && result.output && typeof result.output === 'object' ? result.output : undefined;
+    };
+    return {
+        canSpeak: () => has(SAY_TOOL),
+        async transcribe(artifactId, conversationId) {
+            const result = await invoke(TRANSCRIBE_TOOL, { artifactId }, conversationId);
+            if (!result.ok)
+                return result;
+            const text = typeof result.output.text === 'string' ? result.output.text.trim() : '';
+            const language = typeof result.output.language === 'string' ? result.output.language : undefined;
+            return { ok: true, text, ...(language ? { language } : {}) };
+        },
+        async say(text, handles, conversationId) {
+            const result = await invoke(SAY_TOOL, { text, ...(handles && Object.keys(handles).length > 0 ? { handles } : {}) }, conversationId);
+            if (!result.ok)
+                return result;
+            const id = result.output.id;
+            if (typeof id !== 'string')
+                return { ok: false, reason: 'failed', message: 'speech.say returned no file' };
+            const mime = result.output.mime;
+            return { ok: true, artifactId: id, ...(typeof mime === 'string' ? { mime } : {}) };
+        },
+        async voicePrefs() {
+            const result = await ownerCall(TELEGRAM_VOICE_TOOL, {});
+            if (!result)
+                return {};
+            const when = result.when;
+            const form = result.form;
+            return {
+                ...(VOICE_WHEN.includes(when) ? { when: when } : {}),
+                ...(VOICE_FORM.includes(form) ? { form: form } : {}),
+            };
+        },
+        async saveVoicePrefs(voice) {
+            return (await ownerCall(TELEGRAM_VOICE_TOOL, { when: voice.when, form: voice.form })) !== undefined;
+        },
+    };
+}
+/* ------------------------------------------------------------------ *
+ * The words
+ * ------------------------------------------------------------------ */
+/**
+ * A detected language, by its English name: Whisper answers a code ("fr"),
+ * OpenAI a name ("french"). Unknown or empty: undefined, and nothing is said.
+ */
+export function languageName(detected) {
+    const raw = detected?.trim();
+    if (!raw || raw.length > 40)
+        return undefined;
+    if (/^[a-z]{2,3}(?:[-_][a-z0-9]{2,8})*$/i.test(raw)) {
+        try {
+            const name = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'none' }).of(raw.replace('_', '-'));
+            return name && name.toLowerCase() !== raw.toLowerCase() ? name : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!/^\p{L}[\p{L} ]*$/u.test(raw))
+        return undefined;
+    return raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+}
+/** The turn's text: the transcript, then a caption the owner typed under the note. */
+export function voiceTurnText(transcript, caption) {
+    return caption ? `${transcript}\n\n${caption}` : transcript;
+}
+export const INSTALL_SPEECH_TEXT = 'To have voice notes heard, install the speech plugin from Settings → Plugins.';
+export const SET_UP_LISTENING_TEXT = 'To have voice notes heard, set up listening in Settings → Speech.';
+export const NO_WORDS_TEXT = 'I saved the voice note, but heard no words in it.';
+/** Transcription refused or failed: one sentence, and the file is kept either way. */
+export function notHeardText(message) {
+    const why = message.replace(/^refused: /, '').replace(/\.$/, '');
+    return `I saved the voice note, but could not transcribe it: ${why.charAt(0).toLowerCase()}${why.slice(1)}.`;
+}
+/** Why this answer came as text, said at most once a day in a chat. */
+export function textInsteadText(reason) {
+    switch (reason) {
+        case 'not-english':
+            return 'I answered in text: the voice on this computer does not speak this language.';
+        case 'missing':
+            return 'I answered in text: voice replies need the speech plugin, from Settings → Plugins.';
+        case 'unconfigured':
+            return 'I answered in text: voice replies need speaking set up in Settings → Speech.';
+        default:
+            return 'I answered in text: the voice could not be made this time.';
+    }
+}
+const WHEN_WORDS = {
+    spoken: 'when you send a voice note',
+    always: 'for every answer',
+};
+const FORM_WORDS = {
+    voice: 'as the voice note alone',
+    both: 'as a voice note with the text',
+};
+/** "when you send a voice note, as the voice note alone", or "off: answers are text only". */
+export function voiceSummary(voice) {
+    return voice.when === 'off' ? 'off: answers are text only' : `${WHEN_WORDS[voice.when]}, ${FORM_WORDS[voice.form]}`;
+}
+export const VOICE_USAGE_TEXT = 'Send /voice spoken, always or off for when, and /voice voice, both or text for what.';
+/** `/voice` alone: the current choice and the words it takes, on one line. */
+export function voiceStatusText(current) {
+    return `Voice replies: ${voiceSummary(current)}. ${VOICE_USAGE_TEXT}`;
+}
+export function voiceSetText(voice) {
+    return `Voice replies: ${voiceSummary(voice)}.`;
+}
+/**
+ * `/voice <word>` over the current choice: spoken, always or off set when;
+ * voice or both set what (and turn an `off` chat back to spoken); text is
+ * off. Undefined when the word is none of these.
+ */
+export function applyVoiceArg(current, arg) {
+    const word = arg.trim().toLowerCase();
+    if (VOICE_WHEN.includes(word))
+        return { ...current, when: word };
+    if (VOICE_FORM.includes(word)) {
+        return { when: current.when === 'off' ? 'spoken' : current.when, form: word };
+    }
+    if (word === 'text')
+        return { ...current, when: 'off' };
+    return undefined;
+}
+/** Will this turn's answer be spoken? When the owner spoke (unless off), or always. */
+export function answerSpoken(when, ownerSpoke) {
+    return when === 'always' || (when === 'spoken' && ownerSpoke);
+}
+/* ------------------------------------------------------------------ *
+ * The chat's setting (core.surface_chat_voice, migrations 048 and 049)
+ * ------------------------------------------------------------------ */
+export async function getChatVoice(pool, surface, chatId) {
+    const { rows } = await pool.query(`select voice_when, voice_form from core.surface_chat_voice where surface = $1 and external_chat_id = $2`, [surface, chatId]);
+    const when = rows[0]?.voice_when;
+    const form = rows[0]?.voice_form;
+    return {
+        when: VOICE_WHEN.includes(when) ? when : DEFAULT_CHAT_VOICE.when,
+        form: VOICE_FORM.includes(form) ? form : DEFAULT_CHAT_VOICE.form,
+    };
+}
+export async function setChatVoice(pool, surface, chatId, voice) {
+    await pool.query(`insert into core.surface_chat_voice (surface, external_chat_id, voice_when, voice_form, updated_at)
+     values ($1, $2, $3, $4, now())
+     on conflict (surface, external_chat_id) do update
+       set voice_when = excluded.voice_when, voice_form = excluded.voice_form, updated_at = now()`, [surface, chatId, voice.when, voice.form]);
+}
+/**
+ * Claim today's "why this came as text" line for a chat: true once per day
+ * in the owner's zone, false after that.
+ */
+export async function claimTextInsteadNote(pool, surface, chatId, now, timezone) {
+    const day = localDateString(now, timezone);
+    const { rows } = await pool.query(`insert into core.surface_chat_voice (surface, external_chat_id, fallback_noted_on)
+     values ($1, $2, $3::date)
+     on conflict (surface, external_chat_id) do update set fallback_noted_on = excluded.fallback_noted_on
+       where core.surface_chat_voice.fallback_noted_on is distinct from excluded.fallback_noted_on
+     returning 1 as claimed`, [surface, chatId, day]);
+    return rows.length > 0;
+}
+//# sourceMappingURL=voice.js.map

package/node_modules/@buddi/gateway/dist/telegram/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../../src/telegram/voice.ts"],"names":[],"mappings":"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"}

package/node_modules/@buddi/gateway/dist/tips/engine.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which tip, if any, Home shows today (docs/dashboard.md, Home).
+ *
+ * Per rule the engine keeps the day its condition first held (`firstHeld`),
+ * the day it was last shown (`shownAt`), the day the owner put it off with ×
+ * (`laterAt`) and whether they said "Not this again" (`dismissed`). The rules:
+ *
+ * - at most one card a day: once a tip is shown on a day, no other shows that
+ *   day, and one put off or dismissed leaves the day empty;
+ * - a tip shows when its condition has held for `holdsForDays` and
+ *   `cooldownDays` have passed since it was last shown or put off; among
+ *   several, the one that has held longest, then the one first in `TIPS`;
+ * - never during first run, never while tips are off;
+ * - never a tip about a plugin that is not installed, unless its action
+ *   installs it;
+ * - a tip whose condition stops holding disappears, and its hold starts over;
+ * - dismissed is forever.
+ *
+ * Pure: state in, state out. `route.ts` reads and writes it under
+ * `core.web_settings` → `tips.state`.
+ */
+import type { Facts } from './facts.js';
+import type { TipAction, TipRule } from './rules.js';
+export interface TipRuleState {
+    firstHeld?: string;
+    shownAt?: string;
+    laterAt?: string;
+    dismissed?: boolean;
+    /** The day of "Not this again", when it was said since this was kept. */
+    dismissedAt?: string;
+}
+export type TipsState = Record<string, TipRuleState>;
+/** What Home draws. */
+export interface TipView {
+    id: string;
+    text: string;
+    action: TipAction;
+}
+/** `YYYY-MM-DD` on the owner's clock. */
+export declare function dayIn(at: Date, timezone: string): string;
+/** Whole days from `from` to `to`, both `YYYY-MM-DD`. */
+export declare function daysBetween(from: string, to: string): number;
+/**
+ * Today's tip, and the state to keep. The state changes when a hold starts or
+ * stops, and when a tip is picked for today.
+ */
+export declare function pickTip(rules: readonly TipRule[], facts: Facts, previous: TipsState, today: string): {
+    tip: TipView | null;
+    state: TipsState;
+};
+/** "Not this again": never again, until the Tips list brings it back. */
+export declare function dismissTip(previous: TipsState, id: string, today?: string): TipsState;
+/** "Bring back": the dismissal is forgotten; holds and cooldowns stay. */
+export declare function restoreTip(previous: TipsState, id: string): TipsState;
+export type TipStatus = 'today' | 'holding' | 'quiet' | 'dismissed' | 'shown';
+/** One row of the Tips list. */
+export interface TipListRow extends TipView {
+    status: TipStatus;
+    dismissedAt?: string;
+    holdsSince?: string;
+    shownAt?: string;
+}
+/**
+ * Every rule and where it stands, reading the state without changing it:
+ *
+ * - `today`: the engine would show it now and it has not been shown today;
+ * - `shown`: shown (or put off) today or within its cooldown;
+ * - `dismissed`: "Not this again";
+ * - `holding`: its condition holds, waiting its day;
+ * - `quiet`: its condition does not hold.
+ */
+export declare function listTips(rules: readonly TipRule[], facts: Facts, previous: TipsState, today: string): TipListRow[];
+/** ×: not today, and not before its cooldown has passed. */
+export declare function laterTip(previous: TipsState, id: string, today: string): TipsState;
+//# sourceMappingURL=engine.d.ts.map

package/node_modules/@buddi/gateway/dist/tips/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/tips/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAErD,uBAAuB;AACvB,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,yCAAyC;AACzC,wBAAgB,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5D;AAeD;;;GAGG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAyC3C;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAErF;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAMrE;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;AAE9E,gCAAgC;AAChC,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,MAAM,EAAE,SAAS,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAwBlH;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAElF"}

package/node_modules/@buddi/gateway/dist/tips/engine.js

@@ -0,0 +1,135 @@
+/** `YYYY-MM-DD` on the owner's clock. */
+export function dayIn(at, timezone) {
+    try {
+        return new Intl.DateTimeFormat('en-CA', { timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(at);
+    }
+    catch {
+        return at.toISOString().slice(0, 10);
+    }
+}
+/** Whole days from `from` to `to`, both `YYYY-MM-DD`. */
+export function daysBetween(from, to) {
+    return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000);
+}
+function applies(rule, facts) {
+    if (rule.plugin && !facts.plugins.has(rule.plugin) && !rule.installs)
+        return false;
+    try {
+        return rule.when(facts);
+    }
+    catch {
+        return false;
+    }
+}
+function viewOf(rule) {
+    return { id: rule.id, text: rule.text, action: { ...rule.action } };
+}
+/**
+ * Today's tip, and the state to keep. The state changes when a hold starts or
+ * stops, and when a tip is picked for today.
+ */
+export function pickTip(rules, facts, previous, today) {
+    const state = {};
+    for (const [id, entry] of Object.entries(previous))
+        state[id] = { ...entry };
+    // Holds first, for every rule, so a hold keeps counting while another tip shows.
+    const holding = new Set();
+    for (const rule of rules) {
+        const entry = (state[rule.id] ??= {});
+        if (applies(rule, facts)) {
+            holding.add(rule.id);
+            if (!entry.firstHeld)
+                entry.firstHeld = today;
+        }
+        else {
+            delete entry.firstHeld;
+        }
+        if (Object.keys(entry).length === 0)
+            delete state[rule.id];
+    }
+    if (facts.firstRun)
+        return { tip: null, state };
+    // One card a day: today's, if there was one.
+    const todays = rules.find((rule) => state[rule.id]?.shownAt === today);
+    if (todays) {
+        const entry = state[todays.id];
+        const live = holding.has(todays.id) && !entry.dismissed && entry.laterAt !== today;
+        return { tip: live ? viewOf(todays) : null, state };
+    }
+    const ready = rules
+        .map((rule, index) => ({ rule, index, entry: state[rule.id] }))
+        .filter(({ rule, entry }) => {
+        if (!entry || !holding.has(rule.id) || entry.dismissed || !entry.firstHeld)
+            return false;
+        if (daysBetween(entry.firstHeld, today) < rule.holdsForDays)
+            return false;
+        const last = [entry.shownAt, entry.laterAt].filter((d) => !!d).sort().pop();
+        return !last || daysBetween(last, today) >= rule.cooldownDays;
+    })
+        .sort((a, b) => a.entry.firstHeld.localeCompare(b.entry.firstHeld) || a.index - b.index);
+    const chosen = ready[0];
+    if (!chosen)
+        return { tip: null, state };
+    state[chosen.rule.id] = { ...chosen.entry, shownAt: today };
+    return { tip: viewOf(chosen.rule), state };
+}
+/** "Not this again": never again, until the Tips list brings it back. */
+export function dismissTip(previous, id, today) {
+    return { ...previous, [id]: { ...previous[id], dismissed: true, ...(today ? { dismissedAt: today } : {}) } };
+}
+/** "Bring back": the dismissal is forgotten; holds and cooldowns stay. */
+export function restoreTip(previous, id) {
+    const { dismissed: _d, dismissedAt: _at, ...rest } = previous[id] ?? {};
+    const next = { ...previous };
+    if (Object.keys(rest).length)
+        next[id] = rest;
+    else
+        delete next[id];
+    return next;
+}
+/**
+ * Every rule and where it stands, reading the state without changing it:
+ *
+ * - `today`: the engine would show it now and it has not been shown today;
+ * - `shown`: shown (or put off) today or within its cooldown;
+ * - `dismissed`: "Not this again";
+ * - `holding`: its condition holds, waiting its day;
+ * - `quiet`: its condition does not hold.
+ */
+export function listTips(rules, facts, previous, today) {
+    const { tip, state } = pickTip(rules, facts, previous, today);
+    return rules.map((rule) => {
+        const before = previous[rule.id] ?? {};
+        const after = state[rule.id] ?? {};
+        const row = viewOf(rule);
+        const last = [before.shownAt, before.laterAt].filter((d) => !!d).sort().pop();
+        if (before.shownAt)
+            row.shownAt = before.shownAt;
+        if (before.dismissed) {
+            row.status = 'dismissed';
+            if (before.dismissedAt)
+                row.dismissedAt = before.dismissedAt;
+        }
+        else if (tip?.id === rule.id && before.shownAt !== today) {
+            row.status = 'today';
+        }
+        else if (last && (last === today || daysBetween(last, today) < rule.cooldownDays)) {
+            row.status = 'shown';
+            row.shownAt = before.shownAt ?? last;
+        }
+        else if (!applies(rule, facts)) {
+            row.status = 'quiet';
+        }
+        else {
+            row.status = 'holding';
+        }
+        if (after.firstHeld && (row.status === 'holding' || row.status === 'today'))
+            row.holdsSince = after.firstHeld;
+        return row;
+    });
+}
+/** ×: not today, and not before its cooldown has passed. */
+export function laterTip(previous, id, today) {
+    return { ...previous, [id]: { ...previous[id], laterAt: today } };
+}
+//# sourceMappingURL=engine.js.map

package/node_modules/@buddi/gateway/dist/tips/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/tips/engine.ts"],"names":[],"mappings":"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"}

package/node_modules/@buddi/gateway/dist/tips/facts.d.ts

@@ -0,0 +1,69 @@
+/** The `core.web_settings` key the dashboard's page views are kept under. */
+export declare const TIPS_PAGES_KEY = "tips.pages";
+/** How many distinct pages are remembered; the oldest seen goes first. */
+export declare const TIPS_PAGES_CAP = 64;
+export interface Facts {
+    /** Whole days since the installation was first set up. */
+    daysSinceInstall: number;
+    /** First run is still going: no tip then. */
+    firstRun: boolean;
+    /** The owner's agents, the maker left out. */
+    agents: number;
+    agentIds: Set<string>;
+    /** Groups not archived. */
+    groups: number;
+    /** Installed plugin names. */
+    plugins: Set<string>;
+    /** The email plugin has at least one mailbox. */
+    mailboxSet: boolean;
+    /** Somebody reads the mail: Mail Triage is on the team. */
+    mailAgent: boolean;
+    speechInstalled: boolean;
+    /** The owner ever spoke to buddi (a recording) or an agent ever used speech. */
+    voiceUsed: boolean;
+    missions: number;
+    telegramPaired: boolean;
+    browserUsed: boolean;
+    toolsUsed: Set<string>;
+    pagesVisited: Set<string>;
+}
+interface Queryable {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+export interface FactsDeps {
+    pool: Queryable;
+    now: () => Date;
+    /** The roster as the catalog holds it now. */
+    agents: () => ReadonlyArray<{
+        id: string;
+        roles?: readonly string[];
+    }>;
+    /** Installed plugin names. */
+    plugins: () => readonly string[];
+    /** Whether the email plugin has a mailbox; its own page query answers it. */
+    mailboxSet: () => Promise<boolean>;
+}
+/** Mail Triage's agent id, as the email plugin proposes it. */
+export declare const MAIL_AGENT_ID = "mail-triage";
+/** The slice of `core.web_settings` the tips read and write; a map in tests. */
+export interface SettingsStore {
+    read<T>(key: string): Promise<T | null>;
+    write(key: string, value: unknown): Promise<void>;
+}
+/** `core.web_settings`, as a `SettingsStore`. */
+export declare function webSettingsStore(pool: Queryable): SettingsStore;
+/** The pages the dashboard said it opened, page → the day it last said so. */
+export declare function readPagesSeen(store: SettingsStore): Promise<Record<string, string>>;
+/** A page name the dashboard may report: its route, without the `#/`, short. */
+export declare const PAGE_NAME: RegExp;
+/**
+ * Remember one page seen on one day. Once a day per page: a second report the
+ * same day writes nothing. Capped: past `TIPS_PAGES_CAP` the page seen longest
+ * ago is forgotten.
+ */
+export declare function recordPageSeen(store: SettingsStore, page: string, day: string): Promise<boolean>;
+export declare function readFacts(deps: FactsDeps): Promise<Facts>;
+export {};
+//# sourceMappingURL=facts.d.ts.map

package/node_modules/@buddi/gateway/dist/tips/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/tips/facts.ts"],"names":[],"mappings":"AAaA,6EAA6E;AAC7E,eAAO,MAAM,cAAc,eAAe,CAAC;AAC3C,0EAA0E;AAC1E,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,MAAM,WAAW,KAAK;IACpB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,UAAU,SAAS;IACjB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACvE,8BAA8B;IAC9B,OAAO,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACjC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACpC;AAED,+DAA+D;AAC/D,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAgB3C,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAK/D;AAED,8EAA8E;AAC9E,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAWzF;AAED,gFAAgF;AAChF,eAAO,MAAM,SAAS,QAAiC,CAAC;AAExD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOtG;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CA6C/D"}

package/node_modules/@buddi/gateway/dist/tips/facts.js

@@ -0,0 +1,104 @@
+/**
+ * What the tips are decided on (docs/dashboard.md, Home): a handful of facts
+ * about this installation, read from what already exists. Nothing here is
+ * recorded for the tips' sake except the pages the dashboard reports it
+ * opened (`tips.pages`), which nothing else knew.
+ *
+ * Every read is forgiving: a table a plugin owns may not be there, and a
+ * failed read is the quiet answer ("not used", "none"), so a broken query can
+ * only ever hold a tip back, never raise one.
+ */
+import { readWebSetting, writeWebSetting } from '@buddi/core';
+import { ROLE_MAKER } from '../agents/roles.js';
+/** The `core.web_settings` key the dashboard's page views are kept under. */
+export const TIPS_PAGES_KEY = 'tips.pages';
+/** How many distinct pages are remembered; the oldest seen goes first. */
+export const TIPS_PAGES_CAP = 64;
+/** Mail Triage's agent id, as the email plugin proposes it. */
+export const MAIL_AGENT_ID = 'mail-triage';
+const DAY_MS = 86_400_000;
+async function rows(pool, sql, params = []) {
+    try {
+        return (await pool.query(sql, params)).rows;
+    }
+    catch {
+        return [];
+    }
+}
+async function count(pool, sql) {
+    const [row] = await rows(pool, sql);
+    return Number(row?.n ?? 0) || 0;
+}
+/** `core.web_settings`, as a `SettingsStore`. */
+export function webSettingsStore(pool) {
+    return {
+        read: (key) => readWebSetting(pool, key),
+        write: (key, value) => writeWebSetting(pool, key, value),
+    };
+}
+/** The pages the dashboard said it opened, page → the day it last said so. */
+export async function readPagesSeen(store) {
+    try {
+        const value = await store.read(TIPS_PAGES_KEY);
+        const out = {};
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const [page, day] of Object.entries(value))
+                if (typeof day === 'string')
+                    out[page] = day;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** A page name the dashboard may report: its route, without the `#/`, short. */
+export const PAGE_NAME = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
+/**
+ * Remember one page seen on one day. Once a day per page: a second report the
+ * same day writes nothing. Capped: past `TIPS_PAGES_CAP` the page seen longest
+ * ago is forgotten.
+ */
+export async function recordPageSeen(store, page, day) {
+    const seen = await readPagesSeen(store);
+    if (seen[page] === day)
+        return false;
+    seen[page] = day;
+    const entries = Object.entries(seen).sort((a, b) => b[1].localeCompare(a[1]) || a[0].localeCompare(b[0]));
+    await store.write(TIPS_PAGES_KEY, Object.fromEntries(entries.slice(0, TIPS_PAGES_CAP)));
+    return true;
+}
+export async function readFacts(deps) {
+    const { pool } = deps;
+    const roster = deps.agents().filter((a) => !(a.roles ?? []).includes(ROLE_MAKER));
+    const agentIds = new Set(roster.map((a) => a.id));
+    const plugins = new Set(deps.plugins());
+    const [install] = await rows(pool, `select least((select min(created_at) from core.owner),
+                  (select min(started_at) from core.onboarding)) as at`);
+    const installedAt = install?.at ? new Date(install.at) : deps.now();
+    const daysSinceInstall = Math.max(0, Math.floor((deps.now().getTime() - installedAt.getTime()) / DAY_MS));
+    const [onboarding] = await rows(pool, `select state from core.onboarding limit 1`);
+    const firstRun = !onboarding || (onboarding.state !== 'done' && onboarding.state !== 'skipped');
+    const toolsUsed = new Set((await rows(pool, `select distinct payload->>'name' as name from core.events where kind = 'tool.called'`))
+        .map((r) => r.name)
+        .filter((n) => typeof n === 'string'));
+    const recorded = await count(pool, `select count(*)::int as n from core.artifacts where kind = 'audio' and created_by = 'owner' and deleted_at is null`);
+    return {
+        daysSinceInstall,
+        firstRun,
+        agents: roster.length,
+        agentIds,
+        groups: await count(pool, `select count(*)::int as n from core.groups where archived_at is null`),
+        plugins,
+        mailboxSet: plugins.has('email') ? await deps.mailboxSet().catch(() => false) : false,
+        mailAgent: agentIds.has(MAIL_AGENT_ID),
+        speechInstalled: plugins.has('speech'),
+        voiceUsed: recorded > 0 || [...toolsUsed].some((t) => t.startsWith('speech.')),
+        missions: await count(pool, `select count(*)::int as n from core.missions`),
+        telegramPaired: (await count(pool, `select count(*)::int as n from core.surface_identities where surface = 'telegram'`)) > 0,
+        browserUsed: [...toolsUsed].some((t) => t.startsWith('browser.')),
+        toolsUsed,
+        pagesVisited: new Set(Object.keys(await readPagesSeen(webSettingsStore(pool)))),
+    };
+}
+//# sourceMappingURL=facts.js.map