[opencode-observability-plugin] Add opt-in W3C trace context propagation

[siglp]

Describe the feature or potential improvement

Feature
OpenCode and OpenTelemetry-enabled LLM gateways currently create separate traces. Tested on agentgateway 1.6.0, Langfuse 4.71.0 and Opencode 1.19.5 and Opencode 2.2.4

Without feature:

Add an optional LANGFUSE_PROPAGATE_TRACE_CONTEXT=true setting so outbound LLM requests can carry the existing Langfuse trace context. It must be disabled by default, preserve existing traceparent headers, and never create a new Trace ID only for propagation.

Proposed Solution
Use OpenCode 1's chat.headers hook to inject W3C traceparent, preferring the active generation span and falling back to the current turn.

Validate span context, preserve existing headers, and add tests for formatting, hierarchy, missing context, concurrency, and plugin replacement.

Support OpenCode 2 only after its native transport can preserve or adopt the supplied parent context. Until then, document V2 as unsupported rather than injecting a header that is overwritten on the wire. More detail is in my comment here: anomalyco/opencode#49038

Solution ready
I have working solution based on last version of https://github.com/langfuse/opencode-observability-plugin - 0.7.0. It is working with agentgateway 1.6.0, Langfuse 4.71.0 and Opencode 1.19.5 and Opencode 2.2.4 (just with "fixed" OpenCode itself)

With feature:

Additional information

No response

[dfbustosus]

The screenshots make the case well — and from the Langfuse side the mechanism you're relying on is fully supported, which is worth stating explicitly for the maintainers: Langfuse natively ingests OTLP (/api/public/otel, since v3.22.0 self-hosted) and correlates by trace ID, so once the gateway starts its spans under the propagated traceparent, everything lands in one stitched trace without any Langfuse-side changes. Your constraints (preserve existing traceparent, never mint a trace ID only for propagation, default-off) are exactly the W3C-correct behavior — an injected context that invented its own trace ID would corrupt exactly the stitching you're after.

Two things worth carrying into the plugin README if this ships:

1. Trace-level attributes won't ride along. Langfuse maps userId / sessionId / tags / version from span attributes (or baggage) — the gateway's spans won't carry langfuse.* attributes, so filtering and aggregation over the stitched trace will depend on the root opencode span having them. Document that the root span should set langfuse.trace.* attributes, otherwise the merged trace is searchable only by content/time.
2. Root-span requirement. Langfuse needs a root span to be exported for the trace to be created correctly. With propagation the root is opencode's span, so if opencode is configured to sample/drop while the gateway exports, you can end up with orphaned child spans. Worth a note on keeping at least the root span unsampled while the opt-in is enabled.

On the V2 limitation: documenting it as unsupported until the transport preserves supplied parent context (vs. overwriting on the wire) is the right call — a traceparent that gets silently replaced produces two traces, which is worse than today's behavior because it looks like propagation worked.

The chat.headers injection point plus a LANGFUSE_PROPAGATE_TRACE_CONTEXT=true opt-in seems like a clean shape; hopefully the anomalyco/opencode#49038 discussion lands the V2 transport fix so both majors can share the implementation.

[siglp]

I've submitted PR #60 implementing opt-in W3C trace context propagation for both OpenCode V1 and V2.

The implementation has been tested end-to-end with OpenCode V1 and V2, AgentGateway, and Langfuse.

V2 requires the corresponding OpenCode transport fix: anomalyco/opencode#61386.