Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

33.9 KB
Raw Blame
/**
 * WeChat messaging — the fourth channel's mirror of messaging.test.ts, over a fake transport
 * (the wire itself is messaging-wechat-transport.test.ts's). No test opens a socket.
 *
 * This channel has NO typed credential (it is bound by a scan), so its PUT carries
 * preferences alone, its test endpoint takes no body, and its inbound side is a long poll
 * whose FIRST answer is a drain, so a binding switched on after a week dark does not replay
 * that week as a task flood. Pictures and files travel both ways.
 *
 * - A stored config is narrowed (one missing a credential refused; no host means the entry
 *   host); a reply anchor reads back to its chat; the poll backs off further after each
 *   failure, up to a ceiling.
 * - The connector's seam carries text, images and files, downloading nothing until the bridge
 *   asks.
 * - The GET masks the token and names the bot id as the account; the PUT saves preferences
 *   only and never creates a binding; the clear flag drops the token, refused while connected;
 *   saving never collides, enabling does; the probe reads the stored binding; the channel
 *   joins the channel-agnostic read.
 * - The connection is ready before any poll answers; the drain runs until the platform
 *   answers and never again on that connection, without spending itself on a silent window;
 *   the first poll's backlog is dropped, keeping its cursor; a refused token stops the loop
 *   with its own reason; a poll failure is one outage report, recovering on its own, and a
 *   failure that recovers on its own does not silence the refusal behind it.
 * - An inbound message reaches the Agent and the reply goes back with the conversation token
 *   (forgotten when the connection closes); the test message goes to the remembered chat; an
 *   empty message gets the not-supported notice; a picture reaches the model as an image typed
 *   from its bytes, a file as a path under the sender's name, an oversize one as a size
 *   refusal; outbound, a picture goes as a picture and any other file as an attachment, and
 *   Markdown renders only when the binding asks.
 */
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
import { assistantText } from "@adelie/core";
import type { OmniMessage } from "@adelie/core";
import type {
  MessagingBindingsResponse,
  WeChatBindingResponse,
  WeChatTestResponse,
} from "../src/api/types.js";
import type { RuntimeSession } from "../src/runtime/session-manager.js";
import {
  MESSAGING_TEST_MESSAGE,
  MESSAGING_UNSUPPORTED_NOTICE,
} from "../src/runtime/messaging/bridge.js";
import { messagingErrorKind } from "../src/runtime/messaging/error-kind.js";
import { MessagingMediaTooLargeError } from "../src/runtime/messaging/media.js";
import type {
  WeChatBotClient,
  WeChatCredentials,
  WeChatInboundEvent,
  WeChatMediaRef,
  WeChatOutboundFile,
  WeChatSendArgs,
  WeChatTransport,
  WeChatUpdates,
} from "../src/runtime/messaging/wechat-api.js";
import { WECHAT_API_BASE, WeChatApiError } from "../src/runtime/messaging/wechat-api.js";
import {
  WeChatConnector,
  chatOfWeChatReplyRef,
  wechatConfigOf,
  wechatRetryDelayMs,
} from "../src/runtime/messaging/wechat-connector.js";
import { forwardingTo } from "./fixtures/forwarding.js";
import { fakeSession, sessionRow, uniqueSessionId } from "./fixtures/session.js";
import { apiClient, createTestApp, provisionUser, waitFor } from "./helpers.js";
import type { TestApp } from "./helpers.js";

const BASE = (sid: string) => `/api/sessions/${sid}/messaging/wechat`;
const PROJECT = "birder-default_project";

const BOT_ID = "bot_9001";
const BOT_TOKEN = "scan-issued-token-XYZ";
const SCANNER = "ilink_user_aaa";
const USER = "ilink_user_bbb";

/** A stored config exactly as a completed scan writes one. */
const SCANNED_CONFIG = {
  botId: BOT_ID,
  botToken: BOT_TOKEN,
  baseUrl: WECHAT_API_BASE,
  userId: SCANNER,
};

/** PNG magic bytes, so the connector's sniff answers `image/png` from the bytes alone. */
const IMAGE_BYTES = Buffer.concat([
  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
  Buffer.from("pretend this is a chart"),
]);
const FILE_BYTES = Buffer.from("%PDF-1.7 a report");

// ---------------------------------------------------------------------------
// Fake transport: answers polls the test feeds it, and records every send.
// ---------------------------------------------------------------------------

type Send =
  | { kind: "text"; args: WeChatSendArgs }
  | { kind: "image"; args: WeChatSendArgs; file: WeChatOutboundFile }
  | { kind: "file"; args: WeChatSendArgs; file: WeChatOutboundFile };

class FakeWeChatClient implements WeChatBotClient {
  readonly sends: Send[] = [];
  readonly cursors: string[] = [];
  readonly fetches: Array<{ ref: WeChatMediaRef; maxBytes: number; what: string }> = [];
  /** Whether each poll asked for a drain, in order — the first should and no later one may. */
  readonly drains: boolean[] = [];
  credentialChecks = 0;
  polls = 0;
  /** Batches waiting to be served, oldest first. */
  private readonly queue: WeChatInboundEvent[][] = [];
  private wake: (() => void) | null = null;

  constructor(
    readonly creds: WeChatCredentials,
    private readonly t: FakeWeChatTransport,
  ) {}

  async checkCredentials(): Promise<void> {
    this.credentialChecks += 1;
    if (this.t.failAuth !== null) throw new Error(this.t.failAuth);
  }

  async getUpdates({
    cursor,
    signal,
    drain = false,
  }: {
    cursor: string;
    signal: AbortSignal;
    drain?: boolean;
  }): Promise<WeChatUpdates> {
    this.polls += 1;
    this.cursors.push(cursor);
    this.drains.push(drain);
    const failure = this.t.failPollWith.shift();
    if (failure !== undefined) throw failure;
    if (this.t.failPoll !== null) throw new Error(this.t.failPoll);
    const queued = this.queue.shift();
    if (queued !== undefined) {
      return { messages: queued, cursor: `cursor-${this.polls}`, timedOut: false };
    }
    // A drain asks only for what the platform is already holding, so it comes back at once.
    // With nothing to hand over the production adapter's window CLOSES instead: an empty list,
    // the cursor it was given, and `timedOut` — never an advanced cursor, which would tell the
    // loop the platform had answered when it had not. A long poll PARKS, which is what
    // production does and what makes the readiness test below meaningful.
    if (drain && !this.t.stallPolls) return { messages: [], cursor, timedOut: true };
    await new Promise<void>((resolve) => {
      this.wake = resolve;
      signal.addEventListener("abort", () => resolve(), { once: true });
    });
    if (signal.aborted) throw new Error("connection closed");
    return { messages: this.queue.shift() ?? [], cursor: `cursor-${this.polls}`, timedOut: false };
  }

  async sendText(args: WeChatSendArgs): Promise<void> {
    if (this.t.failSend !== null) throw new Error(this.t.failSend);
    this.sends.push({ kind: "text", args });
  }
  async sendImage(args: WeChatSendArgs & { file: WeChatOutboundFile }): Promise<void> {
    const { file, ...rest } = args;
    this.sends.push({ kind: "image", args: rest, file });
  }
  async sendFile(args: WeChatSendArgs & { file: WeChatOutboundFile }): Promise<void> {
    const { file, ...rest } = args;
    this.sends.push({ kind: "file", args: rest, file });
  }

  async fetchMedia(ref: WeChatMediaRef, maxBytes: number, what: string): Promise<Buffer> {
    this.fetches.push({ ref, maxBytes, what });
    if (this.t.oversizedMedia) throw new MessagingMediaTooLargeError(what, maxBytes);
    return what === "The image" ? IMAGE_BYTES : FILE_BYTES;
  }

  /**
   * Feeds one batch to the poll loop. With no arguments it queues an EMPTY batch, which is
   * how a test makes a parked poll return without delivering anything — the shape the
   * recovery half of the outage test needs.
   */
  push(...events: WeChatInboundEvent[]): void {
    this.queue.push(events);
    this.wake?.();
    this.wake = null;
  }
}

class FakeWeChatTransport implements WeChatTransport {
  readonly clients: FakeWeChatClient[] = [];
  failAuth: string | null = null;
  failSend: string | null = null;
  failPoll: string | null = null;
  /** Failures the next polls throw, one each and in order, ahead of `failPoll`. */
  readonly failPollWith: Error[] = [];
  /** Every poll parks, the drain included — an idle bot, which is the readiness case. */
  stallPolls = false;
  oversizedMedia = false;

  createClient(creds: WeChatCredentials): FakeWeChatClient {
    const client = new FakeWeChatClient(creds, this);
    this.clients.push(client);
    return client;
  }

  /** The client the poll loop is running on (the connection's, not a send's). */
  poller(): FakeWeChatClient {
    const client = this.clients.find((c) => c.polls > 0);
    if (client === undefined) throw new Error("no fake wechat poll started");
    return client;
  }

  allSends(): Send[] {
    return this.clients.flatMap((c) => c.sends);
  }
  texts(): WeChatSendArgs[] {
    return this.allSends()
      .filter((s) => s.kind === "text")
      .map((s) => s.args);
  }
}

/**
 * One input part as the fake Session records it. Deliberately a loose shape rather than
 * core's payload union: a run's input mixes composer text with `image_url` parts, and the
 * assertions read one field of whichever arrived (the shape messaging-telegram.test.ts uses).
 */
interface InputPayload {
  type?: string;
  role?: string;
  text?: string;
  image_url?: string;
}

/** A plain inbound text message from a fixed user. */
function inboundText(text: string, messageId: string, contextToken = "ctx-1"): WeChatInboundEvent {
  return { userId: USER, messageId, text, contextToken, images: [], files: [] };
}

/** Fake Session: records each run's input payloads and replies with a fixed assistant text. */
function echoFakeSession(
  sessionId: string,
  runs: InputPayload[][],
  reply = "Reply text",
): RuntimeSession {
  return fakeSession(sessionId, {
    async *run(input: OmniMessage[]) {
      runs.push(input.map((m) => m.payload as InputPayload));
      yield assistantText(reply);
    },
  });
}

// ---------------------------------------------------------------------------

describe("wechat config and reply refs", () => {
  it("narrows a stored document and rejects one missing a credential", () => {
    expect(wechatConfigOf({ ...SCANNED_CONFIG })).toEqual(SCANNED_CONFIG);
    expect(() => wechatConfigOf({ botId: BOT_ID })).toThrow(/malformed wechat binding config/);
    expect(() => wechatConfigOf({ botId: "", botToken: BOT_TOKEN })).toThrow();
  });

  it("polls the entry host for a document that names none", () => {
    // A bot with no IDC assignment lives there anyway, so this is the platform's own answer
    // rather than a guess.
    const cfg = wechatConfigOf({ botId: BOT_ID, botToken: BOT_TOKEN });
    expect(cfg.baseUrl).toBe(WECHAT_API_BASE);
    expect(cfg.userId).toBe("");
  });

  it("reads a reply anchor back to the chat it names", () => {
    expect(chatOfWeChatReplyRef(`${USER}:12345`)).toBe(USER);
    expect(() => chatOfWeChatReplyRef("nocolon")).toThrow(/malformed wechat reply ref/);
  });

  it("backs off further after each failure, up to a ceiling", () => {
    expect(wechatRetryDelayMs(2)).toBeGreaterThan(wechatRetryDelayMs(1));
    expect(wechatRetryDelayMs(3)).toBeGreaterThan(wechatRetryDelayMs(2));
    // Past some number of failures the wait stops growing.
    expect(wechatRetryDelayMs(30)).toBe(wechatRetryDelayMs(20));
  });
});

describe("the wechat connector's own seam", () => {
  it("carries text, images and files with no download until the bridge asks", async () => {
    // Handles, not bytes: a redelivery is dropped before anything is transferred.
    const transport = new FakeWeChatTransport();
    const connector = new WeChatConnector(transport, { retryDelayMs: () => 0 });
    const received: Array<{ chatId: string; text: string | null; images: number; files: number }> =
      [];
    const conn = await connector.connect(SCANNED_CONFIG, {
      onMessage: (msg) => {
        received.push({
          chatId: msg.chatId,
          text: msg.text,
          images: msg.images?.length ?? 0,
          files: msg.files?.length ?? 0,
        });
      },
    });
    const client = await waitForPoller(transport);
    client.push({
      userId: USER,
      messageId: "1",
      text: "look at this",
      images: [{ url: "https://cdn/i", aesKey: "a2V5" }],
      files: [{ fileName: "report.pdf", media: { url: "https://cdn/f" } }],
    });
    await waitFor(() => received.length === 1);
    expect(received[0]).toEqual({ chatId: USER, text: "look at this", images: 1, files: 1 });
    expect(client.fetches).toHaveLength(0);
    conn.close();
  });
});

/** Waits for the connector's poll loop to have made its first call. */
async function waitForPoller(transport: FakeWeChatTransport): Promise<FakeWeChatClient> {
  await waitFor(() => transport.clients.some((c) => c.polls > 0));
  return transport.poller();
}

describe("wechat binding routes and the long poll", () => {
  let t: TestApp;
  let api: ReturnType<typeof apiClient>;
  let fake: FakeWeChatTransport;
  let runs: InputPayload[][];
  /**
   * The case's two Sessions, fresh per case: the app is the describe's, and a binding, a poll
   * and a status belong to their Session.
   */
  let SID: string;
  let SID2: string;

  /** Store a scanned config as the scan route would, then flip the toggle on. */
  const bindEnabled = async (sid: string, config: Record<string, unknown> = SCANNED_CONFIG) => {
    t.deps.messagingRepo.upsert({
      sessionId: sid,
      channel: "wechat",
      accountId: String(config.botId),
      config,
    });
    expect((await api.post(`${BASE(sid)}/state`, { enabled: true })).status).toBe(200);
    await waitFor(() => t.deps.messaging.statusOf(sid, "wechat").state === "connected");
  };

  beforeAll(async () => {
    // A small non-zero backoff rather than zero: the loop retries in a tight cycle during
    // the outage test, and a zero delay would spin without yielding.
    t = await createTestApp({
      wechatTransport: forwardingTo(() => fake),
      wechatRetryDelayMs: () => 5,
    });
    const { cookie } = await provisionUser(t.app, "birder");
    api = apiClient(t.app, cookie);
  });
  afterAll(async () => {
    await t.cleanup();
  });
  beforeEach(() => {
    fake = new FakeWeChatTransport();
    runs = [];
    SID = uniqueSessionId();
    SID2 = uniqueSessionId();
    const row = sessionRow(SID, { projectId: PROJECT });
    t.deps.sessionsRepo.insert(row);
    t.deps.manager.adopt(row, echoFakeSession(SID, runs));
  });
  afterEach(() => {
    // What the case bound goes with it, long poll and all.
    for (const row of t.deps.messagingRepo.listAll()) t.deps.messaging.unbindSession(row.sessionId);
  });

  // —— Routes ——————————————————————————————————————————————————————————————

  it("the GET masks the token and names the bot id as the account", async () => {
    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    const body = (await (await api.get(BASE(SID))).json()) as WeChatBindingResponse;
    expect(body.binding?.channel).toBe("wechat");
    expect(body.binding?.botId).toBe(BOT_ID);
    expect(body.binding?.botTokenMasked).toBe("scan…-XYZ");
    expect(JSON.stringify(body)).not.toContain(BOT_TOKEN);
    // Neither the API host nor the scanner's id is projected: one is infrastructure, the
    // other identifies a person, and the editor renders neither.
    expect(JSON.stringify(body)).not.toContain(SCANNER);
    expect(body.binding?.enabled).toBe(false);
  });

  it("the PUT saves preferences only, and refuses to create a binding at all", async () => {
    // There is no credential to carry, so a PUT before a scan has nothing it could store.
    const bare = await api.put(BASE(SID), { renderMarkdown: false });
    expect(bare.status).toBe(400);
    expect(((await bare.json()) as { error: { code: string } }).error.code).toBe(
      "wechat_token_required",
    );

    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    const res = await api.put(BASE(SID), { renderMarkdown: false, linePerMessage: true });
    expect(res.status).toBe(200);
    const saved = t.deps.messagingRepo.find(SID, "wechat")!;
    expect(saved.renderMarkdown).toBe(false);
    expect(saved.linePerMessage).toBe(true);
    // The rest of the stored document survives a preferences save untouched — the connector
    // needs the host and the scanner's id, and this request knows neither.
    expect(saved.config).toEqual(SCANNED_CONFIG);
  });

  it("the clear flag drops the token, and is refused while the connection is live", async () => {
    await bindEnabled(SID);
    const live = await api.put(BASE(SID), { clearBotToken: true });
    expect(live.status).toBe(409);
    expect(((await live.json()) as { error: { code: string } }).error.code).toBe(
      "messaging_disable_before_clear",
    );

    expect((await api.post(`${BASE(SID)}/state`, { enabled: false })).status).toBe(200);
    expect((await api.put(BASE(SID), { clearBotToken: true })).status).toBe(200);
    const cleared = t.deps.messagingRepo.find(SID, "wechat")!;
    expect(cleared.config.botToken).toBe("");
    // The row and its identity stay: only a fresh scan can make it connectable again.
    expect(cleared.accountId).toBe(BOT_ID);
    const gate = await api.post(`${BASE(SID)}/state`, { enabled: true });
    expect(gate.status).toBe(400);
    expect(((await gate.json()) as { error: { code: string } }).error.code).toBe(
      "wechat_token_required",
    );
  });

  it("the bot id is the account: saving never collides, enabling does", async () => {
    t.deps.sessionsRepo.insert(sessionRow(SID2, { projectId: PROJECT }));
    t.deps.manager.adopt(sessionRow(SID2, { projectId: PROJECT }), echoFakeSession(SID2, []));
    await bindEnabled(SID);
    // The same bot saved on a second Session is fine; only the connection is exclusive.
    t.deps.messagingRepo.upsert({
      sessionId: SID2,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    const clash = await api.post(`${BASE(SID2)}/state`, { enabled: true });
    expect(clash.status).toBe(409);
    expect(((await clash.json()) as { error: { code: string } }).error.code).toBe(
      "account_enabled_elsewhere",
    );
  });

  it("the credential probe takes no body and reads the stored binding", async () => {
    const bare = await api.post(`${BASE(SID)}/test`, {});
    expect(bare.status).toBe(400);
    expect(((await bare.json()) as { error: { code: string } }).error.code).toBe(
      "wechat_token_required",
    );

    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    const ok = (await (await api.post(`${BASE(SID)}/test`, {})).json()) as WeChatTestResponse;
    expect(ok.ok).toBe(true);
    // The platform names no account, so success carries no label.
    expect("botUsername" in ok).toBe(false);

    fake.failAuth = "invalid bot token";
    const bad = (await (await api.post(`${BASE(SID)}/test`, {})).json()) as WeChatTestResponse;
    expect(bad.ok).toBe(false);
    expect(bad.error).toContain("invalid bot token");
  });

  it("joins the channel-agnostic read beside the others", async () => {
    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "telegram",
      accountId: "42",
      config: { botToken: "42:tele" },
    });
    const body = (await (
      await api.get(`/api/sessions/${SID}/messaging`)
    ).json()) as MessagingBindingsResponse;
    expect(body.bindings.map((b) => b.binding.channel).sort()).toEqual(["telegram", "wechat"]);
  });

  // —— The long poll ————————————————————————————————————————————————————————

  it("reports the connection ready before any poll has answered", async () => {
    // The reported bug: a long poll is a request held open until something arrives, so a
    // connection reported ready only when one came back sat at `connecting` for the whole
    // window on an idle bot — usable throughout, and saying so nowhere.
    fake.stallPolls = true;
    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    expect((await api.post(`${BASE(SID)}/state`, { enabled: true })).status).toBe(200);
    await waitFor(() => t.deps.messaging.statusOf(SID, "wechat").state === "connected");
    // Ready on the probe, with the poll behind it still parked and having returned nothing.
    const client = fake.poller();
    expect(client.credentialChecks).toBeGreaterThan(0);
    expect(client.polls).toBeGreaterThan(0);
  });

  it("drains until the platform answers, then never again on that connection", async () => {
    await bindEnabled(SID);
    const client = fake.poller();
    client.push(inboundText("hello", "m-0"));
    await waitFor(() => client.drains.includes(false));
    // Every drain comes first and there are at most DRAIN_ATTEMPTS of them: a window that
    // closed on its own deadline handed over no cursor, so spending the drain on it would
    // leave the next ordinary poll to relay a whole backlog as live traffic. The retry is
    // bounded because an idle bot's poll may park every time.
    const drains = client.drains.slice(0, client.drains.indexOf(false));
    expect(drains.length).toBeGreaterThan(0);
    expect(drains.length).toBeLessThanOrEqual(2);
    expect(drains.every((d) => d === true)).toBe(true);
    expect(client.drains.slice(drains.length).every((d) => d === false)).toBe(true);
  });

  it("does not spend the drain on a window that closed without an answer", async () => {
    // The hole this closes: the adapter reports a timed-out window as an empty list with the
    // cursor it was GIVEN, so a drain spent there leaves the cursor at the beginning and the
    // next ordinary poll hands the whole backlog to the Agent as live traffic.
    await bindEnabled(SID);
    const client = fake.poller();
    await waitFor(() => client.drains.length >= 2);
    // The fake's empty drain times out exactly as production's does, so the second call is
    // still a drain rather than an ordinary poll asking from the same unmoved cursor.
    expect(client.drains[0]).toBe(true);
    expect(client.drains[1]).toBe(true);
    expect(client.cursors[1]).toBe(client.cursors[0]);
  });

  it("stops with the credential's own reason when the token is refused", async () => {
    // The probe runs ahead of the poll, so a revoked token reports what is actually wrong
    // instead of an endless poll failure.
    fake.failAuth = "invalid bot token";
    t.deps.messagingRepo.upsert({
      sessionId: SID,
      channel: "wechat",
      accountId: BOT_ID,
      config: SCANNED_CONFIG,
    });
    expect((await api.post(`${BASE(SID)}/state`, { enabled: true })).status).toBe(200);
    await waitFor(() => t.deps.messaging.statusOf(SID, "wechat").state === "error");
    expect(t.deps.messaging.statusOf(SID, "wechat").lastError).toContain("invalid bot token");
  });

  it("drops the first poll's backlog and keeps only its cursor", async () => {
    // A binding switched on after a week dark must not replay that week as a task flood.
    fake.createClient = ((creds: WeChatCredentials) => {
      const client = new FakeWeChatClient(creds, fake);
      fake.clients.push(client);
      // Queued before the loop starts, so it is what the FIRST poll returns.
      client.push(inboundText("sent while nothing was connected", "old-1"));
      return client;
    }) as FakeWeChatTransport["createClient"];

    await bindEnabled(SID);
    const client = fake.poller();
    // The drain's cursor is carried into the next poll rather than starting over.
    await waitFor(() => client.cursors.length >= 2);
    expect(client.cursors[0]).toBe("");
    expect(client.cursors[1]).toBe("cursor-1");

    client.push(inboundText("hello", "new-1"));
    await waitFor(() => runs.length === 1);
    // Only the message that arrived after the drain ever became a task.
    expect(runs).toHaveLength(1);
    expect(runs[0]![0]!.text).toBe("hello");
  });

  it("relays an inbound message to the Agent and its reply back, carrying the conversation token", async () => {
    await bindEnabled(SID);
    const client = fake.poller();
    client.push(inboundText("what is the weather?", "m-1", "ctx-42"));
    await waitFor(() => fake.texts().length > 0);
    expect(runs[0]![0]!.text).toBe("what is the weather?");
    expect(fake.texts()[0]).toEqual({ userId: USER, text: "Reply text", contextToken: "ctx-42" });
    // The chat is remembered, which is what the test-message button needs.
    expect(t.deps.messagingRepo.find(SID, "wechat")?.lastChatId).toBe(USER);
  });

  it("sends the fixed test message to the remembered chat", async () => {
    await bindEnabled(SID);
    const noChat = await api.post(`${BASE(SID)}/test-message`, {});
    expect(noChat.status).toBe(409);
    expect(((await noChat.json()) as { error: { code: string } }).error.code).toBe(
      "wechat_no_chat",
    );

    fake.poller().push(inboundText("hi", "m-2"));
    await waitFor(() => fake.texts().length > 0);
    expect((await api.post(`${BASE(SID)}/test-message`, {})).status).toBe(200);
    expect(fake.texts().at(-1)!.text).toBe(MESSAGING_TEST_MESSAGE);
  });

  it("answers a message carrying nothing at all with the shared not-supported notice", async () => {
    // The one inbound shape this channel cannot read: a recording WeChat could not
    // transcribe. It arrives with no text and no attachment, and the bridge's own notice is
    // what the chat gets — no channel-specific refusal says more than that one already does.
    await bindEnabled(SID);
    fake.poller().push({ userId: USER, messageId: "m-3", text: "", images: [], files: [] });
    await waitFor(() => fake.texts().length > 0);
    expect(fake.texts()[0]!.text).toBe(MESSAGING_UNSUPPORTED_NOTICE);
    expect(runs).toHaveLength(0);
  });

  it("forgets a conversation token when the connection closes", async () => {
    // A token from before a disable would otherwise address a conversation the user ended.
    await bindEnabled(SID);
    fake.poller().push(inboundText("hi", "m-4", "ctx-99"));
    await waitFor(() => fake.texts().length > 0);
    expect(fake.texts()[0]!.contextToken).toBe("ctx-99");

    expect((await api.post(`${BASE(SID)}/state`, { enabled: false })).status).toBe(200);
    await bindEnabled(SID);
    // The remembered chat survives in the DB; the token does not, so the send goes without.
    expect((await api.post(`${BASE(SID)}/test-message`, {})).status).toBe(200);
    expect(fake.texts().at(-1)!.contextToken).toBeUndefined();
  });

  it("reports a poll failure as an outage, and recovers on its own when it clears", async () => {
    await bindEnabled(SID);
    const client = fake.poller();
    fake.failPoll = "connection reset";
    // The loop is parked on a long poll, so waking it is what makes it call again and fail.
    client.push();
    await waitFor(() => t.deps.messaging.statusOf(SID, "wechat").state === "error");
    // Recovery needs nothing to arrive: the probe at the top of the cycle reports it, so the
    // connection comes back while the poll behind it is still parked.
    fake.failPoll = null;
    await waitFor(() => t.deps.messaging.statusOf(SID, "wechat").state === "connected");
  });

  // —— Media, in both directions ————————————————————————————————————————————

  it("an inbound picture reaches the model as an image part, typed from its bytes", async () => {
    await bindEnabled(SID);
    fake.poller().push({
      userId: USER,
      messageId: "m-5",
      text: "",
      images: [{ url: "https://cdn/i", aesKey: "a2V5" }],
      files: [],
    });
    await waitFor(() => runs.length === 1);
    expect(runs[0]).toHaveLength(1);
    expect(runs[0]![0]!.type).toBe("image_url");
    // The wire names no type for an image; the bytes are the only source, and conclusive.
    expect(runs[0]![0]!.image_url).toBe(`data:image/png;base64,${IMAGE_BYTES.toString("base64")}`);
    expect(fake.poller().fetches[0]!.what).toBe("The image");
  });

  it("an inbound file reaches the model as a path, keeping the sender's own name", async () => {
    await bindEnabled(SID);
    fake.poller().push({
      userId: USER,
      messageId: "m-6",
      text: "summarize this",
      images: [],
      files: [{ fileName: "report.pdf", media: { url: "https://cdn/f" } }],
    });
    await waitFor(() => runs.length === 1);
    const text = runs[0]![0]!.text!;
    expect(text.startsWith("summarize this\n\n[attached file: ")).toBe(true);
    expect(text).toContain("report.pdf");
  });

  it("refuses an oversized inbound transfer as a size problem the sender can fix", async () => {
    await bindEnabled(SID);
    fake.oversizedMedia = true;
    fake.poller().push({
      userId: USER,
      messageId: "m-7",
      text: "",
      images: [{ url: "https://cdn/i" }],
      files: [],
    });
    await waitFor(() => fake.texts().length > 0);
    expect(fake.texts()[0]!.text).toContain("limit");
    expect(runs).toHaveLength(0);
  });

  it("a failure that only ever hits the poll still backs off and reports once", async () => {
    // The probe and the poll are different endpoints. A credential that keeps authenticating
    // while `getupdates` keeps refusing — an endpoint-specific 5xx, a rate limit, a cursor the
    // platform has started rejecting — must not zero the counter on every recovery: that walks
    // the backoff nowhere and writes one error record per attempt, which for a token revoked
    // overnight is what the loop exists not to do.
    const delays: number[] = [];
    const errors: unknown[] = [];
    fake.failPoll = "getupdates refused";
    const connector = new WeChatConnector(fake, {
      // Non-zero so the loop yields to the macrotask queue between attempts; a zero delay
      // resolves as a microtask and starves the poller below.
      retryDelayMs: (failures) => {
        delays.push(failures);
        return 1;
      },
    });
    const conn = await connector.connect(SCANNED_CONFIG, {
      onMessage: async () => {},
      onError: (err) => errors.push(err),
    });
    try {
      await waitFor(() => delays.length >= 4);
      // The counter climbs across attempts rather than resetting to 1 on every recovery…
      expect(delays.slice(0, 4)).toEqual([1, 2, 3, 4]);
      // …so the outage is one error record rather than one per attempt.
      expect(errors).toHaveLength(1);
    } finally {
      conn.close();
    }
  });

  it("a failure that recovers on its own does not silence the refusal behind it", async () => {
    // A dropped request is filed as routine, so if it kept the outage's one report, a token
    // refused on every retry after it would never be filed at all: the binding stays down and
    // the dashboard reads zero defects. The transport's verdicts are asserted where they are
    // made (messaging-wechat-transport.test.ts); these stand in for them.
    const errors: unknown[] = [];
    fake.failPollWith.push(
      new WeChatApiError(undefined, "wechat getUpdates failed: fetch failed", { recovers: true }),
      new WeChatApiError(undefined, "wechat getUpdates failed: HTTP 401 invalid bot token"),
      new WeChatApiError(undefined, "wechat getUpdates failed: HTTP 401 invalid bot token"),
    );
    const connector = new WeChatConnector(fake, { retryDelayMs: () => 1 });
    const conn = await connector.connect(SCANNED_CONFIG, {
      onMessage: async () => {},
      onError: (err) => errors.push(err),
    });
    try {
      await waitFor(() => fake.failPollWith.length === 0 && errors.length === 2);
      await new Promise((resolve) => setTimeout(resolve, 20));
      // The blip, then the refusal behind it — and nothing more: the repeat stays quiet.
      expect(errors.map((err) => messagingErrorKind(err, "messaging_connect_failed"))).toEqual([
        "expected",
        "unexpected",
      ]);
    } finally {
      conn.close();
    }
  });

  it("sends a picture as a picture and any other file as an attachment", async () => {
    // The capability QQ has to refuse outright: outbound media, both kinds, no public URL.
    const connector = new WeChatConnector(fake, { retryDelayMs: () => 0 });
    const outbound = await connector.createClient(SCANNED_CONFIG);
    await outbound.sendImage(USER, { fileName: "chart.png", data: IMAGE_BYTES });
    await outbound.sendFile(USER, { fileName: "report.pdf", data: FILE_BYTES });
    const sends = fake.clients.at(-1)!.sends;
    expect(sends.map((s) => s.kind)).toEqual(["image", "file"]);
    expect(sends[0]!.kind === "image" && sends[0]!.file.data.equals(IMAGE_BYTES)).toBe(true);
    expect(sends[0]!.kind === "image" && sends[0]!.file.fileName).toBe("chart.png");
    expect(sends[1]!.kind === "file" && sends[1]!.file.fileName).toBe("report.pdf");
  });

  it("renders a reply's Markdown when the binding asks, and sends the source when it does not", async () => {
    const connector = new WeChatConnector(fake, { retryDelayMs: () => 0 });
    const outbound = await connector.createClient(SCANNED_CONFIG);
    await outbound.sendText(USER, "# Title\n\n**bold**", { markdown: true });
    await outbound.sendText(USER, "# Title\n\n**bold**");
    const sends = fake.clients.at(-1)!.sends;
    // WeChat reads Markdown itself, so a rendered heading stays a heading.
    expect(sends[0]!.args.text).toBe("# Title\n\n**bold**");
    expect(sends[1]!.args.text).toBe("# Title\n\n**bold**");
    // …and the case where rendering actually changes something: a fifth-level heading has no
    // scale here, so its markers go rather than arriving as five literal `#`.
    await outbound.sendText(USER, "##### Deep", { markdown: true });
    expect(fake.clients.at(-1)!.sends.at(-1)!.args.text).toBe("Deep");
  });
});