Diagnose setup by what is certain, and deliver errors the way the client asked

Review of the branch found the persona diagnosis was mostly truncation
wearing a name tag. The <.> marker sits at the start of the system
message and the persona marker after the card, so a card Janitor cut
short arrives with the prompt present and the persona gone — and was
told its persona was wrong, with truncation as an afterthought. The
original message was only ever about context size, which is the best
evidence there is about what actually happens.

diagnoseSetup() now says only what the markers make certain. A missing
<.> is a missing prompt, since truncation cannot remove the first three
characters. A persona marker that is present but not "." is a wrong
description, quoted back so there is nothing to guess. A persona marker
that is gone, or cut off mid-tag, leads with truncation and mentions the
persona second.

The error path decided "streaming?" from the Accept header while the
success path used body.stream, so a client that sent stream:true without
that header got JSON back for every error and never displayed it. The
flag is hoisted above the try; the header is only a fallback for when
the body could not be read.

Token search is restricted to after the greeting, in order. A card built
from a sucker-proxied chat could carry an expired token in its text, and
a lookup on it would fail forever. Conversation order also means the
token a chat was started with always wins over one pasted later. The
system fallback now takes a role-less first message only; a request with
roles but no system turn is reported as such rather than misdiagnosed as
a missing prompt. The echo feature reads the parser's lastUser instead of
its own case-sensitive lookup. "Nothing was saved" is dropped from the
unknown-error message, since it is not guaranteed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NX2SsmUqQftWTZAY4BDuFa

README.md

@@ -17,6 +17,7 @@ You can also build and run Sucker as a Docker container with `docker compose bui
 
 ### Changelog
 
+- 2.5: Real error messages instead of one blanket "dingus" reply; unexplained failures now ask you to DM @lyseverian. Unread dot on the Changelog button. Fixed extraction for users whose Janitor sends a request without the blank turn before the first message — sucker read the parts by position rather than by role, so for them it read the wrong ones and errored. Now resolved by role, with tests for both shapes.
 - 2.4: CSS editor for Janitor profiles. New banner links to the live-preview editor at tools.from-avalon.com/janitor-profile-maker.
 - 2.3: ECHO. Put ECHO: anywhere in a message and sucker repeats whatever comes after it in the reply — for triggering char-side script and lorebook keywords.
 - 2.2: Added support for directly inputting webp file names or character image links when creating PNG character cards

package.json

@@ -6,7 +6,8 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "node --experimental-strip-types --test \"tests/**/*.test.ts\""
   },
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.2",

src/app/api/proxy/route.ts

@@ -1,5 +1,17 @@
 import { NextResponse } from "next/server";
 import type { NextRequest } from "next/server";
+import {
+  selectMessageSlots,
+  tokenCandidates,
+  type Message,
+} from "@/lib/messages";
+import {
+  NO_CARD,
+  NO_GREETING,
+  TOO_FEW_MESSAGES,
+  diagnoseSetup,
+  userFacingMessage,
+} from "@/lib/errors";
 
 interface CardVersion {
   version: number;
@@ -64,10 +76,6 @@ function cleanupExpiredCards() {
   );
 }
 
-interface Message {
-  content: string;
-}
-
 // Extracted shape used during POST handling
 interface ExtractedCard {
   trackingName: string;
@@ -118,9 +126,18 @@ function removePersonaTags(content: string): string {
 }
 
 function extractCardData(messages: Message[]): ExtractedCard {
-  const first_mes = messages[2].content.replace(/{user}/g, "{{user}}");
+  const { system, greeting, nameSlot } = selectMessageSlots(messages);
 
-  const nameContent = messages[3].content;
+  if (!system) {
+    throw NO_CARD;
+  }
+  if (!greeting) {
+    throw NO_GREETING;
+  }
+
+  const first_mes = greeting.replace(/{user}/g, "{{user}}");
+
+  const nameContent = nameSlot ?? "";
   // If the name slot is actually a token, ignore it for naming purposes
   const tokenInNameSlot = parseConversationToken(nameContent);
   const lastColonIndex = nameContent.lastIndexOf(": ");
@@ -130,7 +147,7 @@ function extractCardData(messages: Message[]): ExtractedCard {
     ? nameContent.substring(lastColonIndex + 2).trim()
     : "";
 
-  let content = messages[0].content.replace(/{user}/g, "{{user}}");
+  let content = system.replace(/{user}/g, "{{user}}");
   const inferredName = extractPersonaName(content);
   content = removePersonaTags(content);
 
@@ -148,11 +165,11 @@ function extractCardData(messages: Message[]): ExtractedCard {
     `Name extraction: user="${nameFromUser}", inferred="${inferredName}", tracking="${cleanTrackingName}", display="${displayName}"`
   );
 
-  if (
+  // The two markers are the two REQUIRED setup steps; the diagnosis names
-    !content.includes("<.>") ||
+  // the one that is wrong, or says the card was cut short.
-    !content.includes("<UserPersona>.</UserPersona>")
+  const setupProblem = diagnoseSetup(content);
-  ) {
+  if (setupProblem) {
-    throw new Error("Required substrings not found");
+    throw setupProblem;
   }
 
   content = content.replace("<.>", "");
@@ -319,18 +336,19 @@ export async function POST(request: NextRequest) {
     });
   }
 
+  // Decided from the body, and read again in the catch below: an error must
+  // go back the same way a success would, or the client never shows it.
+  let isStreamingRequest = false;
   try {
     const body = await request.json();
-    const isStreamingRequest = body.stream === true;
+    isStreamingRequest = body.stream === true;
 
     if (!body.messages || body.messages.length < 2) {
       if (isStreamingRequest) {
-        return createSSEErrorResponse(
+        return createSSEErrorResponse(userFacingMessage(TOO_FEW_MESSAGES));
-          "Missing messages or insufficient message count"
-        );
       }
       return NextResponse.json(
-        { error: "Missing messages or insufficient message count" },
+        { error: userFacingMessage(TOO_FEW_MESSAGES) },
         {
           status: 400,
           headers: {
@@ -340,12 +358,14 @@ export async function POST(request: NextRequest) {
       );
     }
 
-    // Parse potential token from messages[3] (user) or messages[4] (assistant prior reply)
+    // The token may be in what the user just typed, or in sucker's own first
-    const tokenCandidateUser: string | undefined = body.messages?.[3]?.content;
+    // reply from earlier in the conversation. Search every message rather than
-    const tokenCandidateAssistant: string | undefined = body.messages?.[4]?.content;
+    // a fixed pair of slots: only the first reply carries a token, so a long
+    // chat would otherwise lose the link and duplicate the card.
     const providedConversationId =
-      parseConversationToken(tokenCandidateUser || undefined) ||
+      tokenCandidates(body.messages)
-      parseConversationToken(tokenCandidateAssistant || undefined);
+        .map((c) => parseConversationToken(c))
+        .find((id): id is string => Boolean(id)) ?? null;
 
     let existingCard: StoredCard | null = null;
     let linkedByToken = false;
@@ -498,12 +518,7 @@ export async function POST(request: NextRequest) {
 
     // Echo back anything the user sent after an "ECHO:" marker in their
     // latest message, appended after the normal status message
-    const lastUserMessage =
+    const echoText = parseEchoText(selectMessageSlots(body.messages).lastUser);
-      [...body.messages]
-        .reverse()
-        .find((m: { role?: string }) => m?.role === "user") ??
-      body.messages[body.messages.length - 1];
-    const echoText = parseEchoText(lastUserMessage?.content);
     if (echoText) {
       responseMessage += `\n\n${echoText}`;
     }
@@ -548,14 +563,15 @@ export async function POST(request: NextRequest) {
   } catch (error) {
     console.error("Error processing request:", error);
 
-    const errorMessage =
+    const errorMessage = userFacingMessage(error);
-      "You dingus, read the directions on sucker before trying again. If you're trying to suck a bot with more tokens than your current context limit, try bumping your Context Size setting up on Generation Settings.";
 
-    // Check if this was a streaming request
+    // The body already said whether the client wanted a stream; the Accept
+    // header is only a fallback for when the body could not be read at all.
     const acceptHeader = request.headers.get("accept");
-    const isStreamingRequest = acceptHeader?.includes("text/event-stream");
+    const streaming =
+      isStreamingRequest || (acceptHeader?.includes("text/event-stream") ?? false);
 
-    if (isStreamingRequest) {
+    if (streaming) {
       return createSSEErrorResponse(errorMessage);
     }
 

src/app/page.tsx

@@ -67,9 +67,36 @@ interface Card {
   initialVersion?: CardDataV2;
 }
 
+/** Bumped once per release; the changelog dot keys off it. */
+const APP_VERSION = "2.5";
+const CHANGELOG_SEEN_KEY = "sucker:changelog-seen";
+
 export default function Home() {
   const [cards, setCards] = useState<Card[]>([]);
+  // The changelog dot. Starts hidden so the server and the first client render
+  // agree; the effect below turns it on for anyone who has not opened the
+  // dialog since this version shipped.
+  const [changelogSeen, setChangelogSeen] = useState(true);
   const [dialogOpen, setDialogOpen] = useState(false);
+  useEffect(() => {
+    try {
+      setChangelogSeen(localStorage.getItem(CHANGELOG_SEEN_KEY) === APP_VERSION);
+    } catch {
+      // Private mode or blocked storage: just leave the dot off.
+    }
+  }, []);
+
+  /** Open the changelog and remember that this version has been read. */
+  const openChangelog = () => {
+    setChangelogDialogOpen(true);
+    setChangelogSeen(true);
+    try {
+      localStorage.setItem(CHANGELOG_SEEN_KEY, APP_VERSION);
+    } catch {
+      // Nothing to do; the dot simply comes back next time.
+    }
+  };
+
   const [selectedCardIndex, setSelectedCardIndex] = useState<number | null>(
     null
   );
@@ -373,15 +400,21 @@ export default function Home() {
           {/* Row 1: Title on left, Hamburger on right */}
           <div className="flex justify-between items-start mb-3">
             <div>
-              <h1 className="text-2xl font-bold">Sucker v2.4</h1>
+              <h1 className="text-2xl font-bold">Sucker v{APP_VERSION}</h1>
               <p className="text-xs text-muted-foreground">
-                ECHO: Consider joining Avalon!
+                New: a live CSS editor for your profile.
               </p>
             </div>
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="icon">
+                <Button variant="outline" size="icon" className="relative">
                   <Menu className="h-4 w-4" />
+                  {!changelogSeen && (
+                    <span
+                      aria-label="New changelog entry"
+                      className="absolute -top-1 -right-1 h-2.5 w-2.5 rounded-full bg-sky-500 ring-2 ring-background"
+                    />
+                  )}
                 </Button>
               </DropdownMenuTrigger>
               <DropdownMenuContent align="end">
@@ -391,8 +424,11 @@ export default function Home() {
                 <DropdownMenuItem onClick={() => setMirrorsDialogOpen(true)}>
                   Mirrors
                 </DropdownMenuItem>
-                <DropdownMenuItem onClick={() => setChangelogDialogOpen(true)}>
+                <DropdownMenuItem onClick={openChangelog}>
                   Changelog
+                  {!changelogSeen && (
+                    <span className="ml-2 h-2 w-2 rounded-full bg-sky-500" />
+                  )}
                 </DropdownMenuItem>
               </DropdownMenuContent>
             </DropdownMenu>
@@ -411,9 +447,9 @@ export default function Home() {
         {/* Desktop Layout */}
         <div className="hidden sm:flex justify-between items-center mb-4">
           <div>
-            <h1 className="text-3xl font-bold">Sucker v2.4</h1>
+            <h1 className="text-3xl font-bold">Sucker v{APP_VERSION}</h1>
             <p className="text-sm text-muted-foreground">
-              ECHO: Consider joining Avalon!
+              New: a live CSS editor for your profile.
             </p>
           </div>
           <div className="flex gap-2">
@@ -430,10 +466,17 @@ export default function Home() {
               Mirrors
             </Button>
             <Button
-              onClick={() => setChangelogDialogOpen(true)}
+              onClick={openChangelog}
               variant="outline"
+              className="relative"
             >
               Changelog
+              {!changelogSeen && (
+                <span
+                  aria-label="New changelog entry"
+                  className="absolute -top-1 -right-1 h-2.5 w-2.5 rounded-full bg-sky-500 ring-2 ring-background"
+                />
+              )}
             </Button>
             <Button
               onClick={fetchCards}
@@ -961,6 +1004,36 @@ export default function Home() {
             </DialogDescription>
           </DialogHeader>
           <div className="space-y-6">
+            <div>
+              <h3 className="font-semibold text-lg mb-2">Sep 2026 - Fixed the dingus error some of you always got</h3>
+              <div className="space-y-2 text-sm text-muted-foreground">
+                <p>
+                  If sucker told you to read the directions no matter what you
+                  did, it wasn&apos;t you. Janitor doesn&apos;t send the same
+                  request to everyone: some accounts include an extra blank turn
+                  before the bot&apos;s first message and some don&apos;t. Sucker
+                  was counting positions in that request instead of reading what
+                  each part was, so for anyone on the shorter shape it read the
+                  wrong pieces and fell over.
+                </p>
+                <p>
+                  It now finds each part by what it is. Both shapes work, and
+                  longer conversations stay linked to the right card. If sucker
+                  never worked for you, give it another go.
+                </p>
+                <p>
+                  The Changelog button also carries a dot now when there is
+                  something here you haven&apos;t read.
+                </p>
+                <p>
+                  And when something does go wrong, sucker now tells you what
+                  actually happened instead of calling you a dingus. If it hits
+                  something it cannot explain, it says so and asks you to DM
+                  @lyseverian on Discord — those are the ones worth hearing about.
+                </p>
+              </div>
+            </div>
+            <Separator />
             <div>
               <h3 className="font-semibold text-lg mb-2">Sep 2026 - CSS Editor for Janitor profiles</h3>
               <div className="space-y-2 text-sm text-muted-foreground">

src/lib/errors.ts

@@ -0,0 +1,161 @@
+/**
+ * Telling people what actually went wrong.
+ *
+ * Every failure used to produce one message: "You dingus, read the directions
+ * on sucker before trying again", with a note about context size. For a
+ * truncated card that was fair. For anything else it blamed the user for
+ * something they could not have done anything about.
+ *
+ * The split that matters is not explained-vs-unexplained, it is
+ * **fixable-vs-not**:
+ *
+ *   - A setup step or a truncated card is something a user can act on;
+ *     those messages are shown verbatim, and name the step.
+ *   - Everything else — a request with no card in it, no greeting, nothing
+ *     at all — cannot happen through Janitor, and if it does the user has no
+ *     way to cause or fix it. Telling them to "open the chat properly" would
+ *     be the old message wearing a new coat. Those say plainly that it is not
+ *     their fault and ask them to report it, carrying a short tag so the
+ *     report identifies which assumption broke.
+ */
+
+/** Where to send someone when sucker is at fault. */
+export const CONTACT = "DM @lyseverian on Discord";
+
+/** A failure the person who hit it can actually do something about. */
+export class SuckerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SuckerError";
+  }
+}
+
+/**
+ * A request shaped in a way Janitor does not produce. Not the user's fault
+ * and not theirs to fix; `detail` exists so their report says which
+ * assumption broke, not so they can act on it.
+ */
+export class ImpossibleRequest extends Error {
+  readonly detail: string;
+  constructor(detail: string) {
+    super(`impossible request: ${detail}`);
+    this.name = "ImpossibleRequest";
+    this.detail = detail;
+  }
+}
+
+/**
+ * Both are checked by name as well as by identity: Next can bundle a module
+ * into more than one chunk, and a mismatched class would quietly send every
+ * classified error down the wrong path.
+ */
+const named = (error: unknown, name: string): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  (error as { name?: unknown }).name === name;
+
+export function isSuckerError(error: unknown): error is SuckerError {
+  return error instanceof SuckerError || named(error, "SuckerError");
+}
+
+export function isImpossibleRequest(error: unknown): error is ImpossibleRequest {
+  return error instanceof ImpossibleRequest || named(error, "ImpossibleRequest");
+}
+
+export function userFacingMessage(error: unknown): string {
+  if (isSuckerError(error)) return error.message;
+  const detail = isImpossibleRequest(error) ? ` (${error.detail})` : "";
+  return (
+    "Something went wrong that sucker has no explanation for. This one is " +
+    "not your fault and there is nothing for you to fix — " +
+    `please ${CONTACT} and say what you were pulling, because unreported ones ` +
+    `do not get fixed.${detail}`
+  );
+}
+
+const PERSONA_OPEN = "<UserPersona>";
+const PERSONA_CLOSE = "</UserPersona>";
+
+/** What the persona marker says, or null if it is absent or cut off mid-tag. */
+function personaDescription(content: string): string | null {
+  const open = content.indexOf(PERSONA_OPEN);
+  if (open === -1) return null;
+  const close = content.indexOf(PERSONA_CLOSE, open + PERSONA_OPEN.length);
+  if (close === -1) return null;
+  return content.slice(open + PERSONA_OPEN.length, close);
+}
+
+/** A short, single-line quote of what the user actually set. */
+function quoted(text: string): string {
+  if (text.trim() === "") return "empty";
+  const flat = text.replace(/\s+/g, " ").trim();
+  return `"${flat.length > 40 ? flat.slice(0, 40) + "…" : flat}"`;
+}
+
+/**
+ * Reads the two markers the two REQUIRED setup steps produce and says which
+ * step is wrong — or, when a marker is simply gone, that the card was
+ * probably cut short. Returns null when both are as they should be.
+ *
+ * `<.>` is the custom prompt and sits at the very start of the system
+ * message, so if it is missing the prompt is not set: truncation cannot
+ * remove the first three characters. `<UserPersona>…</UserPersona>` is the
+ * persona description and sits after the card, so:
+ *
+ *   - present with something other than "." inside → the description is
+ *     wrong. Certain, and the message quotes what it currently says.
+ *   - absent, or cut off mid-tag → either the persona is not set or Janitor
+ *     truncated the card because the bot is bigger than the context size.
+ *     Truncation is the common one, so it leads.
+ */
+export function diagnoseSetup(content: string): SuckerError | null {
+  const hasPrompt = content.includes("<.>");
+  const persona = personaDescription(content);
+  const personaOk = persona === ".";
+  if (hasPrompt && personaOk) return null;
+
+  const stillStuck = `Still stuck: ${CONTACT}.`;
+
+  if (!hasPrompt) {
+    let also = "";
+    if (persona === null) {
+      also =
+        " Your persona did not come through either: it needs the name " +
+        "{{user}} and a description of just a dot.";
+    } else if (!personaOk) {
+      also = ` Your persona description is ${quoted(persona)} as well — it has to be just a dot.`;
+    }
+    return new SuckerError(
+      "Sucker could not read that card: your custom prompt is not coming " +
+        "through as <.> — set it in your API settings." +
+        also +
+        ` Save, then refresh Janitor, not sucker. ${stillStuck}`
+    );
+  }
+
+  if (persona !== null) {
+    // Present but not "." — the one case that is certain.
+    return new SuckerError(
+      `Sucker could not read that card: your persona description is ${quoted(persona)} — ` +
+        "it has to be just a dot, with the name {{user}}. Save, then refresh " +
+        `Janitor, not sucker. ${stillStuck}`
+    );
+  }
+
+  // Prompt is fine and the persona marker is gone entirely: the end of the
+  // card is missing, and the usual reason is that Janitor cut it short.
+  return new SuckerError(
+    "Sucker could not read that card: the end of it is missing. That usually " +
+      "means the bot is bigger than your context size and Janitor cut it " +
+      "short — raise Context Size in Generation Settings and try again. If it " +
+      "is already generous, check your persona: name {{user}}, description " +
+      `just a dot, then refresh Janitor. ${stillStuck}`
+  );
+}
+
+// None of these can happen through Janitor. They exist so that if one ever
+// does, the reply is honest about whose problem it is and the report says
+// which assumption broke.
+export const NO_CARD = new ImpossibleRequest("no system message in the request");
+export const NO_GREETING = new ImpossibleRequest("no greeting in the request");
+export const TOO_FEW_MESSAGES = new ImpossibleRequest("fewer than two messages in the request");

src/lib/messages.ts

@@ -0,0 +1,117 @@
+/**
+ * Locating the parts of a JanitorAI request.
+ *
+ * JanitorAI does not send a fixed number of messages. Most clients put a
+ * throwaway "." user turn between the card and the greeting; some do not.
+ * Sucker used to read fixed indices, so on the shorter shape it read the name
+ * slot as the greeting and the slot after that did not exist at all — a
+ * TypeError that reached the user as the "you dingus" message, blaming them
+ * for something they had no control over.
+ *
+ * So nothing here depends on a position. What is actually stable, in both
+ * shapes and however long the conversation runs:
+ *
+ *   - the card is the system turn;
+ *   - the greeting is the FIRST assistant turn;
+ *   - the name is the first user turn AFTER the greeting — the one the user
+ *     typed to start, which stays put as more turns are appended;
+ *   - what the user typed most recently is the LAST user turn.
+ *
+ * Roles are compared case-insensitively and content is flattened to text
+ * first, because neither is guaranteed: a client may send "Assistant", or
+ * content as OpenAI's multipart array rather than a plain string. Getting
+ * either wrong looks exactly like the bug above.
+ *
+ * If JanitorAI changes the shape again, this is the only file that should
+ * need to know.
+ */
+
+export interface Message {
+  role?: string;
+  content?: unknown;
+}
+
+export interface MessageSlots {
+  /** The character card. */
+  system: string | undefined;
+  /** The character's opening message. */
+  greeting: string | undefined;
+  /** The name — or conversation token — the user typed to start the chat. */
+  nameSlot: string | undefined;
+  /** Whatever the user typed most recently. */
+  lastUser: string | undefined;
+}
+
+/** "Assistant", " user " and "USER" all have to count. */
+function roleOf(message: Message | undefined): string {
+  return typeof message?.role === "string" ? message.role.trim().toLowerCase() : "";
+}
+
+/**
+ * Content is usually a string, but the OpenAI shape allows an array of parts
+ * ({ type: "text", text: "…" }). Anything else — null, a number, a missing
+ * key — flattens to "" so it is simply skipped rather than throwing.
+ */
+export function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        const text = (part as { text?: unknown } | null)?.text;
+        return typeof text === "string" ? text : "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** Messages with usable text, paired with their normalised role. */
+function usable(messages: Message[] | undefined): { role: string; text: string }[] {
+  return (Array.isArray(messages) ? messages : [])
+    .map((m) => ({ role: roleOf(m), text: textOf(m?.content) }))
+    .filter((m) => m.text.length > 0);
+}
+
+export function selectMessageSlots(messages: Message[] | undefined): MessageSlots {
+  const list = usable(messages);
+  const greetingIndex = list.findIndex((m) => m.role === "assistant");
+  const users = list.filter((m) => m.role === "user");
+
+  return {
+    // A first message with no role at all is taken as the card, which is
+    // where it has always been. A request that has roles but no system turn
+    // is left with no card, so it is reported rather than misdiagnosed.
+    system: (list.find((m) => m.role === "system") ?? (list[0]?.role === "" ? list[0] : undefined))?.text,
+    greeting: greetingIndex === -1 ? undefined : list[greetingIndex].text,
+    nameSlot:
+      greetingIndex === -1
+        ? undefined
+        : list.slice(greetingIndex + 1).find((m) => m.role === "user")?.text,
+    lastUser: users[users.length - 1]?.text,
+  };
+}
+
+/**
+ * Message contents to search for a conversation token, in conversation order,
+ * starting after the greeting.
+ *
+ * A legitimate token lives in exactly one of two places, both after the
+ * greeting: the first user turn, when a chat was started with one to capture
+ * an alternate greeting, or sucker's own first reply, which issued it. Every
+ * later reply says "updated" or "unchanged" with no token in it, so a long
+ * conversation has to be searched back to its start or the link is lost and a
+ * duplicate card gets created.
+ *
+ * The card and the greeting are deliberately excluded. A card built from a
+ * sucker-proxied chat could carry an old token in its text, and a lookup on
+ * that would fail forever — the card would never be extractable.
+ * Conversation order also means the token a chat was started with always
+ * wins over one pasted later, so a chat cannot flip between cards.
+ */
+export function tokenCandidates(messages: Message[] | undefined): string[] {
+  const list = usable(messages);
+  const greetingIndex = list.findIndex((m) => m.role === "assistant");
+  if (greetingIndex === -1) return [];
+  return list.slice(greetingIndex + 1).map((m) => m.text);
+}

tests/errors.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Which failures a user can act on, which just need reporting, and whether
+ * the setup diagnosis names the right step.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CONTACT,
+  ImpossibleRequest,
+  NO_CARD,
+  NO_GREETING,
+  SuckerError,
+  TOO_FEW_MESSAGES,
+  diagnoseSetup,
+  isImpossibleRequest,
+  isSuckerError,
+  userFacingMessage,
+} from "../src/lib/errors.ts";
+
+const CARD = "<Gaius's Persona>a tired innkeeper</Gaius's Persona>";
+const ok = (prompt: string, persona: string) => `${prompt}\n${CARD}\n${persona}`;
+
+test("a correctly set up card has nothing to diagnose", () => {
+  assert.equal(diagnoseSetup(ok("<.>", "<UserPersona>.</UserPersona>")), null);
+});
+
+test("a missing custom prompt is named with certainty, not blamed on truncation", () => {
+  const msg = diagnoseSetup(ok("", "<UserPersona>.</UserPersona>"))!.message;
+  assert.match(msg, /custom prompt is not coming through as <\.>/);
+  assert.ok(!/cut it short|Context Size/.test(msg), "truncation cannot remove the first three characters");
+  assert.ok(!/persona/i.test(msg), "the persona is fine and must not be mentioned");
+});
+
+test("a wrong persona description is quoted back, so there is nothing to guess", () => {
+  const msg = diagnoseSetup(ok("<.>", "<UserPersona>I am a knight</UserPersona>"))!.message;
+  assert.match(msg, /persona description is "I am a knight"/);
+  assert.match(msg, /just a dot/);
+  assert.ok(!/Context Size/.test(msg), "this case is certain; truncation is not the story");
+});
+
+test("an empty persona description says so", () => {
+  assert.match(diagnoseSetup(ok("<.>", "<UserPersona></UserPersona>"))!.message, /description is empty/);
+});
+
+test("a long persona description is trimmed to one readable line", () => {
+  const long = "x".repeat(80) + "\n\n  y";
+  const msg = diagnoseSetup(ok("<.>", `<UserPersona>${long}</UserPersona>`))!.message;
+  assert.match(msg, /"x{40}…"/);
+  assert.ok(!msg.includes("\n"), "no raw newlines from user content");
+});
+
+test("a persona marker that is gone leads with truncation, the common cause", () => {
+  const msg = diagnoseSetup(ok("<.>", ""))!.message;
+  assert.match(msg, /end of it is missing/);
+  assert.ok(msg.indexOf("Context Size") < msg.indexOf("persona"), "truncation first, persona second");
+});
+
+test("a persona marker cut off mid-tag is truncation, not a wrong description", () => {
+  const msg = diagnoseSetup(ok("<.>", "<UserPersona>.</UserPe"))!.message;
+  assert.match(msg, /Context Size/);
+  assert.ok(!/description is/.test(msg));
+});
+
+test("both settings wrong at once are both named", () => {
+  const msg = diagnoseSetup(ok("", "<UserPersona>knight</UserPersona>"))!.message;
+  assert.match(msg, /custom prompt is not coming through/);
+  assert.match(msg, /description is "knight" as well/);
+  const neither = diagnoseSetup(ok("", ""))!.message;
+  assert.match(neither, /custom prompt is not coming through/);
+  assert.match(neither, /persona did not come through either/);
+});
+
+test("every setup message is shown verbatim and says where to go when stuck", () => {
+  for (const card of [ok("", "<UserPersona>.</UserPersona>"), ok("<.>", "<UserPersona>x</UserPersona>"), ok("<.>", ""), ok("", "")]) {
+    const e = diagnoseSetup(card)!;
+    assert.ok(isSuckerError(e));
+    assert.equal(userFacingMessage(e), e.message);
+    assert.ok(e.message.includes(CONTACT));
+  }
+});
+
+test("shapes Janitor cannot produce never tell the user to fix them", () => {
+  for (const e of [NO_CARD, NO_GREETING, TOO_FEW_MESSAGES]) {
+    const msg = userFacingMessage(e);
+    assert.match(msg, /not your fault and there is nothing for you to fix/i);
+    assert.ok(msg.includes(CONTACT), "must say where to report it");
+    assert.ok(!/open the chat|try again|point sucker|nothing was saved/i.test(msg), `overclaim or advice leaked into: ${msg}`);
+  }
+});
+
+test("the report carries which assumption broke, so it is useful", () => {
+  assert.match(userFacingMessage(NO_GREETING), /\(no greeting in the request\)/);
+  assert.match(userFacingMessage(NO_CARD), /\(no system message in the request\)/);
+  assert.match(userFacingMessage(TOO_FEW_MESSAGES), /\(fewer than two messages/);
+});
+
+test("a genuine bug reports itself without leaking internals", () => {
+  const msg = userFacingMessage(new TypeError("Cannot read properties of undefined"));
+  assert.match(msg, /not your fault/i);
+  assert.ok(msg.includes(CONTACT));
+  assert.ok(!msg.includes("Cannot read properties"));
+  assert.ok(!/\($/.test(msg.trim()), "no empty detail parenthesis");
+});
+
+test("nobody is called a dingus", () => {
+  for (const e of [diagnoseSetup("nothing")!, NO_CARD, NO_GREETING, TOO_FEW_MESSAGES, new Error("x")]) {
+    assert.ok(!/dingus/i.test(userFacingMessage(e)));
+  }
+});
+
+test("classified across module boundaries, not just by identity", () => {
+  assert.ok(isSuckerError(new SuckerError("x")));
+  assert.ok(isSuckerError({ name: "SuckerError", message: "x" }));
+  assert.ok(isImpossibleRequest(new ImpossibleRequest("x")));
+  assert.ok(isImpossibleRequest({ name: "ImpossibleRequest", detail: "x" }));
+  assert.ok(!isSuckerError(new Error("x")));
+  assert.ok(!isImpossibleRequest(new SuckerError("x")));
+  assert.ok(!isSuckerError(null));
+});

tests/messages.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Every request shape we have actually seen, plus the malformed ones a client
+ * could plausibly send. Run with `npm test` — no framework, node's own runner.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { selectMessageSlots, tokenCandidates, textOf } from "../src/lib/messages.ts";
+
+const CARD =
+  "<.>\n<Gaius's Persona>a tired innkeeper</Gaius's Persona><UserPersona>.</UserPersona>";
+const GREETING = "The clink of bottles is the only greeting you get.";
+const NAME = "{{user}}: Gaius";
+const TOKEN = "[sucker:conv=abc123]";
+
+/** What most clients send: a throwaway "." user turn before the greeting. */
+const withProbe = [
+  { role: "system", content: CARD },
+  { role: "user", content: "." },
+  { role: "assistant", content: GREETING },
+  { role: "user", content: NAME },
+];
+
+/** What some clients send: no "." turn, so every index shifts by one. */
+const withoutProbe = [
+  { role: "system", content: CARD },
+  { role: "assistant", content: GREETING },
+  { role: "user", content: NAME },
+];
+
+/** Three turns in. Only sucker's FIRST reply carries the token. */
+const continued = [
+  ...withProbe,
+  { role: "assistant", content: `New character "Gaius" created (v1). ${TOKEN}` },
+  { role: "user", content: "{{user}}: keep going" },
+  { role: "assistant", content: "Character data unchanged (v1, message 2)." },
+  { role: "user", content: "{{user}}: and again" },
+];
+
+test("both shapes resolve to the same slots", () => {
+  for (const [label, messages] of [
+    ["with probe", withProbe],
+    ["without probe", withoutProbe],
+  ] as const) {
+    const slots = selectMessageSlots(messages);
+    assert.equal(slots.system, CARD, `${label}: card`);
+    assert.equal(slots.greeting, GREETING, `${label}: greeting`);
+    assert.equal(slots.nameSlot, NAME, `${label}: name`);
+  }
+});
+
+test("the greeting and the name stay put as a conversation grows", () => {
+  const slots = selectMessageSlots(continued);
+  assert.equal(slots.greeting, GREETING);
+  // Not "keep going" or "and again": the name is what started the chat.
+  assert.equal(slots.nameSlot, NAME);
+  assert.equal(slots.lastUser, "{{user}}: and again");
+});
+
+test("the token is still found once later replies stop carrying it", () => {
+  const found = tokenCandidates(continued).find((c) => c.includes("sucker:conv="));
+  assert.ok(found, "a token must still be discoverable three turns in");
+  assert.match(found!, /\[sucker:conv=abc123\]/);
+});
+
+test("the token a chat was started with outranks one pasted later, so a chat cannot flip between cards", () => {
+  const candidates = tokenCandidates([
+    ...withProbe,
+    { role: "assistant", content: `created (v1). ${TOKEN}` },
+    { role: "user", content: "{{user}}: [sucker:conv=zzz999]" },
+  ]);
+  const first = candidates.find((c) => c.includes("sucker:conv="));
+  assert.match(first!, /abc123/);
+});
+
+test("a token in the card or the greeting is never a candidate", () => {
+  const stale = "[sucker:conv=stale00]";
+  const candidates = tokenCandidates([
+    { role: "system", content: `${CARD} made with sucker: ${stale}` },
+    { role: "user", content: "." },
+    { role: "assistant", content: `${GREETING} ${stale}` },
+    { role: "user", content: NAME },
+  ]);
+  assert.ok(!candidates.some((c) => c.includes(stale)), "an expired token baked into a card would make it unextractable forever");
+  assert.deepEqual(candidates, [NAME]);
+});
+
+test("roles are matched whatever their casing", () => {
+  const slots = selectMessageSlots([
+    { role: "System", content: CARD },
+    { role: " Assistant ", content: GREETING },
+    { role: "USER", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+  assert.equal(slots.greeting, GREETING);
+  assert.equal(slots.nameSlot, NAME);
+});
+
+test("content sent as OpenAI's multipart array is read as text", () => {
+  assert.equal(textOf([{ type: "text", text: "one " }, { type: "text", text: "two" }]), "one two");
+  const slots = selectMessageSlots([
+    { role: "system", content: [{ type: "text", text: CARD }] },
+    { role: "assistant", content: [{ type: "text", text: GREETING }] },
+    { role: "user", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+  assert.equal(slots.greeting, GREETING);
+});
+
+test("messages with no usable content are skipped, not treated as slots", () => {
+  const slots = selectMessageSlots([
+    { role: "system", content: CARD },
+    { role: "assistant", content: null },
+    { role: "assistant" },
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  // The empty assistant turns must not be mistaken for the greeting.
+  assert.equal(slots.greeting, GREETING);
+  assert.equal(slots.nameSlot, NAME);
+});
+
+test("a request with roles but no system turn has no card, rather than a misdiagnosed one", () => {
+  const slots = selectMessageSlots([
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  // Taking the greeting as the card would produce a "custom prompt not set"
+  // message for a request the user could never have fixed.
+  assert.equal(slots.system, undefined);
+  assert.equal(slots.greeting, GREETING);
+});
+
+test("a card with no role on the system turn still resolves", () => {
+  const slots = selectMessageSlots([
+    { content: CARD },
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+});
+
+test("nothing throws on empty or malformed input", () => {
+  for (const input of [[], undefined, [{}, { role: "user" }], [null], [{ content: 42 }]]) {
+    assert.doesNotThrow(() => selectMessageSlots(input as never));
+    assert.doesNotThrow(() => tokenCandidates(input as never));
+  }
+  assert.equal(selectMessageSlots([]).greeting, undefined);
+  assert.deepEqual(tokenCandidates(undefined), []);
+});