fix(agent): export initialization failures to OTLP

Generated-By: PostHog Code
Task-Id: cd137de1-90a0-4cb9-8509-56f5f210c0e9

Author: tatoalo

packages/agent/src/acp-extensions.ts

@@ -33,6 +33,9 @@ export const POSTHOG_NOTIFICATIONS = {
   /** Error occurred during task execution */
   ERROR: "_posthog/error",
 
+  /** Agent runtime failed before its session became ready */
+  INITIALIZATION_FAILED: "_posthog/initialization_failed",
+
   /** Console/log output from the agent */
   CONSOLE: "_posthog/console",
 

packages/agent/src/otel-telemetry.test.ts

@@ -176,6 +176,30 @@ describe("OtelRunTelemetry", () => {
         body: "run error",
         attrs: { error_source: "agent_server", stop_reason: "error" },
       },
+      {
+        name: "initialization_failed",
+        entry: makeEntry("_posthog/initialization_failed", {
+          runtimeAdapter: "codex",
+          initializationPhase: "session_setup",
+          initMs: 12_345,
+          requestedModel: "gpt-5.2-codex",
+          gatewayConfigured: true,
+          errorType: "timeout",
+          timeoutMs: 30_000,
+          errorDetail: "SECRET provider response",
+        }),
+        severityText: "ERROR",
+        body: "agent initialization failed",
+        attrs: {
+          runtime_adapter: "codex",
+          initialization_phase: "session_setup",
+          init_ms: 12_345,
+          requested_model: "gpt-5.2-codex",
+          gateway_configured: true,
+          error_type: "timeout",
+          timeout_ms: 30_000,
+        },
+      },
       {
         name: "progress",
         entry: makeEntry("_posthog/progress", {
@@ -346,6 +370,20 @@ describe("OtelRunTelemetry", () => {
       );
     });
 
+    it("never exports initialization error detail", () => {
+      const mapped = mapNotificationToLogRecord(
+        makeEntry("_posthog/initialization_failed", {
+          runtimeAdapter: "pi",
+          errorDetail: "SECRET provider response",
+        }),
+      );
+
+      expect(mapped).not.toBeNull();
+      expect(JSON.stringify([mapped?.body, mapped?.attributes])).not.toContain(
+        "SECRET",
+      );
+    });
+
     it("caps body length", () => {
       const mapped = mapNotificationToLogRecord(
         makeEntry("_posthog/progress", {

packages/agent/src/otel-telemetry.ts

@@ -19,6 +19,7 @@ import {
   entryTime,
   MAX_BODY_CHARS,
   normalizeMethod,
+  numAttr,
   strAttr,
   truncate,
   usageAttributes,
@@ -200,6 +201,19 @@ export function mapNotificationToLogRecord(
       strAttr(attrs, "stop_reason", params.stopReason);
       return record(ERROR, "run error", method, attrs);
     }
+    case POSTHOG_NOTIFICATIONS.INITIALIZATION_FAILED: {
+      const attrs: Attributes = {};
+      strAttr(attrs, "runtime_adapter", params.runtimeAdapter);
+      strAttr(attrs, "initialization_phase", params.initializationPhase);
+      numAttr(attrs, "init_ms", params.initMs);
+      strAttr(attrs, "requested_model", params.requestedModel);
+      if (typeof params.gatewayConfigured === "boolean") {
+        attrs.gateway_configured = params.gatewayConfigured;
+      }
+      strAttr(attrs, "error_type", params.errorType);
+      numAttr(attrs, "timeout_ms", params.timeoutMs);
+      return record(ERROR, "agent initialization failed", method, attrs);
+    }
     // POSTHOG_NOTIFICATIONS.CONSOLE is deliberately NOT exported: those are
     // free-text agent-server diagnostics that interpolate arbitrary data
     // (prompt previews, stringified extension params), so shipping them would

packages/agent/src/server/agent-server.test.ts

@@ -448,6 +448,58 @@ describe("AgentServer HTTP Mode", () => {
     );
   };
 
+  it("exports safe telemetry when session initialization fails", async () => {
+    const append = vi.fn();
+    const shutdown = vi.fn(async () => {});
+    const testServer = createServer({
+      runtimeAdapter: "codex",
+      model: "gpt-5.2-codex",
+    }) as unknown as {
+      initializingTelemetry: {
+        append: typeof append;
+        shutdown: typeof shutdown;
+      };
+      _doInitializeSession(
+        payload: JwtPayload,
+        controller: null,
+      ): Promise<void>;
+      initializeSession(payload: JwtPayload, controller: null): Promise<void>;
+    };
+    testServer._doInitializeSession = vi.fn(async () => {
+      testServer.initializingTelemetry = { append, shutdown };
+      throw new Error("SECRET provider response");
+    });
+    const payload = {
+      task_id: "test-task-id",
+      run_id: "test-run-id",
+      team_id: 1,
+      user_id: 1,
+      distinct_id: "test-distinct-id",
+      mode: "interactive" as const,
+    };
+
+    await expect(testServer.initializeSession(payload, null)).rejects.toThrow(
+      "SECRET provider response",
+    );
+
+    expect(append).toHaveBeenCalledWith(
+      "test-run-id",
+      expect.objectContaining({
+        notification: expect.objectContaining({
+          method: POSTHOG_NOTIFICATIONS.INITIALIZATION_FAILED,
+          params: expect.objectContaining({
+            runtimeAdapter: "codex",
+            initializationPhase: "session_setup",
+            requestedModel: "gpt-5.2-codex",
+            errorType: "error",
+          }),
+        }),
+      }),
+    );
+    expect(JSON.stringify(append.mock.calls)).not.toContain("SECRET");
+    expect(shutdown).toHaveBeenCalledOnce();
+  });
+
   it("replays ACP notifications emitted before cloud session assignment", () => {
     const testServer = createServer() as unknown as {
       session: { sseController: null } | null;

packages/agent/src/server/agent-server.ts

@@ -400,6 +400,7 @@ export class AgentServer {
   // often arrives while newSession() is still awaited (this.session is still null),
   // causing a second session to be created and duplicate Slack messages to be sent.
   private initializationPromise: Promise<void> | null = null;
+  private initializingTelemetry: OtelRunTelemetry | undefined;
   private pendingEvents: Record<string, unknown>[] = [];
   /** ACP notifications emitted by newSession/resumeSession before this.session is assigned. */
   private preSessionEvents: Record<string, unknown>[] = [];
@@ -1487,9 +1488,36 @@ export class AgentServer {
       payload,
       sseController,
     );
+    const initStartedAt = Date.now();
     try {
       await this.initializationPromise;
+    } catch (error) {
+      const telemetry = this.initializingTelemetry;
+      telemetry?.append(payload.run_id, {
+        type: "notification",
+        timestamp: new Date().toISOString(),
+        notification: {
+          jsonrpc: "2.0",
+          method: POSTHOG_NOTIFICATIONS.INITIALIZATION_FAILED,
+          params: {
+            runtimeAdapter: this.getRuntimeAdapter(),
+            initializationPhase: "session_setup",
+            initMs: Date.now() - initStartedAt,
+            requestedModel: this.config.model,
+            gatewayConfigured: Boolean(
+              process.env.LLM_GATEWAY_URL || this.config.apiUrl,
+            ),
+            errorType:
+              error instanceof Error && error.name === "TimeoutError"
+                ? "timeout"
+                : "error",
+          },
+        },
+      });
+      await telemetry?.shutdown();
+      throw error;
     } finally {
+      this.initializingTelemetry = undefined;
       this.initializationPromise = null;
     }
   }
@@ -1603,6 +1631,7 @@ export class AgentServer {
       deviceInfo,
       runtimeAdapter,
     );
+    this.initializingTelemetry = telemetry;
 
     const logWriter = new SessionLogWriter({
       posthogAPI,
@@ -1821,6 +1850,7 @@ export class AgentServer {
       pendingHandoffGitState: undefined,
       sessionMeta: effectiveSessionMeta,
     };
+    this.initializingTelemetry = undefined;
     this.flushPreSessionEvents();
 
     this.logger = new Logger({

packages/agent/src/server/pi-agent-server.test.ts

@@ -33,7 +33,11 @@ describe("PiAgentServer", () => {
         sessionPayload: typeof payload,
         sseController: null,
       ): Promise<void>;
+      createRunTelemetry: ReturnType<typeof vi.fn>;
     };
+    const append = vi.fn();
+    const shutdown = vi.fn(async () => {});
+    server.createRunTelemetry = vi.fn(() => ({ append, shutdown }));
     server.createSession = vi.fn(async () => {
       throw new Error("Pi RPC startup failed");
     });
@@ -58,6 +62,20 @@ describe("PiAgentServer", () => {
         }),
       }),
     );
+    expect(append).toHaveBeenCalledWith(
+      "run-1",
+      expect.objectContaining({
+        notification: expect.objectContaining({
+          method: "_posthog/initialization_failed",
+          params: expect.objectContaining({
+            runtimeAdapter: "pi",
+            initializationPhase: "session_setup",
+            errorType: "error",
+          }),
+        }),
+      }),
+    );
+    expect(shutdown).toHaveBeenCalledOnce();
   });
 
   it.each([

packages/agent/src/server/pi-agent-server.ts

@@ -11,6 +11,8 @@ import type {
 import { serializeError } from "@posthog/shared";
 import { Hono } from "hono";
 import { z } from "zod/v4";
+import { POSTHOG_NOTIFICATIONS } from "../acp-extensions";
+import { OtelRunTelemetry } from "../otel-telemetry";
 import { createPiRpcClient, type PiRpcClient } from "../pi/rpc-client";
 import { piRpcCommandSchema, type RpcCommand } from "../pi/rpc-transport";
 import { PiRuntime } from "../pi/runtime";
@@ -132,6 +134,37 @@ export class PiAgentServer {
     this.app = this.createApp();
   }
 
+  private createRunTelemetry(
+    payload: JwtPayload,
+  ): OtelRunTelemetry | undefined {
+    const { otelLogsUrl, otelLogsToken } = this.config;
+    if (!otelLogsUrl || !otelLogsToken) return undefined;
+    try {
+      return new OtelRunTelemetry(
+        {
+          url: otelLogsUrl,
+          token: otelLogsToken,
+          tracesUrl: this.config.otelTracesUrl,
+        },
+        {
+          taskId: payload.task_id,
+          runId: payload.run_id,
+          deviceType: "cloud",
+          teamId: payload.team_id,
+          userId: payload.user_id,
+          distinctId: payload.distinct_id,
+          adapter: "pi",
+          mode: payload.mode ?? this.config.mode,
+          agentVersion: this.config.version,
+        },
+        new Logger({ debug: false, prefix: "[OtelRunTelemetry]" }),
+      );
+    } catch (error) {
+      this.logger.warn("Failed to initialize OTel run telemetry", error);
+      return undefined;
+    }
+  }
+
   async start(): Promise<void> {
     await new Promise<void>((resolve) => {
       this.server = serve(
@@ -388,6 +421,29 @@ export class PiAgentServer {
     try {
       await initializationPromise;
     } catch (error) {
+      const telemetry = this.createRunTelemetry(payload);
+      telemetry?.append(payload.run_id, {
+        type: "notification",
+        timestamp: new Date().toISOString(),
+        notification: {
+          jsonrpc: "2.0",
+          method: POSTHOG_NOTIFICATIONS.INITIALIZATION_FAILED,
+          params: {
+            runtimeAdapter: "pi",
+            initializationPhase: "session_setup",
+            initMs: Date.now() - initStartedAt,
+            requestedModel: this.config.model,
+            gatewayConfigured: Boolean(
+              process.env.LLM_GATEWAY_URL || this.config.apiUrl,
+            ),
+            errorType:
+              error instanceof Error && error.name === "TimeoutError"
+                ? "timeout"
+                : "error",
+          },
+        },
+      });
+      await telemetry?.shutdown();
       this.logger.error("Pi session initialization failed", {
         runtimeAdapter: "pi",
         initializationPhase: "session_setup",