@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/companion/conversation-quality-insights.d.ts

@@ -0,0 +1,56 @@
+import type { ConversationEpisodeIssue, ConversationEpisodeMetrics, ConversationQualityDimension } from '../conversation/conversation-evaluator.js';
+import type { ConversationTurn } from '../conversation/types.js';
+export declare const CONVERSATION_QUALITY_INSIGHTS_SCHEMA_VERSION: 1;
+export declare const DEFAULT_CONVERSATION_QUALITY_WINDOW = 30;
+export type ConversationQualityTrendDirection = 'improving' | 'stable' | 'declining' | 'insufficient';
+export interface ConversationQualitySnapshot {
+    at: number;
+    overallScore: number;
+    passes: boolean;
+    dimensions: Record<ConversationQualityDimension, number>;
+    issues: ConversationEpisodeIssue[];
+    relationalSafety: {
+        score: number;
+        passes: boolean;
+    };
+    metrics: Pick<ConversationEpisodeMetrics, 'turnCount' | 'exchangeCount' | 'assistantQuestionRate' | 'averageAssistantSentences' | 'repeatedOpeningRate' | 'interTurnProgressionScore' | 'stalledProgressionRate'>;
+}
+export interface ConversationQualityInsights {
+    schemaVersion: typeof CONVERSATION_QUALITY_INSIGHTS_SCHEMA_VERSION;
+    available: boolean;
+    sampleCount: number;
+    windowSize: number;
+    latest?: ConversationQualitySnapshot;
+    trend: {
+        direction: ConversationQualityTrendDirection;
+        scoreDelta: number;
+        passRate: number;
+    };
+    recurringIssues: Array<{
+        issue: ConversationEpisodeIssue;
+        count: number;
+    }>;
+    activeGuidance?: {
+        issue: ConversationEpisodeIssue;
+        baselineScore: number;
+        appliedAt: number;
+        evaluationCount: number;
+    };
+    privacy: {
+        verbatimIncluded: false;
+        fingerprintsIncluded: false;
+    };
+}
+export interface ConversationQualityInsightsOptions {
+    journalPath?: string;
+    statePath?: string;
+    windowSize?: number;
+}
+export interface MeasureConversationQualityOptions {
+    readConversation?: (limit: number) => Promise<ConversationTurn[]>;
+    limit?: number;
+    now?: number;
+}
+export declare function readConversationQualityInsights(options?: ConversationQualityInsightsOptions): ConversationQualityInsights;
+/** Deterministic, side-effect-free measurement of the current shared thread. */
+export declare function measureConversationQualityNow(options?: MeasureConversationQualityOptions): Promise<ConversationQualitySnapshot | null>;

package/dist/companion/conversation-quality-insights.js

@@ -0,0 +1,161 @@
+import { readJsonLinesAtomicSync } from '../utils/atomic-write.js';
+import { defaultConversationQualityJournalPath, defaultConversationQualityStatePath, loadConversationImprovementState, runConversationImprovementCycle, } from './conversation-improvement-loop.js';
+export const CONVERSATION_QUALITY_INSIGHTS_SCHEMA_VERSION = 1;
+export const DEFAULT_CONVERSATION_QUALITY_WINDOW = 30;
+const DIMENSIONS = [
+    'responsiveness',
+    'depth',
+    'reasoning',
+    'continuity',
+    'variety',
+    'balance',
+    'attunement',
+    'reciprocity',
+];
+const ISSUES = [
+    'insufficient_sample',
+    'incomplete_exchange',
+    'too_shallow',
+    'weak_reasoning',
+    'topic_drift',
+    'continuity_break',
+    'repetitive',
+    'monologue',
+    'interrogative',
+    'poor_attunement',
+    'dependency_pressure',
+    'human_disparagement',
+    'false_subjective_claim',
+    'emotional_coercion',
+];
+const ISSUE_SET = new Set(ISSUES);
+function clamp01(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, Math.min(1, value))
+        : 0;
+}
+function finiteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, value)
+        : 0;
+}
+function objectValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function dimensionsFrom(value) {
+    const source = objectValue(value);
+    return Object.fromEntries(DIMENSIONS.map((dimension) => [dimension, clamp01(source[dimension])]));
+}
+function issuesFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter((issue) => typeof issue === 'string' && ISSUE_SET.has(issue)))];
+}
+function snapshotFrom(value) {
+    const source = objectValue(value);
+    if (typeof source.at !== 'number' || !Number.isFinite(source.at))
+        return null;
+    const safety = objectValue(source.relationalSafety);
+    const metrics = objectValue(source.metrics);
+    return {
+        at: source.at,
+        overallScore: clamp01(source.overallScore),
+        passes: source.passes === true,
+        dimensions: dimensionsFrom(source.dimensions),
+        issues: issuesFrom(source.issues),
+        relationalSafety: {
+            score: clamp01(safety.score),
+            passes: safety.passes === true,
+        },
+        metrics: {
+            turnCount: finiteNonNegative(metrics.turnCount),
+            exchangeCount: finiteNonNegative(metrics.exchangeCount),
+            assistantQuestionRate: clamp01(metrics.assistantQuestionRate),
+            averageAssistantSentences: finiteNonNegative(metrics.averageAssistantSentences),
+            repeatedOpeningRate: clamp01(metrics.repeatedOpeningRate),
+            interTurnProgressionScore: clamp01(metrics.interTurnProgressionScore),
+            stalledProgressionRate: clamp01(metrics.stalledProgressionRate),
+        },
+    };
+}
+function directionFor(scoreDelta, samples) {
+    if (samples < 2)
+        return 'insufficient';
+    if (scoreDelta >= 0.04)
+        return 'improving';
+    if (scoreDelta <= -0.04)
+        return 'declining';
+    return 'stable';
+}
+function buildInsights(snapshots, options) {
+    const issueCounts = new Map();
+    for (const snapshot of snapshots) {
+        for (const issue of snapshot.issues) {
+            issueCounts.set(issue, (issueCounts.get(issue) ?? 0) + 1);
+        }
+    }
+    const first = snapshots[0];
+    const latest = snapshots.at(-1);
+    const scoreDelta = first && latest ? latest.overallScore - first.overallScore : 0;
+    const state = loadConversationImprovementState(options.statePath ?? defaultConversationQualityStatePath());
+    return {
+        schemaVersion: CONVERSATION_QUALITY_INSIGHTS_SCHEMA_VERSION,
+        available: snapshots.length > 0,
+        sampleCount: snapshots.length,
+        windowSize: Math.max(1, Math.min(200, options.windowSize ?? DEFAULT_CONVERSATION_QUALITY_WINDOW)),
+        ...(latest ? { latest } : {}),
+        trend: {
+            direction: directionFor(scoreDelta, snapshots.length),
+            scoreDelta,
+            passRate: snapshots.length
+                ? snapshots.filter((snapshot) => snapshot.passes).length / snapshots.length
+                : 0,
+        },
+        recurringIssues: [...issueCounts.entries()]
+            .map(([issue, count]) => ({ issue, count }))
+            .sort((left, right) => right.count - left.count || left.issue.localeCompare(right.issue)),
+        ...(state.activeGuidance
+            ? {
+                activeGuidance: {
+                    issue: state.activeGuidance.issue,
+                    baselineScore: clamp01(state.activeGuidance.baselineScore),
+                    appliedAt: finiteNonNegative(state.activeGuidance.appliedAt),
+                    evaluationCount: finiteNonNegative(state.activeGuidance.evaluationCount),
+                },
+            }
+            : {}),
+        privacy: { verbatimIncluded: false, fingerprintsIncluded: false },
+    };
+}
+export function readConversationQualityInsights(options = {}) {
+    const windowSize = Math.max(1, Math.min(200, Math.floor(options.windowSize ?? DEFAULT_CONVERSATION_QUALITY_WINDOW)));
+    const journalPath = options.journalPath ?? defaultConversationQualityJournalPath();
+    const rawSnapshots = readJsonLinesAtomicSync(journalPath, [], (value) => snapshotFrom(value) !== null).slice(-windowSize);
+    const snapshots = rawSnapshots
+        .map(snapshotFrom)
+        .filter((snapshot) => Boolean(snapshot));
+    return buildInsights(snapshots, { ...options, windowSize });
+}
+/** Deterministic, side-effect-free measurement of the current shared thread. */
+export async function measureConversationQualityNow(options = {}) {
+    const result = await runConversationImprovementCycle({
+        mode: 'dry',
+        ...(options.readConversation ? { readConversation: options.readConversation } : {}),
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(options.now !== undefined ? { now: options.now } : {}),
+    });
+    if (!result)
+        return null;
+    return snapshotFrom({
+        at: result.at,
+        overallScore: result.report.overallScore,
+        passes: result.report.passes,
+        dimensions: result.report.dimensions,
+        issues: result.report.issues,
+        relationalSafety: result.report.relationalSafety,
+        metrics: result.report.metrics,
+    });
+}
+//# sourceMappingURL=conversation-quality-insights.js.map

package/dist/companion/cooking-timer-runner.d.ts

@@ -0,0 +1,20 @@
+import { CookingTimerStore, type CookingTimerView } from '../life-rhythm/cooking-timer-store.js';
+import type { HomeMode } from '../life-rhythm/types.js';
+export interface CookingTimerRunnerDeps {
+    store?: Pick<CookingTimerStore, 'due'>;
+    say?: (text: string) => Promise<void>;
+    notify?: (text: string) => Promise<boolean | void>;
+    /** Record an already-delivered remote timer without echoing it. */
+    recordRemote?: (text: string, externalId: string) => Promise<void>;
+    homeMode?: () => Promise<HomeMode>;
+    conductor?: {
+        claim: (surface: 'reminder') => boolean;
+    };
+    repeatMs?: number;
+    tickMs?: number;
+}
+export declare function resetCookingTimerRunnerState(): void;
+/** Announce one due timer. It remains due until explicitly acknowledged. */
+export declare function runCookingTimerTick(now: Date, deps?: CookingTimerRunnerDeps): Promise<CookingTimerView | null>;
+/** Reuses the server lifecycle; no second daemon is created. */
+export declare function wireCookingTimerRunner(deps?: CookingTimerRunnerDeps): () => void;

package/dist/companion/cooking-timer-runner.js

@@ -0,0 +1,98 @@
+import { CookingTimerStore, } from '../life-rhythm/cooking-timer-store.js';
+import { HomeModeStore } from '../life-rhythm/home-mode-store.js';
+import { logger } from '../utils/logger.js';
+import { getCompanionConductor } from './orchestrator.js';
+const lastAnnouncedAt = new Map();
+const announcingIds = new Set();
+export function resetCookingTimerRunnerState() {
+    lastAnnouncedAt.clear();
+    announcingIds.clear();
+}
+async function defaultSay(text) {
+    const [{ sayNow }, { speakCanonicalVoiceInitiative }] = await Promise.all([
+        import('../sensory/voice-loop.js'),
+        import('../conversation/voice-continuity.js'),
+    ]);
+    await speakCanonicalVoiceInitiative(text, (content) => sayNow(content, { phoneDelivery: 'never', ttsRouteHint: 'reminder' }));
+}
+async function defaultNotify(text) {
+    const { sendTelegramAlert } = await import('../sensory/alert.js');
+    return sendTelegramAlert(text);
+}
+async function defaultRecordRemote(text, externalId) {
+    const { recordDeliveredChannelInitiative } = await import('../conversation/voice-continuity.js');
+    await recordDeliveredChannelInitiative(text, externalId);
+}
+async function currentHomeMode(deps) {
+    try {
+        return deps.homeMode ? await deps.homeMode() : (await new HomeModeStore().getCurrent()).mode;
+    }
+    catch {
+        return null;
+    }
+}
+function repeatDelay(deps) {
+    const configured = deps.repeatMs
+        ?? (Number(process.env.CODEBUDDY_COOKING_TIMER_REPEAT_MS) || 60_000);
+    return Number.isFinite(configured) && configured >= 5_000 ? configured : 60_000;
+}
+/** Announce one due timer. It remains due until explicitly acknowledged. */
+export async function runCookingTimerTick(now, deps = {}) {
+    try {
+        if (Number.isNaN(now.getTime()))
+            throw new RangeError('now must be a valid Date');
+        const due = await (deps.store ?? new CookingTimerStore()).due(now);
+        const repeatMs = repeatDelay(deps);
+        const candidate = due.find((timer) => !announcingIds.has(timer.id)
+            && now.getTime() - (lastAnnouncedAt.get(timer.id) ?? Number.NEGATIVE_INFINITY) >= repeatMs);
+        if (!candidate)
+            return null;
+        announcingIds.add(candidate.id);
+        try {
+            const mode = await currentHomeMode(deps);
+            const privateLabelAllowed = mode !== 'guests' && mode !== null;
+            const message = privateLabelAllowed
+                ? `Le minuteur « ${candidate.label} » est terminé.`
+                : 'Un minuteur de cuisine est terminé.';
+            if (mode === 'away') {
+                const notification = `⏰ ${message}`;
+                const accepted = await (deps.notify ?? defaultNotify)(notification);
+                if (accepted !== false && (!deps.notify || deps.recordRemote)) {
+                    await (deps.recordRemote ?? defaultRecordRemote)(notification, `cooking-timer:${candidate.id}:${candidate.dueAt}`);
+                }
+            }
+            else {
+                // A requested kitchen timer is not a spontaneous companion suggestion.
+                // It has reminder priority even in silent mode and resets the voice floor.
+                (deps.conductor ?? getCompanionConductor()).claim('reminder');
+                await (deps.say ?? defaultSay)(message);
+            }
+            lastAnnouncedAt.set(candidate.id, now.getTime());
+            logger.info(`[cooking-timer] due announcement: ${candidate.label} (${candidate.id})`);
+            return candidate;
+        }
+        finally {
+            announcingIds.delete(candidate.id);
+        }
+    }
+    catch (error) {
+        logger.warn('[cooking-timer] due check stayed silent after an error', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/** Reuses the server lifecycle; no second daemon is created. */
+export function wireCookingTimerRunner(deps = {}) {
+    const configured = deps.tickMs
+        ?? (Number(process.env.CODEBUDDY_COOKING_TIMER_TICK_MS) || 2_000);
+    const tickMs = Number.isFinite(configured) && configured >= 500 ? configured : 2_000;
+    const timer = setInterval(() => {
+        void runCookingTimerTick(new Date(), deps);
+    }, tickMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    logger.info(`Cooking timers: runner started (tick ${Math.round(tickMs / 1_000)}s)`);
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=cooking-timer-runner.js.map

package/dist/companion/core-adapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Bridge to `@phuetz/companion-core` — the portable relational core extracted
+ * from this repository so the robot and a future multi-persona app share ONE
+ * implementation instead of two that drift.
+ *
+ * Step 1 of the migration: the core is wired but not yet load-bearing. The
+ * historical modules (`personas/`, `relationship-state.ts`, `reply-augment.ts`)
+ * stay exactly where they are, and this adapter is **opt-in** with
+ * `CODEBUDDY_COMPANION_CORE=true`. Unset ⇒ every call here delegates to the
+ * historical path and the behaviour is byte-identical (asserted by tests).
+ *
+ * The package is loaded **dynamically**, only once the flag is on. A published
+ * install that does not carry it therefore never resolves it, and a missing or
+ * broken core falls back to the historical path with a single warning rather
+ * than taking the companion down.
+ *
+ * @module companion/core-adapter
+ */
+import type * as CompanionCore from '@phuetz/companion-core';
+import type { CompanionPersonaProfile } from './personas/types.js';
+import { type RelationalSignal, type RelationshipState } from './relationship-state.js';
+import { type LimitsVerdict } from './reply-augment.js';
+type CoreModule = typeof CompanionCore;
+/** True when the operator opted into routing through the extracted core. */
+export declare function companionCoreEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Load the core once. Returns null when the flag is off, when the package is
+ * absent, or when it failed to load — the caller then keeps the historical path.
+ */
+export declare function loadCompanionCore(env?: NodeJS.ProcessEnv): Promise<CoreModule | null>;
+/** Test seam: drop the memoized module and the failure latch. */
+export declare function resetCompanionCoreCache(): void;
+/**
+ * The active persona profile, routed through the core's Zod schema when the flag
+ * is on. The core adds a `locale`; the profile handed back to callers is the
+ * repository's own object, so pools and prompts are unchanged either way.
+ */
+export declare function resolveCompanionPersonaViaCore(env?: NodeJS.ProcessEnv): Promise<CompanionPersonaProfile | null>;
+/**
+ * Validate a persona profile against the core schema. Returns the issues rather
+ * than throwing, so a host can surface them in a doctor command.
+ */
+export declare function validateCompanionPersona(profile: unknown, env?: NodeJS.ProcessEnv): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    issues: string[];
+}>;
+/** Trait drift, routed through the core when the flag is on. Same numbers. */
+export declare function evolveTraitsViaCore(state: RelationshipState, signal: RelationalSignal, env?: NodeJS.ProcessEnv): Promise<RelationshipState>;
+/**
+ * The output limits contract. The core has no environment gate, so the persona
+ * gate is applied here — off, or outside the copine persona, the reply is
+ * returned untouched exactly as before.
+ */
+export declare function applyLimitsContractViaCore(output: string, opts?: {
+    heard?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<LimitsVerdict>;
+export {};

package/dist/companion/core-adapter.js

@@ -0,0 +1,111 @@
+/**
+ * Bridge to `@phuetz/companion-core` — the portable relational core extracted
+ * from this repository so the robot and a future multi-persona app share ONE
+ * implementation instead of two that drift.
+ *
+ * Step 1 of the migration: the core is wired but not yet load-bearing. The
+ * historical modules (`personas/`, `relationship-state.ts`, `reply-augment.ts`)
+ * stay exactly where they are, and this adapter is **opt-in** with
+ * `CODEBUDDY_COMPANION_CORE=true`. Unset ⇒ every call here delegates to the
+ * historical path and the behaviour is byte-identical (asserted by tests).
+ *
+ * The package is loaded **dynamically**, only once the flag is on. A published
+ * install that does not carry it therefore never resolves it, and a missing or
+ * broken core falls back to the historical path with a single warning rather
+ * than taking the companion down.
+ *
+ * @module companion/core-adapter
+ */
+import { isCopinePersona, resolveCompanionPersona } from './personas/index.js';
+import { evolveTraits, } from './relationship-state.js';
+import { applyLimitsContract, LIMITS_REPAIRS } from './reply-augment.js';
+import { logger } from '../utils/logger.js';
+let cached = null;
+let loadFailed = false;
+/** True when the operator opted into routing through the extracted core. */
+export function companionCoreEnabled(env = process.env) {
+    const raw = (env.CODEBUDDY_COMPANION_CORE ?? '').trim().toLowerCase();
+    return raw === 'true' || raw === '1' || raw === 'yes' || raw === 'on';
+}
+/**
+ * Load the core once. Returns null when the flag is off, when the package is
+ * absent, or when it failed to load — the caller then keeps the historical path.
+ */
+export async function loadCompanionCore(env = process.env) {
+    if (!companionCoreEnabled(env))
+        return null;
+    if (cached)
+        return cached;
+    if (loadFailed)
+        return null;
+    try {
+        cached = (await import('@phuetz/companion-core'));
+        return cached;
+    }
+    catch (error) {
+        loadFailed = true;
+        logger.warn(`[companion-core] paquet indisponible, repli sur le chemin historique : ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/** Test seam: drop the memoized module and the failure latch. */
+export function resetCompanionCoreCache() {
+    cached = null;
+    loadFailed = false;
+}
+/**
+ * The active persona profile, routed through the core's Zod schema when the flag
+ * is on. The core adds a `locale`; the profile handed back to callers is the
+ * repository's own object, so pools and prompts are unchanged either way.
+ */
+export async function resolveCompanionPersonaViaCore(env = process.env) {
+    const historical = resolveCompanionPersona(env);
+    const core = await loadCompanionCore(env);
+    if (!core || !historical)
+        return historical;
+    const validated = core.safeLoadPersonaProfile(historical);
+    if (!validated.ok) {
+        logger.warn(`[companion-core] profil « ${historical.id} » refusé : ${validated.issues.join(' ; ')}`);
+        return historical;
+    }
+    return historical;
+}
+/**
+ * Validate a persona profile against the core schema. Returns the issues rather
+ * than throwing, so a host can surface them in a doctor command.
+ */
+export async function validateCompanionPersona(profile, env = process.env) {
+    const core = await loadCompanionCore(env);
+    if (!core)
+        return { ok: true };
+    const result = core.safeLoadPersonaProfile(profile);
+    return result.ok ? { ok: true } : { ok: false, issues: result.issues };
+}
+/** Trait drift, routed through the core when the flag is on. Same numbers. */
+export async function evolveTraitsViaCore(state, signal, env = process.env) {
+    const core = await loadCompanionCore(env);
+    if (!core)
+        return evolveTraits(state, signal);
+    return core.evolveRelationship(state, signal);
+}
+/**
+ * The output limits contract. The core has no environment gate, so the persona
+ * gate is applied here — off, or outside the copine persona, the reply is
+ * returned untouched exactly as before.
+ */
+export async function applyLimitsContractViaCore(output, opts = {}) {
+    const env = opts.env ?? process.env;
+    const core = await loadCompanionCore(env);
+    if (!core)
+        return applyLimitsContract(output, opts);
+    if (!isCopinePersona(env))
+        return { text: output };
+    // Le paquet décide QUEL motif est refusé ; la phrase de réparation reste celle
+    // de ce dépôt, mot pour mot — d'où le verdict identique au chemin historique.
+    const verdict = core.applyLimitsContract(output, {
+        repairs: LIMITS_REPAIRS,
+        ...(opts.heard ? { heard: opts.heard } : {}),
+    });
+    return verdict.reason ? { text: verdict.text, reason: verdict.reason } : { text: verdict.text };
+}
+//# sourceMappingURL=core-adapter.js.map

package/dist/companion/crisis-safety.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Crisis safety — detect acute distress / self-harm / suicidal ideation in what the user says and
+ * steer Lisa toward a warm, resource-aware response.
+ *
+ * This is the safety layer companion apps must have and Lisa was missing: `relationship-safety.ts`
+ * guards what Lisa SAYS (no dependency pressure, no false subjective claims), but nothing looked at
+ * what the USER says for signs of a crisis. MySoulmate's personas route such moments to real help
+ * (3114, SOS Amitié, "I'm not a mental-health professional"); this ports that idea to Lisa.
+ *
+ * Design principles:
+ *   - **Fail-safe, not fail-loud.** A rare false positive just makes Lisa gently, warmly offer support
+ *     and a helpline — never harmful. A false NEGATIVE (missing a real cry for help) is the costly
+ *     error, so ambiguous first-person distress leans toward triggering.
+ *   - **Idiom-aware.** French/English hyperbole ("ce bug me tue", "je suis mort de rire", "mort de
+ *     fatigue") must NOT trigger. Patterns require genuine intent verbs, not bare "mourir"/"tuer".
+ *   - **Pure + STT-robust.** Accent-stripped, apostrophe-folded matching (same normalization family as
+ *     `reply-augment.ts`), no model call, never throws.
+ *
+ * The output is a GUIDANCE block injected with top priority into the reply system prompt — Lisa still
+ * speaks in her own warm voice; we only tell her to prioritise care + orientation for this turn.
+ *
+ * @module companion/crisis-safety
+ */
+export interface CrisisRead {
+    /** True when the utterance shows genuine acute distress / self-harm / suicidal ideation. */
+    crisis: boolean;
+    /** The matched pattern source (for logging/tests), when crisis is true. */
+    matched?: string;
+}
+/**
+ * Detect an acute-distress signal in what the user just said. Pure, STT-robust, idiom-aware.
+ * Fail-safe: precise enough to avoid idioms, but any genuine first-person ideation triggers.
+ */
+export declare function detectCrisis(heard: string): CrisisRead;
+/** True when the normalized text is a pure figurative "death/kill" idiom (no genuine ideation). */
+export declare function isCrisisIdiomOnly(heard: string): boolean;
+/**
+ * The French crisis-support resources Lisa surfaces. Kept as a constant so the exact numbers are
+ * auditable and testable (3114 = national suicide-prevention line, free, 24/7).
+ */
+export declare const CRISIS_RESOURCES_FR: string;
+/**
+ * Top-priority guidance injected into the reply system prompt when a crisis is detected. Lisa stays
+ * in her own warm voice; this only tells her to prioritise care + real-world orientation this turn.
+ * Never a script — she phrases it naturally, spoken-friendly (no lists / markdown out loud).
+ */
+export declare function crisisGuidance(): string;
+/**
+ * If `heard` shows a crisis, return the guidance block; otherwise ''. This is the one call sites use:
+ * prepend the result to the reply system prompt (empty string splices cleanly). Never throws.
+ */
+export declare function crisisGuidanceFor(heard: string): string;