/** * v1.22 (B2/B6) — Coach episodic reminder memory: capture + grammar. * * The missing memory type between `CoachFact` (durable traits) and `CoachPlan` * (standing if-then habits): a time-anchored "bring this back later" intent the * user explicitly asked the Coach to remember ("remind me about my sleep next * week"). Captured inline on EVERY turn via the provider-neutral * `---REMEMBER---` sentinel — so a casual "remember this" in a SHORT chat is no * longer lost waiting for the >20-turn memory worker. * * Friction tier (matches the design): a plain note the user EXPLICITLY asked * for is captured silently as `status: "active"` — confirming "should I remember * what you just told me to remember?" is the annoying anti-pattern. The * propose→confirm rule stays where it belongs: durable traits/plans the model * INFERRED (those still flow through the extractor + a confirm card). * * Defence-in-depth mirrors `suggest-reminder.ts` / `keyvalues.ts`: a byte cap on * the payload, a single block kept, the `when` validated against a CLOSED * grammar (ISO date / relative `+Nd`-`+Nw` / a context-cue enum), the metric * validated against a loose key pattern, and a malformed block dropped (the user * never sees the raw marker). The note TEXT is encrypted via `bytes-codec.ts` * (the same AES-256-GCM codec as `CoachPlan`); `metric`, `status`, the trigger * fields and the dates stay plain so the sweep + picker filter without a decrypt. * * Server-only — the capture path reads `@/lib/db`. */ import { prisma } from "@/lib/db"; import { annotate } from "@/lib/logging/context"; import { encryptToBytes } from "./bytes-codec"; /** App-side closed status enum (NOT a DB enum — matches the schema column). */ export const COACH_REMINDER_STATUSES = [ "proposed", "active", "due", "surfaced", "done", "dismissed", ] as const; /** App-side closed trigger-kind enum (matches the schema column). */ export const COACH_REMINDER_TRIGGER_KINDS = ["date", "context"] as const; export type CoachReminderTriggerKind = (typeof COACH_REMINDER_TRIGGER_KINDS)[number]; /** * Closed context-cue enum. A `context` reminder fires when the cue is satisfied * (evaluated by the daily sweep against persisted rows). The set is deliberately * small and deterministic — "next time you log X" / "next time you open the app". */ export const COACH_REMINDER_CONTEXT_CUES = [ "NEXT_BP_LOGGED", "NEXT_WEIGHT_LOGGED", "NEXT_SLEEP_LOGGED", "NEXT_APP_OPEN", ] as const; export type CoachReminderContextCue = (typeof COACH_REMINDER_CONTEXT_CUES)[number]; /** Per-field caps (mirror the Zod gate + the prompt instruction). */ export const REMINDER_NOTE_MAX_CHARS = 280; export const REMINDER_METRIC_MAX_CHARS = 60; /** Hard cap on non-terminal reminders per user (active + proposed + due/surfaced). */ export const MAX_REMINDERS_PER_USER = 50; /** How many reminders the recall sub-block carries into the snapshot. */ export const REMINDERS_INJECT_TOP_N = 6; /** Bounds on the relative-`+Nd` grammar (1 day .. 1 year out). */ const MIN_RELATIVE_DAYS = 1; const MAX_RELATIVE_DAYS = 366; const OPEN_SENTINEL = "---REMEMBER---"; const CLOSE_SENTINEL = "---END---"; /** Hard cap on the sentinel payload before parsing (prompt-injection guard). */ const SENTINEL_BYTE_CAP = 1024; /** A loose metric key the model may name ("SLEEP", "BLOOD_PRESSURE"). */ const METRIC_KEY_RE = /^[A-Za-z][A-Za-z0-9_]*$/; const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/; const RELATIVE_RE = /^\+(\d{1,3})([dw])$/i; const MS_PER_DAY = 24 * 60 * 60 * 1000; /** The resolved trigger a valid `when` grammar maps onto. */ export interface ResolvedTrigger { triggerKind: CoachReminderTriggerKind; dueAt: Date | null; contextCue: CoachReminderContextCue | null; } function isContextCue(value: string): value is CoachReminderContextCue { return (COACH_REMINDER_CONTEXT_CUES as readonly string[]).includes(value); } /** * Resolve the closed `when` grammar into a trigger, or `null` when the token is * unparseable / out of bounds (the caller drops the reminder). Accepts: * - an ISO calendar date `YYYY-MM-DD` → date trigger, dueAt 09:00 UTC that day * - a relative `+Nd` / `+Nw` → date trigger, dueAt now + N days/weeks * - a context-cue token from the enum → context trigger, dueAt null */ export function resolveWhenGrammar( whenRaw: string, now: Date, ): ResolvedTrigger | null { const when = whenRaw.trim(); if (!when) return null; if (ISO_DATE_RE.test(when)) { // Anchor at 09:00 UTC on the named day — a deterministic, timezone-stable // fire moment for the daily sweep (push delivery + per-tz receptivity land // in a later wave; this is in-app surfacing only). const dueAt = new Date(`${when}T09:00:00.000Z`); if (Number.isNaN(dueAt.getTime())) return null; return { triggerKind: "date", dueAt, contextCue: null }; } const rel = RELATIVE_RE.exec(when); if (rel) { const n = Number.parseInt(rel[1], 10); const unit = rel[2].toLowerCase(); const days = unit === "w" ? n * 7 : n; if (days < MIN_RELATIVE_DAYS || days > MAX_RELATIVE_DAYS) return null; return { triggerKind: "date", dueAt: new Date(now.getTime() + days * MS_PER_DAY), contextCue: null, }; } const cue = when.toUpperCase(); if (isContextCue(cue)) { return { triggerKind: "context", dueAt: null, contextCue: cue }; } return null; } /** The fields a valid `---REMEMBER---` block yields. */ export interface ParsedReminderSentinel { note: string; /** Resolved trigger when a valid `when` was given; null = a recall-only note. */ trigger: ResolvedTrigger | null; metric: string | null; } export interface RememberParseResult { /** The reply with the block stripped (run AFTER the other sentinels). */ prose: string; reminder: ParsedReminderSentinel | null; /** True when an opening sentinel was seen but yielded no valid reminder. */ malformed: boolean; } /** Pull one `key: value` line out of the block body (first match wins). */ function fieldLine(body: string, key: string): string | null { for (const rawLine of body.split(/\r?\n/)) { const line = rawLine.trim(); if (!line) continue; const colon = line.indexOf(":"); if (colon < 1) continue; if (line.slice(0, colon).trim().toLowerCase() !== key) continue; const value = line .slice(colon + 1) .trim() // Strip a trailing inline comment + surrounding quotes/backticks. .replace(/\s+#.*$/, "") .replace(/^["'`]|["'`]$/g, "") .trim(); if (value) return value; } return null; } /** * Strip the `---REMEMBER---` block out of a reply and resolve its fields. Run * AFTER the KEYVALUES + SUGGEST-REMINDER strips so the prose it receives is * already free of those blocks. A missing `note`, or a present-but-unparseable * `when`, drops the reminder (`malformed: true`) while still removing the raw * marker from the prose. */ export function parseRememberSentinel( raw: string, now: Date, ): RememberParseResult { if (!raw) return { prose: "", reminder: null, malformed: false }; const openIdx = raw.indexOf(OPEN_SENTINEL); if (openIdx === -1) return { prose: raw, reminder: null, malformed: false }; const before = raw.slice(0, openIdx); const afterOpen = raw.slice(openIdx + OPEN_SENTINEL.length); const closeRel = afterOpen.indexOf(CLOSE_SENTINEL); const bodyRaw = closeRel === -1 ? afterOpen : afterOpen.slice(0, closeRel); const body = bodyRaw.length > SENTINEL_BYTE_CAP ? bodyRaw.slice(0, SENTINEL_BYTE_CAP) : bodyRaw; const after = closeRel === -1 ? "" : afterOpen.slice(closeRel + CLOSE_SENTINEL.length); const prose = `${before}${after}`.replace(/^\s+|\s+$/gu, ""); const noteRaw = fieldLine(body, "note"); if (!noteRaw) return { prose, reminder: null, malformed: true }; const note = noteRaw.slice(0, REMINDER_NOTE_MAX_CHARS).trim(); if (!note) return { prose, reminder: null, malformed: true }; // `when` is optional. Present-but-invalid is a malformed drop; absent is a // recall-only note (active, no due moment). const whenRaw = fieldLine(body, "when"); let trigger: ResolvedTrigger | null = null; if (whenRaw) { trigger = resolveWhenGrammar(whenRaw, now); if (!trigger) return { prose, reminder: null, malformed: true }; } let metric: string | null = null; const metricRaw = fieldLine(body, "metric"); if (metricRaw && METRIC_KEY_RE.test(metricRaw)) { metric = metricRaw.slice(0, REMINDER_METRIC_MAX_CHARS).toUpperCase(); } return { prose, reminder: { note, trigger, metric }, malformed: false }; } /** * The one system-prompt clause that teaches the model to emit `---REMEMBER---`. * Appended to the assembled Coach system prompt in the chat route (the canonical * system-prompt module is owned elsewhere). Provider-neutral; EN + DE only (the * Coach reasons in de/en). */ export function buildRememberAddendum(locale: string | undefined): string { if (locale?.toLowerCase().startsWith("de")) { return `WENN die Person dich bittet, dir etwas zu merken oder sie später daran zu erinnern, hänge GENAU EINEN Block ans Ende deiner Antwort: ---REMEMBER--- note: when: metric: ---END--- Erfinde NIEMALS eine Erinnerung, um die die Person nicht ausdrücklich gebeten hat. Bestätige kurz im Fließtext, dass die Erinnerung zur Bestätigung vorgemerkt ist ("Vorgemerkt — bestätige sie in den Einstellungen, dann melde ich mich."). Lass "when" weg, wenn keine Zeit genannt wurde.`; } return `WHEN the user asks you to remember something or remind them later, append EXACTLY ONE block at the end of your reply: ---REMEMBER--- note: when: metric: ---END--- NEVER invent a reminder the user did not explicitly ask for. Acknowledge briefly in prose that the reminder is queued for their confirmation ("Noted — confirm it in settings and I'll bring it back."). Omit "when" if no time was stated.`; } type PrismaLike = Pick; /** * Persist a sentinel-captured reminder field-by-field (no mass assignment), * always `status: "proposed"` — the user promotes it to `active` through the * settings confirm control (`PATCH /api/coach/reminders/[id]`), exactly like a * Coach-extracted plan. The per-user cap refuses a write once the non-terminal * set is full. Best-effort: a failure never breaks the chat turn (the caller * fires it fire-and-forget). * * Returns the created id, or `null` when the cap displaced it / a write failed. */ export async function captureReminderFromSentinel(args: { userId: string; conversationId: string; parsed: ParsedReminderSentinel; now?: Date; db?: PrismaLike; }): Promise { const db = args.db ?? prisma; const { userId, conversationId, parsed } = args; const nonTerminal = await db.coachReminder.count({ where: { userId, deletedAt: null, status: { in: ["proposed", "active", "due", "surfaced"] }, }, }); if (nonTerminal >= MAX_REMINDERS_PER_USER) { annotate({ action: { name: "coach.reminder.capture_capped" }, meta: { conversationId }, }); return null; } const created = await db.coachReminder.create({ data: { userId, noteEncrypted: encryptToBytes(parsed.note), metric: parsed.metric, triggerKind: parsed.trigger?.triggerKind ?? "date", dueAt: parsed.trigger?.dueAt ?? null, contextCue: parsed.trigger?.contextCue ?? null, // v1.30.25 — captured as `proposed`, not `active`. This was the only // model-driven write that persisted straight from model output with no // confirm step; its sibling extractors (`plans.ts`, `suggest-action.ts`) // have always written `proposed` and let the user-facing PATCH promote. // The gap mattered because a `---REMEMBER---` block is emitted by the // model, and the model reads a prompt containing document-sourced text — // so a hostile lab document could induce a reminder, and the reminder // recall block would then feed that text back into every later turn // independently of the row that seeded it. `proposed` breaks that loop // for free: `buildCoachRemindersBlock` already selects only // due / surfaced / active, so a proposed reminder never re-enters the // prompt, and the daily sweep never fires it, until the user confirms. status: "proposed", source: "sentinel", sourceConversationId: conversationId, }, select: { id: true }, }); annotate({ action: { name: "coach.reminder.captured" }, meta: { conversationId, triggerKind: parsed.trigger?.triggerKind ?? "none", hasDue: parsed.trigger?.dueAt != null, }, }); return created.id; }