feat: AI-powered eligibility detection from Copy Agent screenshots

Adds an "AI Detect & Check Eligibility" action to the Copy Agent page that
sends captured screenshots to Claude to extract Member ID/DOB, then opens
the chatbot's eligibility confirm step pre-filled with the result.

- POST /api/ai/detect-eligibility-info: Claude vision extraction of
  Member ID/DOB from uploaded screenshots.
- POST /api/patients/create-temp: auto-creates a placeholder "PID-<id>"
  patient (matched by insuranceId+dob) when no patient is selected, so
  screenshots can be saved immediately; the real eligibility check later
  rewrites the patient's name and Cloud Storage folder automatically via
  the existing createOrUpdatePatientByInsuranceId matching logic.
- Chatbot: Member ID/DOB on the confirm card are now editable (MM/DD/YYYY),
  with edits synced back to the patient record before the check runs.
- Fixed a useEffect ordering bug on the insurance-status page that could
  silently clear a chatbot-prefilled Member ID/DOB before the auto-trigger
  effect ran, preventing the eligibility check from ever starting.
- Added a local-disk-only screenshot backup (apps/Backend/uploads/
  screenshot-backups/) for debugging, not exposed anywhere in the UI.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/Backend/src/queue/processors/eligibilityProcessor.ts

@@ -30,6 +30,7 @@ export interface EligibilityProcessorResult {
   patientUpdateStatus?: string;
   pdfUploadStatus?: string;
   pdfFileId?: number | string | null;
+  patientId?: number | null;
 }
 
 export async function runEligibilityProcessor(
@@ -109,6 +110,8 @@ export async function runEligibilityProcessor(
     throw new Error(`Failed to create/update patient: ${e.message}`);
   }
 
+  outputResult.patientId = patient?.id ?? null;
+
   // 5) Update patient status
   if (patient && patient.id !== undefined) {
     let newStatus = "UNKNOWN";
@@ -121,13 +124,24 @@ export async function runEligibilityProcessor(
     await storage.updatePatient(patient.id, updates);
     outputResult.patientUpdateStatus = `Patient status updated to ${newStatus}`;
 
+    // Rename the Copy Agent page's temp folder ("PID-<id>") to the real name now that we know
+    // it — only touches folders still using that placeholder pattern, never a normal patient's.
+    const patientName = `${patient.firstName ?? ""} ${patient.lastName ?? ""}`.trim() || `Patient ${patient.id}`;
+    try {
+      const existingFolder = await storage.getPatientFolder(patient.id);
+      if (existingFolder && /^PID-\d+$/.test(existingFolder.name) && patientName) {
+        await storage.updateFolder((existingFolder as any).id, { name: patientName });
+      }
+    } catch (e) {
+      console.error("[eligibilityProcessor] temp folder rename failed:", e);
+    }
+
     // 6) Save PDF
     let createdPdfFileId: number | string | null = null;
 
     if (seleniumResult.pdf_path?.endsWith(".pdf")) {
       try {
         const pdfBuffer = await fs.readFile(seleniumResult.pdf_path);
-        const patientName = `${patient.firstName ?? ""} ${patient.lastName ?? ""}`.trim() || `Patient ${patient.id}`;
 
         const cloudFile = await storage.savePdfToCloudStorage(
           userId,

apps/Backend/src/routes/ai-settings.ts

@@ -2,10 +2,15 @@ import express, { Request, Response } from "express";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import multer from "multer";
 import { storage } from "../storage";
 import { classifyInternalChat } from "../ai/internal-chat-graph";
 import { runInternalChatWorkflow, createAppointmentToday } from "../ai/internal-chat-workflow";
-import { resolveAiProvider } from "../ai/llm-factory";
+import { resolveAiProvider, getLlm } from "../ai/llm-factory";
+import { backupScreenshots } from "../utils/screenshotBackup";
+
+const eligibilityImageUpload = multer({ storage: multer.memoryStorage() });
+const ELIGIBILITY_IMAGE_MIMES = new Set(["image/png", "image/jpeg", "image/jpg"]);
 
 const CHAT_HISTORY_DIR = path.join(__dirname, "..", "..", "chat-history");
 
@@ -336,6 +341,78 @@ router.post("/internal-chat", async (req: Request, res: Response): Promise<any>
   }
 });
 
+// POST /api/ai/detect-eligibility-info
+// Sends screenshot(s) to the configured vision-capable AI to extract a Member ID and DOB,
+// used by the Copy Agent page's "AI Detect & Check Eligibility" action.
+router.post(
+  "/detect-eligibility-info",
+  eligibilityImageUpload.array("files", 10),
+  async (req: Request, res: Response): Promise<any> => {
+    try {
+      const userId = req.user?.id;
+      if (!userId) return res.status(401).json({ message: "Unauthorized" });
+
+      const files = req.files as Express.Multer.File[] | undefined;
+      if (!files?.length) return res.status(400).json({ error: "No files uploaded" });
+
+      const badFile = files.find((f) => !ELIGIBILITY_IMAGE_MIMES.has(f.mimetype.toLowerCase()));
+      if (badFile) {
+        return res.status(400).json({ error: `Unsupported file type: ${badFile.mimetype}` });
+      }
+
+      backupScreenshots(files);
+
+      const aiSettings = await storage.getAiSettings(userId);
+      const activeAi = resolveAiProvider(aiSettings ?? {});
+      if (!activeAi) {
+        return res.status(200).json({ error: true, message: "AI is not configured. Please add an API key in AI Settings." });
+      }
+      if (activeAi.provider !== "claude") {
+        return res.status(200).json({ error: true, message: "Screenshot detection requires Claude to be the active AI provider." });
+      }
+
+      const llm = getLlm(activeAi.provider, activeAi.key, activeAi.model);
+
+      const content: Array<Record<string, unknown>> = [
+        {
+          type: "text",
+          text:
+            "Extract the Member ID and Date of Birth from this dental/insurance eligibility screenshot. " +
+            'Respond with strict JSON only, no prose, no markdown fences: {"memberId": string|null, "dob": "YYYY-MM-DD"|null}',
+        },
+        ...files.map((f) => ({
+          type: "image_url",
+          image_url: { url: `data:${f.mimetype};base64,${f.buffer.toString("base64")}` },
+        })),
+      ];
+
+      const response = await llm.invoke([{ role: "user", content }] as any);
+
+      let memberId: string | null = null;
+      let dob: string | null = null;
+      try {
+        const raw = String(response.content).trim();
+        const jsonStr = raw.replace(/^```json\s*/i, "").replace(/```\s*$/, "").trim();
+        const parsed = JSON.parse(jsonStr) as { memberId?: string | null; dob?: string | null };
+        // Sanitize once here so this is the single source of truth for the memberId
+        // used downstream (temp-patient creation, chatbot prefill, real eligibility check) —
+        // any mismatch in formatting would cause createOrUpdatePatientByInsuranceId to create
+        // a second patient instead of matching the temp one.
+        const cleanedMemberId = (parsed.memberId || "").replace(/[^A-Za-z0-9]/g, "");
+        memberId = cleanedMemberId || null;
+        dob = parsed.dob || null;
+      } catch (parseErr) {
+        console.error("[detect-eligibility-info] failed to parse AI response", parseErr);
+      }
+
+      return res.status(200).json({ error: false, data: { memberId, dob } });
+    } catch (err) {
+      console.error("[detect-eligibility-info]", err);
+      return res.status(500).json({ error: true, message: "Failed to detect eligibility info", details: String(err) });
+    }
+  }
+);
+
 router.post("/create-appointment-today", async (req: Request, res: Response): Promise<any> => {
   try {
     const userId = req.user?.id;

apps/Backend/src/routes/claims.ts

@@ -19,6 +19,7 @@ import {
 } from "@repo/db/types";
 import { forwardToSeleniumClaimPreAuthAgent } from "../services/seleniumInsuranceClaimPreAuthClient";
 import { formatDobForAgent } from "../utils/dateUtils";
+import { backupScreenshots } from "../utils/screenshotBackup";
 
 const router = Router();
 
@@ -106,13 +107,22 @@ router.post(
 
     const patientId = Number(req.body.patientId);
     const patientName = String(req.body.patientName || "unknown").replace(/[/\\?%*:|"<>]/g, "-").trim();
+    const pending = String(req.body.pending || "") === "true";
+    const isScreenshotUpload = String(req.body.screenshotBackup || "") === "true";
 
     if (!patientId || isNaN(patientId)) {
       return res.status(400).json({ error: "Invalid patientId" });
     }
 
+    if (isScreenshotUpload) backupScreenshots(files);
+
     try {
-      const folder = await storage.getOrCreatePatientFolder(req.user.id, patientId, patientName);
+      let folderName = patientName;
+      if (pending) {
+        const existingFolder = await storage.getPatientFolder(patientId);
+        if (!existingFolder) folderName = "Pending Review";
+      }
+      const folder = await storage.getOrCreatePatientFolder(req.user.id, patientId, folderName);
       const attachmentsFolder = await storage.getOrCreateSubfolder(
         req.user.id,
         (folder as any).id,
@@ -158,6 +168,33 @@ router.post(
   }
 );
 
+// PATCH /api/claims/patient-folder/:patientId/confirm-name
+// Renames a patient's Cloud Storage folder from its placeholder ("Pending Review") to the
+// real patient name once the user has confirmed the attachments belong to that patient.
+router.patch(
+  "/patient-folder/:patientId/confirm-name",
+  async (req: Request, res: Response): Promise<any> => {
+    if (!req.user?.id) return res.status(401).json({ error: "Unauthorized" });
+
+    const patientId = Number(req.params.patientId);
+    const patientName = String(req.body.patientName || "").replace(/[/\\?%*:|"<>]/g, "-").trim();
+    if (!patientId || isNaN(patientId) || !patientName) {
+      return res.status(400).json({ error: "Invalid patientId or patientName" });
+    }
+
+    try {
+      const folder = await storage.getPatientFolder(patientId);
+      if (!folder) return res.status(404).json({ error: "Patient folder not found" });
+
+      await storage.updateFolder((folder as any).id, { name: patientName });
+      return res.json({ error: false });
+    } catch (err: any) {
+      console.error("[confirm-name]", err);
+      return res.status(500).json({ error: "Failed to rename patient folder", message: err?.message });
+    }
+  }
+);
+
 // GET /api/claims/patient-attachments?patientId=123
 // Lists this patient's previously saved Cloud Storage "Attachments" (e.g. Copy Agent screenshots)
 // so they can be picked and re-attached to a claim/preauth without re-uploading from disk.

apps/Backend/src/routes/patients.ts

@@ -4,6 +4,7 @@ import { storage } from "../storage";
 import { z } from "zod";
 import { insertPatientSchema, updatePatientSchema } from "@repo/db/types";
 import { normalizeInsuranceId } from "../utils/helpers";
+import { createOrUpdatePatientByInsuranceId } from "../queue/processors/_shared";
 
 const router = Router();
 
@@ -190,6 +191,38 @@ router.get(
   }
 );
 
+// POST /api/patients/create-temp
+// Creates (or reuses) a lightweight placeholder patient — "PID-<id>" — from a Member ID/DOB
+// read off a screenshot by the Copy Agent page's AI Detect flow, before the real name is known.
+// Uses the same memberId+dob matching the actual eligibility check will later use, so that
+// check automatically rewrites this patient's real name once it runs (see eligibilityProcessor.ts).
+router.post("/create-temp", async (req: Request, res: Response): Promise<any> => {
+  try {
+    if (!req.user?.id) return res.status(401).json({ message: "Unauthorized" });
+
+    const memberId = String(req.body.memberId || "").trim();
+    const dob = req.body.dob;
+    if (!memberId || !dob) {
+      return res.status(400).json({ message: "memberId and dob are required" });
+    }
+
+    let patient = await createOrUpdatePatientByInsuranceId({
+      insuranceId: memberId,
+      dob,
+      userId: req.user.id,
+    });
+
+    if (patient && patient.id !== undefined && !patient.firstName) {
+      await storage.updatePatient(patient.id, { firstName: `PID-${patient.id}` });
+      patient = (await storage.getPatient(patient.id)) ?? patient;
+    }
+
+    return res.status(200).json({ error: false, data: patient });
+  } catch (error: any) {
+    return res.status(500).json({ message: "Failed to create temp patient", details: error?.message });
+  }
+});
+
 // Create a new patient
 router.post("/", async (req: Request, res: Response): Promise<any> => {
   try {

apps/Backend/src/storage/cloudStorage-storage.ts

@@ -138,6 +138,7 @@ export interface IStorage {
   streamFileTo(resStream: NodeJS.WritableStream, fileId: number): Promise<void>;
 
   // Patient folder
+  getPatientFolder(patientId: number): Promise<CloudFolder | null>;
   getOrCreatePatientFolder(
     userId: number,
     patientId: number,
@@ -549,6 +550,13 @@ export const cloudStorageStorage: IStorage = {
   },
 
   // --- PATIENT FOLDER ---
+  async getPatientFolder(patientId: number) {
+    const existing = await db.cloudFolder.findFirst({
+      where: { patientId },
+    });
+    return (existing as unknown as CloudFolder) ?? null;
+  },
+
   async getOrCreatePatientFolder(
     userId: number,
     patientId: number,

apps/Backend/src/utils/screenshotBackup.ts

@@ -0,0 +1,21 @@
+import fs from "fs";
+import path from "path";
+
+// Local-disk-only debug copy of screenshots captured via the Copy Agent page.
+// Not exposed anywhere in the app UI — purely for finding raw captures on disk when
+// diagnosing AI detection issues. Never blocks the calling request if it fails.
+const BACKUP_ROOT = path.join(process.cwd(), "uploads", "screenshot-backups");
+
+export function backupScreenshots(files: { originalname: string; buffer: Buffer }[]): void {
+  try {
+    const dateDir = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const dir = path.join(BACKUP_ROOT, dateDir);
+    fs.mkdirSync(dir, { recursive: true });
+    for (const file of files) {
+      const safeName = `${Date.now()}_${file.originalname.replace(/[/\\?%*:|"<>]/g, "-")}`;
+      fs.writeFileSync(path.join(dir, safeName), file.buffer);
+    }
+  } catch (err) {
+    console.error("[screenshotBackup] failed to write backup:", err);
+  }
+}