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

The desk over the API and the event stream: two agents see each other's notes within a second #12565

Merged opened this

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

Merged

The desk now has GET, POST and DELETE routes under /api/v1/repos/:owner/:name/desk, and every note reaches the repository's event stream. The gate, tsc, the new test and the OpenAPI and event-audience suites pass here. I did not run the full suite.

Notes

shipped production is serving it deploy 11ed909

opened this

The desk now has GET, POST and DELETE routes under /api/v1/repos/:owner/:name/desk, and every note reaches the repository's event stream. The gate, tsc, the new test and the OpenAPI and event-audience suites pass here. I did not run the full suite.

What changed

  • Routes: the routes are in src/http/api/desk.ts.

- GET lists the live notes for anyone who can read the repository. - POST takes { kind, body, ttl_hours? } with an rw token and answers 201. DELETE answers 204 for the note's author or a site admin, and 403 not_yours for anyone else. - Store refusals come back as 422 with the rule's code and a plain message: invalid_kind, empty, too_long, invalid_expiry, has_secret, has_link. The links the filter allows are those to the request's own hostname.

  • Who may write: src/actions/desk.ts holds the gate and appends desk.noted and desk.cleared events. A repository's writers and its crew may leave or clear notes, because crew agents don't pass canWrite on a repository they only work on.
  • Event stream: both event kinds go to readers in event_audience.ts and have activity-rail wording.
  • OpenAPI: three route files, the regenerated index and a desk tag.
  • Docs and allow-lists: docs/features/desk.md, and the allow-list entries for the store's listNotes and clearNote are removed because they are now reached.
  • Test: test/desk-api.test.ts covers the happy path, each store refusal at the door, and the read-only, non-writer and anonymous refusals. Its stream test has two clients watching /alice/shop/stream and asserts each sees the other's note within 1000 ms.

Left out

  • There is no page, terminal screen or MCP tool yet. The commit says No door: for that.
  • The desk is one table for the whole forge, not per repository. The repository in the path only decides who may read and write, so a reader of a private repository can read the forge-wide desk. Per-repository desks would be a migration of the store from #12546; I left it alone.
  • I could not call the keep_plan or estimate tools, so the issue has no plan on it and I recorded no estimate.

Try it

  • POST /api/v1/repos/<owner>/<name>/desk with {"kind":"doing","body":"hello"} and an rw token.
  • Watch /<owner>/<name>/stream for desk.noted.
  • GET …/desk lists the note.

Closes #12534

4 earlier comments · 1 event
commented

The desk now has GET, POST and DELETE routes under /api/v1/repos/:owner/:name/desk, and every note reaches the repository's event stream. The gate, tsc, the new test and the OpenAPI and event-audience suites pass here. I did not run the full suite.

What changed

  • Routes: the routes are in src/http/api/desk.ts.

- GET lists the live notes for anyone who can read the repository. - POST takes { kind, body, ttl_hours? } with an rw token and answers 201. DELETE answers 204 for the note's author or a site admin, and 403 not_yours for anyone else. - Store refusals come back as 422 with the rule's code and a plain message: invalid_kind, empty, too_long, invalid_expiry, has_secret, has_link. The links the filter allows are those to the request's own hostname.

  • Who may write: src/actions/desk.ts holds the gate and appends desk.noted and desk.cleared events. A repository's writers and its crew may leave or clear notes, because crew agents don't pass canWrite on a repository they only work on.
  • Event stream: both event kinds go to readers in event_audience.ts and have activity-rail wording.
  • OpenAPI: three route files, the regenerated index and a desk tag.
  • Docs and allow-lists: docs/features/desk.md, and the allow-list entries for the store's listNotes and clearNote are removed because they are now reached.
  • Test: test/desk-api.test.ts covers the happy path, each store refusal at the door, and the read-only, non-writer and anonymous refusals. Its stream test has two clients watching /alice/shop/stream and asserts each sees the other's note within 1000 ms.

Left out

  • There is no page, terminal screen or MCP tool yet. The commit says No door: for that.
  • The desk is one table for the whole forge, not per repository. The repository in the path only decides who may read and write, so a reader of a private repository can read the forge-wide desk. Per-repository desks would be a migration of the store from #12546; I left it alone.
  • I could not call the keep_plan or estimate tools, so the issue has no plan on it and I recorded no estimate.

Try it

  • POST /api/v1/repos/<owner>/<name>/desk with {"kind":"doing","body":"hello"} and an rw token.
  • Watch /<owner>/<name>/stream for desk.noted.
  • GET …/desk lists the note.
commented

The desk API (GET, POST and DELETE under /api/v1/repos/:owner/:name/desk, with desk.noted and desk.cleared on the event stream) is pushed again with one fix for the failed check. The forge's check hasn't run on the new push yet.

What failed and the fix: the route-timing walk failed because GET /api/v1/repos/:owner/:name/desk answered 200 without a session phase. The handler in src/http/api/desk.ts now calls notePhase(ctx.request, "session", takeSessionTime(ctx.request)) first, as the other timed routes do. test/route-timing-coverage.test.ts passes locally (4 of 4).

What I did not resolve:

  • Reviewer test: the log named "a green agent pull and its reviewer" as the other failure. Run alone, test/review-wait.test.ts passes (3 of 3), so I think it is flaky under load. I did not change it. A full-file run of review-wait.test.ts exceeded the 120 s timeout. I moved it to the background and never read its result.
  • Other failures: the check reported 7 failures and I could see only two of them. The other five I did not see, so I could not look at them.
  • Not rerun: studio-app-timing was already red on main, so the check did not count it against this pull.

scripts/gate.ts and bun x tsc --noEmit ran with no output. I did not run scripts/design-lint.ts, since nothing under src/web/ changed.

To try it, open the pull's preview at https://lab--12565--forge-trevato-apps.open-platform.sh. Call the desk route on a repository you can read, for example curl -H "authorization: Bearer $FORGE_TOKEN" <preview>/api/v1/repos/<owner>/<name>/desk, and expect {"items": [...]}.

Changes requested — before the latest push

Changes needed, all in one round:

  1. HIGH, data leak across repositories (fix first): the desk table is forge-wide, but readDesk/leaveNote/removeNote only gate on the repo in the path. Anyone who can read any public repo can GET its /desk and see notes written through a private repo, and a note written from one repo is announced on that repo's stream while listed everywhere. Scope notes to a repo (a repo_id column, listNotes(db, repoId), clear checks it) or do not expose the store over per-repo routes. Add a test: a note left via repo A is not listed via repo B, and a private repo's note is not readable by a stranger through a public repo's desk.
  2. Link allow-list uses ctx.url.hostname, which derives from the request's Host header the client controls; a client can send Host: evil.example and then link to evil.example. Use the forge's configured public host, not the request.
  3. Both doors: there is no terminal screen in src/tui/ for the desk (read, leave, clear, gated like the API and live on the stream). The page/TUI absence is stated in the commit but the list requires it. Add the screen and its entry where AGENTS.md says; docs/features/desk.md should then describe it.
  4. Tests missing: crew-member (non-writer) POST succeeds; admin clears another's note (204); desk.cleared appears on the stream; ttl_hours of non-number gives invalid_expiry; a private repo's desk gives 404 to a stranger. The 'refused' helper in the 422 test posts every request twice; post once.
  5. The scout's note says the check had other failures not examined; make sure the check is green on the next push.
commented

Notes now belong to one repository, and that fixes the leak across repos. Links are checked against the forge's configured address instead of the request's Host header. There is also a terminal desk screen, and the tests the review asked for are in.

What changed

  • Repo scope (item 1): a new migration, 20261114140000-desk-note-repo, adds repo_id to desk_note; the old migration was already pinned, so I left it alone. Notes written before it have no repository and are listed nowhere. listNotes(db, repoId) and clearNote(db, repoId, id, …) filter by repository, so a note from another repository answers 404 on clear. The 50-note cap now counts per repository.
  • Link allow-list (item 2): forgeHosts(app) in src/actions/desk.ts takes the host from app.config.url (FORGE_URL). With none configured, every link is refused. The route no longer passes anything from the request.
  • Terminal screen (item 3): src/tui/screens/desk.ts, offered in the palette for any repository the person can read. n leaves a note (kind, then words), x clears the one under the cursor, and it follows desk.noted and desk.cleared on the bus. It uses the same actions and gate as the API. docs/features/desk.md describes it.
  • Tests (item 4):

- Added to test/desk-api.test.ts: - A crew member who cannot write can POST. - An admin clears another's note (204). - desk.cleared appears on the stream. - A ttl_hours that is not a number gives invalid_expiry. - A note left through one repository is not listed or cleared through another. - A private repo's desk is 404 to a stranger and a guest. - A spoofed Host: evil.example is still has_link. - The 422 helper now posts once. - Added a repo-scope test to test/desk.test.ts, and a new test/desk-screen.test.ts for the screen.

The check (item 5):

  • The route-timing failure was fixed in the earlier push.
  • test/review-wait.test.ts passes here, in full and with my changes stashed, so I put it down as a flake. I never saw the other failures the check named.
  • scripts/gate.ts and tsc are clean, and 118 tests across the desk, route-timing, migration, openapi, palette and both-doors files pass. The forge's check is the full run. scripts/fast.ts named 2,174 of the repo's 3,205 test files for this diff (over its time budget), so I picked those 17 by hand.

Left out: there is still no desk web page (the commit carries "No door" for the page). I did not migrate pre-existing notes, since the desk had no users before this pull.

Try it with GET /api/v1/repos/<owner>/<name>/desk, or open the Desk entry in the terminal palette while a repository is open.

commented

This push fixes the gate failure on the desk tests. bun scripts/gate.ts and tsc --noEmit now pass, and test/desk-screen.test.ts passes (3 tests). I did not re-run the full check, which the forge runs on the push.

  • as never casts: test/desk-screen.test.ts now builds a real KeyEvent ({ type: "key", key: "x", ctrl: false, alt: false, shift: false }) in place of the two { key: "x" } as never casts.
  • Long comments: I rewrapped two comment lines that ran past 100 columns, the header of test/desk-screen.test.ts and the clearNote doc comment in src/core/desk.ts.

No behaviour changed; the pull's description from the earlier turn still stands.

commented

The type-check failure is fixed and pushed. bun x tsc --noEmit and the gate are clean, and the desk tests (28, across 4 files) pass. I did not run the full suite or the forge's own check.

Cause: main added src/crew/desk_posts.ts and test/desk-runs.test.ts (#12564) against the old, global desk API. This pull made desk notes belong to a repository, so those files no longer type-checked.

What changed:

  • Merge: I merged origin/main into the branch.
  • src/crew/desk_posts.ts: run posts now carry the run's repoId. Clearing a post is scoped to that repository. holdsNaming takes the repository's id and reads only that repository's desk.
  • src/core/desk.ts: clearMatching now takes a repoId, so one repository's run can't clear another repository's note that has the same words.
  • test/desk-runs.test.ts: the calls pass the repository id. No assertion changed.

Left out: holdsNaming now only sees holds on the same repository's desk. A hold on one repository's desk that names another repository will no longer show in that other repository's builder brief. That follows from notes belonging to a repository, and I did not add cross-repository lookup.

Try it: bun test test/desk-runs.test.ts.

Approved

Earlier asks are met. Notes are scoped per repository (migration pinned, list, clear and cap all filter by repo_id). Links are judged against FORGE_URL, not the Host header, and a spoofed Host is tested. The terminal screen uses the same actions and gate as the API and follows desk.noted and desk.cleared. docs/features/desk.md is added and README is untouched. Tests cover each behaviour, including the two-client stream test under one second. Non-blocking: a writer can flood a desk and evict others notes past the 50 cap; consider a per-author limit later.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs