Files
HealthLog/src/app/api/insights/chat/route.ts
T
Marc-André Bombeck 8fcd204172 feat(coach): seams for steps, tables, charts, method, chips and clarification
Each later piece of the dialog gets its own module, answering nothing for
now: the step builder, the table projection and chart choice, the result
ref marks, the follow-up derivation, sentinel, resolution and continue
chip, the reuse turn, the clarification parse and answer, the method line,
and the four prompt addenda. The turn pipeline calls them where they
belong, so the frames go out in the documented order (step, token,
provenance, result, cards, clarification, followUps, done) and a blocked
turn drops its tables, chips and clarification. With every piece empty
the stream and the prompt stay byte for byte as before.
2026-09-27 10:43:15 +02:00

250 lines
9.9 KiB
TypeScript

/**
* v1.4.20 — POST /api/insights/chat
*
* Streaming chat endpoint for the AI Coach. Returns Server-Sent
* Events: one `token` frame per chunk of the assistant reply, then a
* single `provenance` frame describing what the assistant could see,
* and a closing `done` frame carrying the persisted message ids.
*
* This file owns the front door: auth, the `coach` AI capability
* (refused with the capability envelope, except `no_provider`, which
* keeps its `coach.provider.none` SSE frame with `reason`), the body
* read and `coachChatRequestSchema`, the per-user rate limit, the
* locale, and the inbound refusal screen (`detectRefusal` — a refusal
* streams the localised copy and never reaches a provider).
*
* Everything after that — conversation, context, provider chain and
* consent, the capability re-check at the egress site, the budget
* reservation, the model, the reply guards, persistence and the
* streamed frames — is the turn pipeline in `src/lib/ai/coach/turn/`.
*/
import { type NextRequest } from "next/server";
import { apiHandler, requireAuth, HttpError } from "@/lib/api-handler";
import {
apiError,
apiSuccess,
apiValidationError,
sanitiseZodIssues,
} from "@/lib/api-response";
import { annotate } from "@/lib/logging/context";
import { checkRateLimit } from "@/lib/rate-limit";
import { requireAiCapability } from "@/lib/ai/capabilities/gate";
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
import { resolveServerLocale } from "@/lib/i18n/server-locale";
import { coachChatRequestSchema } from "@/lib/ai/coach/types";
import { listConversations } from "@/lib/ai/coach/persistence";
import { detectRefusal } from "@/lib/ai/coach/refusal";
import { runCoachTurn } from "@/lib/ai/coach/turn/pipeline";
import { streamProviderError, streamRefusal } from "@/lib/ai/coach/turn/sse";
/**
* The `coach` capability gate for a turn. Every unavailable reason throws the
* capability envelope (`assistant.disabled.coach`, `module.disabled`,
* `consent.ai.required`, `ai.record.notPermitted`, `ai.unavailable`), except
* `no_provider`: the streaming clients already read that one as the
* `coach.provider.none` SSE frame, so it keeps that wire and gains `reason`.
* Returns the frame to send, or null when the Coach is available.
*/
async function coachCapabilityRefusal(): Promise<Response | null> {
try {
await requireAiCapability("coach");
return null;
} catch (err) {
if (err instanceof AiUnavailableError && err.reason === "no_provider") {
annotate({ action: { name: "insights.coach.noProvider" } });
return streamProviderError({
code: "coach.provider.none",
reason: "no_provider",
});
}
throw err;
}
}
async function handleChatRequest(request: NextRequest): Promise<Response> {
const auth = await requireAuth();
// The `coach` capability, right after auth and before the rate limit and
// the body parse. It folds in what the Coach module gate, the operator
// switch and the `disableCoach` opt-out used to answer separately, plus
// provider presence and consent.
const refused = await coachCapabilityRefusal();
if (refused) return refused;
const userId = auth.user.id;
let body: unknown;
try {
const raw = await request.text();
if (raw.length > 64 * 1024) {
throw new HttpError(413, `Request body exceeds ${64 * 1024} bytes`);
}
body = JSON.parse(raw);
} catch (err) {
if (err instanceof HttpError) throw err;
throw new HttpError(400, "Invalid JSON body");
}
const parsed = coachChatRequestSchema.safeParse(body);
if (!parsed.success) {
annotate({
action: { name: "insights.coach.invalid" },
meta: { issues: parsed.error.issues.length },
});
// The dotted token keeps its place in `error`: this refusal keeps its 422,
// so moving the string would be a wire change with nothing forcing it —
// the `invalid_json` siblings moved only because their status moved to 400
// anyway. `meta.errorCode` publishes the same token in the field a machine
// code belongs in, and `details.issues` names the fields that were refused.
return apiValidationError(
"coach.request.invalid",
sanitiseZodIssues(parsed.error.issues),
422,
{ errorCode: "coach.request.invalid" },
);
}
const {
conversationId,
message,
locale: bodyLocale,
scope,
guidedQuestion,
workoutId,
followUp,
clarification,
} = parsed.data;
// Per-user request-rate ceiling layered in front of the daily budget
// gate. The budget catches the cost dimension; this catches the
// request-rate dimension (a tight loop or a stolen session can burn
// the budget in seconds while pinning Prisma + provider slots before
// the budget arithmetic catches up). 20 / minute is well outside any
// realistic interactive use — a human can't type that fast, the iOS
// client paces from user gestures.
const rl = await checkRateLimit(`coach-chat:${userId}`, 20, 60 * 1000);
if (!rl.allowed) {
annotate({
action: { name: "insights.coach.rate-limited" },
meta: { userId, resetAt: rl.resetAt },
});
return apiError("Too many Coach requests, please wait a moment", 429);
}
// v1.18.7 (SENIOR-DEV HIGH) — the daily token cap is enforced atomically
// by reserving budget right before the provider call (`reserveTurnBudget`
// in the turn pipeline), not by a read-then-write here. The old
// read-before-call gate let concurrent requests all pass the cap.
const locale = await resolveServerLocale({
request,
override: bodyLocale,
userLocale: auth.user.locale ?? null,
});
// ── Refusal short-circuit ────────────────────────────────────
// v1.16.6 — the guided-flow question rides the prompt too, so it
// runs through the same regex bank as the message. The questions
// are server-derived in the honest case; this guards the dishonest
// one (a crafted client using the field as an unchecked channel).
const refusal = detectRefusal({
message: guidedQuestion ? `${guidedQuestion}\n${message}` : message,
locale,
});
if (refusal.refuse && refusal.message) {
annotate({
action: { name: "insights.coach.refused" },
meta: { reason: refusal.reason },
});
return streamRefusal({
userId,
conversationId,
message,
refusalText: refusal.message,
});
}
// Conversation, context, chain, egress re-check, budget, and the streamed
// reply: `src/lib/ai/coach/turn/`.
return runCoachTurn({
userId,
locale,
signal: request.signal,
conversationId,
message,
scope,
guidedQuestion,
workoutId,
followUp,
clarification,
recheckCapability: coachCapabilityRefusal,
});
}
// Idempotency is intentionally NOT applied to this SSE-streaming route.
// `withIdempotency()` caches the response body via `cloned.text()` and
// replays it through `NextResponse.json(JSON.parse(...))` — that path
// turns an SSE wire format (`data: …\n\n` frames) into a `null` body
// because the cached text isn't JSON. The PWA never sets
// `Idempotency-Key` here so the bug is invisible today, but the iOS
// client does. Dedup still holds: a duplicate first-turn POST creates
// a second conversation row (cheap), and follow-up turns are gated by
// the conversationId existence check + 20-turn cap.
export const POST = apiHandler(handleChatRequest);
/** v1.30.2 (QoL H1) — hard cap on the `?q=` search string length. */
const LIST_QUERY_MAX_LEN = 200;
/**
* GET /api/insights/chat?cursor=<id>&limit=<n>&q=<text>
*
* Cursor-paginated list of the caller's conversations for the rail.
* Default limit 20, hard cap 50. Cursor is the id of the last item
* on the previous page; callers receive `{ nextCursor: null }` when
* they have reached the end.
*
* v1.30.2 (QoL H1) — optional `q` narrows the page to conversations whose
* TITLE contains the text (case-insensitive substring). This makes the
* history rail's search reach the caller's FULL conversation set instead
* of only the loaded page; the client re-issues the cursor walk under the
* new `q` whenever the search box changes rather than filtering client-
* side. Message bodies are encrypted at rest and are NOT searched — a
* decrypt-and-scan over every message would be prohibitively expensive
* for a live keystroke search and is out of scope for this pass.
*/
export const GET = apiHandler(async (request: NextRequest) => {
const auth = await requireAuth();
// Never AI-gated and never module-gated: the conversation list is the
// person's stored data. It stays readable while the Coach is unavailable
// for any reason, so every thread can be found and deleted.
const url = new URL(request.url);
const cursor = url.searchParams.get("cursor");
const limitRaw = url.searchParams.get("limit");
const limit = limitRaw ? Number.parseInt(limitRaw, 10) : undefined;
const qRaw = url.searchParams.get("q");
const q = qRaw ? qRaw.trim().slice(0, LIST_QUERY_MAX_LEN) : undefined;
const page = await listConversations({
userId: auth.user.id,
cursor,
limit: Number.isFinite(limit) ? (limit as number) : undefined,
q,
// v1.28.51 (Documents R3, Design A) — the rail now surfaces BOTH health
// threads and doc-scoped threads (the DTO carries `documentId` +
// `documentTitle` so the client badges the fenced ones). Omitting the
// `documentId` key drops the filter entirely — a union of both scopes —
// while `userId` stays narrowed from the session, so the relaxation never
// widens ownership. Doc turns still POST to the hardened document endpoint,
// never this route (see the `documentId: null` guard on the POST path).
});
annotate({
action: { name: "insights.coach.list" },
meta: { count: page.conversations.length, hasQuery: Boolean(q) },
});
return apiSuccess(page);
});
// Disable the static-page optimisation; we are always streaming.
export const dynamic = "force-dynamic";
export const runtime = "nodejs";