feat(testing): version-staleness hint when agent is on pre-factory @adcp/client

[bokelley]

Context

PR #848 shipped runtime hints naming `buildCreativeResponse` / `audioAsset` / `displayRender` / `parameterizedRender`. If a developer is on `@adcp/client` < 5.14 (the version these factories first shipped in — scope3's original path in agentic-adapters#100 was on 4.16.2), the hint is slightly misleading: the helper exists in the SDK, but their pinned version doesn't have it.

DX-expert's review flagged this as a gap — the developer follows the hint, adds the import, gets a "module has no exported member" error, and has to figure out they need to upgrade.

Proposal

Two places where version staleness could be detected:

1. Agent-observed case — the storyboard runner pulls the agent's `get_adcp_capabilities` response, which includes `library_version: '@adcp/client@X.Y.Z'` when the agent self-reports via the existing capability surface. If the version is present AND older than the minimum release that shipped the referenced helpers, suffix the hint:
   ```
   ... Use buildCreativeResponse() from @adcp/client/server.
   (Note: your agent reports @adcp/client@4.16.2 — these helpers ship in ≥5.14. Upgrade your SDK dep.)
   ```

2. Client-side case — the CLI startup staleness check (shipped in feat(cli): pin @latest in docs + startup staleness check #835) already hits npm for the latest version. Extend it to note which features the user's pinned version lacks, if we maintain a `FEATURES_BY_VERSION` map.

(1) is tighter — it triggers only when the hint actually applies. (2) is broader but less targeted.

Scope

Start with (1). Add a `library_version` field to `StoryboardContext` (populated from the capabilities response), thread it into `detectShapeDriftHint`, and maintain a small `HELPER_MIN_VERSION` map:

```ts
const HELPER_MIN_VERSION: Record<string, string> = {
buildCreativeResponse: '5.14.0',
audioAsset: '5.14.0', // shipped earlier, confirm via git log before merging
displayRender: '5.14.0',
parameterizedRender: '5.14.0',
};
```

Suffix the hint when the agent's reported version is below the min for the helper being recommended.

Out of scope

• Forcing agents to report `library_version`. If it's absent, skip the suffix — don't demand it. Some agents will be hand-rolled and won't carry this field.
• Per-feature capability flags (`capabilities.supports_build_creative_v2`) — heavier and overlaps with version reporting.

Related

• feat: creative-agent ergonomics — render factories, --strict-flags, shape-drift hint #848 (merged) — shape-drift hint framework
• feat(cli): pin @latest in docs + startup staleness check #835 (merged) — CLI startup staleness check
• feat(testing): extend detectShapeDriftHint to sync_creatives and preview_creative #849 — shape-drift expansion to sync_creatives / preview_creative

Follow-up from #848's DX review.

[bokelley]

Triage

Classification: feature
Bucket(s): conformance, cli
Status: drafting-pr

What the experts said:

• ad-tech-protocol-expert: library_version is not in the AdCP spec schema, but GetAdCPCapabilitiesResponseSchema uses .passthrough() so stamping it as an extension field is safe — no AJV rejection risk; nit that ext.library_version would be more spec-aligned long term.
• code-reviewer: concept sound; two blockers fixed before PR (dead HELPER_MIN_VERSION entries for helpers not referenced in any hint message; pre-release semver strip to handle 5.14.0-beta.1). Numeric semver comparison correctly guards the 5.9.0 < 5.14.0 lexicographic trap.

My take: Both sides needed: createAdcpServer now stamps library_version automatically, so agents built on this SDK surface the version without adopter changes. Draft PR #1030 covers the full implementation with 6 new tests.

---

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

---

Generated by Claude Code