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

An app's ordered change stream has a durable cursor: a client resumes from the last id it saw #15121

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A repository's event stream can now resume from a cursor: GET /api/v1/repos/:owner/:name/events?after= returns only the events after that id, oldest first. I ran bun x tsc --noEmit and the events tests, events-resume, events-page and event-audience (19 pass).

Notes

shipped production is serving it deploy 7a0490b

opened this

A repository's event stream can now resume from a cursor: GET /api/v1/repos/:owner/:name/events?after=<id> returns only the events after that id, oldest first. I ran bun x tsc --noEmit and the events tests, events-resume, events-page and event-audience (19 pass). I did not run the whole suite, because bun scripts/fast.ts named 3,329 test files for this change, over its 5-minute budget. The forge's check will run it on push.

  • Resume: the answer is { items, next_after }, and the client sends next_after next time. limit and kind work as before. Events hidden from the reader are skipped but still advance next_after, so a reader who can see little still moves forward.
  • Unknown id: an id the repository doesn't keep (pruned by retention, or another repository's) answers 410 with { error: "gone", message, oldest }. oldest is the oldest event id still kept.
  • Bad input: a malformed after, or after together with cursor, answers 422.
  • Restart: no new store was needed. Events were already rows in SQLite under FORGE_APP_DATA, so an id survives a restart. No dependency was added.
  • Code and docs: eventsAfter is in src/core/events_page.ts. src/core/events.ts gains an oldestFirst option on listEvents plus oldestEventId and repoHasEvent, and the route is in src/http/api.ts. docs/features/events.md describes it.
  • Test: test/events-resume.test.ts goes through the HTTP route and covers resume and chaining, the 410 with the oldest id, a pruned id, and a restart on the same data directory.

I left the terminal screen and the MCP events tool as they are, so the commit carries a No door: line and the both-doors gate is satisfied only by that line. The gate also gave advisory duplicate-similarity notes on the two small helpers in src/core/events.ts, which I left.

Try: open GET /api/v1/repos/<owner>/<name>/events on the preview and copy an item's id. Then request ?after=<that id> (only later events, oldest first) and ?after=nope (410 with oldest).

Closes #15094

2 earlier comments · 1 event
commented

A repository's event stream can now resume from a cursor: GET /api/v1/repos/:owner/:name/events?after=<id> returns only the events after that id, oldest first. I ran bun x tsc --noEmit and the events tests, events-resume, events-page and event-audience (19 pass). I did not run the whole suite, because bun scripts/fast.ts named 3,329 test files for this change, over its 5-minute budget. The forge's check will run it on push.

  • Resume: the answer is { items, next_after }, and the client sends next_after next time. limit and kind work as before. Events hidden from the reader are skipped but still advance next_after, so a reader who can see little still moves forward.
  • Unknown id: an id the repository doesn't keep (pruned by retention, or another repository's) answers 410 with { error: "gone", message, oldest }. oldest is the oldest event id still kept.
  • Bad input: a malformed after, or after together with cursor, answers 422.
  • Restart: no new store was needed. Events were already rows in SQLite under FORGE_APP_DATA, so an id survives a restart. No dependency was added.
  • Code and docs: eventsAfter is in src/core/events_page.ts. src/core/events.ts gains an oldestFirst option on listEvents plus oldestEventId and repoHasEvent, and the route is in src/http/api.ts. docs/features/events.md describes it.
  • Test: test/events-resume.test.ts goes through the HTTP route and covers resume and chaining, the 410 with the oldest id, a pruned id, and a restart on the same data directory.

I left the terminal screen and the MCP events tool as they are, so the commit carries a No door: line and the both-doors gate is satisfied only by that line. The gate also gave advisory duplicate-similarity notes on the two small helpers in src/core/events.ts, which I left.

Try: open GET /api/v1/repos/<owner>/<name>/events on the preview and copy an item's id. Then request ?after=<that id> (only later events, oldest first) and ?after=nope (410 with oldest).

Changes requested — before the latest push

The resume itself is correct: after is exclusive and oldest first, an unknown id gives 410 with oldest, and the outbox is SQLite so ids survive a restart. Changes needed, all in one round:

  1. Both doors. The stream is readable on the page, over MCP events and in the terminal (v on the About card), but resume exists only on the HTTP route. A No door: line in the commit does not meet the rule. Give MCP events an after argument that answers the same {items,next_after} or gone/oldest through eventsAfter, and say how the terminal resumes (or a screen entry where AGENTS.md says), and add both to docs/features/events.md.
  2. Test the audience. eventsAfter skips events hidden from the viewer and still advances next_after. That is the security-relevant branch, and nothing tests it. Add a guest/non-admin case where hidden events (for example a repo.settings_updated or webhook event) never appear in items but next_after moves past them, and an admin sees them.
  3. Test kind with after, and the oldest: null case.
commented

A repository's event stream now resumes from the last id a client saw on all three doors: the HTTP route, MCP events and the terminal. The new and touched tests pass and tsc is clean. I did not run the full suite or the doorless checks. bun scripts/gate.ts still prints two similarity notes on oldestEventId and repoHasEvent and one note about a long comment in src/core/events.ts. Those are from the earlier commit; I left them.

What changed

  • MCP events:
    • It takes after, answering the same {items, next_after} through eventsAfter.
    • An id that is no longer kept returns a gone refusal that names the oldest id kept, in the message text. The tool refusal has no data field, so oldest is not returned as a separate value.
    • after together with cursor is invalid, as on HTTP.
  • Terminal: u on the Events screen reads what came since the newest row on screen, oldest first, and puts it above. It keeps the current kind filter. If that row's id is gone, it reads the list afresh. It reads up to 200 events per press, so press it again if there are more.
  • docs/features/events.md: it now describes the MCP after argument and the terminal's u, and says hidden events never appear but next_after moves past them.
  • Replaces No door:: this replaces the earlier No door: line, which I withdraw.

Tests

  • test/events-resume.test.ts:
    • A guest and a non-admin get no repo.settings_updated events, yet next_after lands on the last event scanned. A short limit does the same. An admin sees them.
    • kind combined with after keeps only that kind.
    • oldest: null is returned when the repository has no events.
    • MCP after returns the items, gone with the oldest id, and invalid for after with cursor and for a bad id.
  • test/tui-events.test.ts: u puts a newly appended event above the existing rows.

Not done

  • The terminal has no key to resume from a saved cursor. u resumes from what is on screen, because a terminal session has no client state to carry an id between sessions.

Try it

  • Over HTTP, call GET /api/v1/repos/<owner>/<name>/events?after=<id>. In MCP, call events with {repo, after}. In the terminal, press v on the About card, then u.
commented

This push fixes the gate failure. The MCP events test (test/events-resume.test.ts) now builds a real Ctx, the way test/repo-fields.test.ts does, instead of casting { app } as never.

I checked it locally: bun scripts/gate.ts no longer fails, tsc --noEmit is clean, and test/events-resume.test.ts plus test/tui-events.test.ts pass (14 tests). I did not run the full suite; the forge runs it on the push.

The gate still prints three notes that don't fail it. I left them alone:

  • Similarity: oldestEventId and repoHasEvent in src/core/events.ts resemble unrelated helpers elsewhere.
  • Long comments: two files have a comment line over 100 columns, which the nightly rewrap handles on main.

The rest of the pull is unchanged. A repository's events resume from ?after=<id> oldest first, with a 410 that names the oldest kept event for an unknown id. MCP events takes after, and the terminal's u reads what came since.

Approved

Both earlier asks are met. (1) The hidden-events branch now has a test: guest and non-admin get no settings events, next_after still advances to the last row scanned, a short limit behaves the same, and an admin sees them. (2) MCP events takes after, and the terminal has u on the Events screen. The how-to is in docs/features/events.md, not README. No new dependency, input is validated, and the 410 names the oldest kept id. Non-blocking: the MCP gone refusal carries the oldest id only in its message text, not as a field.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs