Skip to content

Commit 7ad8e74

Browse files
mayoalexanderclaude
andcommitted
feat(cli): list must declare what it withholds, and return identity not everything
Two data-contract defects, both measured, both of which read as model failures and were not. Written test-first; the tests fail against the old behaviour. 1. TRUNCATION WAS INVISIBLE. `bloqs list --json` returned 20 records as a FLAT ARRAY. The account has 137. No total, no truncated flag, no next — so a model reading it reasonably concluded it had everything, then answered "your family project is anomalyco#602" while #200 Family Businesses, #137 Family Health and Finance, #544 and #584 sat in the other 117. The API sends the total; the CLI dropped it on the floor. Now: {data, meta:{returned, total, truncated, limit, hint}}. Verified live — returned 20, total 137, truncated true. When the server sends no total, a FULL page is treated as truncated. Claiming "complete" on no evidence is exactly the failure being fixed: over-reporting costs one extra query, under-reporting produces a confident wrong answer. 2. `list` HAD NO FIELD CONTRACT. bloqs list = 20 records x 4 fields = 2,290 bytes agents list = 30 records x 72 fields = 145,395 bytes Same verb, 63x apart. The second overflowed the MCP every time, forcing a spill -> jq -> narrow round-trip to answer "what agents do I have". LIST_FIELDS caps a listing at 8 fields — identity plus discriminators — and a test enforces the ceiling plus the presence of an id and a human-readable label, because a row you cannot follow up with `get` is not lean, it is useless. `agents get <id>` still returns the full record. Measured: agents list 145,395 -> 7,828 bytes. 18.6x. It no longer overflows. WHY THIS RATHER THAN MORE PROMPTING. I previously diagnosed the missed-bloqs bug as a prompt problem and wrote tool-description guidance for it. That guidance still helps, but it was teaching models to compensate for a payload that misleads them. A tool returning 15% of the data while looking complete will defeat any model; one returning 145KB for a listing makes an easy question expensive. Fix the contract, not the reader. Shape change on --json for these two commands: consumers doing `jq '.[]'` now need `jq '.data[]'`. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 27bbf37 commit 7ad8e74

4 files changed

Lines changed: 281 additions & 3 deletions

File tree

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
/**
2+
* The `list` data contract: say how much you are withholding, and return identity
3+
* rather than everything.
4+
*
5+
* Two defects measured on 2026-08-17, both of which read as model failures and
6+
* were not:
7+
*
8+
* 1. TRUNCATION WAS INVISIBLE. `bloqs list --json` returned 20 records as a flat
9+
* array. The account has 137. Nothing in the payload said so — no total, no
10+
* truncated flag, no next — so a model reading it reasonably concluded it had
11+
* everything, then answered "your family project is #602" while #200 (Family
12+
* Businesses), #137 (Family Health and Finance), #544 and #584 sat in the other
13+
* 117. The API sends pagination metadata; the CLI dropped it.
14+
*
15+
* 2. `list` HAD NO FIELD CONTRACT. bloqs list = 20 x 4 fields = 2,290 bytes.
16+
* agents list = 30 x 72 fields = 145,395 bytes. Same verb, 63x apart. The
17+
* second overflowed every time, forcing a spill -> jq -> narrow round-trip to
18+
* answer "what agents do I have".
19+
*
20+
* A tool that returns 15% of the data while looking complete will defeat any
21+
* model, and one that returns 145KB for a listing makes an easy question
22+
* expensive. Prompt guidance can compensate for both; it should not have to.
23+
*/
24+
25+
export interface ListMeta {
26+
/** How many rows are in `data`. */
27+
returned: number
28+
/** How many exist server-side, when the API tells us. Absent means unknown. */
29+
total?: number
30+
/** True when rows are being withheld — or when we cannot rule it out. */
31+
truncated: boolean
32+
/** The page size that produced this result. */
33+
limit?: number
34+
/** Present only when truncated: how to actually get the rest. */
35+
hint?: string
36+
}
37+
38+
export interface ListEnvelope<T> {
39+
data: T[]
40+
meta: ListMeta
41+
}
42+
43+
/**
44+
* Wrap rows with metadata that makes withholding visible.
45+
*
46+
* When the server sends no total, a FULL page is treated as truncated. That is
47+
* deliberate: a full page is the only evidence available, and claiming
48+
* "complete" on no evidence is precisely the failure being fixed. Over-reporting
49+
* truncation costs one extra query; under-reporting it produces a confident
50+
* wrong answer.
51+
*/
52+
export function buildListEnvelope<T>(
53+
rows: T[],
54+
opts: { total?: number; limit?: number; resource?: string } = {},
55+
): ListEnvelope<T> {
56+
const returned = rows.length
57+
const { total, limit, resource } = opts
58+
59+
const truncated =
60+
typeof total === "number"
61+
? returned < total
62+
: typeof limit === "number" && returned >= limit && returned > 0
63+
64+
const meta: ListMeta = { returned, truncated }
65+
if (typeof total === "number") meta.total = total
66+
if (typeof limit === "number") meta.limit = limit
67+
68+
if (truncated) {
69+
const noun = resource ?? "results"
70+
const searchCmd = resource ? `iris ${resource} search <term>` : "search"
71+
meta.hint =
72+
`Showing ${returned}${typeof total === "number" ? ` of ${total}` : ""} ${noun}. ` +
73+
`This is NOT the full set — do not answer "which do I have" from it. ` +
74+
`Use --limit <n> for more, or ${searchCmd} to find by keyword across everything.`
75+
}
76+
77+
return { data: rows, meta }
78+
}
79+
80+
/**
81+
* Summary fields per resource — identity plus the few discriminators a caller
82+
* needs to choose a row and then `get` it.
83+
*
84+
* The ceiling is 8. Past that it has stopped being a listing, and the caller
85+
* should be fetching the record instead. A test enforces both the ceiling and
86+
* the presence of an id and a human-readable label, because a row you cannot
87+
* follow up on is not lean, it is useless.
88+
*/
89+
export const LIST_FIELDS: Record<string, string[]> = {
90+
bloqs: ["id", "name", "type", "is_owner"],
91+
agents: ["id", "name", "type", "active", "description", "last_active_at"],
92+
leads: ["id", "name", "email", "company", "status", "updated_at"],
93+
pages: ["id", "title", "slug", "status", "updated_at"],
94+
workflows: ["id", "name", "type", "active", "updated_at"],
95+
}
96+
97+
/**
98+
* Keep only `allow` on each row. `id` survives regardless — a row that cannot be
99+
* followed up with `get` defeats the purpose of a listing.
100+
*
101+
* Passing `undefined` returns rows untouched, so `get` keeps returning
102+
* everything. The contract is about `list`.
103+
*/
104+
export function projectFields<T extends Record<string, any>>(
105+
rows: T[],
106+
allow: string[] | undefined,
107+
): Partial<T>[] {
108+
if (!allow || allow.length === 0) return rows
109+
110+
const keys = allow.includes("id") ? allow : ["id", ...allow]
111+
112+
return rows.map((row) => {
113+
const out: Partial<T> = {}
114+
for (const k of keys) {
115+
if (row && Object.prototype.hasOwnProperty.call(row, k)) {
116+
out[k as keyof T] = row[k]
117+
}
118+
}
119+
return out
120+
})
121+
}

‎packages/opencode/src/cli/cmd/platform-agents.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { cmd } from "./cmd"
22
import * as prompts from "./clack"
33
import { UI } from "../ui"
4+
import { buildListEnvelope, projectFields, LIST_FIELDS } from "./list-envelope"
45
import { irisFetch, requireAuth, handleApiError, requireUserId, printDivider, printKV, dim, bold, success, highlight, isNonInteractive, IRIS_API, writeJson } from "./iris-api"
56
import { matchesSearchQuery } from "./bloq-item-format"
67
import { executeChat } from "./platform-chat"
@@ -161,7 +162,17 @@ const AgentsListCommand = cmd({
161162
if (spinner) spinner.stop(`${agents.length} agent(s)${total > agents.length ? ` (${total} total — page ${currentPage}/${lastPage})` : ""}`)
162163

163164
if (args.json) {
164-
await writeJson({ agents, page: currentPage, total, last_page: lastPage })
165+
// Identity, not everything. This listing was 30 records x 72 fields =
166+
// 145,395 bytes, which overflowed the MCP every time and forced a
167+
// spill -> jq -> narrow round-trip to answer "what agents do I have".
168+
// `agents get <id>` still returns the full record.
169+
await writeJson(
170+
buildListEnvelope(projectFields(agents, LIST_FIELDS.agents), {
171+
total,
172+
limit: agents.length,
173+
resource: "agents",
174+
}),
175+
)
165176
return
166177
}
167178

‎packages/opencode/src/cli/cmd/platform-bloqs.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { cmd } from "./cmd"
2+
import { buildListEnvelope } from "./list-envelope"
23
import { federatedSearch, resolveSources, formatOutcomes } from "./federated-search"
34
import * as prompts from "./clack"
45
import { UI } from "../ui"
@@ -154,8 +155,11 @@ const BloqsListCommand = cmd({
154155
return
155156
}
156157

157-
const data = (await res.json()) as { data?: any[] }
158+
const data = (await res.json()) as { data?: any[]; total?: number; meta?: { total?: number } }
158159
let bloqs: any[] = data?.data ?? []
160+
// The index endpoint reports how many exist. Capture it — dropping it is what
161+
// made `bloqs list` look complete while withholding 117 of 137 boards.
162+
const serverTotal = data?.total ?? data?.meta?.total
159163
// Client-side filter (the API index endpoint returns all bloqs and ignores
160164
// the search param). Tokenize + AND the terms so a natural name like
161165
// "Mayo Life Atlas" matches a stored "MAYO — Life Atlas" — a raw substring
@@ -168,7 +172,17 @@ const BloqsListCommand = cmd({
168172
spinner.stop(`${bloqs.length} bloq(s)${args.search ? ` matching "${args.search}"` : ""}`)
169173

170174
if (args.json) {
171-
await writeJson(bloqs)
175+
// Envelope, not a bare array: an agent must be able to see that it is
176+
// holding a page rather than an inventory. Client-side search filtering
177+
// above changes the count, so a filtered result reports its own size and
178+
// is never labelled truncated against the server total.
179+
await writeJson(
180+
buildListEnvelope(bloqs, {
181+
total: args.search ? bloqs.length : serverTotal,
182+
limit: args.search ? undefined : Number(args.limit),
183+
resource: "bloqs",
184+
}),
185+
)
172186
return
173187
}
174188

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
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

Comments
 (0)