feat(ai): assist ladder — free tier, Socratic mode, community handoff, self-reset (#864)

Author: thomgabriel

apps/web/src/app/api/ai/__tests__/partner-route.test.ts

@@ -40,6 +40,9 @@ export async function GET(request: NextRequest) {
     return NextResponse.json({ error: "Lesson not found" }, { status: 404 });
   }
 
-  const { paidUsed, log } = await getAssistState(user.id, lesson._id);
-  return NextResponse.json({ log, paidUsed });
+  const { counts, resetState, resetAvailableAt, log } = await getAssistState(
+    user.id,
+    lesson._id
+  );
+  return NextResponse.json({ log, counts, resetState, resetAvailableAt });
 }

apps/web/src/app/api/ai/partner/log/route.ts

@@ -0,0 +1,88 @@
+import { NextRequest, NextResponse } from "next/server";
+import { createClient } from "@/lib/supabase/server";
+import { isRateLimited } from "@/lib/rate-limit";
+import { getLessonBySlug } from "@/lib/content/queries";
+import { resetAssists } from "@/lib/ai/assist-budget";
+
+const MAX_BODY_CHARS = 4_000;
+const MAX_SLUG_CHARS = 256;
+
+/**
+ * Self-serve per-lesson assist reset (#864, P2-5 / owner D-8). Self-only by
+ * construction: keyed to the AUTHENTICATED user's id — the request body only
+ * names the lesson. Both guards — once per (user, lesson) AND the 7-day
+ * cooldown — are enforced INSIDE the SECURITY DEFINER
+ * `reset_challenge_assists` RPC (rule R-6), shipped in the same migration as
+ * this route; this handler only relays the verdict. A denial is 200 with
+ * `{ allowed: false, reason }` — it is an expected product state (cooldown /
+ * already used), not an error.
+ */
+export async function POST(request: NextRequest) {
+  const supabase = await createClient();
+  const {
+    data: { user },
+    error: authError,
+  } = await supabase.auth.getUser();
+  if (authError || !user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const raw = await request.text();
+  if (raw.length > MAX_BODY_CHARS) {
+    return NextResponse.json(
+      { error: "Request body too large" },
+      { status: 413 }
+    );
+  }
+
+  let body: { courseSlug?: unknown; lessonSlug?: unknown };
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return NextResponse.json(
+      { error: "Invalid request body" },
+      { status: 400 }
+    );
+  }
+
+  const { courseSlug, lessonSlug } = body;
+  if (
+    typeof courseSlug !== "string" ||
+    typeof lessonSlug !== "string" ||
+    !courseSlug ||
+    !lessonSlug ||
+    courseSlug.length > MAX_SLUG_CHARS ||
+    lessonSlug.length > MAX_SLUG_CHARS
+  ) {
+    return NextResponse.json({ error: "Missing lesson" }, { status: 400 });
+  }
+
+  // Abuse throttle only — the RPC's internal guards are the real ceiling.
+  // Fail-open is fine here (unlike the paid partner route): a reset spends no
+  // Gemini tokens, and the once+cooldown guards hold regardless.
+  if (
+    await isRateLimited("ai:partner:reset", user.id, {
+      maxTokens: 5,
+      refillIntervalMs: 60_000,
+    })
+  ) {
+    return NextResponse.json(
+      { error: "Rate limit exceeded. Please wait before trying again." },
+      { status: 429, headers: { "Retry-After": "60" } }
+    );
+  }
+
+  // Resolve the lesson id the budget is keyed by (same seam the paid route
+  // uses — the catalog gate applies here too).
+  const lesson = await getLessonBySlug(courseSlug, lessonSlug);
+  if (!lesson) {
+    return NextResponse.json({ error: "Lesson not found" }, { status: 404 });
+  }
+
+  const result = await resetAssists(user.id, lesson._id);
+  return NextResponse.json({
+    allowed: result.allowed,
+    reason: result.reason,
+    availableAt: result.availableAt,
+  });
+}

apps/web/src/app/api/ai/partner/reset/route.ts

@@ -4,8 +4,8 @@ import { createClient } from "@/lib/supabase/server";
 import { isRateLimited, getClientIp } from "@/lib/rate-limit";
 import { getLessonBySlug } from "@/lib/content/queries";
 import {
-  spendAssist,
-  refundAssist,
+  spendAssistTurn,
+  refundAssistTurn,
   recordBilledAssist,
   appendAssistLog,
 } from "@/lib/ai/assist-budget";
@@ -368,14 +368,23 @@ export async function POST(request: NextRequest) {
   // cost lever) rather than refusing. "Degrade first, then stop" (owner).
   const degraded = spendGate.decision === "degraded";
 
-  // Every request that reaches this route is a PAID action — free authored
-  // hints are served client-side from the block's `hints` ladder and never
-  // hit this route. Spend atomically before calling Gemini so a denied budget
-  // never triggers a model call. Budget is keyed by the lesson id.
-  const spend = await spendAssist(user.id, lesson._id);
+  // Every request that reaches this route is a METERED AI turn — free authored
+  // hints are served client-side from the block's `hints` ladder and never hit
+  // this route. Spend one assist-LADDER turn atomically before calling Gemini
+  // (#864): the SECURITY DEFINER RPC resolves the tier server-side (2 free →
+  // 8 metered → 20 Socratic, per (user, lesson)) and reports which tier this
+  // turn landed in. A denial means the whole ladder is spent — the community
+  // handoff (spec §4.2 turn 31): the client degrades to the forum link, never
+  // a paywall shape. Budget is keyed by the lesson id.
+  const spend = await spendAssistTurn(user.id, lesson._id);
   if (!spend.allowed) {
-    return NextResponse.json({ budgetExhausted: true, used: spend.used });
+    return NextResponse.json({ budgetExhausted: true, counts: spend.counts });
   }
+  // Socratic tier (§4.4): flip the default contract for hint/ask to ONE
+  // diagnostic question (prompt suffix below) at a hint-sized output cap.
+  // `propose` keeps its full diff contract at every tier — the §4.2 ruling —
+  // and `review` is post-pass and unaffected.
+  const socratic = spend.tier === "socratic";
 
   // Whether Gemini has BILLED us for this request. Flips true the instant the
   // model returns a 2xx (`response.ok`) — a non-2xx or a network throw means it
@@ -428,14 +437,17 @@ export async function POST(request: NextRequest) {
       tutorNotes,
       language: codeBlock.language,
     });
-    const suffix = buildDynamicSuffix({
-      lessonSlug,
-      courseSlug,
-      action,
-      message,
-      code,
-      testSummary,
-    });
+    const suffix = buildDynamicSuffix(
+      {
+        lessonSlug,
+        courseSlug,
+        action,
+        message,
+        code,
+        testSummary,
+      },
+      { socratic }
+    );
 
     const response = await fetch(`${GEMINI_URL}?key=${GEMINI_API_KEY}`, {
       method: "POST",
@@ -451,9 +463,11 @@ export async function POST(request: NextRequest) {
           temperature: 0.3,
           // Degrade-first (#591): past a soft spend cap, halve the output budget
           // (floored to stay usable) to cut the dominant cost before any refusal.
+          // Socratic hint/ask turns run at the hint-sized cap (one diagnostic
+          // question); propose keeps its full budget at every tier.
           maxOutputTokens: degraded
-            ? degradedMaxTokens(maxTokensFor(action))
-            : maxTokensFor(action),
+            ? degradedMaxTokens(maxTokensFor(action, { socratic }))
+            : maxTokensFor(action, { socratic }),
           // gemini-3.5-flash is a thinking model and thinking tokens share the
           // maxOutputTokens budget; disable it so the full budget goes to the
           // structured response (and to cut latency/cost).
@@ -468,9 +482,9 @@ export async function POST(request: NextRequest) {
       const errorText = await response.text();
       console.error("Gemini partner API error:", response.status, errorText);
       // A spend already happened above (spend.allowed was true to reach
-      // here) but Gemini never ran — refund so a failed call doesn't burn
-      // one of the user's 4 paid assists.
-      await refundAssist(user.id, lesson._id);
+      // here) but Gemini never ran — refund exactly the ladder tier the spend
+      // landed in so a failed call doesn't burn one of the learner's turns.
+      await refundAssistTurn(user.id, lesson._id, spend.tier);
       // Surface the upstream status (not Gemini's raw body) so a config-side
       // failure (403 API-not-enabled / key-restricted, 404 model, 429 quota)
       // is diagnosable from the Network tab, not just the server logs.
@@ -615,7 +629,7 @@ export async function POST(request: NextRequest) {
     // appendAssistLog, so the old unconditional refund handed back a fully
     // billed success (the AIE-10 line-411 correction).
     if (!billed) {
-      await refundAssist(user.id, lesson._id);
+      await refundAssistTurn(user.id, lesson._id, spend.tier);
     }
     return NextResponse.json(
       { error: "Failed to get response" },

apps/web/src/app/api/ai/partner/route.ts

@@ -15,16 +15,23 @@ const review = vi.fn();
 const hookState = {
   messages: [] as unknown[],
   freeHintsUsed: 0,
-  paidUsed: 0,
-  paidRemaining: 4,
+  counts: { free: 0, metered: 0, socratic: 0 },
+  tier: "free" as const,
   budgetExhausted: false,
   spendCapped: false,
+  resetState: "none" as const,
+  resetAvailableAt: null as number | null,
   loading: false,
   error: null as string | null,
   requestHint: vi.fn(),
   proposeFix: vi.fn(),
   ask: vi.fn(),
   review,
+  requestReset: vi.fn(async () => ({
+    allowed: false,
+    reason: "error",
+    availableAt: null,
+  })),
   verifyCheck: vi.fn(),
 };
 

apps/web/src/components/editor/ai-partner/__tests__/ai-partner-pane.test.tsx

@@ -9,13 +9,17 @@ vi.mock("@/lib/ai/use-ai-partner", () => ({
   useAiPartner: () => ({
     messages: [],
     freeHintsUsed: 0,
-    paidUsed: 0,
+    counts: { free: 0, metered: 0, socratic: 0 },
+    tier: "free",
     budgetExhausted: false,
     spendCapped: false,
+    resetState: "none",
+    resetAvailableAt: null,
     loading: false,
     error: null,
     requestHint: vi.fn(),
     review: vi.fn(),
+    requestReset: vi.fn(),
     verifyCheck: vi.fn(),
   }),
 }));