Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

34.9 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import { MAX_EXTRACTED_CHARACTERS } from "@openbot/shared/attachments";
import {
  newInlineBudget,
  resolveAttachmentParts,
  type StoredAttachment,
} from "../src/channels/attachment-parts";

function loadFrom(
  store: Record<string, StoredAttachment>,
): (id: string) => Promise<StoredAttachment | null> {
  return async (id: string) => store[id] ?? null;
}

describe("resolving stored attachment references into model-readable content", () => {
  test("a url-source image part gets inline data, metadata preserved", async () => {
    const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
    const metadata = { attachmentId: "img1", filename: "photo.png" };
    const content = [
      {
        type: "image",
        source: {
          type: "url",
          value: "/api/attachments/img1",
          mimeType: "image/png",
        },
        metadata,
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        img1: { mimeType: "image/png", name: "photo.png", bytes },
      }),
    )) as Array<Record<string, unknown>>;

    expect(result[0].type).toBe("image");
    expect(result[0].metadata).toBe(metadata);
    expect(result[0].source).toEqual({
      type: "data",
      value: bytes.toString("base64"),
      mimeType: "image/png",
    });
  });

  test("a url-source document part becomes a text part naming the file", async () => {
    const bytes = Buffer.from("hello world", "utf8");
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/doc1" },
        metadata: { attachmentId: "doc1", filename: "notes.txt" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        doc1: { mimeType: "text/plain", name: "notes.txt", bytes },
      }),
    )) as Array<Record<string, unknown>>;

    expect(result[0]).toEqual({
      type: "text",
      text: 'Attached file "notes.txt":\n\nhello world',
    });
  });

  test("text past MAX_EXTRACTED_CHARACTERS is cut AT that many characters", async () => {
    /*
     * THE WHOLE PART, NOT `toContain("truncated")`.
     *
     * The looser assertions this replaces — that the text mentions truncation and is shorter than
     * the file — hold for a cut at one character just as well as for a cut at 120,000, so the one
     * number the constant exists to set was the one thing not being checked. Written out in full
     * so a change to the caption, the blank line before it, or the cut itself is a red test rather
     * than a silent change to what every model is shown.
     */
    const long = "a".repeat(MAX_EXTRACTED_CHARACTERS + 5000);
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/doc2" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        doc2: {
          mimeType: "text/plain",
          name: "big.txt",
          bytes: Buffer.from(long, "utf8"),
        },
      }),
    )) as Array<{ text: string }>;

    expect(result[0].text).toBe(
      [
        'Attached file "big.txt":',
        "",
        "a".repeat(MAX_EXTRACTED_CHARACTERS),
        "",
        `[attachment truncated at ${MAX_EXTRACTED_CHARACTERS} characters]`,
      ].join("\n"),
    );
  });

  test("text exactly MAX_EXTRACTED_CHARACTERS long is not cut at all", async () => {
    // The other side of the same boundary: an off-by-one in `extractDocumentText` shows up here as
    // a truncation marker on a file that fitted, and above as a cut in the wrong place.
    const exact = "b".repeat(MAX_EXTRACTED_CHARACTERS);
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/doc3" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        doc3: {
          mimeType: "text/plain",
          name: "exact.txt",
          bytes: Buffer.from(exact, "utf8"),
        },
      }),
    )) as Array<{ text: string }>;

    expect(result[0].text).toBe(`Attached file "exact.txt":\n\n${exact}`);
  });

  test("a cut that would land inside a character stops one code unit short", async () => {
    /*
     * `slice` counts UTF-16 code units, so a limit landing between the halves of a surrogate pair
     * left a lone high surrogate as the last code unit of the extracted text. That is not a
     * character: `JSON.stringify` emits it as a bare `\ud83d` escape, which a provider either
     * rejects or silently replaces with U+FFFD — so a file whose 120,000th code unit happens to
     * fall inside an emoji damaged a turn for a reason with nothing to do with its contents.
     * `withinFilenameLimit` in `channels/attachments.ts` guards the same hazard on the same kind of
     * cut, and said so in a comment, while this one — applied to far more bytes, far more often —
     * did not.
     *
     * Built so the pair straddles the limit exactly: MAX-1 filler characters, then one emoji whose
     * high half sits at MAX-1 and whose low half sits at MAX, then enough after it to truncate.
     */
    const emoji = "😀";
    expect(emoji.length).toBe(2);
    const long = `${"a".repeat(MAX_EXTRACTED_CHARACTERS - 1)}${emoji}tail`;
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/pair1" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        pair1: {
          mimeType: "text/plain",
          name: "emoji.txt",
          bytes: Buffer.from(long, "utf8"),
        },
      }),
    )) as Array<{ text: string }>;

    // The whole part, for the reason the test above spells out: a looser assertion would hold for
    // a cut in the wrong place just as well.
    expect(result[0].text).toBe(
      [
        'Attached file "emoji.txt":',
        "",
        "a".repeat(MAX_EXTRACTED_CHARACTERS - 1),
        "",
        `[attachment truncated at ${MAX_EXTRACTED_CHARACTERS - 1} characters]`,
      ].join("\n"),
    );
    // Said directly as well, because it is the property and the line above is one instance of it:
    // no lone surrogate survives the cut.
    const body = result[0].text.split("\n\n")[1] ?? "";
    const lastUnit = body.charCodeAt(body.length - 1);
    expect(lastUnit >= 0xd800 && lastUnit <= 0xdbff).toBe(false);
  });

  test("a cut that lands cleanly still cuts at exactly the limit", async () => {
    // The guard must not cost a character on the ordinary file. An emoji ending one unit BEFORE the
    // limit is whole inside the cut, so nothing is dropped and the count is the constant.
    const long = `${"a".repeat(MAX_EXTRACTED_CHARACTERS - 2)}😀tail`;
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/pair2" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({
        pair2: {
          mimeType: "text/plain",
          name: "emoji2.txt",
          bytes: Buffer.from(long, "utf8"),
        },
      }),
    )) as Array<{ text: string }>;

    expect(result[0].text).toBe(
      [
        'Attached file "emoji2.txt":',
        "",
        `${"a".repeat(MAX_EXTRACTED_CHARACTERS - 2)}😀`,
        "",
        `[attachment truncated at ${MAX_EXTRACTED_CHARACTERS} characters]`,
      ].join("\n"),
    );
  });

  test("a missing attachment throws, naming the attachment id", async () => {
    const content = [
      {
        type: "image",
        source: { type: "url", value: "/api/attachments/missing1" },
      },
    ];

    await expect(resolveAttachmentParts(content, loadFrom({}))).rejects.toThrow(
      /missing1/,
    );
  });

  test("the refusal names the file the person chose, not only the id they never saw", async () => {
    /*
     * The uuid is minted by the upload route; what the person picked out of a file dialog is
     * `quarterly.png`, and it is the only one of the two they can match against what they did. The
     * id stays behind it for whoever is reading a log next to a table.
     *
     * AND IT DOES NOT COLLAPSE FOUR SITUATIONS INTO ONE CLAIM. `load` answers null for a row the
     * sweeper reclaimed, for a file of somebody this asker cannot see, for one in another channel,
     * and for an id naming no row at all — different situations with different things to do about
     * them, flattened by the `(id) => Promise<StoredAttachment | null>` seam. Naming one would be a
     * guess printed as a fact, so the sentence offers the possibilities instead of picking.
     */
    const content = [
      {
        type: "image",
        source: { type: "url", value: "/api/attachments/missing2" },
        metadata: { attachmentId: "missing2", filename: "quarterly.png" },
      },
    ];

    const failure = resolveAttachmentParts(content, loadFrom({}));

    await expect(failure).rejects.toThrow(/"quarterly\.png" \(id "missing2"\)/);
    await expect(failure).rejects.toThrow(/deleted/);
    await expect(failure).rejects.toThrow(/another channel/);
  });

  test("a part with no filename is named once, not twice over", async () => {
    // `displayName` falls back to the id, and every part not written by our own composer arrives
    // without a filename — so the id would otherwise be printed beside itself.
    const content = [
      {
        type: "image",
        source: { type: "url", value: "/api/attachments/missing3" },
      },
    ];

    await expect(resolveAttachmentParts(content, loadFrom({}))).rejects.toThrow(
      'Attachment "missing3" could not be loaded',
    );
  });

  test("a missing attachment in history becomes a text part naming the file", async () => {
    /*
     * "note" is what an older message gets, because history is replayed on
     * every turn and a throw there would fail this channel for ever — the
     * failure `toolkit/history-sanitize.ts` records finding in production
     * twice. The part still SAYS the file is gone, so nothing answers as
     * though it were there.
     */
    const content = [
      {
        type: "image",
        source: { type: "url", value: "/api/attachments/gone1" },
        metadata: { attachmentId: "gone1", filename: "budget.png" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({}),
      "note",
    )) as Array<Record<string, unknown>>;

    expect(result[0]).toEqual({
      type: "text",
      text: '[attachment "budget.png" is no longer available]',
    });
  });

  test("a missing attachment with no filename is named by its id", async () => {
    const content = [
      {
        type: "document",
        source: { type: "url", value: "/api/attachments/gone2" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({}),
      "note",
    )) as Array<Record<string, unknown>>;

    expect(result[0]).toEqual({
      type: "text",
      text: '[attachment "gone2" is no longer available]',
    });
  });

  test('an attachment that still loads is inlined under "note" too', async () => {
    // "note" changes what a MISSING row does and nothing else: a row that is
    // still there resolves exactly as it does for the asked-about message.
    const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
    const content = [
      {
        type: "image",
        source: { type: "url", value: "/api/attachments/img3" },
        metadata: { attachmentId: "img3", filename: "kept.png" },
      },
    ];

    const result = (await resolveAttachmentParts(
      content,
      loadFrom({ img3: { mimeType: "image/png", name: "kept.png", bytes } }),
      "note",
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toEqual({
      type: "data",
      value: bytes.toString("base64"),
      mimeType: "image/png",
    });
  });

  test("a part that already carries a data source is left alone", async () => {
    const content = [
      {
        type: "image",
        source: { type: "data", value: "AAAA", mimeType: "image/png" },
        metadata: { attachmentId: "img2", filename: "already.png" },
      },
    ];

    const result = await resolveAttachmentParts(content, loadFrom({}));

    expect(result).toBe(content);
  });

  test("string content is returned by identity", async () => {
    const content = "just some plain message text";

    const result = await resolveAttachmentParts(content, loadFrom({}));

    expect(result).toBe(content);
  });
});

/**
 * WHICH SIDE DECIDES WHAT A FILE IS.
 *
 * A part's `type` is the browser's claim, fixed from `file.type` before the upload and never
 * reconciled with what the upload answered. `mimeType` is `sniffMimeType`'s reading of the actual
 * bytes. They disagree in production for an ordinary reason: `sniffMimeType` runs the image
 * signatures FIRST, so a PNG whose browser claim was `text/plain` is stored as `image/png` while
 * the part that named it still says `document`.
 *
 * Every test here fails if `resolvePart` goes back to reading `part.type`.
 */
describe("what a stored attachment becomes is decided by its bytes, not by the part", () => {
  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);

  function partOf(type: string, id: string, filename?: string) {
    return [
      {
        type,
        source: { type: "url", value: `/api/attachments/${id}` },
        metadata: { attachmentId: id, ...(filename ? { filename } : {}) },
      },
    ];
  }

  test('a "document" part naming a stored image is sent as an image, not as mojibake', async () => {
    /*
     * The defect in full: `photo.png` renamed and dragged out of an editor arrives claiming
     * `text/plain`, the SDK fixes the modality to `document` from that claim, the server sniffs the
     * bytes and stores `image/png` — and the old branch ran a PNG through `toString("utf8")` and
     * captioned the result `Attached file "photo.png":`. The model was handed a page of noise and
     * nothing anywhere said the picture had not been sent.
     */
    const result = (await resolveAttachmentParts(
      partOf("document", "shot1", "photo.png"),
      loadFrom({
        shot1: { mimeType: "image/png", name: "photo.png", bytes: png },
      }),
    )) as Array<Record<string, unknown>>;

    // `type` is REWRITTEN, not merely left alone: a provider shown a `document` part does not look
    // at the picture, so inlining the bytes under the claimed type would fix nothing.
    expect(result[0].type).toBe("image");
    expect(result[0].source).toEqual({
      type: "data",
      value: png.toString("base64"),
      mimeType: "image/png",
    });
  });

  test('an "image" part naming a stored text file is extracted, not base64-ed', async () => {
    const result = (await resolveAttachmentParts(
      partOf("image", "note1", "notes.txt"),
      loadFrom({
        note1: {
          mimeType: "text/markdown",
          name: "notes.txt",
          bytes: Buffer.from("# hello", "utf8"),
        },
      }),
    )) as Array<Record<string, unknown>>;

    expect(result[0]).toEqual({
      type: "text",
      text: 'Attached file "notes.txt":\n\n# hello',
    });
  });

  test("a part type AG-UI has and this app never sends still respects MAX_EXTRACTED_CHARACTERS", async () => {
    /*
     * AG-UI's union is `text | image | audio | video | document | binary`, and message content is
     * written by the browser, so all six are constructible by anyone who composes their own request
     * — our composer only ever emitting `image`/`document` is not a gate.
     *
     * Under the old `part.type === "document"` test, `binary` took the else branch: a text file at
     * the `MAX_FILE_BYTES` ceiling went to the model as ~1.4 MB of base64 with the extraction cap
     * bypassed entirely. The cut is what this asserts, because the cut is what was bypassed.
     */
    const long = "c".repeat(MAX_EXTRACTED_CHARACTERS + 1);

    const result = (await resolveAttachmentParts(
      partOf("binary", "sneak1", "notes.txt"),
      loadFrom({
        sneak1: {
          mimeType: "text/plain",
          name: "notes.txt",
          bytes: Buffer.from(long, "utf8"),
        },
      }),
    )) as Array<{ type: string; text: string }>;

    expect(result[0].type).toBe("text");
    expect(result[0].text).toBe(
      [
        'Attached file "notes.txt":',
        "",
        "c".repeat(MAX_EXTRACTED_CHARACTERS),
        "",
        `[attachment truncated at ${MAX_EXTRACTED_CHARACTERS} characters]`,
      ].join("\n"),
    );
  });

  test("a stored type this app cannot read becomes a note naming the type", async () => {
    // Not reachable through today's upload route, which runs `classifyAttachment` first. It becomes
    // reachable the day a type leaves the accepted lists with rows of it still in the table, and
    // the answer must not be mojibake — the model has to be told it cannot see the file.
    const result = (await resolveAttachmentParts(
      partOf("document", "pdf1", "invoice.pdf"),
      loadFrom({
        pdf1: {
          mimeType: "application/pdf",
          name: "invoice.pdf",
          bytes: Buffer.from("%PDF-1.7", "utf8"),
        },
      }),
    )) as Array<Record<string, unknown>>;

    expect(result[0]).toEqual({
      type: "text",
      text: '[attachment "invoice.pdf" is a application/pdf file, which cannot be put in front of the model]',
    });
  });

  test("one id named twice in a message is read once and encoded twice", async () => {
    // Two parts must not be handed the same object, but they must not cost two reads either. What
    // they DO cost twice is the budget, which the next test asserts: two encoded copies, two
    // charges, one read.
    const reads: string[] = [];
    const content = [
      ...partOf("image", "twice1"),
      ...partOf("image", "twice1"),
    ];

    const result = (await resolveAttachmentParts(content, async (id) => {
      reads.push(id);
      return { mimeType: "image/png", name: "photo.png", bytes: png };
    })) as Array<Record<string, unknown>>;

    expect(reads).toEqual(["twice1"]);
    expect(result[0]).not.toBe(result[1]);
    expect(result[0]).toEqual(result[1]);
  });

  /*
   * THE OTHER HALF OF THAT SENTENCE, WHICH THE TEST ABOVE DOES NOT REACH: ONE READ, TWO CHARGES.
   *
   * This test used to assert the opposite — "charged to the budget once", budget 20 minus one
   * 8-byte file leaving 12 — and it was wrong in the direction that matters. Deduplicating the
   * READ is a saving and stays; deduplicating the CHARGE made every copy after the first free,
   * which took the ceiling off the one thing the budget bounds. Two parts naming one file really
   * are two base64 strings live at once, so they are two charges.
   *
   * The two properties are asserted together here precisely because they were once collapsed into
   * one claim ("one read per distinct id, and one charge") that read as coherent and was not.
   */
  test("one id named twice is read once and charged twice", async () => {
    const content = [
      ...partOf("image", "charged1"),
      ...partOf("image", "charged1"),
    ];
    const eightBytes = Buffer.from("12345678", "utf8");
    const budget = newInlineBudget(20);
    const reads: string[] = [];

    const result = (await resolveAttachmentParts(
      content,
      async (id) => {
        reads.push(id);
        return {
          mimeType: "image/png",
          name: "photo.png",
          bytes: eightBytes,
        };
      },
      "note",
      budget,
    )) as Array<Record<string, unknown>>;

    // One trip to `bytea`: the memo is untouched by the fix.
    expect(reads).toEqual(["charged1"]);
    // Two copies emitted, so 16 of the 20 bytes are spent, not 8.
    expect(budget.remaining).toBe(4);
    expect(result).toHaveLength(2);
    expect(result[0]).toEqual(result[1]);
  });

  /*
   * The consequence, stated separately because it is the one a reader coming from the old behaviour
   * would doubt: once the room is gone, a part naming an id that ALREADY FIT is cut like any other.
   *
   * The rejected argument was that its bytes are in the run already, so the second mention is free
   * and cutting it puts one file in front of the model twice over — once as itself, once as a note.
   * It is not free. The second mention is a second encoded copy, and exempting it is exactly what
   * let a repeated id inline without limit. A note saying one of two mentions was left out is a
   * true statement about a turn that ran out of room, and the file is still there on the first.
   */
  test("a repeated id is cut like any other once the budget is gone", async () => {
    const content = [
      ...partOf("image", "paid"),
      ...partOf("image", "big"),
      ...partOf("image", "paid"),
    ];
    const budget = newInlineBudget(12);

    const result = (await resolveAttachmentParts(
      content,
      async (id) => ({
        mimeType: "image/png",
        name: `${id}.png`,
        bytes: Buffer.from(id === "big" ? "1234567890123456" : "12345678"),
      }),
      "note",
      budget,
    )) as Array<Record<string, unknown>>;

    expect(budget.remaining).toBe(0);
    // The first mention fit and was inlined.
    expect(result[0]).toMatchObject({ source: { type: "data" } });
    // The oversized one is cut...
    expect(JSON.stringify(result[1])).toContain("not included");
    // ...and so is the third, which names a paid id but would cost a second copy of it.
    expect(JSON.stringify(result[2])).toContain("not included");
  });
});

/**
 * HOW MUCH ONE TURN MAY SPEND ON FILES.
 *
 * `MAX_IMAGE_BYTES` bounds a file. Nothing bounded a run: history is replayed on every turn, so a
 * channel that had seen a few large images re-read and re-base64-ed all of them on every later
 * turn, and the way that fails is the pod's heap rather than any refusal a person can read.
 *
 * The budget is spent NEWEST-FIRST by `inlineAttachments`, so what runs out is the room for
 * history. The asked message is the one under `onMissing: "fail"`, and it is never cut — it is
 * served whole, or, past the limit, it refuses the turn. Both halves of that sentence are asserted
 * below, because for a while only the first was true and the second was not bounded at all.
 */
describe("a run's inlining budget", () => {
  const eightBytes = Buffer.from("12345678", "utf8");

  function imagePart(id: string, filename: string) {
    return {
      type: "image",
      source: { type: "url", value: `/api/attachments/${id}` },
      metadata: { attachmentId: id, filename },
    };
  }

  function pngStore(id: string) {
    return {
      [id]: { mimeType: "image/png", name: `${id}.png`, bytes: eightBytes },
    };
  }

  test("a history part that does not fit becomes a note that does not claim the file is gone", async () => {
    const budget = newInlineBudget(4);

    const result = (await resolveAttachmentParts(
      [imagePart("big1", "chart.png")],
      loadFrom(pngStore("big1")),
      "note",
      budget,
    )) as Array<Record<string, unknown>>;

    /*
     * NOT the `is no longer available` wording. The row is still there and a question about it
     * makes it the asked message, which the budget is spent on first; telling somebody their file
     * was deleted when it was not is a wrong answer that gets acted on.
     */
    expect(result[0]).toEqual({
      type: "text",
      text: '[attachment "chart.png" from an earlier message was not included in this turn]',
    });
    expect(budget.remaining).toBe(0);
  });

  test("a spent budget stops the database read, not just the encoding", async () => {
    // The read out of `bytea` is most of what the budget exists to bound, so a part that cannot fit
    // must not be fetched to discover that. Once the budget is at zero, later parts cost one
    // comparison each.
    const reads: string[] = [];
    const budget = newInlineBudget(0);

    await resolveAttachmentParts(
      [imagePart("skip1", "chart.png")],
      async (id) => {
        reads.push(id);
        return { mimeType: "image/png", name: "chart.png", bytes: eightBytes };
      },
      "note",
      budget,
    );

    expect(reads).toEqual([]);
  });

  test("the message being asked about spends the budget and is never cut by it", async () => {
    /*
     * The property that makes the budget defensible at all. `inlineAttachments` walks backwards, so
     * the asked message is charged first; if it were also cuttable, a person attaching one large
     * file would be told their own question's attachment was left out of their own turn.
     *
     * "fail" is what marks that message — the same flag that says an unloadable row there must not
     * degrade — so this asserts the two travel together.
     *
     * Sized to FIT, unlike the version of this test that stood here while the asked message had no
     * ceiling at all. That one passed a budget of 4 against an 8-byte file and asserted it was
     * inlined anyway, which read as "never cut" but was really "never bounded" — the assertion that
     * made the hole below look deliberate. What "never cut" means is asserted here; what happens
     * past the limit is the next test, and it is not this.
     */
    const budget = newInlineBudget(20);

    const result = (await resolveAttachmentParts(
      [imagePart("asked1", "chart.png")],
      loadFrom(pngStore("asked1")),
      "fail",
      budget,
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toMatchObject({ type: "data" });
    // Charged, not exempted: it is what leaves less for the history behind it.
    expect(budget.remaining).toBe(12);
  });

  /*
   * THE HOLE THE BUDGET LEFT OPEN, AND THE SHAPE OF THE ANSWER.
   *
   * Both places that stopped spending tested `onMissing === "note"`, and the message being asked
   * about is resolved under `"fail"`, so neither ever fired for it: nothing capped how many
   * attachment parts a browser-written message could carry. Two hundred previously-sent 8 MiB files
   * named in one message inlined about 1.6 GiB plus its base64, in one turn — the exact heap
   * exhaustion `MAX_INLINED_BYTES_PER_RUN` was written to stop, through the one door it left open.
   *
   * The answer is NOT to make that message cuttable, which is why these tests assert a rejection
   * rather than a note. Cutting it would drop files out of the message somebody is asking a question
   * about, silently, which is the failure the strict mode exists to prevent. "Served in full or the
   * turn fails loudly" survives; "in full" acquires a ceiling.
   */
  test("the message being asked about refuses the turn rather than being cut down to fit", async () => {
    const budget = newInlineBudget(4);

    const failure = resolveAttachmentParts(
      [imagePart("asked2", "chart.png")],
      loadFrom(pngStore("asked2")),
      "fail",
      budget,
    );

    // The file, so the person knows which one; the limit, so "too big" is a number; and a way out,
    // because this is their own most recent action and the message is still in front of them.
    await expect(failure).rejects.toThrow(/"chart\.png" \(id "asked2"\)/);
    await expect(failure).rejects.toThrow(/more than the 4 bytes/);
    await expect(failure).rejects.toThrow(/Send fewer files/);
  });

  test("a refused message is refused, not quietly turned into a note", async () => {
    /*
     * Stated separately because it is the regression that would be easy to introduce while fixing
     * the one above: reusing `notIncludedNote` for the asked message would bound the bytes just as
     * well and would be exactly the silent truncation `onMissing: "fail"` exists to rule out. The
     * turn must end, not continue with a file missing from the question it is answering.
     */
    const budget = newInlineBudget(4);
    let resolved: unknown = "never assigned";

    try {
      resolved = await resolveAttachmentParts(
        [imagePart("asked3", "chart.png")],
        loadFrom(pngStore("asked3")),
        "fail",
        budget,
      );
    } catch {
      resolved = "threw";
    }

    expect(resolved).toBe("threw");
  });

  test("the part past the limit refuses the turn without reading it first", async () => {
    /*
     * The refusal inherits "cut before the load", because a turn that is going to be refused should
     * not pay for the bytes it cannot afford on the way to saying so. Two 8-byte files against a
     * budget of 8: the first fits exactly and is read, and the second finds nothing left and must
     * never reach the database.
     */
    const reads: string[] = [];
    const budget = newInlineBudget(8);

    const failure = resolveAttachmentParts(
      [imagePart("first", "one.png"), imagePart("second", "two.png")],
      async (id) => {
        reads.push(id);
        return { mimeType: "image/png", name: `${id}.png`, bytes: eightBytes };
      },
      "fail",
      budget,
    );

    await expect(failure).rejects.toThrow(/"two\.png"/);
    expect(reads).toEqual(["first"]);
  });

  test("a message that fills the budget exactly is served, not refused", async () => {
    // The other side of that boundary. An off-by-one turning `>` into `>=` would refuse a message
    // that fits, which is a person told their own question is too big when it is not.
    const budget = newInlineBudget(8);

    const result = (await resolveAttachmentParts(
      [imagePart("exact1", "chart.png")],
      loadFrom(pngStore("exact1")),
      "fail",
      budget,
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toMatchObject({ type: "data" });
    expect(budget.remaining).toBe(0);
  });

  test("an unbudgeted caller is still unbounded, refusal or not", async () => {
    /*
     * The refusal is a property of the BUDGET, not of `onMissing: "fail"`. A single-message caller
     * that passes no budget — the documented "absent means unbounded" case, and what every caller
     * did before the budget existed — must not start failing because its message is large.
     */
    const result = (await resolveAttachmentParts(
      [imagePart("free2", "chart.png"), imagePart("free3", "other.png")],
      async (id) => ({
        mimeType: "image/png",
        name: `${id}.png`,
        bytes: Buffer.alloc(64 * 1024 * 1024),
      }),
      "fail",
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toMatchObject({ type: "data" });
    expect(result[1].source).toMatchObject({ type: "data" });
  });

  /*
   * WHAT THE READ MEMO IS SCOPED TO, ASSERTED RATHER THAN ASSUMED.
   *
   * `resolveAttachmentParts` builds `loadOnce` per call, and it is called once per message, so an
   * id quoted in two messages of one thread is read twice. The comment on it once said "this run",
   * which was simply false, and the fix was to the comment: per message is the intended scope. A
   * run-scoped memo would pin every attachment's buffer live for the whole backward walk — worse
   * for the heap this budget exists to protect than the second read is for the clock.
   *
   * The CHARGE has no scope question left to answer. It runs once per part emitted, here and
   * everywhere, so two messages quoting one id pay for it twice for the same reason two parts of
   * one message do: two encoded copies reach the run.
   */
  test("an id quoted in two messages is read once per message and charged once per part", async () => {
    const budget = newInlineBudget(20);
    const reads: string[] = [];
    const load = async (id: string) => {
      reads.push(id);
      return { mimeType: "image/png", name: `${id}.png`, bytes: eightBytes };
    };

    // Two calls, because two messages are two calls: this is the seam the scope question is about.
    await resolveAttachmentParts(
      [imagePart("quoted", "chart.png")],
      load,
      "note",
      budget,
    );
    await resolveAttachmentParts(
      [imagePart("quoted", "chart.png")],
      load,
      "note",
      budget,
    );

    expect(reads).toEqual(["quoted", "quoted"]);
    expect(budget.remaining).toBe(4);
  });

  test("a history part that fits draws the budget down by the stored bytes", async () => {
    const budget = newInlineBudget(20);

    const result = (await resolveAttachmentParts(
      [imagePart("fits1", "chart.png")],
      loadFrom(pngStore("fits1")),
      "note",
      budget,
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toMatchObject({ type: "data" });
    expect(budget.remaining).toBe(12);
  });

  test("no budget means no ceiling, which is what a single-message caller wants", async () => {
    const result = (await resolveAttachmentParts(
      [imagePart("free1", "chart.png")],
      loadFrom(pngStore("free1")),
      "note",
    )) as Array<Record<string, unknown>>;

    expect(result[0].source).toMatchObject({ type: "data" });
  });

  /*
   * THE BUDGET BOUNDS WHAT COMES OUT, NOT HOW MANY DISTINCT FILES WENT IN.
   *
   * This is the regression that made the whole number decorative. The charge was deduplicated per
   * id, on the reasoning that one id is read once so it should be billed once — but this function
   * emits a base64 part for EVERY OCCURRENCE of an id, and every one of those strings is live at the
   * same time. Forty parts naming one 1 KiB file against a 1 KiB budget inlined 40 KiB and reported
   * the budget spent exactly to zero. At the 8 MiB upload ceiling a hundred references came to about
   * 1.04 GiB of base64 against a 32 MiB budget: the heap exhaustion the budget exists to prevent,
   * with the counter insisting nothing was wrong.
   *
   * SO THIS ASSERTS ON DECODED OUTPUT BYTES AND NOT ON `budget.remaining`. The counter is precisely
   * what lied: it read zero while forty copies went out. What a run can afford to hold is a fact
   * about the parts it returns, so that is the thing measured — sum the bytes behind every `data`
   * source that actually left this function.
   *
   * The read memo is asserted in the same breath, because the fix must not buy the bound back by
   * giving up `loadOnce`: one id, one trip to `bytea`, many charges.
   */
  test("one id repeated past the budget inlines no more bytes than the budget", async () => {
    const kilobyte = Buffer.alloc(1024, 0x41);
    const budget = newInlineBudget(1024);
    const reads: string[] = [];
    const content = Array.from({ length: 40 }, () =>
      imagePart("repeated", "chart.png"),
    );

    const result = (await resolveAttachmentParts(
      content,
      async (id) => {
        reads.push(id);
        return { mimeType: "image/png", name: "chart.png", bytes: kilobyte };
      },
      "note",
      budget,
    )) as Array<Record<string, unknown>>;

    const inlinedBytes = result.reduce((total, part) => {
      const source = part.source as
        | { type?: unknown; value?: unknown }
        | undefined;
      if (source?.type !== "data" || typeof source.value !== "string") {
        return total;
      }
      return total + Buffer.from(source.value, "base64").length;
    }, 0);

    // One read, because `loadOnce` still memoises: the fix is to the charge, not to the fetch.
    expect(reads).toEqual(["repeated"]);
    // The bound, measured where it matters: one copy's worth of bytes left this function.
    expect(inlinedBytes).toBe(1024);
    // Every part is still accounted for — the ones past the bound say so rather than vanishing.
    expect(result).toHaveLength(40);
    expect(JSON.stringify(result[1])).toContain("not included");
  });
});