Let an agent select scopes from a connection's menu

[haruotsu]

Why

The google connection listed sheets, drive, and people among its hosts, but its scopes were gmail.readonly and calendar.readonly only — a token could travel to the Sheets API and be refused there every time. The catalog could not simply grow, though: authorizations are created per agent, but scopes were composed from the connection definition alone, so adding a write scope to the catalog would have put it on the consent screen — and into the token — of every agent holding the connection.

This PR splits that into two layers:

• the connection carries a reviewed menu (oauth.optional_scopes) next to its defaults (oauth.scopes),
• the agent selects from that menu in its own declaration, and the selection is built into that agent's authorization URI alone.

Invariants kept

1. A bare connections: [google] keeps meaning what it always did: the read-only gmail + calendar defaults.
2. Write scopes are opt-in only. A selection lands in the selecting agent's authorization and nowhere else.
3. An agent can select only from the menu (catalog, or its gete.yaml override). gete validate refuses anything else, and gete register refuses it again since it can run without validate. The same connection declared twice — the string and the mapping spelling name one connection, which uniqueItems cannot see — is refused by both for the same reason: only one entry's selection could reach the consent screen.
4. hosts remains the ceiling for where a token may be sent, whatever scopes it carries, and none of it reaches GCP: www.googleapis.com appears only scoped to the paths of the APIs served nowhere else.

What changed

Declaration — a connections entry may now be a mapping:

connections:
  - freee                       # the defaults only, as before
  - id: google                  # the defaults plus a selection from the menu
    scopes: [https://www.googleapis.com/auth/spreadsheets]

Hosts — an entry may scope itself to a path prefix, written host/path/. Drive v3 and Calendar v3 are served from www.googleapis.com and nowhere else — drive.googleapis.com and calendar-json.googleapis.com are service names that route no requests — and a bare www.googleapis.com would open storage, compute, and oauth2 as well. The google hosts therefore carry www.googleapis.com/calendar/, www.googleapis.com/drive/, and www.googleapis.com/upload/drive/ next to the per-API hostnames. A dot segment or an encoded separator in a request path is refused rather than resolved, because resolving would have to guess how many times the server decodes. This is also what makes the calendar.readonly default actually reachable.

Catalog (google.yaml) — the menu offers reads for Sheets, Drive, Docs, Slides, and contacts, and writes for Sheets, Docs, Slides, and calendar events. Drive write is drive.file only (files the agent creates or the user opens with it); Drive-wide write is deliberately absent. gmail.send is the heaviest entry — mail sent as the user is outward and cannot be recalled, which is what the old read-only comment feared — and is offered because it stays opt-in and its consent text says plainly that the agent sends as the user. gmail.modify and mail.google.com stay off the menu: rewriting or deleting the inbox is not needed to send. docs.googleapis.com and slides.googleapis.com join the hosts, and people.googleapis.com — until now a host no scope could use — gets contacts.readonly on the menu. All serving hosts were verified against the live endpoints.

Mechanism

• schema/agent.json: a connections entry is a string or {id, scopes}; an entry that selects nothing must be written as the string.
• schema/connection.json + OAuth: optional_scopes, same scope→consent-text shape as scopes; a hosts entry may be host/path/ (trailing slash required, so /api cannot quietly admit /api-and-more).
• connection/registry.py: allows() and allows_redirect() understand path-scoped host entries.
• register.py: the authorization URI carries defaults + that agent's selection; a selection outside the menu, a selection on a connection with a verbatim authorization_query, or a connection declared twice in both spellings is refused rather than silently dropped.
• validate.py: selection ⊆ menu (the problem names what the menu offers), and a connection declared in both spellings is reported — even when the connection itself is unknown to the registry.
• connection/checks.py: a menu entry repeated in the defaults, or a menu next to a verbatim authorization_query, is a definition problem.
• gete connections <id> prints the menu next to the defaults, since the OAuth client has to be prepared for everything an agent may select.
• Conformance tests pin the google invariants: read-only defaults, the exact menu, no blanket Drive write, no inbox mutation, consent text for gmail.send that does not soften what it grants, www.googleapis.com never bare, and storage, compute, and oauth2 refused by allows().

Not included

The optional warning for agents that select a write scope while declaring no effect: write tool was left out: validate currently has no warning channel, only problems, and a hard error there would be wrong. Worth revisiting if a warning level ever exists.