synabun 2.0.0-beta → 2.0.5

package/neural-interface/lib/cloudflared/pins.json

@@ -0,0 +1,63 @@
+{
+  "version": "2026.10.0",
+  "baseUrl": "https://github.com/cloudflare/cloudflared/releases/download/2026.10.0/",
+  "release": "https://github.com/cloudflare/cloudflared/releases/tag/2026.10.0",
+  "license": "Apache-2.0",
+  "origin": "Cloudflare's own release files, the stable release of 2026-10-05. `sha256` is the digest GitHub publishes for the release asset (the `digest` of the asset in the releases API). `binary.sha256` is the checksum in the release's own notes (SHA256 Checksums): for the macOS archives that is the checksum of the cloudflared inside, for the other files it is the file itself. Each file was downloaded on 2026-10-13 and both values, and the sizes, were computed from it and found equal to what is published.",
+  "platforms": {
+    "darwin-arm64": {
+      "file": "cloudflared-darwin-arm64.tgz",
+      "sha256": "a2f79ff7b9420aa537d74af239f376da170bbabeb529aec416002adac6a72e70",
+      "size": 19809074,
+      "archive": "tgz",
+      "member": "cloudflared",
+      "binary": {
+        "sha256": "72edfd3eea463aef4d5cb89e2e209cecb048cc756c2b01915de2e0ad7cb39830",
+        "size": 39364384,
+        "format": "macho"
+      }
+    },
+    "darwin-x64": {
+      "file": "cloudflared-darwin-amd64.tgz",
+      "sha256": "903845b81828c8cb3c5d13d816a2de71c06a3da5785469df8eb0e1b736d92f9f",
+      "size": 21741581,
+      "archive": "tgz",
+      "member": "cloudflared",
+      "binary": {
+        "sha256": "0560c9ab7281ac3f746055323623ed23bc0405b6dab9400474020cba33a978da",
+        "size": 42328240,
+        "format": "macho"
+      }
+    },
+    "linux-x64": {
+      "file": "cloudflared-linux-amd64",
+      "sha256": "d33ff2d14475178d2012c2c56beba87389ac5ded27649519f198a7d3134a99db",
+      "size": 40129756,
+      "binary": {
+        "sha256": "d33ff2d14475178d2012c2c56beba87389ac5ded27649519f198a7d3134a99db",
+        "size": 40129756,
+        "format": "elf"
+      }
+    },
+    "linux-arm64": {
+      "file": "cloudflared-linux-arm64",
+      "sha256": "e6422b9d4f72d3194bc5a38676f13667c06666523217b842a877d72a80b5ac08",
+      "size": 37687584,
+      "binary": {
+        "sha256": "e6422b9d4f72d3194bc5a38676f13667c06666523217b842a877d72a80b5ac08",
+        "size": 37687584,
+        "format": "elf"
+      }
+    },
+    "win32-x64": {
+      "file": "cloudflared-windows-amd64.exe",
+      "sha256": "86aee4017b26625cee8484c113558f48effa4cd47f7aa05fcf425604e5d2b23c",
+      "size": 55365048,
+      "binary": {
+        "sha256": "86aee4017b26625cee8484c113558f48effa4cd47f7aa05fcf425604e5d2b23c",
+        "size": 55365048,
+        "format": "pe"
+      }
+    }
+  }
+}

package/neural-interface/lib/cloudflared/tunnel.js

@@ -0,0 +1,265 @@
+// ═══════════════════════════════════════════
+// SynaBun — the public address (a Cloudflare quick tunnel)
+// ═══════════════════════════════════════════
+//
+// `cloudflared tunnel --url http://localhost:<port>`: no Cloudflare account, an
+// address under trycloudflare.com for as long as the process runs. One tunnel
+// at a time. What server.js keeps of it are three thin routes (/api/tunnel/…)
+// and the address itself, which it needs for its Host and remote rules: it
+// gets every change through `onUrl`, the moment cloudflared prints the address.
+//
+//   start()   answers at once. Behind it: the copy of cloudflared to run
+//             (manager.js: a download on a machine that has none), then the
+//             process, then its address. A second start while one is on its
+//             way, or running, changes nothing.
+//   stop()    ends the process, and whatever a start was still waiting for.
+//   status()  what is happening, for the page: idle, downloading (with
+//             progress), starting, running (the address, which copy runs and
+//             its version), failed (a code and a sentence; a start tries again).
+//   shutdown()  stop(), then waits (a bounded time) until cloudflared has
+//             really exited. killNow(): at the server's exit, kill it now.
+//
+// A copy of SynaBun's own is started with --no-autoupdate: it is a pinned file,
+// and cloudflared would otherwise replace itself where it stands, inside an
+// installed application too. The user's own cloudflared is started as before.
+// Whatever copy it is, the manager checks it once more right before the start
+// (confirm: the very file its check read, by its real path), and that path is
+// what is started, at once.
+//
+// An ended process is not forgotten: it is asked to end (SIGTERM), killed when
+// it is still there a moment later (SIGKILL), and kept until it has exited.
+
+import { spawn as nodeSpawn } from 'node:child_process';
+
+const exited = (proc) => !proc.pid || proc.exitCode !== null || proc.signalCode !== null;
+
+/**
+ * End a child process for sure: SIGTERM now, SIGKILL when it is still there `killAfterMs` later. Resolves once it
+ * has exited (at once for one that is gone, or never started). How long to wait for that is the caller's choice.
+ */
+export function endChild(proc, { killAfterMs = 1000 } = {}) {
+  return new Promise((done) => {
+    if (!proc || exited(proc)) { done(); return; }
+    let timer = null;
+    proc.once('exit', () => { clearTimeout(timer); done(); });
+    try { proc.kill('SIGTERM'); } catch { /* gone already */ }
+    timer = setTimeout(() => {
+      if (!exited(proc)) { try { proc.kill('SIGKILL'); } catch { /* gone already */ } }
+    }, killAfterMs);
+  });
+}
+
+/** The address of a quick tunnel, as cloudflared prints it. */
+const TUNNEL_URL = /https:\/\/([a-z0-9-]+)\.trycloudflare\.com/g;
+/** Names under trycloudflare.com that are Cloudflare's own, never a tunnel's (they appear in its error lines). */
+const NOT_A_TUNNEL = new Set(['api', 'www']);
+const OUTPUT_KEPT = 4096;
+
+/** The first quick-tunnel address in a piece of cloudflared's output, or null. */
+export function tunnelUrlIn(text) {
+  TUNNEL_URL.lastIndex = 0;
+  for (let match = TUNNEL_URL.exec(text); match; match = TUNNEL_URL.exec(text)) {
+    if (!NOT_A_TUNNEL.has(match[1])) return match[0];
+  }
+  return null;
+}
+
+/** The arguments cloudflared is started with for a copy from `source` (manager.js). */
+export function tunnelArguments(port, source) {
+  return ['tunnel', ...(source === 'system' ? [] : ['--no-autoupdate']), '--url', `http://localhost:${port}`];
+}
+
+/** What cloudflared said last that reads like a reason: its last error line, without the timestamp. */
+function lastReason(output) {
+  const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const said = [...lines].reverse().find((line) => /\b(?:ERR|error|failed)\b/i.test(line)) || '';
+  return said.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z?\s+/, '').replace(/^(?:ERR|INF|WRN)\s+/, '').slice(0, 240);
+}
+
+/**
+ * @param {object} o
+ * @param {{ ensure: Function, inspect: Function, status: Function, cancel: Function, confirm?: Function, killNow?: Function }} o.cloudflared manager.js
+ * @param {number | string} o.port the port of this server
+ * @param {(url: string | null) => void} [o.onUrl] every change of the address: set when it is known, null when it is gone
+ * @param {typeof nodeSpawn} [o.spawn]
+ * @param {number} [o.urlTimeoutMs] how long a started cloudflared may take to print its address
+ * @param {number} [o.killAfterMs] how long an ended cloudflared has to exit before it is killed
+ * @param {(line: string) => void} [o.log]
+ */
+export function createQuickTunnel({ cloudflared, port, onUrl = () => {}, spawn = nodeSpawn, urlTimeoutMs = 90_000, killAfterMs = 1000, log = () => {} }) {
+  let phase = 'idle';   // idle | preparing | starting | running | failed
+  let child = null;
+  let url = null;
+  let copy = null;      // { source, version } of the cloudflared that runs
+  let error = null;     // { code, message, reason } of the start that failed, until the next one (`reason`: cloudflared's own words, when it gave any)
+  let attempt = 0;      // a start that is not the current attempt any more does nothing
+  let preparing = null; // the AbortController of the start that is getting its copy ready
+  const ending = new Map();   // a process that was asked to end → its endChild(): kept until it has really exited
+
+  /** Ask a process to end, kill it when it does not, and keep it until it has exited. */
+  function end(proc) {
+    if (!proc) return Promise.resolve();
+    if (!ending.has(proc)) ending.set(proc, endChild(proc, { killAfterMs }).then(() => { ending.delete(proc); }));
+    return ending.get(proc);
+  }
+
+  const setUrl = (value) => {
+    if (url === value) return;
+    url = value;
+    try { onUrl(value); } catch { /* the address is still ours to report */ }
+  };
+
+  function fail(code, message, reason = null) {
+    phase = 'failed';
+    error = { code, message, reason };
+    copy = null;
+    setUrl(null);
+    log(`  Tunnel:  ${code === 'ended' ? 'stopped' : 'not started'} (${code}): ${message}`);
+  }
+
+  function launch(found, mine) {
+    // Checked once more as it is about to run (the manager's confirm: the very file its check read, still where
+    // nobody else can change it), and started at once by the real path that was checked: nothing runs in between.
+    let path = found.path;
+    try {
+      if (typeof cloudflared.confirm === 'function') path = cloudflared.confirm(found);
+    } catch (failure) {
+      return fail(typeof failure?.code === 'string' ? failure.code : 'launch', failure?.message || String(failure));
+    }
+    let proc;
+    try {
+      proc = spawn(path, tunnelArguments(port, found.source), { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (failure) {
+      return fail('launch', `cloudflared could not be started (${failure?.code || failure?.message || failure}).`);
+    }
+    child = proc;
+    copy = { source: found.source, version: found.version };
+    phase = 'starting';
+    let output = '';
+    const timer = setTimeout(() => {
+      if (mine !== attempt || phase !== 'starting') return;
+      child = null;
+      end(proc);
+      fail('no_address', `cloudflared gave no address within ${Math.round(urlTimeoutMs / 1000)} seconds.`, lastReason(output) || null);
+    }, urlTimeoutMs);
+    timer.unref?.();
+    // cloudflared prints the address to stderr, in pieces that can end anywhere: the search runs over what
+    // came last, not over one piece.
+    const read = (data) => {
+      output = (output + data.toString()).slice(-OUTPUT_KEPT);
+      if (mine !== attempt || phase !== 'starting') return;
+      const address = tunnelUrlIn(output);
+      if (!address) return;
+      clearTimeout(timer);
+      phase = 'running';
+      setUrl(address);
+      log(`  Tunnel:  ${address} (cloudflared ${found.version}, ${found.source})`);
+    };
+    proc.stdout?.on('data', read);
+    proc.stderr?.on('data', read);
+    proc.on('error', (failure) => {
+      clearTimeout(timer);
+      if (mine !== attempt || child !== proc) return;
+      child = null;
+      fail('launch', `cloudflared could not be started (${failure?.code || failure?.message || failure}).`);
+    });
+    proc.on('close', (code, signal) => {
+      clearTimeout(timer);
+      if (mine !== attempt || child !== proc) return;   // stopped on request, or already accounted for
+      child = null;
+      const said = lastReason(output) || null;
+      if (phase === 'running') fail('ended', 'The tunnel stopped by itself. Start it again for a new address.', said);
+      else fail('exited', said || `cloudflared stopped before it gave an address (${signal || `exit ${code}`}).`, said);
+    });
+    return undefined;
+  }
+
+  function answer(message) {
+    return { ok: true, state: phase, url, message };
+  }
+
+  function start() {
+    if (phase === 'running') return { ...answer('Already running.') };
+    if (phase === 'preparing' || phase === 'starting') return answer('Tunnel starting...');
+    const mine = ++attempt;
+    phase = 'preparing';
+    error = null;
+    copy = null;
+    setUrl(null);
+    // What the preparation runs (a hash, a `cloudflared --version`, a download) stops with this, on stop().
+    const ready = new AbortController();
+    preparing = ready;
+    const done = () => { if (preparing === ready) preparing = null; };
+    Promise.resolve().then(() => cloudflared.ensure({ signal: ready.signal })).then((found) => {
+      done();
+      if (mine === attempt) launch(found, mine);
+    }, (failure) => {
+      done();
+      if (mine !== attempt) return;
+      fail(typeof failure?.code === 'string' ? failure.code : 'unknown', failure?.message || String(failure));
+    });
+    return answer('Tunnel starting...');
+  }
+
+  function stop() {
+    const was = phase;
+    attempt++;
+    const proc = child;
+    child = null;
+    phase = 'idle';
+    error = null;
+    copy = null;
+    setUrl(null);
+    if (preparing) { preparing.abort(); preparing = null; }
+    if (was === 'preparing') { try { cloudflared.cancel(); } catch { /* nothing was running */ } }
+    end(proc);
+    return { ok: true, state: phase, message: was === 'idle' || was === 'failed' ? 'Not running.' : 'Tunnel stopped.' };
+  }
+
+  /**
+   * stop(), and a wait until cloudflared has really exited (killed when it does not end by itself): at most
+   * `timeoutMs`, so the server's shutdown never waits on it for long. `exited` says whether it did by then.
+   */
+  async function shutdown({ timeoutMs = 2000 } = {}) {
+    const stopped = stop();
+    let timer = null;
+    const exitedInTime = await Promise.race([
+      Promise.all([...ending.values()]).then(() => true),
+      new Promise((done) => { timer = setTimeout(() => done(false), timeoutMs); }),
+    ]);
+    clearTimeout(timer);
+    return { ...stopped, exited: exitedInTime && ending.size === 0 };
+  }
+
+  /** At the server's exit, when nothing can be waited for: every cloudflared this started that is still there is killed now. */
+  function killNow() {
+    stop();
+    for (const proc of ending.keys()) { if (!exited(proc)) { try { proc.kill('SIGKILL'); } catch { /* gone already */ } } }
+    try { cloudflared.killNow?.(); } catch { /* nothing of its own runs */ }
+  }
+
+  async function status() {
+    // While a start waits for the copy, the manager is asked what it knows, not sent to look again.
+    let tool;
+    try { tool = phase === 'preparing' ? cloudflared.status() : await cloudflared.inspect(); } catch (failure) { tool = { ...cloudflared.status(), state: 'failed', error: { code: 'unknown', message: failure?.message || String(failure) } }; }
+    const downloading = phase === 'preparing' && tool.state === 'downloading';
+    return {
+      ok: true,
+      // What a page that predates the download reads: can a tunnel be started here, is one up, is one on its way.
+      available: tool.state !== 'unsupported',
+      running: phase === 'running' || phase === 'starting',
+      starting: phase === 'preparing' || phase === 'starting',
+      url,
+      state: downloading ? 'downloading' : phase === 'preparing' ? 'starting' : phase,
+      error,
+      cloudflared: {
+        ...tool,
+        // The copy that runs, when one does; otherwise the one a start would run.
+        source: copy?.source ?? tool.source,
+        version: copy?.version ?? tool.version,
+      },
+    };
+  }
+
+  return { start, stop, status, url: () => url, phase: () => phase, shutdown, killNow };
+}

package/neural-interface/lib/editor-completion-endpoint.js

@@ -0,0 +1,264 @@
+// ── AI autocomplete through an endpoint of the user's own ──
+// A local Ollama, or anything that speaks the OpenAI completions or chat
+// protocol. What is sent (docs/design/code-editor/SPEC.md, section 9.6):
+//
+//   ollama + fim   POST {url}/api/generate { model, prompt: prefix, suffix, stream, options, keep_alive }
+//   ollama + chat  POST {url}/api/chat     { model, messages, stream, options, keep_alive }
+//   openai + fim   POST {url} { model, prompt: prefix, suffix, max_tokens, temperature, stream }
+//   openai + chat  POST {url} { model, messages, max_tokens, temperature, stream }
+//
+// `Authorization: Bearer` is added when SYNABUN_EDITOR_AI_KEY is set; the key is
+// never part of an error, in any form: nothing an endpoint says about a failure
+// (an error body, an error inside a stream) is passed on. An endpoint may repeat
+// the request's Authorization header as sent, URL-encoded, JSON-escaped or in a
+// form nobody listed, so its words are only read to pick one of a few sentences
+// of this file's own (endpointFailure). Every failure of a call leaves here as
+// an EndpointFailure with such a sentence. The answer is read as it streams
+// (server-sent events, one JSON object per line, or one JSON body) until it
+// ends, until the caller says it holds enough, or until the request is aborted.
+
+const MAX_TOKENS = 256;
+const TEMPERATURE = 0.1;
+const MAX_REPLY_CHARS = 16_000;
+
+const trimSlashes = (url) => String(url || '').replace(/\/+$/, '');
+
+const REDACTED = '[redacted]';
+// What follows "Bearer" in a header an endpoint echoes: the characters a token is made of (lib/editor-config.js).
+const BEARER_TOKEN = /\b(Bearer)\s+[A-Za-z0-9._~+/=:@-]+/gi;
+
+/**
+ * A text without the endpoint's key as it was sent: the key itself wherever it stands, and whatever follows
+ * "Bearer" (a credential whoever it belongs to). It knows the key in one form only, so it is not what keeps the
+ * key out of an endpoint's errors (nothing an endpoint says is passed on: endpointFailure); it is a second rule
+ * for text of this server's own.
+ * @param {string} text
+ * @param {string} [key] the endpoint's key (SYNABUN_EDITOR_AI_KEY), when one is set
+ */
+export function redactKey(text, key = '') {
+  let out = String(text ?? '');
+  if (key) out = out.split(String(key)).join(REDACTED);
+  return out.replace(BEARER_TOKEN, `$1 ${REDACTED}`);
+}
+
+/** A failure of an endpoint call, in words of this file only: safe for the page, a test's row and the log. */
+export class EndpointFailure extends Error {
+  /** @param {string} message @param {{ status?: number | null, kind?: string | null }} [o] */
+  constructor(message, { status = null, kind = null } = {}) {
+    super(message);
+    this.name = 'EndpointFailure';
+    this.status = status;
+    this.kind = kind;
+  }
+}
+
+// What a failure is called, by what the answer mentions and by its status. The first sentence whose words are
+// found wins; with no words found, the first whose statuses hold this one.
+const FAILURE_KINDS = [
+  { kind: 'model', says: 'it does not have that model', statuses: [], words: /model.{0,60}(?:not found|does not exist|doesn't exist|unknown|not supported|not available)|(?:no such|unknown|invalid) model|try pulling/i },
+  { kind: 'key', says: 'it refused the key', statuses: [401, 403], words: /unauthori[sz]ed|incorrect api key|invalid.{0,12}(?:api.?key|token|credential)|authentication|not authenticated|forbidden|permission denied/i },
+  { kind: 'rate', says: 'it takes no more requests for now', statuses: [429], words: /rate.?limit|too many requests|quota|insufficient.{0,12}(?:credit|balance|funds|quota)/i },
+  { kind: 'long', says: 'the request is too long for the model', statuses: [413], words: /context.{0,20}(?:length|window)|too long|maximum.{0,20}tokens|too many tokens/i },
+  { kind: 'busy', says: 'it is busy or still loading the model', statuses: [502, 503, 504], words: /overloaded|unavailable|loading model|still loading|timed? ?out/i },
+  { kind: 'address', says: 'nothing takes completions at that address', statuses: [404, 405], words: null },
+];
+// Why a request never got an answer, by the code of what ended it (fetch's `cause`).
+const NETWORK_KINDS = {
+  ECONNREFUSED: 'nothing is listening at its address',
+  ENOTFOUND: 'its address is not a name that is known',
+  EAI_AGAIN: 'its address could not be looked up',
+  ECONNRESET: 'it closed the connection',
+  ETIMEDOUT: 'it did not answer in time',
+  UND_ERR_CONNECT_TIMEOUT: 'it did not answer in time',
+  UND_ERR_SOCKET: 'it closed the connection',
+  CERT_HAS_EXPIRED: 'its certificate is not accepted',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'its certificate is not accepted',
+  SELF_SIGNED_CERT_IN_CHAIN: 'its certificate is not accepted',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'its certificate is not accepted',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'its certificate is not accepted',
+  ERR_INVALID_URL: 'its address is not a URL',
+};
+const READ_FOR_KIND = 4000;
+
+/**
+ * What an endpoint's failure is called. `said` (its error body, or the error inside its stream) is read for what
+ * it mentions and for nothing else: not a character of it is in the result.
+ * @param {number | null} status the HTTP status, or null for an error an answer carried in its stream
+ * @param {string} [said]
+ * @returns {EndpointFailure}
+ */
+export function endpointFailure(status, said = '') {
+  const words = String(said ?? '').slice(0, READ_FOR_KIND);
+  const code = Number.isInteger(status) ? status : null;
+  const found = FAILURE_KINDS.find((each) => each.words && each.words.test(words))
+    || (code === null ? null : FAILURE_KINDS.find((each) => each.statuses.includes(code)));
+  const lead = code === null ? 'The endpoint reported an error' : `The endpoint answered ${code}`;
+  return new EndpointFailure(found ? `${lead}: ${found.says}` : lead, { status: code, kind: found?.kind ?? null });
+}
+
+/**
+ * Whatever ended an endpoint call, as an EndpointFailure: its own when it is one; a request that got no answer by
+ * the code of what ended it; anything else without its words (they are not this file's).
+ */
+export function asEndpointFailure(error) {
+  if (error instanceof EndpointFailure) return error;
+  // fetch says "fetch failed" and keeps the reason in `cause` (several of them when a name has several addresses).
+  const causes = [error?.cause, error, error?.cause?.cause, ...(Array.isArray(error?.cause?.errors) ? error.cause.errors : [])];
+  const code = causes.map((each) => each?.code).find((each) => typeof each === 'string' && Object.hasOwn(NETWORK_KINDS, each));
+  return new EndpointFailure(code ? `The endpoint could not be reached: ${NETWORK_KINDS[code]}` : 'The endpoint could not be asked', { kind: code ? 'network' : null });
+}
+
+/**
+ * The HTTP request of one completion.
+ * @param {object} o
+ * @param {{ kind: 'ollama' | 'openai', url: string, model: string, shape: 'fim' | 'chat' }} o.endpoint `ai.endpoint`
+ * @param {string} [o.key] the bearer token, when one is set
+ * @param {{ prefix: string, suffix: string }} o.request
+ * @param {{ system: string, user: string }} o.prompt the chat messages (lib/editor-completion.js buildChatPrompt)
+ * @returns {{ url: string, headers: object, body: object }}
+ */
+export function endpointRequest({ endpoint, key = '', request, prompt }) {
+  const headers = { 'Content-Type': 'application/json', Accept: 'text/event-stream, application/x-ndjson, application/json' };
+  if (key) headers.Authorization = `Bearer ${key}`;
+  const messages = [{ role: 'system', content: prompt.system }, { role: 'user', content: prompt.user }];
+  if (endpoint.kind === 'ollama') {
+    // The address is the server's; a pasted /api/generate or /api/chat is not doubled.
+    const base = trimSlashes(endpoint.url).replace(/\/api\/(?:generate|chat)$/, '');
+    const common = { model: endpoint.model, stream: true, options: { temperature: TEMPERATURE, num_predict: MAX_TOKENS }, keep_alive: '30m' };
+    return endpoint.shape === 'chat'
+      ? { url: `${base}/api/chat`, headers, body: { ...common, messages } }
+      : { url: `${base}/api/generate`, headers, body: { ...common, prompt: request.prefix, suffix: request.suffix } };
+  }
+  const common = { model: endpoint.model, max_tokens: MAX_TOKENS, temperature: TEMPERATURE, stream: true };
+  return endpoint.shape === 'chat'
+    ? { url: endpoint.url, headers, body: { ...common, messages } }
+    : { url: endpoint.url, headers, body: { ...common, prompt: request.prefix, suffix: request.suffix } };
+}
+
+/**
+ * What one object of an answer holds, whichever of the four protocols it is.
+ * @param {object} chunk
+ * @returns {{ text: string, done: boolean, tokens: { input: number, output: number } | null, error: string | null }}
+ *   `error`: what the failure is called (endpointFailure), never the endpoint's own words
+ */
+export function readChunk(chunk) {
+  const out = { text: '', done: false, tokens: null, error: null };
+  if (!chunk || typeof chunk !== 'object') return out;
+  if (chunk.error) {
+    let said = '';
+    try { said = typeof chunk.error === 'string' ? chunk.error : JSON.stringify(chunk.error); } catch { said = ''; }
+    out.error = endpointFailure(null, said).message;
+    return out;
+  }
+  const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : null;
+  const text = chunk.response ?? chunk.message?.content ?? choice?.text ?? choice?.delta?.content ?? choice?.message?.content;
+  if (typeof text === 'string') out.text = text;
+  out.done = chunk.done === true || (choice != null && choice.finish_reason != null);
+  const input = chunk.prompt_eval_count ?? chunk.usage?.prompt_tokens;
+  const output = chunk.eval_count ?? chunk.usage?.completion_tokens;
+  if (Number.isFinite(input) || Number.isFinite(output)) out.tokens = { input: Math.round(input || 0), output: Math.round(output || 0) };
+  return out;
+}
+
+/**
+ * Read an answer to its end, or until `isDone(text)` says it holds enough.
+ * @param {Response} res
+ * @param {{ isDone?: (text: string) => boolean }} [o]
+ * @returns {Promise<{ text: string, tokens: { input: number, output: number } | null, stoppedEarly: boolean }>}
+ *   rejects with an EndpointFailure for an error the answer carries, and for an answer that cannot be read
+ */
+export async function readEndpointAnswer(res, { isDone = () => false } = {}) {
+  let text = '';
+  let tokens = null;
+  let pending = '';        // the line that is still arriving
+  let unparsed = '';       // lines that were not objects on their own: one JSON body spread over several lines
+  let finished = false;
+
+  const take = (chunk) => {
+    const part = readChunk(chunk);
+    if (part.error) throw new EndpointFailure(part.error, { kind: 'reported' });
+    text += part.text;
+    if (part.tokens) tokens = part.tokens;
+    if (part.done) finished = true;
+  };
+  const line = (raw) => {
+    let value = raw.trim();
+    if (!value || value.startsWith(':') || value.startsWith('event:') || value.startsWith('id:') || value.startsWith('retry:')) return;
+    if (value.startsWith('data:')) value = value.slice(5).trim();
+    if (value === '[DONE]') { finished = true; return; }
+    let chunk;
+    try { chunk = JSON.parse(value); } catch { unparsed += `${raw}\n`; return; }
+    take(chunk);
+  };
+
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    for (const each of (await res.text()).split('\n')) line(each);
+  } else {
+    const decoder = new TextDecoder();
+    let stoppedEarly = false;
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        pending += decoder.decode(value, { stream: true });
+        const lines = pending.split('\n');
+        pending = lines.pop();
+        for (const each of lines) line(each);
+        if (finished) break;
+        if (text.length > MAX_REPLY_CHARS || isDone(text)) { stoppedEarly = true; break; }
+      }
+    } finally {
+      // Whatever is still on its way is not wanted: the connection is given back.
+      try { await reader.cancel(); } catch { /* already closed */ }
+    }
+    if (stoppedEarly) return { text, tokens, stoppedEarly: true };
+    if (pending) line(pending);
+  }
+  if (unparsed.trim() && !text) {
+    let whole;
+    try { whole = JSON.parse(unparsed); } catch { throw new EndpointFailure('The endpoint did not answer in a form this editor reads', { kind: 'form' }); }
+    take(whole);
+  }
+  return { text, tokens, stoppedEarly: false };
+}
+
+/** @param {{ fetchImpl?: typeof fetch }} [deps] */
+export function createEndpointCompletionEngine({ fetchImpl = (...args) => fetch(...args) } = {}) {
+  return {
+    /**
+     * One completion.
+     * @param {object} o
+     * @param {{ kind: string, url: string, model: string, shape: string }} o.endpoint
+     * @param {string} [o.key]
+     * @param {{ prefix: string, suffix: string }} o.request
+     * @param {{ system: string, user: string }} o.prompt
+     * @param {AbortSignal} [o.signal]
+     * @param {(text: string) => boolean} [o.isDone] the first stop condition: the answer so far holds all that would be shown
+     * @returns {Promise<{ text: string, tokens: { input: number, output: number } | null }>} rejects with an
+     *   EndpointFailure (its message holds nothing the endpoint said), or with the abort when `signal` fired
+     */
+    async complete({ endpoint, key = '', request, prompt, signal, isDone } = {}) {
+      const { url, headers, body } = endpointRequest({ endpoint, key, request, prompt });
+      // Our own controller, so an answer that holds enough can be cut off without the caller aborting.
+      const own = new AbortController();
+      const onAbort = () => own.abort();
+      if (signal?.aborted) own.abort();
+      signal?.addEventListener('abort', onAbort, { once: true });
+      try {
+        const res = await fetchImpl(url, { method: 'POST', headers, body: JSON.stringify(body), signal: own.signal });
+        // What it says is read for what the failure is called, and stays here.
+        if (!res.ok) throw endpointFailure(res.status, await res.text().catch(() => ''));
+        const answer = await readEndpointAnswer(res, { isDone });
+        return { text: answer.text, tokens: answer.tokens };
+      } catch (error) {
+        // The caller gave up: that is not the endpoint's failure.
+        if (signal?.aborted) throw error;
+        throw asEndpointFailure(error);
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+        own.abort();
+      }
+    },
+  };
+}