merge: W7 coach memory, reminders, action cards into v1.22

This commit is contained in:
Marc-André Bombeck committed 2026-06-27 13:39:45 +02:00
commit e2c6e46f2a
33 files changed
+3913 -5

No files matched your search

@@ -0,0 +1,177 @@
/**
* v1.22 (B2) — Coach episodic reminder capture: grammar + sentinel + write.
*
* Covers the closed `when` grammar (ISO date / relative / context cue / reject),
* the `---REMEMBER---` strip (capture, recall-only note, malformed drop, prose
* preserved), and the cap-aware capture write.
*/
import { describe, it, expect, vi } from "vitest";
vi.mock("@/lib/db", () => ({ prisma: {} }));
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
vi.mock("../bytes-codec", () => ({
encryptToBytes: (s: string) => new Uint8Array(Buffer.from(`enc:${s}`)),
}));
import {
resolveWhenGrammar,
parseRememberSentinel,
captureReminderFromSentinel,
MAX_REMINDERS_PER_USER,
} from "../reminders";
const NOW = new Date("2026-06-27T12:00:00.000Z");
describe("resolveWhenGrammar", () => {
it("parses an ISO date into a date trigger at 09:00 UTC", () => {
const r = resolveWhenGrammar("2026-07-11", NOW);
expect(r).toEqual({
triggerKind: "date",
dueAt: new Date("2026-07-11T09:00:00.000Z"),
contextCue: null,
});
});
it("parses a relative +Nd / +Nw offset from now", () => {
expect(resolveWhenGrammar("+14d", NOW)?.dueAt).toEqual(
new Date("2026-07-11T12:00:00.000Z"),
);
expect(resolveWhenGrammar("+2w", NOW)?.dueAt).toEqual(
new Date("2026-07-11T12:00:00.000Z"),
);
});
it("parses a context cue into a context trigger (no dueAt)", () => {
expect(resolveWhenGrammar("NEXT_BP_LOGGED", NOW)).toEqual({
triggerKind: "context",
dueAt: null,
contextCue: "NEXT_BP_LOGGED",
});
});
it("rejects an unknown / out-of-bounds token", () => {
expect(resolveWhenGrammar("someday", NOW)).toBeNull();
expect(resolveWhenGrammar("+0d", NOW)).toBeNull();
expect(resolveWhenGrammar("+9999d", NOW)).toBeNull();
expect(resolveWhenGrammar("NEXT_MOON", NOW)).toBeNull();
});
});
describe("parseRememberSentinel", () => {
it("captures note + when + metric and strips the block from the prose", () => {
const raw = `Got it — I'll bring that up around the 11th.
---REMEMBER---
note: revisit the evening-walk idea for your sleep
when: 2026-07-11
metric: SLEEP
---END---`;
const r = parseRememberSentinel(raw, NOW);
expect(r.malformed).toBe(false);
expect(r.prose).toBe("Got it — I'll bring that up around the 11th.");
expect(r.reminder?.note).toBe(
"revisit the evening-walk idea for your sleep",
);
expect(r.reminder?.metric).toBe("SLEEP");
expect(r.reminder?.trigger?.dueAt).toEqual(
new Date("2026-07-11T09:00:00.000Z"),
);
});
it("captures a recall-only note when `when` is omitted", () => {
const raw = `Noted.
---REMEMBER---
note: you wanted to discuss your labs
---END---`;
const r = parseRememberSentinel(raw, NOW);
expect(r.malformed).toBe(false);
expect(r.reminder?.note).toBe("you wanted to discuss your labs");
expect(r.reminder?.trigger).toBeNull();
});
it("drops the block (malformed) on a missing note or an invalid when, keeping prose", () => {
const noNote = parseRememberSentinel(
"Sure.\n---REMEMBER---\nwhen: 2026-07-11\n---END---",
NOW,
);
expect(noNote.reminder).toBeNull();
expect(noNote.malformed).toBe(true);
expect(noNote.prose).toBe("Sure.");
const badWhen = parseRememberSentinel(
"Sure.\n---REMEMBER---\nnote: x\nwhen: someday\n---END---",
NOW,
);
expect(badWhen.reminder).toBeNull();
expect(badWhen.malformed).toBe(true);
// The raw marker is never left in the prose.
expect(badWhen.prose).not.toContain("REMEMBER");
});
it("returns the prose untouched when no block is present", () => {
const r = parseRememberSentinel("just a normal reply", NOW);
expect(r).toEqual({
prose: "just a normal reply",
reminder: null,
malformed: false,
});
});
});
describe("captureReminderFromSentinel", () => {
function db(count: number) {
return {
coachReminder: {
count: vi.fn(async () => count),
create: vi.fn(async () => ({ id: "r1" })),
},
};
}
it("writes an active reminder field-by-field with source sentinel", async () => {
const d = db(0);
const id = await captureReminderFromSentinel({
userId: "u1",
conversationId: "c1",
parsed: {
note: "revisit sleep",
trigger: {
triggerKind: "date",
dueAt: new Date("2026-07-11T09:00:00.000Z"),
contextCue: null,
},
metric: "SLEEP",
},
db: d as never,
});
expect(id).toBe("r1");
const createArgs = d.coachReminder.create.mock.calls[0] as unknown as [
{
data: {
userId: string;
status: string;
source: string;
sourceConversationId: string;
metric: string;
};
},
];
const data = createArgs[0].data;
expect(data.userId).toBe("u1");
expect(data.status).toBe("active");
expect(data.source).toBe("sentinel");
expect(data.sourceConversationId).toBe("c1");
expect(data.metric).toBe("SLEEP");
});
it("refuses the write once the per-user cap is reached", async () => {
const d = db(MAX_REMINDERS_PER_USER);
const id = await captureReminderFromSentinel({
userId: "u1",
conversationId: "c1",
parsed: { note: "x", trigger: null, metric: null },
db: d as never,
});
expect(id).toBeNull();
expect(d.coachReminder.create).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,94 @@
/**
* v1.22 (F6) — generalised confirm-card sentinel parse.
*
* Covers the CLOSED allowlist (checkup.create / reminder.note), the
* field-by-field resolution, and the safety property that an unknown action
* type or a malformed block yields NO action (never auto-applies, never mints
* an arbitrary entity) while the prose is preserved and the raw marker stripped.
*/
import { describe, it, expect } from "vitest";
import {
parseSuggestAction,
isSuggestedActionType,
isCheckupIntervalId,
} from "../suggest-action";
describe("parseSuggestAction", () => {
it("resolves a checkup.create action with a closed interval id", () => {
const raw = `You might add an annual panel.
---SUGGEST-ACTION---
action: checkup.create
label: Annual blood panel
interval: yearly
---END---`;
const r = parseSuggestAction(raw);
expect(r.malformed).toBe(false);
expect(r.prose).toBe("You might add an annual panel.");
expect(r.action?.actionType).toBe("checkup.create");
expect(r.action?.summary).toBe("Annual blood panel");
expect(r.action?.params).toEqual({
actionType: "checkup.create",
label: "Annual blood panel",
interval: "yearly",
});
});
it("resolves a reminder.note action with the closed when grammar token", () => {
const raw = `---SUGGEST-ACTION---
action: reminder.note
note: revisit the evening-walk effect on sleep
when: +14d
metric: SLEEP
---END---`;
const r = parseSuggestAction(raw);
expect(r.action?.params).toEqual({
actionType: "reminder.note",
note: "revisit the evening-walk effect on sleep",
when: "+14d",
metric: "SLEEP",
});
});
it("drops an unknown / off-allowlist action type (no entity, prose kept)", () => {
const raw = `ok.
---SUGGEST-ACTION---
action: medication.create
label: start a new drug
interval: monthly
---END---`;
const r = parseSuggestAction(raw);
expect(r.action).toBeNull();
expect(r.malformed).toBe(true);
expect(r.prose).toBe("ok.");
expect(r.prose).not.toContain("SUGGEST-ACTION");
});
it("drops a checkup with an unknown interval id", () => {
const raw = `---SUGGEST-ACTION---
action: checkup.create
label: x
interval: hourly
---END---`;
const r = parseSuggestAction(raw);
expect(r.action).toBeNull();
expect(r.malformed).toBe(true);
});
it("passes the prose through untouched when no block is present", () => {
const r = parseSuggestAction("a normal reply");
expect(r).toEqual({
prose: "a normal reply",
action: null,
malformed: false,
});
});
it("closed-allowlist guards reject anything off-list", () => {
expect(isSuggestedActionType("checkup.create")).toBe(true);
expect(isSuggestedActionType("reminder.note")).toBe(true);
expect(isSuggestedActionType("medication.create")).toBe(false);
expect(isCheckupIntervalId("yearly")).toBe(true);
expect(isCheckupIntervalId("hourly")).toBe(false);
});
});
+29 -2
View File
@@ -39,7 +39,12 @@ import {
} from "@/lib/insights/narrative/period-narrative";
import type { BaselineProfile } from "@/lib/insights/derived";
import { buildCoachFactsBlock } from "./facts";
import { buildCoachPlansBlock, type CoachPlanInjectEntry } from "./plans";
import {
buildCoachPlansBlock,
buildCoachRemindersBlock,
type CoachPlanInjectEntry,
type CoachReminderInjectEntry,
} from "./plans";
/** The period the rolling profile recalls — month is the high-signal beat. */
const MEMORY_PERIOD: NarrativePeriod = "month";
@@ -85,6 +90,13 @@ export interface CoachMemoryBlock {
* still awaiting the user's confirmation. Absent when none.
*/
plans?: CoachPlanInjectEntry[];
/**
* v1.22 (B2/B3) — the user's near/overdue or already-surfaced episodic
* reminders ("remind me about X"), top-N soonest first. Lets the Coach
* reference them unprompted next turn — the progress-reflection reflex.
* Absent when none.
*/
reminders?: CoachReminderInjectEntry[];
}
/** Pull the headline + driver recall off the latest period narrative. */
@@ -185,11 +197,25 @@ export async function buildCoachMemoryBlock(
plans = undefined;
}
// Sub-source 5 (v1.22 B2/B3): the user's near/overdue or surfaced episodic
// reminders. Fault-isolated like the others; the read half lives in plans.ts
// alongside the plan-injection block.
let reminders: CoachReminderInjectEntry[] | undefined;
try {
const remindersBlock = await buildCoachRemindersBlock(userId, now);
if (remindersBlock && remindersBlock.reminders.length > 0) {
reminders = remindersBlock.reminders;
}
} catch {
reminders = undefined;
}
if (
!priorNarrative &&
Object.keys(trendMemory).length === 0 &&
!facts &&
!plans
!plans &&
!reminders
) {
return null;
}
@@ -198,5 +224,6 @@ export async function buildCoachMemoryBlock(
if (priorNarrative) block.priorNarrative = priorNarrative;
if (facts) block.facts = facts;
if (plans) block.plans = plans;
if (reminders) block.reminders = reminders;
return block;
}
+93
View File
@@ -39,6 +39,7 @@ import { runStatusCompletion } from "@/lib/insights/status-provider";
import { annotate } from "@/lib/logging/context";
import { decryptFromBytes, encryptToBytes } from "./bytes-codec";
import { REMINDERS_INJECT_TOP_N } from "./reminders";
/** App-side closed status enum (NOT a DB enum — matches the schema column). */
export const COACH_PLAN_STATUSES = [
@@ -60,6 +61,7 @@ const RECENT_TURNS_CAP = 10;
type RunCompletionFn = typeof runStatusCompletion;
type PrismaLike = Pick<typeof prisma, "coachPlan" | "coachConversation">;
type ReminderPrismaLike = Pick<typeof prisma, "coachReminder">;
interface ExtractOpts {
runCompletion?: RunCompletionFn;
@@ -462,3 +464,94 @@ export async function buildCoachPlansBlock(
if (plans.length === 0) return null;
return { plans };
}
// ---------------------------------------------------------------------------
// v1.22 (B2/B3) — episodic reminder recall sub-block
// ---------------------------------------------------------------------------
/**
* How far ahead of `now` an active reminder enters the recall block. A
* reminder due within this horizon (or already overdue) is "near" enough that
* the Coach should reference it unprompted on the next message; a reminder due
* far in the future stays dormant until its window approaches.
*/
const REMINDER_RECALL_HORIZON_DAYS = 3;
const REMINDER_RECALL_HORIZON_MS = REMINDER_RECALL_HORIZON_DAYS * 86_400_000;
/** One reminder as the snapshot recall block carries it. */
export interface CoachReminderInjectEntry {
note: string;
metric?: string;
/** ISO due moment, when the reminder is date-triggered. */
dueAt?: string;
/** Lifecycle status (active | due | surfaced) for the model's framing. */
status: string;
}
interface InjectReminderRow {
noteEncrypted: Uint8Array;
metric: string | null;
dueAt: Date | null;
status: string;
updatedAt: Date;
}
/**
* Build the recall sub-block: the reminders the Coach should reference next
* time — anything already `due`/`surfaced` (the sweep flipped it and the user
* has not resolved it) plus `active` reminders whose `dueAt` is near or overdue.
* A recall-only `active` note (no `dueAt`) is also surfaced so the Coach honours
* the user's explicit "remember this" even without a fire moment. Decrypt is
* fault-isolated — an undecryptable row is skipped, never thrown. Returns `null`
* when the user has nothing to recall.
*
* This is the read half of the episodic memory type, mirroring
* `buildCoachPlansBlock`; the write half lives in `reminders.ts`.
*/
export async function buildCoachRemindersBlock(
userId: string,
now: Date,
opts?: { prisma?: ReminderPrismaLike },
): Promise<{ reminders: CoachReminderInjectEntry[] } | null> {
const db = opts?.prisma ?? prisma;
const horizon = new Date(now.getTime() + REMINDER_RECALL_HORIZON_MS);
const rows = (await db.coachReminder.findMany({
where: {
userId,
deletedAt: null,
OR: [
// Already surfaced by the sweep and not yet resolved.
{ status: { in: ["due", "surfaced"] } },
// Active + near/overdue date trigger.
{ status: "active", dueAt: { lte: horizon } },
// Active recall-only note (no fire moment) — honour the explicit ask.
{ status: "active", dueAt: null },
],
},
// Soonest-due first, then most-recently touched.
orderBy: [{ dueAt: "asc" }, { updatedAt: "desc" }],
take: REMINDERS_INJECT_TOP_N * 3,
select: {
noteEncrypted: true,
metric: true,
dueAt: true,
status: true,
updatedAt: true,
},
})) as InjectReminderRow[];
const reminders: CoachReminderInjectEntry[] = [];
for (const r of rows) {
if (reminders.length >= REMINDERS_INJECT_TOP_N) break;
const note = decryptOrNull(r.noteEncrypted);
if (note === null) continue;
const entry: CoachReminderInjectEntry = { note, status: r.status };
if (r.metric) entry.metric = r.metric;
if (r.dueAt) entry.dueAt = r.dueAt.toISOString();
reminders.push(entry);
}
if (reminders.length === 0) return null;
return { reminders };
}
+319
View File
@@ -0,0 +1,319 @@
/**
* 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;
export type CoachReminderStatus = (typeof COACH_REMINDER_STATUSES)[number];
/** 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];
/** Provenance of a reminder row (matches the schema `source` column). */
export const COACH_REMINDER_SOURCES = [
"sentinel",
"extractor",
"manual",
"action",
] as const;
export type CoachReminderSource = (typeof COACH_REMINDER_SOURCES)[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: <kurz, in der Formulierung der Person, worum es geht>
when: <optional: ISO-Datum JJJJ-MM-TT | relativ +Nd / +Nw | ein Kontext-Cue: NEXT_BP_LOGGED, NEXT_WEIGHT_LOGGED, NEXT_SLEEP_LOGGED, NEXT_APP_OPEN>
metric: <optional, z. B. SLEEP, BLOOD_PRESSURE>
---END---
Erfinde NIEMALS eine Erinnerung, um die die Person nicht ausdrücklich gebeten hat. Bestätige kurz im Fließtext ("Notiert — ich komme darauf zurück."). 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: <short, in the user's own framing, what to bring back>
when: <optional: ISO date YYYY-MM-DD | relative +Nd / +Nw | a context cue: NEXT_BP_LOGGED, NEXT_WEIGHT_LOGGED, NEXT_SLEEP_LOGGED, NEXT_APP_OPEN>
metric: <optional, e.g. SLEEP, BLOOD_PRESSURE>
---END---
NEVER invent a reminder the user did not explicitly ask for. Acknowledge briefly in prose ("Got it — I'll bring that up again."). Omit "when" if no time was stated.`;
}
type PrismaLike = Pick<typeof prisma, "coachReminder">;
/**
* Persist a sentinel-captured reminder field-by-field (no mass assignment),
* always `status: "active"` (the user explicitly asked — no confirm gate). 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<string | null> {
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,
status: "active",
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;
}
+10
View File
@@ -2558,11 +2558,21 @@ function degradeToBudget(
block && Array.isArray(block.plans) && block.plans.length > 0
? block.plans
: null;
// v1.22 (B2/B3) — the episodic reminders survive the drop alongside
// facts/plans: they are the user's own "remember this" asks, tiny by
// construction (top-6, ≤280 chars each), and shedding them would make the
// Coach forget a reminder on exactly the data-heavy accounts that hit the
// char cap.
const reminders =
block && Array.isArray(block.reminders) && block.reminders.length > 0
? block.reminders
: null;
const survivors: Record<string, unknown> = {
omitted: "trimmed for prompt budget",
};
if (facts) survivors.facts = facts;
if (plans) survivors.plans = plans;
if (reminders) survivors.reminders = reminders;
snapshot[key] = survivors;
return true;
};
+252
View File
@@ -0,0 +1,252 @@
/**
* v1.22 (F6) — generalised inline "confirm → apply" Coach action cards.
*
* The propose→confirm moat already ships for ONE action type — the cadence
* reminder (`suggest-reminder.ts` CADENCE_CATALOG → `suggestion` SSE frame →
* `reminder-suggestion-card.tsx` → `POST /api/coach/reminder-suggestions`).
* This module generalises it: the Coach may append a `---SUGGEST-ACTION---`
* block naming ONE action type from a CLOSED allowlist plus bounded,
* server-resolvable params. The route strips it, validates it, and emits an
* additive `suggestedAction` SSE frame the client renders as a one-tap confirm
* card. Confirm POSTs to `POST /api/coach/suggested-actions`, which builds the
* entity FIELD-BY-FIELD from a server-resolved spec.
*
* HARD SAFETY (matches the design §3.6):
* - NEVER auto-apply. The frame is additive; the prose stands alone if
* ignored. Only the user's confirm tap creates anything.
* - CLOSED allowlist only. The model names an action type + bounded params;
* it can never mint an arbitrary entity or widen a schedule (the interval
* is a closed preset id resolved on the server, never a free rrule).
* - NO clinical / medication changes via this path. The allowlist excludes
* anything that creates/edits a medication, a dose, or a clinical target.
*
* Defence-in-depth mirrors the other sentinels: a byte cap, a single block, the
* fields validated, a malformed block dropped (the user never sees the marker).
*/
/**
* The system-prompt clause teaching the model to emit `---SUGGEST-ACTION---`.
* Appended to the assembled Coach system prompt in the chat route. Provider-
* neutral; EN + DE only. Names ONLY the closed allowlist — never medication or
* clinical changes.
*/
export function buildSuggestActionAddendum(locale: string | undefined): string {
if (locale?.toLowerCase().startsWith("de")) {
return `WENN eine deiner Empfehlungen mit einem Tipp umsetzbar ist, biete sie als bestätigbare Aktion an — hänge GENAU EINEN Block ans Ende deiner Antwort. NUR diese geschlossene Liste, NIEMALS Medikamente oder klinische Ziele:
---SUGGEST-ACTION---
action: checkup.create # eine Vorsorge-/Check-up-Erinnerung
label: <kurzer Titel, z. B. Jährliches Blutbild>
interval: <yearly | halfYearly | quarterly | monthly>
---END---
oder
---SUGGEST-ACTION---
action: reminder.note # eine Erinnerung, auf etwas zurückzukommen
note: <kurz, worum es geht>
when: <optional: ISO-Datum | +Nd / +Nw | NEXT_BP_LOGGED …>
metric: <optional>
---END---
Wende NIEMALS etwas selbst an — die Person bestätigt mit einem Tipp. Schlage höchstens eine Aktion pro Antwort vor und nur, wenn sie klar hilfreich ist.`;
}
return `WHEN one of your recommendations is actionable with a reminder, offer it as a confirmable action — append EXACTLY ONE block at the end of your reply. ONLY this closed allowlist, NEVER a medication or clinical target:
---SUGGEST-ACTION---
action: checkup.create # a preventive-care / check-up reminder
label: <short title, e.g. Annual blood panel>
interval: <yearly | halfYearly | quarterly | monthly>
---END---
or
---SUGGEST-ACTION---
action: reminder.note # a reminder to revisit something
note: <short, what to bring back>
when: <optional: ISO date | +Nd / +Nw | NEXT_BP_LOGGED …>
metric: <optional>
---END---
NEVER apply anything yourself — the user confirms with a tap. Suggest at most one action per reply, and only when it is clearly helpful.`;
}
const OPEN_SENTINEL = "---SUGGEST-ACTION---";
const CLOSE_SENTINEL = "---END---";
const SENTINEL_BYTE_CAP = 1024;
/** The CLOSED action-type allowlist. NEVER add a clinical / medication type. */
export const SUGGESTED_ACTION_TYPES = [
"checkup.create",
"reminder.note",
] as const;
export type SuggestedActionType = (typeof SUGGESTED_ACTION_TYPES)[number];
export function isSuggestedActionType(v: string): v is SuggestedActionType {
return (SUGGESTED_ACTION_TYPES as readonly string[]).includes(v);
}
/** Field caps shared with the route Zod gate. */
export const CHECKUP_LABEL_MAX_CHARS = 120;
export const ACTION_NOTE_MAX_CHARS = 280;
export const ACTION_METRIC_MAX_CHARS = 60;
/**
* Closed cadence catalog for `checkup.create`. The model names ONLY a preset
* id; the server owns the RRULE so the model cannot mint an arbitrary schedule.
* A preventive-care item is, by nature, infrequent — the set is deliberately
* coarse (monthly at the tightest).
*/
export const CHECKUP_INTERVAL_CATALOG: Readonly<
Record<string, { id: string; rrule: string; labelKey: string }>
> = Object.freeze({
yearly: {
id: "yearly",
rrule: "FREQ=YEARLY;INTERVAL=1",
labelKey: "coach.suggestedAction.interval.yearly",
},
halfYearly: {
id: "halfYearly",
rrule: "FREQ=MONTHLY;INTERVAL=6",
labelKey: "coach.suggestedAction.interval.halfYearly",
},
quarterly: {
id: "quarterly",
rrule: "FREQ=MONTHLY;INTERVAL=3",
labelKey: "coach.suggestedAction.interval.quarterly",
},
monthly: {
id: "monthly",
rrule: "FREQ=MONTHLY;INTERVAL=1",
labelKey: "coach.suggestedAction.interval.monthly",
},
});
export type CheckupIntervalId = keyof typeof CHECKUP_INTERVAL_CATALOG;
export function isCheckupIntervalId(v: string): v is CheckupIntervalId {
return Object.prototype.hasOwnProperty.call(CHECKUP_INTERVAL_CATALOG, v);
}
/**
* The validated params the SSE frame carries + the confirm route accepts. A
* discriminated union keyed on `actionType`, so the route switch is exhaustive.
*/
export type SuggestedActionParams =
| { actionType: "checkup.create"; label: string; interval: CheckupIntervalId }
| {
actionType: "reminder.note";
note: string;
when?: string;
metric?: string;
};
/** The DTO the `suggestedAction` SSE frame carries (additive; older clients drop it). */
export interface CoachSuggestedAction {
actionType: SuggestedActionType;
/** Plain-text preview of what will be created (the model's own content). */
summary: string;
/** i18n key for the action-type heading on the card. */
titleKey: string;
params: SuggestedActionParams;
}
const METRIC_KEY_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
export interface SuggestActionParseResult {
prose: string;
action: CoachSuggestedAction | null;
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()
.replace(/\s+#.*$/, "")
.replace(/^["'`]|["'`]$/g, "")
.trim();
if (value) return value;
}
return null;
}
/** Resolve the per-action params from the block body; null = drop (malformed). */
function resolveActionParams(
actionType: SuggestedActionType,
body: string,
): { params: SuggestedActionParams; summary: string; titleKey: string } | null {
if (actionType === "checkup.create") {
const labelRaw = fieldLine(body, "label");
const intervalRaw = fieldLine(body, "interval");
if (!labelRaw || !intervalRaw) return null;
const label = labelRaw.slice(0, CHECKUP_LABEL_MAX_CHARS).trim();
if (!label) return null;
if (!isCheckupIntervalId(intervalRaw)) return null;
return {
params: { actionType, label, interval: intervalRaw },
summary: label,
titleKey: "coach.suggestedAction.checkup.title",
};
}
// reminder.note
const noteRaw = fieldLine(body, "note");
if (!noteRaw) return null;
const note = noteRaw.slice(0, ACTION_NOTE_MAX_CHARS).trim();
if (!note) return null;
const params: SuggestedActionParams = { actionType: "reminder.note", note };
const whenRaw = fieldLine(body, "when");
if (whenRaw) params.when = whenRaw.slice(0, 32);
const metricRaw = fieldLine(body, "metric");
if (metricRaw && METRIC_KEY_RE.test(metricRaw)) {
params.metric = metricRaw.slice(0, ACTION_METRIC_MAX_CHARS).toUpperCase();
}
return {
params,
summary: note,
titleKey: "coach.suggestedAction.note.title",
};
}
/**
* Strip the `---SUGGEST-ACTION---` block and resolve it into a closed action.
* Run AFTER the other sentinel strips. An unknown action type, or a missing /
* invalid param, drops the action (`malformed: true`) while still removing the
* raw marker from the prose.
*/
export function parseSuggestAction(raw: string): SuggestActionParseResult {
if (!raw) return { prose: "", action: null, malformed: false };
const openIdx = raw.indexOf(OPEN_SENTINEL);
if (openIdx === -1) return { prose: raw, action: 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 actionRaw = fieldLine(body, "action");
if (!actionRaw || !isSuggestedActionType(actionRaw)) {
return { prose, action: null, malformed: true };
}
const resolved = resolveActionParams(actionRaw, body);
if (!resolved) return { prose, action: null, malformed: true };
return {
prose,
action: {
actionType: actionRaw,
summary: resolved.summary,
titleKey: resolved.titleKey,
params: resolved.params,
},
malformed: false,
};
}
+10
View File
@@ -8,6 +8,8 @@
*/
import { z } from "zod/v4";
import type { CoachSuggestedAction } from "./suggest-action";
/**
* Chat-message role. Stored as a free-form string column server-side
* (`coach_messages.role`) but constrained at the application layer so a
@@ -205,6 +207,7 @@ export type CoachStreamEvent =
metricSource: CoachProvenance;
}
| { type: "suggestion"; suggestion: CoachSuggestion }
| { type: "suggestedAction"; suggestedAction: CoachSuggestedAction }
| { type: "reasoning"; text: string }
| {
type: "done";
@@ -338,6 +341,13 @@ export interface CoachProvenance {
* on a conversation reload. Absent on turns that carry no suggestion.
*/
suggestion?: CoachSuggestion;
/**
* v1.22 (F6) — a generalised confirm→apply action card attached to this turn
* (`checkup.create` / `reminder.note`, closed allowlist). Persisted alongside
* the message so the card re-renders on a conversation reload. Absent on turns
* that carry no action.
*/
suggestedAction?: CoachSuggestedAction;
/**
* v1.20.0 (F1) — the retrieval-tool trace for this turn: which tools the
* Coach called and whether each found data (`present`). Metadata only — no
+2
View File
@@ -112,6 +112,8 @@ export const ENCRYPTED_COLUMNS: readonly EncryptedColumn[] = [
{ model: "CoachPlan", field: "ifCueEncrypted", kind: "bytes" },
{ model: "CoachPlan", field: "thenActionEncrypted", kind: "bytes" },
{ model: "CoachPlan", field: "targetEncrypted", kind: "bytes" },
// v1.22 (B2/B6) — Coach episodic reminder free-text note.
{ model: "CoachReminder", field: "noteEncrypted", kind: "bytes" },
// ───── User health profile (Bytes columns) ─────
{ model: "UserHealthProfile", field: "aboutMeEncrypted", kind: "bytes" },
@@ -0,0 +1,106 @@
/**
* v1.22 (M4) — daily Coach-reminder sweep.
*
* Covers: overdue active date-reminders flip to `due`; a passed CoachPlan
* reviewDate mints a one-off reminder from the plan's own cue→action text and
* clears the reviewDate (activating the dangling B1 column); an undecryptable
* plan is skipped (counted errored) without sinking the tick.
*/
import { describe, it, expect, vi } from "vitest";
vi.mock("@/lib/ai/coach/bytes-codec", () => ({
decryptFromBytes: (buf: Uint8Array) => {
const tag = Buffer.from(buf).toString("utf8");
if (tag === "__bad__") throw new Error("unknown key id");
return `dec:${tag}`;
},
encryptToBytes: (s: string) => new Uint8Array(Buffer.from(`enc:${s}`)),
}));
import { runCoachReminderSweep } from "../coach-reminder-sweep";
const NOW = new Date("2026-06-27T05:20:00.000Z");
function bytes(tag: string): Uint8Array {
return new Uint8Array(Buffer.from(tag, "utf8"));
}
describe("runCoachReminderSweep", () => {
it("flips overdue active date-reminders to due and mints plan-review reminders", async () => {
const prisma = {
coachReminder: {
updateMany: vi.fn(async () => ({ count: 3 })),
create: vi.fn(async () => ({ id: "r-new" })),
},
coachPlan: {
findMany: vi.fn(async () => [
{
id: "p1",
userId: "u1",
metric: "WEIGHT",
ifCueEncrypted: bytes("every morning"),
thenActionEncrypted: bytes("weigh in"),
},
]),
update: vi.fn(async () => ({})),
},
};
const summary = await runCoachReminderSweep(prisma as never, NOW);
expect(summary.remindersDue).toBe(3);
expect(summary.planReviewsMinted).toBe(1);
expect(summary.errored).toBe(0);
// The flip query is scoped to active, date-triggered, overdue rows.
const flipArgs = prisma.coachReminder.updateMany.mock
.calls[0] as unknown as [
{ where: { status: string; triggerKind: string; dueAt: unknown } },
];
const where = flipArgs[0].where;
expect(where.status).toBe("active");
expect(where.triggerKind).toBe("date");
expect(where.dueAt).toEqual({ not: null, lte: NOW });
// The minted reminder carries the plan's own prose + relatedPlanId.
const createArgs = prisma.coachReminder.create.mock.calls[0] as unknown as [
{ data: { relatedPlanId: string; source: string; status: string } },
];
const data = createArgs[0].data;
expect(data.relatedPlanId).toBe("p1");
expect(data.source).toBe("extractor");
expect(data.status).toBe("due");
// The plan's reviewDate is cleared so the review fires exactly once.
expect(prisma.coachPlan.update).toHaveBeenCalledWith({
where: { id: "p1" },
data: { reviewDate: null },
});
});
it("skips an undecryptable plan without sinking the tick", async () => {
const prisma = {
coachReminder: {
updateMany: vi.fn(async () => ({ count: 0 })),
create: vi.fn(async () => ({ id: "r-new" })),
},
coachPlan: {
findMany: vi.fn(async () => [
{
id: "p1",
userId: "u1",
metric: "SLEEP",
ifCueEncrypted: bytes("__bad__"),
thenActionEncrypted: bytes("lights out"),
},
]),
update: vi.fn(async () => ({})),
},
};
const summary = await runCoachReminderSweep(prisma as never, NOW);
expect(summary.planReviewsMinted).toBe(0);
expect(summary.errored).toBe(1);
expect(prisma.coachReminder.create).not.toHaveBeenCalled();
expect(prisma.coachPlan.update).not.toHaveBeenCalled();
});
});
+133
View File
@@ -0,0 +1,133 @@
/**
* v1.22 (B2/M4) — daily Coach-reminder sweep.
*
* The active scheduler the "remind me" complaint needs: a single indexed query
* per tick that brings a reminder back at its chosen moment. Two sources:
*
* 1. `CoachReminder` rows that are date-triggered, `active`, and whose `dueAt`
* has passed → flipped to `due` (the in-app tile + indicator read `due` /
* `surfaced`). `lastSurfacedAt` is stamped + `surfaceCount` bumped.
* 2. `CoachPlan` rows whose dangling `reviewDate` (written nowhere, read
* nowhere until now — see the design §1c) has passed and that are still
* `active` → a one-off `CoachReminder` is minted from the plan's own
* cue→action text (relatedPlanId set, source `extractor`) and the plan's
* `reviewDate` is cleared so the review fires once. This finally activates
* the column the B1 schema anticipated.
*
* In-app surfacing ONLY in this wave: push delivery + the receptivity gate (B4)
* land later. The sweep never calls a provider and never pushes — it only flips
* status + mints the plan-review reminder, both idempotent across re-fires.
*
* Context-cue reminders (`triggerKind: "context"`) are NOT evaluated here — that
* is a follow-on (F4); the column exists and capture supports it, but the date
* sweep is the high-value slice.
*/
import type { PrismaClient } from "@/generated/prisma/client";
import { decryptFromBytes, encryptToBytes } from "@/lib/ai/coach/bytes-codec";
export const COACH_REMINDER_SWEEP_QUEUE = "coach-reminder-sweep";
// Daily at 05:20 Europe/Berlin — just after the 05:15 nudge tick so both
// proactive passes run on settled overnight rows.
export const COACH_REMINDER_SWEEP_CRON = "20 5 * * *";
/** Bound the plan-review fan-out per tick so one sweep can't run unbounded. */
const PLAN_REVIEW_BATCH = 200;
export interface CoachReminderSweepSummary {
remindersDue: number;
planReviewsMinted: number;
errored: number;
}
type SweepPrisma = Pick<PrismaClient, "coachReminder" | "coachPlan">;
/**
* Run one sweep tick. Idempotent: a reminder already `due` is not re-flipped,
* and a plan whose `reviewDate` was cleared on a prior tick is not re-minted.
*/
export async function runCoachReminderSweep(
prisma: SweepPrisma,
now: Date = new Date(),
): Promise<CoachReminderSweepSummary> {
const summary: CoachReminderSweepSummary = {
remindersDue: 0,
planReviewsMinted: 0,
errored: 0,
};
// ── 1. flip overdue active date-reminders → due ──────────────
const due = await prisma.coachReminder.updateMany({
where: {
deletedAt: null,
status: "active",
triggerKind: "date",
dueAt: { not: null, lte: now },
},
data: {
status: "due",
lastSurfacedAt: now,
surfaceCount: { increment: 1 },
},
});
summary.remindersDue = due.count;
// ── 2. mint plan-review reminders for passed reviewDates ──────
const plans = await prisma.coachPlan.findMany({
where: {
deletedAt: null,
status: "active",
reviewDate: { not: null, lte: now },
},
take: PLAN_REVIEW_BATCH,
select: {
id: true,
userId: true,
metric: true,
ifCueEncrypted: true,
thenActionEncrypted: true,
},
});
for (const plan of plans) {
try {
// The note is the plan's OWN cue→action prose (the user's words), never
// fabricated. Decrypt fault-isolated — an undecryptable plan is skipped
// (its reviewDate stays so a future key fix can still surface it).
let note: string;
try {
const ifCue = decryptFromBytes(plan.ifCueEncrypted);
const thenAction = decryptFromBytes(plan.thenActionEncrypted);
note = `${ifCue} → ${thenAction}`.slice(0, 280);
} catch {
summary.errored += 1;
continue;
}
await prisma.coachReminder.create({
data: {
userId: plan.userId,
noteEncrypted: encryptToBytes(note),
metric: plan.metric,
relatedPlanId: plan.id,
triggerKind: "date",
dueAt: now,
status: "due",
source: "extractor",
lastSurfacedAt: now,
surfaceCount: 1,
},
});
// Clear the plan's reviewDate so the review fires exactly once.
await prisma.coachPlan.update({
where: { id: plan.id },
data: { reviewDate: null },
});
summary.planReviewsMinted += 1;
} catch {
summary.errored += 1;
}
}
return summary;
}
+43
View File
@@ -34,6 +34,11 @@ import {
COACH_NUDGE_CRON,
runCoachNudgeTick,
} from "@/lib/jobs/coach-nudge";
import {
COACH_REMINDER_SWEEP_QUEUE,
COACH_REMINDER_SWEEP_CRON,
runCoachReminderSweep,
} from "@/lib/jobs/coach-reminder-sweep";
import {
MEDICATION_LOW_STOCK_QUEUE,
MEDICATION_LOW_STOCK_CRON,
@@ -159,6 +164,9 @@ const allQueues = [
// v1.15.20 — proactive Coach nudge. Without this entry the daily 05:15
// schedule silently no-ops and no nudge ever fires.
COACH_NUDGE_QUEUE,
// v1.22 (M4) — daily Coach-reminder sweep. Without this entry the 05:20
// schedule silently no-ops and no "remind me" reminder ever surfaces.
COACH_REMINDER_SWEEP_QUEUE,
// v1.16.11 — daily medication low-stock pass. Without this entry the 09:00
// schedule silently no-ops and no low-stock alert ever fires.
MEDICATION_LOW_STOCK_QUEUE,
@@ -204,6 +212,10 @@ const schedules: ScheduleEntry[] = [
// the 04:45–04:55 score crons so the recovery-score trigger reads
// settled rows. Deterministic triggers only — no AI call on this path.
[COACH_NUDGE_QUEUE, COACH_NUDGE_CRON],
// v1.22 (M4) — daily 05:20 Europe/Berlin Coach-reminder sweep, just after
// the nudge tick. Flips overdue reminders to `due` + mints plan-review
// reminders from passed CoachPlan.reviewDate. In-app surface only; no push.
[COACH_REMINDER_SWEEP_QUEUE, COACH_REMINDER_SWEEP_CRON],
// v1.16.11 — medication low-stock pass at 09:00 Europe/Berlin: a
// supply alert is an errand prompt, so it fires at a time the user
// can act on it. Once daily; the per-medication stamp keeps it at
@@ -447,5 +459,36 @@ export async function registerStatusQueues(
},
);
// v1.22 (M4) — daily Coach-reminder sweep. Single-flight; flipping an overdue
// reminder to `due` and minting plan-review reminders are both idempotent
// across re-fires (an already-due reminder is not re-flipped; a plan whose
// reviewDate was cleared is not re-minted). No provider call, no push.
await boss.work(
COACH_REMINDER_SWEEP_QUEUE,
{ localConcurrency: 1 },
async () => {
await withBackgroundEvent("job.coach_reminder_sweep", async (evt) => {
try {
const summary = await runCoachReminderSweep(
getWorkerPrisma(),
new Date(),
);
evt.setBackground({
task_name: "job.coach_reminder_sweep",
result: {
reminders_due: summary.remindersDue,
plan_reviews_minted: summary.planReviewsMinted,
errored: summary.errored,
},
});
} catch (err) {
evt.setError(err);
recordError();
throw err;
}
});
},
);
return allQueues;
}
+262
View File
@@ -22,6 +22,12 @@ import { coachChatRequestSchema } from "@/lib/ai/coach/types";
import { exportSelectionSchema } from "@/lib/validations/health-record-export";
import { createShareLinkSchema } from "@/lib/validations/clinician-share-link";
import { coachReminderSuggestionActionSchema } from "@/lib/validations/coach-reminder-suggestion";
import { COACH_REMINDER_STATUSES } from "@/lib/ai/coach/reminders";
import {
coachReminderCreateSchema,
coachReminderPatchSchema,
coachSuggestedActionSchema,
} from "@/lib/validations/coach-reminder";
import { dataEnvelope, errorEnvelope, stdResponses } from "./shared";
// ── Coach cadence suggestions (v1.18.1) ──────────────────────────────
@@ -316,6 +322,70 @@ coachPlansListQuerySchema.meta({
"Optional `?status=` filter for the plans list (proposed | active | met | abandoned). Omitted returns the non-terminal set (proposed + active).",
});
// ── Coach episodic reminders (v1.22 B2/B6) ──────────────────────────────
const coachReminderItem = z
.object({
id: z.string(),
note: z
.string()
.nullable()
.describe(
"Decrypted note (the user's own framing). Null when the row's key id is no longer in the map.",
),
metric: z.string().nullable(),
triggerKind: z.enum(["date", "context"]),
dueAt: z.iso.datetime({ offset: true }).nullable(),
contextCue: z.string().nullable(),
status: z.enum(COACH_REMINDER_STATUSES),
source: z.enum(["sentinel", "extractor", "manual", "action"]),
createdAt: z.iso.datetime({ offset: true }),
updatedAt: z.iso.datetime({ offset: true }),
})
.meta({
id: "CoachReminder",
description:
"One Coach episodic reminder, decrypted server-side. The note reads null only when the encryption key id has rotated out of the map.",
});
const coachRemindersListResponse = z.object({
reminders: z
.array(coachReminderItem)
.describe(
"The caller's reminders, soonest-due first. Undecryptable rows are omitted. No `status` filter returns the non-terminal set (proposed + active + due + surfaced).",
),
});
const coachReminderCreatedResponse = z.object({
reminder: coachReminderItem,
});
const coachReminderUpdatedResponse = z.object({
reminder: coachReminderItem,
});
const coachReminderDeletedResponse = z.object({
deleted: z
.boolean()
.describe(
"True when a reminder owned by the caller was soft-deleted; false for an unknown / cross-user / already-deleted id (idempotent no-op).",
),
});
const coachSuggestedActionResultResponse = z
.object({
ok: z.literal(true),
actionType: z.enum(["checkup.create", "reminder.note"]),
reminder: z.unknown().optional(),
reminderId: z.string().optional(),
})
.meta({
id: "CoachSuggestedActionResult",
description:
"Outcome of confirming a Coach action card. `checkup.create` returns the created MeasurementReminder DTO; `reminder.note` returns the created CoachReminder id.",
});
// The request bodies carry their `.meta({ id })` from
// `@/lib/validations/coach-reminder` (single-source with the runtime parse).
// ── Coach conversation history (v1.18.0) ─────────────────────────────
// List + detail + delete surface for the Coach's persisted chat
// conversations. Bodies are stored encrypted at rest; the detail
@@ -1058,6 +1128,198 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
};
export const coachReminderPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/coach/reminders": {
get: {
tags: ["Insights"],
summary: "List the caller's Coach reminders",
description:
'v1.22 (B2/B6) — the durable "remind me about X" memory the Coach captured inline, decrypted on the fly, soonest-due first. Pass `?status=` (one status or a comma set like `due,surfaced` for the in-app tile); omitted returns the non-terminal set (proposed + active + due + surfaced). Coach-gated (`requireModuleEnabled("coach")`). Auth via cookie or Bearer; the owner is narrowed from the session. Undecryptable rows are omitted.',
parameters: [
{
name: "status",
in: "query",
required: false,
schema: { type: "string" },
description:
"Filter to one status or a comma-separated set (proposed | active | due | surfaced | done | dismissed). Omit for the non-terminal set.",
},
],
responses: {
"200": {
description: "The caller's reminders.",
content: {
"application/json": {
schema: dataEnvelope(
coachRemindersListResponse,
"CoachRemindersList",
),
},
},
},
"403": {
description: "Coach surface disabled.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
post: {
tags: ["Insights"],
summary: "Create a Coach reminder manually",
description:
"v1.22 (B6) — create a reminder from the ledger. `note` is the only writable content; `when` is the closed grammar (ISO date | +Nd / +Nw | a context cue) resolved into the trigger server-side; `metric` optional. The per-user cap returns 409 when the non-terminal set is full. Coach-gated. Auth via cookie or Bearer; the owner is narrowed from the session.",
requestBody: {
required: true,
content: {
"application/json": { schema: coachReminderCreateSchema },
},
},
responses: {
"201": {
description: "The created reminder.",
content: {
"application/json": {
schema: dataEnvelope(
coachReminderCreatedResponse,
"CoachReminderCreated",
),
},
},
},
"403": {
description: "Coach surface disabled.",
content: { "application/json": { schema: errorEnvelope } },
},
"409": {
description: "The per-user reminder cap is full.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
"/api/coach/reminders/{id}": {
patch: {
tags: ["Insights"],
summary: "Confirm or update a Coach reminder's lifecycle",
description:
"v1.22 (B6) — confirm a proposed reminder (→ active), mark it done / dismissed, or re-schedule via the closed `when` grammar (null clears the due moment). The body never carries the note text. A foreign / unknown / already-deleted id maps to 404 (never 403) so the existence channel does not leak. Coach-gated. Auth via cookie or Bearer.",
parameters: [
{
name: "id",
in: "path",
required: true,
schema: { type: "string" },
description: "Reminder id.",
},
],
requestBody: {
required: true,
content: {
"application/json": { schema: coachReminderPatchSchema },
},
},
responses: {
"200": {
description: "The reminder after the lifecycle update.",
content: {
"application/json": {
schema: dataEnvelope(
coachReminderUpdatedResponse,
"CoachReminderUpdated",
),
},
},
},
"403": {
description: "Coach surface disabled.",
content: { "application/json": { schema: errorEnvelope } },
},
"404": {
description: "Reminder not found or not owned by the caller.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
delete: {
tags: ["Insights"],
summary: "Soft-delete one Coach reminder",
description:
"v1.22 (B6) — soft-deletes a single reminder owned by the caller. An unknown / cross-user / already-deleted id is an idempotent no-op returning `{ deleted: false }`. Coach-gated. Auth via cookie or Bearer.",
parameters: [
{
name: "id",
in: "path",
required: true,
schema: { type: "string" },
description: "Reminder id.",
},
],
responses: {
"200": {
description:
"The reminder was soft-deleted (`deleted: true`) or the id matched nothing the caller owns (`deleted: false`).",
content: {
"application/json": {
schema: dataEnvelope(
coachReminderDeletedResponse,
"CoachReminderDeleted",
),
},
},
},
"403": {
description: "Coach surface disabled.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
};
export const coachSuggestedActionPaths: NonNullable<ZodOpenApiObject["paths"]> =
{
"/api/coach/suggested-actions": {
post: {
tags: ["Insights"],
summary: "Confirm a Coach action card",
description:
'v1.22 (F6) — the confirm half of the generalised propose→confirm moat. `actionType` is from the CLOSED allowlist (checkup.create | reminder.note) — NEVER a medication or clinical change. `checkup.create` builds a preventive-care Vorsorge `MeasurementReminder` (free-text label + a closed interval id resolved to an RRULE server-side); `reminder.note` builds a `CoachReminder`. Nothing is created without this explicit confirm. Coach-gated (`requireModuleEnabled("coach")`); per-user rate-limited (429). Auth via cookie or Bearer; the owner is narrowed from the session, built field-by-field — no mass assignment, no IDOR.',
requestBody: {
required: true,
content: {
"application/json": { schema: coachSuggestedActionSchema },
},
},
responses: {
"201": {
description: "The action was applied (entity created server-side).",
content: {
"application/json": {
schema: dataEnvelope(
coachSuggestedActionResultResponse,
"CoachSuggestedActionResultCreated",
),
},
},
},
"403": {
description: "Coach surface disabled.",
content: { "application/json": { schema: errorEnvelope } },
},
"409": {
description: "The per-user reminder cap is full (reminder.note).",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
};
export const coachFeedbackPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/insights/chat/messages/{id}/feedback": {
post: {
+4
View File
@@ -27,6 +27,8 @@ import {
coachFeedbackPaths,
coachPaths,
coachReminderSuggestionPaths,
coachReminderPaths,
coachSuggestedActionPaths,
} from "./coach";
import { consentPaths } from "./consent";
import { cyclePaths } from "./cycle";
@@ -62,6 +64,8 @@ export const openApiPaths: NonNullable<ZodOpenApiObject["paths"]> = {
...profilePaths,
...coachPaths,
...coachReminderSuggestionPaths,
...coachReminderPaths,
...coachSuggestedActionPaths,
...adminInvitePaths,
...coachFeedbackPaths,
...adminDiagnosticPaths,
+10
View File
@@ -32,4 +32,14 @@ export const coachKeys = {
* (`GET /api/insights/coach/seeded-question`).
*/
coachSeededQuestion: () => ["coach-seeded-question"] as const,
/**
* v1.22 (B2/B6) — the user's Coach episodic reminders (`GET /api/coach/
* reminders`). The optional `status` arg keys the in-app tile read
* (`due,surfaced`) separately from the full ledger list so the two never
* share a cache slot.
*/
coachReminders: (status?: string) =>
["coach-reminders", status ?? "all"] as const,
/** Prefix key — invalidates every `coachReminders(status)` slot at once. */
coachRemindersAll: () => ["coach-reminders"] as const,
};
+138
View File
@@ -0,0 +1,138 @@
/**
* v1.22 (B2/B6/F6) — request schemas for the Coach episodic-reminder surface
* (`/api/coach/reminders` + `/[id]`) and the generalised confirm-card endpoint
* (`/api/coach/suggested-actions`).
*
* Lives outside the route files so the OpenAPI registry can import it without
* touching the route modules (route files may only export handlers + config).
*
* No `userId` field anywhere — the owner is always narrowed from the session.
* The note free-text is the only user-writable content; everything timing is
* resolved SERVER-side from a closed grammar / catalog, so a client can never
* mint an arbitrary schedule.
*/
import { z } from "zod/v4";
import {
COACH_REMINDER_STATUSES,
REMINDER_NOTE_MAX_CHARS,
REMINDER_METRIC_MAX_CHARS,
} from "@/lib/ai/coach/reminders";
import {
SUGGESTED_ACTION_TYPES,
CHECKUP_LABEL_MAX_CHARS,
ACTION_NOTE_MAX_CHARS,
ACTION_METRIC_MAX_CHARS,
} from "@/lib/ai/coach/suggest-action";
/** A `when` grammar token: ISO date | relative +Nd/+Nw | a context cue. */
const whenToken = z.string().trim().min(1).max(32);
const metricToken = z
.string()
.trim()
.min(1)
.max(REMINDER_METRIC_MAX_CHARS)
.regex(/^[A-Za-z][A-Za-z0-9_]*$/, "metric must be a metric key");
/**
* `?status=` filter on the list endpoint. Accepts one status or a
* comma-separated set (e.g. `due,surfaced` for the in-app tile). Each token is
* validated against the closed status enum; an unknown token 422s.
*/
export const coachRemindersListQuerySchema = z.object({
status: z
.string()
.optional()
.transform((v) =>
v
? v
.split(",")
.map((s) => s.trim())
.filter(Boolean)
: undefined,
)
.pipe(z.array(z.enum(COACH_REMINDER_STATUSES)).min(1).optional()),
});
/**
* Manual create (the ledger "+ add a reminder" path). The note is the only
* free text; `when` is the closed grammar (resolved server-side into the
* trigger), `metric` optional. Strict: unknown keys 422.
*/
export const coachReminderCreateSchema = z
.object({
note: z.string().trim().min(1).max(REMINDER_NOTE_MAX_CHARS),
when: whenToken.optional(),
metric: metricToken.optional(),
})
.strict()
.meta({
id: "CoachReminderCreate",
description:
"Create a Coach reminder manually. `note` is free text (the only writable content). `when` is an optional closed grammar token — an ISO date (YYYY-MM-DD), a relative offset (+Nd / +Nw), or a context cue (NEXT_BP_LOGGED, NEXT_WEIGHT_LOGGED, NEXT_SLEEP_LOGGED, NEXT_APP_OPEN) — resolved into the trigger server-side. Omit `when` for a recall-only note. Strict: unknown keys 422.",
});
/**
* The lifecycle PATCH. `status` confirms a proposed reminder (→ active), marks
* it done / dismissed, or re-activates it. `when` optionally re-schedules
* (snooze) via the same closed grammar. The body never carries the note text,
* so a client can never overwrite a reminder's prose — only its lifecycle.
*/
export const coachReminderPatchSchema = z
.object({
status: z.enum(COACH_REMINDER_STATUSES).optional(),
when: whenToken.nullable().optional(),
})
.strict()
.refine(
(v) => v.status !== undefined || v.when !== undefined,
"At least one of status or when must be provided",
)
.meta({
id: "CoachReminderPatch",
description:
"Update a Coach reminder's lifecycle. `status` confirms (proposed → active), or marks done / dismissed. `when` re-schedules via the closed grammar (null clears the due moment). Never carries the note text. Strict: unknown keys 422.",
});
// ── Suggested-action confirm endpoint (F6) ──────────────────────────────
const checkupParams = z.object({
actionType: z.literal("checkup.create"),
label: z.string().trim().min(1).max(CHECKUP_LABEL_MAX_CHARS),
interval: z.enum(["yearly", "halfYearly", "quarterly", "monthly"]),
});
const reminderNoteParams = z.object({
actionType: z.literal("reminder.note"),
note: z.string().trim().min(1).max(ACTION_NOTE_MAX_CHARS),
when: whenToken.optional(),
metric: z
.string()
.trim()
.min(1)
.max(ACTION_METRIC_MAX_CHARS)
.regex(/^[A-Za-z][A-Za-z0-9_]*$/)
.optional(),
});
/**
* The confirm-card POST body. `actionType` names a closed-allowlist action; the
* params are a discriminated union, validated field-by-field. The server resolves
* every schedule from a closed catalog and builds the entity field-by-field —
* the client can never mint an arbitrary entity, widen a cadence, or touch a
* medication / clinical target.
*/
export const coachSuggestedActionSchema = z
.discriminatedUnion("actionType", [checkupParams, reminderNoteParams])
.meta({
id: "CoachSuggestedAction",
description:
"Confirm a Coach action card. `actionType` is from the closed allowlist (checkup.create, reminder.note); NEVER a medication or clinical change. `checkup.create` builds a preventive-care Vorsorge reminder (free-text label + a closed interval id resolved to an RRULE server-side); `reminder.note` builds a CoachReminder (note + optional closed `when` grammar + optional metric). Nothing is created without this explicit confirm.",
});
export type CoachSuggestedActionInput = z.infer<
typeof coachSuggestedActionSchema
>;
/** Stable list of confirmable action types (mirrors the lib allowlist). */
export const COACH_SUGGESTED_ACTION_TYPES = SUGGESTED_ACTION_TYPES;