@telemetry-dev/omp 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,101 @@
+# @telemetry-dev/omp
+
+Telemetry integration for the [Oh My Pi (omp)](https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent)
+coding agent and [telemetry.dev](https://telemetry.dev). It records omp agent loops, model calls,
+tool executions, and lifecycle events without changing omp's behavior.
+
+## Install
+
+Create `~/.omp/agent/extensions/telemetry-dev.ts` (global) or
+`.omp/extensions/telemetry-dev.ts` (project):
+
+```ts
+import { telemetryDevExtension } from "@telemetry-dev/omp";
+export default telemetryDevExtension();
+```
+
+Install `@telemetry-dev/omp` somewhere that file can resolve it. The package also ships an
+`omp.extensions` manifest pointing at `@telemetry-dev/omp/register`, so installing it as an omp
+package loads the extension automatically with environment-driven configuration.
+
+The integration targets `@oh-my-pi/pi-coding-agent` 17.x. The omp package is an optional peer
+dependency because omp bundles its extension API and provides it to loaded 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       | `omp`                          | OpenTelemetry service name.                                             |
+
+All four are also settable through SDK options when loading the extension directly:
+
+```ts
+import { telemetryDevExtension } from "@telemetry-dev/omp";
+
+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, model, response id,
+  finish reason, usage (including cache and reasoning tokens), TTFT, and provider-reported duration;
+- 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 auto-retry.
+
+Every span and log reads `ctx.sessionManager.getSessionId()` when its event fires and records it as
+`gen_ai.conversation.id`, so session switches, branches, and tree navigation attach telemetry to the
+correct session. Logs also carry `gen_ai.agent.name` and the raw omp 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 the process exits.
+
+Chat spans use omp's own message timestamps: start = `message.timestamp`, end = start +
+`message.duration`, so span timing matches provider-reported request duration rather than local
+event-dispatch time.
+
+## 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 omp reports them.
+
+## Limitations
+
+- `tool_call` and `tool_result` are intentionally not intercepted. In omp, an uncaught `tool_call`
+  handler error blocks the tool (fail-closed), 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.
+- omp does not report client-side cost; telemetry.dev computes cost server-side from usage and
+  pricing data.
+- Subagents (task tool) run in separate processes with their own extension instances, so their
+  telemetry appears as separate sessions.
+- Initialization is one-shot. Loading the extension more than once does not replace the first
+  configuration.

package/dist/extension-CItLaHEs.mjs

@@ -0,0 +1,316 @@
+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 ?? "omp",
+		registerGlobal: false
+	}, overrides);
+}
+//#endregion
+//#region src/extension.ts
+function asRecord(value) {
+	if (value === null || Array.isArray(value) || !(value instanceof Object)) return void 0;
+	return value;
+}
+function stringField(record, key) {
+	const value = record?.[key];
+	if (value === void 0 || value === null || value.constructor !== String || value === "") return void 0;
+	return value;
+}
+function numberField(record, key) {
+	const value = record?.[key];
+	if (value === void 0 || value === null || value.constructor !== Number) return void 0;
+	const number = value;
+	return Number.isFinite(number) ? number : void 0;
+}
+function booleanField(record, key) {
+	const value = record?.[key];
+	if (value === void 0 || value === null || value.constructor !== Boolean) return void 0;
+	return value;
+}
+function reportError(onError, cause) {
+	try {
+		onError?.(cause instanceof Error ? cause : new Error(String(cause)));
+	} catch {}
+}
+function sessionId(ctx) {
+	const id = ctx.sessionManager.getSessionId();
+	return id && id.length > 0 ? id : void 0;
+}
+/** Joins the text blocks of an omp message content array. */
+function textContent(content) {
+	if (!Array.isArray(content)) return void 0;
+	const parts = [];
+	for (const block of content) {
+		const record = asRecord(block);
+		const text = record?.text;
+		if (record?.type === "text" && text !== void 0 && text !== null && text.constructor === String) parts.push(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, "reasoningTokens")
+	};
+}
+function assistantMessageKey(message) {
+	const timestamp = numberField(message, "timestamp");
+	if (timestamp === void 0) return void 0;
+	return JSON.stringify([
+		timestamp,
+		stringField(message, "provider") ?? "",
+		stringField(message, "model") ?? "",
+		stringField(message, "responseId") ?? "",
+		stringField(message, "stopReason") ?? ""
+	]);
+}
+/** 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 an omp extension factory that exports agent loops, model calls, and
+* tool executions 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. Session lifecycle, compaction, and retry events are emitted
+* as logs joined via `gen_ai.conversation.id`.
+*/
+function telemetryDevExtension(options = {}, overrides) {
+	const { agentName = "omp", ...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.bind(pi)(event, handler);
+		}
+		let agentSpan;
+		/** Stable key of the latest assistant message emitted for the active agent span. */
+		let agentMessageKey;
+		let pendingPrompt;
+		/** 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;
+			agentMessageKey = void 0;
+		}
+		function on(event, handler) {
+			register(event, (payload, ctx) => {
+				try {
+					return handler(payload, ctx);
+				} catch (error) {
+					reportError(onError, error);
+					return;
+				}
+			});
+		}
+		register("before_agent_start", (event) => {
+			try {
+				pendingPrompt = stringField(event, "prompt");
+			} catch (error) {
+				reportError(onError, error);
+			}
+		});
+		on("agent_start", (_event, ctx) => {
+			if (agentSpan) {
+				if (pendingPrompt === void 0) return;
+				endAgentSpan({ finishReason: "incomplete" });
+			}
+			agentSpan = startSpan("invoke_agent", {
+				type: "agent",
+				agentName,
+				input: pendingPrompt,
+				attributes: spanAttributes(ctx)
+			});
+			pendingPrompt = void 0;
+		});
+		on("agent_end", (event, _ctx) => {
+			if (!agentSpan) return;
+			if (event.willContinue === true) {
+				flush();
+				return;
+			}
+			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;
+			}
+			if (lastAssistant) {
+				const eventMessageKey = assistantMessageKey(lastAssistant);
+				if (eventMessageKey === void 0 || eventMessageKey !== agentMessageKey) {
+					flush();
+					return;
+				}
+			}
+			const stopReason = stringField(lastAssistant, "stopReason");
+			const errorMessage = stringField(lastAssistant, "errorMessage");
+			endAgentSpan({
+				output: textContent(lastAssistant?.content),
+				finishReason: stopReason,
+				error: stopReason === "error" ? failureError(stopReason, errorMessage) : void 0
+			});
+			flush();
+		});
+		on("message_end", (event, ctx) => {
+			const message = asRecord(event.message);
+			if (message?.role !== "assistant") return;
+			if (agentSpan) agentMessageKey = assistantMessageKey(message);
+			const model = stringField(message, "model");
+			const startTime = numberField(message, "timestamp");
+			const duration = numberField(message, "duration");
+			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"),
+				responseId: stringField(message, "responseId"),
+				usage: usageFields(message),
+				finishReason: stopReason,
+				timeToFirstChunkMs: numberField(message, "ttft"),
+				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);
+				const id = stringField(record, "id");
+				if (record?.type === "toolCall" && id !== void 0) chatSpanByToolCall.set(id, span);
+			}
+			span.end({ endTime: startTime !== void 0 && duration !== void 0 ? startTime + duration : void 0 });
+		});
+		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", { "omp.turn.index": event.turnIndex });
+		});
+		on("turn_end", (event, ctx) => {
+			emit("turn_end", ctx, "debug", "Turn completed", { "omp.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"),
+				"omp.cwd": ctx.cwd
+			});
+		});
+		on("session_switch", (_event, ctx) => {
+			emit("session_switch", ctx, "info", "Session switched");
+		});
+		on("session_branch", (_event, ctx) => {
+			emit("session_branch", ctx, "info", "Session branched");
+		});
+		on("session_compact", (_event, ctx) => {
+			emit("session_compact", ctx, "info", "Session compacted");
+		});
+		on("auto_compaction_start", (event, ctx) => {
+			emit("auto_compaction_start", ctx, "info", `Auto-compaction started (${event.reason})`, {
+				"omp.compaction.reason": event.reason,
+				"omp.compaction.action": event.action
+			});
+		});
+		on("auto_compaction_end", (event, ctx) => {
+			const record = asRecord(event);
+			const errorMessage = stringField(record, "errorMessage");
+			emit("auto_compaction_end", ctx, errorMessage ? "error" : "info", errorMessage ? `Auto-compaction failed: ${errorMessage}` : "Auto-compaction completed", {
+				"omp.compaction.action": event.action,
+				"omp.compaction.aborted": booleanField(record, "aborted"),
+				"omp.compaction.skipped": booleanField(record, "skipped")
+			});
+		});
+		on("auto_retry_start", (event, ctx) => {
+			emit("auto_retry_start", ctx, "warn", `Auto-retry attempt ${event.attempt}/${event.maxAttempts}: ${event.errorMessage}`, {
+				"omp.retry.attempt": event.attempt,
+				"omp.retry.max_attempts": event.maxAttempts,
+				"omp.retry.delay_ms": event.delayMs
+			});
+		});
+		on("auto_retry_end", (event, ctx) => {
+			const finalError = stringField(asRecord(event), "finalError");
+			emit("auto_retry_end", ctx, event.success ? "info" : "error", event.success ? `Auto-retry succeeded after ${event.attempt} attempt(s)` : `Auto-retry failed: ${finalError ?? "unknown error"}`, { "omp.retry.attempt": event.attempt });
+		});
+		register("session_shutdown", async (_event, ctx) => {
+			try {
+				if (agentSpan) endAgentSpan({ finishReason: "incomplete" });
+				emit("session_shutdown", ctx, "info", "Session shutdown");
+				await flush();
+			} catch (error) {
+				reportError(onError, error);
+			}
+		});
+	};
+}
+//#endregion
+export { telemetryDevExtension as t };

package/dist/extension-o2etehO0.d.mts

@@ -0,0 +1,59 @@
+import { ClientOverrides, TelemetryOptions } from "@telemetry-dev/sdk";
+
+//#region src/config.d.ts
+/**
+ * SDK options accepted by @telemetry-dev/omp. `registerGlobal` is excluded on
+ * purpose: omp 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 TelemetryDevOmpOptions = Omit<TelemetryOptions, "registerGlobal">;
+//#endregion
+//#region src/extension.d.ts
+/** Options for {@link telemetryDevExtension}. */
+interface TelemetryDevExtensionOptions extends TelemetryDevOmpOptions {
+  /** Value for `gen_ai.agent.name` on spans and logs. Defaults to `"omp"`. */
+  agentName?: string;
+}
+/**
+ * Structural slice of omp's `ExtensionContext` read by this integration.
+ *
+ * The host package (`@oh-my-pi/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: {
+    id?: string;
+    provider?: string;
+  } | undefined;
+  /** 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 an omp extension factory that exports agent loops, model calls, and
+ * tool executions 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. Session lifecycle, compaction, and retry events are emitted
+ * as logs joined via `gen_ai.conversation.id`.
+ */
+declare function telemetryDevExtension(options?: TelemetryDevExtensionOptions, overrides?: ClientOverrides): TelemetryDevExtension;
+//#endregion
+export { telemetryDevExtension as a, TelemetryDevExtensionOptions as i, TelemetryDevExtensionContext as n, TelemetryDevOmpOptions as o, TelemetryDevExtensionHost as r, TelemetryDevExtension as t };

package/dist/index.d.mts

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

package/dist/index.mjs

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

package/dist/register.d.mts

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

package/dist/register.mjs

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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@telemetry-dev/omp",
+  "version": "0.1.0",
+  "description": "Oh My Pi (omp) coding-agent telemetry integration for telemetry.dev.",
+  "keywords": [
+    "agents",
+    "coding-agent",
+    "genai",
+    "llm",
+    "observability",
+    "oh-my-pi",
+    "omp",
+    "opentelemetry",
+    "telemetry",
+    "tracing"
+  ],
+  "homepage": "https://telemetry.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telemetry-dev/telemetry.dev.git",
+    "directory": "packages/omp"
+  },
+  "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": {
+    "@oh-my-pi/pi-coding-agent": "17.1.8",
+    "@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": {
+    "@oh-my-pi/pi-coding-agent": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "@oh-my-pi/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "omp": {
+    "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,37 @@
+import { init, shutdown, type ClientOverrides, type TelemetryOptions } from "@telemetry-dev/sdk";
+
+/**
+ * SDK options accepted by @telemetry-dev/omp. `registerGlobal` is excluded on
+ * purpose: omp 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 TelemetryDevOmpOptions = 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: TelemetryDevOmpOptions = {},
+  overrides?: ClientOverrides,
+): void {
+  if (initialized) return;
+  initialized = true;
+  init(
+    {
+      ...options,
+      serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "omp",
+      // 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,482 @@
+import {
+  flush,
+  log,
+  startSpan,
+  type LogLevel,
+  type SpanHandle,
+  type TokenUsage,
+} from "@telemetry-dev/sdk";
+
+import { ensureInit, type ClientOverrides, type TelemetryDevOmpOptions } from "./config.ts";
+
+/** Options for {@link telemetryDevExtension}. */
+export interface TelemetryDevExtensionOptions extends TelemetryDevOmpOptions {
+  /** Value for `gen_ai.agent.name` on spans and logs. Defaults to `"omp"`. */
+  agentName?: string;
+}
+
+/**
+ * Structural slice of omp's `ExtensionContext` read by this integration.
+ *
+ * The host package (`@oh-my-pi/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: { id?: string; provider?: string } | undefined;
+  /** 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
+  | undefined
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+type Attrs = { [key: string]: JsonValue };
+type JsonRecord = { [key: string]: JsonValue };
+
+function asRecord(value: JsonValue): JsonRecord | undefined {
+  if (value === null || Array.isArray(value) || !(value instanceof Object)) return undefined;
+  return value as JsonRecord;
+}
+
+function stringField(record: JsonRecord | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  if (value === undefined || value === null || value.constructor !== String || value === "")
+    return undefined;
+  return value as string;
+}
+
+function numberField(record: JsonRecord | undefined, key: string): number | undefined {
+  const value = record?.[key];
+  if (value === undefined || value === null || value.constructor !== Number) return undefined;
+  const number = value as number;
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function booleanField(record: JsonRecord | undefined, key: string): boolean | undefined {
+  const value = record?.[key];
+  if (value === undefined || value === null || value.constructor !== Boolean) return undefined;
+  return value as boolean;
+}
+
+function reportError(onError: ((error: Error) => void) | undefined, cause: unknown): void {
+  try {
+    onError?.(cause instanceof Error ? cause : new Error(String(cause)));
+  } catch {
+    // telemetry must never fail an omp session.
+  }
+}
+
+function sessionId(ctx: TelemetryDevExtensionContext): string | undefined {
+  const id = ctx.sessionManager.getSessionId();
+  return id && id.length > 0 ? id : undefined;
+}
+
+/** Joins the text blocks of an omp message content array. */
+function textContent(content: JsonValue): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  const parts: string[] = [];
+  for (const block of content) {
+    const record = asRecord(block);
+    const text = record?.text;
+    if (
+      record?.type === "text" &&
+      text !== undefined &&
+      text !== null &&
+      text.constructor === String
+    ) {
+      parts.push(text as string);
+    }
+  }
+  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, "reasoningTokens"),
+  };
+}
+
+function assistantMessageKey(message: JsonRecord): string | undefined {
+  const timestamp = numberField(message, "timestamp");
+  if (timestamp === undefined) return undefined;
+  return JSON.stringify([
+    timestamp,
+    stringField(message, "provider") ?? "",
+    stringField(message, "model") ?? "",
+    stringField(message, "responseId") ?? "",
+    stringField(message, "stopReason") ?? "",
+  ]);
+}
+
+/** 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 an omp extension factory that exports agent loops, model calls, and
+ * tool executions 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. Session lifecycle, compaction, and retry events are emitted
+ * as logs joined via `gen_ai.conversation.id`.
+ */
+export function telemetryDevExtension(
+  options: TelemetryDevExtensionOptions = {},
+  overrides?: ClientOverrides,
+): TelemetryDevExtension {
+  const { agentName = "omp", ...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<E extends JsonValue>(
+      event: string,
+      handler: (event: E, ctx: TelemetryDevExtensionContext) => void | Promise<void>,
+    ): void {
+      const registerEvent = pi.on.bind(pi) as (
+        event: string,
+        handler: (event: E, ctx: TelemetryDevExtensionContext) => void | Promise<void>,
+      ) => void;
+      registerEvent(event, handler);
+    }
+
+    let agentSpan: SpanHandle | undefined;
+    /** Stable key of the latest assistant message emitted for the active agent span. */
+    let agentMessageKey: string | undefined;
+    let pendingPrompt: string | undefined;
+    /** 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,
+      } satisfies Attrs;
+    }
+
+    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;
+      agentMessageKey = undefined;
+    }
+
+    function on<E extends JsonValue>(
+      event: string,
+      handler: (event: E, ctx: TelemetryDevExtensionContext) => void | Promise<void>,
+    ): void {
+      register<E>(event, (payload, ctx) => {
+        try {
+          return handler(payload, ctx);
+        } catch (error) {
+          reportError(onError, error);
+          return undefined;
+        }
+      });
+    }
+
+    register("before_agent_start", (event: { prompt?: JsonValue }) => {
+      try {
+        pendingPrompt = stringField(event, "prompt");
+      } catch (error) {
+        reportError(onError, error);
+      }
+    });
+
+    on("agent_start", (_event, ctx) => {
+      if (agentSpan) {
+        if (pendingPrompt === undefined) {
+          // Continuations (auto-retry, compaction, queued continuations)
+          // re-enter the loop without a fresh before_agent_start prompt, and
+          // the host launches the willContinue agent_end notification without
+          // awaiting it, so this agent_start can arrive before that event.
+          // Keep the original prompt span open until the terminal agent_end.
+          return;
+        }
+        // A fresh prompt while a previous loop never emitted agent_end: close
+        // the dangling span instead of silently merging two prompts into it.
+        endAgentSpan({ finishReason: "incomplete" });
+      }
+      agentSpan = startSpan("invoke_agent", {
+        type: "agent",
+        agentName,
+        input: pendingPrompt,
+        attributes: spanAttributes(ctx),
+      });
+      pendingPrompt = undefined;
+    });
+
+    on("agent_end", (event: { messages: JsonValue[]; willContinue?: boolean }, _ctx) => {
+      if (!agentSpan) return;
+      if (event.willContinue === true) {
+        // The host scheduled another loop for this prompt (auto-retry,
+        // compaction, or a queued continuation); this agent_end is not
+        // terminal, so keep the prompt span open.
+        void flush();
+        return;
+      }
+      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;
+      }
+      if (lastAssistant) {
+        const eventMessageKey = assistantMessageKey(lastAssistant);
+        if (eventMessageKey === undefined || eventMessageKey !== agentMessageKey) {
+          void flush();
+          return;
+        }
+      }
+      const stopReason = stringField(lastAssistant, "stopReason");
+      const errorMessage = stringField(lastAssistant, "errorMessage");
+      endAgentSpan({
+        output: textContent(lastAssistant?.content),
+        finishReason: stopReason,
+        error: stopReason === "error" ? failureError(stopReason, errorMessage) : undefined,
+      });
+      void flush();
+    });
+
+    on("message_end", (event: { message: JsonValue }, ctx) => {
+      const message = asRecord(event.message);
+      if (message?.role !== "assistant") return;
+      if (agentSpan) agentMessageKey = assistantMessageKey(message);
+      const model = stringField(message, "model");
+      const startTime = numberField(message, "timestamp");
+      const duration = numberField(message, "duration");
+      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"),
+        responseId: stringField(message, "responseId"),
+        usage: usageFields(message),
+        finishReason: stopReason,
+        timeToFirstChunkMs: numberField(message, "ttft"),
+        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);
+        const id = stringField(record, "id");
+        if (record?.type === "toolCall" && id !== undefined) {
+          chatSpanByToolCall.set(id, span);
+        }
+      }
+      span.end({
+        endTime:
+          startTime !== undefined && duration !== undefined ? startTime + duration : undefined,
+      });
+    });
+
+    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", { "omp.turn.index": event.turnIndex });
+    });
+
+    on("turn_end", (event: { turnIndex: number }, ctx) => {
+      emit("turn_end", ctx, "debug", "Turn completed", { "omp.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"),
+        "omp.cwd": ctx.cwd,
+      });
+    });
+
+    on("session_switch", (_event, ctx) => {
+      emit("session_switch", ctx, "info", "Session switched");
+    });
+
+    on("session_branch", (_event, ctx) => {
+      emit("session_branch", ctx, "info", "Session branched");
+    });
+
+    on("session_compact", (_event, ctx) => {
+      emit("session_compact", ctx, "info", "Session compacted");
+    });
+
+    on("auto_compaction_start", (event: { reason: string; action: string }, ctx) => {
+      emit("auto_compaction_start", ctx, "info", `Auto-compaction started (${event.reason})`, {
+        "omp.compaction.reason": event.reason,
+        "omp.compaction.action": event.action,
+      });
+    });
+
+    on(
+      "auto_compaction_end",
+      (
+        event: {
+          action: string;
+          aborted: boolean;
+          willRetry: boolean;
+          errorMessage?: string;
+          skipped?: boolean;
+        },
+        ctx,
+      ) => {
+        const record = asRecord(event);
+        const errorMessage = stringField(record, "errorMessage");
+        emit(
+          "auto_compaction_end",
+          ctx,
+          errorMessage ? "error" : "info",
+          errorMessage ? `Auto-compaction failed: ${errorMessage}` : "Auto-compaction completed",
+          {
+            "omp.compaction.action": event.action,
+            "omp.compaction.aborted": booleanField(record, "aborted"),
+            "omp.compaction.skipped": booleanField(record, "skipped"),
+          },
+        );
+      },
+    );
+
+    on(
+      "auto_retry_start",
+      (
+        event: { attempt: number; maxAttempts: number; delayMs: number; errorMessage: string },
+        ctx,
+      ) => {
+        emit(
+          "auto_retry_start",
+          ctx,
+          "warn",
+          `Auto-retry attempt ${event.attempt}/${event.maxAttempts}: ${event.errorMessage}`,
+          {
+            "omp.retry.attempt": event.attempt,
+            "omp.retry.max_attempts": event.maxAttempts,
+            "omp.retry.delay_ms": event.delayMs,
+          },
+        );
+      },
+    );
+
+    on(
+      "auto_retry_end",
+      (event: { success: boolean; attempt: number; finalError?: string }, ctx) => {
+        const finalError = stringField(asRecord(event), "finalError");
+        emit(
+          "auto_retry_end",
+          ctx,
+          event.success ? "info" : "error",
+          event.success
+            ? `Auto-retry succeeded after ${event.attempt} attempt(s)`
+            : `Auto-retry failed: ${finalError ?? "unknown error"}`,
+          { "omp.retry.attempt": event.attempt },
+        );
+      },
+    );
+
+    register("session_shutdown", async (_event: JsonValue, ctx: TelemetryDevExtensionContext) => {
+      try {
+        if (agentSpan) endAgentSpan({ finishReason: "incomplete" });
+        emit("session_shutdown", ctx, "info", "Session shutdown");
+        await flush();
+      } catch (error) {
+        reportError(onError, error);
+      }
+    });
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { TelemetryDevOmpOptions } 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 omp extension entry configured from `TELEMETRY_DEV_*`
+ * environment variables. Referenced by this package's `omp.extensions`
+ * manifest so `@telemetry-dev/omp` works as an installed omp package.
+ */
+export default telemetryDevExtension();