---
name: add-oauth-integration
description: Add a new Rome-managed OAuth integration for a third-party service so a user can delegate access by clicking Connect, and Rome can act on the service with the delegated token (the GitHub/Slack model — brokered by Pantheon, NOT Composio). Use when asked to "add an integration / connector for <service>", "let users connect their <service>", or "delegate <service> access to Rome". NOT for Composio-managed toolkits (those are a declarative catalog entry only — see rome_apps/connector), and NOT for inbound real-time events (that needs a central webhook broker; this skill is OAuth/API-only). Worked example to diff against: the Slack connector (PR #1225) and the GitHub connector already in-tree.
---

# Add an OAuth integration

Goal end-state: a user opens **Settings → Connections**, clicks **Connect <Service>**, approves on the provider's consent screen, and Rome ends up holding a delegated token it can use to call the provider's API on the user's behalf. This mirrors the existing **GitHub** and **Slack** integrations — "Rome-managed" providers brokered by Rome's own Pantheon OAuth, with **zero Composio involvement**.

Work the five phases in order. Don't skip Phase 1 (scoping) — the answers decide how much of Phases 4–5 you build.

The two reference implementations to read and mirror throughout:
- **GitHub** — the original Rome-managed provider (single token, has a CLI consumer).
- **Slack** — the most recent, closest template for a fresh service (two tokens, pure API consumer). PR #1225.

---

## Phase 1 — Scope the integration (convey the goal, lock the decisions)

Two things are fixed for this skill and need no confirmation: the integration is **OAuth-only** (act on the service via its API — real-time inbound events need a central webhook broker and are out of scope) and **Rome-managed** (our own Pantheon OAuth, direct API, with **no Composio connection** — never mix the two). State the goal back to the user in one sentence, then resolve the two gates that actually change the build **with the human**:

1. **How many tokens?** Some providers return one access token; some return more, each for different methods. Find out — it drives token storage and the proxy's token selection.
2. **Token rotation?** Default **off**. Rotation is often irreversible once enabled and adds refresh machinery; only opt in deliberately.

Capture the answers — they are the spec for everything below.

---

## Phase 2 — Learn the provider's delegation mechanism (read the docs)

Read the provider's OAuth documentation and produce a short "build guide" (a scratch doc is fine). Extract exactly these, because the adapter in Phase 4 needs every one:

- **Authorization endpoint** + params: scope format (space vs comma), `state`, `redirect_uri`, and **whether it uses PKCE** (many confidential-client flows don't — confirm, don't assume).
- **Token exchange**: endpoint, request encoding, and the **response shape** — where the access token is, refresh token, expiry, and any *extra* tokens the response carries beyond the primary one.
- **Connecting account's identity** — resolve two things for the consenting human: an opaque, stable **`subject`** that keys and dedups the connection (the machine identity), and a **human-readable handle** so a person can recognize which account is wired up (it's the label in Settings → Connections). The handle can come from an **OIDC `email` / `email_verified` claim** or a **provider-specific profile API** — find whichever the provider exposes (Google has the OIDC claim; GitHub uses `/user/emails`; Slack uses `users.info`). **Rome broker invariant:** the callback (`packages/pantheon/src/app/oauth/[provider]/callback/route.ts`) currently requires that handle to be a **verified email** specifically and rejects the handoff without one, so the adapter must *produce* `{email, emailVerified}` by whatever means fits — real claim, provider API, or a justified synthesis (Slack treats any returned email as verified, since it only admits verified members). **If the provider exposes no email at all** (handle-only services), that's a genuine blocker to raise, not a detail — the fix is a broker change (key on `subject` alone), not something the adapter can paper over. **Trap:** if the grant mints a service/bot/app identity distinct from the human who clicked Connect, the "whoami" call on the primary token returns the *service* identity (no email) — resolve the human instead (read the installing user's id from the token response held in `bundle.raw`, then call the user-profile endpoint) and use the human for `subject` too.
- **Scopes** needed for the capabilities you want, and which are sensitive.
- **Quirks**: e.g. an API that signals errors in the response body rather than the HTTP status; rate-limit headers; a required `https` redirect.

---

## Phase 3 — Tell the human what to register (and where it plugs in)

You can't register the provider app for them (their account, their consent). Produce a precise checklist — and, if the provider's console supports app manifests (many do), a manifest file the human imports; otherwise step-by-step console instructions. The human needs:

- **Create the app** in the provider's developer console.
- **Redirect URL** — a single, central Pantheon callback: `https://<PANTHEON_DOMAIN>/oauth/<provider>/callback`. It is **not** per-tenant and has **no wildcard** — Pantheon brokers all tenants through one origin (`getPantheonOrigin` + `/oauth/<provider>/callback` in `packages/pantheon/src/app/start/route.ts`). Register the prod origin; for local testing add the tunnel origin too (Phase 5).
- **Scopes** from Phase 2.
- **Client ID + Secret** → set in Pantheon env as `<PROVIDER>_OAUTH_CLIENT_ID` / `<PROVIDER>_OAUTH_CLIENT_SECRET` (read automatically by `packages/pantheon/src/lib/oauth/providers.ts`).
- **Public distribution** toggle if users beyond the dev workspace will install it.

---

## Phase 4 — Build it

Two halves: (a) obtain consent + exchange the token (the broker, in Pantheon + core), and (b) consume the token for API calls (the connector). Mirror GitHub/Slack file-for-file.

### 4a. Obtain consent & exchange the token

- **Pantheon adapter** — `packages/pantheon/src/lib/oauth/<provider>.ts` implementing `OAuthProviderAdapter` (`createAuthorizationUrl`, `exchangeCode`, `fetchProfile`). Copy `oauth/slack.ts` (two-token, no PKCE) or `oauth/google.ts` (PKCE, refresh) as the closer match. Map the primary token to `bundle.accessToken`; stash the full provider response (any extra tokens, team/workspace id) in `bundle.raw` — it survives the broker→instance handoff. `fetchProfile` must return a verified email.
- **Register the provider**: add `"<provider>"` to `OAUTH_PROVIDERS` in `packages/pantheon/src/lib/oauth-providers.ts`, to `PROVIDER_ADAPTERS` in `packages/pantheon/src/lib/oauth/providers.ts`, and document the env vars in `packages/pantheon/.env.example`.
- **Core provider list**: add `"<provider>"` + a descriptor to `packages/core/src/lib/oauth-providers.ts`. The broker, token storage, `/api/integrations`, connect/disconnect, and the per-tenant handoff are all provider-agnostic and light up automatically.
- **Deliver the token to the runtime** (only if the connector/agent needs it): `packages/core/src/lib/<provider>-shell-integration.ts` writes the token(s) to `/run/rome/<provider>-oauth-token` on connect and clears on disconnect (single string like GitHub, or JSON for multiple tokens like Slack). Wire `sync…ForProvider` into `packages/core/src/api/routes/oauth.ts` (redeem) and `clear…ForProvider` into `packages/core/src/api/routes/integrations.ts` (disconnect). Reference `slack-shell-integration.ts` / `github-shell-integration.ts`.

### 4b. Consume the token for API calls

- **Mark it Rome-managed**: add `"<provider>"` to `ROME_MANAGED_TOOLKITS` in `rome_apps/connector/src/shared.ts`, set `romeManaged: true` in `rome_apps/connector/src/web/lib/connections.ts`, and ensure the toolkit exists in the SDK `SUPPORTED_CONNECTORS` (`packages/app-runtime-sdk`) with a `TOOLKIT_API_HOSTS` entry (`shared.ts`).
- **Direct proxy**: `rome_apps/connector/src/api/<provider>-proxy.ts` reads the token file and exposes a `<provider>ProxyCall` (auth header, default API host). Add a branch in `rome_apps/connector/src/actions/connector-proxy/index.ts` that, for this toolkit, reads the token and calls the proxy — bypassing Composio. For multi-token services, select the token by endpoint (Slack: `search.*` → user token). Reference `slack-proxy.ts` / `github-proxy.ts`.
- **Connect card**: `rome_apps/connector/src/web/<provider>-connect-card.tsx` (drives core's `/api/integrations` OAuth inline), side-effect-imported in `rome_apps/connector/src/web/App.tsx`, listed under `components:` in `rome_apps/connector/app.yaml`, and rendered from a branch in `rome_apps/connector/src/actions/connector-connect/index.ts`. The card is currently copy-pasted per provider — **if you're adding the 3rd one, generalize it** into one `<RomeManagedConnectCard provider>` instead.
- `connector_tool_execute` already short-circuits any Rome-managed toolkit to a "use connector_proxy" hint — no change needed.

### File checklist (mirror of the Slack change set)

```
packages/pantheon/src/lib/oauth/<provider>.ts            NEW  adapter
packages/pantheon/src/lib/oauth-providers.ts             +    OAUTH_PROVIDERS
packages/pantheon/src/lib/oauth/providers.ts             +    adapter map
packages/pantheon/.env.example                           +    <PROVIDER>_OAUTH_CLIENT_ID/SECRET
packages/core/src/lib/oauth-providers.ts                 +    provider + descriptor
packages/core/src/lib/<provider>-shell-integration.ts    NEW  token-file write/clear (if runtime needs the token)
packages/core/src/api/routes/oauth.ts                    +    sync…ForProvider on redeem
packages/core/src/api/routes/integrations.ts             +    clear…ForProvider on disconnect
rome_apps/connector/src/shared.ts                        +    ROME_MANAGED_TOOLKITS (+ TOOLKIT_API_HOSTS if missing)
rome_apps/connector/src/api/<provider>-proxy.ts          NEW  token read + proxy call
rome_apps/connector/src/actions/connector-proxy/index.ts +    provider branch
rome_apps/connector/src/actions/connector-connect/index.ts +  provider branch → connect card
rome_apps/connector/src/web/<provider>-connect-card.tsx  NEW  inline connect card
rome_apps/connector/src/web/App.tsx                      +    import the card
rome_apps/connector/src/web/lib/connections.ts           +    romeManaged: true
rome_apps/connector/app.yaml                             +    component + version bump
```

---

## Phase 5 — Validate end-to-end

Run the **validate-oauth-integration** skill — it owns the full recipe (static + unit → a token-only smoke that proves Rome can *use* a token → the real consent round-trip that proves Rome can *obtain* one) and the local-only blockers. Report honestly which layers actually ran; the real round-trip needs a registered app, creds, and a human at the consent screen, so it's often where the human takes over.

One build-coupled heads-up before you hand off: adding the provider trips drift guards — the enabled-provider lists in `packages/core/src/lib/oauth-providers.test.ts` and the Rome-managed lists in `rome_apps/connector/src/web/lib/connections.test.ts`. Update both, and switch any test that used the service as a stand-in *Composio* toolkit to a still-Composio one (e.g. `notion`).

---

## Gotchas (these generalize to every provider — platform invariants + universal OAuth facts)

Service-specific quirks are deliberately NOT listed here — Phase 2 tells you to hunt for them per provider, and Phase 4 says where they land. Two we hit with Slack are examples of that category, not standing gotchas: an API that signals errors in the body rather than the HTTP status (Slack's `ok:false` at 200), and a provider that returns more than one token (stash extras in `bundle.raw`). These below are the ones that bite on *every* integration:

- **The verified-email gate** in the Pantheon callback silently fails the handoff if `fetchProfile` returns no verified email. This is a Rome broker invariant, not an OAuth2/OIDC guarantee — most providers can satisfy it (OIDC claim, provider API, or justified synthesis), but a handle-only provider with no email can't without a broker change. Confirm the provider has a usable email *before* building (Phase 2).
- **Resolve the *human's* email, not the app's** — the single most likely bug (it broke Slack's whole round-trip): when the grant produces a service/bot identity alongside the human, calling the provider's "whoami" on the primary token returns the bot, whose empty email trips the gate on *every* connect. Read the consenting human's profile instead, and distrust comments that *say* installer while the code reads the app identity (contract > impl).
- **A scope is a multi-surface contract, not just an adapter constant** — adding a scope to the adapter's list grants nothing on its own; the *registered provider app* (and its manifest) must also offer it, or the consent screen never asks for it. Change all three in one diff: the adapter scope list, the manifest artifact, and the live app in the provider console (the human-only step). Auditing the granted token (`auth.test`-equivalent shows the scopes it actually has) is the only proof the contract closed.
- **One central redirect URL**, not per-tenant — Pantheon routes all tenants through `https://<PANTHEON_DOMAIN>/oauth/<provider>/callback`. (Rome architecture.)
- **Redirect-scheme strictness varies and breaks local testing** — providers differ on whether they allow `http`/`localhost` redirects. The strict ones require `https`, which is why local Layer-2 testing fronts Pantheon with a tunnel (`ROME_DEV_PANTHEON_PUBLIC_ORIGIN`). Check each provider's policy before assuming the dev `http` origin works.
- **Don't assume PKCE** — it varies per provider (Google uses `code_challenge`, others don't). Copy the closest adapter, but verify rather than inherit it.
- **Generalize at the 3rd provider** — the connect card and the per-provider proxy/connect branches are copy-paste today; fold them into one generic Rome-managed path instead of a fourth copy. (Codebase, not service.)