Design first-class Go seller framework API

[bokelley]

Goal

Define the public Go seller-framework API that makes adcp-go feel first-class, not just a typed MCP helper. This should be the Go equivalent of the JS/Python decisioning-platform layer, adapted to Go idioms.

Why

The current adcp.Register surface works and is small, but adopters still hand-wire too much: update/list_creatives outside Config, auth/account context, task handoff, validation, and production guardrails. A first-class Go SDK needs one coherent framework surface.

Scope

• Define the target public API for seller implementations.
• Decide whether to evolve adcp.Config or add a higher-level builder/platform abstraction.
• Group handlers by domain/specialism without making simple sellers verbose.
• Include extension points for auth, account resolution, tenant routing, validation, idempotency, task handoff, and webhooks.
• Keep dependency boundaries explicit; optional heavier integrations belong in subpackages.

Acceptance Criteria

• A design doc or ADR lands in-repo.
• The design includes a minimal hello-seller example and a production translator-pattern example as target consumers.
• The API avoids global state and uses functional options/interfaces where appropriate.
• Existing adcp.Register users have a clear migration path or compatibility wrapper.

Related

• Add first-class seller SDK hooks for update_media_buy and list_creatives #144
• Schema-driven validation: client hooks + opt-in server middleware #67
• reference: A2A transport alongside MCP on reference agents #69
• Make the Go SDK generator first-class #153

[bokelley]

Triage

Classification: Feature request (RFC / design task)
Bucket(s): sdk, tmpclient
Status: ready-for-human
Milestone: Go first-class SDK (#1)

What the experts said:

• code-reviewer: acct any is the central design risk — ResolveAccount returns any and every handler that follows receives it untyped; adding auth, tenant-routing, and task-handoff hooks on top of an untyped account context will compound this. The RFC must commit to a typed Account interface or Config[A any] generic before wiring more extension points. Also: update_media_buy and list_creatives currently bypass Register entirely (wired via raw adcp.AddTool); the new framework must close this gap, not paper over it. Split the ADR landing from the Add first-class seller SDK hooks for update_media_buy and list_creatives #144 implementation so each PR is independently reviewable.
• dx-expert: The flat Config struct already strains at 16 function fields across four protocol domains, and governance tools are off-Config entirely. The acct any parameter is the dominant agent-generation hazard — coding agents cannot infer the concrete type and generate casts that compile but panic at runtime. Migration path needs both a mechanical transformation rule and a compatibility shim commitment in the acceptance criteria; without an explicit shim guarantee, existing adcp.Register callers will stall on upgrade. Acceptance criteria should require that both examples pass the storyboard runner (npx @adcp/client) and that the adcp.Register deprecation timeline is declared explicitly.
• ad-tech-protocol-expert: Hard dependency ordering issue — Design first-class Go seller framework API #348 cannot produce a transport-agnostic framework until reference: A2A transport alongside MCP on reference agents #69's handler-closure refactor lands; if Design first-class Go seller framework API #348 ships before reference: A2A transport alongside MCP on reference agents #69, every handler signature will embed *mcp.CallToolRequest and a later A2A port forces a breaking API change. "Task handoff" must be scoped to an async executor behind CreateMediaBuySubmitted.TaskID only — the design must not introduce a parallel async return channel that bypasses MediaBuyResponse. The translator example must pass through the upstream seller's get_adcp_capabilities faithfully; running detectProtocols against a translator's shim handlers will over-declare supported_protocols relative to the upstream seller.
• adtech-product-expert: Design first-class Go seller framework API #348 is implicitly the umbrella for Add first-class seller SDK hooks for update_media_buy and list_creatives #144, Schema-driven validation: client hooks + opt-in server middleware #67, reference: A2A transport alongside MCP on reference agents #69, and Make the Go SDK generator first-class #153 but is not formally structured as one — those issues will produce conflicting designs against the same adcp/seller.go surface if they proceed in parallel without a decided API shape. The ADR must be landed before Add first-class seller SDK hooks for update_media_buy and list_creatives #144 ships (or Add first-class seller SDK hooks for update_media_buy and list_creatives #144 will bake an assumption that the ADR may reverse). Missing from the example targets: a multi-tenant SaaS seller shape where a single binary serves N publisher accounts with per-tenant backends — this is where the ResolveAccount func(...) (any, error) boundary breaks down most visibly in production.
• security-reviewer: Three blockers for the design doc. (1) ResolveAccount returning any is not a safe type boundary in a TEE SDK — nothing prevents an implementor from placing secrets or session-scoped values inside the any return and having them flow into response builders or log context; the ADR must define a sealed account interface the framework enforces. (2) Webhook egress from TEE violates the pinhole without an explicit outbound allow-list; webhook target URLs must be validated through the same SSRF guard already in router/router.go and must not be runtime-injectable in TEE-bound agents. (3) The root go.mod already carries direct deps on prometheus/client_golang, redis/go-redis/v9, testcontainers-go, the full OTel stack, and Docker client libraries — AGENTS.md states "root module has zero external deps" but this invariant is already violated; any framework surface added to the root module will compound this, and the discrepancy must be resolved before the ADR can prescribe where new code lands.

My take: This is the right issue to have — the adcp.Config flat-struct approach will not scale cleanly to the full "Go first-class SDK" roadmap, and an ADR before #144 ships is the correct gate. However, security-reviewer raised three design-level blockers (untyped account boundary, webhook TEE egress, root module dep invariant) and the protocol expert identified a hard sequencing constraint with #69 that the ADR must resolve explicitly. Route to @bokelley to drive the design doc; the relevant constraints are all captured here.

ADR must address:

• Choose typed Account interface / Config[A any] generic vs. keeping any — justify the type boundary from a TEE-safety perspective.
• Declare whether adcp.Register is a permanent alias or deprecated-with-timeline.
• Sequence decision for reference: A2A transport alongside MCP on reference agents #69 (transport-agnostic refactor): block Design first-class Go seller framework API #348 on reference: A2A transport alongside MCP on reference agents #69, or include transport abstraction in Design first-class Go seller framework API #348 itself.
• Webhook extension point: require static-config URL validation through the existing SSRF guard; document prohibition in TEE-bound agents.
• Idempotency wiring: decide whether Config gains an IdempotencyStore field or sellers continue to wrap handlers manually.
• Define "optional heavier integrations in subpackages" precisely: auth context, account resolution, and validation hooks stay in the core adcp package; persistence backends (Postgres idempotency, webhook delivery) go in subpackages.
• Resolve the root module dep invariant before specifying where new framework code lands.

---

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

---

Generated by Claude Code