A repository's events page through the API and MCP `events`: `{ items, next_cursor }`, bounded, with the reader's view kept #4781

GET /api/v1/repos/:owner/:name/events now answers { items, next_cursor }, newest first, and MCP has an events tool right after trail. This push fixes the check failure that parked the issue. The type check is clean. The suites I ran pass: test/contents-api.test.ts, sealed-git, sealed-issues, event-audience and app. I did not run the full check.

The failure: the old caller in test/contents-api.test.ts ("a push event fires so the outbox/webhooks/SSE see API commits") still read the bare array. I missed it last time because it fetches the URL through ${base}/api/v1/repos/mira/app/events. It now reads .items. A second search of src/, test/ and scripts/ for readers of the old array found none.

What changed overall

• API: limit is a whole number from 1 to 200 (default 50), and cursor is the next_cursor of the previous page. A bad limit or cursor is a 422 (invalid_limit, invalid_cursor). audienceFilter and eventForReader are unchanged, so a reader never sees a webhook URL or a variable name.
• Paging: the new src/core/events_page.ts filters for the reader before it cuts the page, so a hidden event never shifts a page or leaks through a cursor. The API and MCP both call it, so they answer the same for the same caller. It needed a beforeId option on listEvents.
• MCP: the tool takes repo, limit and cursor. It has a one-sentence description, so test/mcp-size.test.ts still passes.
• Docs: docs/MCP.md has the row beside trail, and src/contract/openapi.ts describes the new shape. The README's API notes say the bare array is gone and clients should read items.
• Tests:

- A reader gets no webhook URL or variable name through the API or MCP, and an admin does. - limit pages until next_cursor is null, and the pages equal the unpaged list. - Bad limit and cursor values are a 422. - test/mcp.test.ts expects events after trail in tools/list.

Left out: the reader-view filtering has no scan cap. A repository whose older events are almost all hidden from the reader makes a request read more rows.

Closes #4772

GET /api/v1/repos/:owner/:name/events now answers { items, next_cursor }, newest first, and MCP has an events tool right after trail. This push fixes the check failure that parked the issue. The type check is clean. The suites I ran pass: test/contents-api.test.ts, sealed-git, sealed-issues, event-audience and app. I did not run the full check.

The failure: the old caller in test/contents-api.test.ts ("a push event fires so the outbox/webhooks/SSE see API commits") still read the bare array. I missed it last time because it fetches the URL through ${base}/api/v1/repos/mira/app/events. It now reads .items. A second search of src/, test/ and scripts/ for readers of the old array found none.

What changed overall

• API: limit is a whole number from 1 to 200 (default 50), and cursor is the next_cursor of the previous page. A bad limit or cursor is a 422 (invalid_limit, invalid_cursor). audienceFilter and eventForReader are unchanged, so a reader never sees a webhook URL or a variable name.
• Paging: the new src/core/events_page.ts filters for the reader before it cuts the page, so a hidden event never shifts a page or leaks through a cursor. The API and MCP both call it, so they answer the same for the same caller. It needed a beforeId option on listEvents.
• MCP: the tool takes repo, limit and cursor. It has a one-sentence description, so test/mcp-size.test.ts still passes.
• Docs: docs/MCP.md has the row beside trail, and src/contract/openapi.ts describes the new shape. The README's API notes say the bare array is gone and clients should read items.
• Tests:

- A reader gets no webhook URL or variable name through the API or MCP, and an admin does. - limit pages until next_cursor is null, and the pages equal the unpaged list. - Bad limit and cursor values are a 422. - test/mcp.test.ts expects events after trail in tools/list.

Left out: the reader-view filtering has no scan cap. A repository whose older events are almost all hidden from the reader makes a request read more rows.

The check's type error is fixed and pushed. The events change itself is unchanged from the earlier descriptions.

Cause: src/http/api.ts still imported listEvents, audienceFilter and eventForReader. They are now used only inside src/core/events_page.ts. I removed both import lines. A tsc --noUnusedLocals run shows nothing left in src/http/api.ts.

Verified: test/event-audience.test.ts and test/contents-api.test.ts pass (17 tests). I did not run the full check.

Not mine: that same tsc --noUnusedLocals run also flags Property 'hostKey' is declared but its value is never read at src/ssh/server.ts:78. I didn't touch that file and left it alone.

The events page now reads at most 1,000 rows per request (5 batches of 200), so the unbounded scan @sentinel flagged is closed. The type check is clean and test/event-audience.test.ts passes. I did not run the whole check.

• The cap: the change is in src/core/events_page.ts. When the cap is reached before limit + 1 visible events are found, the page is whatever was found, possibly short or empty. Its next_cursor resumes after the last scanned row.
• The cursor: when the page fills, the cursor is the last item's id, as before. It is null only when the outbox is exhausted.
• Subject lookups: each batch now goes to audienceFilter(db, viewer, batch), so sealed-subject lookups are one query per batch.
• New test: a reader pages a repository with 1,100 hidden events behind a few visible ones. The first limit=200 page is short and has a non-null next_cursor. Following cursors to the end gives exactly the unpaged reader view. The old loop returned the whole visible set in one page with a null cursor, so it would have failed this test.
• README: the API notes now say a page can come back short while next_cursor is non-null, and to keep following it until it is null. That is a visible change for clients that stop at the first short page.

The tools/list headroom failure is fixed and pushed.

Cause: main gained other MCP tools while this pull was open. After I merged main in, tools/list came to 37,002 bytes, 2 over the 37,000 ceiling. The events tool's description was the part I could trim.

Fix: I shortened the description to "A repository's events, newest first, paged." The { items, next_cursor } shape is still in docs/MCP.md and src/contract/openapi.ts, so only the one-line tool blurb lost it. I did not raise the ceiling.

bun test on test/mcp-size.test.ts, test/mcp.test.ts and test/event-audience.test.ts passes (51 tests), and the type check is clean. I did not run the whole check.

The earlier check log also showed shards 20, 22 and 23 exiting 143 without naming a test. They were skipped after the red exit, and I did not run them here.

The full gate on land was red; the pull is open again. Red tests:

• tools/list stays under 40 KB, with 3 KB of headroom (37,000 bytes)
• tools/list stays under 40 KB, with 3 KB of headroom (37,000 bytes) [26.82ms] [shard 663]

Red on top of #4802, which landed first from the same merge-queue candidate: red on its own on that base, or only together with them. Bring this pull up to date with the base and push.

The branch is up to date with main again, and tools/list is back under its headroom: 36,963 bytes against the 37,000 ceiling.

test/mcp-size.test.ts was red because main itself sits at exactly 37,000 bytes, so any new tool breaks it. To fit events (about 245 bytes after slimming it) I trimmed wording in other tools: spawn's parameter notes, and the descriptions of plan, close, asks_act, spend, model_ceiling, tell and a few more. Those tools now say slightly less than before.

My first trim broke test/asks-mute.test.ts, which expects "saved filter" in the asks and feed descriptions. I pushed that commit before running the neighbouring suites. I restored the wording and trimmed elsewhere instead. After that, tsc --noEmit is clean. Every test that reads tools/list or tool descriptions passes (233 tests), and the earlier MCP run (106) and test/event-audience.test.ts passed too. I did not run the whole check.

Headroom is only 37 bytes, so any other MCP tool landing in parallel will hit the ceiling again. Someone should raise it or cut descriptions in bulk.

I did not do @sentinel's low-severity point about making next_cursor opaque. When the scan cap stops a read, the cursor is the id of the last row scanned, and that can be a hidden event, so a non-admin learns it exists and roughly when. Changing the cursor to seq is a separate change to the cursor format and the beforeEvent SQL. I'd rather land the bounded read as approved and do that on its own.