[OTEL] Wire root request span

ts/docs/architecture/telemetry/opentelemetry.md

@@ -335,7 +335,8 @@ Ordinary `debug(...)` and `logger.logEvent(...)` calls do not change. Add a span
 for an externally meaningful or independently timed operation:
 
 ```ts
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { trace } from "@opentelemetry/api";
+import { otel } from "@typeagent/telemetry";
 
 const tracer = trace.getTracer("typeagent");
 
@@ -344,8 +345,10 @@ return tracer.startActiveSpan("typeagent.translate", async (span) => {
     span.setAttribute("typeagent.agent.name", agentName);
     return await translateRequest(request);
   } catch (error) {
-    span.recordException(error instanceof Error ? error : String(error));
-    span.setStatus({ code: SpanStatusCode.ERROR });
+    otel.recordTypeAgentSpanException(span, error, {
+      safeName: "TranslationError",
+      safeMessage: "translation failed",
+    });
     throw error;
   } finally {
     span.end();
@@ -357,6 +360,20 @@ return tracer.startActiveSpan("typeagent.translate", async (span) => {
 inside the callback receive its trace and span IDs. If code converts an exception
 to `ActionResult`, it must still record the exception and error status.
 
+Dispatcher request spans start a new trace by default. Embedded hosts can join
+the OTel context active when each request is submitted with a one-time option:
+
+```ts
+await createDispatcher(hostName, {
+  telemetry: { joinActiveTrace: true },
+});
+```
+
+Original exception messages and stacks are omitted because they can contain user
+content. A host may explicitly opt into redacted details with
+`telemetry.captureSensitiveErrorDetails`, but this remains sensitive diagnostic
+capture even after known secrets are removed.
+
 | Signal          | Use                                          |
 | --------------- | -------------------------------------------- |
 | Span attributes | Stable facts such as agent, action, or model |

ts/packages/dispatcher/dispatcher/package.json

@@ -49,6 +49,7 @@
     "@azure/identity": "^4.10.0",
     "@github/copilot-sdk": "1.0.5",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@opentelemetry/api": "1.9.0",
     "@typeagent/action-grammar": "workspace:*",
     "@typeagent/action-schema": "workspace:*",
     "@typeagent/agent-cache": "workspace:*",

ts/packages/dispatcher/dispatcher/src/command/command.ts

@@ -11,6 +11,14 @@ import {
     getRequestId,
     requestIdToString,
 } from "../context/commandHandlerContext.js";
+import {
+    context as otelContext,
+    trace,
+    type Context,
+} from "@opentelemetry/api";
+import { otel } from "@typeagent/telemetry";
+import { wrapRootRequestSpan } from "../otel/rootRequestSpan.js";
+import { getSessionName } from "../context/session.js";
 
 import {
     CommandDescriptor,
@@ -356,6 +364,23 @@ export async function processCommandNoLock(
         if (e.name === "AbortError" || context.currentAbortSignal?.aborted) {
             throw new DOMException("The operation was aborted.", "AbortError");
         }
+        // Record the exception on the active `typeagent.request` span
+        // *before* processCommandNoLock swallows it. The design doc rule
+        // (opentelemetry.md, "Developer Usage") is explicit: "If code
+        // converts an exception to `ActionResult`, it must still record
+        // the exception and error status." The catch below converts the
+        // thrown error into a user-visible display message + logged event,
+        // not a re-throw; without this recordException/setStatus pair the
+        // root span would silently end with status UNSET on real failures.
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan !== undefined) {
+            otel.recordTypeAgentSpanException(activeSpan, e, {
+                safeName: "CommandError",
+                safeMessage: "command failed",
+                captureSensitiveDetails:
+                    context.telemetryOptions.captureSensitiveErrorDetails,
+            });
+        }
         context.clientIO.appendDisplay(
             makeClientIOMessage(
                 context,
@@ -442,6 +467,7 @@ export async function processCommand(
     requestId: RequestId,
     attachments?: string[],
     options?: ProcessCommandOptions,
+    parentContext?: Context,
 ): Promise<CommandResult | undefined> {
     // Create the AbortController *before* acquiring the lock so that a
     // cancelCommandByClientId() call that arrives while we are queued can
@@ -453,38 +479,101 @@ export async function processCommand(
             abortController,
         );
     }
-    try {
-        // Process one command at a time.
-        return await context.commandLock(async () => {
-            const requestIdStr = requestId.requestId;
-            context.activeRequests.set(requestIdStr, abortController);
-            context.currentOptions = options;
-            beginProcessCommand(
-                requestId,
-                context,
-                options,
-                abortController.signal,
-            );
-            context.clientIO.setUserRequest(requestId, originalInput);
+    // Compute the correlation attributes ONCE, before opening the root
+    // `typeagent.request` span. Values that only become known later
+    // (agent name, action name) are set on the active span by downstream
+    // steps in later phases; the root span carries only the values known
+    // at the outermost async boundary. Everything the wrapper receives is
+    // an identifier, not user text - see setTypeAgentSpanAttributes.
+    const sessionId = context.session.sessionDirPath
+        ? getSessionName(context.session.sessionDirPath)
+        : undefined;
+    const rootAttributes: {
+        -readonly [K in keyof otel.TypeAgentSpanAttributes]: otel.TypeAgentSpanAttributes[K];
+    } = {};
+    if (sessionId !== undefined) rootAttributes.sessionId = sessionId;
+    if (context.activationId !== undefined)
+        rootAttributes.activationId = context.activationId;
+    if (context.traceId !== undefined) rootAttributes.traceId = context.traceId;
+    // wrapRootRequestSpan opens `typeagent.request` and applies the
+    // correlation attributes; the callback body preserves the original
+    // command flow. startActiveSpan uses AsyncHooks context propagation
+    // so every downstream await (commandLock, processCommandNoLock,
+    // translation/reasoning/action) automatically nests under this span.
+    const rootParentContext =
+        parentContext ??
+        (context.telemetryOptions.joinActiveTrace
+            ? otelContext.active()
+            : undefined);
+    return await wrapRootRequestSpan(
+        rootAttributes,
+        async () => {
             try {
-                await processCommandNoLock(originalInput, context, attachments);
-            } catch (e: any) {
-                if (e.name === "AbortError") {
-                    ensureCommandResult(context).cancelled = true;
-                } else {
-                    throw e;
-                }
+                // Process one command at a time.
+                return await context.commandLock(async () => {
+                    const requestIdStr = requestId.requestId;
+                    context.activeRequests.set(requestIdStr, abortController);
+                    context.currentOptions = options;
+                    beginProcessCommand(
+                        requestId,
+                        context,
+                        options,
+                        abortController.signal,
+                    );
+                    context.clientIO.setUserRequest(requestId, originalInput);
+                    try {
+                        await processCommandNoLock(
+                            originalInput,
+                            context,
+                            attachments,
+                        );
+                    } catch (e: any) {
+                        if (e.name === "AbortError") {
+                            // Design rule: exceptions converted to ActionResult
+                            // must still be recorded on the active span. Do it
+                            // here (inside the wrapper's context) so the
+                            // exception event lands on `typeagent.request`.
+                            // The wrapper separately sets ERROR status with
+                            // message "cancelled" when it sees cancelled=true.
+                            const activeSpan = trace.getActiveSpan();
+                            if (activeSpan !== undefined) {
+                                otel.recordTypeAgentSpanException(
+                                    activeSpan,
+                                    e,
+                                    {
+                                        safeName: "AbortError",
+                                        safeMessage: "cancelled",
+                                        captureSensitiveDetails:
+                                            context.telemetryOptions
+                                                .captureSensitiveErrorDetails,
+                                    },
+                                );
+                            }
+                            ensureCommandResult(context).cancelled = true;
+                        } else {
+                            throw e;
+                        }
+                    } finally {
+                        context.activeRequests.delete(requestIdStr);
+                        context.currentOptions = undefined;
+                        // eslint-disable-next-line no-unsafe-finally
+                        return endProcessCommand(requestId, context);
+                    }
+                });
             } finally {
-                context.activeRequests.delete(requestIdStr);
-                context.currentOptions = undefined;
-                return endProcessCommand(requestId, context);
+                if (requestId.clientRequestId !== undefined) {
+                    context.activeRequestsByClientId.delete(
+                        requestId.clientRequestId,
+                    );
+                }
             }
-        });
-    } finally {
-        if (requestId.clientRequestId !== undefined) {
-            context.activeRequestsByClientId.delete(requestId.clientRequestId);
-        }
-    }
+        },
+        {
+            parentContext: rootParentContext,
+            captureSensitiveErrorDetails:
+                context.telemetryOptions.captureSensitiveErrorDetails,
+        },
+    );
 }
 
 export const enum unicodeChar {

ts/packages/dispatcher/dispatcher/src/context/commandHandlerContext.ts

@@ -393,6 +393,22 @@ export type CommandHandlerContext = {
     persistedGrammarStore?: PersistedGrammarStore; // Persistence layer for dynamic grammar rules
     currentScriptDir: string;
     logger?: Logger | undefined;
+    /**
+     * Dispatcher activation id (created once per context, not per request).
+     * Mirrors what the logger stamps on events and is the correlation value
+     * used for the `typeagent.activation.id` OTel span attribute.
+     */
+    readonly activationId: string;
+    /**
+     * Preserved caller-supplied pre-OTel trace id. OTel owns the canonical
+     * trace id; this value is carried on spans and logs as
+     * `typeagent.trace.id` so existing logs can still be joined.
+     */
+    readonly traceId: string | undefined;
+    readonly telemetryOptions: {
+        readonly joinActiveTrace: boolean;
+        readonly captureSensitiveErrorDetails: boolean;
+    };
     currentRequestId: RequestId | undefined;
     currentAbortSignal: AbortSignal | undefined;
     currentOptions?: ProcessCommandOptions | undefined;
@@ -534,6 +550,7 @@ async function getAgentCache(
  * - collectCommandResult: whether to collect command result in the return for `processCommand`. Default is false.
  * - dblogging: whether to enable database telemetry logging. Default is true; pass false to opt out.
  * - traceId: An optional trace ID to use for logging identification.
+ * - telemetry: OpenTelemetry request-span integration options.
  */
 export type DispatcherOptions = DeepPartialUndefined<DispatcherConfig> & {
     // Core options
@@ -577,6 +594,18 @@ export type DispatcherOptions = DeepPartialUndefined<DispatcherConfig> & {
     collectCommandResult?: boolean; // default to false
     dblogging?: boolean; // default to true
     traceId?: string; // optional additional for logging identification
+    telemetry?: {
+        /**
+         * Join the OTel context active when each request is submitted.
+         * Default false: each request starts a new trace.
+         */
+        joinActiveTrace?: boolean;
+        /**
+         * Export redacted original exception messages and stacks. These can
+         * still contain user content, so this is disabled by default.
+         */
+        captureSensitiveErrorDetails?: boolean;
+    };
 
     // Additional integration options
     constructionProvider?: ConstructionProvider;
@@ -1184,14 +1213,16 @@ export async function initializeCommandHandlerContext(
         debug(`Session directory: ${sessionDirPath}`);
         const clientIO = options?.clientIO ?? nullClientIO;
         const loggerSink = getLoggerSink(() => context.dblogging, clientIO);
+        const activationId = randomUUID();
+        const traceId = options?.traceId;
         const logger = new ChildLogger(loggerSink, DispatcherName, {
             hostName,
-            traceId: options?.traceId,
+            traceId,
             sessionId: () =>
                 context.session.sessionDirPath
                     ? getSessionName(context.session.sessionDirPath)
                     : undefined,
-            activationId: randomUUID(),
+            activationId,
         });
 
         const cacheDir = persistDir ? ensureCacheDir(persistDir) : undefined;
@@ -1276,6 +1307,13 @@ export async function initializeCommandHandlerContext(
             ),
             displayLog: await DisplayLog.load(persistDir),
             logger,
+            activationId,
+            traceId,
+            telemetryOptions: {
+                joinActiveTrace: options?.telemetry?.joinActiveTrace ?? false,
+                captureSensitiveErrorDetails:
+                    options?.telemetry?.captureSensitiveErrorDetails ?? false,
+            },
             metricsManager: metrics ? new RequestMetricsManager() : undefined,
             promptLogger,
             devTrace,
@@ -1344,6 +1382,7 @@ export async function initializeCommandHandlerContext(
                     reqId,
                     qctx.attachments,
                     qctx.options,
+                    qctx.traceContext,
                 );
                 try {
                     context.displayLog.logCommandResult(

ts/packages/dispatcher/dispatcher/src/dispatcher.ts

@@ -34,6 +34,7 @@ import {
     initializeCommandHandlerContext,
 } from "./context/commandHandlerContext.js";
 import { randomUUID } from "node:crypto";
+import { context as otelContext } from "@opentelemetry/api";
 import { getAgentSchemas } from "./context/system/describe/agentSchemaInfo.js";
 
 async function getDynamicDisplay(
@@ -216,6 +217,9 @@ export function createDispatcherFromContext(
         if (attachments != null) input.attachments = attachments;
         if (options != null) input.options = options;
         if (requestId !== undefined) input.requestId = requestId;
+        if (context.telemetryOptions.joinActiveTrace) {
+            input.traceContext = otelContext.active();
+        }
         return input;
     };