---
paths:
  - proof-of-work/lib/ai/**
  - proof-of-work/app/api/ai/**
---

# AI subsystem

Scoped guidance for the AI generation subsystem (`proof-of-work/lib/ai/**` and the
generate/generations route handlers). Whole-repo rules live in `AGENTS.md`.

## Architecture

- `generate/route.ts` kicks off a **detached background runner** (`generationRunner.ts`)
  and returns an id; the client attaches via SSE (`generations/[id]/stream`) and can also
  poll the row. Navigating away does NOT cancel generation.
- System prompt = `systemPromptBase.ts` (output contract: JSON-only, library
  `exerciseId`s only, suggested weights) + the template's coaching prompt +
  `PROGRAM_OUTPUT_SHAPE` + library + optional history block (`historyContext.ts`).
- Multi-config: `AIConfigProfile` rows per user; `UserPreferences.activeAIConfigId`
  points at the active one and is mirrored into the legacy `ai*` columns for back-compat.

## Two generation kinds (`AIGeneration.kind`)

The runner spine is shared by two output shapes, discriminated by `AIGeneration.kind`
("program" | "workout", default "program"). The runner picks the parser by kind and
stores the JSON in the (reused) `parsedProgram` column.

- **program** (`kind: 'program'`) — `generate/route.ts` → `programSchema.ts`
  (`PROGRAM_OUTPUT_SHAPE` / `parseAIProgram`). Applied to DB rows via `apply.ts`.
  Shown in AI · History (which filters `kind: 'program'`).
- **workout** (`kind: 'workout'`) — `generate-workout/route.ts` (uses
  `workoutPrompt.ts` + `workoutSchema.ts`: `WORKOUT_OUTPUT_SHAPE` / `parseAIWorkout`).
  A single day's session. **No server-side apply**: the client (`GenerateWorkoutClient.tsx`)
  stashes the reviewed suggestion in `sessionStorage` and routes to
  `/main/workouts/new?from=ai`, where `AiWorkoutPrefill.tsx` expands it (via
  `workoutDraft.ts::buildPrefillExercises`) and pre-fills the normal `WorkoutForm` —
  nothing persists until the user saves through the regular workout path.
  **Refine = a new workout generation** seeded with the prior suggestion JSON
  (`priorWorkout` in the route body → REVISION mode in `workoutPrompt.ts`). These rows
  are ephemeral, so they're excluded from the program-shaped AI · History.
- Adding a new kind: extend the union in `KickoffOpts`, add a parser + output-shape,
  branch the parser selection in `generationRunner.ts`, and decide whether it belongs in
  History (filtered by kind).

## Provider abstraction

- Each provider yields an async iterable of `GenerateChunk` (`text` / `usage` / `done` /
  `error`); add new ones under `lib/ai/providers/` and register in `index.ts`.
  `openai.ts` exports both `openai` and `openai-compatible`, so the four provider files
  register **5** providers (`claude`, `openai`, `openai-compatible`, `gemini`, `ollama`).
- Streaming AI uses SSE; partial JSON is recovered with `lib/ai/lenientJson.ts`.
- Pricing/model menus live in `lib/ai/pricing.ts` (`PRICES`, `MODEL_MENU`) — keep them
  paired so every menu model has a price entry (there's a test enforcing this).

## SSRF / provider-URL safety

- Any `fetch` to a user-supplied provider base URL MUST go through
  `assertSafeProviderUrl` (`lib/ai/safeUrl.ts`) first — it enforces http(s) and blocks
  link-local/cloud-metadata (169.254/16, fe80::/10) + unspecified. **Private-LAN +
  loopback are allowed on purpose** (reaching `ollama.startos`/LAN gateways is the
  feature). Currently wired into `providers/ollama.ts`, the `openai-compatible` path in
  `providers/openai.ts` (NOT the fixed `api.openai.com` path), and the `ai/ollama/models`
  probe. Add the guard to any new user-URL fetch path.
- Custom-URL providers (those with `requiresBaseUrl`: ollama, openai-compatible) are
  **admin-only** — `isCustomUrlProvider` gates `ai/configs` POST + `[id]` PATCH + `ai/test`,
  and `ai/ollama/models` is fully admin-only. The Settings UI hides them from non-admins.
  This is a second defense layer on top of the IP block; keep both when adding routes.