@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.0

package/index.js

@@ -0,0 +1,1411 @@
+/**
+ * DeepSeek web-chat provider for the harness.
+ *
+ * Registers the provider route `deepseek-web`, backed by a real browser driving chat.deepseek.com.
+ *
+ * @file    index.js
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * WHY THIS PROVIDER EXISTS
+ *     A harness can only talk to a provider it has an adapter for, and an adapter is allowed to be slow
+ *     or clever underneath as long as it speaks `StreamChunk`. This one speaks it by driving the public
+ *     web product, which means the account in the browser is the account being used: no API key, no
+ *     per-token billing, and the same model the person already has open in a tab.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *     It does not call the site's private HTTP API. That API requires a proof-of-work challenge per
+ *     message and sits behind a bot gate; re-implementing either would break whenever the site changed
+ *     and would look like a network fault when it did. The page solves its own challenges, so the
+ *     adapter never has to know they exist.
+ *
+ * THE HONEST LIMITATION
+ *     A web chat cannot return a structured tool call. Tool use is therefore emulated through the
+ *     prompt and recovered by parsing JSON out of the reply, which is described in `lib/prompt.mjs`.
+ *     Emulation is weaker than a native tool channel: a model that ignores the instruction produces
+ *     prose instead of a call, and the harness sees no tool use that turn.
+ */
+
+import { ChatSession, WebChatError } from './lib/engine.mjs';
+import { buildPrompt, messageText, parseToolCall, stripToolCall, streamSafeCut } from './lib/prompt.mjs';
+import { SavingsMeter, estimateTokens as estimateTokensForSavings } from './lib/savings.mjs';
+import { Locales } from './lib/i18n.mjs';
+import { Prefs, prefsPath, profileDir } from './lib/prefs.mjs';
+
+// `llm` is required: without it there is no provider to register.
+//
+// The other three are REQUIRED for the switch and were the reason it silently did nothing. In Cordis a
+// service is only resolvable through `ctx.get` once it is declared here; an undeclared one resolves to
+// undefined, no error is raised, and every call that guarded on it quietly took the fallback path. That
+// is how the switch came to save a default while the open conversation kept answering from the API.
+export const inject = ['llm', 'agentDefaultModel', 'sessionController', 'webServer'];
+
+/**
+ * Route switching.
+ *
+ * The client cannot change the model: client services are layout, locale, sessions, slots, theme,
+ * timer and uiWorkspace, and none of them selects a model. The Host can, through
+ * `agentDefaultModel.saveSelection`, which writes the profile. So the switch is a Host route and the
+ * client component is a view over it - one source of truth, and both places that show the switch read
+ * the same state.
+ *
+ * WHY THE PREVIOUS SELECTION IS REMEMBERED
+ *     The left side of the switch must return the person to the model they were actually using, not to
+ *     a hard-coded guess. The first time the switch is moved to WEB the current API selection is stored;
+ *     moving back restores exactly that. Nothing here ever changes the route on its own - the only
+ *     writer is a click.
+ */
+const ROUTE_PATH = '/api/deepseek-web/route';
+const WEB_SELECTION = { provider: 'deepseek-web', model: 'deepseek-chat' };
+
+/** Per-process memory of the API-side selection, so switching back is exact. */
+let lastApiSelection = null;
+
+/**
+ * The previous answer and when it arrived, per conversation.
+ *
+ * Used only to notice that the page served the same answer twice in a row, which is a stuck generation
+ * rather than a new reply. Two facts are stored: the text, and the time. An identical answer minutes
+ * apart is a person asking the same question twice - legitimate - so only a near-immediate repeat counts
+ * as a fault. One small object per live conversation.
+ */
+const lastAnswer = new Map();
+
+function selectionIsWeb(selection) {
+  return Boolean(selection) && selection.provider === 'deepseek-web';
+}
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > 64 * 1024) {
+        reject(new Error('request body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8');
+      if (!text) return resolve({});
+      try {
+        resolve(JSON.parse(text));
+      } catch {
+        reject(new Error('body is not JSON'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+const PROVIDER = 'deepseek-web';
+
+/**
+ * Model identities advertised for this route.
+ *
+ * The web product has TWO switches - DeepThink (a reasoning pass) and Search (read the live web) - and
+ * the harness has no per-call provider-option channel. Rather than hide them in config, they are encoded
+ * in the model name, because the model picker is exactly the place a person already chooses "what kind
+ * of answer do I want". Four combinations, four entries, no hidden state:
+ *
+ *   deepseek-chat             fast, from memory
+ *   deepseek-chat-search      fast, but reads the web first
+ *   deepseek-reasoner         thinks before answering
+ *   deepseek-reasoner-search  thinks, and reads the web
+ */
+/**
+ * The model list, translated.
+ *
+ * Ids never change - they are embedded in saved selections - so only the words a person reads are replaced.
+ * The provider is a browser tab rather than an API, so the descriptions say what the page will actually do.
+ */
+/**
+ * Every key the settings panel draws.
+ *
+ * One list, used by the route and by the locale tests, so a string added to en.json and forgotten here is
+ * caught rather than silently missing. Anything not listed cannot reach the panel.
+ */
+const PANEL_KEYS = [
+  'title', 'buyMeACoffee', 'languageLabel', 'starting', 'switching', 'languageAuto',
+  'routeTitle', 'routeNote', 'pageIntro',
+  'braveTitle', 'braveWhy', 'braveSecurity', 'braveSecurityBody',
+  'bravePrivacy', 'bravePrivacyBody', 'braveQuiet', 'braveQuietBody',
+  'braveInvisible', 'usingBrave', 'usingEdge', 'edgeSwitch', 'getBrave',
+  'statusRunning', 'statusSession', 'statusProvider', 'statusReady', 'statusUsing',
+  'browserListening', 'browserNone', 'sessionSignedIn', 'sessionNotSignedIn',
+  'sessionSignedInButSignInScreen', 'browserNoneFound',
+  'providerRegistered', 'providerMissing', 'readyWeb', 'readyApiFallback', 'readyApiOnly',
+  'savingsTitle', 'savingsEmpty', 'savingsEstimatedNote', 'savingsDetail',
+  'trustTitle', 'trustUsesSession', 'trustLocal', 'trustCounts',
+  'trustNoPassword', 'trustNoProxy', 'trustNoTelemetry',
+  'lastSentTitle', 'toolsOffered',
+  'buttonSignIn', 'buttonOpenChat', 'buttonCheck', 'buttonFresh', 'buttonShow', 'buttonNeedsBrowser',
+  'noteFirstRun',
+  'authorIntro', 'authorAsk', 'authorCloser',
+  'specTitle', 'specCpu', 'specNpu', 'specGpu', 'specRam',
+  'specStorage', 'specDisplay', 'specPorts', 'specPower',
+  'apiModelHint',
+];
+
+function localizedModels(t) {
+  const names = {
+    'deepseek-chat': ['modelChatName', 'modelChatDesc'],
+    'deepseek-chat-search': ['modelChatSearchName', 'modelChatSearchDesc'],
+    'deepseek-reasoner': ['modelReasonerName', 'modelReasonerDesc'],
+    'deepseek-reasoner-search': ['modelReasonerSearchName', 'modelReasonerSearchDesc'],
+  };
+  return MODELS.map((m) => {
+    const keys = names[m.id];
+    if (!keys) return m;
+    return { ...m, name: t(keys[0]), description: t(keys[1]) };
+  });
+}
+
+const MODELS = [
+  {
+    provider: PROVIDER,
+    id: 'deepseek-chat',
+    name: 'DeepSeek Chat (web)',
+    description: 'Fast web chat. DeepThink off, Search off.',
+    inputModalities: ['text'],
+    switches: { deepThink: false, search: false },
+  },
+  {
+    provider: PROVIDER,
+    id: 'deepseek-chat-search',
+    name: 'DeepSeek Chat + Search (web)',
+    description: 'Fast web chat with live web search. DeepThink off, Search on.',
+    inputModalities: ['text'],
+    switches: { deepThink: false, search: true },
+  },
+  {
+    provider: PROVIDER,
+    id: 'deepseek-reasoner',
+    name: 'DeepSeek Reasoner (web)',
+    description: 'Thinks before answering. DeepThink on, Search off. Only the answer is forwarded.',
+    inputModalities: ['text'],
+    switches: { deepThink: true, search: false },
+  },
+  {
+    provider: PROVIDER,
+    id: 'deepseek-reasoner-search',
+    name: 'DeepSeek Reasoner + Search (web)',
+    description: 'Thinks, and reads the live web. DeepThink on, Search on.',
+    inputModalities: ['text'],
+    switches: { deepThink: true, search: true },
+  },
+];
+
+/** Resolve a model id to its switch states, falling back to the configured default model. */
+function switchesFor(modelId, config) {
+  const found = MODELS.find((m) => m.id === modelId);
+  if (found) return found.switches;
+  return {
+    deepThink: config.deepThink === true,
+    search: config.search === true,
+  };
+}
+
+const CONTEXT_TOKENS = 64000;
+
+/** A rough token count. Used only for usage reporting, never for routing or truncation. */
+function estimateTokens(text) {
+  return Math.max(1, Math.round(String(text ?? '').length / 4));
+}
+
+function textOf(options) {
+  const parts = [];
+  if (options.system) parts.push(options.system);
+  for (const m of options.messages ?? []) {
+    const c = m?.content;
+    if (typeof c === 'string') parts.push(c);
+    else if (Array.isArray(c)) {
+      for (const b of c) if (b?.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+    }
+  }
+  return parts.join('\n');
+}
+
+export function apply(ctx, config = {}) {
+  const settings = {
+    port: Number(config.port) || 9222,
+    defaultModel: String(config.defaultModel || 'deepseek-chat'),
+    showBrowser: config.showBrowser !== false,
+    // Fallbacks used only for an unrecognised model id; the model list is the real control surface.
+    deepThink: config.deepThink === true,
+    search: config.search === true,
+    /**
+     * How the browser should present itself.
+     *
+     *   'headless'   invisible. Chromium REFUSES headless on a profile a visible browser has used
+     *                ("Multiple targets are not supported in headless mode"), so this needs a profile of
+     *                its own - which means its own one-time sign-in. That trade is why the default is
+     *                headless only for people who have completed that sign-in; the preflight decides.
+     *   'minimized'  a real window, started minimised. Uses the existing profile and session, so no
+     *                second login, and it still stays out of the way.
+     *   'visible'    a normal window. Only useful for watching what the plugin is doing.
+     */
+    // Headless is deliberately absent: CloudFront answers it with 403, measured with a clean profile and
+    // both the modern and legacy flags, so it can never work. Only the two windowed modes remain.
+    // The window is minimised after launch unless the person explicitly asks to watch it. There is no
+    // mode to choose: Brave is used when present and Edge otherwise, and headless is not possible.
+    autoMinimise: config.autoMinimise !== false,
+    // Whether the browser conversation continues turn to turn. The default is on; `false` makes every
+    // call start a fresh chat.
+    continueChat: config.continueChat !== false,
+  };
+
+  // Captured here, while `llm` is definitely mounted on this context. The web-server route handler runs
+  // in a different context that cannot resolve `llm`, so it must not try to look the service up itself -
+  // that threw "cannot get required service llm in inactive context" and made every readiness check lie.
+  const llmService = ctx.get('llm') ?? ctx.llm;
+
+  // Browser launch state, shared with the route so the badge can say "starting" instead of "unavailable".
+  // `launching` distinguishes "not started yet" from "starting right now", which is the difference
+  // between a badge that looks broken and one that explains a ten-second pause.
+  let launching = false;
+  let browserLaunchError;
+
+  const session = new ChatSession({ port: settings.port, autoMinimise: settings.autoMinimise });
+
+  // Counts what the web route saved this session. In memory only: the figure is an estimate and should
+  // not survive a restart looking like a bill.
+  /**
+   * Durable plugin state. The language choice lives here so a restart cannot silently lose it - the bug
+   * that made the panel go back to English and answers come back in English.
+   */
+  const prefsDir = profileDir();
+  const prefs = prefsDir ? new Prefs(prefsPath(prefsDir)) : null;
+
+  /** A language the reader picked in the panel; empty means follow the harness. */
+  let chosenLanguage = String((prefs && prefs.get('language')) || '');
+  if (chosenLanguage) {
+    try {
+      console.log(`[deepseek-web] language restored from the last session: ${chosenLanguage}`);
+    } catch {
+      /* a logger that throws must not stop activation */
+    }
+  }
+
+  const locales = new Locales(new URL('./locale', import.meta.url).pathname.replace(/^\//, ''), config.language);
+
+  /**
+   * The translator for the language the harness is currently in.
+   *
+   * The harness owns the language choice - it has its own settings row for it - so this asks rather than
+   * decides. When the service is absent, or the language has no translation, English answers, because a
+   * panel in the wrong language is still usable and a panel of key names is not.
+   */
+  function translator() {
+    if (chosenLanguage) {
+      // An override naming a language this package cannot speak falls through to the harness value rather
+      // than silently showing English under the wrong name.
+      if (locales.available().some((l) => l.code === chosenLanguage)) return locales.pick(chosenLanguage);
+    }
+    let active = '';
+    try {
+      const service = ctx.get('locale');
+      active = service?.getSnapshot?.()?.active ?? '';
+    } catch {
+      // No locale service on this profile; English it is.
+    }
+    return locales.pick(active);
+  }
+
+  /**
+   * Every string the panel draws, keyed as locale/en.json is keyed.
+   *
+   * Placeholders stay as %s on purpose: the values they stand for are runtime facts the panel already
+   * holds (the port, the character count), so it fills them and the host never has to format prose.
+   */
+  function stringsForPanel() {
+    const t = translator();
+    const out = { metaTitle: t.meta('title'), metaDescription: t.meta('description') };
+    for (const key of PANEL_KEYS) out[key] = t(key);
+    return out;
+  }
+
+  const savings = new SavingsMeter({
+    inputPerMTok: Number(config.inputPricePerMTok) || undefined,
+    outputPerMTok: Number(config.outputPricePerMTok) || undefined,
+    currency: config.currency ? String(config.currency) : undefined,
+  });
+
+  /**
+   * Count one completed web call toward the session saving.
+   *
+   * Only called where a reply actually came back. A failed call, or one the API served, contributes
+   * nothing - counting those would inflate the number the product is sold on.
+   */
+  let lastRecordedAt = 0;
+  /** The most recent text typed into the browser, for the "what am I sending" panel. */
+  let lastPromptPreview = null;
+  function recordWebCall(inputText, outputText) {
+    // The three usage sites pass their own numbers in; this guards against a double count when a
+    // single turn emits usage more than once.
+    const now = Date.now();
+    if (now - lastRecordedAt < 50) return;
+    lastRecordedAt = now;
+    savings.record({
+      inputTokens: estimateTokensForSavings(inputText),
+      outputTokens: estimateTokensForSavings(outputText),
+    });
+  }
+
+  const adapter = {
+    providerInfo(provider) {
+      return { id: provider || PROVIDER, name: 'DeepSeek (web chat)' };
+    },
+
+    providerRetryPolicy() {
+      // The browser path fails in ways an HTTP retry cannot fix (a closed tab, a signed-out session),
+      // so retries are shallow and slow rather than aggressive.
+      return {
+        mode: 'normal',
+        maxRetries: 1,
+        retryableCodes: ['NO_FIRST_TOKEN'],
+        initialDelayMs: 1200,
+        maxDelayMs: 4000,
+        jitterRatio: 0.25,
+      };
+    },
+
+    imageRequestPricing() {
+      return undefined;
+    },
+
+    imageRequestTarget() {
+      const err = new Error('deepseek-web accepts text only; it cannot carry images');
+      err.code = 'UNSUPPORTED_IMAGE';
+      throw err;
+    },
+
+    async listModels() {
+      // Rebuilt per call so the picker speaks the language the harness is in now, not the one that was
+      // active when the plugin loaded.
+      return localizedModels(translator());
+    },
+
+    async resolveModel(provider, model) {
+      const known = MODELS.find((m) => m.id === model) ?? MODELS[0];
+      return {
+        ...known,
+        provider: provider || PROVIDER,
+        model: known.id,
+        id: known.id,
+        context: { contextWindow: CONTEXT_TOKENS },
+        defaultMaxTokens: 8192,
+      };
+    },
+
+    async prepareCall(provider, model) {
+      const resolved = await adapter.resolveModel(provider, model);
+      return {
+        model: resolved,
+        stream: (options) => adapter.stream(options),
+      };
+    },
+
+    /**
+     * Stream one call.
+     *
+     * The shape of this generator is fixed by the harness contract: a block must be opened before any
+     * delta refers to it, and exactly one terminal `finish` chunk must end the stream. Everything
+     * between those two points is the browser's problem, translated into text deltas.
+     */
+    async *stream(options) {
+      /*
+       * Continue the browser chat rather than restarting it.
+       *
+       * This is what makes the WEB route useful: the conversation the person watches in the harness is
+       * the conversation in the browser tab, and it keeps its own memory turn to turn. Resetting on every
+       * call meant the whole transcript was re-typed into a fresh chat each time, which looked like the
+       * harness "sending everything twice" and cost the browser a full re-read per message.
+       *
+       * A call with no prior user turn cannot continue anything, so it starts clean either way.
+       */
+      const continueChat = settings.continueChat !== false;
+      /*
+       * The language the panel is in, so the page knows what language to answer in.
+       *
+       * The NAME is the English one: an instruction reading "answer in Spanish" is unambiguous where
+       * "answer in Español" asks the model to translate the instruction before following it. English
+       * itself is dropped inside buildPrompt, because an English reader needs no telling.
+       */
+      const prompt = buildPrompt({ ...options, continueChat, answerIn: translator().languageNameInEnglish });
+      const model = options.model || settings.defaultModel;
+
+      if (!prompt.text) {
+        yield {
+          type: 'finish',
+          reason: { kind: 'error', failure: { message: 'empty prompt', code: 'EMPTY_PROMPT' } },
+        };
+        return;
+      }
+
+      const wantTools = Array.isArray(options.tools) && options.tools.length > 0;
+      const switches = switchesFor(model, settings);
+      // A search answer is delivered as two blocks: what was searched and where it looked, then the
+      // answer. That means the text cannot stream while search is on - the sources are only readable
+      // once the answer settles - so search calls buffer and plain calls still stream token by token.
+      const wantSearch = switches.search === true;
+
+      /**
+       * Internal calls get their own slot, never the person's chat.
+       *
+       * The harness asks the model to summarise a session for its title and to compact long history.
+       * Those requests carry `purpose`, and routing them into the same browser chat is what produced odd
+       * extra messages there: a chat titled "hello" would suddenly contain a request to summarise the
+       * conversation. They are short, self-contained, and must not continue anything, so each purpose
+       * gets a key of its own and therefore a fresh chat.
+       */
+      const purpose = options.purpose;
+      const conversationKey = purpose
+        ? `purpose:${purpose}`
+        : String(options.sessionId ?? 'unattributed');
+
+      // Tool calls need the whole transcript in view, because the reply must be checked for JSON that
+      // names a tool. A continuing chat would only see the newest turn, so those calls start clean.
+      // A purpose call never continues: it asks its own question and must not inherit a conversation.
+      const effectiveContinue = !purpose && prompt.continuing && !wantTools;
+      let sources = { domains: [], links: [] };
+
+      let assembled = '';
+      // `emitted` must match the concatenation of every delta in the block, including the route label, or
+      // the committed block-end text disagrees with what streamed and the harness rightly rejects it.
+      let emitted = '';
+      /*
+       * How far into `assembled` has already been shown.
+       *
+       * The old code decided once, from the reply's FIRST character, whether to stream or to buffer. That is
+       * how the tool envelope reached the screen: this reply opened with prose, so it was streamed whole, and
+       * the JSON arrived on the last chunk where scrubbing was too late. Position is tracked instead -
+       * everything up to the first brace that could still become a call is shown, the rest waits.
+       */
+      let shown = 0;
+
+      /*
+       * Name the web route in the answer itself.
+       *
+       * A badge beside the composer has to be remembered and looked for; a name above the reply is read
+       * whether the person meant to check or not. Since nobody is ever quite sure which engine answered,
+       * the answer says so: a red dot and "Uncle Sam" precede every WEB reply, and API replies carry
+       * nothing, so the label's presence IS the signal.
+       *
+       * The red dot is the joke. "Uncle Sam" alone would read as a claim of authority; a red light beside
+       * it reads as "this one came from the other side, and we both know it". It goes in as plain text at
+       * the head of the first block rather than as UI decoration, because a transcript that is copied,
+       * exported or read back later must still show which route produced it.
+       */
+      // Internal calls (session titles, compaction) carry no label: nothing shows their text to a person,
+      // and a title that began "Uncle Sam" would end up in the sidebar.
+      const WEB_LABEL = purpose ? '' : '\u{1F534} Uncle Sam\n\n';
+
+      try {
+        if (!wantSearch) {
+          yield { type: 'block-start', index: 0, blockType: 'text' };
+          /*
+           * The label is NOT emitted here.
+           *
+           * It used to be, before anything was known about the answer. When the page returned nothing at
+           * all, the person was left with "🔴 Uncle Sam" and no words after it - recorded on screen, and it
+           * reads as the plugin failing rather than the page failing. It now goes out with the first real
+           * text, so a reply can never be a bare signature.
+           */
+        }
+
+        // Keep a bounded copy for the panel: enough to recognise what was sent, not the whole document.
+        lastPromptPreview = {
+          chars: prompt.text.length,
+          text: prompt.text.length > 2000 ? prompt.text.slice(0, 2000) + '\u2026' : prompt.text,
+          at: Date.now(),
+          tools: Array.isArray(options.tools) ? options.tools.length : 0,
+          // The tool preamble on its own, so a person can see exactly what the page was told about tools
+          // without hunting for it inside the message. A prompt without a blank line has no separate
+          // preamble, so it is reported in full rather than with its last character cut off.
+          preamble:
+            prompt.text.includes('Tools: ')
+              ? prompt.text.slice(0, Math.max(0, prompt.text.indexOf('\n\n')))
+              : prompt.text.slice(0, 400),
+        };
+
+        for await (const chunk of session.ask(prompt.text, {
+          signal: options.signal,
+          deepThink: switches.deepThink,
+          search: switches.search,
+          // Pass the decision down so the engine does not reset the page.
+          continueChat: effectiveContinue,
+          // Which harness conversation the browser chat belongs to; a change resets it.
+          conversationKey,
+        })) {
+          if (chunk.done) {
+            assembled = chunk.text;
+            if (chunk.sources) sources = chunk.sources;
+            continue;
+          }
+          if (!chunk.text) continue;
+          assembled += chunk.text;
+
+          if (wantSearch) {
+            // held for ordering; nothing is emitted until the sources are known
+            continue;
+          }
+
+          /*
+           * Show only what cannot become a tool call.
+           *
+           * `streamSafeCut` answers "how far is safe right now" - up to the first brace that might still
+           * grow into {"tool":...}. Ordinary prose passes straight through, braces included, so the stream
+           * stays live; it simply stops one brace early when a call might be starting.
+           */
+          const safe = streamSafeCut(assembled);
+          if (safe > shown) {
+            const out = assembled.slice(shown, safe);
+            shown = safe;
+            if (!emitted) {
+              // First real text: the label goes out with it, never on its own.
+              emitted += WEB_LABEL;
+              yield { type: 'text-delta', index: 0, text: WEB_LABEL };
+            }
+            emitted += out;
+            yield { type: 'text-delta', index: 0, text: out };
+          }
+        }
+
+        // Search answers are emitted as two visible blocks so the transcript shows BOTH what was asked
+        // of the web and what came back, before the answer that used it.
+        if (wantSearch) {
+          /*
+           * The query is the person's newest message - and ONLY the person's.
+           *
+           * The harness files its own notices under `role: 'user'`: time context, runtime context, the
+           * "[model changed: …]" line written when the model is switched mid-conversation, and more.
+           * Taking the newest `role: 'user'` entry therefore took whatever machinery was written last.
+           * Recorded: the person switched from Web Chat to Web Reasoner+Search and the search query became
+           * "[model changed: assistant turns above this point were generated by …]", so the search found
+           * nothing and the answer was written from memory instead of from the web.
+           */
+          const isFromPerson = (m) => {
+            if (m?.role !== 'user') return false;
+            const kind = m?.source?.kind;
+            return typeof kind !== 'string' || kind === 'user';
+          };
+          const asked = [...(options.messages ?? [])].reverse().find(isFromPerson);
+          const query = messageText(asked).replace(/\s+/g, ' ').trim().slice(0, 240);
+          const domains = (sources?.domains ?? []).slice(0, 12);
+          const links = (sources?.links ?? []).slice(0, 5);
+
+          /*
+           * A search reply must not lie about what backing it had.
+           *
+           * Search was ON, so the person paid for a web lookup and expects a web-backed answer. When the
+           * page reports no sources the answer is written from the model's own memory, and saying so is
+           * the difference between an honest answer and one that looks researched. Recorded: an answer
+           * presented under a "Web search" heading that had used no search results at all.
+           */
+          const lines = [`Web search — "${query}"`];
+          lines.push(
+            domains.length
+              ? `Sources (${domains.length}): ${domains.join(' · ')}`
+              : 'Sources: none — this answer comes from the model\'s own memory, not from a web search',
+          );
+          if (links.length) lines.push(`Links: ${links.join(' ')}`);
+          const summary = lines.join('\n');
+
+          // The search summary opens the reply, so the route label belongs at its head. The answer block
+          // below is then plain: one name per reply, not one per block.
+          const summaryWithLabel = WEB_LABEL + summary;
+          yield { type: 'block-start', index: 0, blockType: 'text' };
+          yield { type: 'text-delta', index: 0, text: summaryWithLabel };
+          yield { type: 'block-end', index: 0, block: { type: 'text', text: summaryWithLabel } };
+
+          const answerText = stripToolCall(assembled);
+          yield { type: 'block-start', index: 1, blockType: 'text' };
+          if (answerText) yield { type: 'text-delta', index: 1, text: answerText };
+          yield { type: 'block-end', index: 1, block: { type: 'text', text: answerText } };
+
+          /*
+           * Search and tools are not mutually exclusive. Before this, a reply that carried both ended
+           * here without ever being parsed, so a raw tool envelope landed in the answer block. The call
+           * block is emitted after the answer, exactly as the plain path does.
+           */
+          if (wantTools) {
+            const call = parseToolCall(assembled);
+            if (call) {
+              const callId = `webcall_${Date.now().toString(36)}`;
+              yield { type: 'block-start', index: 2, blockType: 'tool-call' };
+              yield {
+                type: 'tool-call-delta',
+                index: 2,
+                id: callId,
+                name: call.name,
+                argumentsDelta: call.arguments,
+              };
+              yield {
+                type: 'block-end',
+                index: 2,
+                block: { type: 'tool-call', id: callId, name: call.name, arguments: call.arguments },
+              };
+              recordWebCall(prompt.text, answerText);
+              yield {
+                type: 'usage',
+                usage: {
+                  inputTokens: estimateTokens(prompt.text),
+                  outputTokens: estimateTokens(assembled),
+                  totalTokens: estimateTokens(prompt.text) + estimateTokens(assembled),
+                },
+              };
+              yield { type: 'finish', reason: { kind: 'tool-calls' } };
+              return;
+            }
+          }
+
+          recordWebCall(prompt.text, answerText);
+          yield {
+            type: 'usage',
+            usage: {
+              inputTokens: estimateTokens(prompt.text),
+              outputTokens: estimateTokens(assembled),
+              totalTokens: estimateTokens(prompt.text) + estimateTokens(assembled),
+            },
+          };
+          yield { type: 'finish', reason: { kind: 'stop' } };
+          return;
+        }
+
+        if (wantTools) {
+          const call = parseToolCall(assembled);
+          if (call) {
+            // A tool call was made. Any prose the model wrapped around it belongs in the text block;
+            // the JSON itself must not reach the transcript.
+            /*
+             * Emit only the part of the prose that has not streamed yet.
+             *
+             * `emitted` includes the route label, so comparing the prose against it used to fail for every
+             * turn and the WHOLE prose was appended a second time - the streamed prefix appeared twice in
+             * the transcript. The streamed part is exactly the safe prefix `assembled.slice(0, shown)`,
+             * which stripping never touches, so the unseen remainder is simply everything after `shown`.
+             */
+            /*
+             * Scrub ONLY the held portion, and never index into the whole reply.
+             *
+             * The previous expression was `prose.slice(shown)`, where `prose` is the SCRUBBED WHOLE reply and
+             * `shown` is an offset into the UNSCRUBBED one. `stripToolCall` ends with `.trim()`, so a reply
+             * that began with whitespace is shorter than its offset - and the tail then started mid-word.
+             * Measured on four shapes:
+             *
+             *     "\n\nHi. {…} more text here"   became  "Hi. ore text here"
+             *     "  Hello there. {…} and then"  became  "Hello there. nd then"
+             *     "\n\n{…} trailing words"       became  "ailing words"
+             *
+             * Characters were silently deleted from the person's answer whenever the model prefixed prose
+             * with a newline - which it does constantly. Scrubbing the held slice keeps every offset inside
+             * one string, so the two numbers can never disagree.
+             */
+            /*
+             * The label goes out even when there is no prose, because a call-only turn has to say which
+             * route made the call.
+             *
+             * MEASURED: three live cases in a row produced a bare tool call and no text, so `emitted` stayed
+             * empty, the label was never written, and the turn carried no signature at all. That breaks the
+             * one rule this label exists for - the person must always be able to tell the web route from the
+             * API route. A tool call is not an empty reply: something happened, so naming the route above it
+             * is information rather than noise. (An empty reply with no call is a different case and still
+             * fails with an error, unlabelled, because there is nothing to sign.)
+             */
+            if (!emitted) {
+              emitted += WEB_LABEL;
+              yield { type: 'text-delta', index: 0, text: WEB_LABEL };
+            }
+            const tail = stripToolCall(assembled.slice(shown));
+            if (tail) {
+              emitted += tail;
+              yield { type: 'text-delta', index: 0, text: tail };
+            }
+            yield { type: 'block-end', index: 0, block: { type: 'text', text: emitted } };
+
+            const callId = `webcall_${Date.now().toString(36)}`;
+            yield { type: 'block-start', index: 1, blockType: 'tool-call' };
+            yield {
+              type: 'tool-call-delta',
+              index: 1,
+              id: callId,
+              name: call.name,
+              argumentsDelta: call.arguments,
+            };
+            yield {
+              type: 'block-end',
+              index: 1,
+              block: { type: 'tool-call', id: callId, name: call.name, arguments: call.arguments },
+            };
+            recordWebCall(prompt.text, emitted);
+            yield {
+              type: 'usage',
+              usage: {
+                inputTokens: estimateTokens(prompt.text),
+                outputTokens: estimateTokens(assembled),
+                totalTokens: estimateTokens(prompt.text) + estimateTokens(assembled),
+              },
+            };
+            yield { type: 'finish', reason: { kind: 'tool-calls' } };
+            return;
+          }
+        }
+
+        /*
+         * Release whatever was held, scrubbed exactly once.
+         *
+         * Only the held portion needs scrubbing: what was already shown contains no tool object, because the
+         * scanner stopped one brace short of any. Scrubbing the tail and appending it keeps the committed
+         * block equal to the deltas that were yielded, which the harness checks.
+         */
+        const held = stripToolCall(assembled.slice(shown));
+        if (held) {
+          if (!emitted) {
+            emitted += WEB_LABEL;
+            yield { type: 'text-delta', index: 0, text: WEB_LABEL };
+          }
+          emitted += held;
+          yield { type: 'text-delta', index: 0, text: held };
+        }
+
+        /*
+         * An empty answer is a fault, not a reply.
+         *
+         * The page does occasionally return nothing. Because the label used to be emitted up front, the
+         * person saw "🔴 Uncle Sam" with no words and no explanation. Nothing is emitted now, and the turn
+         * ends as an error, which is what actually happened.
+         */
+        if (!assembled.trim()) {
+          yield { type: 'block-end', index: 0, block: { type: 'text', text: emitted } };
+          yield {
+            type: 'finish',
+            reason: {
+              kind: 'error',
+              failure: {
+                message: 'the browser page returned an empty answer — send it again, or start a fresh chat',
+                code: 'WEB_CHAT_EMPTY',
+              },
+            },
+          };
+          return;
+        }
+
+        /*
+         * An identical repeat is a fault too.
+         *
+         * The page sometimes serves the previous answer again - a stuck generation rather than a new one.
+         * Showing it twice teaches the person that this plugin repeats itself, so it is reported instead.
+         * Two guards keep this from firing on honest traffic: the answer must be long (an "ok" twice is
+         * plausible, a paragraph twice is not), and it must arrive within a minute of the previous one
+         * (the same question asked an hour later, answered the same way, is a correct answer).
+         */
+        const answerSignature = assembled.replace(/\s+/g, ' ').trim();
+        const previous = lastAnswer.get(conversationKey);
+        lastAnswer.set(conversationKey, { text: answerSignature, at: Date.now() });
+        if (
+          previous &&
+          previous.text === answerSignature &&
+          answerSignature.length > 40 &&
+          Date.now() - previous.at < 60_000
+        ) {
+          yield { type: 'block-end', index: 0, block: { type: 'text', text: emitted } };
+          yield {
+            type: 'finish',
+            reason: {
+              kind: 'error',
+              failure: {
+                message:
+                  'the browser page repeated its previous answer word for word — start a fresh chat and ask again',
+                code: 'WEB_CHAT_REPEATED',
+              },
+            },
+          };
+          return;
+        }
+
+        yield { type: 'block-end', index: 0, block: { type: 'text', text: emitted } };
+        recordWebCall(prompt.text, emitted);
+        yield {
+          type: 'usage',
+          usage: {
+            inputTokens: estimateTokens(prompt.text),
+            outputTokens: estimateTokens(assembled),
+            totalTokens: estimateTokens(prompt.text) + estimateTokens(assembled),
+          },
+        };
+        yield { type: 'finish', reason: { kind: 'stop' } };
+      } catch (err) {
+        const aborted = err?.code === 'ABORTED' || err?.name === 'AbortError';
+        if (!aborted && emitted) {
+          yield { type: 'block-end', index: 0, block: { type: 'text', text: emitted } };
+        }
+        yield {
+          type: 'finish',
+          reason: aborted
+            ? { kind: 'aborted', failure: { message: 'cancelled', code: 'ABORTED' } }
+            : {
+                kind: 'error',
+                failure: {
+                  message: err?.message ?? String(err),
+                  code: err?.code ?? (err instanceof WebChatError ? 'WEB_CHAT' : 'WEB_CHAT_UNKNOWN'),
+                },
+              },
+        };
+      }
+    },
+  };
+
+  const registration = ctx.llm.registerAdapter([PROVIDER], adapter);
+
+  // ---------------------------------------------------------------- route switch
+  //
+  // The route is optional: a profile without the web server still gets a working provider, and the
+  // switch simply does not appear. That keeps a deployment without the Web app from failing to mount.
+  let routeDisposer = null;
+  // Declared alongside routeDisposer, not inside the block that registers it: the cleanup closure below
+  // lives outside that block, and a `let` inside it would be invisible here - a ReferenceError on
+  // dispose, which is exactly when a cleanup bug is least welcome.
+  let setupDisposer = null;
+  const defaultModel = ctx.get('agentDefaultModel');
+  const sessionController = ctx.get('sessionController');
+  const server = ctx.get('webServer');
+
+  // A missing service used to be invisible; now it is reported in every reply so the cause of a switch
+  // that does nothing is on screen instead of inferred. `missing` is what the route echoes back.
+  const missing = [];
+  if (!defaultModel) missing.push('agentDefaultModel');
+  if (!sessionController) missing.push('sessionController');
+  if (!server) missing.push('webServer');
+  if (missing.length) {
+    try {
+      console.error(`[deepseek-web] Host services unavailable: ${missing.join(', ')}`);
+    } catch {
+      /* a logger that throws must not stop activation */
+    }
+  }
+
+  /**
+   * Apply a selection to the session the person is looking at, not just to future ones.
+   *
+   * `agentDefaultModel` changes what a NEW session starts with; the open conversation keeps the model
+   * it began on. That is why flipping the switch used to leave the current chat answering from the API
+   * while the badge said WEB - the switch was correct and the conversation was simply not listening.
+   * `sessionController.selectModel` is the call that changes the live session.
+   *
+   * A missing sessionId is not a failure: it means no conversation is open, and saving the default is
+   * all that can be done.
+   */
+  async function applyToSession(sessionId, selection) {
+    if (!sessionId || !sessionController?.selectModel) return { applied: false, reason: 'no session' };
+    try {
+      const result = await sessionController.selectModel({
+        sessionId,
+        provider: selection.provider,
+        model: selection.model,
+        ...(selection.reasoningEffort ? { reasoningEffort: selection.reasoningEffort } : {}),
+      });
+      return { applied: true, selected: result?.selected ?? selection };
+    } catch (err) {
+      return { applied: false, reason: err?.message ?? String(err) };
+    }
+  }
+
+  if (defaultModel && server) {
+    const handler = async (req, res) => {
+      try {
+        const current = defaultModel.currentSelection();
+        const onWeb = selectionIsWeb(current);
+        if (!onWeb && current?.provider && current?.model) {
+          // remember where "API" should return to; only meaningful while we are NOT on web
+          if (current.provider !== PROVIDER) lastApiSelection = { ...current };
+        }
+
+        /**
+         * Two independent facts decide whether "WEB" is honest:
+         *
+         *   1. the adapter is registered, and
+         *   2. a browser is actually reachable to drive.
+         *
+         * Only checking (1) was not enough. The provider registers whenever the plugin mounts, so the
+         * badge read WEB while Brave was closed and no page could possibly answer - and the reply that
+         * arrived came from the API instead. A registered adapter with nothing behind it accepts a call
+         * and fails, and a fallback then bills the wrong route quietly.
+         *
+         * So the browser is probed directly here. `webReady` means "this can work right now", not
+         * "this was configured once".
+         */
+        let adapterRegistered = false;
+        let providerProbeError;
+        try {
+          // `ctx` here is the web-server's context, which cannot see `llm` - reading it inside the
+          // handler throws "cannot get required service \"llm\" in inactive context". The service is
+          // therefore captured once at apply() time, where it is definitely in hand.
+          const llm = llmService ?? ctx.llm;
+          const providers = llm?.listProviders?.() ?? [];
+          adapterRegistered = providers.some((p) => (p?.id ?? p?.provider) === PROVIDER);
+          if (!providers.length) providerProbeError = 'the llm service reported no providers';
+        } catch (err) {
+          adapterRegistered = false;
+          providerProbeError = err?.message ?? String(err);
+        }
+
+        let browserReady = false;
+        let browserReason;
+        try {
+          const res2 = await fetch(`http://127.0.0.1:${settings.port}/json/version`, {
+            signal: AbortSignal.timeout(1200),
+          });
+          browserReady = res2.ok;
+          if (!browserReady) browserReason = `the browser answered ${res2.status}`;
+        } catch {
+          browserReady = false;
+          browserReason = `no browser is listening on port ${settings.port}`;
+        }
+
+        const webReady = adapterRegistered && browserReady;
+        const webReadyReason = !adapterRegistered
+          ? 'the deepseek-web provider is not registered'
+          : browserReady
+            ? undefined
+            : launching
+              ? 'starting the browser…'
+              : browserLaunchError
+                ? `the browser could not start: ${browserLaunchError}`
+                : `${browserReason} — click WEB to start it`;
+
+        // A conversation configured for web while it cannot actually work is NOT on web, whatever the
+        // setting says. Reporting it as `web` is what made the badge lie.
+        const effectiveRoute = onWeb && webReady ? 'web' : 'api';
+
+        if (req.method === 'GET' || req.method === 'HEAD') {
+          json(res, 200, {
+            route: effectiveRoute,
+            configuredRoute: onWeb ? 'web' : 'api',
+            webReady,
+            adapterRegistered,
+            browserReady,
+            launching,
+            browserLaunchError,
+            providerProbeError,
+            webReadyReason,
+            selection: current,
+            apiSelection: lastApiSelection,
+            webSelection: WEB_SELECTION,
+            missing,
+          });
+          return;
+        }
+
+        if (req.method !== 'POST') {
+          json(res, 405, { error: 'method not allowed', allow: 'GET, POST' });
+          return;
+        }
+
+        const body = await readBody(req);
+        const want = String(body.route || '').toLowerCase();
+        if (want !== 'api' && want !== 'web') {
+          json(res, 400, { error: 'route must be "api" or "web"' });
+          return;
+        }
+
+        // Which conversation to change.
+        //
+        // The client is the only thing that knows which chat the person is looking at, so it must send
+        // the id. The Host never infers one: "the newest session" is not "the open session", and a wrong
+        // guess here changes a DIFFERENT conversation mid-answer while the person watches the one they
+        // are in. When the id is missing or unknown the switch still saves the default and reports
+        // `applied: false` with the reason - a visible non-action beats a silent wrong action.
+        const requestedId = typeof body.sessionId === 'string' && body.sessionId ? body.sessionId : null;
+        let sessionResult = {
+          applied: false,
+          reason: requestedId ? 'session controller unavailable' : 'the client did not identify a conversation',
+        };
+
+        if (want === 'web') {
+          if (!onWeb) {
+            if (current?.provider && current?.model && current.provider !== PROVIDER) {
+              lastApiSelection = { ...current };
+            }
+            await defaultModel.saveSelection({ ...WEB_SELECTION });
+          }
+          if (requestedId) sessionResult = await applyToSession(requestedId, WEB_SELECTION);
+
+          /**
+           * Choosing WEB starts the browser.
+           *
+           * Without this, nothing ever began the launch: the adapter starts Brave lazily on the first
+           * call, so the switch reported "unavailable" until a message was sent, and the person had no
+           * way to tell whether WEB would ever work. Asking for the route is the moment the intent is
+           * expressed, so it is the moment to satisfy it.
+           *
+           * The launch is not awaited. It takes about ten seconds and the click must feel immediate; the
+           * `launching` flag lets the badge explain the pause instead of looking stuck.
+           */
+          if (!browserReady && !launching) {
+            launching = true;
+            browserLaunchError = undefined;
+            /**
+             * A launch that never settles must not become a badge that says "starting" forever.
+             *
+             * `ensureReady` polls for the browser and the page, and on a wrong port or a browser that
+             * refuses to start it polls until its own long timeout. If that promise is slow the person
+             * sees an eternal "starting the browser…" with no way out. A watchdog therefore clears the
+             * flag on a hard deadline and records why, so the state always resolves to something a
+             * person can act on.
+             */
+            const watchdog = setTimeout(() => {
+              if (launching) {
+                launching = false;
+                browserLaunchError =
+                  browserLaunchError ||
+                  'the browser did not finish starting within 45 s — click Check now, or switch mode';
+              }
+            }, 45000);
+            session
+              .ensureReady()
+              .then(() => {
+                clearTimeout(watchdog);
+                launching = false;
+              })
+              .catch((err) => {
+                clearTimeout(watchdog);
+                launching = false;
+                browserLaunchError = err?.message ?? String(err);
+              });
+          }
+        } else if (onWeb) {
+          /**
+           * Returning to the API must always be possible.
+           *
+           * A switch that goes one way and refuses to come back is a trap, and refusing is what this did:
+           * when no API model had been remembered - which happens whenever the plugin starts already on
+           * the web route, so no switch was ever observed - it answered with an error instead of moving.
+           *
+           * The order of attempts is: what was remembered, then the deployment default, then ANY routable
+           * non-web model the harness reports. Only when the harness offers no API model at all does this
+           * refuse, and then it says exactly that rather than blaming the person for not having picked one.
+           */
+          let back = lastApiSelection;
+          let returnReason;
+
+          if (!back?.provider || !back?.model) {
+            try {
+              const catalog = await sessionController.modelCatalog?.();
+              const isApi = (sel) => sel && sel.provider && sel.model && sel.provider !== PROVIDER;
+
+              if (isApi(catalog?.default)) {
+                back = { provider: catalog.default.provider, model: catalog.default.model };
+              } else {
+                // The default is the web route, so look through the routable providers for anything else.
+                const groups = Array.isArray(catalog?.groups) ? catalog.groups : [];
+                for (const group of groups) {
+                  if (!group || group.id === PROVIDER) continue;
+                  const first = Array.isArray(group.models) ? group.models[0] : undefined;
+                  if (first?.id) {
+                    back = { provider: group.id, model: first.id };
+                    break;
+                  }
+                }
+                if (!back) {
+                  const routable = Array.isArray(catalog?.routableProviders)
+                    ? catalog.routableProviders.filter((p) => p !== PROVIDER)
+                    : [];
+                  returnReason = routable.length
+                    ? `the harness lists ${routable.join(', ')} but reported no model for it`
+                    : 'the harness reports no API model at all — only the web route is configured. ' +
+                      'Add an API model in Settings → Models and this switch will return to it.';
+                }
+              }
+            } catch (err) {
+              returnReason = `could not read the model catalog: ${err?.message ?? err}`;
+            }
+            if (back && (!back.provider || !back.model)) back = null;
+            if (back) lastApiSelection = { ...back };
+          }
+          if (!back?.provider || !back?.model) {
+            json(res, 409, {
+              error:
+                returnReason ||
+                'no API model to return to. Pick an API model once in the model list and the switch ' +
+                  'will remember it from then on.',
+            });
+            return;
+          }
+          await defaultModel.saveSelection({ ...back });
+          if (requestedId) sessionResult = await applyToSession(requestedId, back);
+        } else if (requestedId) {
+          // already on the API: still make sure THIS conversation is on it
+          sessionResult = await applyToSession(requestedId, current);
+        }
+
+        const after = sessionResult?.selected ?? defaultModel.currentSelection();
+        const afterOnWeb = selectionIsWeb(after);
+        json(res, 200, {
+          route: afterOnWeb && webReady ? 'web' : 'api',
+          configuredRoute: afterOnWeb ? 'web' : 'api',
+          webReady,
+          adapterRegistered,
+          browserReady,
+          launching,
+          browserLaunchError,
+          providerProbeError,
+          webReadyReason,
+          selection: after,
+          apiSelection: lastApiSelection,
+          webSelection: WEB_SELECTION,
+          session: sessionResult,
+          missing,
+          /*
+           * The switch's own words.
+           *
+           * The composer control renders "Uncle Sam" and its tooltip, so it needs the same translated words
+           * the panel has. Sending them here keeps one dictionary for the whole plugin.
+           */
+          strings: {
+            title: translator()('title'),
+            dockApi: translator()('dockApi'),
+            dockWebTip: translator()('dockWebTip'),
+            dockApiTip: translator()('dockApiTip'),
+            starting: translator()('starting'),
+            switching: translator()('switching'),
+          },
+        });
+      } catch (err) {
+        json(res, 500, { error: err?.message ?? String(err) });
+      }
+    };
+
+    try {
+      routeDisposer = server.register({ kind: 'exact', path: ROUTE_PATH, handler });
+    } catch {
+      routeDisposer = null;
+    }
+
+    // ------------------------------------------------------------------ setup panel
+    //
+    // A plugin that needs one manual sign-in has to say so somewhere the person will find it. This route
+    // backs the Settings page: it reports the three facts that decide whether the provider can work, and
+    // it can perform the single action that fixes the common case - open the browser at the sign-in page.
+    //
+    // It never accepts, stores, or returns a credential. The session lives in the browser profile, which
+    // is where a session belongs.
+    const SETUP_PATH = '/api/deepseek-web/setup';
+
+    const setupHandler = async (req, res) => {
+      try {
+        const probe = async () => {
+
+          let browserReady = false;
+          let browserError;
+          try {
+            const r = await fetch(`http://127.0.0.1:${settings.port}/json/version`, {
+              signal: AbortSignal.timeout(1200),
+            });
+            browserReady = r.ok;
+          } catch {
+            browserReady = false;
+            browserError = `no browser is listening on port ${settings.port}`;
+          }
+
+          let page = { ok: false };
+          if (browserReady) {
+            /**
+             * Wait for the single-page app to hydrate before judging it.
+             *
+             * The first read right after a navigation sees an empty shell: `signedIn` can be true from a
+             * stored token while the composer has not been created yet, and the panel then reported "not
+             * signed in, but the page is showing the sign-in screen" for a page that was simply still
+             * loading. Worst case it showed a red failure that fixed itself a second later.
+             *
+             * A signed-in page gets a short grace period to produce a composer. A genuinely signed-out
+             * page has nothing to wait for, so it is answered immediately and the panel stays responsive.
+             */
+            page = await session.inspect();
+            if (page.ok && page.signedIn && !page.hasComposer) {
+              const started = Date.now();
+              while (Date.now() - started < 6000) {
+                await new Promise((r) => setTimeout(r, 400));
+                const again = await session.inspect();
+                if (again.ok) {
+                  page = again;
+                  if (again.hasComposer) break;
+                }
+              }
+            }
+          }
+
+          let adapterRegistered = false;
+          try {
+            const providers = llmService?.listProviders?.() ?? [];
+            adapterRegistered = providers.some((p) => (p?.id ?? p?.provider) === PROVIDER);
+          } catch {
+            adapterRegistered = false;
+          }
+
+          const signedIn = Boolean(page.ok && page.signedIn);
+          const composer = Boolean(page.ok && page.hasComposer);
+          return {
+            browserReady,
+            browserError,
+            browserUrl: page.ok ? page.url : undefined,
+            signedIn,
+            composer,
+            onSignInPage: Boolean(page.ok && page.onSignInPage),
+            pageError: page.ok ? undefined : page.error,
+            adapterRegistered,
+            launching,
+            launchError: browserLaunchError,
+            // Ready means a call could succeed right now: browser up, signed in, and a composer to type in.
+            ready: browserReady && signedIn && composer && adapterRegistered,
+            // The port actually in use, so the panel names the address it just probed rather than a
+            // fixed one that may not be the live browser.
+            port: settings.port,
+            // Which engine will be used, and whether it is the recommended one.
+            browser: session.browserKind,
+            // What the window actually did on the last launch, not what was requested. `null` means no
+            // launch has happened since the plugin loaded.
+            lastMinimise: session.lastMinimise ?? null,
+            // Which engine each mode uses, so the trade is visible before choosing rather than after.
+            recommended: session.browserKind === 'brave',
+            // What the web route has saved so far, priced at the API rate. Estimated from character
+            // counts - the page reports no usage - and labelled as an estimate wherever it is shown.
+            savings: savings.snapshot(),
+            // The exact text most recently typed into the browser, so a person can see what was sent
+            // without opening the tab.
+            lastPrompt: lastPromptPreview,
+            /*
+             * The panel's words, in the language the harness is set to.
+             *
+             * The panel runs in the browser and cannot read files, so the dictionary travels with the
+             * status. Sending the whole table means the panel never needs to know which keys exist: it asks
+             * for one and renders whatever comes back, with the English default already built in.
+             */
+            strings: stringsForPanel(),
+            // Which languages this package can speak, and which one is in use right now.
+            languages: locales.available(),
+            language: translator().languageName,
+            languageCode: chosenLanguage || '',
+          };
+        };
+
+        if (req.method === 'GET' || req.method === 'HEAD') {
+          json(res, 200, await probe());
+          return;
+        }
+        if (req.method !== 'POST') {
+          json(res, 405, { error: 'method not allowed', allow: 'GET, POST' });
+          return;
+        }
+
+        const body = await readBody(req);
+        const action = String(body.action || 'check').toLowerCase();
+
+        if (action === 'signin') {
+          /**
+           * Bring the site forward so the person can sign in.
+           *
+           * Signing in needs a window somebody can type into, which is why this is the one moment the
+           * plugin shows the browser deliberately. The session then lives in that browser's profile, so
+           * it is asked for once and not again.
+           */
+          launching = true;
+          browserLaunchError = undefined;
+          try {
+            await session.openSignIn();
+          } catch (err) {
+            browserLaunchError = err?.message ?? String(err);
+          } finally {
+            launching = false;
+          }
+        } else if (action === 'launch') {
+          launching = true;
+          browserLaunchError = undefined;
+          try {
+            await session.ensureReady();
+          } catch (err) {
+            browserLaunchError = err?.message ?? String(err);
+          } finally {
+            launching = false;
+          }
+        } else if (action === 'fresh') {
+          /**
+           * Start a clean conversation in the browser.
+           *
+           * The one thing a person cannot do from inside the harness: when a chat drifts or fills up, the
+           * only way back to a clean starting point is to reset the page. The site sees the same "New chat"
+           * a human would click, so this is ordinary use, not a workaround.
+           */
+          try {
+            await session.startFresh();
+          } catch (err) {
+            browserLaunchError = err?.message ?? String(err);
+          }
+        } else if (action === 'language') {
+          /*
+           * The reader's own choice of language, which always beats what the harness is set to.
+           *
+           * Detection is a good default and a bad decision: someone who reads English fine on a Chinese
+           * system should not be forced into Chinese. An empty value clears the override and follows the
+           * harness again.
+           */
+          chosenLanguage = String(body?.language ?? '').trim().toLowerCase().replace(/[^a-z-]/g, '');
+          // Written through immediately: the whole point is that it survives the next restart.
+          if (prefs) prefs.set('language', chosenLanguage);
+        } else if (action === 'show') {
+          // Raise the browser window so a person can look at the page without hunting the taskbar.
+          try {
+            await session.showWindow();
+          } catch (err) {
+            browserLaunchError = err?.message ?? String(err);
+          }
+        } else if (action !== 'check') {
+          json(res, 400, {
+            error: `unknown action "${action}"`,
+            allow: ['signin', 'launch', 'fresh', 'show', 'language', 'check'],
+          });
+          return;
+        }
+
+        json(res, 200, await probe());
+      } catch (err) {
+        json(res, 500, { error: err?.message ?? String(err) });
+      }
+    };
+
+    try {
+      setupDisposer = server.register({ kind: 'exact', path: SETUP_PATH, handler: setupHandler });
+    } catch {
+      setupDisposer = null;
+    }
+  }
+
+  return () => {
+    try {
+      registration?.();
+    } catch {
+      /* already disposed */
+    }
+    for (const dispose of [routeDisposer, setupDisposer]) {
+      try {
+        dispose?.();
+      } catch {
+        /* already disposed */
+      }
+    }
+    session.close();
+  };
+}