@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/companion/prefetch-engine.js

@@ -0,0 +1,513 @@
+/**
+ * Prefetch engine — precompute answers to common voice questions so they can be
+ * served INSTANTLY (no LLM). A heartbeat treatment calls `runPrefetchCycle`
+ * periodically; the reply path (hybrid-reply.ts) calls `matchPrefetched` and, on
+ * a hit, returns the cached answer text directly (only the TTS synth remains).
+ *
+ * Reuses the real tools: WeatherTool (Open-Meteo, $0), WebSearchTool (headlines),
+ * reminders agenda, and an inline French date. All deps are injectable so the
+ * engine is unit-testable without network. never-throws.
+ *
+ * @module companion/prefetch-engine
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
+import { formatMarketDigest, formatNewsDigest, } from '../conversation/fresh-context.js';
+import { DEFAULT_NEWS_QUERY, DEFAULT_NEWS_SEARCH_LANES, loadMarketSymbols, loadPrefetchItems, normalizeMarketSymbols, prefetchItemKey, } from './prefetch-config.js';
+/** Fresh window: ordinary cache hits never need a disclosure. */
+export const FRESH_TTL_MS = {
+    weather: 30 * 60_000,
+    news: 15 * 60_000,
+    market: 15 * 60_000,
+    agenda: 10 * 60_000,
+    date: 12 * 60 * 60_000,
+};
+/** Last-known-good window used only when live refresh failed. */
+export const STALE_TTL_MS = {
+    weather: 45 * 60_000,
+    news: 60 * 60_000,
+    market: 30 * 60_000,
+    agenda: 6 * 60 * 60_000,
+    date: 24 * 60 * 60_000,
+};
+// ---------------------------------------------------------------------------
+// Cache store (JSON under ~/.codebuddy/companion/)
+// ---------------------------------------------------------------------------
+export function defaultPrefetchCachePath(env = process.env) {
+    return (env.CODEBUDDY_PREFETCH_CACHE_FILE?.trim() ||
+        join(homedir(), '.codebuddy', 'companion', 'prefetch-cache.json'));
+}
+export function loadPrefetchCache(path = defaultPrefetchCachePath()) {
+    try {
+        const raw = readJsonAtomicSync(path, [], {
+            mode: 0o600,
+            isValid: (value) => Array.isArray(value),
+        });
+        return raw.filter((e) => Boolean(e && typeof e === 'object' && 'key' in e && 'answer' in e));
+    }
+    catch {
+        return [];
+    }
+}
+export function savePrefetchCache(entries, path = defaultPrefetchCachePath()) {
+    try {
+        writeJsonAtomicSync(path, entries, { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// ---------------------------------------------------------------------------
+// Intent matching (pure)
+// ---------------------------------------------------------------------------
+/** Lowercase + strip diacritics so STT accents don't break matching. Pure. */
+export function normalizeQuery(text) {
+    return (text ?? '')
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/\p{M}+/gu, '') // strip combining diacritics (accents)
+        .replace(/['’`\-_.,!?;:()]/g, ' ') // apostrophes/hyphens/punctuation → space (STT-robust)
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const KIND_PATTERNS = {
+    weather: /\b(meteo|quel temps|le temps qu|temps qu il fait|il fait quel temps)\b/,
+    news: /\b(actualite|actualites|nouvelles|les infos|quoi de neuf|gros titres|l actu)\b/,
+    market: /\b(bourse|marches? financiers?|indices? boursiers?|cac\s*40|s\s*(?:&|et)?\s*p\s*500|sp\s*500|nasdaq|wall street|portefeuille boursier|mes valeurs|cours (?:de |des )?(?:indices?|actions?|titres?|valeurs?))\b/,
+    agenda: /\b(agenda|mes rappels|mon programme|au programme|qu est ce que j ai|mes rendez|ma journee)\b/,
+    date: /\b(quel jour|quelle date|on est quel|le jour on est|date du jour|quel jour on est|on est le combien)\b/,
+};
+/**
+ * Which prefetch cache key a question wants, given the configured items (needed
+ * to resolve the weather city). Returns null when nothing matches. Pure.
+ */
+export function intentKeyForQuery(heard, items) {
+    const q = normalizeQuery(heard);
+    if (!q)
+        return null;
+    if (KIND_PATTERNS.weather.test(q)) {
+        const weatherItems = items.filter((i) => i.kind === 'weather');
+        if (weatherItems.length === 0)
+            return null;
+        // Prefer a configured city whose name is spoken in the question.
+        const named = weatherItems.find((i) => i.param && q.includes(normalizeQuery(i.param)));
+        return prefetchItemKey(named ?? weatherItems[0]);
+    }
+    for (const kind of ['market', 'news', 'agenda', 'date']) {
+        if (KIND_PATTERNS[kind].test(q))
+            return kind;
+    }
+    return null;
+}
+/**
+ * Return a fresh cached answer for `heard`, or null. Pure over the injected
+ * cache + items (the reply path passes the loaded cache).
+ */
+export function matchPrefetched(heard, args) {
+    const key = intentKeyForQuery(heard, args.items);
+    if (!key)
+        return null;
+    const entry = args.cache.find((e) => e.key === key);
+    if (!entry)
+        return null;
+    const ttl = FRESH_TTL_MS[entry.kind] ?? 60 * 60_000;
+    return args.now - entry.at < ttl ? entry.answer : null;
+}
+/**
+ * Rich match for conversation surfaces. Unlike the legacy string matcher this
+ * can use a bounded stale value after a refresh outage and discloses its age.
+ */
+export function matchPrefetchedDetailed(heard, args) {
+    const key = intentKeyForQuery(heard, args.items);
+    if (!key)
+        return null;
+    const entry = args.cache.find((candidate) => candidate.key === key);
+    if (!entry)
+        return null;
+    const ageMs = Math.max(0, args.now - entry.at);
+    if (ageMs < FRESH_TTL_MS[entry.kind]) {
+        return { entry, answer: entry.answer, freshness: 'fresh', ageMs };
+    }
+    if (!args.allowStale || ageMs >= STALE_TTL_MS[entry.kind])
+        return null;
+    if (entry.kind === 'news' && entry.context?.kind === 'news') {
+        const formatted = formatNewsDigest(entry.context, { stale: true, now: args.now });
+        if (formatted.speech) {
+            return { entry, answer: formatted.speech, freshness: 'stale', ageMs };
+        }
+    }
+    if (entry.kind === 'market' && entry.context?.kind === 'market') {
+        const formatted = formatMarketDigest(entry.context, { stale: true, now: args.now });
+        if (formatted.speech) {
+            return { entry, answer: formatted.speech, freshness: 'stale', ageMs };
+        }
+    }
+    const minutes = Math.max(1, Math.round(ageMs / 60_000));
+    return {
+        entry,
+        answer: `Je n'ai pas pu rafraîchir cette information. La dernière version date d'environ ${minutes} minutes. ${entry.answer}`,
+        freshness: 'stale',
+        ageMs,
+    };
+}
+// ---------------------------------------------------------------------------
+// Default compute impls (real tools, lazy-imported)
+// ---------------------------------------------------------------------------
+const FR_WEEKDAYS = ['dimanche', 'lundi', 'mardi', 'mercredi', 'jeudi', 'vendredi', 'samedi'];
+const FR_MONTHS = [
+    'janvier',
+    'février',
+    'mars',
+    'avril',
+    'mai',
+    'juin',
+    'juillet',
+    'août',
+    'septembre',
+    'octobre',
+    'novembre',
+    'décembre',
+];
+export function frenchDate(now) {
+    const d = new Date(now);
+    return `Nous sommes le ${FR_WEEKDAYS[d.getDay()]} ${d.getDate()} ${FR_MONTHS[d.getMonth()]} ${d.getFullYear()}.`;
+}
+async function defaultFetchWeather(city) {
+    try {
+        const { WeatherTool } = await import('../tools/weather.js');
+        const res = await new WeatherTool().getWeather(city || 'Paris', 1);
+        return res.success && res.output ? res.output.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isStockWidgetData(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    const validType = candidate.type === 'stock' || candidate.type === 'market' || candidate.type === 'bourse';
+    const price = candidate.price ?? candidate.value;
+    return validType && (typeof price === 'number' || typeof price === 'string');
+}
+function isStockQuoteMetadata(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (typeof candidate.provider === 'string' &&
+        typeof candidate.sourceUrl === 'string' &&
+        /^https?:\/\//i.test(candidate.sourceUrl) &&
+        typeof candidate.fetchedAt === 'number' &&
+        Number.isFinite(candidate.fetchedAt));
+}
+/** Fetch all symbols concurrently and retain every independently sourced success. */
+export async function fetchMarketContext(symbols, fetchedAt, getQuote) {
+    try {
+        const settled = await Promise.allSettled(symbols.map((symbol) => getQuote(symbol)));
+        const items = [];
+        for (const [index, outcome] of settled.entries()) {
+            if (outcome.status !== 'fulfilled')
+                continue;
+            const result = outcome.value;
+            if (!result.success || !isStockWidgetData(result.data) || !isStockQuoteMetadata(result.metadata)) {
+                continue;
+            }
+            const data = result.data;
+            const metadata = result.metadata;
+            const symbol = (data.symbol ?? symbols[index] ?? '').trim().toUpperCase();
+            const name = (data.name ?? symbol).trim();
+            const price = data.price ?? data.value;
+            if (!symbol || !name || price == null)
+                continue;
+            const quoteTime = metadata.quoteTime ?? data.time;
+            items.push({
+                title: `${name} (${symbol})`,
+                url: metadata.sourceUrl,
+                source: metadata.provider,
+                symbol,
+                name,
+                type: data.type,
+                price,
+                fetchedAt: metadata.fetchedAt,
+                ...(data.change != null ? { change: data.change } : {}),
+                ...(data.changePercent != null ? { changePercent: data.changePercent } : {}),
+                ...(data.currency ? { currency: data.currency } : {}),
+                ...(data.market ? { market: data.market } : {}),
+                ...(quoteTime ? { quoteTime, publishedAt: quoteTime } : {}),
+            });
+        }
+        return items.length > 0
+            ? { kind: 'market', locale: 'fr-FR', fetchedAt, symbols: [...symbols], items }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultFetchMarketContext(symbols, fetchedAt) {
+    const { StockQuoteTool } = await import('../tools/stock-quote.js');
+    const tool = new StockQuoteTool();
+    return fetchMarketContext(symbols, fetchedAt, (symbol) => tool.getQuote(symbol));
+}
+/** Build dated topic lanes so one broad query cannot collapse the whole bulletin onto AI. */
+export function buildNewsSearchQueries(baseQuery, fetchedAt, locale, env = process.env) {
+    const timezone = env.CODEBUDDY_TIMEZONE?.trim() || env.TZ?.trim() || 'Europe/Paris';
+    let dateLabel = new Date(fetchedAt).toISOString().slice(0, 10);
+    try {
+        dateLabel = new Intl.DateTimeFormat(locale, {
+            dateStyle: 'long',
+            timeZone: timezone,
+        }).format(new Date(fetchedAt));
+    }
+    catch {
+        /* Invalid locale/timezone: the stable ISO date remains safe for search. */
+    }
+    const lanes = baseQuery === DEFAULT_NEWS_QUERY
+        ? DEFAULT_NEWS_SEARCH_LANES
+        : [baseQuery];
+    return lanes.map((lane) => `${lane} ${dateLabel}`);
+}
+function interleaveSearchResults(batches, limit = 12) {
+    const output = [];
+    const seen = new Set();
+    const width = Math.max(0, ...batches.map((batch) => batch.length));
+    for (let index = 0; index < width && output.length < limit; index += 1) {
+        for (const batch of batches) {
+            const row = batch[index];
+            if (!row)
+                continue;
+            const key = row.url.trim().toLowerCase();
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            output.push(row);
+            if (output.length >= limit)
+                break;
+        }
+    }
+    return output;
+}
+function decodeXmlText(value) {
+    return value
+        .replace(/^<!\[CDATA\[([\s\S]*)\]\]>$/i, '$1')
+        .replace(/&#x([0-9a-f]+);/gi, (_match, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_match, decimal) => String.fromCodePoint(Number.parseInt(decimal, 10)))
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&quot;/gi, '"')
+        .replace(/&apos;/gi, "'")
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function rssTag(block, tag) {
+    const match = block.match(new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)<\\/${tag}>`, 'i'));
+    return decodeXmlText(match?.[1] ?? '');
+}
+/** Parse ordinary RSS 2.0 headlines into the same evidence shape as web search. Pure. */
+export function parseNewsRss(xml, source, maxItems = 6) {
+    const blocks = String(xml ?? '').match(/<item\b[^>]*>[\s\S]*?<\/item>/gi) ?? [];
+    const output = [];
+    for (const block of blocks) {
+        const title = rssTag(block, 'title');
+        const url = rssTag(block, 'link');
+        if (!title || !/^https?:\/\//i.test(url))
+            continue;
+        const publishedAt = rssTag(block, 'pubDate') || rssTag(block, 'dc:date');
+        const summary = rssTag(block, 'description');
+        output.push({
+            title,
+            url,
+            source,
+            ...(publishedAt ? { publishedAt } : {}),
+            ...(summary ? { summary } : {}),
+        });
+        if (output.length >= maxItems)
+            break;
+    }
+    return output;
+}
+async function defaultFetchNewsRssContext(fetchedAt, locale, env = process.env) {
+    if (!locale.toLowerCase().startsWith('fr'))
+        return null;
+    const configured = env.CODEBUDDY_NEWS_RSS_URLS?.trim();
+    const feeds = configured
+        ? configured.split(',').map((url) => url.trim()).filter(Boolean).map((url) => ({ url, source: new URL(url).hostname }))
+        : [
+            { url: 'https://www.franceinfo.fr/titres.rss', source: 'franceinfo' },
+            { url: 'https://www.lemonde.fr/rss/une.xml', source: 'Le Monde' },
+            { url: 'https://www.france24.com/fr/rss', source: 'France 24' },
+        ];
+    const settled = await Promise.allSettled(feeds.map(async (feed) => {
+        const response = await fetch(feed.url, {
+            headers: { Accept: 'application/rss+xml, application/xml, text/xml', 'User-Agent': 'CodeBuddy/1.8' },
+            signal: AbortSignal.timeout(8_000),
+        });
+        if (!response.ok)
+            return [];
+        return parseNewsRss(await response.text(), feed.source, 5);
+    }));
+    const batches = settled.map((result) => result.status === 'fulfilled' ? result.value : []);
+    const items = [];
+    const seen = new Set();
+    for (let index = 0; index < 5 && items.length < 10; index += 1) {
+        for (const batch of batches) {
+            const item = batch[index];
+            if (!item)
+                continue;
+            const key = item.url.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            items.push(item);
+        }
+    }
+    return items.length > 0
+        ? { kind: 'news', query: feeds.map((feed) => feed.url).join(' | '), locale, fetchedAt, items }
+        : null;
+}
+async function defaultFetchNewsContext(query) {
+    try {
+        const fetchedAt = Date.now();
+        const locale = process.env.CODEBUDDY_NEWS_LOCALE?.trim() || 'fr-FR';
+        // Editorial feeds provide concrete, timestamped headlines and avoid the
+        // generic homepages/SEO calendars frequently returned by broad web search.
+        // Search remains the resilient fallback and supports custom topic queries.
+        if (!query.trim()) {
+            const rss = await defaultFetchNewsRssContext(fetchedAt, locale);
+            if (rss)
+                return rss;
+        }
+        const { WebSearchTool } = await import('../tools/web-search.js');
+        const [language = 'fr', country = 'FR'] = locale.split('-');
+        const effectiveQuery = query ||
+            process.env.CODEBUDDY_NEWS_QUERY?.trim() ||
+            DEFAULT_NEWS_QUERY;
+        const datedQueries = buildNewsSearchQueries(effectiveQuery, fetchedAt, locale);
+        const tool = new WebSearchTool();
+        const batches = [];
+        const paceMs = Math.max(250, Math.min(5_000, Number(process.env.CODEBUDDY_NEWS_SEARCH_PACE_MS) || 1_100));
+        for (const [index, datedQuery] of datedQueries.entries()) {
+            if (index > 0)
+                await new Promise((resolve) => setTimeout(resolve, paceMs));
+            batches.push(await tool.searchStructured(datedQuery, {
+                maxResults: 8,
+                search_lang: language.toLowerCase(),
+                country: country.toUpperCase(),
+                freshness: 'pd',
+                mode: 'live',
+            }));
+        }
+        const rows = interleaveSearchResults(batches);
+        const items = (rows ?? [])
+            .filter((row) => (row?.title ?? '').trim() && (row?.url ?? '').trim())
+            // Formatting applies stricter editorial gates than the search backend.
+            // Preserve enough candidates here so filtered social/homepage fragments
+            // can be replaced by later, concrete headlines.
+            .slice(0, 12)
+            .map((row) => ({
+            title: row.title.trim(),
+            url: row.url.trim(),
+            ...(row.siteName?.trim() ? { source: row.siteName.trim() } : {}),
+            ...(row.published?.trim() ? { publishedAt: row.published.trim() } : {}),
+            ...(row.snippet?.trim() ? { summary: row.snippet.trim() } : {}),
+        }));
+        return items.length > 0
+            ? { kind: 'news', query: datedQueries.join(' | '), locale, fetchedAt, items }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultFetchAgenda(now) {
+    try {
+        const { loadReminders, agendaFor, describeAgendaForSpeech } = await import('./reminders.js');
+        const reminders = await loadReminders();
+        return describeAgendaForSpeech(agendaFor(reminders, now, 2), now);
+    }
+    catch {
+        return null;
+    }
+}
+/** Compute the spoken answer for one item. Returns the cache entry, or null on failure. */
+export async function computeAnswer(item, deps = {}) {
+    const now = deps.now ?? Date.now();
+    const key = prefetchItemKey(item);
+    let answer = null;
+    let context;
+    try {
+        switch (item.kind) {
+            case 'weather':
+                answer = await (deps.fetchWeather ?? defaultFetchWeather)((item.param ?? '').trim());
+                break;
+            case 'news':
+                if (deps.fetchNews) {
+                    answer = await deps.fetchNews((item.param ?? '').trim());
+                }
+                else {
+                    const digest = await (deps.fetchNewsContext ?? defaultFetchNewsContext)((item.param ?? '').trim());
+                    if (digest) {
+                        context = digest;
+                        answer = formatNewsDigest(digest, { now }).speech;
+                    }
+                }
+                break;
+            case 'market': {
+                const symbols = deps.marketSymbols
+                    ? normalizeMarketSymbols(deps.marketSymbols)
+                    : loadMarketSymbols();
+                const digest = await (deps.fetchMarketContext ?? defaultFetchMarketContext)(symbols, now);
+                if (digest) {
+                    context = digest;
+                    answer = formatMarketDigest(digest, { now }).speech;
+                }
+                break;
+            }
+            case 'agenda':
+                answer = await (deps.fetchAgenda ?? defaultFetchAgenda)(now);
+                break;
+            case 'date':
+                answer = (deps.makeDate ?? frenchDate)(now);
+                break;
+        }
+    }
+    catch {
+        answer = null;
+    }
+    const clean = (answer ?? '').trim();
+    return clean
+        ? { key, kind: item.kind, answer: clean, at: now, ...(context ? { context } : {}) }
+        : null;
+}
+/**
+ * One prefetch cycle: recompute every configured item and merge into the cache
+ * (updating computed keys, preserving others). never-throws.
+ */
+export async function runPrefetchCycle(deps = {}) {
+    const items = loadPrefetchItems(deps.itemsPath);
+    const cachePath = deps.cachePath;
+    const cache = loadPrefetchCache(cachePath);
+    const byKey = new Map(cache.map((e) => [e.key, e]));
+    const result = { computed: [], failed: [] };
+    const computedEntries = await Promise.all(items.map((item) => computeAnswer(item, deps)));
+    for (const [index, item] of items.entries()) {
+        const entry = computedEntries[index] ?? null;
+        if (entry) {
+            byKey.set(entry.key, entry);
+            result.computed.push(entry.key);
+        }
+        else {
+            result.failed.push(prefetchItemKey(item));
+        }
+    }
+    savePrefetchCache([...byKey.values()], cachePath);
+    logger.info(`[prefetch] cycle: ${result.computed.length} prêt(s) [${result.computed.join(', ')}]` +
+        (result.failed.length ? `, ${result.failed.length} échec(s)` : ''));
+    return result;
+}
+//# sourceMappingURL=prefetch-engine.js.map

package/dist/companion/presence-loop.d.ts

@@ -0,0 +1,85 @@
+import { type HomeInteractionDecision } from './home-interaction-policy.js';
+import { type DailyInteractionReservation } from './daily-interaction-budget.js';
+export interface PresenceCtx {
+    now: Date;
+    /** Local hour 0-23. */
+    hour: number;
+    /** Someone is actually here (camera presence / recent arrival). */
+    personPresent: boolean;
+    /** Recent transcripts — for frustration / thread cues. */
+    recentHearing: string[];
+    /** A recent drowsy signal. */
+    drowsy: boolean;
+    /** A thread from memory worth following up (e.g. a project). */
+    projectThread: string | null;
+    /** Whole days since the companion first saw Patrice (shared-history tenure). */
+    daysTogether: number;
+    /** Whole days since the last confirmed sighting (0 on a continuous presence). */
+    daysSinceLastSeen: number;
+    /** Tenure milestones already celebrated — so a milestone moment fires exactly once. */
+    celebratedMilestones: number[];
+    /** An event Patrice mentioned that is now due for a "how did it go?" follow-up, or null. */
+    dueEventFollowUp?: {
+        id: string;
+        followUp: string;
+    } | null;
+}
+export interface Moment {
+    id: string;
+    /** Minimum gap before THIS moment may fire again. */
+    cooldownMs: number;
+    /** It asked something → open the conversation window so he can answer back. */
+    engage?: boolean;
+    /** Produce the spoken line, or null if this moment doesn't fit right now. */
+    generate: (ctx: PresenceCtx) => string | null;
+}
+export interface PresenceDeps {
+    say?: (text: string) => Promise<void>;
+    now?: () => Date;
+    isPersonPresent?: () => boolean | Promise<boolean>;
+    /** Don't talk over a live exchange. */
+    inConversation?: () => boolean | Promise<boolean>;
+    recentHearing?: () => Promise<string[]>;
+    drowsy?: () => boolean | Promise<boolean>;
+    projectThread?: () => Promise<string | null>;
+    /** Open the conversation window after an engaging moment. */
+    onEngage?: () => void;
+    /** Override the moment library (tests). */
+    moments?: Moment[];
+    /** Max presence acts per rolling hour (default from env, generous since he chose "vivant"). */
+    hourlyCap?: number;
+    tickMs?: number;
+    /** Override the relationship-state file path (tests). Default: CODEBUDDY_RELATIONSHIP_STATE_FILE
+     *  or ~/.codebuddy/companion/relationship-state.json. */
+    relationshipStatePath?: string;
+    /** Override the event-followups file path (tests). Setting it (or CODEBUDDY_COMPANION_EVENT_FOLLOWUPS)
+     *  enables the due-follow-up read each tick. Default path: ~/.codebuddy/companion/event-followups.json. */
+    eventFollowUpsPath?: string;
+    /** The shared conductor (arbitrates who speaks). Default: the singleton. Injectable for tests. */
+    conductor?: {
+        claim: (surface: 'presence') => boolean;
+    };
+    /** Household posture/calendar gate. Wired by `wirePresenceLoop`; injectable for tests. */
+    homePolicy?: (now: Date) => Promise<HomeInteractionDecision>;
+    /** Shared cross-surface daily invitation budget. Wired by `wirePresenceLoop`. */
+    claimDailyBudget?: (limit: number, now: Date) => Promise<DailyInteractionReservation>;
+}
+export declare const RELATIONSHIP_MOMENTS: Moment[];
+export declare const DEFAULT_MOMENTS: Moment[];
+/** Test seam. */
+export declare function resetPresenceState(): void;
+/**
+ * Presence files can be fresh while explicitly saying that nobody matched
+ * (`left`, `unknown`, or an empty camera frame). Only a confirmed match is a
+ * licence for an unsolicited spoken moment.
+ */
+export declare function hasConfirmedPresence(context: {
+    hasMatch?: unknown;
+} | null | undefined): boolean;
+/**
+ * One pass of the conductor. Exposed so tests drive it with a controlled clock + injected gates.
+ * Never-throws. Returns the spoken line (or null when it stayed silent) — for tests/logging.
+ */
+export declare function runPresenceTick(deps?: PresenceDeps): Promise<string | null>;
+/** Start the presence loop on its own interval (works without the sensory daemon). Returns teardown. */
+export declare function wirePresenceLoop(deps?: PresenceDeps): () => void;