|
| 1 | +import { describe, expect, test } from "bun:test" |
| 2 | +import { buildListEnvelope, projectFields, LIST_FIELDS } from "../../src/cli/cmd/list-envelope" |
| 3 | + |
| 4 | +/** |
| 5 | + * TDD for the two data-contract defects found on 2026-08-17. |
| 6 | + * |
| 7 | + * DEFECT 1 — truncation is invisible. |
| 8 | + * `bloqs list --json` returns 20 records as a FLAT ARRAY. The account has 137. |
| 9 | + * Nothing in the payload says so, so a model reading it concludes it has |
| 10 | + * everything — and then confidently answers "your family project is #602", |
| 11 | + * missing #200, #137, #544 and #584, all of which live in the other 117. |
| 12 | + * The API DOES send pagination metadata; the CLI drops it on the floor. |
| 13 | + * |
| 14 | + * DEFECT 2 — `list` has no field contract. |
| 15 | + * `bloqs list --json` = 20 records x 4 fields = 2,290 bytes. |
| 16 | + * `agents list --json` = 30 records x 72 fields = 145,395 bytes. |
| 17 | + * Same verb, 63x apart. The second overflows every time, forcing a |
| 18 | + * spill -> jq -> narrow round-trip to answer "what agents do I have". |
| 19 | + * |
| 20 | + * These are not model failures. A tool that returns 15% of the data while |
| 21 | + * looking complete will defeat any model, and one that returns 145KB for a |
| 22 | + * listing will make even a good one work hard for an easy answer. |
| 23 | + */ |
| 24 | + |
| 25 | +describe("buildListEnvelope — truncation must declare itself", () => { |
| 26 | + test("reports returned and total, and flags truncation", () => { |
| 27 | + const env = buildListEnvelope(new Array(20).fill({ id: 1 }), { total: 137, limit: 20 }) |
| 28 | + expect(env.meta.returned).toBe(20) |
| 29 | + expect(env.meta.total).toBe(137) |
| 30 | + expect(env.meta.truncated).toBe(true) |
| 31 | + }) |
| 32 | + |
| 33 | + test("is NOT truncated when everything fits", () => { |
| 34 | + const env = buildListEnvelope(new Array(11).fill({ id: 1 }), { total: 11, limit: 20 }) |
| 35 | + expect(env.meta.truncated).toBe(false) |
| 36 | + expect(env.meta.hint).toBeUndefined() |
| 37 | + }) |
| 38 | + |
| 39 | + test("infers truncation when the server sends no total but the page is full", () => { |
| 40 | + // A full page is the only evidence available that more may exist. Claiming |
| 41 | + // "complete" here is the exact failure being fixed, so assume more. |
| 42 | + const env = buildListEnvelope(new Array(20).fill({ id: 1 }), { limit: 20 }) |
| 43 | + expect(env.meta.truncated).toBe(true) |
| 44 | + expect(env.meta.total).toBeUndefined() |
| 45 | + }) |
| 46 | + |
| 47 | + test("a short page with no total is complete", () => { |
| 48 | + const env = buildListEnvelope(new Array(7).fill({ id: 1 }), { limit: 20 }) |
| 49 | + expect(env.meta.truncated).toBe(false) |
| 50 | + }) |
| 51 | + |
| 52 | + test("the hint names a REAL escape, not just the fact of truncation", () => { |
| 53 | + // "there is more" without "here is how to get it" still leaves the agent |
| 54 | + // guessing, and guessing is what produced the wrong answer. |
| 55 | + const env = buildListEnvelope(new Array(20).fill({ id: 1 }), { total: 137, limit: 20, resource: "bloqs" }) |
| 56 | + expect(env.meta.hint).toContain("--limit") |
| 57 | + expect(env.meta.hint).toContain("search") |
| 58 | + }) |
| 59 | + |
| 60 | + test("keeps the rows under `data`, unchanged", () => { |
| 61 | + const rows = [{ id: 602, name: "Mia Mayo — Life Atlas" }] |
| 62 | + const env = buildListEnvelope(rows, { total: 137, limit: 20 }) |
| 63 | + expect(env.data).toEqual(rows) |
| 64 | + }) |
| 65 | + |
| 66 | + test("handles an empty result without claiming truncation", () => { |
| 67 | + const env = buildListEnvelope([], { total: 0, limit: 20 }) |
| 68 | + expect(env.meta.returned).toBe(0) |
| 69 | + expect(env.meta.truncated).toBe(false) |
| 70 | + }) |
| 71 | +}) |
| 72 | + |
| 73 | +describe("projectFields — `list` returns identity, not everything", () => { |
| 74 | + const agent = { |
| 75 | + id: 703, name: "MODEL BENCH", type: "assistant", active: true, |
| 76 | + config: { a: 1 }, settings: { b: 2 }, stats: { c: 3 }, |
| 77 | + google_workspace_groups: [], initial_prompt: "x".repeat(4000), |
| 78 | + personality_traits: {}, v7_config: {}, updated_at: "2026-08-17", |
| 79 | + } |
| 80 | + |
| 81 | + test("keeps only the allowed fields", () => { |
| 82 | + const [out] = projectFields([agent], ["id", "name", "type", "active"]) |
| 83 | + expect(Object.keys(out).sort()).toEqual(["active", "id", "name", "type"]) |
| 84 | + }) |
| 85 | + |
| 86 | + test("drops the heavy blobs that make a listing 145KB", () => { |
| 87 | + const [out] = projectFields([agent], LIST_FIELDS.agents) |
| 88 | + expect(out).not.toHaveProperty("initial_prompt") |
| 89 | + expect(out).not.toHaveProperty("config") |
| 90 | + expect(out).not.toHaveProperty("settings") |
| 91 | + expect(out).not.toHaveProperty("v7_config") |
| 92 | + }) |
| 93 | + |
| 94 | + test("ALWAYS keeps id, even if the caller forgets it", () => { |
| 95 | + // Without an id the row cannot be followed up with `get`, which makes a |
| 96 | + // listing useless rather than merely lean. |
| 97 | + const [out] = projectFields([agent], ["name"]) |
| 98 | + expect(out).toHaveProperty("id", 703) |
| 99 | + }) |
| 100 | + |
| 101 | + test("ignores requested fields the record does not have", () => { |
| 102 | + const [out] = projectFields([agent], ["id", "name", "does_not_exist"]) |
| 103 | + expect(out).not.toHaveProperty("does_not_exist") |
| 104 | + expect(out).toHaveProperty("name") |
| 105 | + }) |
| 106 | + |
| 107 | + test("returns rows untouched when no field list is given", () => { |
| 108 | + // `get` must keep returning everything — the contract is about `list`. |
| 109 | + const [out] = projectFields([agent], undefined) |
| 110 | + expect(Object.keys(out).length).toBe(Object.keys(agent).length) |
| 111 | + }) |
| 112 | + |
| 113 | + test("every LIST_FIELDS set is small enough to be a listing", () => { |
| 114 | + // The rule this encodes: identity + a few discriminators. If a set grows past |
| 115 | + // this, it has stopped being a listing and should be a `get`. |
| 116 | + for (const [resource, fields] of Object.entries(LIST_FIELDS)) { |
| 117 | + expect(fields.length).toBeLessThanOrEqual(8) |
| 118 | + expect(fields).toContain("id") |
| 119 | + expect(fields, `${resource} needs a human-readable label`).toSatisfy( |
| 120 | + (f: string[]) => f.includes("name") || f.includes("title"), |
| 121 | + ) |
| 122 | + } |
| 123 | + }) |
| 124 | + |
| 125 | + test("the agents projection actually collapses the payload", () => { |
| 126 | + // The measured defect: 30 agents x 72 fields = 145,395 bytes. |
| 127 | + const many = new Array(30).fill(agent) |
| 128 | + const before = JSON.stringify(many).length |
| 129 | + const after = JSON.stringify(projectFields(many, LIST_FIELDS.agents)).length |
| 130 | + expect(after).toBeLessThan(before / 10) |
| 131 | + }) |
| 132 | +}) |
0 commit comments