@telemetry-dev/pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telemetry.dev
+
+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,106 @@
+# @telemetry-dev/pi
+
+Telemetry integration for the [pi coding agent](https://github.com/earendil-works/pi) and
+[telemetry.dev](https://telemetry.dev). It records pi agent loops, model calls, tool executions, and
+lifecycle events without changing pi's behavior.
+
+## Install
+
+Add the package to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:@telemetry-dev/pi"]
+}
+```
+
+Pi reads the package's `pi.extensions` manifest and loads `@telemetry-dev/pi/register`
+automatically.
+
+Alternatively, install `@telemetry-dev/pi` where pi can resolve it and create
+`~/.pi/agent/extensions/telemetry-dev.ts`:
+
+```ts
+import { telemetryDevExtension } from "@telemetry-dev/pi";
+export default telemetryDevExtension();
+```
+
+The integration targets `@earendil-works/pi-coding-agent` 0.82.1. The pi package is an optional peer
+dependency because pi bundles its extension API and provides it to installed extensions.
+
+## Environment
+
+| Variable                    | Required | Default                        | Notes                                                                   |
+| --------------------------- | -------- | ------------------------------ | ----------------------------------------------------------------------- |
+| `TELEMETRY_DEV_API_KEY`     | yes      | —                              | Ingest key (`td_live_…`). No key ⇒ the integration is a complete no-op. |
+| `TELEMETRY_DEV_BASE_URL`    | no       | `https://ingest.telemetry.dev` | Trailing slashes are stripped.                                          |
+| `TELEMETRY_DEV_ENVIRONMENT` | no       | `production`                   | Environment label on every trace/log.                                   |
+| `OTEL_SERVICE_NAME`         | no       | `pi`                           | OpenTelemetry service name.                                             |
+
+All four are also settable through SDK options when loading the extension directly:
+
+```ts
+import { telemetryDevExtension } from "@telemetry-dev/pi";
+
+export default telemetryDevExtension({
+  agentName: "pair-programmer",
+  captureInput: false,
+  captureOutput: true,
+});
+```
+
+Initialization is one-shot; the first extension factory initialized in a process supplies the SDK
+options.
+
+## Trace shape
+
+A typical prompt produces this hierarchy:
+
+```text
+invoke_agent
+├── chat {model}                  (assistant message)
+│   ├── execute_tool {toolName}   (tool calls issued by that message)
+│   └── execute_tool {toolName}
+└── chat {model}                  (final assistant message)
+```
+
+- one `invoke_agent` span for the full agent loop, including the prompt and final assistant text;
+- one nested `chat {model}` span per completed assistant message, with provider, requested and
+  response model, response id, finish reason, usage, and pi's estimated USD cost;
+- one `execute_tool {toolName}` span per tool execution, nested under the `chat` span whose tool
+  call issued it (tool call ids are matched against the assistant message's tool-call blocks;
+  executions with no matching message fall back to the `invoke_agent` span), including the tool
+  call id, arguments, result, and error state;
+- lifecycle logs for sessions, turns, compaction, and model changes.
+
+Every span and log reads `ctx.sessionManager.getSessionId()` when its event fires and records it as
+`gen_ai.conversation.id`. This keeps `/new`, `/resume`, `/fork`, and `/reload` events attached to the
+new session rather than a cached id. Logs also carry `gen_ai.agent.name` and the raw pi event type as
+`eventName`.
+
+`agent_end` closes any unfinished tool spans and starts an asynchronous flush. `session_shutdown`
+closes an unfinished agent loop and awaits a final flush before pi tears down or switches sessions.
+It never shuts down the SDK during a pi session change.
+
+## Content capture
+
+Prompt input, assistant text output, tool arguments, and tool results follow the telemetry.dev SDK
+`captureInput` and `captureOutput` settings. Both default to `true`. Use `mask` to redact values before
+capture and `maxAttributeLength` to bound serialized attributes.
+
+Thinking and tool-call content blocks are not copied into assistant output; only text blocks are
+joined. Usage metadata still includes reasoning-token counts when pi reports them.
+
+## Limitations
+
+- Pi does not expose per-request TTFT or duration fields. Chat duration is measured from
+  `message_start` to `message_end` using local wall-clock time, and TTFT is not recorded.
+- `tool_call` and `tool_result` are intentionally not intercepted. In pi, an uncaught `tool_call`
+  handler error blocks the user's tool, so this integration uses the fail-open
+  `tool_execution_start` / `tool_execution_end` events instead.
+- An assistant message with `stopReason: "aborted"` is recorded with finish reason `aborted`, not as an
+  error. Only `stopReason: "error"` marks chat and agent spans as errors.
+- `gen_ai.usage.cost` is pi's client-side USD estimate from its bundled model pricing, not a charge or
+  server-calculated invoice value.
+- Initialization is one-shot. Loading the package more than once does not replace the first
+  configuration.

package/dist/extension-CZQ_PvAB.d.mts

@@ -0,0 +1,55 @@
+import { ClientOverrides, TelemetryOptions } from "@telemetry-dev/sdk";
+
+//#region src/config.d.ts
+/**
+ * SDK options accepted by @telemetry-dev/pi. `registerGlobal` is excluded on
+ * purpose: pi runs its own OpenTelemetry pipeline in-process, so this
+ * integration never touches the global provider — every span is created
+ * through the SDK's own tracer with explicit parenting.
+ */
+type TelemetryDevPiOptions = Omit<TelemetryOptions, "registerGlobal">;
+//#endregion
+//#region src/extension.d.ts
+/** Options for {@link telemetryDevExtension}. */
+interface TelemetryDevExtensionOptions extends TelemetryDevPiOptions {
+  /** Value for `gen_ai.agent.name` on spans and logs. Defaults to `"pi"`. */
+  agentName?: string;
+}
+/**
+ * Structural slice of pi's `ExtensionContext` read by this integration.
+ *
+ * The host package (`@earendil-works/pi-coding-agent`) is an optional peer, so
+ * its types must not appear in this package's emitted declarations;
+ * assignability to the real host types is asserted in this package's tests.
+ */
+interface TelemetryDevExtensionContext {
+  /** Current working directory. */
+  cwd: string;
+  /** Current model descriptor, when one is selected. */
+  model: unknown;
+  /** Read-only session manager exposing the session id. */
+  sessionManager: {
+    getSessionId(): string | undefined;
+  };
+}
+/**
+ * Structural stand-in for the host `ExtensionAPI` passed to extension
+ * factories. The `never` parameters make any host event-subscription surface
+ * assignable; this integration is not meant to be called through this type.
+ */
+interface TelemetryDevExtensionHost {
+  on(event: never, handler: never): void;
+}
+/** Structural stand-in for the host `ExtensionFactory` type. */
+type TelemetryDevExtension = (pi: TelemetryDevExtensionHost) => void;
+/**
+ * Creates a pi extension factory that exports agent loops, model calls, tool
+ * executions, and lifecycle logs to telemetry.dev.
+ *
+ * Trace shape per user prompt: one `invoke_agent` span, with one `chat {model}`
+ * child span per assistant message and one `execute_tool {tool}` child span per
+ * tool execution. Logs join the same session via `gen_ai.conversation.id`.
+ */
+declare function telemetryDevExtension(options?: TelemetryDevExtensionOptions, overrides?: ClientOverrides): TelemetryDevExtension;
+//#endregion
+export { telemetryDevExtension as a, TelemetryDevExtensionOptions as i, TelemetryDevExtensionContext as n, TelemetryDevPiOptions as o, TelemetryDevExtensionHost as r, TelemetryDevExtension as t };

package/dist/extension-DLbX-piL.mjs

@@ -0,0 +1,274 @@
+import { flush, init, log, startSpan } from "@telemetry-dev/sdk";
+//#region src/config.ts
+let initialized = false;
+/** Initializes the telemetry.dev SDK exactly once per process for this integration. */
+function ensureInit(options = {}, overrides) {
+	if (initialized) return;
+	initialized = true;
+	init({
+		...options,
+		serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "pi",
+		registerGlobal: false
+	}, overrides);
+}
+//#endregion
+//#region src/extension.ts
+function asRecord(cause) {
+	if (cause === null || cause instanceof Function || Object(cause) !== cause) return void 0;
+	return cause;
+}
+function stringField(record, key) {
+	const value = record?.[key];
+	return value?.constructor === String && value.length > 0 ? value : void 0;
+}
+function numberField(record, key) {
+	const value = record?.[key];
+	return value?.constructor === Number && Number.isFinite(value) ? value : void 0;
+}
+function booleanField(record, key) {
+	const value = record?.[key];
+	return value?.constructor === Boolean ? value : void 0;
+}
+function reportError(onError, cause) {
+	try {
+		onError?.call(void 0, cause);
+	} catch {}
+}
+function sessionId(ctx) {
+	const id = ctx.sessionManager.getSessionId();
+	return id?.constructor === String && id.length > 0 ? id : void 0;
+}
+/** Joins the text blocks of a pi message content array. */
+function textContent(content) {
+	if (!Array.isArray(content)) return void 0;
+	const parts = [];
+	for (const block of content) {
+		const record = asRecord(block);
+		if (record?.type === "text" && record.text?.constructor === String) parts.push(record.text);
+	}
+	return parts.length > 0 ? parts.join("\n") : void 0;
+}
+function usageFields(message) {
+	const usage = asRecord(message.usage);
+	if (!usage) return void 0;
+	return {
+		inputTokens: numberField(usage, "input"),
+		outputTokens: numberField(usage, "output"),
+		totalTokens: numberField(usage, "totalTokens"),
+		cacheReadInputTokens: numberField(usage, "cacheRead"),
+		cacheCreationInputTokens: numberField(usage, "cacheWrite"),
+		reasoningOutputTokens: numberField(usage, "reasoning")
+	};
+}
+/** Named error so `error.type` reflects the failure class instead of "Error". */
+function failureError(name, message) {
+	const error = new Error(message ?? name);
+	error.name = name;
+	return error;
+}
+/**
+* Creates a pi extension factory that exports agent loops, model calls, tool
+* executions, and lifecycle logs to telemetry.dev.
+*
+* Trace shape per user prompt: one `invoke_agent` span, with one `chat {model}`
+* child span per assistant message and one `execute_tool {tool}` child span per
+* tool execution. Logs join the same session via `gen_ai.conversation.id`.
+*/
+function telemetryDevExtension(options = {}, overrides) {
+	const { agentName = "pi", ...sdkOptions } = options;
+	const onError = sdkOptions.onError;
+	return (pi) => {
+		try {
+			ensureInit(sdkOptions, overrides);
+		} catch (error) {
+			reportError(onError, error);
+		}
+		/** Calls through `pi` so the host's `on` keeps its `this` binding. */
+		function register(event, handler) {
+			pi.on(event, handler);
+		}
+		let agentSpan;
+		let assistantStartedAt;
+		let pendingPrompt;
+		/** Latest agent_end outcome, applied to the prompt span when the run settles. */
+		let lastRunResult;
+		/** Chat span that issued each pending tool call, so tool spans nest under it. */
+		const chatSpanByToolCall = /* @__PURE__ */ new Map();
+		const toolSpans = /* @__PURE__ */ new Map();
+		function baseAttributes(ctx) {
+			return {
+				"gen_ai.conversation.id": sessionId(ctx),
+				"gen_ai.agent.name": agentName
+			};
+		}
+		function emit(eventName, ctx, level, message, attributes = {}) {
+			log(message, {
+				level,
+				eventName,
+				attributes: {
+					...baseAttributes(ctx),
+					...attributes
+				}
+			});
+		}
+		function spanAttributes(ctx) {
+			const id = sessionId(ctx);
+			return id ? { "gen_ai.conversation.id": id } : {};
+		}
+		function endDanglingToolSpans() {
+			for (const span of toolSpans.values()) span.end({ error: failureError("incomplete", "tool execution did not complete") });
+			toolSpans.clear();
+			chatSpanByToolCall.clear();
+		}
+		function endAgentSpan(fields) {
+			endDanglingToolSpans();
+			agentSpan?.end(fields);
+			agentSpan = void 0;
+		}
+		function on(event, handler) {
+			register(event, (payload, ctx) => {
+				try {
+					handler(payload, ctx);
+				} catch (error) {
+					reportError(onError, error);
+				}
+			});
+		}
+		register("before_agent_start", (event) => {
+			try {
+				pendingPrompt = event.prompt?.constructor === String ? event.prompt : void 0;
+			} catch (error) {
+				reportError(onError, error);
+			}
+		});
+		on("agent_start", (_event, ctx) => {
+			if (agentSpan) return;
+			agentSpan = startSpan("invoke_agent", {
+				type: "agent",
+				agentName,
+				input: pendingPrompt,
+				attributes: spanAttributes(ctx)
+			});
+			pendingPrompt = void 0;
+		});
+		on("agent_end", (event, _ctx) => {
+			const messages = Array.isArray(event.messages) ? event.messages : [];
+			let lastAssistant;
+			for (const message of messages) {
+				const record = asRecord(message);
+				if (record?.role === "assistant") lastAssistant = record;
+			}
+			const stopReason = stringField(lastAssistant, "stopReason");
+			const errorMessage = stringField(lastAssistant, "errorMessage");
+			lastRunResult = {
+				output: textContent(lastAssistant?.content),
+				finishReason: stopReason,
+				error: stopReason === "error" ? failureError(stopReason, errorMessage) : void 0
+			};
+			flush();
+		});
+		on("agent_settled", (_event, _ctx) => {
+			endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
+			lastRunResult = void 0;
+			flush();
+		});
+		on("message_start", (event, _ctx) => {
+			if (asRecord(event.message)?.role === "assistant") assistantStartedAt = Date.now();
+		});
+		on("message_end", (event, ctx) => {
+			const message = asRecord(event.message);
+			if (message?.role !== "assistant") return;
+			const startTime = assistantStartedAt;
+			assistantStartedAt = void 0;
+			const endTime = Date.now();
+			const model = stringField(message, "model");
+			const responseModel = stringField(message, "responseModel") ?? model;
+			const errorMessage = stringField(message, "errorMessage");
+			const stopReason = stringField(message, "stopReason");
+			const span = startSpan(model ? `chat ${model}` : "chat", {
+				type: "generation",
+				parent: agentSpan,
+				startTime,
+				model,
+				provider: stringField(message, "provider"),
+				responseModel,
+				responseId: stringField(message, "responseId"),
+				usage: usageFields(message),
+				costUsd: numberField(asRecord(asRecord(message.usage)?.cost), "total"),
+				finishReason: stopReason,
+				output: textContent(message.content),
+				error: stopReason === "error" ? failureError(stopReason, errorMessage) : void 0,
+				attributes: spanAttributes(ctx)
+			});
+			for (const block of Array.isArray(message.content) ? message.content : []) {
+				const record = asRecord(block);
+				if (record?.type === "toolCall" && record.id?.constructor === String) chatSpanByToolCall.set(record.id, span);
+			}
+			span.end({ endTime });
+		});
+		on("tool_execution_start", (event, ctx) => {
+			const span = startSpan(`execute_tool ${event.toolName}`, {
+				type: "tool",
+				parent: chatSpanByToolCall.get(event.toolCallId) ?? agentSpan,
+				toolName: event.toolName,
+				toolCallId: event.toolCallId,
+				input: event.args,
+				attributes: spanAttributes(ctx)
+			});
+			chatSpanByToolCall.delete(event.toolCallId);
+			toolSpans.set(event.toolCallId, span);
+		});
+		on("tool_execution_end", (event, _ctx) => {
+			const span = toolSpans.get(event.toolCallId);
+			if (!span) return;
+			toolSpans.delete(event.toolCallId);
+			const resultText = textContent(asRecord(event.result)?.content);
+			span.end({
+				output: event.result,
+				error: event.isError ? failureError("ToolExecutionError", resultText) : void 0
+			});
+		});
+		on("turn_start", (event, ctx) => {
+			emit("turn_start", ctx, "debug", "Turn started", { "pi.turn.index": event.turnIndex });
+		});
+		on("turn_end", (event, ctx) => {
+			emit("turn_end", ctx, "debug", "Turn completed", { "pi.turn.index": event.turnIndex });
+		});
+		on("session_start", (event, ctx) => {
+			const model = asRecord(ctx.model);
+			emit("session_start", ctx, "info", "Session started", {
+				"gen_ai.request.model": stringField(model, "id"),
+				"gen_ai.provider.name": stringField(model, "provider"),
+				"pi.cwd": ctx.cwd,
+				"pi.session.reason": event.reason
+			});
+		});
+		on("session_compact", (event, ctx) => {
+			emit("session_compact", ctx, "info", "Session compacted", {
+				"pi.compaction.from_extension": booleanField(asRecord(event), "fromExtension"),
+				"pi.compaction.reason": event.reason
+			});
+		});
+		on("model_select", (event, ctx) => {
+			emit("model_select", ctx, "info", "Model changed", {
+				"pi.model.from": stringField(asRecord(event.previousModel), "id"),
+				"pi.model.source": event.source,
+				"pi.model.to": stringField(asRecord(event.model), "id")
+			});
+		});
+		register("session_shutdown", async (event, ctx) => {
+			try {
+				if (agentSpan || toolSpans.size > 0) {
+					endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
+					lastRunResult = void 0;
+				}
+				emit("session_shutdown", ctx, "info", "Session shutdown", { "pi.session.reason": event.reason });
+				await flush();
+			} catch (error) {
+				reportError(onError, error);
+			}
+		});
+	};
+}
+//#endregion
+export { telemetryDevExtension as t };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as telemetryDevExtension, i as TelemetryDevExtensionOptions, n as TelemetryDevExtensionContext, o as TelemetryDevPiOptions, r as TelemetryDevExtensionHost, t as TelemetryDevExtension } from "./extension-CZQ_PvAB.mjs";
+export { type TelemetryDevExtension, type TelemetryDevExtensionContext, type TelemetryDevExtensionHost, type TelemetryDevExtensionOptions, type TelemetryDevPiOptions, telemetryDevExtension };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { t as telemetryDevExtension } from "./extension-DLbX-piL.mjs";
+export { telemetryDevExtension };

package/dist/register.d.mts

@@ -0,0 +1,11 @@
+import { t as TelemetryDevExtension } from "./extension-CZQ_PvAB.mjs";
+
+//#region src/register.d.ts
+/**
+ * Ready-to-load pi extension entry configured from `TELEMETRY_DEV_*`
+ * environment variables. Referenced by this package's `pi.extensions`
+ * manifest so `@telemetry-dev/pi` works as an installed pi package.
+ */
+declare const _default: TelemetryDevExtension;
+//#endregion
+export { _default as default };

package/dist/register.mjs

@@ -0,0 +1,10 @@
+import { t as telemetryDevExtension } from "./extension-DLbX-piL.mjs";
+//#region src/register.ts
+/**
+* Ready-to-load pi extension entry configured from `TELEMETRY_DEV_*`
+* environment variables. Referenced by this package's `pi.extensions`
+* manifest so `@telemetry-dev/pi` works as an installed pi package.
+*/
+var register_default = telemetryDevExtension();
+//#endregion
+export { register_default as default };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@telemetry-dev/pi",
+  "version": "0.1.0",
+  "description": "Pi coding-agent telemetry integration for telemetry.dev.",
+  "keywords": [
+    "agents",
+    "coding-agent",
+    "genai",
+    "llm",
+    "observability",
+    "opentelemetry",
+    "pi",
+    "telemetry",
+    "tracing"
+  ],
+  "homepage": "https://telemetry.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telemetry-dev/telemetry.dev.git",
+    "directory": "packages/pi"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./register": {
+      "types": "./dist/register.d.mts",
+      "import": "./dist/register.mjs",
+      "default": "./dist/register.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@telemetry-dev/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "typescript": "^6.0.2",
+    "vite-plus": "0.1.20",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.20"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.4"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./dist/register.mjs"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm exec vp pack",
+    "dev": "pnpm exec vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}

package/src/config.ts

@@ -0,0 +1,34 @@
+import { init, shutdown, type ClientOverrides, type TelemetryOptions } from "@telemetry-dev/sdk";
+
+/**
+ * SDK options accepted by @telemetry-dev/pi. `registerGlobal` is excluded on
+ * purpose: pi runs its own OpenTelemetry pipeline in-process, so this
+ * integration never touches the global provider — every span is created
+ * through the SDK's own tracer with explicit parenting.
+ */
+export type TelemetryDevPiOptions = Omit<TelemetryOptions, "registerGlobal">;
+
+export type { ClientOverrides };
+
+let initialized = false;
+
+/** Initializes the telemetry.dev SDK exactly once per process for this integration. */
+export function ensureInit(options: TelemetryDevPiOptions = {}, overrides?: ClientOverrides): void {
+  if (initialized) return;
+  initialized = true;
+  init(
+    {
+      ...options,
+      serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "pi",
+      // Enforce the guarantee above at runtime for untyped (plain JS) callers.
+      registerGlobal: false,
+    },
+    overrides,
+  );
+}
+
+/** Test seam for unit tests that need a fresh SDK singleton. */
+export async function resetForTesting(): Promise<void> {
+  initialized = false;
+  await shutdown();
+}

package/src/extension.ts

@@ -0,0 +1,376 @@
+import {
+  flush,
+  log,
+  startSpan,
+  type LogLevel,
+  type LogOptions,
+  type SpanHandle,
+  type TokenUsage,
+} from "@telemetry-dev/sdk";
+
+import { ensureInit, type ClientOverrides, type TelemetryDevPiOptions } from "./config.ts";
+
+/** Options for {@link telemetryDevExtension}. */
+export interface TelemetryDevExtensionOptions extends TelemetryDevPiOptions {
+  /** Value for `gen_ai.agent.name` on spans and logs. Defaults to `"pi"`. */
+  agentName?: string;
+}
+
+/**
+ * Structural slice of pi's `ExtensionContext` read by this integration.
+ *
+ * The host package (`@earendil-works/pi-coding-agent`) is an optional peer, so
+ * its types must not appear in this package's emitted declarations;
+ * assignability to the real host types is asserted in this package's tests.
+ */
+export interface TelemetryDevExtensionContext {
+  /** Current working directory. */
+  cwd: string;
+  /** Current model descriptor, when one is selected. */
+  model: unknown;
+  /** Read-only session manager exposing the session id. */
+  sessionManager: { getSessionId(): string | undefined };
+}
+
+/**
+ * Structural stand-in for the host `ExtensionAPI` passed to extension
+ * factories. The `never` parameters make any host event-subscription surface
+ * assignable; this integration is not meant to be called through this type.
+ */
+export interface TelemetryDevExtensionHost {
+  on(event: never, handler: never): void;
+}
+
+/** Structural stand-in for the host `ExtensionFactory` type. */
+export type TelemetryDevExtension = (pi: TelemetryDevExtensionHost) => void;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+type JsonRecord = { [key: string]: JsonValue };
+type Attrs = NonNullable<LogOptions["attributes"]>;
+
+function asRecord(cause: unknown): JsonRecord | undefined {
+  if (cause === null || cause instanceof Function || Object(cause) !== cause) return undefined;
+  return cause as JsonRecord;
+}
+
+function stringField(record: JsonRecord | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  return value?.constructor === String && value.length > 0 ? value : undefined;
+}
+
+function numberField(record: JsonRecord | undefined, key: string): number | undefined {
+  const value = record?.[key];
+  return value?.constructor === Number && Number.isFinite(value) ? value : undefined;
+}
+
+function booleanField(record: JsonRecord | undefined, key: string): boolean | undefined {
+  const value = record?.[key];
+  return value?.constructor === Boolean ? value : undefined;
+}
+
+function reportError(onError: Function | undefined, cause: unknown): void {
+  try {
+    onError?.call(undefined, cause);
+  } catch {
+    // telemetry must never fail a pi session.
+  }
+}
+
+function sessionId(ctx: TelemetryDevExtensionContext): string | undefined {
+  const id = ctx.sessionManager.getSessionId();
+  return id?.constructor === String && id.length > 0 ? id : undefined;
+}
+
+/** Joins the text blocks of a pi message content array. */
+function textContent(content: JsonValue | undefined): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  const parts: string[] = [];
+  for (const block of content) {
+    const record = asRecord(block);
+    if (record?.type === "text" && record.text?.constructor === String) parts.push(record.text);
+  }
+  return parts.length > 0 ? parts.join("\n") : undefined;
+}
+
+function usageFields(message: JsonRecord): TokenUsage | undefined {
+  const usage = asRecord(message.usage);
+  if (!usage) return undefined;
+  return {
+    inputTokens: numberField(usage, "input"),
+    outputTokens: numberField(usage, "output"),
+    totalTokens: numberField(usage, "totalTokens"),
+    cacheReadInputTokens: numberField(usage, "cacheRead"),
+    cacheCreationInputTokens: numberField(usage, "cacheWrite"),
+    reasoningOutputTokens: numberField(usage, "reasoning"),
+  };
+}
+
+/** Named error so `error.type` reflects the failure class instead of "Error". */
+function failureError(name: string, message: string | undefined): Error {
+  const error = new Error(message ?? name);
+  error.name = name;
+  return error;
+}
+
+/**
+ * Creates a pi extension factory that exports agent loops, model calls, tool
+ * executions, and lifecycle logs to telemetry.dev.
+ *
+ * Trace shape per user prompt: one `invoke_agent` span, with one `chat {model}`
+ * child span per assistant message and one `execute_tool {tool}` child span per
+ * tool execution. Logs join the same session via `gen_ai.conversation.id`.
+ */
+export function telemetryDevExtension(
+  options: TelemetryDevExtensionOptions = {},
+  overrides?: ClientOverrides,
+): TelemetryDevExtension {
+  const { agentName = "pi", ...sdkOptions } = options;
+  const onError = sdkOptions.onError;
+
+  return (pi) => {
+    try {
+      ensureInit(sdkOptions, overrides);
+    } catch (error) {
+      reportError(onError, error);
+    }
+
+    /** Calls through `pi` so the host's `on` keeps its `this` binding. */
+    function register<Event>(
+      event: string,
+      handler: (event: Event, ctx: TelemetryDevExtensionContext) => void | Promise<void>,
+    ): void {
+      pi.on(event as never, handler as never);
+    }
+
+    let agentSpan: SpanHandle | undefined;
+    let assistantStartedAt: number | undefined;
+    let pendingPrompt: string | undefined;
+    /** Latest agent_end outcome, applied to the prompt span when the run settles. */
+    let lastRunResult: Parameters<SpanHandle["end"]>[0];
+    /** Chat span that issued each pending tool call, so tool spans nest under it. */
+    const chatSpanByToolCall = new Map<string, SpanHandle>();
+    const toolSpans = new Map<string, SpanHandle>();
+
+    function baseAttributes(ctx: TelemetryDevExtensionContext) {
+      return {
+        "gen_ai.conversation.id": sessionId(ctx),
+        "gen_ai.agent.name": agentName,
+      };
+    }
+
+    function emit(
+      eventName: string,
+      ctx: TelemetryDevExtensionContext,
+      level: LogLevel,
+      message: string,
+      attributes: Attrs = {},
+    ): void {
+      log(message, { level, eventName, attributes: { ...baseAttributes(ctx), ...attributes } });
+    }
+
+    function spanAttributes(ctx: TelemetryDevExtensionContext): Record<string, string> {
+      const id = sessionId(ctx);
+      return id ? { "gen_ai.conversation.id": id } : {};
+    }
+
+    function endDanglingToolSpans(): void {
+      for (const span of toolSpans.values()) {
+        span.end({ error: failureError("incomplete", "tool execution did not complete") });
+      }
+      toolSpans.clear();
+      chatSpanByToolCall.clear();
+    }
+
+    function endAgentSpan(fields: Parameters<SpanHandle["end"]>[0]): void {
+      endDanglingToolSpans();
+      agentSpan?.end(fields);
+      agentSpan = undefined;
+    }
+
+    function on<Event>(
+      event: string,
+      handler: (event: Event, ctx: TelemetryDevExtensionContext) => void,
+    ): void {
+      register(event, (payload: Event, ctx) => {
+        try {
+          handler(payload, ctx);
+        } catch (error) {
+          reportError(onError, error);
+        }
+      });
+    }
+
+    register("before_agent_start", (event: { prompt?: JsonValue }) => {
+      try {
+        pendingPrompt = event.prompt?.constructor === String ? event.prompt : undefined;
+      } catch (error) {
+        reportError(onError, error);
+      }
+    });
+
+    on("agent_start", (_event, ctx) => {
+      // Automatic retries, compaction, and queued continuations re-enter the
+      // agent loop before the run settles; keep the original prompt span open.
+      if (agentSpan) return;
+      agentSpan = startSpan("invoke_agent", {
+        type: "agent",
+        agentName,
+        input: pendingPrompt,
+        attributes: spanAttributes(ctx),
+      });
+      pendingPrompt = undefined;
+    });
+
+    on("agent_end", (event: { messages: JsonValue[] }, _ctx) => {
+      const messages = Array.isArray(event.messages) ? event.messages : [];
+      let lastAssistant: JsonRecord | undefined;
+      for (const message of messages) {
+        const record = asRecord(message);
+        if (record?.role === "assistant") lastAssistant = record;
+      }
+      const stopReason = stringField(lastAssistant, "stopReason");
+      const errorMessage = stringField(lastAssistant, "errorMessage");
+      // agent_end only closes one low-level run; pi may remove a retryable
+      // failure and start another run before the prompt settles. Record the
+      // outcome and close the span at agent_settled.
+      lastRunResult = {
+        output: textContent(lastAssistant?.content),
+        finishReason: stopReason,
+        error: stopReason === "error" ? failureError(stopReason, errorMessage) : undefined,
+      };
+      void flush();
+    });
+
+    on("agent_settled", (_event, _ctx) => {
+      endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
+      lastRunResult = undefined;
+      void flush();
+    });
+
+    on("message_start", (event: { message: JsonValue }, _ctx) => {
+      const message = asRecord(event.message);
+      if (message?.role === "assistant") assistantStartedAt = Date.now();
+    });
+
+    on("message_end", (event: { message: JsonValue }, ctx) => {
+      const message = asRecord(event.message);
+      if (message?.role !== "assistant") return;
+      const startTime = assistantStartedAt;
+      assistantStartedAt = undefined;
+      const endTime = Date.now();
+      const model = stringField(message, "model");
+      const responseModel = stringField(message, "responseModel") ?? model;
+      const errorMessage = stringField(message, "errorMessage");
+      const stopReason = stringField(message, "stopReason");
+      const span = startSpan(model ? `chat ${model}` : "chat", {
+        type: "generation",
+        parent: agentSpan,
+        startTime,
+        model,
+        provider: stringField(message, "provider"),
+        responseModel,
+        responseId: stringField(message, "responseId"),
+        usage: usageFields(message),
+        costUsd: numberField(asRecord(asRecord(message.usage)?.cost), "total"),
+        finishReason: stopReason,
+        output: textContent(message.content),
+        error: stopReason === "error" ? failureError(stopReason, errorMessage) : undefined,
+        attributes: spanAttributes(ctx),
+      });
+      for (const block of Array.isArray(message.content) ? message.content : []) {
+        const record = asRecord(block);
+        if (record?.type === "toolCall" && record.id?.constructor === String) {
+          chatSpanByToolCall.set(record.id, span);
+        }
+      }
+      span.end({ endTime });
+    });
+
+    on(
+      "tool_execution_start",
+      (event: { toolCallId: string; toolName: string; args: JsonValue }, ctx) => {
+        const span = startSpan(`execute_tool ${event.toolName}`, {
+          type: "tool",
+          parent: chatSpanByToolCall.get(event.toolCallId) ?? agentSpan,
+          toolName: event.toolName,
+          toolCallId: event.toolCallId,
+          input: event.args,
+          attributes: spanAttributes(ctx),
+        });
+        chatSpanByToolCall.delete(event.toolCallId);
+        toolSpans.set(event.toolCallId, span);
+      },
+    );
+
+    on(
+      "tool_execution_end",
+      (
+        event: { toolCallId: string; toolName: string; result: JsonValue; isError: boolean },
+        _ctx,
+      ) => {
+        const span = toolSpans.get(event.toolCallId);
+        if (!span) return;
+        toolSpans.delete(event.toolCallId);
+        const resultText = textContent(asRecord(event.result)?.content);
+        span.end({
+          output: event.result,
+          error: event.isError ? failureError("ToolExecutionError", resultText) : undefined,
+        });
+      },
+    );
+
+    on("turn_start", (event: { turnIndex: number }, ctx) => {
+      emit("turn_start", ctx, "debug", "Turn started", { "pi.turn.index": event.turnIndex });
+    });
+
+    on("turn_end", (event: { turnIndex: number }, ctx) => {
+      emit("turn_end", ctx, "debug", "Turn completed", { "pi.turn.index": event.turnIndex });
+    });
+
+    on("session_start", (event: { reason: string; previousSessionFile?: string }, ctx) => {
+      const model = asRecord(ctx.model);
+      emit("session_start", ctx, "info", "Session started", {
+        "gen_ai.request.model": stringField(model, "id"),
+        "gen_ai.provider.name": stringField(model, "provider"),
+        "pi.cwd": ctx.cwd,
+        "pi.session.reason": event.reason,
+      });
+    });
+
+    on("session_compact", (event: { reason: string; fromExtension: boolean }, ctx) => {
+      emit("session_compact", ctx, "info", "Session compacted", {
+        "pi.compaction.from_extension": booleanField(asRecord(event), "fromExtension"),
+        "pi.compaction.reason": event.reason,
+      });
+    });
+
+    on(
+      "model_select",
+      (event: { model: JsonValue; previousModel: JsonValue; source: string }, ctx) => {
+        emit("model_select", ctx, "info", "Model changed", {
+          "pi.model.from": stringField(asRecord(event.previousModel), "id"),
+          "pi.model.source": event.source,
+          "pi.model.to": stringField(asRecord(event.model), "id"),
+        });
+      },
+    );
+
+    register(
+      "session_shutdown",
+      async (event: { reason?: string }, ctx: TelemetryDevExtensionContext) => {
+        try {
+          if (agentSpan || toolSpans.size > 0) {
+            endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
+            lastRunResult = undefined;
+          }
+          emit("session_shutdown", ctx, "info", "Session shutdown", {
+            "pi.session.reason": event.reason,
+          });
+          await flush();
+        } catch (error) {
+          reportError(onError, error);
+        }
+      },
+    );
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { TelemetryDevPiOptions } from "./config.ts";
+export {
+  telemetryDevExtension,
+  type TelemetryDevExtension,
+  type TelemetryDevExtensionContext,
+  type TelemetryDevExtensionHost,
+  type TelemetryDevExtensionOptions,
+} from "./extension.ts";

package/src/register.ts

@@ -0,0 +1,8 @@
+import { telemetryDevExtension } from "./extension.ts";
+
+/**
+ * Ready-to-load pi extension entry configured from `TELEMETRY_DEV_*`
+ * environment variables. Referenced by this package's `pi.extensions`
+ * manifest so `@telemetry-dev/pi` works as an installed pi package.
+ */
+export default telemetryDevExtension();