pi-telemetry-otel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# pi OTEL Telemetry Extension
+
+Emits OpenTelemetry spans for pi agent lifecycle + tool usage to an OTLP/HTTP collector (Jaeger).
+
+## Install / enable
+
+Install as a **pi package** (recommended):
+
+```bash
+# Global install (writes ~/.pi/agent/settings.json)
+pi install npm:pi-telemetry-otel
+
+# Project-local install (writes .pi/settings.json)
+pi install -l npm:pi-telemetry-otel
+```
+
+Try without installing:
+
+```bash
+pi -e npm:pi-telemetry-otel "List files"
+```
+
+Pi loads the extension from the package’s `pi.extensions` manifest automatically once installed (unless disabled via `pi config`).
+
+## Configuration
+
+All settings accept `PI_` overrides (e.g. `PI_OTEL_SERVICE_NAME`) and fall back to standard OTEL env vars.
+
+| Env var                       | Default                           | Purpose                                                                                         |
+| ----------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` | OTLP/HTTP endpoint                                                                              |
+| `OTEL_EXPORTER_OTLP_HEADERS`  | _(none)_                          | Comma-separated `k=v` headers                                                                   |
+| `OTEL_SERVICE_NAME`           | `pi-agent`                        | Service name in Jaeger (defaults to agent name from `PI_AGENT_CHAIN` if present)                |
+| `OTEL_RESOURCE_ATTRIBUTES`    | _(none)_                          | Comma-separated `k=v` attributes                                                                |
+| `PI_AGENT_TRACE_ID`           | _(generated)_                     | Parent trace ID to reuse; set once and kept for subprocess trace linking                        |
+| `PI_AGENT_SPAN_ID`            | _(generated)_                     | Parent span ID for subprocess linking; updated to current active span (session/agent/turn/tool) |
+
+## Extension interoperability (child spans)
+
+Other pi extensions can attach spans to the *current* pi trace.
+
+### Recommended: use the helper APIs
+
+```ts
+import { withPiSpan } from "pi-telemetry-otel/helpers";
+
+pi.on("tool_call", async (_event, ctx) => {
+  await withPiSpan(ctx, "myext.do_work", async (span) => {
+    span?.setAttribute("myext.foo", "bar");
+    // ... your work
+  });
+});
+```
+
+The helper functions:
+- reuse the tracer/export pipeline registered by this extension
+- parent spans under the **active** pi span (session/agent/turn/tool)
+- prefer a per-session context registry (avoids env-var races in concurrent in-process sub-sessions)
+
+### Advanced: global registries (no hard dependency)
+
+If you don’t want to depend on the package, you can read the registries directly:
+
+- Runtime registry symbol: `Symbol.for("pi.telemetry-otel.runtimeRegistry.v1")`
+- Active span context registry symbol: `Symbol.for("pi.telemetry-otel.activeSpanContextRegistry.v1")`
+- Map key: `ctx.sessionManager.getSessionId()`
+
+(See `flow-machine` for a reference integration that emits `pi.flow.*` spans.)
+
+## Open the current trace
+
+Use `/open-jaeger-trace` to show the current trace URL and optionally open it in your browser.
+If Tailscale is available, the command also surfaces a Tailscale IP URL for remote access.
+
+## Jaeger smoke check
+
+```bash
+# Run pi (interactive preferred so spans flush)
+PI_OTEL_SERVICE_NAME=pi-agent-dev pi
+
+# Query traces
+curl -sSf "http://localhost:16686/api/traces?service=pi-agent-dev&limit=5" | jq -r '.data[].traceID'
+curl -sSf "http://localhost:16686/api/traces/<trace-id>" | jq -r '.data[0].spans[].operationName'
+```
+
+Expected operations: `pi.session`, `pi.agent`, `pi.turn`, `pi.tool: <tool-name>` (bash adds command preview).
+
+## Tests
+
+```bash
+cd telemetry-otel
+bun install
+bun test
+```

package/extensions/index.ts

@@ -0,0 +1,792 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { type Attributes, type Span, SpanStatusCode, type Tracer, context, trace } from "@opentelemetry/api";
+import { registerTelemetryRuntime, unregisterTelemetryRuntime } from "./runtime-registry";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { clearActiveSpanContext, setActiveSpanContext } from "./span-context-registry";
+import { getCurrentAgentName } from "../lib/agent-chain";
+import {
+  TraceEnvStack,
+  isValidTraceId,
+  readParentSpanContext,
+  readParentSpanContextFromEntries,
+  readServiceNameFromEntries,
+} from "../lib/trace-env";
+
+function invariant(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+const DEFAULT_ENDPOINT = "http://localhost:4318/v1/traces";
+const DEFAULT_SERVICE_NAME = "pi-agent";
+const PAYLOAD_MAX_BYTES = 8 * 1024;
+const INPUT_PREVIEW_MAX_CHARS = 50;
+const TOOL_COMMAND_PREVIEW_MAX_CHARS = 120;
+const INPUT_LAST_SENTENCE_MAX_CHARS = 70;
+const REDACTION_PATTERN = /api_key|token|secret|password/i;
+const DEFAULT_JAEGER_TRACE_URL = "http://localhost:16686/trace";
+
+interface TelemetryConfig {
+  endpoint: string;
+  headers: Record<string, string>;
+  serviceName: string;
+  resourceAttributes: Record<string, string>;
+}
+
+export interface TelemetryRuntime {
+  tracer: Tracer;
+  shutdown: () => Promise<void>;
+}
+
+export interface TelemetryOptions {
+  runtime?: TelemetryRuntime;
+  now?: () => number;
+}
+
+interface SpanRegistry {
+  session?: Span;
+  agent?: Span;
+  turns: Map<number, Span>;
+  tools: Map<string, Span>;
+}
+
+interface InputSummary {
+  preview: string;
+  previewBytes: number;
+  previewTruncated: boolean;
+  firstSentence?: string;
+  firstSentenceTruncated?: boolean;
+  lastSentence?: string;
+  lastSentenceTruncated?: boolean;
+}
+
+function getEnvValue(key: string): string | undefined {
+  return process.env[`PI_${key}`] ?? process.env[key];
+}
+
+function parseKeyValuePairs(raw: string | undefined): Record<string, string> {
+  if (!raw) return {};
+  return raw
+    .split(",")
+    .map((pair) => pair.trim())
+    .filter(Boolean)
+    .reduce<Record<string, string>>((acc, pair) => {
+      const [key, ...rest] = pair.split("=");
+      if (!key || rest.length === 0) return acc;
+      acc[key.trim()] = rest.join("=").trim();
+      return acc;
+    }, {});
+}
+
+export function resolveServiceName(): string {
+  const explicitServiceName = getEnvValue("OTEL_SERVICE_NAME");
+  if (explicitServiceName) return explicitServiceName;
+
+  const agentName = getCurrentAgentName();
+  if (agentName) return agentName;
+
+  return DEFAULT_SERVICE_NAME;
+}
+
+function loadConfig(): TelemetryConfig {
+  const endpoint = getEnvValue("OTEL_EXPORTER_OTLP_ENDPOINT") ?? DEFAULT_ENDPOINT;
+  const headers = parseKeyValuePairs(getEnvValue("OTEL_EXPORTER_OTLP_HEADERS"));
+  const serviceName = resolveServiceName();
+  const resourceAttributes = parseKeyValuePairs(getEnvValue("OTEL_RESOURCE_ATTRIBUTES"));
+
+  return {
+    endpoint,
+    headers,
+    serviceName,
+    resourceAttributes,
+  };
+}
+
+function buildJaegerTraceUrl(traceId: string): string {
+  return `${DEFAULT_JAEGER_TRACE_URL}/${traceId}`;
+}
+
+function getOpenUrlCommand(url: string): { command: string; args: string[] } {
+  switch (process.platform) {
+    case "darwin":
+      return { command: "open", args: [url] };
+    case "win32":
+      return { command: "cmd", args: ["/c", "start", "", url] };
+    default:
+      return { command: "xdg-open", args: [url] };
+  }
+}
+
+async function getTailscaleIp(pi: ExtensionAPI): Promise<string | undefined> {
+  try {
+    const { stdout, code } = await pi.exec("tailscale", ["status", "--json"], {});
+    if (code !== 0) return undefined;
+
+    const data = JSON.parse(stdout) as { Self?: { TailscaleIPs?: unknown[] } };
+    const ips = data.Self?.TailscaleIPs ?? [];
+    const first = ips.find((ip) => typeof ip === "string");
+    return typeof first === "string" ? first : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function buildTraceUrls(pi: ExtensionAPI, traceId: string): Promise<{ primary: string; tailscale?: string }> {
+  const primary = buildJaegerTraceUrl(traceId);
+  const tailscaleIp = await getTailscaleIp(pi);
+
+  if (!tailscaleIp) {
+    return { primary };
+  }
+
+  return {
+    primary,
+    tailscale: `http://${tailscaleIp}:16686/trace/${traceId}`,
+  };
+}
+
+function redactPayload(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactPayload(item));
+  }
+
+  if (value && typeof value === "object") {
+    const output: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      if (REDACTION_PATTERN.test(key)) {
+        output[key] = "[redacted]";
+      } else {
+        output[key] = redactPayload(entry);
+      }
+    }
+    return output;
+  }
+
+  return value;
+}
+
+function serializePayload(value: unknown): { text: string; bytes: number; truncated: boolean } {
+  const safe = redactPayload(value);
+  const text = JSON.stringify(safe) ?? "null";
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= PAYLOAD_MAX_BYTES) {
+    return { text, bytes, truncated: false };
+  }
+
+  const truncatedText = text.slice(0, PAYLOAD_MAX_BYTES);
+  return { text: truncatedText, bytes, truncated: true };
+}
+
+function buildPayloadAttributes(prefix: string, value: unknown): Attributes {
+  const payload = serializePayload(value);
+  return {
+    [`${prefix}`]: payload.text,
+    [`${prefix}.bytes`]: payload.bytes,
+    [`${prefix}.truncated`]: payload.truncated,
+  };
+}
+
+function normalizeText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function trimTextByWord(value: string, maxChars: number): { text: string; truncated: boolean } {
+  if (value.length <= maxChars) {
+    return { text: value, truncated: false };
+  }
+
+  const words = value.split(" ");
+  let result = "";
+  for (const word of words) {
+    const next = result ? `${result} ${word}` : word;
+    if (next.length > maxChars) break;
+    result = next;
+  }
+
+  if (!result) {
+    return { text: value.slice(0, maxChars), truncated: true };
+  }
+
+  return { text: result, truncated: true };
+}
+
+function buildInputSummary(text: string): InputSummary {
+  const normalized = normalizeText(text);
+  const preview = trimTextByWord(normalized, INPUT_PREVIEW_MAX_CHARS);
+  const previewBytes = Buffer.byteLength(preview.text, "utf8");
+
+  if (!normalized) {
+    return {
+      preview: preview.text,
+      previewBytes,
+      previewTruncated: preview.truncated,
+    };
+  }
+
+  const sentences = normalized.split(/(?<=[.!?])\s+/).filter(Boolean);
+  const firstSentence = trimTextByWord(sentences[0] ?? normalized, INPUT_PREVIEW_MAX_CHARS);
+  const lastSentence = trimTextByWord(sentences[sentences.length - 1] ?? normalized, INPUT_LAST_SENTENCE_MAX_CHARS);
+
+  return {
+    preview: preview.text,
+    previewBytes,
+    previewTruncated: preview.truncated,
+    firstSentence: firstSentence.text,
+    firstSentenceTruncated: firstSentence.truncated,
+    lastSentence: lastSentence.text,
+    lastSentenceTruncated: lastSentence.truncated,
+  };
+}
+
+function buildInputSummaryAttributes(prefix: string, summary: InputSummary): Attributes {
+  return {
+    [`${prefix}.preview`]: summary.preview,
+    [`${prefix}.preview.bytes`]: summary.previewBytes,
+    [`${prefix}.preview.truncated`]: summary.previewTruncated,
+    [`${prefix}.first_sentence`]: summary.firstSentence ?? "",
+    [`${prefix}.first_sentence.truncated`]: summary.firstSentenceTruncated ?? false,
+    [`${prefix}.last_sentence`]: summary.lastSentence ?? "",
+    [`${prefix}.last_sentence.truncated`]: summary.lastSentenceTruncated ?? false,
+  };
+}
+
+function buildToolSpanName(toolName: string, input: unknown): string {
+  if (toolName !== "bash") {
+    return `pi.tool: ${toolName}`;
+  }
+
+  const command = (input as { command?: unknown } | undefined)?.command;
+  if (typeof command !== "string") {
+    return `pi.tool: ${toolName}`;
+  }
+
+  const normalized = normalizeText(command);
+  if (!normalized) {
+    return `pi.tool: ${toolName}`;
+  }
+
+  const trimmed = trimTextByWord(normalized, TOOL_COMMAND_PREVIEW_MAX_CHARS);
+  const suffix = trimmed.truncated ? `${trimmed.text}…` : trimmed.text;
+  return `pi.tool: ${toolName}(${suffix})`;
+}
+
+function updateSpanName(span: Span | undefined, name: string | undefined): void {
+  if (!span || !name) return;
+  span.updateName(name);
+}
+
+function addSpanEvent(span: Span | undefined, type: string, attrs: Attributes): void {
+  if (!span) return;
+  span.addEvent(type, {
+    "pi.event.type": type,
+    ...attrs,
+  });
+}
+
+function getSessionId(ctx: ExtensionContext): string | undefined {
+  return "getSessionId" in ctx.sessionManager ? ctx.sessionManager.getSessionId() : undefined;
+}
+
+function findLastStopReason(messages: Array<{ role?: string; stopReason?: string }>): string | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.role === "assistant") {
+      return message.stopReason;
+    }
+  }
+  return undefined;
+}
+
+function ensureAttribute(span: Span, key: string, value: string | number | boolean | undefined): void {
+  if (value === undefined) return;
+  span.setAttribute(key, value);
+}
+
+function setSpanAttributes(span: Span | undefined, attrs: Attributes): void {
+  if (!span) return;
+  for (const [key, value] of Object.entries(attrs)) {
+    span.setAttribute(key, value as string | number | boolean);
+  }
+}
+
+function createTracer(config: TelemetryConfig): TelemetryRuntime {
+  const resource = resourceFromAttributes({
+    ...config.resourceAttributes,
+    [SemanticResourceAttributes.SERVICE_NAME]: config.serviceName,
+  });
+
+  const exporter = new OTLPTraceExporter({ url: config.endpoint, headers: config.headers });
+  const processor = new BatchSpanProcessor(exporter);
+  const provider = new BasicTracerProvider({
+    resource,
+    spanProcessors: [processor],
+  });
+
+  return {
+    tracer: provider.getTracer("pi-telemetry-otel", "0.1.0"),
+    shutdown: async () => {
+      await provider.forceFlush();
+      await provider.shutdown();
+    },
+  };
+}
+
+export default function telemetryOtelExtension(pi: ExtensionAPI, options: TelemetryOptions = {}): void {
+  const config = loadConfig();
+  const now = options.now ?? Date.now;
+
+  // Tracer creation is deferred until ensureSessionSpan() so we can read a
+  // service-name override from session entries (injected by parent sessions
+  // for in-process sub-agents like the ask tool).
+  let runtime: TelemetryRuntime | undefined = options.runtime;
+  let tracer: Tracer | undefined = options.runtime?.tracer;
+  let shutdown: (() => Promise<void>) | undefined = options.runtime?.shutdown;
+
+  function ensureRuntime(serviceNameOverride?: string): TelemetryRuntime {
+    if (runtime) return runtime;
+    const effectiveConfig = serviceNameOverride
+      ? { ...config, serviceName: serviceNameOverride }
+      : config;
+    runtime = createTracer(effectiveConfig);
+    tracer = runtime.tracer;
+    shutdown = runtime.shutdown;
+    return runtime;
+  }
+
+  const spans: SpanRegistry = {
+    turns: new Map(),
+    tools: new Map(),
+  };
+
+  const traceEnvStack = new TraceEnvStack<Span>();
+  const traceScopeKeys = {
+    session: "session",
+    agent: "agent",
+    turn: (turnIndex: number) => `turn:${turnIndex}`,
+    tool: (toolCallId: string) => `tool:${toolCallId}`,
+  };
+
+  let sessionId: string | undefined;
+  let activeTurnIndex: number | undefined;
+  let lastInputSummary: InputSummary | undefined;
+  let shutdownTriggered = false;
+
+  function updateTraceStatus(ctx: ExtensionContext, traceId: string | undefined): void {
+    if (!ctx.hasUI) return;
+    if (!traceId) {
+      ctx.ui.setStatus("telemetry-otel", undefined);
+      return;
+    }
+    const theme = ctx.ui.theme;
+    const shortTraceId = traceId.slice(0, 8);
+    ctx.ui.setStatus("telemetry-otel", theme.fg("dim", `trace ${shortTraceId}`));
+  }
+
+  function syncActiveSpanContext(): void {
+    if (!sessionId) return;
+    const top = traceEnvStack.peek();
+    if (!top) {
+      clearActiveSpanContext(sessionId);
+      return;
+    }
+
+    setActiveSpanContext(sessionId, {
+      ...top.spanContext(),
+      isRemote: false,
+    });
+  }
+
+  function ensureSessionSpan(ctx: ExtensionContext): Span {
+    if (spans.session) return spans.session;
+
+    sessionId = getSessionId(ctx);
+    const entries = ctx.sessionManager.getEntries();
+
+    // Prefer trace context from session entries (injected by parent session for
+    // in-process sub-sessions) over env vars (which race across concurrent subs).
+    // Fall back to env vars for cross-process propagation (RPC sub-agents).
+    const parentSpanContext =
+      readParentSpanContextFromEntries(entries) ?? readParentSpanContext();
+    const parentContext = parentSpanContext
+      ? trace.setSpanContext(context.active(), parentSpanContext)
+      : context.active();
+
+    // Initialize runtime with service name override from entries (if present).
+    // This allows in-process sub-sessions to appear with a distinct service
+    // name in the trace (e.g. "pi-ask-agent" instead of "pi-agent").
+    const serviceNameOverride = readServiceNameFromEntries(entries);
+    const ensured = ensureRuntime(serviceNameOverride);
+    if (sessionId) {
+      registerTelemetryRuntime(sessionId, ensured);
+    }
+
+    invariant(tracer, "Tracer not initialized");
+    const span = tracer.startSpan(
+      "pi.session",
+      {
+        startTime: now(),
+      },
+      parentContext,
+    );
+
+    ensureAttribute(span, "pi.session.id", sessionId);
+    ensureAttribute(span, "pi.session.file", ctx.sessionManager.getSessionFile());
+
+    traceEnvStack.push(traceScopeKeys.session, span);
+    syncActiveSpanContext();
+    updateTraceStatus(ctx, span.spanContext().traceId);
+    spans.session = span;
+    return span;
+  }
+
+  function endSpan(span: Span | undefined, endTime?: number): void {
+    if (!span) return;
+    span.end(endTime);
+  }
+
+  function closeOrphanToolSpans(reason: string): void {
+    for (const [toolCallId, span] of spans.tools.entries()) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: `Closed without tool_result (${reason})` });
+      span.setAttribute("pi.tool.missing_result", true);
+      span.end();
+      traceEnvStack.pop(traceScopeKeys.tool(toolCallId));
+    }
+    spans.tools.clear();
+    syncActiveSpanContext();
+  }
+
+  function closeOrphanTurnSpans(reason: string): void {
+    for (const [turnIndex, span] of spans.turns.entries()) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: `Closed without turn_end (${reason})` });
+      span.setAttribute("pi.turn.missing_end", true);
+      span.end();
+      traceEnvStack.pop(traceScopeKeys.turn(turnIndex));
+    }
+    spans.turns.clear();
+    activeTurnIndex = undefined;
+    syncActiveSpanContext();
+  }
+
+  function closeOrphanAgentSpan(reason: string): void {
+    if (!spans.agent) return;
+    spans.agent.setStatus({ code: SpanStatusCode.ERROR, message: `Closed without agent_end (${reason})` });
+    spans.agent.setAttribute("pi.agent.missing_end", true);
+    spans.agent.end();
+    spans.agent = undefined;
+    traceEnvStack.pop(traceScopeKeys.agent);
+    syncActiveSpanContext();
+  }
+
+  function sendTraceMessage(ctx: ExtensionCommandContext, message: string, type: "info" | "error" = "info"): void {
+    if (ctx.hasUI) {
+      ctx.ui.notify(message, type);
+      return;
+    }
+
+    pi.sendMessage({
+      customType: "telemetry-otel-trace-url",
+      content: message,
+      display: true,
+    });
+  }
+
+  async function openUrl(ctx: ExtensionCommandContext, url: string): Promise<void> {
+    const { command, args } = getOpenUrlCommand(url);
+    const { code, stderr } = await pi.exec(command, args, {});
+    if (code !== 0) {
+      const error = stderr.trim() || `Failed to open URL (exit ${code}).`;
+      sendTraceMessage(ctx, error, "error");
+    }
+  }
+
+  pi.registerCommand("open-jaeger-trace", {
+    description: "Open the current Jaeger trace in your browser",
+    handler: async (_args, ctx) => {
+      const sessionSpan = ensureSessionSpan(ctx);
+      const traceId = sessionSpan.spanContext().traceId;
+      if (!traceId || !isValidTraceId(traceId)) {
+        sendTraceMessage(ctx, "No valid trace ID found for this session.", "error");
+        return;
+      }
+
+      const urls = await buildTraceUrls(pi, traceId);
+      const messageLines = [`Trace URL: ${urls.primary}`];
+      if (urls.tailscale) {
+        messageLines.push(`Tailscale URL: ${urls.tailscale}`);
+      }
+      const message = messageLines.join("\n");
+
+      if (!ctx.hasUI) {
+        sendTraceMessage(ctx, message, "info");
+        return;
+      }
+
+      const confirm = await ctx.ui.confirm("Open Jaeger trace?", `${message}\n\nOpen in your browser?`);
+      if (!confirm) {
+        sendTraceMessage(ctx, message, "info");
+        return;
+      }
+
+      await openUrl(ctx, urls.primary);
+      sendTraceMessage(ctx, message, "info");
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    sessionId = getSessionId(ctx);
+    lastInputSummary = undefined;
+    ensureSessionSpan(ctx);
+  });
+
+  pi.on("session_switch", (_event, ctx) => {
+    closeOrphanToolSpans("session_switch");
+    closeOrphanTurnSpans("session_switch");
+    closeOrphanAgentSpan("session_switch");
+
+    endSpan(spans.session, now());
+    spans.session = undefined;
+    traceEnvStack.clear();
+    if (sessionId) {
+      clearActiveSpanContext(sessionId);
+    }
+    updateTraceStatus(ctx, undefined);
+    sessionId = getSessionId(ctx);
+    lastInputSummary = undefined;
+    ensureSessionSpan(ctx);
+  });
+
+  pi.on("input", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const payloadAttributes = buildPayloadAttributes("pi.input.text", event.text);
+    const summary = buildInputSummary(event.text);
+
+    lastInputSummary = summary;
+
+    const summaryAttributes = buildInputSummaryAttributes("pi.input", summary);
+
+    addSpanEvent(sessionSpan, "input", {
+      "pi.event.source": event.source,
+      "pi.session.id": sessionId ?? "",
+      "pi.input.images": event.images?.length ?? 0,
+      ...payloadAttributes,
+      ...summaryAttributes,
+    });
+
+    setSpanAttributes(sessionSpan, buildInputSummaryAttributes("pi.input.latest", summary));
+    updateSpanName(sessionSpan, summary.preview ? `pi.session ${summary.preview}` : undefined);
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const parent = trace.setSpan(context.active(), sessionSpan);
+    invariant(tracer, "Tracer not initialized");
+    const span = tracer.startSpan("pi.agent", { startTime: now() }, parent);
+
+    ensureAttribute(span, "pi.session.id", sessionId);
+
+    if (lastInputSummary) {
+      setSpanAttributes(span, buildInputSummaryAttributes("pi.input.latest", lastInputSummary));
+      updateSpanName(span, lastInputSummary.preview ? `pi.agent ${lastInputSummary.preview}` : undefined);
+    }
+
+    traceEnvStack.push(traceScopeKeys.agent, span);
+    syncActiveSpanContext();
+    updateTraceStatus(ctx, span.spanContext().traceId);
+    spans.agent = span;
+  });
+
+  pi.on("turn_start", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const parent = trace.setSpan(context.active(), spans.agent ?? sessionSpan);
+
+    activeTurnIndex = event.turnIndex;
+
+    invariant(tracer, "Tracer not initialized");
+    const span = tracer.startSpan(
+      "pi.turn",
+      {
+        startTime: event.timestamp ?? now(),
+      },
+      parent,
+    );
+
+    ensureAttribute(span, "pi.session.id", sessionId);
+    ensureAttribute(span, "pi.turn.index", event.turnIndex);
+
+    if (lastInputSummary) {
+      setSpanAttributes(span, buildInputSummaryAttributes("pi.input.latest", lastInputSummary));
+    }
+
+    spans.turns.set(event.turnIndex, span);
+    traceEnvStack.push(traceScopeKeys.turn(event.turnIndex), span);
+    syncActiveSpanContext();
+    addSpanEvent(span, "turn_start", {
+      "pi.turn.index": event.turnIndex,
+      "pi.session.id": sessionId ?? "",
+    });
+  });
+
+  pi.on("tool_call", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const parentSpan = activeTurnIndex !== undefined ? spans.turns.get(activeTurnIndex) : spans.agent;
+    const parent = trace.setSpan(context.active(), parentSpan ?? sessionSpan);
+
+    invariant(tracer, "Tracer not initialized");
+    const span = tracer.startSpan(buildToolSpanName(event.toolName, event.input), { startTime: now() }, parent);
+
+    ensureAttribute(span, "pi.session.id", sessionId);
+    ensureAttribute(span, "pi.turn.index", activeTurnIndex);
+    ensureAttribute(span, "pi.tool.name", event.toolName);
+    ensureAttribute(span, "pi.tool.call_id", event.toolCallId);
+
+    spans.tools.set(event.toolCallId, span);
+    traceEnvStack.push(traceScopeKeys.tool(event.toolCallId), span);
+    syncActiveSpanContext();
+
+    addSpanEvent(span, "tool_call", {
+      "pi.tool.name": event.toolName,
+      "pi.tool.call_id": event.toolCallId,
+      "pi.session.id": sessionId ?? "",
+      "pi.turn.index": activeTurnIndex ?? -1,
+      ...buildPayloadAttributes("pi.tool.input", event.input),
+    });
+  });
+
+  pi.on("tool_result", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const span = spans.tools.get(event.toolCallId);
+
+    const outputPayload = {
+      content: event.content,
+      details: event.details,
+    };
+
+    addSpanEvent(span ?? sessionSpan, "tool_result", {
+      "pi.tool.name": event.toolName,
+      "pi.tool.call_id": event.toolCallId,
+      "pi.tool.is_error": event.isError,
+      "pi.session.id": sessionId ?? "",
+      "pi.turn.index": activeTurnIndex ?? -1,
+      ...buildPayloadAttributes("pi.tool.output", outputPayload),
+    });
+
+    if (span) {
+      if (event.isError) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: "tool_result error" });
+      }
+      span.end();
+      spans.tools.delete(event.toolCallId);
+    }
+
+    traceEnvStack.pop(traceScopeKeys.tool(event.toolCallId));
+    syncActiveSpanContext();
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const span = spans.turns.get(event.turnIndex);
+
+    const turnStopReason = "stopReason" in event.message ? event.message.stopReason : undefined;
+
+    addSpanEvent(span ?? sessionSpan, "turn_end", {
+      "pi.turn.index": event.turnIndex,
+      "pi.session.id": sessionId ?? "",
+      "pi.turn.tool_results": event.toolResults.length,
+      "pi.message.stop_reason": turnStopReason ?? "",
+    });
+
+    endSpan(span, now());
+    spans.turns.delete(event.turnIndex);
+    traceEnvStack.pop(traceScopeKeys.turn(event.turnIndex));
+    syncActiveSpanContext();
+    if (activeTurnIndex === event.turnIndex) {
+      activeTurnIndex = undefined;
+    }
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    const stopReason = findLastStopReason(event.messages);
+
+    addSpanEvent(spans.agent ?? sessionSpan, "agent_end", {
+      "pi.session.id": sessionId ?? "",
+      "pi.message.stop_reason": stopReason ?? "",
+    });
+
+    closeOrphanToolSpans("agent_end");
+    closeOrphanTurnSpans("agent_end");
+
+    endSpan(spans.agent, now());
+    spans.agent = undefined;
+    traceEnvStack.pop(traceScopeKeys.agent);
+    syncActiveSpanContext();
+
+    if (!ctx.hasUI && !shutdownTriggered) {
+      shutdownTriggered = true;
+      endSpan(spans.session, now());
+      spans.session = undefined;
+      traceEnvStack.clear();
+      if (sessionId) {
+        clearActiveSpanContext(sessionId);
+        unregisterTelemetryRuntime(sessionId);
+      }
+      await shutdown?.();
+    }
+  });
+
+  pi.on("model_select", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    addSpanEvent(sessionSpan, "model_select", {
+      "pi.session.id": sessionId ?? "",
+      "pi.model.provider": event.model.provider,
+      "pi.model.id": event.model.id,
+      "pi.model.source": event.source,
+    });
+  });
+
+  pi.on("session_compact", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    addSpanEvent(sessionSpan, "session_compact", {
+      "pi.session.id": sessionId ?? "",
+      "pi.compaction.first_kept_entry": event.compactionEntry?.firstKeptEntryId ?? "",
+      "pi.compaction.tokens_before": event.compactionEntry?.tokensBefore ?? 0,
+      ...buildPayloadAttributes("pi.compaction.summary", event.compactionEntry?.summary),
+    });
+  });
+
+  pi.on("session_tree", (event, ctx) => {
+    const sessionSpan = ensureSessionSpan(ctx);
+    addSpanEvent(sessionSpan, "session_tree", {
+      "pi.session.id": sessionId ?? "",
+      "pi.tree.new_leaf": event.newLeafId ?? "",
+      "pi.tree.old_leaf": event.oldLeafId ?? "",
+      "pi.tree.from_extension": event.fromExtension ?? false,
+    });
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (shutdownTriggered) return;
+    shutdownTriggered = true;
+
+    ensureSessionSpan(ctx);
+    closeOrphanToolSpans("session_shutdown");
+    closeOrphanTurnSpans("session_shutdown");
+    closeOrphanAgentSpan("session_shutdown");
+
+    endSpan(spans.session, now());
+    spans.session = undefined;
+    traceEnvStack.clear();
+    updateTraceStatus(ctx, undefined);
+
+    if (sessionId) {
+      clearActiveSpanContext(sessionId);
+      unregisterTelemetryRuntime(sessionId);
+    }
+
+    await shutdown?.();
+  });
+}

package/extensions/runtime-registry.ts

@@ -0,0 +1,30 @@
+import type { Tracer } from "@opentelemetry/api";
+
+export type TelemetryOtelRuntimeHandle = {
+  tracer: Tracer;
+  shutdown: () => Promise<void>;
+};
+
+export const RUNTIME_REGISTRY_SYMBOL = Symbol.for("pi.telemetry-otel.runtimeRegistry.v1");
+
+type Registry = Map<string, TelemetryOtelRuntimeHandle>;
+
+function getRegistry(): Registry {
+  const globalAny = globalThis as unknown as { [RUNTIME_REGISTRY_SYMBOL]?: Registry };
+  if (!globalAny[RUNTIME_REGISTRY_SYMBOL]) {
+    globalAny[RUNTIME_REGISTRY_SYMBOL] = new Map();
+  }
+  return globalAny[RUNTIME_REGISTRY_SYMBOL]!;
+}
+
+export function registerTelemetryRuntime(sessionId: string, runtime: TelemetryOtelRuntimeHandle): void {
+  getRegistry().set(sessionId, runtime);
+}
+
+export function unregisterTelemetryRuntime(sessionId: string): void {
+  getRegistry().delete(sessionId);
+}
+
+export function getTelemetryRuntime(sessionId: string): TelemetryOtelRuntimeHandle | undefined {
+  return getRegistry().get(sessionId);
+}

package/extensions/span-context-registry.ts

@@ -0,0 +1,31 @@
+import type { SpanContextLike } from "../lib/trace-env";
+
+/**
+ * Holds the currently active span context for a given pi session.
+ *
+ * This is intentionally stored on globalThis under a Symbol.for key so that
+ * multiple copies / versions of this package can share the same registry.
+ */
+export const ACTIVE_SPAN_CONTEXT_REGISTRY_SYMBOL = Symbol.for("pi.telemetry-otel.activeSpanContextRegistry.v1");
+
+type Registry = Map<string, SpanContextLike>;
+
+function getRegistry(): Registry {
+  const globalAny = globalThis as unknown as { [ACTIVE_SPAN_CONTEXT_REGISTRY_SYMBOL]?: Registry };
+  if (!globalAny[ACTIVE_SPAN_CONTEXT_REGISTRY_SYMBOL]) {
+    globalAny[ACTIVE_SPAN_CONTEXT_REGISTRY_SYMBOL] = new Map();
+  }
+  return globalAny[ACTIVE_SPAN_CONTEXT_REGISTRY_SYMBOL]!;
+}
+
+export function setActiveSpanContext(sessionId: string, spanContext: SpanContextLike): void {
+  getRegistry().set(sessionId, spanContext);
+}
+
+export function clearActiveSpanContext(sessionId: string): void {
+  getRegistry().delete(sessionId);
+}
+
+export function getActiveSpanContext(sessionId: string): SpanContextLike | undefined {
+  return getRegistry().get(sessionId);
+}

package/helpers/index.ts

@@ -0,0 +1,132 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { type Attributes, type Span, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { getActiveSpanContext } from "../extensions/span-context-registry";
+import { getTelemetryRuntime, type TelemetryOtelRuntimeHandle } from "../extensions/runtime-registry";
+import {
+  TRACE_CONTEXT_ENTRY_TYPE,
+  isValidSpanId,
+  isValidTraceId,
+  readParentSpanContext,
+  readParentSpanContextFromEntries,
+  type SpanContextLike,
+} from "../lib/trace-env";
+
+export interface StartPiSpanOptions {
+  /** Initial span attributes. */
+  attributes?: Attributes;
+  /** Explicit parent span context. When omitted, uses the current pi active span context. */
+  parentSpanContext?: SpanContextLike;
+  /** Start time (unix ms) or hr-time depending on OTEL impl. */
+  startTime?: number;
+}
+
+function getSessionId(ctx: ExtensionContext): string | undefined {
+  return "getSessionId" in ctx.sessionManager ? ctx.sessionManager.getSessionId() : undefined;
+}
+
+/**
+ * Returns the telemetry-otel runtime handle for the current pi session (if the telemetry extension is loaded).
+ */
+export function getPiTelemetryRuntime(ctx: ExtensionContext): TelemetryOtelRuntimeHandle | undefined {
+  const sessionId = getSessionId(ctx);
+  if (!sessionId) return undefined;
+  return getTelemetryRuntime(sessionId);
+}
+
+/** Returns the OTEL tracer registered by telemetry-otel for this session (if available). */
+export function getPiTracer(ctx: ExtensionContext) {
+  return getPiTelemetryRuntime(ctx)?.tracer;
+}
+
+/**
+ * Get the best available span context to parent child spans under.
+ *
+ * Preference order:
+ * 1) Per-session active span context registry (race-free for in-process concurrency)
+ * 2) Session entry trace context (in-process sub-sessions)
+ * 3) Env vars PI_AGENT_TRACE_ID / PI_AGENT_SPAN_ID (cross-process propagation)
+ */
+export function getPiActiveSpanContext(ctx: ExtensionContext): SpanContextLike | undefined {
+  const sessionId = getSessionId(ctx);
+  const fromRegistry = sessionId ? getActiveSpanContext(sessionId) : undefined;
+  if (fromRegistry) return fromRegistry;
+
+  const entries = ctx.sessionManager.getEntries?.() ?? [];
+  return readParentSpanContextFromEntries(entries) ?? readParentSpanContext();
+}
+
+/**
+ * Start a new span as a child of the currently active pi span.
+ *
+ * Returns undefined if telemetry-otel is not loaded (no tracer runtime registered).
+ */
+export function startPiSpan(ctx: ExtensionContext, name: string, options: StartPiSpanOptions = {}): Span | undefined {
+  const tracer = getPiTracer(ctx);
+  if (!tracer) return undefined;
+
+  const parentSpanContext = options.parentSpanContext ?? getPiActiveSpanContext(ctx);
+  const parentContext = parentSpanContext ? trace.setSpanContext(context.active(), parentSpanContext) : context.active();
+
+  return tracer.startSpan(
+    name,
+    {
+      attributes: options.attributes,
+      startTime: options.startTime,
+    },
+    parentContext,
+  );
+}
+
+/**
+ * Convenience helper: creates a child span, runs `fn`, records errors, and ends the span.
+ */
+export async function withPiSpan<T>(
+  ctx: ExtensionContext,
+  name: string,
+  fn: (span: Span | undefined) => Promise<T> | T,
+  options: StartPiSpanOptions = {},
+): Promise<T> {
+  const span = startPiSpan(ctx, name, options);
+  try {
+    return await fn(span);
+  } catch (error) {
+    if (span) {
+      span.recordException(error as any);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    throw error;
+  } finally {
+    span?.end();
+  }
+}
+
+/**
+ * Capture the current trace/span IDs for correlation or sub-session propagation.
+ */
+export function capturePiTraceContext(ctx: ExtensionContext): { traceId: string; spanId: string } | undefined {
+  const sc = getPiActiveSpanContext(ctx);
+  if (!sc) return undefined;
+  if (!isValidTraceId(sc.traceId) || !isValidSpanId(sc.spanId)) return undefined;
+  return { traceId: sc.traceId, spanId: sc.spanId };
+}
+
+/**
+ * Inject current trace context into another SessionManager-like object (in-process sub-sessions).
+ */
+export function injectPiTraceContextEntry(
+  ctx: ExtensionContext,
+  sessionManager: { appendCustomEntry: (customType: string, data: unknown) => void },
+  options: { serviceName?: string } = {},
+): void {
+  const captured = capturePiTraceContext(ctx);
+  if (!captured) return;
+
+  sessionManager.appendCustomEntry(TRACE_CONTEXT_ENTRY_TYPE, {
+    traceId: captured.traceId,
+    spanId: captured.spanId,
+    serviceName: options.serviceName,
+  });
+}

package/index.ts

@@ -0,0 +1,12 @@
+export { default } from "./extensions/index";
+export * from "./extensions/index";
+
+// Public helper APIs for other extensions/packages.
+export * from "./helpers/index";
+
+// Trace context utilities (env + session entry helpers).
+export * from "./lib/trace-env";
+
+// Global registries (advanced interop).
+export * from "./extensions/runtime-registry";
+export * from "./extensions/span-context-registry";

package/lib/agent-chain.ts

@@ -0,0 +1,75 @@
+const AGENT_CHAIN_ENV = "PI_AGENT_CHAIN";
+const AGENT_CHAIN_MAX_DEPTH_ENV = "PI_AGENT_CHAIN_MAX_DEPTH";
+const DEFAULT_AGENT_CHAIN_MAX_DEPTH = 1;
+
+export interface BuildAgentSpawnEnvOptions {
+  baseEnv?: NodeJS.ProcessEnv;
+  extraEnv?: NodeJS.ProcessEnv;
+  maxDepth?: number;
+}
+
+export interface BuildAgentSpawnEnvResult {
+  env?: NodeJS.ProcessEnv;
+  error?: string;
+}
+
+export function parseAgentChain(env: NodeJS.ProcessEnv = process.env): string[] {
+  const raw = env[AGENT_CHAIN_ENV]?.trim();
+  if (!raw) return [];
+  return raw
+    .split(">")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function getCurrentAgentName(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const chain = parseAgentChain(env);
+  return chain.length > 0 ? chain[chain.length - 1] : undefined;
+}
+
+export function formatAgentChain(chain: string[]): string {
+  return chain.join(">");
+}
+
+export function readChainMaxDepth(
+  env: NodeJS.ProcessEnv = process.env,
+  defaultValue: number = DEFAULT_AGENT_CHAIN_MAX_DEPTH,
+): number {
+  const raw = env[AGENT_CHAIN_MAX_DEPTH_ENV]?.trim();
+  if (!raw) return defaultValue;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return defaultValue;
+  return parsed;
+}
+
+export function buildAgentSpawnEnv(agentName: string, options: BuildAgentSpawnEnvOptions = {}): BuildAgentSpawnEnvResult {
+  const baseEnv = options.baseEnv ?? process.env;
+  const chain = parseAgentChain(baseEnv);
+  if (chain.includes(agentName)) {
+    return {
+      error: `Critical: agent chain already includes "${agentName}" (${formatAgentChain(chain)}).`,
+    };
+  }
+
+  const maxDepth = options.maxDepth ?? readChainMaxDepth(baseEnv, DEFAULT_AGENT_CHAIN_MAX_DEPTH);
+  if (chain.length >= maxDepth) {
+    return {
+      error: `Critical: agent chain depth ${chain.length} exceeds max ${maxDepth}.`,
+    };
+  }
+
+  const nextChain = formatAgentChain([...chain, agentName]);
+  return {
+    env: {
+      ...baseEnv,
+      [AGENT_CHAIN_ENV]: nextChain,
+      ...options.extraEnv,
+    },
+  };
+}
+
+export const AgentChainEnv = {
+  AGENT_CHAIN_ENV,
+  AGENT_CHAIN_MAX_DEPTH_ENV,
+  DEFAULT_AGENT_CHAIN_MAX_DEPTH,
+};

package/lib/trace-env.ts

@@ -0,0 +1,160 @@
+export const TRACE_ID_ENV = "PI_AGENT_TRACE_ID";
+export const SPAN_ID_ENV = "PI_AGENT_SPAN_ID";
+
+/**
+ * CustomEntry type used to pass parent trace context into sub-sessions via SessionManager.
+ * Preferred over env vars for in-process sub-sessions to avoid race conditions.
+ */
+export const TRACE_CONTEXT_ENTRY_TYPE = "telemetry-otel-trace-context";
+
+/** Shape of the data stored in a trace context custom entry. */
+export interface TraceContextEntryData {
+  traceId: string;
+  spanId: string;
+  /** Optional service name override for the sub-session's OTEL resource. */
+  serviceName?: string;
+}
+
+const TRACE_ID_LENGTH = 32;
+const SPAN_ID_LENGTH = 16;
+const TRACE_FLAGS_SAMPLED = 0x01;
+
+export interface SpanContextLike {
+  traceId: string;
+  spanId: string;
+  traceFlags: number;
+  isRemote?: boolean;
+}
+
+export interface SpanLike {
+  spanContext(): { traceId: string; spanId: string };
+}
+
+function isValidHexId(value: string, length: number): boolean {
+  if (value.length !== length) return false;
+  if (!/^[0-9a-f]+$/i.test(value)) return false;
+  return !/^0+$/.test(value);
+}
+
+export function isValidTraceId(value: string): boolean {
+  return isValidHexId(value, TRACE_ID_LENGTH);
+}
+
+export function isValidSpanId(value: string): boolean {
+  return isValidHexId(value, SPAN_ID_LENGTH);
+}
+
+export function readParentSpanContext(env: NodeJS.ProcessEnv = process.env): SpanContextLike | undefined {
+  const traceId = env[TRACE_ID_ENV];
+  const spanId = env[SPAN_ID_ENV];
+
+  if (!traceId || !spanId) return undefined;
+  if (!isValidTraceId(traceId) || !isValidSpanId(spanId)) return undefined;
+
+  return {
+    traceId,
+    spanId,
+    traceFlags: TRACE_FLAGS_SAMPLED,
+    isRemote: true,
+  };
+}
+
+/**
+ * Read parent span context from session entries (CustomEntry with TRACE_CONTEXT_ENTRY_TYPE).
+ * Returns the last matching entry's data, or undefined if none found.
+ *
+ * Use this for in-process sub-sessions where env vars may conflict.
+ * Falls back to readParentSpanContext() for cross-process propagation.
+ */
+export function readParentSpanContextFromEntries(
+  entries: ReadonlyArray<{ type: string; customType?: string; data?: unknown }>,
+): SpanContextLike | undefined {
+  // Scan backwards — last entry wins (most recent context)
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type === "custom" && entry.customType === TRACE_CONTEXT_ENTRY_TYPE) {
+      const data = entry.data as TraceContextEntryData | undefined;
+      if (!data?.traceId || !data?.spanId) continue;
+      if (!isValidTraceId(data.traceId) || !isValidSpanId(data.spanId)) continue;
+
+      return {
+        traceId: data.traceId,
+        spanId: data.spanId,
+        traceFlags: TRACE_FLAGS_SAMPLED,
+        isRemote: false,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Read service name override from session entries (if present in trace context entry).
+ */
+export function readServiceNameFromEntries(
+  entries: ReadonlyArray<{ type: string; customType?: string; data?: unknown }>,
+): string | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type === "custom" && entry.customType === TRACE_CONTEXT_ENTRY_TYPE) {
+      const data = entry.data as TraceContextEntryData | undefined;
+      return data?.serviceName;
+    }
+  }
+  return undefined;
+}
+
+export function syncTraceEnv(span: SpanLike, env: NodeJS.ProcessEnv = process.env): void {
+  const { traceId, spanId } = span.spanContext();
+  const existingTraceId = env[TRACE_ID_ENV];
+
+  if (!existingTraceId || !isValidTraceId(existingTraceId)) {
+    env[TRACE_ID_ENV] = traceId;
+  }
+
+  env[SPAN_ID_ENV] = spanId;
+}
+
+export class TraceEnvStack<TSpan extends SpanLike = SpanLike> {
+  private stack: Array<{ key: string; span: TSpan }> = [];
+
+  constructor(private readonly env: NodeJS.ProcessEnv = process.env) {}
+
+  /** Returns the current top span (the one synced into env), if any. */
+  peek(): TSpan | undefined {
+    return this.stack[this.stack.length - 1]?.span;
+  }
+
+  push(key: string, span: TSpan): void {
+    const existingIndex = this.stack.findIndex((entry) => entry.key === key);
+    if (existingIndex !== -1) {
+      this.stack.splice(existingIndex, 1);
+    }
+
+    this.stack.push({ key, span });
+    syncTraceEnv(span, this.env);
+  }
+
+  pop(key: string): void {
+    const index = this.stack.findIndex((entry) => entry.key === key);
+    if (index === -1) return;
+
+    const wasTop = index === this.stack.length - 1;
+    this.stack.splice(index, 1);
+
+    if (wasTop) {
+      this.syncTop();
+    }
+  }
+
+  syncTop(): void {
+    const top = this.stack[this.stack.length - 1];
+    if (!top) return;
+    syncTraceEnv(top.span, this.env);
+  }
+
+  clear(): void {
+    this.stack = [];
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pi-telemetry-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry (OTLP/HTTP) telemetry extension + helper APIs for pi",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "opentelemetry", "otel", "tracing", "jaeger", "otlp"],
+  "license": "MIT",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./extension": "./extensions/index.ts",
+    "./helpers": "./helpers/index.ts",
+    "./trace-env": "./lib/trace-env.ts",
+    "./runtime-registry": "./extensions/runtime-registry.ts",
+    "./span-context-registry": "./extensions/span-context-registry.ts"
+  },
+  "files": ["index.ts", "extensions", "helpers", "lib", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.37.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  }
+}