[design] Stage 2: register the generic connector OAuth redirect for Drive/WorkDrive/Gmail and retire the dedicated flows (Stage 1 — the registry declaration — has shipped)

[serge-ivo]

The gap

lib/connectors/registry.ts is the platform's answer to "what can an agent reach, and who says so". A
connector is declared once and everything derives from that entry: the tool catalog,
connectorClient auth dispatch, capabilities.tools gating, the write-consent gate (#90), and all
three surfaces (agent runtime / /v1/instances/:id/tools / MCP).

Eleven connectors live there: github, meta, terminal, tmux, browser, repo-local,
supervision, http, mcp, google_sheets, web-search.

Google Drive, Zoho WorkDrive and Gmail are not among them. They are bespoke routes
(routes/drive.ts, routes/workdrive.ts, routes/email.ts), with hand-written console blocks in
SettingsTab.tsx:967-1075.

Because they are not declared, there is nothing for a capability to gate against. So they render on
every instance, for every agent, regardless of what that agent can do. On this account that is 26
instances — including Repo Chat, whose entire job is answering questions about code, and the four
terminal Operators, none of which has any file-connector tool.

Why this is a half-finished migration, not a refactor

Three pieces of the destination already exist and are already tested:

1. The grant model is built and unused. Connector.grantModel (lib/connectors/types.ts:129)
takes "user" | "instance-resource", the second documented as "each tool call must target a
resource granted to the instance" — which is precisely Drive/WorkDrive's folder grant.
connectors/client.ts:90-102 mints a token for such a connector only after
requireConnectorGrant passes, fail-closed with a 403, and client.test.ts:143,152 covers both
directions.

No connector in CONNECTORS declares grantModel: "instance-resource". The feature was built for
these three and they never arrived.

2. They already share the storage. routes/drive.ts:27 and routes/workdrive.ts:16 both import
lib/connector-grants.js — the same connector_grants table the registry model reads. Its own
header comment names the intended consumers: "Known values: google_drive | zoho_workdrive | (any
connector id with grantModel:"instance-resource")".

3. The OAuth path is proven on the same credential. google_sheets (#89/#143/#147) is a
declarative manifest driven by the generic OAuth2 handler, connecting at
/v1/connectors/google_sheets/oauth/start — using the same GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET
as Drive, with its refresh token in its own vault slot. Its source comment says so explicitly:
"separate from Drive". Sheets took the new road; Drive stayed on the old one.

So the destination is not hypothetical. It is a manifest per connector plus handlers for the parts
that are genuinely custom (Drive's file listing, WorkDrive's DC-specific bases, Gmail's
find_confirmation_link permission gate).

What it buys

• Each connector's console block appears only when the agent declares a tool for it. The clutter
  in [bug] An unconfigured connector renders a red error on every agent's Settings tab — Zoho WorkDrive has never been configured #353 and [design] Account-level connections are rendered inside one agent's Settings — disconnecting Gmail there disconnects it everywhere #355 stops being UI to prune and becomes a derived property.
• They join the tool-policy list, so "what can this agent do" stays the one honest answer.
• Drive/WorkDrive writes become write-consentable ([connectors] Connector consent + write-scope safety + admin visibility #90) like every other write connector.
• One fewer parallel system. connectors/client.ts:34 currently carries the tell:
  "the hand-written google_drive connector keeps its hardcoded creds."

Sequencing

This supersedes the symptom fixes rather than competing with them — but those are small and land
today, so do them first and let this delete the code they touch.

Gmail is the delicate one: find_confirmation_link is permission-gated on
AgentState.permissions.email and reads the owner's inbox. Its gate must survive the move as a
declared scope, not be softened into a plain write-consent checkbox.

Related: #146 (connector manifests), #147 (generic connector OAuth), #86 (registry), #90
(write-consent).

[serge-ivo]

Correction — the gating mechanism in "What it buys" does not hold

Checked after filing. The first bullet claimed each connector's console block would appear "only when
the agent declares a tool for it". That is wrong for all three connectors, for two different reasons.

Drive and WorkDrive have no agent-callable tools at all. routes/drive.ts is OAuth start/status/
callback, grants CRUD, GET /files, and POST /instances/:id/import. routes/workdrive.ts is the
same shape. Nothing in agent-do-tools.ts or the registry exposes a drive_* tool. They are
ingestion sources — user-driven import plus sync triggers — not things an agent calls mid-turn. So
there is no tool to declare, and capabilities.tools cannot gate them.

Gmail's tool is deliberately not declarable. find_confirmation_link exists
(lib/storage-tools.ts:206) but is intentionally excluded from CREATOR_SELECTABLE_TOOLS —
agent-do-tools.ts:126 says so, and it is granted at runtime by the permission flag instead
(:225, agent-think.ts:638). Gating its console block on a declared tool would invert a security
decision that is currently correct.

What this changes

The diagnosis stands. The remedy was mis-assigned. Everything in the body above about the two
parallel systems is still true and still verifiable: grantModel:"instance-resource" is built,
tested and unused; connector_grants is already shared; google_sheets runs the same Google
credential through the new road while Drive stays on the old one; client.ts:34 still hardcodes
Drive's creds.

But this issue is not the fix for the settings clutter it was filed alongside. #355 is — once
connect/disconnect moves to the account page, an instance only shows a grant box for a connector the
account has actually connected, and on this deployment that removes both Drive (connected:false)
and WorkDrive (configured:false) from all 26 instances immediately, with no registry work.

What this issue is still needed for is the steady state. Connect Drive once at account level and
#355 alone puts a Drive grant box back on all 26 instances — including the four terminal Operators,
which will never read a document. Suppressing that needs a real capability axis, and that axis is
what the registry provides.

Re-scope

Folding these in requires deciding what the agent-facing surface actually is, which the original body
skipped:

1. Drive / WorkDrive — either give them genuine read tools (drive_list_files, drive_read_file)
   so grantModel:"instance-resource" gates them the way it was designed to, or keep them
   user-driven and gate the UI on a different declared axis (e.g. "this agent ingests documents").
   The first is more work and more honest; it is also a scope expansion that was not stated here.
2. Gmail — moving it in must preserve permissions.email as the gate. Its shape is a
   permission-gated tool, not a creator-selectable one, and the registry has no such category today.

Until (1) is decided this is architectural debt, not a queued fix. Sequence: #353 → #354 → #355 →
this, not the order the four were filed in.

[serge-ivo]

One more open question for whoever triages: this may belong under the #68 focus bet as deferred: no demand. The debt is real and the evidence above stands, but nothing user-visible depends on it once #353 and #355 land — those remove the symptom without touching the registry. Leaving the label off deliberately rather than applying it unilaterally; it is a priority call, not a technical one.

[serge-ivo]

Assessment: fold them in — but the migration is smaller than the risk suggests, and the destination is smaller than the ticket claims. Three things here should not be built.

I ran two probes against the code rather than reasoning from the design docs. Both changed the answer.

Tested: the data migration is empty

The framing everyone (including me, before checking) brings to this is "moving live grants is a data risk". It isn't, because the storage is not merely shared — it is identical, keyed by the same value.

• routes/drive.ts:149 and routes/workdrive.ts:134 store the refresh token with saveConnectorRefreshToken(env, {userId, provider: "google_drive" | "zoho_workdrive", …}). routes/email.ts:156 does the same INSERT inline under provider gmail.
• saveConnectorRefreshToken writes user_api_keys (user_id, provider, …), envelope-encrypted (lib/connector-oauth.ts:120). There is no connector_tokens table; [design] Account-level connections are rendered inside one agent's Settings — disconnecting Gmail there disconnects it everywhere #355's scope table names one that doesn't exist.
• connectors/client.ts:125 mints a bearer for an auth:"oauth" registry connector by calling readConnectorRefreshToken(env, uid, connector.id, connector.label) — same function, same table, provider = the connector id.
• Grants are already in connector_grants under the same ids (lib/connector-grants.ts:6 documents them by name).

So: add google_drive to CONNECTORS with auth:"oauth" and connectorClient finds every already-connected user's token on the first call. No backfill, no rename, no dual-write window, nothing to roll back. The ids already match because the hand-written routes were written against the shared helper.

The one non-empty cost is external, and it is a deployment step rather than a data step: the generic flow's callback is /v1/connectors/:id/oauth/callback, so new connects need that redirect URI registered on the Google/Zoho OAuth client — the same "inert until the redirect is registered" caveat google_sheets already carries. Existing connections keep working throughout, because the token row is found by provider id and nothing about it changes.

Tested: a manifest cannot hold these three

The body's case rests on "google_sheets took the new road; Drive stayed on the old one". I compiled and validated it:

sanitizeConnectorManifest(GOOGLE_SHEETS_MANIFEST)               =>  REJECTED
compileConnector({…oauth2 manifest…}).connector.grantModel      =>  "user"

Two independent blockers, both in lib/connectors/manifest.ts:

1. grantModel is not a manifest field. ConnectorManifest (:69) has no such key and compileConnector hardcodes grantModel: "user" (:184). The instance-resource model — the exact thing the body correctly identifies as built-and-unused for these connectors — cannot be expressed in a manifest at all. Only a hand-written Connector object in CONNECTORS can express it.
2. The manifest validator only accepts pure-declarative HTTP tools. sanitizeConnectorManifest drops any tool without a request (url/path), then rejects a manifest with zero tools. Both existing "manifest" connectors — web-search and google_sheets — define their tools with the handler escape hatch and no request, so both would be rejected by the repo's own manifest validator; they exist only because first-party manifests go through compileConnector, which does not validate. (ID_RE also forbids underscores, so google_sheets/google_drive/zoho_workdrive fail on the id alone.)

Drive's file listing, MIME export, folder-descendant check and WorkDrive's DC-specific bases are exactly the custom-handler shape the validator rejects. So this work should be costed as "a hand-written registry entry with handlers calling the existing lib/drive.ts", not as "a reviewed JSON manifest, not a .ts + deploy" (#146's promise). That promise is real for a plain REST API and is not available here.

What the fold actually buys — and what it doesn't

Honest accounting, because two of the body's four bullets don't survive contact:

Claimed benefit	Holds?
Console block appears only when the agent declares a tool	❌ already withdrawn in the correction above, and see "would not build"
They join the tool-policy list — one honest answer to "what can this agent do"	⚠️ only if they get tools; with tools: [] they join the connection list, not the tool list
Drive/WorkDrive writes become write-consentable (#90)	❌ there are no writes. DRIVE_SCOPE = ".../auth/drive.readonly" (lib/drive.ts:4). Nothing to consent to
One fewer parallel system	✅ and it is worth more than the body says

That last one is the real case, and it is bigger than the two files named. Five places independently know "google_drive and zoho_workdrive are the file connectors, and here is where their routes live":

• routes/drive.ts + routes/workdrive.ts (the flows)
• tabs/SettingsTab.tsx:931-1075 (three hand-written blocks)
• workers/mcp/src/instance-tools/connectors.ts:21 — a hardcoded PROVIDERS = {google_drive: {base:"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/v1/drive"}, zoho_workdrive: {base:"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/v1/workdrive"}} map, plus a z.enum of the same two
• lib/triggers.ts:669,721 — the sync_connector branch, one hardcoded readConnectorRefreshToken(…, "google_drive", …) per provider
• lib/connectors/client.ts:34 — the comment admitting the exception

A sixth connector of this kind means editing five files and a Zod enum. That is the cost the registry removes, and it is a maintenance argument rather than a safety one — which brings me to:

The fold adds no safety property. Drive/WorkDrive already fail closed: requireConnectorGrant guards the routes, and the sync path re-checks descent from the granted root (triggers.ts:674) so the walk cannot leave the grant. Gmail's find_confirmation_link is already gated on AgentState.permissions.email and deliberately excluded from CREATOR_SELECTABLE_TOOLS. Nothing here is currently reachable by an agent that shouldn't reach it. The problem is comprehension and duplication, not exposure, and it should be justified on those terms rather than by borrowing #90's language.

What I would not build

1. Inventing drive_list_files / drive_read_file so capabilities.tools has something to gate. This is option (1) in the correction above, described there as "more work and more honest". I think it is more work and less honest: a gate whose precondition is inventing the thing it gates is designed backwards. Concretely it costs —

• a second content path into the agent that bypasses the KB and the vector store, so the same document reaches the model chunked-and-cited via RAG or raw-and-unbounded via a tool, depending which it picks;
• a second place the folder grant must be enforced, per call, for a connector whose current security story is "one grant check at the top of a walk that cannot leave the root";
• a live-read capability nobody asked for. Drive is an ingestion source: the user imports, or a sync_connector trigger does, and the content then lives in the instance's own store where every other agent surface can already see it.

If the goal is "the four terminal Operators shouldn't show a Drive card", gate on an axis that already exists — declared surfaces, or a boolean capability like ingests_documents — rather than manufacturing a tool to be the gate. capabilities is a registry of what an agent is; it does not have to be spelled as tools.

2. Renaming the ids to satisfy ID_RE. google_drive → google-drive is the only change in this whole area that would touch live rows (user_api_keys.provider, connector_grants.provider, the MCP enum, existing triggers' stored config). It buys eligibility for a validator these connectors cannot pass anyway. Leave the ids alone; if the underscore ban is wanted, it can stay a rule about creator-supplied manifests, which is all it currently governs.

3. Moving Gmail's tool in the same pass. Its shape — permission-gated, non-creator-selectable, granted at runtime from AgentState.permissions — has no category in the registry today. scopes is {read, write} and grantModel is user | instance-resource; neither expresses "granted by an owner-set permission flag, never declarable by a creator". Folding it in means either inventing a third grantModel or softening the gate, and the second is a security regression dressed as a refactor. Gmail's account-level connect/disconnect should move to Preferences with the others (#355); its tool stays exactly where it is until someone deliberately designs a permission-gated grant model.

Recommended shape and sequence

Stage 1 — declare, don't migrate (small, no behaviour change, do it first). Add google_drive, zoho_workdrive and gmail to CONNECTORS with tools: [], auth: "oauth", and grantModel: "instance-resource" for the first two. Empty tools leaves connectorTools() unchanged, so no agent gains anything. Add the one route the console needs and does not have: GET /v1/connectors returning {id, label, auth, connected, configured} — no such endpoint exists today (routes/connectors.ts has only /:id/oauth/{start,callback,status}) and the console never calls /v1/connectors/* at all.

Stage 1 should land before #355, not after. The correction on #355 is right that its Connections section is new work rather than a transplant — which means building it first, by hand, writes a third hardcoded copy of these three blocks that Stage 1 then deletes. With GET /v1/connectors in place, #355's section is a loop over the registry, and it arrives already correct for google_sheets and any future OAuth connector — both of which the hand-written version would silently omit.

Stage 2 — retire the duplicated flows (worth it). Point Drive/WorkDrive connect at /v1/connectors/:id/oauth/{start,callback} and delete their copies. The generic route is already equivalent — same signConnectorState, same bind nonce, same access_type=offline&prompt=consent, same save. Two small gaps to close first: it doesn't request openid email or pass accountLabel, so the console would lose the "connected (name@example.com)" line, and it has no per-connector "is this deployment configured" answer of the shape /v1/drive/status returns. Keep the Drive-specific file routes (list, import, grants) — those are the genuinely custom part and there is no reason to make them generic.

Stage 3 — never, or not until someone asks: agent-callable Drive tools, a manifest form, id renames.

Sequence, amending the one above: #353 → #354 → #352 Stage 1 → #355 → #352 Stage 2.

[serge-ivo]

Stage 1 landed — b9e224a on main. The two probes held; the reach was one place bigger than the count.

Both findings survived implementation exactly as written, so this is a report rather than a correction.

The data migration was empty, as measured. google_drive, zoho_workdrive and gmail are now entries in CONNECTORS (lib/connectors/connected-accounts.ts). No backfill, no rename, no dual-write window, nothing to roll back — the ids already match because the hand-written routes were written against saveConnectorRefreshToken, and connectorClient looks up the same user_api_keys(user_id, provider) row.

A manifest could not hold them, so none was attempted. These are hand-written Connector objects with grantModel: "instance-resource" on the first two — the field a manifest has no key for.

The three things not to build, not built

• No drive_* tools. tools: [] on all three, and a test asserts connectorTools() contains nothing from them, so connectorTools() is byte-identical and no agent gained anything.
• No id renames. The ids in user_api_keys.provider, instance_connector_grants.provider, the MCP enum and stored trigger configs are untouched.
• Gmail's tool was not moved. Only its account-level connection is declared; find_confirmation_link is still granted at runtime by AgentState.permissions.email and still excluded from CREATOR_SELECTABLE_TOOLS.

What landed

GET /v1/connectors — the catalog resolved for the caller: {id, label, auth, scopes, grantModel, unattended, tools, configured, connected, account, connectedAt}. configured vs connected keeps #353's distinction (this deployment cannot / you have not) in the payload rather than leaving each consumer to re-derive it, and connected is null — not false — for a connector that holds no credential, so a relay connector does not read as a gap. One indexed read over user_api_keys for the whole catalog.

client.ts:34's hardcoded google_drive branch is deleted, not left as a fallback. Drive resolves its OAuth config from its own declaration now, like everything else. That is one of the five copies actually gone rather than merely made derivable. The test that pinned the special case was rewritten to assert the declaration produces the same result; client.test.ts's oauth_conn fixture had to gain a real oauth block, which is the honest consequence — a fixture that declares no credentials should resolve to none.

One thing the design note did not anticipate

DELETE /v1/connectors/:id/oauth had to grow the #357 cascade in the same commit. Declaring Drive/WorkDrive makes the generic disconnect route a second path to disconnect them — and it dropped only the token row, which is exactly the bug #357 had just closed on the dedicated routes. Left alone, Stage 1 would have silently re-opened it through another door. It now calls revokeUserConnectorGrants for instance-resource connectors and reports revoked; /oauth/status returns reach for the same connectors, the same contract /v1/drive/status carries.

This is the general form of the risk in folding a hand-written flow into a generic one, and it is worth carrying into Stage 2: the generic route is only "already equivalent" for the behaviour someone checked. The two gaps the design note names (openid email / accountLabel, and a per-connector configured answer) are real; this was a third.

Two declarations that say something deliberately unfinished

• WorkDrive declares no oauth block. Zoho's authorize/token endpoints are per data-centre (workDriveAccountsBase(env)), so there is no static URL to declare. Omitting it keeps /v1/connectors/zoho_workdrive/oauth/* answering 404 rather than minting an authorize URL against the wrong DC. Stage 2 needs an answer for this before it can retire /v1/workdrive/zoho/start.
• Drive and Gmail declare theirs, which makes the generic start route able to build a URL whose redirect_uri is /v1/connectors/<id>/oauth/callback — a path those OAuth apps do not have registered. Same inert state google_sheets already carries; nothing links it, and the dedicated flows remain the live ones.

Where that leaves the sequence

#352 Stage 1 → #355 → #352 Stage 2 still holds, and Stage 1 landing first is what the design note said it was for: #355's Connections section is now a loop over GET /v1/connectors rather than a third hardcoded copy of these blocks, and it arrives already correct for google_sheets.

Of the five hardcoded copies: one is deleted (client.ts), one is superseded by an endpoint anyone can call. The remaining three — the two route files, the console blocks, the MCP PROVIDERS map + Zod enum, the sync_connector trigger branch — are Stage 2 and #355 work, and each is now a consumer of one answer rather than an author of its own.

Also worth noting for whoever picks up Stage 2: #357 closed independently, so the "silently restores them" hazard is gone from both disconnect paths, and the argument in that issue about #355 making the move riskier no longer applies — there is nothing left to restore.

[serge-ivo]

Recommend deferring — #355 shipped and took the symptom with it

0735b24 + 91e762c moved connect/disconnect to Preferences and, per its closing note, the Drive/WorkDrive grant panel now renders on connected rather than configured — so the block is gone from all 26 instances. That was the user-visible reason this issue existed.

What remains is exactly the steady-state argument in the correction above, and it is now the ONLY thing here: connect Drive once at account level and the grant panel returns on every instance, including the four terminal Operators that will never read a document. Real, but hypothetical until someone connects Drive.

Against that: this issue has been corrected twice, its symptom is fixed, and it still needs a design decision nobody has made — whether Drive/WorkDrive get genuine agent-callable read tools (a scope expansion) or a different declared axis. Starting it today means making that call to service a problem no user currently has.

Suggest deferred: no demand under the #68 focus bet, to be revived by either a user connecting Drive and complaining, or a third-party-creator push where the closed connector vocabulary actually blocks someone. Not applying the label — that is a priority call.