feat: add OpenTelemetry distributed tracing (enterprise) (#232)

* feat(tracing): add OpenTelemetry dependencies and --import preload flag

* feat(enterprise): add distributed_tracing feature gate

* feat(tracing): add SDK bootstrap with enterprise gating

* fix(tracing): correct test coverage for enterprise-unavailable path and prevent double-init

Test 2 now mocks @snapotter/enterprise to throw an import error, exercising
the catch block in the preload. Test 3 imports with no endpoint so the preload
is a no-op, avoiding leaked SDK from double-initialization. Added idempotency
guard to initTracing() as a safety net.

* feat(tracing): add Pino trace mixin and shared logger

When OTel tracing is active, every Pino log line now includes traceId,
spanId, and traceFlags fields for log-to-trace correlation. The mixin
is a no-op when no SDK is registered (community users).

* feat(tracing): add _otel to ToolJobData and inject trace context at enqueue

Add optional _otel carrier field to ToolJobData for W3C trace context
propagation across BullMQ job boundaries. When an active OTel span exists,
propagation.inject() writes traceparent/tracestate into the job data before
queue.add(). When no SDK is registered (community edition), the carrier
stays empty and _otel remains undefined -- zero overhead.

* feat(tracing): extract trace context and create spans in BullMQ worker

* feat(tracing): inject trace context into Python sidecar calls

* feat(tracing): add trace context extraction to Python sidecar

* feat(tracing): add shutdownTracing to graceful shutdown sequence

* feat(tracing): enrich HTTP spans with tool_id and user_id attributes

* docs: add OpenTelemetry env var documentation to .env.example

* test(tracing): add lifecycle integration tests for trace propagation

* fix(tracing): inject trace context into pipeline and batch flow jobs

* fix(tracing): add sidecar.execute Node-side span and remove unnecessary comment

Wraps PythonDispatcher.run() with a sidecar.execute span on the Node
side so traces show the full round-trip (Node span -> Python span).
Also removes an obvious comment from logger.ts.

tests/unit/api/log-trace-mixin.test.ts

@@ -0,0 +1,84 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  type Context,
+  type ContextManager,
+  context,
+  ROOT_CONTEXT,
+  trace,
+} from "@opentelemetry/api";
+import { afterEach, describe, expect, it } from "vitest";
+import { traceMixin } from "../../../apps/api/src/lib/log-trace-mixin.js";
+
+/**
+ * Minimal AsyncLocalStorage-based context manager for tests.
+ * OTel v2 BasicTracerProvider no longer registers one automatically.
+ */
+class TestContextManager implements ContextManager {
+  private _als = new AsyncLocalStorage<Context>();
+
+  active(): Context {
+    return this._als.getStore() ?? ROOT_CONTEXT;
+  }
+
+  with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
+    ctx: Context,
+    fn: F,
+    thisArg?: ThisParameterType<F>,
+    ...args: A
+  ): ReturnType<F> {
+    return this._als.run(ctx, () => fn.call(thisArg, ...args));
+  }
+
+  bind<T>(_ctx: Context, target: T): T {
+    return target;
+  }
+
+  enable(): this {
+    return this;
+  }
+
+  disable(): this {
+    this._als.disable();
+    return this;
+  }
+}
+
+describe("traceMixin", () => {
+  afterEach(() => {
+    context.disable();
+    trace.disable();
+  });
+
+  it("returns empty object when no span is active", () => {
+    const result = traceMixin();
+    expect(result).toEqual({});
+  });
+
+  it("returns traceId, spanId, traceFlags when span is active", async () => {
+    const { InMemorySpanExporter, SimpleSpanProcessor, BasicTracerProvider } = await import(
+      "@opentelemetry/sdk-trace-base"
+    );
+
+    // Register a real context manager so context.with() propagates
+    context.setGlobalContextManager(new TestContextManager());
+
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = trace.getTracer("test");
+    const span = tracer.startSpan("test-span");
+    const ctx = trace.setSpan(ROOT_CONTEXT, span);
+
+    const result = context.with(ctx, () => traceMixin());
+
+    expect(result.traceId).toBe(span.spanContext().traceId);
+    expect(result.spanId).toBe(span.spanContext().spanId);
+    expect(result.traceFlags).toBe(span.spanContext().traceFlags);
+
+    span.end();
+    await provider.shutdown();
+  });
+});