leetcode-capture-helper 0.0.0-stage → 0.1.0

package/runtime/companion/mouse-input.js

@@ -0,0 +1,154 @@
+// companion/mouse-input.js - parses xterm SGR mouse-report escape sequences
+// (`\x1b[<Cb;Cx;Cy;M` for press/wheel, `...m` for release) out of a raw
+// input stream, so wheel-up/down events can drive companion.js's own
+// scrollback viewport instead of ever reaching readline.
+//
+// Why this has to happen before readline sees the bytes at all: readline's
+// own keypress decoder has no notion of the SGR mouse protocol (confirmed
+// live - see the PR that introduced this file). Fed a raw wheel-report
+// sequence, it doesn't ignore it or emit one clean "mouse" event; it shreds
+// the sequence into a run of ordinary-looking keypresses, one per
+// character (`6`, `4`, `;`, `1`, `0`, ...), each of which readline's own
+// line editor then inserts into whatever's currently typed - a wheel
+// notch would corrupt the input line with literal digits and semicolons.
+// Legacy X10 mouse reports (`\x1b[M` + three raw bytes, mode 1000 without
+// 1006) happen to be silently swallowed by Node's decoder already, but
+// that mode can't report coordinates past 223 and isn't what this program
+// requests - SGR (1006) is, and SGR gets no such special handling.
+//
+// Kept separate from companion.js's stream wiring (which stream gets raw
+// mode, which one readline reads from) so the byte-level parsing itself is
+// unit-testable without a real TTY - mirrors this project's existing split
+// between terminal-format.js's pure rendering helpers and companion.js's
+// orchestration of when/where they're used.
+
+// Only button-event tracking (1000) + SGR extended coordinates (1006) are
+// requested, not full motion tracking (1002/1003): wheel notches are
+// already reported as "buttons" 64-67 under plain 1000, so drag/motion
+// tracking would only add noise this program has no use for. Disable in
+// the reverse order, matching how the alternate-screen buffer's own
+// enable/disable pair is ordered elsewhere in companion.js.
+export const ENABLE_MOUSE_TRACKING = '\x1b[?1000h\x1b[?1006h';
+export const DISABLE_MOUSE_TRACKING = '\x1b[?1006l\x1b[?1000l';
+
+// A real terminal delivers one escape sequence in a single write in the
+// overwhelming common case, but nothing guarantees it - this bounds how
+// long a possible-in-progress `\x1b[<...` prefix is held waiting for the
+// rest before it's abandoned and let through byte by byte, so a malformed
+// or truncated sequence can't buffer forever.
+const MAX_PENDING = 32;
+
+// A short idle window covers the rare case where a sequence really is
+// split across two reads (e.g. a slow/laggy pty) without leaving a lone,
+// unrelated Escape keypress (which also starts with `\x1b[<`'s first byte)
+// stuck waiting indefinitely just because no more bytes ever follow it.
+const IDLE_FLUSH_MS = 50;
+
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+
+// The wheel bit (bit 6, value 64) distinguishes a wheel report from an
+// ordinary button (0-3) regardless of any modifier bits (4=shift, 8=meta,
+// 16=ctrl) added on top; the low bit (1) then distinguishes up (even) from
+// down (odd). Standard xterm SGR encoding - matches xterm.js/blessed/
+// neovim's own mouse-report handling. Returns null for anything that isn't
+// a wheel report (plain clicks, releases - these are passed through
+// unchanged by createMouseFilter below, not decoded here).
+export function decodeWheelDirection(cb) {
+  if ((cb & 64) !== 64) return null;
+  return (cb & 1) === 1 ? 'down' : 'up';
+}
+
+// Creates a filter: feed it raw bytes as they arrive from the real
+// terminal via push(chunk), and it calls onWheel('up' | 'down') for each
+// complete SGR wheel report found, while writing every other byte -
+// unchanged and in order, including non-wheel mouse reports (clicks,
+// releases) this program doesn't act on - to `output` (expected to be a
+// plain Writable, e.g. a PassThrough handed to readline as its own
+// `input`).
+//
+// `chunk` may be a Buffer or a string; bytes are held internally as a
+// binary/latin1 string (a straight 1:1 byte-to-char-code mapping) rather
+// than decoded as UTF-8, specifically so a multi-byte UTF-8 character that
+// happens to be split across two chunks is never corrupted by a decode
+// happening mid-character - every byte, mouse-protocol or not, round-trips
+// through unchanged.
+export function createMouseFilter({ output, onWheel }) {
+  let pending = '';
+  let idleTimer = null;
+
+  function clearIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  function flushPending() {
+    idleTimer = null;
+    if (pending) output.write(Buffer.from(pending, 'binary'));
+    pending = '';
+  }
+
+  function armIdleTimer() {
+    idleTimer = setTimeout(flushPending, IDLE_FLUSH_MS);
+    // Never let a lingering timer keep the process alive on its own - it's
+    // purely a cleanup safety net, not something companion.js should have
+    // to wait on to exit.
+    if (idleTimer.unref) idleTimer.unref();
+  }
+
+  function push(chunk) {
+    clearIdleTimer();
+    pending += Buffer.isBuffer(chunk) ? chunk.toString('binary') : String(chunk);
+    for (;;) {
+      const escIndex = pending.indexOf('\x1b');
+      if (escIndex === -1) {
+        if (pending) output.write(Buffer.from(pending, 'binary'));
+        pending = '';
+        return;
+      }
+      if (escIndex > 0) {
+        output.write(Buffer.from(pending.slice(0, escIndex), 'binary'));
+        pending = pending.slice(escIndex);
+      }
+      // pending now starts at an ESC byte - not yet enough of it buffered
+      // to tell whether it's the start of a mouse report at all.
+      if (pending.length < 3) {
+        armIdleTimer();
+        return;
+      }
+      if (!pending.startsWith('\x1b[<')) {
+        // Not a mouse report - forward just the ESC byte and keep
+        // scanning from the next one; whatever follows (arrow keys, other
+        // CSI sequences, a lone Escape) is ordinary input for readline to
+        // decode exactly as it always has.
+        output.write(Buffer.from(pending[0], 'binary'));
+        pending = pending.slice(1);
+        continue;
+      }
+      const match = SGR_MOUSE_RE.exec(pending);
+      if (!match) {
+        if (pending.length > MAX_PENDING) {
+          // Long past any real mouse report's length with no terminator -
+          // stop waiting and let it through byte by byte rather than
+          // buffering forever.
+          output.write(Buffer.from(pending[0], 'binary'));
+          pending = pending.slice(1);
+          continue;
+        }
+        armIdleTimer();
+        return;
+      }
+      const direction = decodeWheelDirection(Number(match[1]));
+      if (direction) onWheel(direction);
+      // Any other SGR mouse report (a click, a release, a modifier-only
+      // variant) is deliberately swallowed too, not forwarded - this
+      // program never enabled motion tracking, so the only reports it can
+      // receive at all are clicks/releases/wheel, none of which readline
+      // has any use for either.
+      pending = pending.slice(match[0].length);
+    }
+  }
+
+  return { push };
+}

package/runtime/companion/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/runtime/companion/panel-bridge.js

@@ -0,0 +1,273 @@
+// companion/panel-bridge.js - mirrors the tutor conversation to the in-page
+// panel (the extension's panel.js on leetcode.com) through the relay server.
+//
+// Two directions, both over the relay (see relay-server/panel-broker.js):
+//   - publish(event): tutor/user/capture events go out in batches to
+//     POST /panel/publish. Best effort: the terminal chat is the source of
+//     truth, so a relay hiccup drops panel events rather than disturbing it.
+//   - inbox: a long-lived GET /panel/inbox stream delivers messages the
+//     student typed into the panel, handed to onMessage. It reconnects with
+//     backoff for as long as the bridge runs, which is also how the panel
+//     learns whether a companion is online at all.
+//   - setBusy(busy): tells the relay whether the tutor is working on a turn
+//     (POST /panel/activity), for the panel's "Processing" light.
+//   - dropProblem(slug): asks the relay to forget one problem's buffered
+//     events (POST /panel/drop-problem) once the tutor has moved on from it.
+//     It goes out after everything published before it, so the old
+//     problem's last events cannot land after the drop.
+//   - setConfig(config): publishes the non-secret `config` event (which
+//     provider and model the tutor uses) and publishes it again whenever the
+//     inbox reconnects, since a restarted relay has none to replay.
+//   - rpc: an inbox message `{ type: 'rpc', id, method, params }` is a call
+//     from the extension's options page (relay POST /settings/rpc). It goes to
+//     onRpc(method, params), and whatever that resolves to is posted back to
+//     POST /panel/rpc-result as `{ id, response }`. Calls run concurrently with
+//     the inbox, so a slow connection test never holds up a typed message.
+//
+// Kept free of any terminal/readline code so it can be tested against a stub
+// relay without booting companion.js.
+
+const FLUSH_MS = 40;
+// A relay that accepts a publish but never answers must not stall the flush
+// chain (and with it every later publish) forever.
+const PUBLISH_TIMEOUT_MS = 5000;
+// While a publish is slow the queue keeps growing; past this many events the
+// oldest are dropped. Losing them is fine (the panel tolerates a missing
+// turn-start, and a turn-end carries the full text), running out of memory is
+// not.
+const MAX_QUEUED_EVENTS = 1000;
+// The relay's companion-only routes require this header; a browser page cannot
+// send it without a CORS preflight, which the relay refuses (see
+// relay-server/panel-broker.js, companionOnlyRejection).
+const COMPANION_HEADERS = { 'X-LC-Companion': '1' };
+const RECONNECT_MIN_MS = 1000;
+const RECONNECT_MAX_MS = 8000;
+
+// Parses one SSE block ("id: 3\ndata: {...}") into its JSON payload, or null
+// for a comment/keep-alive/malformed block.
+export function parseSseBlock(block) {
+  const data = block
+    .split('\n')
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice(5).replace(/^ /, ''))
+    .join('\n');
+  if (!data) return null;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+export function createPanelBridge({
+  baseUrl,
+  onMessage,
+  onState,
+  onRpc = null,
+  fetchImpl = fetch,
+  flushMs = FLUSH_MS,
+  publishTimeoutMs = PUBLISH_TIMEOUT_MS,
+}) {
+  let stopped = false;
+  let queue = [];
+  let flushTimer = null;
+  let flushing = Promise.resolve();
+  let inboxAbort = null;
+  let reconnectDelay = RECONNECT_MIN_MS;
+  let state = 'connecting';
+  let config = null;
+
+  function setState(next) {
+    if (state === next) return;
+    state = next;
+    if (onState) onState(next);
+  }
+
+  function publish(event) {
+    if (stopped) return;
+    const last = queue[queue.length - 1];
+    // Consecutive chunks of one turn travel as one: the panel only ever
+    // concatenates them, and a long reply would otherwise cost one HTTP
+    // request per streamed token.
+    if (last && event.type === 'chunk' && last.type === 'chunk' && last.turnId === event.turnId) {
+      last.text += event.text;
+    } else {
+      queue.push({ ...event });
+      if (queue.length > MAX_QUEUED_EVENTS) queue.splice(0, queue.length - MAX_QUEUED_EVENTS);
+    }
+    if (!flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flushing = flushing.then(flushQueue);
+      }, flushMs);
+      flushTimer.unref();
+    }
+  }
+
+  async function flushQueue() {
+    if (queue.length === 0) return;
+    const events = queue;
+    queue = [];
+    try {
+      await fetchImpl(`${baseUrl}/panel/publish`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...COMPANION_HEADERS },
+        body: JSON.stringify({ events }),
+        signal: AbortSignal.timeout(publishTimeoutMs),
+      });
+    } catch {
+      // Best effort - see the file header.
+    }
+  }
+
+  async function runInbox() {
+    while (!stopped) {
+      inboxAbort = new AbortController();
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await fetchImpl(`${baseUrl}/panel/inbox`, {
+          headers: COMPANION_HEADERS,
+          signal: inboxAbort.signal,
+        });
+        if (res.status === 404) {
+          // A relay server started before this feature existed.
+          setState('unsupported');
+        } else if (res.ok && res.body) {
+          reconnectDelay = RECONNECT_MIN_MS;
+          setState('connected');
+          if (busy) flushing = flushing.then(postActivity);
+          if (config) publish({ type: 'config', ...config });
+          const decoder = new TextDecoder();
+          let buffer = '';
+          // eslint-disable-next-line no-restricted-syntax
+          for await (const chunk of res.body) {
+            buffer += decoder.decode(chunk, { stream: true });
+            let idx;
+            // eslint-disable-next-line no-cond-assign
+            while ((idx = buffer.indexOf('\n\n')) !== -1) {
+              const message = parseSseBlock(buffer.slice(0, idx));
+              buffer = buffer.slice(idx + 2);
+              if (message && message.type === 'rpc') handleRpc(message);
+              else if (message && typeof message.text === 'string') onMessage(message);
+            }
+          }
+        }
+      } catch {
+        // Relay not up (yet) or the stream dropped - fall through to retry.
+      }
+      if (stopped) return;
+      if (state === 'connected') setState('disconnected');
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => {
+        const t = setTimeout(resolve, reconnectDelay);
+        t.unref();
+      });
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+    }
+  }
+
+  async function handleRpc(message) {
+    if (typeof message.id !== 'string' || !message.id) return;
+    let response;
+    try {
+      response = onRpc
+        ? await onRpc(message.method, message.params)
+        : { ok: false, error: { message: 'this companion does not take settings calls' } };
+    } catch (err) {
+      response = { ok: false, error: { message: (err && err.message) || 'the settings call failed' } };
+    }
+    try {
+      await fetchImpl(`${baseUrl}/panel/rpc-result`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...COMPANION_HEADERS },
+        body: JSON.stringify({ id: message.id, response }),
+        signal: AbortSignal.timeout(publishTimeoutMs),
+      });
+    } catch {
+      // The options page times out on its own and says so.
+    }
+  }
+
+  function setConfig(next) {
+    if (stopped || !next || typeof next !== 'object') return;
+    config = { ...next };
+    publish({ type: 'config', ...config });
+  }
+
+  async function postDrop(problemSlug) {
+    try {
+      await fetchImpl(`${baseUrl}/panel/drop-problem`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...COMPANION_HEADERS },
+        body: JSON.stringify({ problemSlug }),
+        signal: AbortSignal.timeout(publishTimeoutMs),
+      });
+    } catch {
+      // Best effort - see the file header.
+    }
+  }
+
+  // Tells the relay whether the tutor is working on (or has queued) a turn,
+  // for the panel's status light. Sent in order after everything published
+  // before it, and again whenever the inbox (re)connects, since a restarted
+  // relay starts out idle.
+  let busy = false;
+  async function postActivity() {
+    try {
+      await fetchImpl(`${baseUrl}/panel/activity`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...COMPANION_HEADERS },
+        body: JSON.stringify({ busy }),
+        signal: AbortSignal.timeout(publishTimeoutMs),
+      });
+    } catch {
+      // Best effort - see the file header.
+    }
+  }
+
+  function setBusy(next) {
+    if (stopped || busy === Boolean(next)) return;
+    busy = Boolean(next);
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    flushing = flushing.then(flushQueue).then(postActivity);
+  }
+
+  function dropProblem(problemSlug) {
+    if (stopped || typeof problemSlug !== 'string' || !problemSlug) return;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    flushing = flushing.then(flushQueue).then(() => postDrop(problemSlug));
+  }
+
+  return {
+    publish,
+    dropProblem,
+    setBusy,
+    setConfig,
+    start() {
+      runInbox();
+    },
+    stop() {
+      stopped = true;
+      if (flushTimer) clearTimeout(flushTimer);
+      if (inboxAbort) inboxAbort.abort();
+    },
+    // Resolves once everything queued so far has been sent (for tests).
+    async drain() {
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+        flushing = flushing.then(flushQueue);
+      }
+      await flushing;
+    },
+    get state() {
+      return state;
+    },
+  };
+}

package/runtime/companion/settings-rpc.js

@@ -0,0 +1,228 @@
+// companion/settings-rpc.js - what the extension's options page can ask the
+// companion to do: read the settings, save a change, test a connection, list a
+// server's models, keep its list of saved models (profiles) up to date; and
+// what the Tutor panel's model switcher can ask: switch to one of those saved
+// models (switchProfile, the only method the relay's panel-origin
+// POST /panel/switch-profile forwards).
+//
+// The options page talks to the relay, which forwards each call here over the
+// companion's existing inbox stream (see panel-bridge.js). All the decisions
+// live in this module so they can be tested without a browser, a relay, or a
+// running companion:
+//   - a save is validated, a backend is built from it (so a config that cannot
+//     work is refused up front), and only then is it written and applied;
+//   - a test builds a throwaway backend from an unsaved draft and never touches
+//     the saved file or the live conversation;
+//   - nothing returned to the options page ever contains an API key, and error
+//     text is scrubbed of any key it might echo.
+
+import {
+  PROVIDERS,
+  SettingsError,
+  applyPatch,
+  missingRequirement,
+  publicView,
+  resolveEffective,
+  saveSettings,
+  statusSummary,
+} from './settings.js';
+import { checkCodexLogin } from './codex-backend.js';
+import { PROFILE_ID_RE, findProfile } from '../extension/shared/profiles.js';
+import { CONNECTION_TEST_PROMPT as TEST_PROMPT } from '../extension/shared/tutor-prompt.js';
+
+const TEST_TIMEOUT_MS = 90_000;
+const MODELS_TIMEOUT_MS = 6000;
+const MAX_MODELS = 200;
+
+function scrub(message, secrets) {
+  let out = String(message);
+  for (const secret of secrets) {
+    if (secret && secret.length >= 6) out = out.split(secret).join('***');
+  }
+  return out;
+}
+
+function withTimeout(promise, ms, what) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${what} did not answer within ${Math.round(ms / 1000)} seconds`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+// deps:
+//   file, env                       where settings live and the environment to resolve against
+//   getStored()                     the saved settings object currently in memory
+//   setStored(next)                 replace it after a successful save
+//   buildBackend(effective)         throws if a backend can't be built (async allowed)
+//   apply(effective, backend, why)  swap the live backend (companion.js queues it behind the
+//                                   current turn); may return a promise of the swap having happened
+//   validateVault(effective)        throws if the vault auto-summary can't run (optional)
+//   fetchImpl, codexCommand         injectable for tests
+export function createSettingsRpc(deps) {
+  const fetchImpl = deps.fetchImpl || fetch;
+
+  function view(extra = {}) {
+    const stored = deps.getStored();
+    const effective = resolveEffective(stored, deps.env);
+    return { settings: publicView(stored, deps.env, deps.file), active: statusSummary(effective), ...extra };
+  }
+
+  async function get() {
+    return view();
+  }
+
+  async function save({ patch }) {
+    const stored = deps.getStored();
+    const next = applyPatch(stored, patch);
+    const effective = resolveEffective(next, deps.env);
+    const problem = missingRequirement(effective);
+    if (problem) throw new SettingsError(problem, 'provider');
+    if (effective.options.vaultAutoSummary && deps.validateVault) {
+      try {
+        deps.validateVault(effective);
+      } catch (err) {
+        throw new SettingsError(err.message, 'vaultAutoSummary');
+      }
+    }
+    // Build before persisting: a configuration that cannot produce a backend
+    // must not replace one that works.
+    let backend;
+    try {
+      backend = await deps.buildBackend(effective);
+    } catch (err) {
+      throw new SettingsError(scrub(err.message, [effective.apiKey]), 'provider');
+    }
+    saveSettings(next, deps.file);
+    deps.setStored(next);
+    // Not waited for: the page hears "saved" even while a reply still runs.
+    Promise.resolve(deps.apply(effective, backend, 'save')).catch(() => {});
+    return view({ saved: true });
+  }
+
+  // The options page's list of saved models that run through the helper.
+  // Changes nothing about the running backend; an active profile that is no
+  // longer listed is simply no longer one.
+  async function setProfiles({ profiles }) {
+    const next = applyPatch(deps.getStored(), { profiles: Array.isArray(profiles) ? profiles : [] });
+    saveSettings(next, deps.file);
+    deps.setStored(next);
+    return view({ saved: true });
+  }
+
+  // The model switcher: makes a saved profile the active one. It can change
+  // nothing but which saved profile is active (never a key, a URL or any
+  // other setting), so whoever may call it can at most flip between the
+  // models the user saved. Resolves once the new backend is in place, after
+  // any turn already queued, with only the non-secret summary.
+  async function switchProfile({ id }) {
+    const stored = deps.getStored();
+    const profile = typeof id === 'string' && PROFILE_ID_RE.test(id) ? findProfile(stored.profiles, id) : null;
+    if (!profile) {
+      throw Object.assign(new SettingsError('The helper app does not have that model saved. Open Manage models and press Save.', 'profile'), { code: 'unknown' });
+    }
+    const env = deps.env || {};
+    if ((env.COMPANION_BACKEND && env.COMPANION_BACKEND !== profile.provider) || (env.COMPANION_MODEL && env.COMPANION_MODEL !== profile.model)) {
+      const name = env.COMPANION_BACKEND && env.COMPANION_BACKEND !== profile.provider ? 'COMPANION_BACKEND' : 'COMPANION_MODEL';
+      throw Object.assign(new SettingsError(`The model is set by ${name} in the helper's environment, so it can't be switched here.`, 'profile'), { code: 'locked' });
+    }
+    const current = resolveEffective(stored, deps.env);
+    if (stored.activeProfile === id && current.provider === profile.provider && (current.model || null) === (profile.model || null)) {
+      return { active: statusSummary(current), profile: id };
+    }
+    const next = applyPatch(stored, { activeProfile: id });
+    const effective = resolveEffective(next, deps.env);
+    const problem = missingRequirement(effective);
+    if (problem) throw Object.assign(new SettingsError(`${problem}. Open Manage models to finish setting it up.`, 'profile'), { code: 'unavailable' });
+    let backend;
+    try {
+      backend = await deps.buildBackend(effective);
+    } catch (err) {
+      throw Object.assign(new SettingsError(scrub(err.message, [effective.apiKey]), 'profile'), { code: 'unavailable' });
+    }
+    saveSettings(next, deps.file);
+    deps.setStored(next);
+    await deps.apply(effective, backend, 'switch');
+    return { active: statusSummary(effective), profile: id };
+  }
+
+  // Tries a draft (the saved settings with the page's unsaved edits on top).
+  async function test({ patch }) {
+    const draft = applyPatch(deps.getStored(), patch || {});
+    const effective = resolveEffective(draft, deps.env);
+    const secrets = [effective.apiKey];
+    const problem = missingRequirement(effective);
+    if (problem) return { ok: false, message: problem };
+    const started = Date.now();
+    try {
+      if (effective.provider === 'chatgpt') {
+        const login = await checkCodexLogin({ ...(deps.codexCommand || {}), env: deps.env });
+        if (!login.ok) return { ok: false, message: `ChatGPT sign-in: ${login.message}. Run "codex login" and choose ChatGPT.` };
+      }
+      const backend = await deps.buildBackend(effective);
+      const reply = await withTimeout(backend.sendMessage(TEST_PROMPT, {}), TEST_TIMEOUT_MS, PROVIDERS[effective.provider].label);
+      if (!reply || !String(reply).trim()) return { ok: false, message: 'The model answered with nothing.' };
+      return { ok: true, message: `Connected in ${((Date.now() - started) / 1000).toFixed(1)}s`, reply: String(reply).trim().slice(0, 120) };
+    } catch (err) {
+      return { ok: false, message: scrub(err.message, secrets) };
+    }
+  }
+
+  // Lists model names a server offers, for the model field's suggestions.
+  async function models({ provider, baseUrl, apiKey }) {
+    const stored = deps.getStored();
+    const id = PROVIDERS[provider] ? provider : 'local';
+    const draft = applyPatch(stored, {
+      providers: { [id]: { ...(baseUrl ? { baseUrl } : {}), ...(typeof apiKey === 'string' && apiKey ? { apiKey } : {}) } },
+    });
+    const effective = resolveEffective({ ...draft, provider: id }, deps.env);
+    if (!effective.baseUrl) return { models: [] };
+    const base = effective.baseUrl.replace(/\/+$/, '');
+    const headers = effective.apiKey ? { Authorization: `Bearer ${effective.apiKey}` } : {};
+    const secrets = [effective.apiKey];
+    const ask = async (url) => {
+      const res = await withTimeout(fetchImpl(url, { headers }), MODELS_TIMEOUT_MS, url);
+      if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+      return res.json();
+    };
+    try {
+      let names = [];
+      // Ollama's own listing names models exactly as `ollama list` does and is
+      // the one most local users want; fall back to the OpenAI-style list.
+      if (id === 'local' && /\/v1$/.test(base)) {
+        try {
+          const tags = await ask(`${base.replace(/\/v1$/, '')}/api/tags`);
+          names = (tags.models || []).map((m) => m.name);
+        } catch {
+          names = [];
+        }
+      }
+      if (names.length === 0) {
+        const list = await ask(`${base}/models`);
+        names = (list.data || []).map((m) => m.id);
+      }
+      return { models: [...new Set(names.filter((n) => typeof n === 'string' && n))].sort().slice(0, MAX_MODELS) };
+    } catch (err) {
+      return { models: [], message: scrub(err.message, secrets) };
+    }
+  }
+
+  const METHODS = { get, save, test, models, setProfiles, switchProfile };
+
+  // Single entry point used by the bridge. Never throws: the result is always
+  // { ok: true, result } or { ok: false, error: { message, field } }.
+  async function handle(method, params) {
+    const fn = Object.prototype.hasOwnProperty.call(METHODS, method) ? METHODS[method] : null;
+    if (!fn) return { ok: false, error: { message: `unknown settings method "${method}"` } };
+    try {
+      return { ok: true, result: await fn(params && typeof params === 'object' ? params : {}) };
+    } catch (err) {
+      if (err instanceof SettingsError) {
+        return { ok: false, error: { message: err.message, field: err.field, ...(err.code ? { code: err.code } : {}) } };
+      }
+      return { ok: false, error: { message: scrub(err.message, [deps.env.COMPANION_API_KEY]) } };
+    }
+  }
+
+  return { handle };
+}