Instrument LangGraph Platform thread-controller execution

Inizia con la strumentazione esistente per runs.wait e runs.stream, quindi esamina i punti di ingresso del controller client.threads.stream(...), thread.run.start(options), thread.input.respond(...) e client.threads.joinStream(...). Usa i casi end-to-end richiesti con real-SDK come prima superficie di test. Il lavoro è completato quando le API supportate e i cicli di vita degli span sono documentati, tutti gli scenari di accettazione hanno esito positivo e le modalità ripetuta, concorrente, con wrapping, automatica e disabilitata preservano il comportamento dell’applicazione.

Follow-up to https://github.com/braintrustdata/braintrust-sdk-javascript/issues/2199.

Thread-controller execution was explicitly deferred from #2199. The current implementation intentionally instruments only runs.wait and runs.stream, where execution and result consumption belong to one call.

Scope

Add instrumentation for the controller returned by client.threads.stream(...), starting with thread.run.start(options). Evaluate continuation and reattachment APIs, including thread.input.respond(...) and client.threads.joinStream(...), and explicitly document which are supported.

Controller construction does not execute an agent. A run.start() acknowledgement can arrive before execution completes, so tracing must distinguish controller setup, submission, and the run's actual lifecycle.

Implementation considerations

• In the inspected SDK versions (1.9.25 and 1.10.2), a controller's output promise is cached across runs. Do not let a previous run's settled promise prematurely finish a later run's span.
• Prefer public lifecycle observations and normal typed-channel instrumentation. Avoid opening extra subscriptions or consuming streams solely for tracing when existing events suffice.
• Define correlation when a controller observes an execution started elsewhere, as well as behavior across reconnection and repeated runs.
• Keep remote model/tool internals distinct from client-side execution observations; do not invent spans for unobserved work.

Acceptance criteria

• Provide automatic and explicit instrumentation with shared extraction logic and stable task-span names.
• Capture each supported run's input, final state, errors, available usage, and streaming timing; use allowlisted metadata.
• End spans correctly on completion, failure, interruption, and controller closure. Preserve cancellation, promise/controller identity, and private-field receivers.
• Ensure repeated runs, teardown/re-enabling, and wrapper-plus-hook usage do not duplicate spans, mix contexts, leak listeners, or change application behavior.
• Add real-SDK e2e tests for multiple runs on one controller, independent concurrent controllers, acknowledgement before completion, failures, interruptions, closure, and supported continuation/reattachment behavior.
• Cover pinned and separately named latest SDK aliases, ESM/CommonJS, and wrapped/automatic/combined/disabled modes. Assert paired span-tree snapshots, update the CI summary, and verify three consecutive replay runs.
• Document the supported controller APIs and span lifetimes.