adcpError should support echoing request context

[bokelley]

Summary

The server-side adcpError() builder cannot carry the buyer-supplied opaque request context onto the response envelope. Sellers that must satisfy request/response context correlation therefore need a wrapper that constructs the SDK error and then manually rewrites structuredContent.

Downstream example: https://github.com/scope3data/agentic-api/blob/main/apps/api/src/core-routes/storefront-handlers/_shared.ts

That one wrapper currently has 108 call sites across storefront handlers. The duplication is not error construction itself—the SDK already owns that well—but the missing context-preserving variant means every error path must remember to use a downstream replacement instead of adcpError() directly.

Current workaround

function errorWithContext(code, options, requestContext) {
  const envelope = adcpError(code, options)
  if (requestContext === undefined) return envelope
  return {
    ...envelope,
    structuredContent: {
      ...envelope.structuredContent,
      context: requestContext,
    },
  }
}

This also risks the text fallback and structured payload drifting because the caller is modifying only one of the builder's transport layers after construction.

Expected

Give adcpError() a supported way to include opaque response context while it constructs all transport layers. Exact API shape is a maintainer choice, for example an optional envelope argument:

adcpError(code, options, { context: request.context })

or a dedicated adcpErrorWithContext() helper.

The context belongs beside adcp_error in the response payload, not inside the error details or per-code allowlist.

Acceptance criteria

• Callers can supply an opaque context value without manually spreading the returned envelope.
• When context is defined, structuredContent contains both adcp_error and the unchanged context.
• The text fallback represents the same payload so L2 and L3 consumers do not observe different context behavior.
• Undefined context remains omitted and preserves the current output exactly.
• Error-field allowlisting/sanitization continues to apply only to adcp_error; context is not accidentally folded into diagnostic details.
• Server examples and tests show success and error responses echoing the same request context.

Why this belongs in the SDK

The builder already owns the three-layer error envelope contract. Adding context after construction makes those layers inconsistent and makes the safe path easy to bypass. Encoding the behavior once in the SDK removes a high-fan-out downstream wrapper and keeps correlation semantics uniform across sellers.

[bokelley]

Triage

Classification: Feature request
Bucket(s): library
Status: ready-to-implement

What the experts said:

• code-reviewer: Blocker on text-fallback divergence is real — the current workaround patches only structuredContent and not content[0].text, so L2 consumers observe no context. Must apply isEchoableContext() guard before attaching (same predicate wrapEnvelope uses). Type widening on AdcpErrorResponse.structuredContent to { adcp_error: AdcpErrorPayload; context?: object } is required; the existing [key: string]: unknown index does not cover the inner shape. Changeset: minor.
• dx-expert: Framework users (createAdcpServer / createAdcpServerFromPlatform) already get context echo for free from injectContextIntoResponse in the dispatch path — the gap is real but scoped to v5 raw-handler adopters. Recommends folding context into AdcpErrorOptions (Option C) rather than a positional third arg — a third arg is ambiguous with WrapEnvelopeOptions and harder for agents to discover. Only examples/error-compliant-server.ts needs one representative call site updated.

My take: Both experts agree the change is non-breaking and well-scoped. The main implementation constraint is atomic dual-write to content[0].text and structuredContent — same pattern injectContextIntoResponse already uses at create-adcp-server.ts.

Implementation scope:

• src/lib/server/errors.ts — add optional context?: unknown to AdcpErrorOptions; apply isEchoableContext() guard; dual-write to both transport layers; widen AdcpErrorResponse.structuredContent type.
• Export or inline isEchoableContext from wrap-envelope.ts to avoid duplicating the guard.
• examples/error-compliant-server.ts — add context: params.context to one representative adcpError() call.
• Add tests: context echoes to both layers; non-object context dropped silently; undefined produces no context key; sanitization applies only to adcp_error, not to context.
• npm run changeset — minor (new optional public field on exported interface + optional param on exported function).

---

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

---

Generated by Claude Code