From 4c1d3b822fdfb571a84e433db13d3b5d6c7e4f95 Mon Sep 17 00:00:00 2001
From: examon <examon@users.noreply.github.com>
Date: Sun, 2 Aug 2026 16:43:44 +0000
Subject: [PATCH] docs: fix the Node.js inbound trace-context example to use a
 real tool-registration API

The Node.js example in the "CLI -> SDK (inbound)" section of
docs/observability/opentelemetry.md registered a tool by calling
session.registerTool(myTool, handler). That method is not part of the public
CopilotSession API, so copying the example fails to compile with

  error TS2339: Property 'registerTool' does not exist on type 'CopilotSession'

and, if the types are bypassed, throws
"TypeError: session.registerTool is not a function" at runtime. The plural
registerTools() is marked @internal and stripped from the shipped declarations,
so there is no public session method to register a tool with after the session
exists.

Move the trace-restoring handler into defineTool() and register the tool through
client.createSession({ tools: [myTool] }), which is the public registration path
and the one used by the rest of the documentation. The trace-context logic is
unchanged; only the registration mechanism is corrected. As a side effect the
handler's args and invocation parameters are now contextually typed, so the
invocation.traceparent / invocation.tracestate access in the example is actually
type-checked.
---
 docs/observability/opentelemetry.md | 47 +++++++++++++++++------------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/docs/observability/opentelemetry.md b/docs/observability/opentelemetry.md
index ad86145e40..b3932ce66a 100644
--- a/docs/observability/opentelemetry.md
+++ b/docs/observability/opentelemetry.md
@@ -152,29 +152,36 @@ When the CLI invokes a tool handler, the `traceparent` and `tracestate` from the
 
 <!-- docs-validate: skip -->
 ```typescript
+import { defineTool } from "@github/copilot-sdk";
 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();
-      }
-    })
-  );
+const myTool = defineTool("my-tool", {
+  description: "Do work",
+  handler: 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();
+        }
+      })
+    );
+  },
 });
+
+// Tool handlers are registered when the session is created.
+const session = await client.createSession({ tools: [myTool] });
 ```
 
 ### Per-language dependencies