@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.0

package/src/chatops/handoff.mjs

@@ -0,0 +1,258 @@
+/**
+ * Hand-off: what happens when the machine holding a task does not answer (v0.7.7).
+ *
+ * ## What this decides
+ *
+ * "The default PC did not reply, so another PC takes over" is a rule with a sharp edge that is
+ * easy to miss while implementing it, and the edge is this:
+ *
+ * > **Hand-off turns execution from at-most-once into at-least-once.**
+ *
+ * A command may now run on **two** machines. That is harmless for `node --test` and it is not
+ * harmless for anything that writes — a `write: true` task could apply its change twice, and the
+ * second application happens on a machine that has no idea the first one already ran. The design
+ * document forbids automatic hand-off for writing tasks until a fencing token exists, and this
+ * module **is** that prohibition: `write: true` plus `halt: 'now'` is refused outright rather than
+ * quietly allowed.
+ *
+ * ## The four cases, and why each needs its own answer
+ *
+ * | case | what it means | what happens |
+ * |---|---|---|
+ * | **done** | the machine answered | nothing; the aggregate is decided |
+ * | **silent** | connected but its heartbeat stopped | takes over only under `halt: 'now'` |
+ * | **offline** | the connection dropped | same as silent, but immediately — this is the main path |
+ * | **late** | the original reported *after* a takeover | recorded, and **never** overwrites the successor |
+ *
+ * The late case is the one worth stating: a result that arrives after its lease was reassigned is
+ * **evidence**, not an answer. Overwriting the successor's result with it would mean the verdict
+ * depends on which machine was slower to reply, which is not a property anyone asked for.
+ *
+ * ## Refusals are named
+ *
+ * "Why did nothing take over" has several different answers — the task was cancelled, the caller
+ * asked not to halt, the task writes, there is no other machine — and they have different fixes.
+ * Collapsing them into "no hand-off" is how an operator concludes the feature is broken.
+ */
+
+/** Why a takeover did not happen. Every value is a thing an operator can act on. */
+export const NO_HANDOFF = Object.freeze({
+  /** Nothing to do: the lease finished. */
+  DONE: 'done',
+  /** The caller asked the relay not to reassign (`halt: 'never'`). */
+  HALT_NEVER: 'halt_never',
+  /** The task writes, so a second run could apply the same change twice. */
+  WRITE_NOT_IDEMPOTENT: 'write_not_idempotent',
+  /** The task was cancelled; taking it over would resurrect it. */
+  CANCELLED: 'cancelled',
+  /** No other machine in this fleet is online. */
+  NO_ALTERNATE_MACHINE: 'no_alternate_machine',
+  /** Every other machine has already tried this slice. */
+  ALL_TRIED: 'all_tried',
+  /** The lease has not expired yet, so the holder is presumed to be working. */
+  NOT_YET_EXPIRED: 'not_yet_expired',
+});
+
+/** Which attempt a lease is on. Kept explicit so a late result can be recognised by number. */
+export const LEASE_STATE = Object.freeze({
+  OFFERED: 'offered',
+  CLAIMED: 'claimed',
+  DONE: 'done',
+  EXPIRED: 'expired',
+  REFUSED: 'refused',
+  CANCELLED: 'cancelled',
+});
+
+/**
+ * Is this lease finished, one way or another?
+ *
+ * `expired` and `refused` are terminal for the *lease* but not for the *task* — the slice may
+ * still be handed to another machine, which is the whole point. `done` is terminal for both.
+ */
+export function isLeaseTerminal(state) {
+  return state === LEASE_STATE.DONE || state === LEASE_STATE.CANCELLED;
+}
+
+/**
+ * Should this slice be handed to another machine?
+ *
+ * @param {object} input
+ * @param {{state: string, machine_id: string, attempt: number, lease_until_ms?: number}} input.lease
+ * @param {boolean} input.write Whether the task writes. Decides whether hand-off is safe at all.
+ * @param {'never'|'now'} input.halt The caller's stated policy.
+ * @param {boolean} input.cancelled
+ * @param {string[]} input.triedMachineIds Machines that have already held this slice.
+ * @param {Array<{machine_id: string, fleet_id?: string, online?: boolean, caps?: object}>} input.candidates
+ *        Devices that may take over. Already fleet-filtered by the caller.
+ * @param {number} [input.now]
+ * @param {number} [input.takeoverGraceMs] Extra delay before a takeover, so a machine that is
+ *        merely slow is not pre-empted. A slow machine is not a dead one.
+ */
+export function shouldHandOff({
+  lease,
+  write,
+  halt,
+  cancelled,
+  triedMachineIds,
+  candidates,
+  now = Date.now(),
+  takeoverGraceMs = 0,
+}) {
+  if (lease === null || typeof lease !== 'object') {
+    return { takeOver: false, reason: NO_HANDOFF.DONE, text: '没有租约。' };
+  }
+  if (cancelled === true) {
+    // Reassigning a cancelled task would resurrect it, and the operator cancelled it on purpose.
+    return { takeOver: false, reason: NO_HANDOFF.CANCELLED, text: '任务已取消，不会重派。' };
+  }
+  if (isLeaseTerminal(lease.state)) {
+    return { takeOver: false, reason: NO_HANDOFF.DONE, text: '这一片已经有结果了。' };
+  }
+  if (halt !== 'now') {
+    // The default. A stopped machine is *recorded* rather than replaced, because for anything
+    // that writes, a second runner is worse than a missing result.
+    return { takeOver: false, reason: NO_HANDOFF.HALT_NEVER, text: '这个任务没有开启接手（halt 不是 now）。' };
+  }
+  if (write === true) {
+    // The sharp edge. Refused, not warned about: a second application of the same write is a
+    // data-loss shape, and the caller cannot tell it happened from the verdict alone.
+    return {
+      takeOver: false,
+      reason: NO_HANDOFF.WRITE_NOT_IDEMPOTENT,
+      text: '这是写任务，自动接手会让同一条命令执行两次，因此拒绝。',
+    };
+  }
+
+  /**
+   * A lease that has not expired is presumed to be progressing.
+   *
+   * Two separate questions, in this order — and the first version of this got the arithmetic
+   * backwards by adding the grace to the wrong side, which a test caught:
+   *
+   *   1. **Is the lease still valid?** If `now < lease_until`, the holder is within its window and
+   *      nothing is taken over, whatever the grace says.
+   *   2. **Has the grace elapsed since it expired?** Only then is a takeover considered. A machine
+   *      that is merely slow is not a machine that is gone.
+   *
+   * The boundary is inclusive on the decline side, so the outcome does not depend on which side of
+   * a millisecond the scheduler landed.
+   */
+  const until = Number(lease.lease_until_ms);
+  if (Number.isFinite(until)) {
+    if (now < until) {
+      return { takeOver: false, reason: NO_HANDOFF.NOT_YET_EXPIRED, text: '租约还没到期，先假定它在正常工作。' };
+    }
+    if (now < until + takeoverGraceMs) {
+      return { takeOver: false, reason: NO_HANDOFF.NOT_YET_EXPIRED, text: '租约刚到期，还在宽限期内。' };
+    }
+  }
+
+  const tried = new Set(Array.isArray(triedMachineIds) ? triedMachineIds : []);
+  // The current holder is "tried" whether or not the caller said so: handing the slice back to the
+  // machine that just went silent is the one reassignment guaranteed to be useless.
+  if (typeof lease.machine_id === 'string') tried.add(lease.machine_id);
+
+  // "Available" means untried **and online**. An offline machine is not an alternate, and counting
+  // it as one is what would make the two refusals below indistinguishable.
+  const available = (Array.isArray(candidates) ? candidates : []).filter(
+    (c) => c && typeof c.machine_id === 'string' && !tried.has(c.machine_id) && c.online !== false,
+  );
+  const alternate = available[0];
+
+  if (alternate === undefined) {
+    /**
+     * Two different situations, and the distinction is *how many machines exist*, not how many
+     * are untried.
+     *
+     * A test found the first version of this checking "is there an untried machine", which is
+     * always false in the all-tried case — so the two refusals were indistinguishable and the
+     * named reason was unreachable. The question an operator is actually asking is:
+     *
+     *   * the fleet has other machines and every one of them has had a turn → `ALL_TRIED`
+     *     (fix: wait, or make one succeed)
+     *   * the fleet holds only this machine → `NO_ALTERNATE_MACHINE`
+     *     (fix: add a machine to the fleet)
+     *
+     * The current holder is excluded from *availability* but not from *existence*: a fleet of one
+     * has no alternate and never will.
+     */
+    const others = (Array.isArray(candidates) ? candidates : []).filter(
+      (c) => c && typeof c.machine_id === 'string' && c.machine_id !== lease.machine_id,
+    );
+    return others.length > 0
+      ? { takeOver: false, reason: NO_HANDOFF.ALL_TRIED, text: '这条舰队里其他机器都已经试过这一片了。' }
+      : { takeOver: false, reason: NO_HANDOFF.NO_ALTERNATE_MACHINE, text: '这条舰队里没有其他机器可以接手。' };
+  }
+
+  return {
+    takeOver: true,
+    machineId: alternate.machine_id,
+    attempt: (Number.isFinite(lease.attempt) ? lease.attempt : 1) + 1,
+    text: `交给 ${alternate.machine_name ?? alternate.machine_id} 接手（第 ${(Number.isFinite(lease.attempt) ? lease.attempt : 1) + 1} 次尝试）。`,
+  };
+}
+
+/**
+ * Which attempt's result counts, when more than one arrived.
+ *
+ * The rule is **highest attempt wins**, not "last to arrive" and not "first to arrive". Arrival
+ * order is a property of the network, and a verdict that depends on it is a verdict nobody can
+ * reason about. The attempt number is assigned by the relay, so it is the one ordering that does
+ * not depend on who was faster.
+ *
+ * Results from superseded attempts are **returned rather than dropped**: a late result from the
+ * machine that went silent is diagnostic — it says the machine was alive and slow, not dead —
+ * and discarding it turns a diagnosable situation into an unexplained one.
+ */
+export function reconcileResults(results) {
+  const list = (Array.isArray(results) ? results : []).filter((r) => r && typeof r === 'object');
+  if (list.length === 0) return { winner: null, superseded: [], arrivedLate: [] };
+
+  // A missing attempt number is treated as **0**, not as infinity. A frame with no attempt is an
+  // old frame whose attempt was not recorded — treating it as the newest would let a stale result
+  // from a superseded lease win the aggregate, which is the exact inversion this function exists
+  // to prevent. A test asserts the direction.
+  const attemptOf = (r) => (Number.isFinite(r.attempt) ? r.attempt : 0);
+
+  let winner = list[0];
+  for (const result of list) {
+    const better = attemptOf(result);
+    const best = attemptOf(winner);
+    if (better > best) {
+      winner = result;
+    } else if (better === best) {
+      // Same attempt twice: only possible when one machine delivered twice. Either delivery is
+      // equivalent, so the first is kept — which makes the outcome stable across a replay of the
+      // ledger rather than dependent on ingest order.
+      continue;
+    }
+  }
+
+  const superseded = list.filter((r) => r !== winner && attemptOf(r) < attemptOf(winner));
+  const arrivedLate = superseded.filter((r) => r.arrivedAfterHandoff === true);
+  return { winner, superseded, arrivedLate };
+}
+
+/**
+ * The slice's story, in the order the relay saw it, for a report.
+ *
+ * Kept as a list rather than a summary because "which machine tried, in what order, and why the
+ * next one did or did not" is the question an operator actually asks, and a summarised answer
+ * cannot be interrogated.
+ */
+export function handoffTrace(events) {
+  const list = Array.isArray(events) ? events : [];
+  return list
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => {
+      const machine = e.machine_name ?? e.machine_id ?? '?';
+      if (e.event === 'offer') return `attempt ${e.attempt ?? '?'}: offered to ${machine}`;
+      if (e.event === 'done') return `attempt ${e.attempt ?? '?'}: ${machine} answered (${e.status ?? 'ok'})`;
+      if (e.event === 'expired') return `attempt ${e.attempt ?? '?'}: ${machine} went silent`;
+      if (e.event === 'refused') return `attempt ${e.attempt ?? '?'}: ${machine} refused (${e.reason ?? '?'})`;
+      if (e.event === 'handoff') return `attempt ${e.attempt ?? '?'}: handed to ${machine}`;
+      if (e.event === 'handoff-declined') return `no hand-off: ${e.reason ?? '?'}`;
+      if (e.event === 'late') return `attempt ${e.attempt ?? '?'}: ${machine} reported late, not counted`;
+      return `${e.event ?? '?'}: ${machine}`;
+    });
+}

package/src/chatops/ilink-protocol.mjs

@@ -0,0 +1,165 @@
+/**
+ * The WeChat (ClawBot / iLink) wire protocol, as measured (v0.7.1).
+ *
+ * ## Why this file exists
+ *
+ * v0.7.0 shipped an `ilink.mjs` built from *reading* the audited plugin's source, and every
+ * field name in it was wrong. Nine separate mismatches, all of which passed 237 tests, because
+ * those tests drove an injected transport and asserted on the requests we *constructed*
+ * rather than the requests WeChat *accepts*. A self-consistent suite cannot falsify its own
+ * assumptions.
+ *
+ * Everything below came from a live exchange — a real QR scan, a real bot, a real message in
+ * both directions. The comments name the response each constant was read from, so a future
+ * change can be checked against something rather than against a memory.
+ *
+ * ## The two things that cost the most time
+ *
+ * **`AuthorizationType: ilink_bot_token` is mandatory and undocumented.** Without it every
+ * authenticated endpoint answers `{"errcode":-14,"errmsg":"session timeout"}` — *including a
+ * request with no `Authorization` header at all*, because the server rejects on the missing
+ * type header before it ever looks at the credential. That is why the error reads as a dead
+ * session and sends you looking for an expiry bug that does not exist.
+ *
+ * **Business failures arrive as HTTP 200.** A success answers `{"ret":0,…}`; a failure answers
+ * `{"errcode":-14,"errmsg":"session timeout"}` with the same 200. Checking the status code is
+ * therefore not enough, and a client that does has a silent-failure bug in the one place it
+ * matters most.
+ */
+
+/** Where login happens. The only host reachable without a token. */
+export const QR_BASE_URL = 'https://ilinkai.weixin.qq.com/';
+
+/**
+ * Hosts an authenticated request may be sent to.
+ *
+ * Measured: the login response returns exactly `https://ilinkai.weixin.qq.com`. v0.7.0 also
+ * allowed `weixin.qq.com` and `api.weixin.qq.com` on a guess, which weakened the one guarantee
+ * that matters here — that the bot token only ever reaches WeChat's bot endpoint. An
+ * allow-list wider than the measurement is not caution, it is the absence of the check.
+ */
+export const ALLOWED_API_HOSTS = Object.freeze(['ilinkai.weixin.qq.com']);
+
+/** Sent on every request, authenticated or not. `iLink-App-Id: bot` is not the bot's id. */
+export const APP_ID = 'bot';
+/** `(2 << 16) | (4 << 8) | 6` — the reference client reports 2.4.6 as a packed integer. */
+export const CLIENT_VERSION = String((2 << 16) | (4 << 8) | 6); // '132102'
+/** `channel_version` inside `base_info`. */
+export const PROTOCOL_VERSION = '2.4.6';
+/** `bot_type` for the QR request. */
+export const BOT_TYPE = '3';
+/** `AuthorizationType`. Omitting this is the defect described at the top of this file. */
+export const AUTH_TYPE = 'ilink_bot_token';
+
+export const ENDPOINTS = Object.freeze({
+  QRCODE: 'ilink/bot/get_bot_qrcode',
+  QRCODE_STATUS: 'ilink/bot/get_qrcode_status',
+  UPDATES: 'ilink/bot/getupdates',
+  SEND: 'ilink/bot/sendmessage',
+  NOTIFY_START: 'ilink/bot/msg/notifystart',
+  NOTIFY_STOP: 'ilink/bot/msg/notifystop',
+});
+
+/** `base_info`, required in every request body. Measured in every accepted call. */
+export function baseInfo(agent = 'DeepSeekHarness/w2m') {
+  return { channel_version: PROTOCOL_VERSION, bot_agent: agent };
+}
+
+/** Login states, as strings. `scaned` is WeChat's spelling, not a typo here. */
+export const LOGIN_STATUS = Object.freeze({
+  WAIT: 'wait',
+  SCANED: 'scaned',
+  CONFIRMED: 'confirmed',
+  EXPIRED: 'expired',
+  SCANED_BUT_REDIRECT: 'scaned_but_redirect',
+  NEED_VERIFYCODE: 'need_verifycode',
+  VERIFY_CODE_BLOCKED: 'verify_code_blocked',
+  BINDED_REDIRECT: 'binded_redirect',
+});
+
+/** Message types and states, as measured. Inbound is 1; our outbound replies are 2. */
+export const MESSAGE = Object.freeze({
+  TYPE_INBOUND: 1,
+  TYPE_OUTBOUND: 2,
+  STATE: 2,
+  ITEM_TEXT: 1,
+});
+
+/**
+ * Is this response a success?
+ *
+ * Three shapes are accepted, because the server uses three and only one of them is documented
+ * by its own field names:
+ *
+ *   * `{"ret":0, ...}` — the QR, status, notifystart and getupdates calls.
+ *   * `{"message_id":...}` — `sendmessage`. **Measured**: a delivered reply came back with a
+ *     `message_id` and *no* `ret` at all, so a strict `ret === 0` check reports a successful
+ *     send as a failure. That was caught by this suite, which is the point of it.
+ *   * `{"errcode":0}` — an explicit zero, which some WeChat endpoints use.
+ *
+ * A body with none of these is **not** a success: an unknown shape is an unknown outcome, and
+ * guessing in the permissive direction is how a refusal gets counted as a delivery.
+ */
+export function isOk(body) {
+  if (body === null || typeof body !== 'object') return false;
+  if (body.errcode !== undefined && body.errcode !== 0) return false;
+  if (body.ret !== undefined) return body.ret === 0;
+  if (body.errcode === 0) return true;
+  // `sendmessage`'s success shape, measured.
+  return body.message_id !== undefined && body.message_id !== null;
+}
+
+/** The reason a response carries, for a log or an error. Never invented. */
+export function failureOf(body) {
+  if (body === null || typeof body !== 'object') return { errcode: null, errmsg: 'the response was not an object' };
+  return {
+    errcode: body.errcode ?? null,
+    errmsg: body.errmsg ?? body.err_msg ?? body.message ?? null,
+  };
+}
+
+/**
+ * Is this a URL the bot token may be sent to?
+ *
+ * Checked on the parsed hostname, not a string prefix: `ilinkai.weixin.qq.com.attacker.example`
+ * ends with a plausible string and is not WeChat.
+ */
+export function isAllowedApiUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { ok: false, reason: 'not a url' };
+  }
+  if (parsed.protocol !== 'https:') {
+    return { ok: false, reason: `the base url is ${parsed.protocol}//, and a bearer token goes over https only` };
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!ALLOWED_API_HOSTS.includes(host)) {
+    return { ok: false, reason: `${host} is not a host this channel will send a token to` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Text out of an inbound message, using the shape a live response actually has:
+ *
+ *     item_list: [{ type: 1, text_item: { text: "..." }, ... }]
+ */
+export function extractText(message) {
+  const items = Array.isArray(message?.item_list) ? message.item_list : [];
+  const parts = [];
+  for (const item of items) {
+    const text = item?.text_item?.text;
+    if (typeof text === 'string' && text !== '') parts.push(text);
+  }
+  return parts.length === 0 ? null : parts.join('\n');
+}
+
+/** The platform's id for a message. Measured as a number in a live response, so it is stringified. */
+export function messageId(message) {
+  const id = message?.message_id ?? message?.msg_id ?? null;
+  if (id === null || id === undefined) return null;
+  const text = String(id);
+  return text === '' ? null : text;
+}

package/src/chatops/ilink-transport.mjs

@@ -0,0 +1,168 @@
+/**
+ * The real HTTP transport for the WeChat channel (v0.7.1).
+ *
+ * v0.7.0 required the host to inject a transport and shipped none, so nothing could ever send
+ * a request. That was a design gap rather than a typo: an adapter with no default client is an
+ * adapter that cannot run. This is the default, and it is still injectable, because the
+ * contract tests need to drive it without a network.
+ *
+ * ## What it does that a bare `fetch` does not
+ *
+ * * **A per-request deadline**, because `getupdates` is a deliberate long poll and `notifystart`
+ *   is not; one timeout for both would either cut the poll short or hang the handshake.
+ * * **`undici`'s `cause` unwrapping.** A bare `fetch` failure is `TypeError: fetch failed` with
+ *   the actual reason (`ECONNRESET`, `ENOTFOUND`, `CERT_*`) on `error.cause`. Reporting only the
+ *   TypeError is how a network problem looks like a protocol problem.
+ * * **The `ret` / `errcode` distinction returned as data.** It does not throw on a business
+ *   failure: `{"errcode":-14}` arrives with HTTP 200 and is a *value*, and a transport that
+ *   turned it into an exception would make the channel's own error handling unreachable.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { APP_ID, CLIENT_VERSION, AUTH_TYPE, isOk, failureOf } from './ilink-protocol.mjs';
+
+/** `X-WECHAT-UIN`: base64 of a random uint32 rendered as decimal text. Measured. */
+export function makeUin() {
+  return Buffer.from(String(randomBytes(4).readUInt32BE(0)), 'utf8').toString('base64');
+}
+
+/**
+ * Headers for one request.
+ *
+ * `AuthorizationType` is the one that is easy to leave out and impossible to debug: without it
+ * every authenticated endpoint answers `-14 session timeout`, including calls with no
+ * credential at all, because the server rejects before it reads the token.
+ */
+export function buildHeaders({ token, uin = makeUin() } = {}) {
+  const headers = {
+    'iLink-App-Id': APP_ID,
+    'iLink-App-ClientVersion': CLIENT_VERSION,
+    'content-type': 'application/json',
+    AuthorizationType: AUTH_TYPE,
+    'X-WECHAT-UIN': uin,
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+/**
+ * Return a copy with rounded `message_id` numbers replaced by the exact digits the server sent.
+ *
+ * **Returns** rather than mutates. The first version edited in place, so a caller holding the
+ * body it had passed in saw it change underneath — and in the test suite, where a fixture
+ * constant is shared between cases, the first case silently rewrote it for every case after.
+ * A function whose name says "repair" should not be able to surprise its caller that way, and
+ * the symptom (a later test failing on data it never touched) is expensive to trace.
+ *
+ * Walked in document order: `JSON.parse` preserves key order, and the regex that collected the
+ * ids read them in the same order, so the nth `message_id` encountered is the nth id captured.
+ * Matching by value instead would be circular — the whole problem is that the value is wrong.
+ */
+export function repairMessageIds(node, exactIds) {
+  const remaining = [...exactIds];
+  function walk(current) {
+    if (current === null || typeof current !== 'object') return current;
+    if (Array.isArray(current)) return current.map(walk);
+    const copy = {};
+    for (const [key, value] of Object.entries(current)) {
+      if (key === 'message_id' && typeof value === 'number' && remaining.length > 0) {
+        copy[key] = remaining.shift();
+      } else {
+        copy[key] = walk(value);
+      }
+    }
+    return copy;
+  }
+  return walk(node);
+}
+
+/**
+ * Create a transport.
+ *
+ * @param {object} [options]
+ * @param {typeof fetch} [options.fetch] Injected in tests; the platform's own otherwise.
+ * @param {() => string} [options.mintUin]
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ * @returns {(request: {url: string, body: unknown, token?: string|null, timeoutMs?: number, signal?: AbortSignal}) => Promise<{ok: boolean, http: number, body: object, ms: number, errcode?: number|null, errmsg?: string|null}>}
+ */
+export function createTransport(options = {}) {
+  // `??` would treat an explicit `null` as "not provided" and quietly fall back to the global
+  // fetch, so a test asking for no fetch would silently get the network instead. Presence is
+  // checked rather than nullishness.
+  const hasFetch = Object.prototype.hasOwnProperty.call(options, 'fetch');
+  const doFetch = hasFetch ? options.fetch : globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    // Named rather than left to fail at the first request with "doFetch is not a function".
+    throw new TypeError('createTransport needs a fetch implementation; Node 20.19+ provides one, or inject options.fetch');
+  }
+  const mintUin = options.mintUin ?? makeUin;
+  const audit = options.audit ?? (() => {});
+
+  return async function request({ url, body, token = null, timeoutMs = 20_000, signal: outer } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // Both the caller's cancellation and the deadline apply, so a channel being stopped cuts a
+    // long poll short instead of waiting out its 45 seconds.
+    const signal = outer ? AbortSignal.any([outer, controller.signal]) : controller.signal;
+    const started = Date.now();
+
+    let response;
+    try {
+      response = await doFetch(url, {
+        method: 'POST',
+        headers: buildHeaders({ token, uin: mintUin() }),
+        body: JSON.stringify(body ?? {}),
+        signal,
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      if (error?.name === 'AbortError' || error?.name === 'TimeoutError') {
+        return { ok: false, http: 0, body: {}, ms: Date.now() - started, errcode: null, errmsg: `timed out after ${timeoutMs}ms`, timedOut: true };
+      }
+      // `fetch failed` hides the reason on `cause`; without this a network fault reads as a
+      // protocol fault and sends you debugging field names.
+      const cause = error?.cause;
+      const detail = cause ? `${cause.code ?? ''}${cause.code ? ' ' : ''}${cause.message ?? cause}`.trim() : 'no-cause';
+      audit('transport/network-error', { url, detail });
+      return { ok: false, http: 0, body: {}, ms: Date.now() - started, errcode: null, errmsg: `${error?.message ?? error} [${detail}]` };
+    }
+    clearTimeout(timer);
+
+    const text = await response.text();
+    let json = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      // Some endpoints answer with an opaque string; the caller sees it in `errmsg`.
+      json = null;
+    }
+    const ms = Date.now() - started;
+
+    if (json === null) {
+      return { ok: false, http: response.status, body: {}, ms, errcode: null, errmsg: `non-JSON response: ${text.slice(0, 200)}` };
+    }
+
+    // 64-bit ids, recovered as text.
+    //
+    // A live `message_id` is 7515840255213248776 — nineteen digits, and past
+    // `Number.MAX_SAFE_INTEGER` (9007199254740991). `JSON.parse` therefore rounds it, and the
+    // value we hold is *not* the value the server sent. Measured: the constant
+    // `7515840255213248776` came back out of a parse as `7515840255213249000`.
+    //
+    // For de-duplication the rounding is mostly harmless — a re-delivery carries the same
+    // rounded number, so it is still caught. It is not harmless if an id is ever sent back to
+    // the platform or persisted as a key, so the exact digits are recovered here rather than
+    // left to a comment.
+    const exactIds = [...text.matchAll(/"message_id"\s*:\s*(\d{16,})/g)].map((m) => m[1]);
+    if (exactIds.length > 0) json = repairMessageIds(json, exactIds);
+
+    const ok = response.ok && isOk(json);
+    if (!ok) {
+      const { errcode, errmsg } = failureOf(json);
+      audit('transport/refused', { url, http: response.status, errcode, errmsg });
+      return { ok: false, http: response.status, body: json, ms, errcode, errmsg: errmsg ?? `HTTP ${response.status}` };
+    }
+    audit('transport/ok', { url, http: response.status, ms });
+    return { ok: true, http: response.status, body: json, ms, errcode: null, errmsg: null };
+  };
+}