docs: fix the Node.js inbound trace-context example to use a real tool-registration API

[examon]

Fixes #2222

Problem

The Node.js example in the CLI -> SDK (inbound) part 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 the documented snippet does not compile:

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

and throws TypeError: session.registerTool is not a function if the types are bypassed. The plural
registerTools() is @internal and removed from the shipped declarations by stripInternal: true,
so there is no public session method to swap in - the registration step has to be restructured.

The example's trace-restoration logic was always correct: ToolInvocation.traceparent and
.tracestate are public and are delivered to the handler. Only the registration mechanism was wrong.

Fix

Move the trace-restoring handler into defineTool() and register the tool through
client.createSession({ tools: [myTool] }), the public registration path already used by the rest of
the documentation. Every part of the trace-context logic is carried over unchanged:
propagation.extract(context.active(), carrier), trace.getTracer("my-app"),
context.with(parentCtx, ...), tracer.startActiveSpan("my-tool", ...) and span.end() in a
finally.

One file changes, and only the one fenced block inside it. No API, no behaviour, and no other
documentation is touched.

The <!-- docs-validate: skip --> marker on the block is deliberately kept: scripts/docs-validation
has no @opentelemetry/api dependency, so unskipping the block would make it fail on the missing
third-party import rather than validate anything about the SDK.

Verification

Reproducer, against the published package so it does not depend on this branch:

printf '{"name":"repro","version":"0.0.0","private":true,"type":"module"}\n' > package.json
npm install @github/copilot-sdk@1.0.8 typescript@5.9.3 @opentelemetry/api@1.9.1

Before - the old snippet, with only the scaffolding the surrounding docs supply out-of-band
(session, myTool, doWork):

$ npx tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --skipLibCheck before.ts
before.ts(7,9): error TS2339: Property 'registerTool' does not exist on type 'CopilotSession'.
before.ts(7,37): error TS7006: Parameter 'args' implicitly has an 'any' type.
before.ts(7,43): error TS7006: Parameter 'invocation' implicitly has an 'any' type.
$ echo $?
2

After - the new snippet extracted from the updated doc, with client and doWork declared:

$ npx tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --skipLibCheck after.ts
$ echo $?
0

Both results hold against the published @github/copilot-sdk@1.0.8 and against a local build of this
branch, and under both TypeScript 5.9.3 and 7.0.2. The two TS7006 errors disappear with the fix
because args and invocation become contextually typed, so the example's
invocation.traceparent / .tracestate access is now genuinely type-checked.

Runtime confirmation that the old call could never have worked:

$ node --input-type=module -e 'import { CopilotSession } from "@github/copilot-sdk";
  const p = CopilotSession.prototype;
  console.log("registerTool: ", typeof p.registerTool);
  console.log("registerTools:", typeof p.registerTools);'
registerTool:  undefined
registerTools: function

I also confirmed the corrected path really does deliver the trace context, so the section still does
what it promises: createSession() passes config.tools to the session, the session stores each
tool's handler by name, and the handler is invoked with a ToolInvocation carrying traceparent and
tracestate from the incoming request.

scripts/docs-validation was run before and after; its extracted-block manifest is identical, which
confirms no collateral damage (it skips this block by design, so it is a regression check, not proof
of the fix - the compile above is the proof).

Out of scope

The feature table in docs/troubleshooting/compatibility.md lists two methods that are absent from
the shipped declarations: registerTools() at line 35 and destroy() at line 19, both under the
"Available in SDK" heading. Line 35 is not the only stale cell there, so correcting just it in an
OpenTelemetry docs fix would be arbitrary. That table looks like its own small pass, so I left it
alone.

[Copilot]

🟢 Ready to approve

The example now uses verified public APIs while preserving the trace-restoration logic.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Fixes #2222 by replacing a nonexistent session API with the public Node.js tool-registration flow.

Changes:

• Defines the traced handler with defineTool().
• Registers the tool through client.createSession().

File summaries

File	Description
docs/observability/opentelemetry.md	Corrects the inbound trace-context example.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.