@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.0

package/lib/prompt.mjs

@@ -0,0 +1,518 @@
+/**
+ * Turn harness request messages into the single block of prose a web chat can accept.
+ *
+ * @file    prompt.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * THE CONSTRAINT THAT SHAPES THIS FILE
+ *     chat.deepseek.com has ONE text box. It has no notion of a system role, a tool result, or a
+ *     structured tool call. Everything the harness wants to say has to be flattened into one message,
+ *     and everything the model wants to do has to be recovered from plain text.
+ *
+ * WHY THE FLATTENING IS NOT JUST CONCATENATION
+ *     A transcript glued together with newlines loses the boundary between "the user said this" and
+ *     "you said that". Speakers are therefore labelled explicitly whenever there is more than one turn,
+ *     because a model that cannot tell its own earlier answer from the user's request will happily
+ *     continue the wrong voice.
+ *
+ * WHY A SINGLE-TURN REQUEST IS SENT RAW
+ *     The common case is one user message and nothing else. Wrapping that in speaker labels and a
+ *     preamble costs tokens, changes the answer, and makes short prompts feel unlike the web product.
+ *     Only requests that actually carry history or a system prompt get the scaffolding.
+ */
+
+/** Pull readable text out of a message whose content may be a string or a list of blocks. */
+export function messageText(message) {  if (!message) return '';
+  const content = message.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text);
+    else if (block.type === 'reasoning' && typeof block.text === 'string') continue;
+    else if (block.type === 'tool-call') {
+      parts.push(`[called ${block.name}(${block.arguments ?? ''})]`);
+    } else if (block.type === 'image') parts.push('[image attached]');
+    else if (block.type === 'file') parts.push(`[file: ${block.attachment?.name ?? 'attached'}]`);
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * Render the tool catalogue as instructions the model can follow in plain text.
+ *
+ * The protocol is one JSON object and nothing else. Anything more elaborate - XML tags, a custom
+ * grammar, a sentinel language - competes with the model's instinct to be helpful in prose, and in
+ * practice it answers the question instead of calling the tool. A bare JSON object is the one shape it
+ * will reliably produce when asked and will not accidentally produce when not asked.
+ */
+/**
+ * Hard limits on what is sent to the chat box.
+ *
+ * MEASURED, NOT GUESSED
+ *     A one-word "hello" once became a 234,530-character prompt because every tool was described in full
+ *     on every message. chat.deepseek.com silently ignores Enter on text that large, so the message was
+ *     never sent and the caller waited for an answer to a question that was never asked.
+ *
+ *     Each tool cost roughly 1,600 characters - description plus a JSON schema - and a working harness can
+ *     carry a hundred or more of them. So the budget is set per tool AND in total, and whichever is hit
+ *     first truncates. A truncated list that still sends beats a complete list that never leaves the box.
+ *
+ * WHY THESE NUMBERS
+ *     8,000 characters of tool description is about five detailed tools, which is the most a person can
+ *     usefully ask a chat model to choose between in one turn. 24,000 for the whole prompt leaves room for
+ *     a real conversation on top of it. Both sit far below the size that failed.
+ */
+export const MAX_TOOL_PREAMBLE_CHARS = 8000;
+export const MAX_PROMPT_CHARS = 24000;
+/** Per-tool caps, so one enormous schema cannot consume the whole budget. */
+const MAX_TOOL_DESCRIPTION = 220;
+const MAX_TOOL_SCHEMA = 420;
+
+/**
+ * Is this message worth answering, or is it just the person being friendly?
+ *
+ * WHY
+ *     Every message carried the tool preamble, because tools were offered on every call. On a greeting that
+ *     turned a hello into "What would you like me to do? I have a broad toolset available…" - recorded
+ *     twice, and it reads as a machine waiting for orders rather than a model saying hello back.
+ *
+ *     A greeting carries no task, so no tool can be the answer. Dropping the preamble for one leaves the
+ *     model free to reply like a person, and costs nothing: nothing needed calling.
+ *
+ * HOW
+ *     Short AND made only of greeting-ish words. Both conditions matter - "hola, arregla el bug del
+ *     proveedor" starts with a greeting and is obviously a task, so length alone disqualifies it.
+ */
+export function isOnlyGreeting(text) {
+  const s = String(text ?? '').trim().toLowerCase();
+  if (!s) return false;
+  if (s.length > 40) return false;
+  const words = s.split(/[\s,!?.¿¡·-]+/).filter(Boolean);
+  if (words.length > 4) return false;
+  const GREETING = new Set([
+    'hi', 'hello', 'hey', 'yo', 'sup', 'morning', 'evening', 'howdy', 'greetings',
+    'hola', 'buenas', 'buenos', 'dias', 'días', 'tardes', 'noches', 'que', 'qué', 'tal', 'estas', 'estás',
+    'bonjour', 'salut', 'ça', 'va', 'hallo', 'guten', 'tag', 'ciao', 'buongiorno', 'olá', 'oi', 'tudo', 'bem',
+    'hallo', 'hoi', 'hej', 'hei', 'terve', 'привет', 'здравствуйте', 'مرحبا', 'السلام', 'عليكم',
+    'こんにちは', 'こんばんは', 'おはよう', '你好', '您好', '안녕하세요', '안녕', 'नमस्ते', 'नमस्कार',
+    'สวัสดี', 'xin', 'chào', 'merhaba', 'selam', 'σου', 'γεια', 'szia', 'ahoj', 'czesc', 'cześć',
+    'unutbud', 'dobre', 'god', 'dag', 'there', 'amigo', 'friend', 'mi', 'gran', 'sam', 'uncle',
+  ]);
+  return words.every((w) => GREETING.has(w) || /^[\p{Emoji_Presentation}\p{Extended_Pictographic}]$/u.test(w));
+}
+
+/**
+ * Describe the available tools, within a fixed budget.
+ *
+ * Tools are taken in the order given, because the harness lists the most relevant first; when the budget
+ * runs out the rest are named but not described, so the model still knows they exist without paying for
+ * every schema. The truncation is stated in the preamble itself rather than hidden, so the model can say
+ * "I could not see the details of that tool" instead of inventing an argument shape.
+ */
+export function toolPreamble(tools) {
+  if (!tools?.length) return '';
+  /**
+   * Names only, and hard-capped.
+   *
+   * The first version carried a "NEVER do this" list plus a schema dump per tool. The second cut that to
+   * descriptions - which was fine for three tools and produced ONE ENORMOUS LINE for this session's thirty,
+   * because every description was still there. Recorded on screen: a paragraph of tool names and blurbs
+   * sitting above the person's own message, which is exactly the "gobbly goop" complaint.
+   *
+   * So: names only. A model does not need the description to call a tool - it needs to know the tool
+   * exists and what it is called. Arguments come from understanding, and the harness validates them.
+   */
+  const names = tools.map((t) => t.name);
+
+  /**
+   * One line, not a paraffle.
+   *
+   * The first version printed a dozen names AND a two-line call format above every single message. What
+   * the person saw in their own chat box was a wall of tool names before their own sentence - reported,
+   * correctly, as looking broken.
+   *
+   * The names have to stay: a model cannot call a tool it was never told exists. The call format has to
+   * stay too, because without it the model answers in prose instead of calling anything. What goes is the
+   * repetition - the format is one short clause on the same line, not a second block.
+   *
+   * The full text is still visible in the panel's "last thing sent" view, which is where a person looks
+   * when something goes wrong.
+   */
+  const HEAD = 'Tools: ';
+  const TAIL = ' · to call one reply only with {"tool":"name","arguments":{}}';
+  const MAX_VISIBLE_NAMES = 12;
+  const budget = MAX_TOOL_PREAMBLE_CHARS - HEAD.length - TAIL.length;
+  const kept = [];
+  let used = 0;
+  for (const name of names) {
+    if (kept.length >= MAX_VISIBLE_NAMES) break;
+    const add = (kept.length ? 2 : 0) + name.length;
+    if (used + add > budget) break;
+    kept.push(name);
+    used += add;
+  }
+  const omitted = names.length - kept.length;
+  const list = kept.join(', ') + (omitted > 0 ? `, +${omitted} more` : '');
+
+  return `${HEAD}${list}${TAIL}`;
+}
+
+/**
+ * Build the single prompt to type into the web composer.
+ *
+ * Returns `{ text, expectsToolCall }`, where `expectsToolCall` tells the caller whether a JSON reply
+ * would be a tool call rather than an answer that happens to look like JSON.
+ *
+ * WHAT THE PERSON SEES IN THE BROWSER
+ *     The chat box has one field and no system-prompt channel, so anything the harness wants the model to
+ *     know must be typed in as visible text. The browser tab is the same page the model answers on, so
+ *     every instruction becomes something a human can read there - and scaffolding in a chat box looks
+ *     like something broke.
+ *
+ *     So plain conversation sends ONLY the person's own words. No headings, no tool list, no marker of any
+ *     kind. Tools are described only on turns that actually carry tools, and that is the one case where
+ *     visible scaffolding is unavoidable: the model cannot call a tool it was never told about.
+ */
+export function buildPrompt(options) {
+  const system = typeof options.system === 'string' ? options.system.trim() : '';
+  const tools = Array.isArray(options.tools) ? options.tools : [];
+
+  /*
+   * A greeting carries no task, so the tool list would only invite "what would you like me to do?".
+   * Judged from the person's newest message, which is what this call is answering.
+   */
+  const newest = [...(options.messages ?? [])]
+    .reverse()
+    .find((m) => {
+      if (m?.role !== 'user') return false;
+      const kind = m?.source?.kind;
+      return typeof kind !== 'string' || kind === 'user';
+    });
+  const greetingOnly = isOnlyGreeting(messageText(newest));
+  const preamble = greetingOnly ? '' : toolPreamble(tools);
+
+  /**
+   * Tell the model which language to answer in.
+   *
+   * WHY THIS EXISTS
+   *     The panel can be in Spanish while the message reaching the page is a single word - "hola". The web
+   *     model has nothing to infer from and answers in English, which looks like the plugin ignored the
+   *     reader's choice. It can only answer in their language if it is told, and it has to be told the same
+   *     way a person would: one short line in the message.
+   *
+   * WHY IT IS SENT IN ENGLISH
+   *     The instruction itself is English, because that is the language the page reasons in. The language
+   *     NAME comes from each locale's `languageNameEn`, so it is always unambiguous - "Spanish", not
+   *     "Español", "Japanese" not "日本語".
+   *
+   * WHY IT IS OMITTED FOR ENGLISH
+   *     An English reader asking in English needs no instruction, and adding one would put a line of
+   *     scaffolding in front of every message for no reason.
+   *
+   * WHY IT COMES AFTER THE TOOL LINE
+   *     The tool list is machinery; the language is a request about the answer. Instructions about the
+   *     reply belong next to the words being replied to, which is where a person would put them.
+   */
+  const answerIn = typeof options.answerIn === 'string' ? options.answerIn.trim() : '';
+  const languageLine = answerIn && answerIn.toLowerCase() !== 'english' ? `[Answer in ${answerIn}]` : '';
+
+  /**
+   * When the browser chat continues, it already holds every earlier turn.
+   *
+   * Re-sending the transcript on top of a chat that remembers it duplicates the whole conversation, and
+   * the model then answers a question it was asked twice. So a continuing call sends only the newest user
+   * message, plus any system instructions the browser has no way to know about.
+   */
+  const continuing = options.continueChat === true;
+
+  const turns = [];
+  for (const message of options.messages ?? []) {
+    const role = message?.role;
+    const text = messageText(message);
+    if (!text) continue;
+    if (role === 'user') {
+      /*
+       * ONLY WHAT THE PERSON TYPED.
+       *
+       * The harness marks a message the person wrote with `source.kind === 'user'`. It also files a dozen
+       * kinds of its own machinery under `role: 'user'` - time context, runtime context, the skill catalog,
+       * goal notes, tool-job notices and, most damagingly, the "[model changed: …]" line written when the
+       * model is switched mid-conversation.
+       *
+       * Measured in one real transcript: of 1112 `role: 'user'` entries, 770 were the person and 342 were
+       * machinery. Treating the machinery as conversation meant a mid-chat switch could REPLACE the
+       * question - recorded happening: the search query became "[model changed: assistant turns above this
+       * point were generated by …]" and the answer was written from memory because the search it ran was
+       * meaningless.
+       *
+       * A message with no `source` at all is kept: the API path and older transcripts do not carry one, and
+       * dropping those would break ordinary use. Only an explicitly non-user source is excluded.
+       */
+      const kind = message?.source?.kind;
+      if (typeof kind === 'string' && kind !== 'user') continue;
+      turns.push({ role: 'user', text });
+    } else if (role === 'assistant') turns.push({ role: 'assistant', text });
+    else if (role === 'tool') turns.push({ role: 'tool', text });
+    else if (role === 'system' || role === 'developer') turns.push({ role: 'system', text });
+  }
+
+  /**
+   * Plain conversation: send the words, nothing else.
+   *
+   * This is the common case and the one the person actually watches happen in the browser. The harness's
+   * system prompt and tool list are deliberately dropped here - they exist to steer an API model, and
+   * pasting them into a chat box produces exactly the wall of instructions that looked like a malfunction.
+   * The model still answers the question; it simply is not told about machinery it will not use.
+   */
+  const hasTools = Boolean(preamble);
+  const onlyOneUserTurn = turns.length === 1 && turns[0].role === 'user';
+
+  if (!hasTools && (!system || onlyOneUserTurn)) {
+    const lastUser = [...turns].reverse().find((t) => t.role === 'user');
+    if (lastUser) {
+      /*
+       * The clean path: their words, and the language line only when it is needed.
+       *
+       * A continuing chat already has the history, so only this turn is typed. A fresh one gets the same
+       * treatment when there is nothing else to send, which is the pristine case. Even here the language
+       * line is kept, because it is the case where the answer is most likely to come back in the wrong
+       * language - one short message with nothing to infer from.
+       */
+      const text = languageLine ? `${languageLine}\n\n${lastUser.text}` : lastUser.text;
+      return finish(text, false, continuing);
+    }
+  }
+
+  if (continuing) {
+    const lastUser = [...turns].reverse().find((t) => t.role === 'user');
+    const sections = [];
+    if (preamble) sections.push(preamble);
+    // An instruction about the answer sits next to the question it is about.
+    if (languageLine) sections.push(languageLine);
+    // The harness system prompt is NOT sent here. It exists to steer an API model, and typing it into a
+    // chat box puts a wall of instructions in front of the person using that browser tab. The web model
+    // answers the question perfectly well without being told it is a coding agent with a shell.
+    if (lastUser) sections.push(lastUser.text);
+    return finish(sections.join('\n\n'), Boolean(preamble), true);
+  }
+
+  if (onlyOneUserTurn && !system && !preamble) {
+    const text = languageLine ? `${languageLine}\n\n${turns[0].text}` : turns[0].text;
+    return finish(text, false, false);
+  }
+
+  const sections = [];
+  // Same reasoning as the continuing branch: no harness system prompt in the visible text.
+  if (preamble) sections.push(preamble);
+  if (languageLine) sections.push(languageLine);
+
+  if (turns.length === 1) {
+    sections.push(turns[0].text);
+  } else {
+    const lines = ['# Conversation so far'];
+    for (const turn of turns) {
+      const label =
+        turn.role === 'user'
+          ? 'User'
+          : turn.role === 'assistant'
+            ? 'Assistant'
+            : turn.role === 'tool'
+              ? 'Tool result'
+              : 'System note';
+      lines.push(`${label}: ${turn.text}`);
+    }
+    lines.push('Assistant (reply now, continuing the conversation):');
+    sections.push(lines.join('\n\n'));
+  }
+
+  return finish(sections.join('\n\n'), Boolean(preamble), false);
+}
+
+/**
+ * Enforce the total budget, keeping the end of the conversation.
+ *
+ * If the assembled prompt is over the limit the oldest material goes first, because the newest turns are
+ * what the person is actually asking about. Trimming is done at a turn boundary where possible and stated
+ * in the text, so the model knows it is missing context rather than silently answering a half-question.
+ *
+ * This is a backstop: the tool budget above should normally keep the prompt well under the limit, but a
+ * long conversation or an unusually large system prompt could still exceed it, and the failure mode is
+ * silence from the site, which is the worst kind.
+ */
+function finish(text, expectsToolCall, continuing) {
+  if (text.length <= MAX_PROMPT_CHARS) return { text, expectsToolCall, continuing, truncated: false };
+
+  const room = MAX_PROMPT_CHARS - 200;
+  const cut = text.length - room;
+  const head = text.slice(0, 400);
+  const tail = text.slice(text.length - (room - 400));
+  const notice =
+    `\n\n[Earlier part of this conversation omitted - ${cut} characters - to fit the message limit.]\n\n`;
+  return {
+    text: head + notice + tail,
+    expectsToolCall,
+    continuing,
+    truncated: true,
+  };
+}
+
+/**
+ * Recover a tool call from a plain-text reply, if the model made one.
+ *
+ * The reply may be bare JSON, fenced JSON, or prose with JSON inside it. Fenced blocks are searched
+ * last-first because a model that explains itself tends to put the final answer at the end. A reply
+ * that merely CONTAINS the word tool but no valid object is treated as prose, because treating it as a
+ * malformed call would throw away a perfectly good answer.
+ */
+export function parseToolCall(reply) {
+  const text = String(reply ?? '').trim();
+  if (!text) return null;
+
+  const candidates = [];
+  // fenced blocks first
+  const fence = /```(?:json)?\s*([\s\S]*?)```/gi;
+  let m;
+  while ((m = fence.exec(text)) !== null) candidates.push(m[1].trim());
+  // then the whole reply, then any balanced-looking object
+  candidates.push(text);
+  const brace = text.indexOf('{');
+  const lastBrace = text.lastIndexOf('}');
+  if (brace >= 0 && lastBrace > brace) candidates.push(text.slice(brace, lastBrace + 1));
+
+  for (const raw of candidates.reverse()) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') continue;
+      const name = parsed.tool ?? parsed.name ?? parsed.function;
+      if (typeof name !== 'string' || !name) continue;
+      let args = parsed.arguments ?? parsed.args ?? parsed.parameters ?? {};
+      if (typeof args === 'string') {
+        try {
+          args = JSON.parse(args);
+        } catch {
+          /* leave as the raw string */
+        }
+      }
+      return { name, arguments: typeof args === 'string' ? args : JSON.stringify(args) };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Strip a tool-call JSON blob out of a reply that also contained prose, for the text channel.
+ *
+ * ASKING IS NOT ENOUGH
+ *     The preamble tells the model to emit only the object, and it leaked anyway: a call appeared as plain
+ *     words in the reply, followed by prose. What the person sees in that case is a raw {"tool": ...}
+ *     sitting in their answer, which looks like the plugin broke.
+ *
+ *     The old pattern also only matched a call at the END of the text with the anchor `\{\s*"tool"...$`,
+ *     so a call emitted FIRST survived scrubbing. This removes the object wherever it appears, with or
+ *     without a fence, with or without a closing brace, plus a stray narrator line a describing model
+ *     leaves behind.
+ */
+/**
+ * How much of a growing reply is safe to show while it is still arriving.
+ *
+ * THE BUG THIS EXISTS FOR
+ *     A reply arrived as prose followed by a call: `I'll test the reply speed… {"tool":"x","arguments":{}}`.
+ *     The old code decided how to handle a reply by looking only at its FIRST character - a reply opening
+ *     with a brace was buffered, everything else streamed straight through. This one opened with prose, so
+ *     the whole thing was streamed live, JSON included, and scrubbing afterwards could only fix a copy
+ *     nobody would see. Recorded on screen as a raw tool envelope inside an answer.
+ *
+ * WHAT IT DOES
+ *     Returns the index beyond which the text must be held: the first brace that could still turn out to be
+ *     the start of a tool object. `{"tool"` is certainly one. A brace whose following characters could
+ *     still grow into `"tool"` is *unresolved*, so it is held; a brace that has already diverged (`{a`) can
+ *     never become a call and is released immediately. That keeps streaming for ordinary prose, including
+ *     prose that merely contains a brace.
+ *
+ * WHAT IT IS NOT
+ *     It does not decide whether a call exists - `parseToolCall` does that at the end. It only answers
+ *     "how far can I safely show right now", which is the question a live stream needs.
+ */
+export function streamSafeCut(text) {
+  const s = String(text ?? '');
+
+  /**
+   * Could the brace at `i` still turn out to be the start of a tool object?
+   *
+   * Returns 'hold' when it might (`{`, `{"`, `{"t`, `{"tool`, `{"tool"`, `{"tool":`), and 'no' when the
+   * characters after it have already ruled it out (`{a`, `{"name"`). Only 'hold' stops the stream.
+   */
+  const candidate = (i) => {
+    let j = i + 1;
+    while (j < s.length && /\s/.test(s[j])) j += 1;
+    if (j >= s.length) return 'hold';            // `{` alone - the next character decides
+    if (s[j] !== '"') return 'no';               // can never become `{"tool"`
+
+    j += 1;
+    let word = '';
+    while (j < s.length && /[a-zA-Z]/.test(s[j])) {
+      word += s[j];
+      j += 1;
+    }
+    if (!'tool'.startsWith(word.toLowerCase())) return 'no';
+    if (word.length < 4) return 'hold';          // `{"t` - still growing
+    if (j >= s.length) return 'hold';            // `{"tool` - the closing quote may be coming
+    return s[j] === '"' ? 'hold' : 'no';         // `{"tool"` is a key; `{"toolx` is not
+  };
+
+  for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
+    if (candidate(i) === 'hold') return i;
+  }
+  return s.length;
+}
+
+export function stripToolCall(reply) {
+  let text = String(reply ?? '');
+
+  // Fenced calls first: the fence marks the whole block, so no brace counting is needed.
+  text = text.replace(/```(?:json)?\s*\{\s*"tool"[\s\S]*?\}\s*```/gi, '');
+
+  /**
+   * Remove bare tool objects by counting braces rather than matching them with a pattern.
+   *
+   * A regex cannot do this job. The call `{"tool":"x","arguments":{}}` contains TWO closing braces, and
+   * every lazy pattern stops at the first one - which deleted most of the object and left `}I'll start by…`
+   * behind, exactly as recorded. Counting depth is unambiguous and handles nested argument objects too.
+   */
+  const OPEN = /\{\s*"tool"\s*:/i;
+  for (let guard = 0; guard < 20; guard += 1) {
+    const match = OPEN.exec(text);
+    if (!match) break;
+    const start = match.index;
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < text.length; i += 1) {
+      if (text[i] === '{') depth += 1;
+      else if (text[i] === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    if (end === -1) {
+      // Unterminated: the stream was cut mid-call. Drop everything from the opening brace onward.
+      text = text.slice(0, start);
+      break;
+    }
+    text = text.slice(0, start) + text.slice(end + 1);
+  }
+
+  return text
+    // A narrator line a describing model leaves behind.
+    .replace(/^\s*(?:tool|function)\s*:\s*[\w.-]+\s*$/gim, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/lib/savings.mjs

@@ -0,0 +1,131 @@
+/**
+ * Session savings meter.
+ *
+ * Copyright (c) 2026 Operating Tag. All rights reserved. Released under the CC BY-NC-ND 4.0 licence.
+ *
+ * @file    savings.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * WHY THIS EXISTS
+ *     The whole reason to use Uncle Sam is that web replies do not cost money per token. Until now that
+ *     was a claim the user had to take on trust. This counts what actually went through the web route and
+ *     prices it at the published API rate, so the saving is a number that climbs in front of them.
+ *
+ * WHAT IS COUNTED, AND WHAT IS HONEST ABOUT IT
+ *     Tokens are ESTIMATED from character counts, not measured - the web page does not report usage. The
+ *     estimate is the standard four-characters-per-token rule, which is close for English and English
+ *     code and drifts for other scripts. So the figure is labelled as an estimate everywhere it appears,
+ *     and the price is a configurable rate rather than a promise.
+ *
+ *     Only calls that really went through the page are counted. A call that failed, or that the API
+ *     served, contributes nothing - counting those would inflate the number the product is sold on.
+ */
+
+/**
+ * Published DeepSeek API prices, in US dollars per one million tokens.
+ *
+ * These are the rates a person would actually pay for the same work through the API, which is the number
+ * the saving is measured against. They change; the caller may override them from configuration, and the
+ * panel states which rate it used.
+ */
+export const DEFAULT_PRICES = {
+  inputPerMTok: 0.27,
+  outputPerMTok: 1.10,
+  currency: 'USD',
+  label: 'DeepSeek API list price',
+};
+
+/** Four characters per token, the same rule the rest of the plugin uses for usage reporting. */
+export function estimateTokens(text) {
+  return Math.max(1, Math.round(String(text ?? '').length / 4));
+}
+
+export function money(tokens, perMTok) {
+  return (tokens / 1_000_000) * perMTok;
+}
+
+/**
+ * Running totals for one plugin lifetime.
+ *
+ * Deliberately in memory only: a figure that survives restarts invites people to treat it as billed
+ * truth, and it is an estimate. A session is a session.
+ */
+export class SavingsMeter {
+  #calls = 0;
+  #inputTokens = 0;
+  #outputTokens = 0;
+  #startedAt = Date.now();
+  #lastCallAt = null;
+  #prices;
+
+  constructor(prices = {}) {
+    /*
+     * Only override a default with a number that really is a number.
+     *
+     * The prices arrive from plugin configuration, where an unset field is not absent - it is `undefined`,
+     * and an explicit `undefined` still overwrites the default when spread. That silently priced output at
+     * `undefined`, which turns the whole figure into NaN and arrives at the panel as null. A non-numeric
+     * rate now falls back to the published default instead of poisoning the total.
+     */
+    const given = prices && typeof prices === 'object' ? prices : {};
+    const pick = (value, fallback) => {
+      const n = Number(value);
+      return value !== undefined && value !== null && Number.isFinite(n) ? n : fallback;
+    };
+
+    this.#prices = {
+      ...DEFAULT_PRICES,
+      inputPerMTok: pick(given.inputPerMTok, DEFAULT_PRICES.inputPerMTok),
+      outputPerMTok: pick(given.outputPerMTok, DEFAULT_PRICES.outputPerMTok),
+      currency:
+        typeof given.currency === 'string' && given.currency.trim()
+          ? given.currency.trim().toUpperCase()
+          : DEFAULT_PRICES.currency,
+      label:
+        typeof given.label === 'string' && given.label.trim() ? given.label.trim() : DEFAULT_PRICES.label,
+    };
+  }
+
+  get prices() {
+    return { ...this.#prices };
+  }
+
+  /** Record one completed web call. Called only when the reply actually came back. */
+  record({ inputTokens = 0, outputTokens = 0 } = {}) {
+    this.#calls += 1;
+    this.#inputTokens += Math.max(0, Number(inputTokens) || 0);
+    this.#outputTokens += Math.max(0, Number(outputTokens) || 0);
+    this.#lastCallAt = Date.now();
+  }
+
+  /** Everything the panel needs, with the money already worked out. */
+  snapshot() {
+    const input = this.#inputTokens;
+    const output = this.#outputTokens;
+    const total = input + output;
+    const inputValue = money(input, this.#prices.inputPerMTok);
+    const outputValue = money(output, this.#prices.outputPerMTok);
+
+    return {
+      calls: this.#calls,
+      inputTokens: input,
+      outputTokens: output,
+      totalTokens: total,
+      /** What the same tokens would have cost through the API. */
+      saved: Number((inputValue + outputValue).toFixed(4)),
+      currency: this.#prices.currency,
+      priceLabel: this.#prices.label,
+      estimated: true,
+      startedAt: this.#startedAt,
+      lastCallAt: this.#lastCallAt,
+      // A human-readable line the panel can show without formatting anything itself.
+      summary:
+        this.#calls === 0
+          ? 'No web calls yet this session'
+          : `${this.#calls} call${this.#calls === 1 ? '' : 's'} · ~${total.toLocaleString()} tokens · ` +
+            `~${this.#prices.currency} ${(inputValue + outputValue).toFixed(2)} saved`,
+    };
+  }
+}