update_media_buy dispatched via projectSync, not routeIfHandoff, async task not framework-scoped (unpollable via tasks/get)

[tej656]

Summary

In createAdcpServerFromPlatform, the updateMediaBuy handler is wrapped in projectSync only, whereas getProducts, createMediaBuy, syncCreatives, and getSignals are wrapped in routeIfHandoff. Because of this, an adopter's update_media_buy handler can't return a ctx.handoffToTask(...) marker to go async. The framework never creates or owns the task, so it isn't registered with a framework-computed owner_scope, which means it can't be polled via tasks/get / get_task_status.

This is inconsistent with the spec. update_media_buy is a valid async task type (it's in enums/task-type.json and in SPEC_WEBHOOK_TASK_TYPES in runtime/protocol-for-tool.mjs), so async is spec-legal for it, but the runtime doesn't wire it up.

Version

@adcp/sdk@12.0.4 (spec 3.1.2). Present throughout the 12.x line.

Where (dist paths / symbols)

dist/lib/server/decisioning/runtime/from-platform.mjs:

• routeIfHandoff is used by getProducts (~1858, 1936), createMediaBuy (~2007), syncCreatives (~2095, 2295), and getSignals (~2464).
• The updateMediaBuy handler (~2033–2081) returns projectSync(...) (~2054) with no routeIfHandoff branch.
• routeIfHandoff (defined ~1224) gates on isTaskHandoff(result); projectSync (~1173) has no handoff detection at all.

Impact

Adopters whose update_media_buy is genuinely slow (for example, an ad-server activation sync that runs past the buyer's transport timeout) have no framework path to return a Submitted task. Working around it means manually writing to the taskRegistry and hand-computing owner_scope to match what tasks/get re-derives (taskOwnerScopeFor → session:${ctx.sessionKey} when a session key is present). If the manual owner_scope doesn't match exactly, taskBelongsToCaller fails and every poll returns REFERENCE_NOT_FOUND even though the task completed. It's a silent, easy-to-hit footgun, and it forces adopters to duplicate internal SDK logic they shouldn't need to know about.

Steps to reproduce

1. Adopter update_media_buy handler returns ctx.handoffToTask(fn).
2. The marker is ignored or mis-validated (it goes through projectSync, not routeIfHandoff).
3. Work around it with a manual taskRegistry.create({...}) that omits ownerScope, so the row falls back to account:<id>.
4. Poll tasks/get with the returned task_id and get REFERENCE_NOT_FOUND, because the poll expects session:<id>.

Expected

updateMediaBuy should be wrapped in routeIfHandoff like the other async-capable tools, so that a handler returning ctx.handoffToTask(...) is framework-owned. Task creation, owner_scope (taskOwnerScopeFor), polling, and webhook emission would all be handled by the runtime, with no adopter-side owner_scope duplication.

Proposed fix

Wrap the updateMediaBuy dispatch result in routeIfHandoff, mirroring the createMediaBuy closure (~2007):

return routeIfHandoff(
  taskRegistry,
  {
    tool: "update_media_buy",
    accountId,
    ownerScope: taskOwnerScopeFor(ctx, reqCtx.account.id),
    // …
  },
  result,
  project
);

update_media_buy is already in SPEC_WEBHOOK_TASK_TYPES, so sync-completion and async webhooks will emit consistently.

Workaround (for other adopters hitting this)

Register the task manually on the same taskRegistry the server was constructed with, and set owner_scope to session:${ctx.sessionKey} (that is, whatever your configured resolveSessionKey returns) so tasks/get scope-matches. Note that sessionKey isn't exposed on the handler's reqCtx, so you'll need to derive it the same way your resolveSessionKey does.

[bokelley]

Triage

Classification: Bug
Bucket(s): media-buy
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Spec is unambiguous — update_media_buy is in enums/task-type.json, has dedicated update-media-buy-async-response-{submitted,working,input-required}.json schemas, and DR-0008 is explicit: "This record does not license SDKs to diverge from an unambiguous spec — that is an SDK bug." No schema or doc change needed in this repo.
• javascript-protocol-expert: Fix is sound — wrap updateMediaBuy in routeIfHandoff mirroring the createMediaBuy closure; non-breaking for handlers returning sync responses (routeIfHandoff gates on isTaskHandoff(result)). Adopters using the manual taskRegistry.create workaround face double task-registration and potential double webhook emission on upgrade — the SDK release notes must call this out prominently.

My take: The spec fully supports async update_media_buy (task-type enum, three dedicated async response schemas, taskSupport: 'optional' in the training agent, webhook registry already wired). The fix belongs entirely in adcp-client; nothing changes in this repo.

Implementation brief (for adcp-client / @adcp/sdk patch):

• File: src/server/decisioning/runtime/from-platform.ts → compiled dist/lib/server/decisioning/runtime/from-platform.mjs
• Change: In createAdcpServerFromPlatform, wrap the updateMediaBuy handler result in routeIfHandoff(taskRegistry, { tool: "update_media_buy", accountId, ownerScope: taskOwnerScopeFor(ctx, reqCtx.account.id), … }, result, project), mirroring the createMediaBuy closure (~line 2007 of compiled output)
• Non-breaking for common case: routeIfHandoff gates on isTaskHandoff(result) — sync-returning handlers pass through unchanged
• Migration note (required in release notes): Adopters using the manual taskRegistry.create workaround must remove it before upgrading — double-registration produces double async completion webhook emission; no automatic deduplication covers that path
• Verify in patch PR: Confirm isTaskHandoff returns false for error-body shapes so the ERROR_IN_BODY_TOOLS path doesn't enter the handoff branch (almost certainly fine given createMediaBuy shares the same error convention, but worth an explicit test case)

Sibling-repo-fix-needed: adcontextprotocol/adcp-client — from-platform.ts, updateMediaBuy handler, missing routeIfHandoff wrap. Patch to @adcp/sdk@12.x line. Please file a tracking issue in adcp-client to own the fix.

---

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

---

Generated by Claude Code