@telemetry-dev/pi 0.1.0 → 0.1.2

package/README.md

@@ -54,45 +54,54 @@ options.
 
 ## Trace shape
 
-A typical prompt produces this hierarchy:
+A typical session 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)
+session
+└── invoke_agent
+    ├── chat {model}                  (assistant message)
+    │   ├── execute_tool {toolName}   (tool calls from 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;
+- one `session` wrapper span for the full pi session;
+- one `invoke_agent` span for each prompt, with the prompt and the final assistant content;
+- one nested `chat {model}` span for each completed assistant message, with the provider, models,
+  response id, finish reason, usage, pi cost, provider request, and all returned content blocks;
+- one `execute_tool {toolName}` span for each tool execution, under the `chat` span that issued the
+  call. If no message matches the tool call id, the span is under the `invoke_agent` span. The span
+  includes 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`.
+Each span and log reads `ctx.sessionManager.getSessionId()` when its event occurs. The span or log
+records the value as `gen_ai.conversation.id`. This keeps `/new`, `/resume`, `/fork`, and `/reload`
+events with the new session. Logs also have `gen_ai.agent.name` and the 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.
+`agent_end` records the last run result and starts an asynchronous flush. `agent_settled` closes
+unfinished tool spans and the prompt span. `session_shutdown` closes an unfinished prompt and the
+session span, then waits for the final flush. It does not shut 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.
+The prompt includes its image blocks. Chat input records the provider-formatted request from
+`before_provider_request`, after all `context` handlers and pi's model-message conversion.
+This conversion removes `!!` shell output and custom-message `details` from the model input.
+System instructions come from the effective `ctx.getSystemPrompt()` at the request boundary, after all
+`before_agent_start` handlers. Chat output contains all returned content blocks. The integration also
+records tool arguments and tool results.
 
-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.
+These values obey the telemetry.dev SDK `captureInput` and `captureOutput` settings, which default to
+`true`. Use `mask` to remove values before capture. Use `maxAttributeLength` to limit serialized
+attributes.
 
 ## Limitations
 
+- Chat input uses each provider's request shape, not pi's raw session messages. Pi's public hooks do
+  not expose the final wire payload. A later `before_provider_request` handler can replace the request
+  after capture. Custom providers must call pi's `onPayload` callback for request and system
+  instruction capture. Without that callback, those fields are absent. Prompt, output, and tool
+  capture still work.
 - 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`

package/dist/{extension-CZQ_PvAB.d.mts → extension-DhhRAe5R.d.mts}

@@ -7,7 +7,7 @@ import { ClientOverrides, TelemetryOptions } from "@telemetry-dev/sdk";
  * integration never touches the global provider — every span is created
  * through the SDK's own tracer with explicit parenting.
  */
-type TelemetryDevPiOptions = Omit<TelemetryOptions, "registerGlobal">;
+type TelemetryDevPiOptions = Omit<TelemetryOptions, "registerGlobal" | "sdkName">;
 //#endregion
 //#region src/extension.d.ts
 /** Options for {@link telemetryDevExtension}. */
@@ -31,6 +31,8 @@ interface TelemetryDevExtensionContext {
   sessionManager: {
     getSessionId(): string | undefined;
   };
+  /** Effective system prompt after all before_agent_start handlers. */
+  getSystemPrompt(): string;
 }
 /**
  * Structural stand-in for the host `ExtensionAPI` passed to extension
@@ -46,9 +48,12 @@ 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`.
+ * Trace shape: one trace per pi session with a `session` root span. Each user
+ * prompt is an `invoke_agent` child, with one `chat {model}` child span per
+ * assistant message and one `execute_tool {tool}` child span per tool
+ * execution. Payloads include the prompt and its images, the provider-formatted
+ * request, and every returned content block (thinking, text, tool calls).
+ * Logs join the same session through `gen_ai.conversation.id`.
  */
 declare function telemetryDevExtension(options?: TelemetryDevExtensionOptions, overrides?: ClientOverrides): TelemetryDevExtension;
 //#endregion

package/dist/{extension-DLbX-piL.mjs → extension-V9WCbPBU.mjs}

@@ -8,6 +8,7 @@ function ensureInit(options = {}, overrides) {
 	init({
 		...options,
 		serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "pi",
+		sdkName: "@telemetry-dev/pi",
 		registerGlobal: false
 	}, overrides);
 }
@@ -70,9 +71,12 @@ function failureError(name, message) {
 * 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`.
+* Trace shape: one trace per pi session with a `session` root span. Each user
+* prompt is an `invoke_agent` child, with one `chat {model}` child span per
+* assistant message and one `execute_tool {tool}` child span per tool
+* execution. Payloads include the prompt and its images, the provider-formatted
+* request, and every returned content block (thinking, text, tool calls).
+* Logs join the same session through `gen_ai.conversation.id`.
 */
 function telemetryDevExtension(options = {}, overrides) {
 	const { agentName = "pi", ...sdkOptions } = options;
@@ -87,9 +91,13 @@ function telemetryDevExtension(options = {}, overrides) {
 		function register(event, handler) {
 			pi.on(event, handler);
 		}
+		/** Root of the one trace per pi session; every prompt span nests under it. */
+		let sessionSpan;
 		let agentSpan;
 		let assistantStartedAt;
 		let pendingPrompt;
+		let systemPrompt;
+		let request;
 		/** 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. */
@@ -125,6 +133,10 @@ function telemetryDevExtension(options = {}, overrides) {
 			agentSpan?.end(fields);
 			agentSpan = void 0;
 		}
+		function endSessionSpan() {
+			sessionSpan?.end();
+			sessionSpan = void 0;
+		}
 		function on(event, handler) {
 			register(event, (payload, ctx) => {
 				try {
@@ -136,15 +148,29 @@ function telemetryDevExtension(options = {}, overrides) {
 		}
 		register("before_agent_start", (event) => {
 			try {
-				pendingPrompt = event.prompt?.constructor === String ? event.prompt : void 0;
+				const prompt = event.prompt?.constructor === String ? event.prompt : void 0;
+				pendingPrompt = Array.isArray(event.images) && event.images.length > 0 ? [{
+					type: "text",
+					text: prompt ?? ""
+				}, ...event.images] : prompt;
 			} catch (error) {
 				reportError(onError, error);
 			}
 		});
+		on("before_provider_request", (event, ctx) => {
+			request = event.payload;
+			systemPrompt = ctx.getSystemPrompt();
+		});
 		on("agent_start", (_event, ctx) => {
 			if (agentSpan) return;
+			sessionSpan ??= startSpan("session", {
+				type: "agent",
+				agentName,
+				attributes: spanAttributes(ctx)
+			});
 			agentSpan = startSpan("invoke_agent", {
 				type: "agent",
+				parent: sessionSpan,
 				agentName,
 				input: pendingPrompt,
 				attributes: spanAttributes(ctx)
@@ -161,7 +187,7 @@ function telemetryDevExtension(options = {}, overrides) {
 			const stopReason = stringField(lastAssistant, "stopReason");
 			const errorMessage = stringField(lastAssistant, "errorMessage");
 			lastRunResult = {
-				output: textContent(lastAssistant?.content),
+				output: lastAssistant?.content,
 				finishReason: stopReason,
 				error: stopReason === "error" ? failureError(stopReason, errorMessage) : void 0
 			};
@@ -196,10 +222,14 @@ function telemetryDevExtension(options = {}, overrides) {
 				usage: usageFields(message),
 				costUsd: numberField(asRecord(asRecord(message.usage)?.cost), "total"),
 				finishReason: stopReason,
-				output: textContent(message.content),
+				systemInstructions: systemPrompt,
+				input: request,
+				output: message.content,
 				error: stopReason === "error" ? failureError(stopReason, errorMessage) : void 0,
 				attributes: spanAttributes(ctx)
 			});
+			request = void 0;
+			systemPrompt = void 0;
 			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);
@@ -235,6 +265,7 @@ function telemetryDevExtension(options = {}, overrides) {
 			emit("turn_end", ctx, "debug", "Turn completed", { "pi.turn.index": event.turnIndex });
 		});
 		on("session_start", (event, ctx) => {
+			endSessionSpan();
 			const model = asRecord(ctx.model);
 			emit("session_start", ctx, "info", "Session started", {
 				"gen_ai.request.model": stringField(model, "id"),
@@ -262,6 +293,7 @@ function telemetryDevExtension(options = {}, overrides) {
 					endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
 					lastRunResult = void 0;
 				}
+				endSessionSpan();
 				emit("session_shutdown", ctx, "info", "Session shutdown", { "pi.session.reason": event.reason });
 				await flush();
 			} catch (error) {

package/dist/index.d.mts

@@ -1,2 +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";
+import { a as telemetryDevExtension, i as TelemetryDevExtensionOptions, n as TelemetryDevExtensionContext, o as TelemetryDevPiOptions, r as TelemetryDevExtensionHost, t as TelemetryDevExtension } from "./extension-DhhRAe5R.mjs";
 export { type TelemetryDevExtension, type TelemetryDevExtensionContext, type TelemetryDevExtensionHost, type TelemetryDevExtensionOptions, type TelemetryDevPiOptions, telemetryDevExtension };

package/dist/index.mjs

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

package/dist/register.d.mts

@@ -1,4 +1,4 @@
-import { t as TelemetryDevExtension } from "./extension-CZQ_PvAB.mjs";
+import { t as TelemetryDevExtension } from "./extension-DhhRAe5R.mjs";
 
 //#region src/register.d.ts
 /**

package/dist/register.mjs

@@ -1,4 +1,4 @@
-import { t as telemetryDevExtension } from "./extension-DLbX-piL.mjs";
+import { t as telemetryDevExtension } from "./extension-V9WCbPBU.mjs";
 //#region src/register.ts
 /**
 * Ready-to-load pi extension entry configured from `TELEMETRY_DEV_*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/pi",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pi coding-agent telemetry integration for telemetry.dev.",
   "keywords": [
     "agents",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@telemetry-dev/sdk": "^0.1.0"
+    "@telemetry-dev/sdk": "^0.1.2"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.82.1",

package/src/config.ts

@@ -6,7 +6,7 @@ import { init, shutdown, type ClientOverrides, type TelemetryOptions } from "@te
  * 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 TelemetryDevPiOptions = Omit<TelemetryOptions, "registerGlobal" | "sdkName">;
 
 export type { ClientOverrides };
 
@@ -20,6 +20,7 @@ export function ensureInit(options: TelemetryDevPiOptions = {}, overrides?: Clie
     {
       ...options,
       serviceName: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "pi",
+      sdkName: "@telemetry-dev/pi",
       // Enforce the guarantee above at runtime for untyped (plain JS) callers.
       registerGlobal: false,
     },

package/src/extension.ts

@@ -30,6 +30,8 @@ export interface TelemetryDevExtensionContext {
   model: unknown;
   /** Read-only session manager exposing the session id. */
   sessionManager: { getSessionId(): string | undefined };
+  /** Effective system prompt after all before_agent_start handlers. */
+  getSystemPrompt(): string;
 }
 
 /**
@@ -116,9 +118,12 @@ function failureError(name: string, message: string | undefined): 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`.
+ * Trace shape: one trace per pi session with a `session` root span. Each user
+ * prompt is an `invoke_agent` child, with one `chat {model}` child span per
+ * assistant message and one `execute_tool {tool}` child span per tool
+ * execution. Payloads include the prompt and its images, the provider-formatted
+ * request, and every returned content block (thinking, text, tool calls).
+ * Logs join the same session through `gen_ai.conversation.id`.
  */
 export function telemetryDevExtension(
   options: TelemetryDevExtensionOptions = {},
@@ -142,9 +147,13 @@ export function telemetryDevExtension(
       pi.on(event as never, handler as never);
     }
 
+    /** Root of the one trace per pi session; every prompt span nests under it. */
+    let sessionSpan: SpanHandle | undefined;
     let agentSpan: SpanHandle | undefined;
     let assistantStartedAt: number | undefined;
-    let pendingPrompt: string | undefined;
+    let pendingPrompt: JsonValue | undefined;
+    let systemPrompt: string | undefined;
+    let request: unknown;
     /** 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. */
@@ -187,6 +196,11 @@ export function telemetryDevExtension(
       agentSpan = undefined;
     }
 
+    function endSessionSpan(): void {
+      sessionSpan?.end();
+      sessionSpan = undefined;
+    }
+
     function on<Event>(
       event: string,
       handler: (event: Event, ctx: TelemetryDevExtensionContext) => void,
@@ -200,20 +214,36 @@ export function telemetryDevExtension(
       });
     }
 
-    register("before_agent_start", (event: { prompt?: JsonValue }) => {
+    register("before_agent_start", (event: { prompt?: JsonValue; images?: JsonValue[] }) => {
       try {
-        pendingPrompt = event.prompt?.constructor === String ? event.prompt : undefined;
+        const prompt = event.prompt?.constructor === String ? event.prompt : undefined;
+        pendingPrompt =
+          Array.isArray(event.images) && event.images.length > 0
+            ? [{ type: "text", text: prompt ?? "" }, ...event.images]
+            : prompt;
       } catch (error) {
         reportError(onError, error);
       }
     });
 
+    // All context handlers and host conversion run before this hook.
+    on("before_provider_request", (event: { payload: unknown }, ctx) => {
+      request = event.payload;
+      systemPrompt = ctx.getSystemPrompt();
+    });
+
     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;
+      sessionSpan ??= startSpan("session", {
+        type: "agent",
+        agentName,
+        attributes: spanAttributes(ctx),
+      });
       agentSpan = startSpan("invoke_agent", {
         type: "agent",
+        parent: sessionSpan,
         agentName,
         input: pendingPrompt,
         attributes: spanAttributes(ctx),
@@ -234,7 +264,7 @@ export function telemetryDevExtension(
       // failure and start another run before the prompt settles. Record the
       // outcome and close the span at agent_settled.
       lastRunResult = {
-        output: textContent(lastAssistant?.content),
+        output: lastAssistant?.content,
         finishReason: stopReason,
         error: stopReason === "error" ? failureError(stopReason, errorMessage) : undefined,
       };
@@ -273,10 +303,14 @@ export function telemetryDevExtension(
         usage: usageFields(message),
         costUsd: numberField(asRecord(asRecord(message.usage)?.cost), "total"),
         finishReason: stopReason,
-        output: textContent(message.content),
+        systemInstructions: systemPrompt,
+        input: request,
+        output: message.content,
         error: stopReason === "error" ? failureError(stopReason, errorMessage) : undefined,
         attributes: spanAttributes(ctx),
       });
+      request = undefined;
+      systemPrompt = undefined;
       for (const block of Array.isArray(message.content) ? message.content : []) {
         const record = asRecord(block);
         if (record?.type === "toolCall" && record.id?.constructor === String) {
@@ -328,6 +362,8 @@ export function telemetryDevExtension(
     });
 
     on("session_start", (event: { reason: string; previousSessionFile?: string }, ctx) => {
+      // A new, resumed, forked, or switched session is a new trace.
+      endSessionSpan();
       const model = asRecord(ctx.model);
       emit("session_start", ctx, "info", "Session started", {
         "gen_ai.request.model": stringField(model, "id"),
@@ -363,6 +399,7 @@ export function telemetryDevExtension(
             endAgentSpan(lastRunResult ?? { finishReason: "incomplete" });
             lastRunResult = undefined;
           }
+          endSessionSpan();
           emit("session_shutdown", ctx, "info", "Session shutdown", {
             "pi.session.reason": event.reason,
           });