feat(http-api): request-id'd /notes/~/v1 + OpenAPI/AsyncAPI specs + X-Api-Key auth + every flow through one dispatch

[arthyn]

Summary

Replaces the Eyre-channel poke surface with a request/response HTTP API at /notes/~/v1. Every action — whether it lands locally or hops cross-ship — carries a client-generated requestId (@uv); the agent holds the POST open until the host's terminal response-update is forwarded back, the host nacks, or a 20s timeout fires. Modeled on the venter-like pattern from tloncorp/tlon-apps#5334, specialized for notes' single-agent dual-mode host/subscriber shape.

The bigger architectural shift: there's now one dispatch path through the agent (dispatch-v1-action). Local actions, cross-ship actions, the FE, MCP clients, dojo pokes, and the legacy %notes-action mark all funnel through it.

What's in the branch (7 commits, oldest→newest)

#	Commit	What it does
1	b483497	Types + state-11 + cycle skeleton. New ++ v1 core in sur/notes.hoon (action / command / response / response-update / response-body / response-update-body / incoming-request / poke-status / action-error). state-11 adds requests=(map request-id incoming-request). New marks mar/notes/{action-1,command-1,response-1,response-update-1}.hoon. Agent: HTTP POST + GET routes, per-request behn timeout, cleanup timer, full subscriber↔host lifecycle (no-action-v1 / se-poke-v1 / no-agent-req-watch / no-agent-req-poke). 4 new tests + 55 existing pass.
2	a419c4b	FE migration. pokeAction switched from Eyre-channel PUT-then-watch-poke-ack to fetch('POST /notes/~/v1'). All ~40 wrapper call sites (pokeNotebook, pokeNoteAction, etc.) unchanged. pendingPokes infra removed — HTTP holds the request open and returns the typed terminal body inline.
3	22c1acf	OpenAPI 3.1 spec. docs/openapi.yaml covers the two endpoints, the discriminated Action / ResponseBody unions, the full r-notes / u-notebook tree returned in %ok responses, ActionError enum, eyre-cookie security scheme. Validates clean under @redocly/cli.
4	9e7201c	AsyncAPI 3.0 spec. docs/asyncapi.yaml documents the three SSE subscription channels (per-notebook stream, inbox events, per-request response stream) over Eyre's PUT-to-subscribe + EventSource transport. Plus docs/asyncapi.html, a single-file viewer.
5	8b9bf5e	Serve openapi.json from the agent. desk/lib/notes-openapi.hoon embeds the spec; scripts/build-notes-openapi.sh regenerates from docs/openapi.yaml via js-yaml. Public route so MCP proxies can fetch the spec without inventing an auth scheme. JSON because %mcp's converter parses with de:json:html and doesn't accept YAML.
6	12d67a3	X-Api-Key auth. state-12 adds api-key=(unit @t) minted on init / after migration. New a-notes variants %regenerate-api-key / %clear-api-key. +request-authorized accepts either eyre-validated cookie OR matching X-Api-Key header. +handle-v1-post bypasses the +poke %notes-action-1 arm's src.bowl guard when api-key matches — calls +dispatch-v1-action directly. Scry /x/v0/api-key for the local user to inspect/copy. 5 new tests.
7	f2372ce	All cross-ship flows through request/response. Previously the membership-wire pokes (handle-send-invite, join-remote, leave-remote) were fire-and-forget with the legacy %notes-command mark. Now they all use +send-v1-request (watch + poke notes-command-1 + behn-wait) and finalize asynchronously when the host's response-update arrives. +poke %notes-command-1 %notify-invite emits a %no-change response-update. no-agent-req-watch kicks off no-start-watch on first successful cross-ship response so freshly-joined subscribers get the broadcast stream. Watch handler relaxed to allow invitee-hosted request paths keyed by inviter's flag. Legacy %notes-command arm removed (pre-Phase-2 sub ships unsupported, per design). Legacy %notes-action arm routes through dispatch-v1-action with a (mix eny.bowl rid-counter)-synthesized rid; state-13 adds rid-counter so test-agent (which doesn't advance bowl.eny) doesn't collide on the per-request watch wire.

Test surface

• 65 unit tests pass (mcp__sidwyn__run-tests on /tests/app/notes)
  • 11 new across the 7 commits: 4 v1 lifecycle, 5 api-key, 2 from existing tests rewritten to use the v1 cross-ship mark
• 12 e2e tests pass (npm run test:e2e) — including the cross-ship invite / accept / leave / edit propagation specs
• Manual smoke — verified end-to-end via curl + via MCP-proxy proxied through Claude Code (tloncorp/mcp upstream pointed at /notes/openapi.json; called submitAction with a 4-deep discriminated body)

Things deliberately out of scope

• Typed %conflict error. se-update-note's expected-revision mismatch still crashes the poke, surfacing as %error %unknown on the response-update path rather than %error %conflict. Single arm fix; left for later so the FE's conflict-banner refactor can land alongside it.
• %ok payloads for top-level actions. %create-notebook, %accept-invite, etc. finalize with %no-change. FE relies on the broadcast SSE stream for state sync.
• Pre-Phase-2 cross-ship compat. Dropping %notes-command means another ship still running pre-Phase-2 notes can't poke this version — an explicit trade-off per option B in the design discussion.

Related upstream

tloncorp/mcp#3 — patches mcp-proxy.hoon's OpenAPI converter to actually resolve $refs into the generated MCP tool's inputSchema. Required for notes_submitAction to expose its Action discriminator union to LLM clients. Without it the inputSchema is empty.

🤖 Generated with Claude Code