RFC: The agent connection layer — one place to configure a buyer–seller relationship

[bokelley]

Problem

Configuration between one authenticated caller and one seller agent is scattered across three layers, and only one of them is unified:

Concern	Where it lives today	Cost
Caller-anchored webhooks (capabilities.changed)	sync_agent_configuration (#6966)	one call ✅
Account-anchored webhooks (creative.*, account.*, product.*, signal.*, …)	each account's notification_configs[] via sync_accounts	N calls to sign up, N calls to unwind a bad endpoint
Media-buy delivery reports	each buy's push_notification_config	M configs
Buyer version/capability declaration	nowhere durable	webhooks have no request context, so async payload versioning has no negotiation channel at all
Push when seller-side connection state changes (destination validating → ready, expiring share grants)	nowhere	buyers poll get_agent_configuration

Concretely: an agency principal managing 200 accounts at one seller makes 201 registration calls to "sign me up for everything," and when the endpoint is misconfigured, 200 more to pull it. A seller that wants to fire a webhook at a buyer six weeks after registration has no way to know what payload version the buyer speaks. And the moment a Delta share grant is about to expire, nobody gets told.

Proposal

Build on #6966's principal, proof, versioning, and revocation machinery. Three additions, one rule flip:

1. Connection-level webhook subscriptions

Allow caller-level subscribers (the notification_configs section) to include account-anchored event types, with authorization evaluated at fire time: each fire covers only accounts the caller is currently authorized for. Losing account authority silently stops that account's fires — the subscription is standing; the authorization is not.

• This flips the current enum rule (notification-type.json today rejects caller-level entries carrying account-anchored types), which is why this RFC should land while protocol.agent_configuration is still experimental.
• No wildcard. "Everything" is an enumerated event_types list plus an explicit include_future_event_types: true opt-in for callers who want new invalidation-style events to flow automatically.
• Account-level and connection-level subscriptions are independent; both fire, receivers dedupe by notification_id (every account-anchored event already carries stable IDs).
• Subscriber-level active: false is a one-call kill switch: all fires to that endpoint across all accounts halt within the seller's advertised interval — the webhook twin of feat(protocol): add agent configuration sync #6966's destination suspension.
• Once feat(reporting): add managed reporting status schemas #6953 lands, reporting.delivery_ready registers here too, matching the connection-scoped reporting destinations it fires about.
• Deferred: media-buy-anchored delivery reports (scheduled, final, …) keep per-buy registration; they carry per-buy cadence choices. A connection-level default with per-buy override is a later step.

2. A declarations section — the flip side of capability negotiation

A third replaceable section in sync_agent_configuration where the buyer declares consumption facts: supported AdCP versions for async payloads, webhook signing algorithms it can verify, experimental features it opts into, accepted transports. The seller returns the accepted intersection in readback state.

• Solves async payload versioning: the durable declaration is the version-negotiation channel that webhook fires lack.
• Discipline: bounded, enumerable declarations of fact about what the buyer can consume — not an open-ended preference language, and not a second capability document. get_adcp_capabilities stays objective seller facts; this stays caller-declared facts; the intersection is the contract.

3. A connection.changed caller-anchored event

An invalidation doorbell for seller-driven connection-state transitions: destination validating → ready, setup.expires_at approaching, proof invalidated, accepted declaration intersection changed. Payload is invalidation-only; receivers repair by reading get_agent_configuration. This closes the poll loop for destination setup and gives buyers early warning before delivery breaks, following the exact capabilities.changed pattern.

Non-goals

• No role field. A campaign governance agent and a buyer agent are different transport principals with their own connections; what each may bind is an account-authorization fact, not a self-asserted body field. Same task, same schema, role-blind connection layer.
• No cross-principal visibility or linking (unchanged from feat(protocol): add agent configuration sync #6966).
• No third capability document.

Relationship to in-flight work

• feat(protocol): add agent configuration sync #6966 — the foundation: stable principal, proof-bound destinations, optimistic concurrency, get_agent_configuration, suspension/revocation. This RFC extends its section model and flips one enum rule it currently ships.
• feat(reporting): add managed reporting status schemas #6953 / RFC: reliable reporting status and managed delivery #6911 — reporting.delivery_ready should register at the connection level per this RFC; the reporting destinations it fires about already live there.
• Fixture-dependent conformance for agent configuration lifecycle #7010 — fixture-dependent conformance; the fire-time-authorization and kill-switch-halt behaviors here land in the same controller-backed storyboard.

Questions for the WG

1. Is the problem real for you? Especially multi-account operators: how many per-account webhook registrations do you carry today, and have you had to unwind a bad endpoint account-by-account?
2. Is fire-time authorization scoping the right model, or do connection-level subscriptions need explicit per-account filters in v1? (Proposal: all-authorized-accounts in v1, filters later if pulled.)
3. When: this flips a rule feat(protocol): add agent configuration sync #6966 currently ships. Land it while the surface is experimental, or let feat(protocol): add agent configuration sync #6966 stabilize a cycle first?

An implementation PR (stacked on #6966) will follow this issue for concreteness; schemas remain subject to this discussion.

🤖 Generated with Claude Code

[bokelley]

Triage

Classification: RFC / proposal
Bucket(s): spec / protocol
Status: deferred

Blocked-on: #6966 — this RFC extends that PR's section model and flips one enum rule it ships; resurfaces on merge.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01TkPro3rrYW93UMEjZewmJ9

---

Generated by Claude Code

[bokelley]

Draft implementation for concreteness: #7020 (stacked on #6966; schemas remain subject to this discussion). It covers all three additions — fire-time-scoped connection-level subscriptions with include_future_event_types, the declarations section with seller-computed accepted intersection, and the connection.changed invalidation webhook — plus caller_event_types capability advertising.

🤖 Generated with Claude Code

[sangilish]

From a multi-account operator perspective, fire-time authorization is the right v1 default; explicit per-account filters would recreate the N-account lifecycle this RFC is trying to remove.

I think one control-plane invariant is still missing: when a caller's authorized-account set changes, emit connection.changed with an authorization-scope reason. Otherwise the receiver cannot distinguish a quiet account from revoked access. The payload need not reveal account IDs; for this reason, repair can be defined as list_accounts under current authority rather than get_agent_configuration.

I would also scope include_future_event_types by anchoring class: opting into future caller-level invalidations should not implicitly opt an endpoint into future account-data events. The accepted async version can bound enum evolution within that class.

With those constraints, the connection-level model looks operationally sound.

[bokelley]

Design update from continued review (reflected in #7020 and the base PR #6966):

• The layer is named after its entity: the principal — the durable party (buyer agent or operator identity) behind an authenticated caller. Tasks are now sync_principal / get_principal; the webhook is principal.changed; the capability block is adcp.principal. "Agent configuration" implied configuring the agent; "connection" read transient; principal is the term the normative text already used throughout.
• Three-tier hierarchy: principal → standing configuration → accounts. list_accounts unification under a resource-oriented principal read is noted as a 4.0-scale north star, not attempted now.
• Operators belong to agents in the agent-auth case. Each agent maps its operators its own way, so operator identity is agent-relative: destinations gain an optional agent-scoped operator_id label (isolation, audit, one-call offboarding), with a normative rule that matching operator labels or domains across principals MUST NOT be linked, deduped, or granted shared authority. Bridging principals is the explicit delegation surface (list_principals), deferred to a follow-up.
• Resolved principal_kind (buyer_agent | operator) on every readback plus an expected_principal_kind assertion fence (CONFLICT on mismatch, never identity input) — so per-party policy like the existing per-agent billing gates has something verifiable to hang off, without reopening self-asserted identity.
• Per-hop composition: buyer agent → Interchange → seller is two independent principal relationships; a person in Claude buying through Interchange is one operator principal at Interchange. No hop sees through the next; end-to-end reconciliation stays at the data layer (rows carry seller + account identity per RFC: reliable reporting status and managed delivery #6911).

🤖 Generated with Claude Code