refactor(nodejs): remove @opentelemetry/api dependency

Replace the optional @opentelemetry/api peer dependency with a
user-provided callback approach:

- Add TraceContext interface and TraceContextProvider type
- Add onGetTraceContext callback to CopilotClientOptions
- Pass traceparent/tracestate directly on ToolInvocation for inbound context
- Remove @opentelemetry/api from peerDependencies and devDependencies
- Rewrite telemetry.ts to a simple callback-based helper (~27 lines)
- Update tests, README, and OpenTelemetry docs with wire-up examples

Users who want distributed trace propagation provide a callback:

  const client = new CopilotClient({
    onGetTraceContext: () => {
      const carrier = {};
      propagation.inject(context.active(), carrier);
      return carrier;
    },
  });

TelemetryConfig (CLI env vars) is unchanged and requires no dependency.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

docs/observability/opentelemetry.md

@@ -80,16 +80,72 @@ var client = new CopilotClient(new CopilotClientOptions
 
 ### Trace Context Propagation
 
-Trace context is propagated automatically — no manual instrumentation is needed:
+> **Most users don't need this.** The `TelemetryConfig` above is all you need to collect traces from the CLI. The trace context propagation described in this section is an **advanced feature** for applications that create their own OpenTelemetry spans and want them to appear in the **same distributed trace** as the CLI's spans.
 
-- **SDK → CLI**: `traceparent` and `tracestate` headers from the current span/activity are included in `session.create`, `session.resume`, and `session.send` RPC calls.
-- **CLI → SDK**: When the CLI invokes tool handlers, the trace context from the CLI's span is propagated so your tool code runs under the correct parent span.
+The SDK can propagate W3C Trace Context (`traceparent`/`tracestate`) on JSON-RPC payloads so that your application's spans and the CLI's spans are linked in one distributed trace. This is useful when, for example, you want to see a "handle tool call" span in your app nested inside the CLI's "execute tool" span, or show the SDK call as a child of your request-handling span.
+
+#### SDK → CLI (outbound)
+
+For **Node.js**, provide an `onGetTraceContext` callback on the client options. This is only needed if your application already uses `@opentelemetry/api` and you want to link your spans with the CLI's spans. The SDK calls this callback before `session.create`, `session.resume`, and `session.send` RPCs:
+
+<!-- docs-validate: skip -->
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+import { propagation, context } from "@opentelemetry/api";
+
+const client = new CopilotClient({
+  telemetry: { otlpEndpoint: "http://localhost:4318" },
+  onGetTraceContext: () => {
+    const carrier: Record<string, string> = {};
+    propagation.inject(context.active(), carrier);
+    return carrier; // { traceparent: "00-...", tracestate: "..." }
+  },
+});
+```
+
+For **Python**, **Go**, and **.NET**, trace context injection is automatic when the respective OpenTelemetry/Activity API is configured — no callback is needed.
+
+#### CLI → SDK (inbound)
+
+When the CLI invokes a tool handler, the `traceparent` and `tracestate` from the CLI's span are available in all languages:
+
+- **Go**: The `ToolInvocation.TraceContext` field is a `context.Context` with the trace already restored — use it directly as the parent for your spans.
+- **Python**: Trace context is automatically restored around the handler via `trace_context()` — child spans are parented to the CLI's span automatically.
+- **.NET**: Trace context is automatically restored via `RestoreTraceContext()` — child `Activity` instances are parented to the CLI's span automatically.
+- **Node.js**: Since the SDK has no OpenTelemetry dependency, `traceparent` and `tracestate` are passed as raw strings on the `ToolInvocation` object. Restore the context manually if needed:
+
+<!-- docs-validate: skip -->
+```typescript
+import { propagation, context, trace } from "@opentelemetry/api";
+
+session.registerTool(myTool, async (args, invocation) => {
+  // Restore the CLI's trace context as the active context
+  const carrier = {
+    traceparent: invocation.traceparent,
+    tracestate: invocation.tracestate,
+  };
+  const parentCtx = propagation.extract(context.active(), carrier);
+
+  // Create a child span under the CLI's span
+  const tracer = trace.getTracer("my-app");
+  return context.with(parentCtx, () =>
+    tracer.startActiveSpan("my-tool", async (span) => {
+      try {
+        const result = await doWork(args);
+        return result;
+      } finally {
+        span.end();
+      }
+    })
+  );
+});
+```
 
 ### Per-Language Dependencies
 
 | Language | Dependency | Notes |
 |---|---|---|
-| Node.js | `@opentelemetry/api` | Optional peer dependency |
+| Node.js | — | No dependency; provide `onGetTraceContext` callback for outbound propagation |
 | Python | `opentelemetry-api` | Install with `pip install copilot-sdk[telemetry]` |
 | Go | `go.opentelemetry.io/otel` | Required dependency |
 | .NET | — | Uses built-in `System.Diagnostics.Activity` |

nodejs/README.md

@@ -85,6 +85,7 @@ new CopilotClient(options?: CopilotClientOptions)
 - `githubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `githubToken` is provided). Cannot be used with `cliUrl`.
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the CLI process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
+- `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the CLI's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
 
 #### Methods
 
@@ -604,7 +605,7 @@ const session = await client.createSession({
 
 ## Telemetry
 
-The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export and automatic W3C Trace Context propagation.
+The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export from the CLI process — this is all most users need:
 
 ```typescript
 const client = new CopilotClient({
@@ -614,6 +615,8 @@ const client = new CopilotClient({
 });
 ```
 
+With just this configuration, the CLI emits spans for every session, message, and tool call to your collector. No additional dependencies or setup required.
+
 **TelemetryConfig options:**
 
 - `otlpEndpoint?: string` - OTLP HTTP endpoint URL
@@ -622,9 +625,28 @@ const client = new CopilotClient({
 - `sourceName?: string` - Instrumentation scope name
 - `captureContent?: boolean` - Whether to capture message content
 
-Trace context (`traceparent`/`tracestate`) is automatically propagated between the SDK and CLI on `session.create`, `session.resume`, and `session.send` calls, and inbound when the CLI invokes tool handlers.
+### Advanced: Trace Context Propagation
+
+> **You don't need this for normal telemetry collection.** The `telemetry` config above is sufficient to get full traces from the CLI.
+
+`onGetTraceContext` is only needed if your application creates its own OpenTelemetry spans and you want them to appear in the **same distributed trace** as the CLI's spans — for example, to nest a "handle tool call" span inside the CLI's "execute tool" span, or to show the SDK call as a child of your application's request-handling span.
+
+If you're already using `@opentelemetry/api` in your app and want this linkage, provide a callback:
+
+```typescript
+import { propagation, context } from "@opentelemetry/api";
+
+const client = new CopilotClient({
+  telemetry: { otlpEndpoint: "http://localhost:4318" },
+  onGetTraceContext: () => {
+    const carrier: Record<string, string> = {};
+    propagation.inject(context.active(), carrier);
+    return carrier;
+  },
+});
+```
 
-Optional peer dependency: `@opentelemetry/api`
+Inbound trace context from the CLI is available on the `ToolInvocation` object passed to tool handlers as `traceparent` and `tracestate` fields. See the [OpenTelemetry guide](../docs/observability/opentelemetry.md) for a full wire-up example.
 
 ## User Input Requests
 

nodejs/package-lock.json

@@ -49,7 +49,6 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@opentelemetry/api": "^1.9.0",
     "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
@@ -69,14 +68,6 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "peerDependencies": {
-    "@opentelemetry/api": "^1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@opentelemetry/api": {
-      "optional": true
-    }
-  },
   "files": [
     "dist/**/*",
     "docs/**/*",

nodejs/package.json

@@ -26,7 +26,7 @@ import {
 import { createServerRpc } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
-import { getTraceContext, withTraceContext } from "./telemetry.js";
+import { getTraceContext } from "./telemetry.js";
 import type {
     ConnectionState,
     CopilotClientOptions,
@@ -48,6 +48,7 @@ import type {
     ToolCallRequestPayload,
     ToolCallResponsePayload,
     ToolResultObject,
+    TraceContextProvider,
     TypedSessionLifecycleHandler,
 } from "./types.js";
 
@@ -145,7 +146,13 @@ export class CopilotClient {
     private options: Required<
         Omit<
             CopilotClientOptions,
-            "cliPath" | "cliUrl" | "githubToken" | "useLoggedInUser" | "onListModels" | "telemetry"
+            | "cliPath"
+            | "cliUrl"
+            | "githubToken"
+            | "useLoggedInUser"
+            | "onListModels"
+            | "telemetry"
+            | "onGetTraceContext"
         >
     > & {
         cliPath?: string;
@@ -157,6 +164,7 @@ export class CopilotClient {
     private isExternalServer: boolean = false;
     private forceStopping: boolean = false;
     private onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
+    private onGetTraceContext?: TraceContextProvider;
     private modelsCache: ModelInfo[] | null = null;
     private modelsCacheLock: Promise<void> = Promise.resolve();
     private sessionLifecycleHandlers: Set<SessionLifecycleHandler> = new Set();
@@ -235,6 +243,7 @@ export class CopilotClient {
         }
 
         this.onListModels = options.onListModels;
+        this.onGetTraceContext = options.onGetTraceContext;
 
         this.options = {
             cliPath: options.cliUrl ? undefined : options.cliPath || getBundledCliPath(),
@@ -560,7 +569,12 @@ export class CopilotClient {
 
         // Create and register the session before issuing the RPC so that
         // events emitted by the CLI (e.g. session.start) are not dropped.
-        const session = new CopilotSession(sessionId, this.connection!);
+        const session = new CopilotSession(
+            sessionId,
+            this.connection!,
+            undefined,
+            this.onGetTraceContext
+        );
         session.registerTools(config.tools);
         session.registerPermissionHandler(config.onPermissionRequest);
         if (config.onUserInputRequest) {
@@ -576,7 +590,7 @@ export class CopilotClient {
 
         try {
             const response = await this.connection!.sendRequest("session.create", {
-                ...(await getTraceContext()),
+                ...(await getTraceContext(this.onGetTraceContext)),
                 model: config.model,
                 sessionId,
                 clientName: config.clientName,
@@ -661,7 +675,12 @@ export class CopilotClient {
 
         // Create and register the session before issuing the RPC so that
         // events emitted by the CLI (e.g. session.start) are not dropped.
-        const session = new CopilotSession(sessionId, this.connection!);
+        const session = new CopilotSession(
+            sessionId,
+            this.connection!,
+            undefined,
+            this.onGetTraceContext
+        );
         session.registerTools(config.tools);
         session.registerPermissionHandler(config.onPermissionRequest);
         if (config.onUserInputRequest) {
@@ -677,7 +696,7 @@ export class CopilotClient {
 
         try {
             const response = await this.connection!.sendRequest("session.resume", {
-                ...(await getTraceContext()),
+                ...(await getTraceContext(this.onGetTraceContext)),
                 sessionId,
                 clientName: config.clientName,
                 model: config.model,
@@ -1586,17 +1605,17 @@ export class CopilotClient {
         }
 
         try {
+            const traceparent = (params as { traceparent?: string }).traceparent;
+            const tracestate = (params as { tracestate?: string }).tracestate;
             const invocation = {
                 sessionId: params.sessionId,
                 toolCallId: params.toolCallId,
                 toolName: params.toolName,
                 arguments: params.arguments,
+                traceparent,
+                tracestate,
             };
-            const traceparent = (params as { traceparent?: string }).traceparent;
-            const tracestate = (params as { tracestate?: string }).tracestate;
-            const result = await withTraceContext(traceparent, tracestate, () =>
-                handler(params.arguments, invocation)
-            );
+            const result = await handler(params.arguments, invocation);
             return { result: this.normalizeToolResultV2(result) };
         } catch (error) {
             const message = error instanceof Error ? error.message : String(error);

nodejs/src/client.ts

@@ -46,6 +46,8 @@ export type {
     SystemMessageConfig,
     SystemMessageReplaceConfig,
     TelemetryConfig,
+    TraceContext,
+    TraceContextProvider,
     Tool,
     ToolHandler,
     ToolInvocation,

nodejs/src/index.ts

@@ -10,7 +10,7 @@
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import { getTraceContext, withTraceContext } from "./telemetry.js";
+import { getTraceContext } from "./telemetry.js";
 import type {
     MessageOptions,
     PermissionHandler,
@@ -23,6 +23,7 @@ import type {
     SessionHooks,
     Tool,
     ToolHandler,
+    TraceContextProvider,
     TypedSessionEventHandler,
     UserInputHandler,
     UserInputRequest,
@@ -69,20 +70,25 @@ export class CopilotSession {
     private userInputHandler?: UserInputHandler;
     private hooks?: SessionHooks;
     private _rpc: ReturnType<typeof createSessionRpc> | null = null;
+    private traceContextProvider?: TraceContextProvider;
 
     /**
      * Creates a new CopilotSession instance.
      *
      * @param sessionId - The unique identifier for this session
      * @param connection - The JSON-RPC message connection to the Copilot CLI
      * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+     * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
      * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
      */
     constructor(
         public readonly sessionId: string,
         private connection: MessageConnection,
-        private _workspacePath?: string
-    ) {}
+        private _workspacePath?: string,
+        traceContextProvider?: TraceContextProvider
+    ) {
+        this.traceContextProvider = traceContextProvider;
+    }
 
     /**
      * Typed session-scoped RPC methods.
@@ -123,7 +129,7 @@ export class CopilotSession {
      */
     async send(options: MessageOptions): Promise<string> {
         const response = await this.connection.sendRequest("session.send", {
-            ...(await getTraceContext()),
+            ...(await getTraceContext(this.traceContextProvider)),
             sessionId: this.sessionId,
             prompt: options.prompt,
             attachments: options.attachments,
@@ -377,14 +383,14 @@ export class CopilotSession {
         tracestate?: string
     ): Promise<void> {
         try {
-            const rawResult = await withTraceContext(traceparent, tracestate, () =>
-                handler(args, {
-                    sessionId: this.sessionId,
-                    toolCallId,
-                    toolName,
-                    arguments: args,
-                })
-            );
+            const rawResult = await handler(args, {
+                sessionId: this.sessionId,
+                toolCallId,
+                toolName,
+                arguments: args,
+                traceparent,
+                tracestate,
+            });
             let result: string;
             if (rawResult == null) {
                 result = "";