Public: anyone can read this; the crew can change it.

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

Parked opened this
Closed without merging

scout/forge:scout/4772-a-repository-s-events-page-through-the-a → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
10 files changed +161 −12
README.md +1 −1
@@ -208,7 +208,7 @@ runs no check and no preview until a writer approves its head or lets it run
208208 (**Let it run here**, which is not a review; a new push waits again), and a bare push to `child/…` starts none. A pull
209209 opened with it says "proposed by child … from …" on every tab of the pull's
210210 page, in the terminal's pull view, and as `proposal` in the pull's JSON
211 (`GET …/pulls/:number`, and MCP's `pull` tool). `GET …/pulls/:number?diff=0` reads the pull without its diff (and skips computing it); `diff` is `0` or `1`, default `1`, and anything else answers 422. `GET …/issues?fields=brief` lists issues with only number, kind, title, state, labels, assignee, author, originAuthor, authorIsAgent, createdAt and updatedAt (and `untrusted` where it applies); no bodies or comments. `fields` is `brief` or left out, and anything else answers 422 `invalid_fields`.
211 (`GET …/pulls/:number`, and MCP's `pull` tool). `GET …/pulls/:number?diff=0` reads the pull without its diff (and skips computing it); `diff` is `0` or `1`, default `1`, and anything else answers 422. `GET …/issues?fields=brief` lists issues with only number, kind, title, state, labels, assignee, author, originAuthor, authorIsAgent, createdAt and updatedAt (and `untrusted` where it applies); no bodies or comments. `fields` is `brief` or left out, and anything else answers 422 `invalid_fields`. `GET …/repos/:owner/:name/events` answers `{ items, next_cursor }`, newest first, `limit` 1 to 200 (default 50) and `cursor` from `next_cursor` (anything else is a 422); it used to answer a bare array of every event, so a client that read the array reads `items` now. MCP's `events` tool answers the same.
212212
213213 ### Proposing to a parent forge
214214
docs/MCP.md +1
@@ -46,6 +46,7 @@ for a tunnel and a forge that sleeps.
4646 | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
4747 | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
4848 | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes |
49 | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no |
4950 | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes |
5051 | `branches` | `{ repo, name?, action?, from? }`: without `name`, lists the branches; with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes |
5152 | `commits` | `{ repo, ref?, limit? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers | |
src/contract/openapi.ts +1
@@ -92,6 +92,7 @@ export const ROUTES: readonly Route[] = [
9292 auth: true,
9393 body: { body: "string" },
9494 },
95 { method: "get", path: `${REPO}/events`, summary: "Page through a repository's events as the caller may see them, newest first: {items, next_cursor}; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", auth: false, query: { limit: "integer", cursor: "string" } },
9596 { method: "post", path: `${REPO}/forks`, summary: "Fork a repository", auth: true },
9697 {
9798 method: "post",
src/core/events.ts +11
@@ -110,7 +110,14 @@ const afterEvent = (n: number): string =>
110110 THEN event.seq > (SELECT c.seq FROM event AS c WHERE c.id = ?${n})
111111 ELSE event.id > ?${n} END)`;
112112
113 const beforeEvent = (n: number): string =>
114 `(CASE WHEN EXISTS (SELECT 1 FROM event AS c WHERE c.id = ?${n})
115 THEN event.seq < (SELECT c.seq FROM event AS c WHERE c.id = ?${n})
116 ELSE event.id < ?${n} END)`;
117
113118 export interface ListEventsOptions {
119 /** Return events written before this one (exclusive; the next page of a newest-first read). */
120 beforeId?: string;
114121 repoId?: string;
115122 /** Restrict to events of this kind. */
116123 kind?: string;
@@ -206,6 +213,10 @@ export function listEvents(
206213 params.push(options.afterId);
207214 clauses.push(afterEvent(params.length));
208215 }
216 if (options.beforeId !== undefined) {
217 params.push(options.beforeId);
218 clauses.push(beforeEvent(params.length));
219 }
209220 params.push(options.limit ?? 100);
210221 const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
211222 const limit = params.length;
src/core/events_page.ts added +49
@@ -0,0 +1,49 @@
1 import type { Database } from "bun:sqlite";
2 import { audienceFilter, eventForReader } from "./event_audience.ts";
3 import { listEvents } from "./events.ts";
4
5 export const EVENTS_LIMIT_DEFAULT = 50;
6 export const EVENTS_LIMIT_MAX = 200;
7
8 /** Read a `limit` as the API and MCP both take it: a whole number, 1 to 200, or undefined. */
9 export function eventsLimit(raw: unknown): number | undefined {
10 if (raw === undefined || raw === null) return EVENTS_LIMIT_DEFAULT;
11 const n = typeof raw === "string" ? (/^\d{1,4}$/.test(raw) ? Number(raw) : 0) : Number(raw);
12 return Number.isInteger(n) && n >= 1 && n <= EVENTS_LIMIT_MAX ? n : undefined;
13 }
14
15 /** A cursor is the id of the last event of the page before. */
16 export const validEventsCursor = (raw: string): boolean => /^[A-Za-z0-9_-]{1,64}$/.test(raw);
17
18 /**
19 * A repository's events as this reader is meant to see them, newest first,
20 * one bounded page. The audience filter runs before the page is cut, so a
21 * hidden event never shifts a page or leaks through the cursor.
22 */
23 export function eventsPage(
24 db: Database,
25 repoId: string,
26 viewer: Parameters<typeof audienceFilter>[1],
27 limit: number,
28 cursor?: string,
29 ) {
30 const visible = audienceFilter(db, viewer);
31 const toReader = eventForReader(db, viewer);
32 const found: ReturnType<typeof listEvents> = [];
33 let before = cursor;
34 while (found.length <= limit) {
35 const batch = listEvents(db, {
36 repoId,
37 limit: EVENTS_LIMIT_MAX,
38 ...(before === undefined ? {} : { beforeId: before }),
39 });
40 for (const event of batch) if (visible(event)) found.push(event);
41 if (batch.length < EVENTS_LIMIT_MAX) break;
42 before = batch[batch.length - 1]!.id;
43 }
44 const page = found.slice(0, limit);
45 return {
46 items: page.map(toReader),
47 next_cursor: found.length > limit ? page[page.length - 1]!.id : null,
48 };
49 }
src/http/api.ts +9 −5
@@ -179,6 +179,7 @@ import {
179179 updateProfile,
180180 } from "../actions/users.ts";
181181 import { listEvents } from "../core/events.ts";
182 import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts";
182183 import { audienceFor } from "../core/audience.ts";
183184 import { audienceFilter, eventForReader } from "../core/event_audience.ts";
184185 import {
@@ -2478,11 +2479,14 @@ export function apiRoutes(router: Router<Handler>): void {
24782479 if (!repo) return notFound();
24792480 // The outbox, as this reader is meant to see it: a webhook's URL and an
24802481 // app's variable names are the admins', not every reader's.
2481 return json(
2482 listEvents(ctx.app.db, { repoId: repo.id }).filter(
2483 audienceFilter(ctx.app.db, ctx.auth.user),
2484 ).map(eventForReader(ctx.app.db, ctx.auth.user)),
2485 );
2482 const q = ctx.url.searchParams;
2483 const limit = eventsLimit(q.get("limit"));
2484 if (limit === undefined)
2485 return apiError("invalid_limit", 422, `limit is a whole number from 1 to ${EVENTS_LIMIT_MAX}`);
2486 const cursor = q.get("cursor");
2487 if (cursor !== null && !validEventsCursor(cursor))
2488 return apiError("invalid_cursor", 422, "cursor is the next_cursor of a page before");
2489 return json(eventsPage(ctx.app.db, repo.id, ctx.auth.user, limit, cursor ?? undefined));
24862490 });
24872491
24882492 router.add("GET", "/api/v1/repos/:owner/:name/forks", (ctx) => {
src/http/mcp.ts +25
@@ -18,6 +18,7 @@
1818 */
1919
2020 import { showProvenance } from "../actions/provenance.ts";
21 import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts";
2122 import { getProvenance, provenanceFacts, trailFacts } from "../core/provenance.ts";
2223 import { upstreamPayload } from "../spawn/upstream.ts";
2324 import { NOT_A_MEMBER } from "../core/roles.ts";
@@ -1757,6 +1758,30 @@ const TOOLS: readonly Tool[] = [
17571758 });
17581759 },
17591760 },
1761 {
1762 name: "events",
1763 description: "A repository's recent events, newest first: `{ items, next_cursor }`.",
1764 inputSchema: {
1765 type: "object",
1766 properties: {
1767 repo: REPO_ARG,
1768 limit: { type: "integer", minimum: 1, maximum: EVENTS_LIMIT_MAX },
1769 cursor: { type: "string" },
1770 },
1771 required: ["repo"],
1772 },
1773 writes: false,
1774 run(ctx, user, args) {
1775 const repo = repoArg(ctx, user, args);
1776 if (isAnswer(repo)) return repo;
1777 const limit = eventsLimit(args["limit"]);
1778 if (limit === undefined) return bad("invalid", `limit is 1 to ${EVENTS_LIMIT_MAX}`);
1779 const given = args["cursor"];
1780 if (given !== undefined && (typeof given !== "string" || !validEventsCursor(given)))
1781 return bad("invalid", "that cursor was not issued here");
1782 return good(eventsPage(ctx.app.db, repo.id, user, limit, given));
1783 },
1784 },
17601785 {
17611786 name: "branches",
17621787 description:
test/app.test.ts +3 −4
@@ -186,10 +186,9 @@ describe("the forge, end to end", () => {
186186 await shOk(["git", "push", "origin", "main"], dir);
187187
188188 const events = await api("/api/v1/repos/alice/app/events");
189 const list = (await events.json()) as {
190 kind: string;
191 payload: { updates?: { ref: string }[] };
192 }[];
189 const list = ((await events.json()) as {
190 items: { kind: string; payload: { updates?: { ref: string }[] } }[];
191 }).items;
193192 const push = list.find((e) => e.kind === "push");
194193 expect(push).toBeDefined();
195194 expect(push?.payload.updates?.[0]?.ref).toBe("refs/heads/main");
test/event-audience.test.ts +60 −2
@@ -187,8 +187,8 @@ describe("who an event is for", () => {
187187 });
188188 const read = (headers: Record<string, string>) =>
189189 fetch(`${base}/api/v1/repos/alice/open/events`, { headers })
190 .then((r) => r.json() as Promise<{ kind: string; payload: Record<string, unknown> }[]>)
191 .then((all) => all.find((e) => e.kind === "run.finished")!);
190 .then((r) => r.json() as Promise<{ items: { kind: string; payload: Record<string, unknown> }[] }>)
191 .then((all) => all.items.find((e) => e.kind === "run.finished")!);
192192 for (const headers of [{}, { authorization: `Bearer ${bobToken}` }]) {
193193 const seen = await read(headers);
194194 expect(seen.payload["runId"]).toBe("r1");
@@ -203,6 +203,64 @@ describe("who an event is for", () => {
203203 expect(owner.payload["node"]).toBe("vx-secret-node");
204204 });
205205
206 test("MCP `events` keeps the reader's view: no webhook URL or variable name for a reader, all for an admin", async () => {
207 const call = async (token: string, args: unknown) => {
208 const res = await fetch(`${base}/mcp`, {
209 method: "POST",
210 headers: {
211 "content-type": "application/json",
212 accept: "application/json, text/event-stream",
213 authorization: `Bearer ${token}`,
214 },
215 body: JSON.stringify({
216 jsonrpc: "2.0",
217 id: 1,
218 method: "tools/call",
219 params: { name: "events", arguments: args },
220 }),
221 });
222 return ((await res.json()) as any).result as { isError?: boolean; content: { text: string }[] };
223 };
224 const reader = await call(bobToken, { repo: "alice/open" });
225 expect(reader.isError).not.toBe(true);
226 const text = reader.content[0]!.text;
227 expect(text).toContain('"push"');
228 expect(text).toContain("next_cursor");
229 expect(text).not.toContain("hooks.example.test");
230 expect(text).not.toContain("STRIPE_SECRET_KEY");
231 const admin = (await call(aliceToken, { repo: "alice/open" })).content[0]!.text;
232 expect(admin).toContain("webhook.created");
233 expect(admin).toContain("app.env_set");
234 expect((await call(bobToken, { repo: "alice/open", limit: 0 })).isError).toBe(true);
235 expect((await call(bobToken, { repo: "alice/open", limit: 201 })).isError).toBe(true);
236 });
237
238 test("the API pages events: limit cuts, next_cursor reaches the end, a bad limit is a 422", async () => {
239 const get = (qs: string) =>
240 fetch(`${base}/api/v1/repos/alice/open/events${qs}`, {
241 headers: { authorization: `Bearer ${aliceToken}` },
242 });
243 type Page = { items: { id: string }[]; next_cursor: string | null };
244 const everything = (await (await get("")).json()) as Page;
245 expect(everything.next_cursor).toBeNull();
246 expect(everything.items.length).toBeGreaterThan(3);
247 const seen: string[] = [];
248 let cursor: string | null = null;
249 let pages = 0;
250 do {
251 const page = (await (await get(`?limit=2${cursor ? `&cursor=${cursor}` : ""}`)).json()) as Page;
252 expect(page.items.length).toBeLessThanOrEqual(2);
253 seen.push(...page.items.map((e) => e.id));
254 cursor = page.next_cursor;
255 pages++;
256 } while (cursor !== null && pages < 100);
257 expect(cursor).toBeNull();
258 expect(pages).toBeGreaterThan(1);
259 expect(seen).toEqual(everything.items.map((e) => e.id));
260 for (const bad of ["limit=0", "limit=201", "limit=abc", "limit=1.5", "cursor=a%20b"])
261 expect((await get(`?${bad}`)).status).toBe(422);
262 });
263
206264 test("the activity rail on the front page says nothing of it to a visitor", async () => {
207265 const page = await fetch(`${base}/`, {
208266 headers: { accept: "text/html" },
test/mcp.test.ts +1
@@ -206,6 +206,7 @@ describe("the forge over MCP", () => {
206206 "decisions_by",
207207 "archive",
208208 "trail",
209 "events",
209210 "branches",
210211 "commits",
211212 "probe",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs