feat(webhooks): receiver-side idempotency_key dedup on AsyncHandler

[bokelley]

Summary

Closes the receiver-side half of AdCP #2417 in the client library. Every MCP webhook payload now carries a required idempotency_key; this PR plumbs it through the pipeline and adds a drop-in dedup layer so at-least-once retries no longer trigger duplicate side effects in handler code.

What's new

• AsyncHandlerConfig.webhookDedup?: { backend, ttlSeconds? } — reuses IdempotencyBackend from @adcp/client/server, so the same memoryBackend() / pgBackend(...) used for request-side idempotency can back webhook dedup. Defaults to 24h.
• WebhookMetadata.idempotency_key?: string — extracted from the MCP envelope and passed to every onXxxStatusChange handler so application code can log, trace, or layer its own dedup.
• Activity union gains 'webhook_duplicate' — emitted via onActivity when a repeat key is dropped. Typed handlers are NOT called for duplicates (no side effects).

Behavior

• Scope is per-agent (webhook\u001f{agent_id}\u001f{idempotency_key}) — matches the spec's "scoped to authenticated sender identity" rule, keys from different senders never collide.
• putIfAbsent closes the concurrent-retry race: when two retries race on the same fresh key, exactly one wins the claim and dispatches; the rest surface as webhook_duplicate.
• Payloads without idempotency_key (non-conforming senders, or A2A transport which doesn't carry the field) dispatch without dedup and log a console.warn. No silent drops, no tuple fallback.

Schema sync

Pulled from AdCP latest — idempotency_key now required on:

• MCPWebhookPayload
• CollectionListChangedWebhook
• PropertyListChangedWebhook
• ArtifactWebhookPayload
• RevocationNotification (brand rights — not previously flagged in #2417)

Usage

import { AdCPClient } from '@adcp/client';
import { memoryBackend } from '@adcp/client/server';

const client = new AdCPClient(agents, {
  webhookUrlTemplate: 'https://your-app.com/adcp/webhook/{task_type}/{agent_id}/{operation_id}',
  webhookSecret: process.env.WEBHOOK_SECRET,
  handlers: {
    webhookDedup: { backend: memoryBackend() },
    onCreateMediaBuyStatusChange: async (result, metadata) => {
      // First delivery runs here; publisher retries are dropped.
    },
  },
});

Out of scope (follow-ups)

• Governance list-change / artifact / revocation webhooks — not currently routed through AsyncHandler; dedup for those payload types is a follow-up.
• Sender-side webhook emission helper — @adcp/client doesn't currently emit webhooks for sellers. When added, it will need to generate one idempotency_key per event and reuse across retries.
• RFC 9421 webhook signing — AdCP #2423 landed upstream; client implementation will follow in a separate PR.

Changeset

minor — new optional config + new metadata field + Activity union gains a new string literal. See .changeset/webhook-receiver-dedup.md.

Test plan

• npm run typecheck — clean
• npm test — 4067 pass / 0 fail
• 7 new tests in test/lib/async-handler-webhook-dedup.test.js:
  • duplicate delivery dropped
  • distinct keys dispatched independently
  • per-agent scoping prevents cross-sender collisions
  • missing key warns + dispatches
  • back-compat when webhookDedup unset
  • TTL expiry re-dispatches
  • end-to-end: idempotency_key propagates from MCP envelope → WebhookMetadata → handler

[bokelley]

Addressed review feedback in 3913076. Summary:

Accepted

• sec T7 — webhook_duplicate activity now omits payload; both events carry idempotency_key for correlation
• sec T2+T6 — receiver validates the spec regex ^[A-Za-z0-9_.:-]{16,255}$; invalid/empty/too-short keys treated as missing (no scoped-key construction from arbitrary sender bytes)
• code AdCP Testing Framework with Authentication, Hierarchical Logging & Security Features #1 — reserved scoped-key prefix adcp\u001fwebhook\u001fv1\u001f... so backend sharing with request-side idempotency is collision-proof
• code Rebrand to Ad Context Protocol and remove side navigation #4 — WebhookMetadata.protocol plumbed through; missing-key warn only fires for MCP (A2A lacks the field by protocol design)
• dx Update documentation and production configuration #3+Rebrand to Ad Context Protocol and remove side navigation #4 — warn message now names the spec regex, describes fallback behavior, links to docs; JSDoc on handlers field points at dedup section
• dx fix the a2a sdk client import issue #5+Fix agent configuration to use .env only approach #7 — docs cover activity double-fire, migration-from-ad-hoc dedup, A2A/invalid-key behavior
• code Implement official MCP/A2A clients with HTTP streaming and UI improvements #6 — changeset has explicit "Type changes" subsection for strict-TS exhaustive Activity.type switches
• code #8a+c — concurrent-race test (5 parallel retries → 1 dispatch) and handler-exception test (claim sticks)
• code Fix agent configuration to use .env only approach #7 — grepped; no downstream references to RevocationNotification.notification_id

Rejected with rationale

• code Fix Fly.io deployment timeout issues #2 (release claim on handler error) — incoherent with current behavior. handleCompletion catches handler exceptions and returns normally, so handleWebhook already 200s the publisher on handler failure. Releasing the claim would trigger infinite retry storms against deterministic handler bugs. Added a test documenting this at-most-once contract rather than changing it.
• dx AdCP Testing Framework with Authentication, Hierarchical Logging & Security Features #1 (webhookDedup: true shortcut) — would force core/ to runtime-import server/, inverting module layering. Explicit { backend: memoryBackend() } is 2 lines and a clear mental model.
• dx Fix Fly.io deployment timeout issues #2 (re-export memoryBackend from root) — fragments module layout.
• sec T3 (memoryBackend LRU cap) — pre-existing backend behavior, not introduced by this PR. Filing separately.
• dx fix the a2a sdk client import issue #5 (onMissingKey throw option) — YAGNI; no user has asked for strict mode.

Test suite: 4084 pass / 0 fail. New tests bring dedup coverage to 12 cases.