Instrument LangGraph Platform thread-controller execution

runs.wait と runs.stream の既存のインストルメンテーションから始め、次にコントローラーのエントリポイントである client.threads.stream(...), thread.run.start(options), thread.input.respond(...)、および client.threads.joinStream(...) を調査します。要求された real-SDK のエンドツーエンドケースを最初のテスト対象として使用します。完了の条件は、サポート対象の API と span のライフタイムが文書化され、すべての受け入れシナリオに合格し、反復、同時実行、ラップ、自動、無効の各モードでアプリケーションの動作が維持されることです。

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.